Atakan Doğan ÖzbanandCursor
56880256e5
Fix double-scaled badge preview, bump default watermark to 42% frame width, and update OSS docs/API for title vs songTitle separation and shared typography. Co-authored-by: Cursor <cursoragent@cursor.com>
144 lines
6.0 KiB
Markdown
144 lines
6.0 KiB
Markdown
---
|
||
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.
|