songs2vid/website/docs/video-editing.md

sidebar_position

sidebar_position
3

Video editing

Self-hosted Songs2VID includes a Layout Studio on the dashboard upload form: art-track compositions, blur backgrounds, typography, and watermarks with live preview. The same options are available on the REST API.

Classic vs art-track

Mode	Behavior
Classic (no template)	Cover letterboxed on a black frame — simple and reliable
Art-track template	Cover + title/artist arranged by a fixed template, with a blurred cover fill behind

Templates are enum-based. Free-form cover coordinates (x, y, coverX, …) are rejected so encoding stays predictable.

Templates

Template	Layout
COVER_LEFT_TEXT_RIGHT	Cover on the left; title & artist on the right
COVER_TOP_TEXT_BOTTOM	Cover on top; title & artist below
COVER_RIGHT_TEXT_LEFT	Cover on the right; title & artist on the left
CENTERED_COMPACT	Centered cover with a compact title/artist stack

Pick a template in the UI under Composition, or set metadata.layout.template in the API.

Video title, song title, and artist

YouTube metadata and on-video layout text are separate fields:

Field	UI label	Purpose	Limits
title	Video title	YouTube upload title only	Required unless fallback applies (below)
songTitle	Song title	Track title burned into art-track layouts	Max 120 characters
artist	Artist	Artist line under the song title on art-track layouts	Max 80 characters

• On the dashboard, video title is always editable. Song title and artist control the Layout Studio preview and the encoded frame.
• If video title is left empty, Songs2VID falls back to ${artist} - ${songTitle} (or whichever of those is present). Self-hosted OSS always has art-track fields and layouts unlocked.
• ID3 tags (when readable) typically prefill song title / artist and a combined video title such as Artist - Song.

Classic letterbox mode does not burn song title or artist into the frame; they still matter for the YouTube title fallback when video title is omitted.

Blur background

When an art-track template is active, the encoder builds a full-frame background from the cover:

• Blur amount (blurAmount, 0–100, default 55) — FFmpeg boxblur intensity
• Background opacity (blurOpacity, 0–100, default 100) — how strong the blurred fill is versus solid black (0 = black, 100 = full blur)

Use lower opacity for a darker, more subdued frame; higher for a soft wash of the artwork.

Fine-tuning

All values are clamped. These nudge the composition inside the template — they are not free-form canvas placement.

Control	Field	Range	Default	What it does
Padding	textPadding	16–120 px	48	Space around cover and text
Title ↔ artist	titleArtistGap	0–64 px	10	Vertical gap between title and artist
Text horizontal	textOffsetX	−120–120 px	0	Shift the text block left/right
Text vertical	textOffsetY	−120–120 px	0	Shift the text block up/down

In the dashboard, sliders update the live preview. Via API, nest them under metadata.layout (camelCase or snake_case aliases are accepted).

Per-track covers

Upload a shared cover for the batch, then optionally set a different image per item (metadata.imagePath after uploading with type=image). Useful for singles that share an album batch but need distinct artwork.

Watermarks

Modes:

Mode	Effect
none	No watermark
default	Built-in Songs2VID badge PNG (assets/watermark.png), same asset in Layout Studio preview and FFmpeg output (~42% of frame width)
text	Custom text (max 80 characters)
logo	Custom PNG (upload with type=logo, then set logoPath; same ~42% width scaling)

Position and offset

• Position: top-left · top-right · bottom-left · bottom-right · center
• Offsets (offsetX / offsetY): 0–200 px from the chosen anchor (default 20)

Typography

Font choice applies to art-track song title / artist and to text watermarks. Layout Studio loads the same .ttf files FFmpeg uses, so preview and encoded video stay aligned.

Curated fonts (bundled under assets/fonts after fetch):

• system — Arial / Helvetica in preview; FFmpeg system default when encoding
• inter · montserrat · roboto · oswald · playfair
• custom — your .ttf / .otf (max 10 MB; upload with type=font, set fontKey: "custom" and fontPath)

Set watermark.fontKey (and fontPath for custom) even when watermark mode is default or none if you only need the font for art-track text.

Refresh curated files if missing:

node scripts/fetch-watermark-fonts.mjs

Dashboard workflow

1. Add audio (and optional per-track covers)
2. Set Video title (YouTube) and, for art-tracks, Song title / Artist
3. Open Layout Studio
4. Choose classic or a template; tune blur, padding, gaps, and text offsets
5. Under Typography, pick a curated or uploaded font
6. Configure watermark mode (Songs2VID badge / text / logo), position, and offsets
7. Preview updates live; submit to enqueue encoding

API

See Endpoints for curl examples. Layout and watermark objects live under each item’s metadata:

{
  "title": "My Artist - My Track (Official Audio)",
  "songTitle": "My Track",
  "artist": "My Artist",
  "layout": {
    "template": "COVER_LEFT_TEXT_RIGHT",
    "blurAmount": 60,
    "blurOpacity": 85,
    "textPadding": 48,
    "titleArtistGap": 12,
    "textOffsetX": 0,
    "textOffsetY": 0
  },
  "watermark": {
    "mode": "default",
    "fontKey": "montserrat",
    "position": "bottom-right",
    "offsetX": 24,
    "offsetY": 24
  }
}

Here title is the YouTube title, songTitle / artist appear on the art-track frame, and fontKey styles that on-video text even though the watermark is the default Songs2VID badge.