songs2vid/website/docs/video-editing.md

---
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](./api/endpoints.md).

## 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 editions always have this 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:

```bash
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](./api/endpoints.md) for curl examples. Layout and watermark objects live under each item’s `metadata`:

```json
{
  "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.