Align preview typography with FFmpeg output, add video/song title split, and ship OSS updates.

Separate YouTube video titles from on-video song/artist fields with Pro gating, serve curated fonts and watermark assets for 1:1 preview parity, and include billing/API/docs/deploy stack for self-hosted release.
2026-07-27 16:26:19 +02:00
parent 5c18d199fd
commit 9404efd86c
206 changed files with 37078 additions and 638 deletions
@@ -0,0 +1,420 @@
+---
+sidebar_position: 2
+---
+
+# Endpoints
+
+Set these for the examples below:
+
+```bash
+export BASE_URL="http://localhost:3000"          # local / self-hosted app
+export API_KEY="s2yt_live_your_key_here"
+```
+
+Local API docs: with `npm run dev:all` (or `npm run docs:dev`) open [http://localhost:3001/docs/api/overview](http://localhost:3001/docs/api/overview).
+
+## Discovery
+
+```bash
+curl "$BASE_URL/api/v1"
+```
+
+Returns the endpoint list and requirements (**no auth**).
+
+## Upload a file (two-step)
+
+```bash
+curl -X POST "$BASE_URL/api/v1/upload" \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "file=@cover.jpg" \
+  -F "type=image"
+```
+
+```bash
+curl -X POST "$BASE_URL/api/v1/upload" \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "file=@track1.mp3" \
+  -F "type=audio"
+```
+
+```bash
+# Optional: PNG watermark logo
+curl -X POST "$BASE_URL/api/v1/upload" \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "file=@logo.png" \
+  -F "type=logo"
+```
+
+```bash
+# Optional: custom watermark font (.ttf / .otf, max 10 MB)
+curl -X POST "$BASE_URL/api/v1/upload" \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "file=@Brand.ttf" \
+  -F "type=font"
+```
+
+### Request fields
+
+| Field | Required | Notes |
+|-------|----------|--------|
+| `file` | Yes | Multipart file |
+| `type` | Yes | `image` \| `audio` \| `logo` \| `font` |
+
+### Allowed files (self-hosted)
+
+| `type` | Formats | Max size |
+|--------|---------|----------|
+| `image` | JPEG, PNG, WebP, GIF | 500 MB |
+| `audio` | MP3, WAV, FLAC (also accepts related MIME types) | 500 MB |
+| `logo` | PNG only | 500 MB |
+| `font` | `.ttf` / `.otf` | **10 MB** |
+
+### Response
+
+```json
+{
+  "path": "/uploads/.../track.mp3",
+  "filename": "track.mp3",
+  "size": 4123456,
+  "audioTags": {
+    "title": "Song Title",
+    "artist": "Artist Name",
+    "album": "Album",
+    "genre": "Electronic",
+    "year": "2024"
+  }
+}
+```
+
+| Field | Notes |
+|-------|--------|
+| `path` | Absolute path on the server — pass this into job create |
+| `filename` | Original filename |
+| `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.
+
+## Create job from paths (recommended)
+
+Use the exact `path` strings returned by upload. Add one `items[]` entry per track.
+
+Self-hosted deployments unlock per-track covers, custom watermarks/fonts, and art-track layouts. Max batch size: **100**.
+
+```bash
+curl -X POST "$BASE_URL/api/v1/jobs" \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "imagePath": "/uploads/.../cover.jpg",
+    "items": [{
+      "audioPath": "/uploads/.../track.mp3",
+      "audioFilename": "track.mp3",
+      "metadata": {
+        "title": "My Track",
+        "artist": "My Artist",
+        "description": "",
+        "tags": "electronic",
+        "privacy": "PUBLIC",
+        "categoryId": "10",
+        "resolution": "1920x1080",
+        "notifySubscribers": true,
+        "madeForKids": false,
+        "embeddable": true,
+        "creativeCommons": false,
+        "includeWatermark": true,
+        "imagePath": "/uploads/.../track-cover.jpg",
+        "layout": {
+          "template": "COVER_LEFT_TEXT_RIGHT",
+          "blurAmount": 60,
+          "blurOpacity": 85,
+          "textPadding": 48,
+          "titleArtistGap": 12,
+          "textOffsetX": 0,
+          "textOffsetY": 0
+        },
+        "watermark": {
+          "mode": "text",
+          "text": "My Label",
+          "fontKey": "montserrat",
+          "position": "bottom-right",
+          "offsetX": 24,
+          "offsetY": 24
+        },
+        "playlistId": null
+      }
+    }]
+  }'
+```
+
+### Success response
+
+```json
+{
+  "jobId": "clxxxxxxxx",
+  "itemCount": 1,
+  "status": "PENDING",
+  "playlist": null
+}
+```
+
+`playlist` is set when you pass `createPlaylist` (see [YouTube playlists](#youtube-playlists)).
+
+### Metadata fields
+
+| Field | Type | Notes |
+|-------|------|--------|
+| `title` | string | Video title |
+| `artist` | string \| null | On-video artist line (max **80**) |
+| `description` | string | YouTube description |
+| `tags` | string | Comma-separated (quoted tags supported) |
+| `privacy` | string | `PUBLIC` \| `PRIVATE` \| `UNLISTED` |
+| `categoryId` | string | YouTube category ID (see below) |
+| `resolution` | string | One of the supported values (see below) |
+| `notifySubscribers` | boolean | YouTube upload notify flag |
+| `madeForKids` | boolean | COPPA / made for kids |
+| `embeddable` | boolean | Allow embedding |
+| `creativeCommons` | boolean | CC license vs standard YouTube |
+| `includeWatermark` | boolean | Apply watermark settings |
+| `imagePath` | string \| null | Per-track cover (overrides job `imagePath`) |
+| `playlistId` | string \| null | Existing playlist ID |
+| `layout` | object | Art-track layout (see below) |
+| `watermark` | object | Watermark settings (see below) |
+
+Snake_case aliases are accepted for layout/watermark fields (e.g. `blur_amount`, `layout_template`).
+
+### Resolutions
+
+| Value | Aspect |
+|-------|--------|
+| `1920x1080` | 16:9 |
+| `1280x720` | 16:9 |
+| `854x480` | 16:9 |
+| `720x720` | 1:1 |
+| `640x360` | 16:9 |
+| `426x240` | 16:9 |
+
+Self-hosted allows all of these.
+
+### YouTube categories
+
+Pass `categoryId` as a string ID. Common values:
+
+| ID | Name |
+|----|------|
+| `1` | Film & Animation |
+| `2` | Autos & Vehicles |
+| `10` | Music |
+| `15` | Pets & Animals |
+| `17` | Sports |
+| `19` | Travel & Events |
+| `20` | Gaming |
+| `22` | People & Blogs |
+| `23` | Comedy |
+| `24` | Entertainment |
+| `25` | News & Politics |
+| `26` | Howto & Style |
+| `27` | Education |
+| `28` | Science & Technology |
+| `29` | Nonprofits & Activism |
+
+Official reference: [YouTube Data API — VideoCategories](https://developers.google.com/youtube/v3/docs/videoCategories/list).
+
+### Watermark fields
+
+`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.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**.
+
+For a full walkthrough of composition controls, see [Video editing](../video-editing.md).
+
+### Art-track layouts
+
+`metadata.layout.template` (or flat `layout_template` / `layoutTemplate`):
+
+| Enum | Description |
+|------|-------------|
+| `COVER_LEFT_TEXT_RIGHT` | Cover left, title & artist right |
+| `COVER_TOP_TEXT_BOTTOM` | Cover top, title & artist below |
+| `COVER_RIGHT_TEXT_LEFT` | Cover right, title & artist left |
+| `CENTERED_COMPACT` | Centered cover + text stack |
+
+Optional fine-tuning (clamped; camelCase or snake_case):
+
+| Field | Range | Default | Purpose |
+|-------|-------|---------|---------|
+| `blurAmount` / `blur_amount` | 0–100 | 55 | Background `boxblur` intensity |
+| `blurOpacity` / `blur_opacity` | 0–100 | 100 | Blurred fill vs black |
+| `textPadding` / `text_padding` | 16–120 | 48 | Padding around cover and text |
+| `titleArtistGap` / `title_artist_gap` | 0–64 | 10 | Space between title and artist |
+| `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.
+
+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`).
+
+Invalid template strings return **400**:
+
+```json
+{ "error": "Invalid layout template. Refer to API documentation for valid enum values." }
+```
+
+## YouTube playlists
+
+List existing playlists, create a new one, or create one inline when starting a job. Pass `playlistId` in item metadata / batch `defaults`, or use `createPlaylist` to make a playlist and attach all videos to it.
+
+Privacy may be `public`, `unlisted`, or `private`. If playlist permission was just added, sign out and sign in again so OAuth includes `youtube.force-ssl`.
+
+YouTube playlist API reference: [Playlists: insert](https://developers.google.com/youtube/v3/docs/playlists/insert).
+
+```bash
+# List playlists
+curl "$BASE_URL/api/v1/playlists" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+```bash
+# Create a playlist
+curl -X POST "$BASE_URL/api/v1/playlists" \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"My Album","description":"From Songs2VID","privacy":"unlisted"}'
+```
+
+```json
+{
+  "playlistId": "PLxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+}
+```
+
+Or create one inline with a job / batch request:
+
+```json
+{
+  "createPlaylist": {
+    "title": "My Album",
+    "description": "Uploaded via Songs2VID",
+    "privacy": "private"
+  },
+  "defaults": { "privacy": "PUBLIC" },
+  "items": [{ "title": "Track One" }]
+}
+```
+
+## One-shot batch (small packs only)
+
+Upload one cover image and a few audio files in a single multipart request. **Not recommended for large batches** — use two-step if you see FormData parse errors.
+
+```bash
+curl -X POST "$BASE_URL/api/v1/jobs/batch" \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "image=@cover.jpg" \
+  -F "audio=@track1.mp3" \
+  -F "audio=@track2.mp3" \
+  -F 'metadata={"createPlaylist":{"title":"My Album","privacy":"unlisted"},"defaults":{"privacy":"PUBLIC"},"items":[{"title":"Track One"},{"title":"Track Two"}]}'
+```
+
+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`.
+
+**Multipart tips**
+
+- Do not set `Content-Type` manually for multipart; the client must include the boundary
+- In Postman: Body → form-data; each audio field key must be exactly `audio` (type File)
+- If a file field shows a warning, re-select the file from disk
+
+## Poll job status
+
+```bash
+curl "$BASE_URL/api/v1/jobs/JOB_ID" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+```bash
+curl "$BASE_URL/api/v1/jobs?limit=10" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+`GET /api/v1/jobs` accepts `limit` (default **20**, max **100**).
+
+### Job response
+
+```json
+{
+  "id": "clxxxxxxxx",
+  "status": "PROCESSING",
+  "createdAt": "2026-07-25T12:00:00.000Z",
+  "completedAt": null,
+  "items": [
+    {
+      "id": "clitemxxx",
+      "audioFilename": "track.mp3",
+      "title": "My Track",
+      "description": "",
+      "tags": "electronic",
+      "privacy": "PUBLIC",
+      "categoryId": "10",
+      "resolution": "1920x1080",
+      "status": "ENCODING",
+      "youtubeVideoId": null,
+      "error": null
+    }
+  ]
+}
+```
+
+### Job statuses
+
+| Status | Meaning |
+|--------|---------|
+| `PENDING` | Queued; worker has not started |
+| `PROCESSING` | At least one item is encoding or uploading |
+| `COMPLETED` | All items succeeded |
+| `FAILED` | All items failed |
+| `PARTIAL` | Mix of completed and failed items |
+
+### Item statuses
+
+| Status | Meaning |
+|--------|---------|
+| `PENDING` | Waiting in the queue |
+| `ENCODING` | FFmpeg is building the video |
+| `UPLOADING` | Uploading to YouTube |
+| `COMPLETED` | Live on YouTube (`youtubeVideoId` set) |
+| `FAILED` | Failed (`error` contains a message) |
+
+### Pipeline notes
+
+- Each item is encoded, then uploaded; the local MP4 is removed after a successful upload
+- Queue retries: **2** attempts with exponential backoff (5s base)
+- Worker concurrency: **2** items in parallel
+- On item failure, reserved allowance for that item is released
+
+YouTube upload limits (channel daily caps, etc.) are enforced by Google, not Songs2VID. See [YouTube Data API — Quota and compliance](https://developers.google.com/youtube/v3/guides/quota_and_compliance_audits).
+
+## HTTP errors
+
+| Status | When |
+|--------|------|
+| `400` | Validation error (bad file type, invalid layout, missing fields, bad JSON) |
+| `401` | Missing or invalid API key |
+| `403` | YouTube not connected, or edition/plan does not allow API features |
+| `404` | Job not found |
+| `429` | API rate limit exceeded — body includes `retryAfterSeconds`; header `Retry-After` is set |
+
+Example rate-limit body:
+
+```json
+{
+  "error": "API rate limit exceeded. Try again shortly.",
+  "retryAfterSeconds": 42
+}
+```
+
+Self-hosted rate limits are effectively unlimited for normal use. See [API overview](./overview.md).
@@ -0,0 +1,75 @@
+---
+sidebar_position: 1
+---
+
+# API overview
+
+Programmatic uploads and batch jobs for self-hosted Songs2VID. Generate your API key under **Dashboard → Settings → API access**.
+
+Keys start with `s2yt_live_` and are shown once at creation.
+
+## Authentication
+
+Send the key on every request:
+
+```http
+Authorization: Bearer s2yt_live_your_key_here
+```
+
+Requirements:
+
+- `S2VID_EDITION=selfhosted` (Compose sets this by default)
+- YouTube channel connected (sign in with Google OAuth that includes YouTube scopes)
+
+OAuth setup: [Getting started](../getting-started.md) and Google’s [OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server). YouTube scopes/API: [YouTube Data API Overview](https://developers.google.com/youtube/v3/getting-started).
+
+## Rate limits
+
+Self-hosted editions use a very high per-account ceiling (effectively unlimited for normal automation). You will rarely see `429`.
+
+If a limit is hit, the response is **429** with `retryAfterSeconds` and a `Retry-After` header. See [Endpoints — HTTP errors](./endpoints.md#http-errors).
+
+## Choosing a flow
+
+### Recommended: two-step (especially 5+ audio files)
+
+1. Upload each file with `POST /api/v1/upload`
+2. Create the job with `POST /api/v1/jobs` (JSON paths)
+
+This avoids huge multipart bodies. Self-hosted max batch size is **100** tracks per job.
+
+### One-shot batch: small packs only
+
+`POST /api/v1/jobs/batch` accepts one cover image and a few audio files in a single multipart request. Large bodies often fail with:
+
+```text
+failed to parse body as FormData
+```
+
+Prefer two-step for albums or long tracklists.
+
+### Multipart tips
+
+- Do not set `Content-Type` manually for multipart; the client must include the boundary
+- In Postman: Body → form-data; each audio field key must be exactly `audio` (type File)
+- If a file field shows a warning, re-select the file from disk
+
+## Job lifecycle
+
+1. Create job → status `PENDING`
+2. Worker picks items → `ENCODING` → `UPLOADING` → `COMPLETED` or `FAILED`
+3. Job rolls up to `COMPLETED`, `FAILED`, or `PARTIAL`
+
+Poll with `GET /api/v1/jobs/:id`. Full status tables and response shapes: [Endpoints — Poll job status](./endpoints.md#poll-job-status).
+
+## Discovery
+
+```http
+GET /api/v1
+```
+
+Returns the endpoint list and requirements (no auth).
+
+## Next
+
+See [Endpoints](./endpoints.md) for curl examples covering upload, jobs, layouts, watermarks, playlists, batch, resolutions, categories, and errors. For composition concepts (templates, blur, fine-tuning, fonts), see [Video editing](../video-editing.md).