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 by default; optional Blurred cover background fills the bars with a blurred cover
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
LOWER_LEFT_COVER_TEXT	Compact cover + title/artist; equal left/bottom textPadding inset from the lower-left corner
LOWER_RIGHT_COVER_TEXT	Compact cover + title/artist; equal right/bottom textPadding inset from the lower-right corner

Pick a composition family in the UI under Composition. Mirrored layouts (Cover beside text, Lower corner) show left/right options under the grid when selected. Or set metadata.layout.template in the API (GET /api/v1 exposes layoutTemplates and compositionFamilies).

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 — or Classic with Blurred cover background enabled (layout.blurFill) — 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. Classic without blurFill keeps solid black letterbox bars.

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. On lower corner templates this inset is equal on both axes (left = bottom, or right = bottom) so a straight diagonal runs from the frame corner to the cover corner
Title ↔ artist	titleArtistGap	0–64 px	10	Vertical gap between title and artist
Bold title	titleBold	boolean	true	Song title uses bold face (preview + FFmpeg)
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).

Lower-corner background image

When Lower corner · cover + text is selected, Layout Studio shows an optional Background image upload. That picture becomes the blurred full-frame fill; the album cover stays the sharp corner square. API equivalent: metadata.backgroundImagePath after uploading with type=image. If omitted, the cover is blurred for the fill (same as other art-track templates).

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 — bundled Arimo in both preview and FFmpeg
• 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": "LOWER_LEFT_COVER_TEXT",
    "blurAmount": 60,
    "blurOpacity": 85,
    "textPadding": 48,
    "titleArtistGap": 12,
    "titleBold": true,
    "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.