Songs2VID/songs2vid
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Enlarge watermark badge for preview/encode parity and document video title fields.

Browse Source 
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.
This commit is contained in:
Atakan Doğan Özban
2026-07-27 18:28:07 +02:00
parent 9404efd86c
commit 0c9b07bcb5
8 changed files with 76 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
website/docs/api/endpoints.md
+16 -11
View File
@@ -46,7 +46,7 @@ curl -X POST "$BASE_URL/api/v1/upload" \
```
```bash
# Optional: custom watermark font (.ttf / .otf, max 10 MB)
# Optional: custom font (.ttf / .otf, max 10 MB) for art-track / text watermark
curl -X POST "$BASE_URL/api/v1/upload" \
-H "Authorization: Bearer $API_KEY" \
-F "file=@Brand.ttf" \
@@ -93,7 +93,7 @@ curl -X POST "$BASE_URL/api/v1/upload" \
| `size` | Bytes |
| `audioTags` | Present for MP3 when tags are readable; otherwise `null`. Fields may be omitted when missing in the file |
Upload the shared cover once (`type=image`), each audio (`type=audio`), optionally a PNG logo (`type=logo`), and optionally a custom font (`type=font`) for text watermarks.
Upload the shared cover once (`type=image`), each audio (`type=audio`), optionally a PNG logo (`type=logo`), and optionally a custom font (`type=font`) for art-track typography and/or text watermarks.
## Create job from paths (recommended)
@@ -111,7 +111,8 @@ curl -X POST "$BASE_URL/api/v1/jobs" \
"audioPath": "/uploads/.../track.mp3",
"audioFilename": "track.mp3",
"metadata": {
"title": "My Track",
"title": "My Artist - My Track (Official Audio)",
"songTitle": "My Track",
"artist": "My Artist",
"description": "",
"tags": "electronic",
@@ -134,8 +135,7 @@ curl -X POST "$BASE_URL/api/v1/jobs" \
"textOffsetY": 0
},
"watermark": {
"mode": "text",
"text": "My Label",
"mode": "default",
"fontKey": "montserrat",
"position": "bottom-right",
"offsetX": 24,
@@ -164,8 +164,9 @@ curl -X POST "$BASE_URL/api/v1/jobs" \
| Field | Type | Notes |
|-------|------|--------|
| `title` | string | Video title |
| `artist` | string \| null | On-video artist line (max **80**) |
| `title` | string | **YouTube** video title. If empty, falls back to ``${artist} - ${songTitle}`` when those are set |
| `songTitle` | string \| null | On-video song / track title for art-track layouts (max **120**) |
| `artist` | string \| null | On-video artist line for art-track layouts (max **80**) |
| `description` | string | YouTube description |
| `tags` | string | Comma-separated (quoted tags supported) |
| `privacy` | string | `PUBLIC` \| `PRIVATE` \| `UNLISTED` |
@@ -224,11 +225,15 @@ Official reference: [YouTube Data API — VideoCategories](https://developers.go
`watermark.position`: `top-left` | `top-right` | `bottom-left` | `bottom-right` | `center`.
`watermark.mode`: `none` | `default` | `text` | `logo` (logo requires prior `type=logo` upload; set `logoPath`).
`watermark.mode`: `none` | `default` | `text` | `logo`
- `default` — built-in Songs2VID badge PNG (`assets/watermark.png`), scaled to ~**42%** of frame width (matches Layout Studio preview)
- `logo` — requires prior `type=logo` upload; set `logoPath` (same width scaling)
- `text` — custom string (max **80**); set `text`
`watermark.offsetX` / `offsetY`: `0`–`200` (default `20`) — pixels from the chosen anchor.
`watermark.fontKey` (text mode): `system` | `inter` | `montserrat` | `roboto` | `oswald` | `playfair` | `custom`. For `custom`, upload with `type=font` first and set `fontPath` to the returned path. Text max length: **80**.
`watermark.fontKey`: `system` | `inter` | `montserrat` | `roboto` | `oswald` | `playfair` | `custom`. Styles **art-track song title / artist** and **text watermarks** (same `.ttf` files in preview and FFmpeg). For `custom`, upload with `type=font` first and set `fontPath`. `system` maps to Arial in the dashboard preview.
For a full walkthrough of composition controls, see [Video editing](../video-editing.md).
@@ -254,7 +259,7 @@ Optional fine-tuning (clamped; camelCase or snake_case):
| `textOffsetX` / `text_offset_x` | −120–120 | 0 | Shift text block horizontally |
| `textOffsetY` / `text_offset_y` | −120–120 | 0 | Shift text block vertically |
Also set `metadata.artist` (max 80) for the on-video artist line.
Also set `metadata.songTitle` (max 120) and `metadata.artist` (max 80) for the on-video text lines. `metadata.title` remains the YouTube title (see [Video editing — Video title, song title, and artist](../video-editing.md#video-title-song-title-and-artist)).
Omit `layout.template` (or use classic letterbox) when you only want a black-padded cover. Free-form cover coordinates (`x`, `y`, `coverX`, …) and layout-level `offsetX`/`offsetY` are **rejected** (use `textOffsetX`/`textOffsetY` instead; watermark offsets stay under `watermark`).
@@ -321,7 +326,7 @@ curl -X POST "$BASE_URL/api/v1/jobs/batch" \
Optional `metadata` JSON supports `defaults` applied to every item and per-item overrides in `items`. Item order should match the order of `audio` files.
When item metadata is omitted, batch defaults include privacy `PUBLIC`, resolution `1920x1080`, and watermark off unless overridden in `defaults`.
When item metadata is omitted, batch defaults include privacy `PUBLIC`, resolution `1920x1080`, and watermark off unless overridden in `defaults`. Per-item `title` is the YouTube title (falls back from the audio filename when omitted). Pass `songTitle` and `artist` in `items[]` or `defaults` when using art-track layouts.
**Multipart tips**
website/docs/getting-started.md
+1 -1
View File
@@ -102,6 +102,6 @@ For public HTTPS, OAuth redirect URIs, and worker checklist, see [Production not
| `npm run dev` | Next.js dev server only |
| `npm run worker` | Background job processor only |
| `npm run docs:dev` | Documentation site only (port 3001) |
| `npm run docs:build` | Static docs build (for Caddy / nginx) |
| `npm run db:push` | Push Prisma schema to the database |
| `npm run build` | Production build |
| `npm run docs:build` | Build the documentation site |
website/docs/intro.md
+3 -2
View File
@@ -12,9 +12,10 @@ This documentation is for **self-hosted / open-source** deployments (`S2VID_EDIT
## What you can do
- Combine one image with multiple tracks in a batch
- Set per-video metadata (title, artist, description, tags, privacy, resolution)
- Set per-video metadata (YouTube **video title**, on-video **song title** / **artist**, description, tags, privacy, resolution)
- Art-track layouts with blur backgrounds and fine-tuning (padding, title/artist gap, text offsets)
- Custom watermarks: text or logo, positions/offsets, curated or uploaded fonts
- Typography: curated or uploaded `.ttf` / `.otf` fonts shared by Layout Studio preview and FFmpeg
- Custom watermarks: Songs2VID badge, text, or logo — positions/offsets match the live preview
- Unique cover image per track
- Add uploads to YouTube playlists
- Use the REST API for automation
website/docs/video-editing.md
+32 -19
View File
@@ -26,14 +26,21 @@ Templates are enum-based. Free-form cover coordinates (`x`, `y`, `coverX`, …)
Pick a template in the UI under **Composition**, or set `metadata.layout.template` in the API.
## Title and artist
## Video title, song title, and artist
Each track can have:
YouTube metadata and on-video layout text are separate fields:
- **Title** — used on the video and as the YouTube title (often prefilled from the filename)
- **Artist** — drawn under the title on art-track layouts (max 80 characters)
| 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 |
Artist is especially useful when ID3 tags or your API payload include it.
- 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
@@ -68,38 +75,42 @@ Modes:
| Mode | Effect |
|------|--------|
| `none` | No watermark |
| `default` | Built-in Songs2VID branding |
| `text` | Custom text with optional typography |
| `logo` | Custom PNG (upload with `type=logo`, then set `logoPath`) |
| `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 (text mode)
### 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` — FFmpeg default
- `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
```
Text length is capped at 80 characters.
## Dashboard workflow
1. Add audio (and optional per-track covers)
2. Open **Layout Studio** on a track
3. Choose classic or a template, then tune blur, padding, gaps, and text offsets
4. Configure watermark mode, font, and position
5. Preview updates live; submit to enqueue encoding
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
@@ -107,7 +118,8 @@ See [Endpoints](./api/endpoints.md) for curl examples. Layout and watermark obje
```json
{
"title": "My Track",
"title": "My Artist - My Track (Official Audio)",
"songTitle": "My Track",
"artist": "My Artist",
"layout": {
"template": "COVER_LEFT_TEXT_RIGHT",
@@ -119,8 +131,7 @@ See [Endpoints](./api/endpoints.md) for curl examples. Layout and watermark obje
"textOffsetY": 0
},
"watermark": {
"mode": "text",
"text": "My Label",
"mode": "default",
"fontKey": "montserrat",
"position": "bottom-right",
"offsetX": 24,
@@ -128,3 +139,5 @@ See [Endpoints](./api/endpoints.md) for curl examples. Layout and watermark obje
}
}
```
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.