Close OSS self-host gaps: in-repo API docs, legal notes, and packaging.
Add MIT license and docs/api, strip SaaS status/admin remnants from robots and footer, align env/compose/README with payment-free product truth. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Atakan Doğan Özban
co-authored by
Cursor
Cursor
parent
e5d1bc86a6
commit
c702686726
+10
-6
@@ -1,19 +1,23 @@
|
||||
# Songs2VID OSS is always self-hosted and has no billing configuration.
|
||||
# Songs2VID OSS is always self-hosted and payment-free.
|
||||
# Do not set Stripe, billing, credits, pricing, or S2VID_EDITION variables — they are unused.
|
||||
|
||||
# --- Required ---
|
||||
DATABASE_URL="postgresql://songs2vid:songs2vid@localhost:5433/songs2vid"
|
||||
REDIS_URL="redis://localhost:6380"
|
||||
NEXTAUTH_URL="http://localhost:3000"
|
||||
NEXTAUTH_SECRET="replace-with-a-long-random-secret"
|
||||
# Optional; falls back to NEXTAUTH_SECRET.
|
||||
# TOKEN_ENCRYPTION_KEY="replace-with-another-long-random-secret"
|
||||
|
||||
GOOGLE_CLIENT_ID="your-google-client-id.apps.googleusercontent.com"
|
||||
GOOGLE_CLIENT_SECRET="your-google-client-secret"
|
||||
|
||||
# --- Optional ---
|
||||
# TOKEN_ENCRYPTION_KEY="replace-with-another-long-random-secret" # falls back to NEXTAUTH_SECRET
|
||||
UPLOAD_DIR="./uploads"
|
||||
# FFMPEG_PATH="C:/path/to/ffmpeg.exe" # override bundled / image ffmpeg
|
||||
# S2VID_PORT=3000 # host port for docker-compose.yml (default 3000)
|
||||
# S2VID_IMAGE_TAG=latest # Docker Hub tag when using published image
|
||||
|
||||
NEXT_PUBLIC_DOCS_URL="https://docs.songs2vid.com"
|
||||
NEXT_PUBLIC_GITEA_ISSUES_URL="https://git.atakanozban.com/Songs2VID/songs2vid/issues"
|
||||
NEXT_PUBLIC_GITEA_URL="https://git.atakanozban.com/Songs2VID"
|
||||
NEXT_PUBLIC_DOCKER_HUB_URL="https://hub.docker.com/r/atakanozban/songs2vid"
|
||||
|
||||
# Optional: override the bundled ffmpeg-static binary.
|
||||
# FFMPEG_PATH="C:/path/to/ffmpeg.exe"
|
||||
|
||||
@@ -3,6 +3,8 @@ node_modules/
|
||||
.next/
|
||||
.env
|
||||
.env.local
|
||||
*.tsbuildinfo
|
||||
tsconfig.tsbuildinfo
|
||||
website/node_modules/
|
||||
website/build/
|
||||
website/.docusaurus/
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
Payment-free, self-hosted software that turns cover art and audio into YouTube videos (FFmpeg + BullMQ). Full entitlements in every deployment — no plans, credits, Stripe, or paywall.
|
||||
|
||||
**Image:** `atakanozban/songs2vid:latest`
|
||||
**License:** MIT
|
||||
|
||||
**Docs:** https://docs.songs2vid.com
|
||||
**Source:** https://git.atakanozban.com/Songs2VID/songs2vid
|
||||
@@ -21,12 +22,12 @@ Payment-free, self-hosted software that turns cover art and audio into YouTube v
|
||||
|
||||
```bash
|
||||
docker pull atakanozban/songs2vid:latest
|
||||
docker compose up -d --build
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Open http://localhost:3000 → sign in with Google → dashboard.
|
||||
|
||||
No Stripe or billing environment variables are required.
|
||||
No Stripe, billing, or edition environment variables are required. Watermarks are optional (no free-tier badge paywall).
|
||||
|
||||
## What you get
|
||||
|
||||
@@ -46,3 +47,4 @@ Next.js 15 · PostgreSQL/Prisma · Redis/BullMQ · NextAuth (Google + YouTube)
|
||||
- Getting started: https://docs.songs2vid.com/docs/getting-started
|
||||
- Environment variables: https://docs.songs2vid.com/docs/environment
|
||||
- REST API: https://docs.songs2vid.com/docs/api/overview
|
||||
- In-repo API notes: https://git.atakanozban.com/Songs2VID/songs2vid/src/branch/main/docs/api
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Atakan Doğan Özban
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -7,6 +7,8 @@ plans, credits, purchases, subscriptions, paywalls, or Stripe.
|
||||
Sign in with Google, open the dashboard, and create videos. Settings cover account,
|
||||
YouTube connection, and API keys only.
|
||||
|
||||
**License:** [MIT](./LICENSE)
|
||||
|
||||
## Quick start (Docker)
|
||||
|
||||
Published image: [`atakanozban/songs2vid:latest`](https://hub.docker.com/r/atakanozban/songs2vid)
|
||||
@@ -23,15 +25,16 @@ Published image: [`atakanozban/songs2vid:latest`](https://hub.docker.com/r/ataka
|
||||
4. Start the stack (web + worker + Postgres + Redis):
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Or pull the published image and run Compose after pointing services at
|
||||
`atakanozban/songs2vid:latest` (same env and volumes).
|
||||
Compose uses the published image by default (`atakanozban/songs2vid:latest`) and can also
|
||||
build from this repo (`docker compose up -d --build`).
|
||||
|
||||
Open http://localhost:3000 → sign in → dashboard.
|
||||
|
||||
No Stripe keys or billing env vars are required.
|
||||
No Stripe keys, billing env vars, or edition flags are required. Watermarks are optional;
|
||||
OSS does not force a free-tier SaaS badge paywall.
|
||||
|
||||
## Features
|
||||
|
||||
@@ -42,6 +45,12 @@ No Stripe keys or billing env vars are required.
|
||||
- REST API for automation (keys under **Dashboard → Settings → API key**)
|
||||
- Always-on self-hosted entitlements (no quota paywall)
|
||||
|
||||
## API documentation
|
||||
|
||||
- In-repo: [docs/api/overview.md](./docs/api/overview.md) and [docs/api/endpoints.md](./docs/api/endpoints.md)
|
||||
- Live site: [docs.songs2vid.com/docs/api/overview](https://docs.songs2vid.com/docs/api/overview)
|
||||
- Machine-readable discovery: `GET /api/v1` (no auth; no billing routes)
|
||||
|
||||
## Local development
|
||||
|
||||
```bash
|
||||
@@ -55,6 +64,17 @@ npm run dev:all
|
||||
- App: http://localhost:3000
|
||||
- `dev:all` runs Next.js and the BullMQ worker
|
||||
|
||||
## Environment
|
||||
|
||||
See [`.env.example`](./.env.example) for the required and optional variables. Matching guide:
|
||||
[docs.songs2vid.com/docs/environment](https://docs.songs2vid.com/docs/environment).
|
||||
|
||||
## Legal (self-hosted)
|
||||
|
||||
In-app **Privacy** and **Terms** pages describe self-hosted responsibility: the operator of
|
||||
each instance controls data and access; this software does not process payments. They are not
|
||||
the paid cloud terms for [songs2vid.com](https://songs2vid.com).
|
||||
|
||||
## Stack
|
||||
|
||||
- Next.js 15, TypeScript, Tailwind
|
||||
|
||||
@@ -8,6 +8,9 @@ export async function GET() {
|
||||
authentication: "Authorization: Bearer <api_key>",
|
||||
requirements: ["YouTube account connected"],
|
||||
rateLimit: "100,000 requests per minute per account",
|
||||
billing: false,
|
||||
notes:
|
||||
"OSS self-hosted: full entitlements, no Stripe/credits/paywall. In-repo docs: docs/api/",
|
||||
guidance: {
|
||||
recommended:
|
||||
"For most jobs (especially 5+ audio files): POST /api/v1/upload per file, then POST /api/v1/jobs with the returned paths",
|
||||
|
||||
+1
-1
@@ -8,7 +8,7 @@ const inter = Inter({ subsets: ["latin"] });
|
||||
const SITE_NAME = "Songs2VID";
|
||||
const DEFAULT_TITLE = "Songs2VID";
|
||||
const DEFAULT_DESCRIPTION =
|
||||
"Self-hosted audio-to-video creation and YouTube uploading.";
|
||||
"Payment-free self-hosted audio-to-video creation and YouTube uploading.";
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: DEFAULT_TITLE,
|
||||
|
||||
+65
-4
@@ -1,15 +1,76 @@
|
||||
import { LegalPageLayout } from "@/components/LegalPageLayout";
|
||||
import { LEGAL_OPERATOR } from "@/lib/legal/constants";
|
||||
import { DOCS_URL, GITEA_URL } from "@/lib/plans";
|
||||
|
||||
export default function PrivacyPage() {
|
||||
return (
|
||||
<LegalPageLayout title="Privacy Policy">
|
||||
<p>
|
||||
Songs2VID is self-hosted software. Your operator controls the deployment, database, uploads,
|
||||
logs, and Google OAuth configuration. Songs2VID does not include payment processing.
|
||||
This policy describes how a <strong>self-hosted Songs2VID</strong> instance typically
|
||||
handles data. Songs2VID OSS does not include payment processing, plans, credits, or
|
||||
Stripe. The person or organization that operates this deployment (the "operator")
|
||||
controls the server, database, uploads, logs, and Google OAuth configuration, and is
|
||||
responsible for privacy compliance for their users.
|
||||
</p>
|
||||
|
||||
<h2>1. Who is responsible</h2>
|
||||
<p>
|
||||
Google and YouTube process account and upload data according to their own policies. Contact
|
||||
the operator of this instance for data access or deletion requests.
|
||||
For this software package as published by {LEGAL_OPERATOR.legalName}, contact:{" "}
|
||||
<a href={`mailto:${LEGAL_OPERATOR.email}`}>{LEGAL_OPERATOR.email}</a>. For data on{" "}
|
||||
<em>this running instance</em>, contact the operator of the deployment you signed into —
|
||||
not necessarily the hosted SaaS at songs2vid.com, which is a separate product with its own
|
||||
policies.
|
||||
</p>
|
||||
|
||||
<h2>2. Data this software processes</h2>
|
||||
<ul>
|
||||
<li>Account profile from Google sign-in (email, name, avatar)</li>
|
||||
<li>YouTube OAuth tokens (encrypted at rest when configured) and channel metadata</li>
|
||||
<li>Uploaded cover art, audio, optional logos/fonts, and derived video files</li>
|
||||
<li>Job metadata (titles, tags, privacy, layouts, watermarks)</li>
|
||||
<li>API key hashes and rate-limit counters</li>
|
||||
</ul>
|
||||
|
||||
<h2>3. Google and YouTube</h2>
|
||||
<p>
|
||||
Google and YouTube process account and upload data under their own terms and policies.
|
||||
Operators must configure OAuth correctly and respect{" "}
|
||||
<a
|
||||
href="https://developers.google.com/terms/api-services-user-data-policy"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
>
|
||||
Google API Services User Data Policy
|
||||
</a>{" "}
|
||||
and{" "}
|
||||
<a
|
||||
href="https://developers.google.com/youtube/terms/developer-policies"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
>
|
||||
YouTube API Services Policies
|
||||
</a>
|
||||
.
|
||||
</p>
|
||||
|
||||
<h2>4. Your choices</h2>
|
||||
<p>
|
||||
Use <strong>Dashboard → Settings</strong> to export or delete your account data on this
|
||||
instance, or ask the operator. You can also revoke Google access in your{" "}
|
||||
<a
|
||||
href="https://security.google.com/settings/security/permissions"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
>
|
||||
Google Account permissions
|
||||
</a>
|
||||
.
|
||||
</p>
|
||||
|
||||
<h2>5. Documentation</h2>
|
||||
<p>
|
||||
Product docs: <a href={DOCS_URL}>{DOCS_URL}</a>. Source:{" "}
|
||||
<a href={GITEA_URL}>{GITEA_URL}</a>.
|
||||
</p>
|
||||
</LegalPageLayout>
|
||||
);
|
||||
|
||||
+7
-2
@@ -1,12 +1,17 @@
|
||||
import type { MetadataRoute } from "next";
|
||||
|
||||
function siteUrl() {
|
||||
const raw = process.env.NEXTAUTH_URL?.trim() || "http://localhost:3000";
|
||||
return raw.replace(/\/$/, "");
|
||||
}
|
||||
|
||||
export default function robots(): MetadataRoute.Robots {
|
||||
return {
|
||||
rules: {
|
||||
userAgent: "*",
|
||||
allow: "/",
|
||||
disallow: ["/admin", "/api/admin"],
|
||||
disallow: ["/api/", "/dashboard", "/jobs"],
|
||||
},
|
||||
sitemap: "https://songs2vid.com/sitemap.xml",
|
||||
sitemap: `${siteUrl()}/sitemap.xml`,
|
||||
};
|
||||
}
|
||||
|
||||
+14
-4
@@ -1,17 +1,27 @@
|
||||
import type { MetadataRoute } from "next";
|
||||
|
||||
const SITE_URL = "https://songs2vid.com";
|
||||
function siteUrl() {
|
||||
const raw = process.env.NEXTAUTH_URL?.trim() || "http://localhost:3000";
|
||||
return raw.replace(/\/$/, "");
|
||||
}
|
||||
|
||||
export default function sitemap(): MetadataRoute.Sitemap {
|
||||
const base = siteUrl();
|
||||
return [
|
||||
{
|
||||
url: SITE_URL,
|
||||
url: base,
|
||||
lastModified: new Date(),
|
||||
changeFrequency: "daily",
|
||||
changeFrequency: "weekly",
|
||||
priority: 1.0,
|
||||
},
|
||||
{
|
||||
url: `${SITE_URL}/privacy`,
|
||||
url: `${base}/privacy`,
|
||||
lastModified: new Date(),
|
||||
changeFrequency: "monthly",
|
||||
priority: 0.3,
|
||||
},
|
||||
{
|
||||
url: `${base}/terms`,
|
||||
lastModified: new Date(),
|
||||
changeFrequency: "monthly",
|
||||
priority: 0.3,
|
||||
|
||||
+40
-4
@@ -1,15 +1,51 @@
|
||||
import { LegalPageLayout } from "@/components/LegalPageLayout";
|
||||
import { LEGAL_OPERATOR } from "@/lib/legal/constants";
|
||||
import { DOCS_URL, GITEA_URL } from "@/lib/plans";
|
||||
|
||||
export default function TermsPage() {
|
||||
return (
|
||||
<LegalPageLayout title="Terms of Use">
|
||||
<p>
|
||||
Songs2VID is provided as open-source, self-hosted software without warranty. The operator of
|
||||
each instance is responsible for availability, configuration, and user access.
|
||||
Songs2VID OSS is open-source, <strong>payment-free, self-hosted software</strong>. These
|
||||
terms describe use of the software and of instances that run it. They are{" "}
|
||||
<strong>not</strong> the paid cloud Terms of Service for songs2vid.com (a separate hosted
|
||||
product with its own billing and policies).
|
||||
</p>
|
||||
|
||||
<h2>1. Software license and warranty</h2>
|
||||
<p>
|
||||
You are responsible for the media you process and upload, including compliance with
|
||||
copyright law and YouTube's terms.
|
||||
The source is provided under the license in the repository <code>LICENSE</code> file. The
|
||||
software is provided <strong>without warranty</strong> of any kind. The operator of each
|
||||
instance is responsible for availability, security, backups, configuration, and who may
|
||||
sign in.
|
||||
</p>
|
||||
|
||||
<h2>2. No paid features in this edition</h2>
|
||||
<p>
|
||||
This edition has no Stripe integration, subscriptions, credits, pricing pages, or paywalls.
|
||||
Full layout, watermark, API, and playlist features are available to signed-in users of the
|
||||
instance. Any paid offering lives only on the separate hosted SaaS product.
|
||||
</p>
|
||||
|
||||
<h2>3. Your content and YouTube</h2>
|
||||
<p>
|
||||
You are solely responsible for media you upload and for compliance with copyright law and
|
||||
YouTube's terms. Connecting Google/YouTube authorizes the instance to upload on your
|
||||
behalf within the scopes granted.
|
||||
</p>
|
||||
|
||||
<h2>4. Acceptable use</h2>
|
||||
<p>
|
||||
Do not use the software to infringe rights, abuse YouTube or Google APIs, or circumvent
|
||||
another party's security. Operators may suspend access on their instances.
|
||||
</p>
|
||||
|
||||
<h2>5. Contact</h2>
|
||||
<p>
|
||||
Package / project contact:{" "}
|
||||
<a href={`mailto:${LEGAL_OPERATOR.email}`}>{LEGAL_OPERATOR.email}</a>. Instance-specific
|
||||
support: contact your operator. Docs: <a href={DOCS_URL}>{DOCS_URL}</a>. Source:{" "}
|
||||
<a href={GITEA_URL}>{GITEA_URL}</a>.
|
||||
</p>
|
||||
</LegalPageLayout>
|
||||
);
|
||||
|
||||
@@ -58,7 +58,8 @@ export function ApiKeySettings({ initialStatus, initialRateLimit }: Props) {
|
||||
return (
|
||||
<div className="space-y-4">
|
||||
<p className="text-sm text-gray-400">
|
||||
Use the REST API to upload files and create video jobs programmatically.
|
||||
Use the REST API to upload files and create video jobs programmatically. There are no
|
||||
billing endpoints in this self-hosted edition.
|
||||
</p>
|
||||
<p className="text-xs text-gray-500">
|
||||
Rate limit: {initialRateLimit.limit} requests per {initialRateLimit.windowSeconds} seconds.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import Link from "next/link";
|
||||
import type { ReactNode } from "react";
|
||||
import { DOCS_URL, GITEA_URL } from "@/lib/plans";
|
||||
|
||||
function LegalLink({
|
||||
href,
|
||||
@@ -33,7 +34,7 @@ export function LegalFooter() {
|
||||
return (
|
||||
<footer className="mt-auto w-full border-t border-gray-800 bg-black/40 py-8 text-xs text-gray-500">
|
||||
<div className="mx-auto flex max-w-4xl flex-wrap items-center justify-center gap-x-4 gap-y-2 px-6 md:justify-start">
|
||||
<span>© {year} Songs2VID. All rights reserved.</span>
|
||||
<span>© {year} Songs2VID. MIT licensed.</span>
|
||||
<span aria-hidden="true" className="hidden sm:inline">
|
||||
|
|
||||
</span>
|
||||
@@ -50,16 +51,18 @@ export function LegalFooter() {
|
||||
<span aria-hidden="true" className="hidden sm:inline">
|
||||
|
|
||||
</span>
|
||||
<LegalLink href="/terms">Terms of Service</LegalLink>
|
||||
<LegalLink href="/terms">Terms of Use</LegalLink>
|
||||
<span aria-hidden="true" className="hidden sm:inline">
|
||||
|
|
||||
</span>
|
||||
<LegalLink href="https://docs.songs2vid.com" external>Documentation</LegalLink>
|
||||
<LegalLink href={DOCS_URL} external>
|
||||
Documentation
|
||||
</LegalLink>
|
||||
<span aria-hidden="true" className="hidden sm:inline">
|
||||
|
|
||||
</span>
|
||||
<LegalLink href="https://status.atakanozban.com/status/2" external>
|
||||
Service Status
|
||||
<LegalLink href={GITEA_URL} external>
|
||||
Source
|
||||
</LegalLink>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
@@ -2,6 +2,7 @@ import Link from "next/link";
|
||||
import type { ReactNode } from "react";
|
||||
import { Logo } from "@/components/Logo";
|
||||
import { LEGAL_LAST_UPDATED } from "@/lib/legal/constants";
|
||||
import { DOCS_URL } from "@/lib/plans";
|
||||
|
||||
type Props = {
|
||||
title: string;
|
||||
@@ -45,7 +46,7 @@ export function LegalPageLayout({ title, description, children }: Props) {
|
||||
Terms
|
||||
</Link>
|
||||
<a
|
||||
href="https://docs.songs2vid.com"
|
||||
href={DOCS_URL}
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="hover:text-gray-300"
|
||||
|
||||
@@ -27,6 +27,7 @@ services:
|
||||
retries: 10
|
||||
|
||||
web:
|
||||
image: atakanozban/songs2vid:${S2VID_IMAGE_TAG:-latest}
|
||||
build: .
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
@@ -49,6 +50,7 @@ services:
|
||||
sh -c "npx prisma db push && node server.js"
|
||||
|
||||
worker:
|
||||
image: atakanozban/songs2vid:${S2VID_IMAGE_TAG:-latest}
|
||||
build: .
|
||||
restart: unless-stopped
|
||||
env_file:
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
# Songs2VID OSS documentation
|
||||
|
||||
This folder ships with the OSS repo so API reference stays available without the docs site.
|
||||
|
||||
| Doc | Contents |
|
||||
|-----|----------|
|
||||
| [API overview](./api/overview.md) | Auth, rate limits, recommended flows |
|
||||
| [API endpoints](./api/endpoints.md) | curl examples for upload, jobs, playlists, errors |
|
||||
|
||||
Live docs (same product truth for self-host): [docs.songs2vid.com](https://docs.songs2vid.com)
|
||||
|
||||
Setup and env: see the root [README](../README.md) and [`.env.example`](../.env.example).
|
||||
@@ -0,0 +1,305 @@
|
||||
# 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"
|
||||
```
|
||||
|
||||
Live HTML docs: [docs.songs2vid.com/docs/api/endpoints](https://docs.songs2vid.com/docs/api/endpoints).
|
||||
|
||||
## Discovery
|
||||
|
||||
```bash
|
||||
curl "$BASE_URL/api/v1"
|
||||
```
|
||||
|
||||
Returns the endpoint list and requirements (**no auth**). No billing routes are listed or implemented.
|
||||
|
||||
## 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 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
|
||||
|
||||
| `type` | Formats | Max size |
|
||||
|--------|---------|----------|
|
||||
| `image` | JPEG, PNG, WebP, GIF | 500 MB |
|
||||
| `audio` | MP3, WAV, FLAC | 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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`audioTags` is present for MP3 when tags are readable; otherwise `null`.
|
||||
|
||||
## Create job from paths (recommended)
|
||||
|
||||
Self-hosted unlocks per-track covers, custom watermarks/fonts, and art-track layouts. Max batch size: **100**. Watermarks are optional — nothing forces the default Songs2VID badge.
|
||||
|
||||
```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 Artist - My Track (Official Audio)",
|
||||
"songTitle": "My Track",
|
||||
"artist": "My Artist",
|
||||
"description": "",
|
||||
"tags": "electronic",
|
||||
"privacy": "PUBLIC",
|
||||
"categoryId": "10",
|
||||
"resolution": "1920x1080",
|
||||
"notifySubscribers": true,
|
||||
"madeForKids": false,
|
||||
"embeddable": true,
|
||||
"creativeCommons": false,
|
||||
"includeWatermark": true,
|
||||
"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
|
||||
},
|
||||
"playlistId": null
|
||||
}
|
||||
}]
|
||||
}'
|
||||
```
|
||||
|
||||
### Success response
|
||||
|
||||
```json
|
||||
{
|
||||
"jobId": "clxxxxxxxx",
|
||||
"itemCount": 1,
|
||||
"status": "PENDING",
|
||||
"playlist": null
|
||||
}
|
||||
```
|
||||
|
||||
### Metadata fields
|
||||
|
||||
| Field | Type | Notes |
|
||||
|-------|------|--------|
|
||||
| `title` | string | YouTube video title |
|
||||
| `songTitle` | string \| null | On-video song title for art-track (max **120**) |
|
||||
| `artist` | string \| null | On-video artist line (max **80**) |
|
||||
| `description` | string | YouTube description |
|
||||
| `tags` | string | Comma-separated |
|
||||
| `privacy` | string | `PUBLIC` \| `PRIVATE` \| `UNLISTED` |
|
||||
| `categoryId` | string | YouTube category ID |
|
||||
| `resolution` | string | See resolutions below |
|
||||
| `notifySubscribers` | boolean | YouTube notify flag |
|
||||
| `madeForKids` | boolean | Made for kids |
|
||||
| `embeddable` | boolean | Allow embedding |
|
||||
| `creativeCommons` | boolean | CC vs standard YouTube license |
|
||||
| `includeWatermark` | boolean | Apply watermark settings |
|
||||
| `imagePath` | string \| null | Per-track cover |
|
||||
| `playlistId` | string \| null | Existing playlist ID |
|
||||
| `layout` | object | Art-track layout |
|
||||
| `watermark` | object | Watermark settings |
|
||||
|
||||
Snake_case aliases are accepted for layout/watermark fields.
|
||||
|
||||
### Resolutions
|
||||
|
||||
| Value | Aspect |
|
||||
|-------|--------|
|
||||
| `1920x1080` | 16:9 |
|
||||
| `1280x720` | 16:9 |
|
||||
| `854x480` | 16:9 |
|
||||
| `720x720` | 1:1 |
|
||||
| `640x360` | 16:9 |
|
||||
| `426x240` | 16:9 |
|
||||
|
||||
### YouTube categories
|
||||
|
||||
| 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 |
|
||||
|
||||
### Watermark fields
|
||||
|
||||
`watermark.mode`: `none` | `default` | `text` | `logo`
|
||||
|
||||
- `none` — no overlay
|
||||
- `default` — built-in Songs2VID badge PNG (`assets/watermark.png`)
|
||||
- `logo` — requires prior `type=logo` upload; set `logoPath`
|
||||
- `text` — custom string (max **80**); set `text`
|
||||
|
||||
`watermark.position`: `top-left` | `top-right` | `bottom-left` | `bottom-right` | `center`
|
||||
|
||||
`watermark.offsetX` / `offsetY`: `0`–`200` (default `20`)
|
||||
|
||||
`watermark.fontKey`: `system` | `inter` | `montserrat` | `roboto` | `oswald` | `playfair` | `custom` (styles art-track text and text watermarks)
|
||||
|
||||
### Art-track layouts
|
||||
|
||||
`metadata.layout.template`:
|
||||
|
||||
| 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 |
|
||||
|
||||
Fine-tuning (defaults in parentheses): `blurAmount` (55), `blurOpacity` (100), `textPadding` (48), `titleArtistGap` (10), `textOffsetX` (0), `textOffsetY` (0).
|
||||
|
||||
## YouTube playlists
|
||||
|
||||
```bash
|
||||
curl "$BASE_URL/api/v1/playlists" \
|
||||
-H "Authorization: Bearer $API_KEY"
|
||||
```
|
||||
|
||||
```bash
|
||||
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"}'
|
||||
```
|
||||
|
||||
Or pass `createPlaylist` on a job / batch body to create a playlist and attach all videos.
|
||||
|
||||
## One-shot batch (small packs only)
|
||||
|
||||
```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={"defaults":{"privacy":"PUBLIC"},"items":[{"title":"Track One"},{"title":"Track Two"}]}'
|
||||
```
|
||||
|
||||
Prefer two-step upload + jobs for larger packs.
|
||||
|
||||
## 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 statuses
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `PENDING` | Queued |
|
||||
| `PROCESSING` | Encoding or uploading |
|
||||
| `COMPLETED` | All items succeeded |
|
||||
| `FAILED` | All items failed |
|
||||
| `PARTIAL` | Mix of completed and failed |
|
||||
|
||||
### Item statuses
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `PENDING` | Waiting |
|
||||
| `ENCODING` | FFmpeg building video |
|
||||
| `UPLOADING` | Uploading to YouTube |
|
||||
| `COMPLETED` | Live (`youtubeVideoId` set) |
|
||||
| `FAILED` | Failed (`error` message) |
|
||||
|
||||
YouTube channel daily upload caps are enforced by Google, not Songs2VID.
|
||||
|
||||
## HTTP errors
|
||||
|
||||
| Status | When |
|
||||
|--------|------|
|
||||
| `400` | Validation error |
|
||||
| `401` | Missing or invalid API key |
|
||||
| `403` | YouTube not connected, or request not allowed |
|
||||
| `404` | Job not found |
|
||||
| `429` | API rate limit exceeded |
|
||||
|
||||
There is no `402` payment / credits status in OSS.
|
||||
@@ -0,0 +1,66 @@
|
||||
# API overview
|
||||
|
||||
Programmatic uploads and batch jobs for self-hosted Songs2VID. Generate your API key under **Dashboard → Settings → API key**.
|
||||
|
||||
Keys start with `s2yt_live_` and are shown once at creation. The OSS / Docker image always allows API use — there is no plan, credit, or paywall gate.
|
||||
|
||||
There are **no billing endpoints** in this edition.
|
||||
|
||||
## Authentication
|
||||
|
||||
Send the key on every request:
|
||||
|
||||
```http
|
||||
Authorization: Bearer s2yt_live_your_key_here
|
||||
```
|
||||
|
||||
Requirements:
|
||||
|
||||
- YouTube channel connected (sign in with Google OAuth that includes YouTube scopes)
|
||||
|
||||
OAuth setup: root [README](../../README.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 OSS uses 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. 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.
|
||||
|
||||
## 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`.
|
||||
|
||||
## Discovery
|
||||
|
||||
```http
|
||||
GET /api/v1
|
||||
```
|
||||
|
||||
Returns the endpoint list and requirements (no auth). Useful as a machine-readable catalog of what this instance exposes.
|
||||
|
||||
## Next
|
||||
|
||||
See [Endpoints](./endpoints.md) for curl examples. Hosted HTML docs: [docs.songs2vid.com/docs/api/overview](https://docs.songs2vid.com/docs/api/overview).
|
||||
@@ -1,7 +1,7 @@
|
||||
import { SUPPORT_EMAIL } from "@/lib/plans";
|
||||
import { BRAND_DOMAIN, BRAND_NAME } from "@/lib/branding";
|
||||
|
||||
export const LEGAL_LAST_UPDATED = "July 30, 2026";
|
||||
export const LEGAL_LAST_UPDATED = "August 3, 2026";
|
||||
|
||||
export const LEGAL_OPERATOR = {
|
||||
name: BRAND_NAME,
|
||||
|
||||
@@ -39,10 +39,11 @@ export function isYouTubeUploadLimitError(message: string) {
|
||||
|
||||
export const YOUTUBE_UPLOAD_LIMIT_USER_MESSAGE =
|
||||
"YouTube upload limit reached: this Google/YouTube account has exceeded the number of videos " +
|
||||
"it may upload right now. This is YouTube's own daily limit, not your Songs2VID plan quota. " +
|
||||
"it may upload right now. This is YouTube's own daily limit, not a Songs2VID usage cap " +
|
||||
"(self-hosted OSS does not enforce a video quota paywall). " +
|
||||
"Try again later (often after 24 hours) or use a different YouTube channel.";
|
||||
|
||||
/** User-facing message for the dashboard (distinct from Songs2VID plan quota). */
|
||||
/** User-facing message for the dashboard (distinct from YouTube's own caps). */
|
||||
export function formatYouTubeErrorForUser(err: unknown): string {
|
||||
const raw = extractYouTubeErrorMessage(err);
|
||||
if (isYouTubeUploadLimitError(raw)) return YOUTUBE_UPLOAD_LIMIT_USER_MESSAGE;
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
"description": "Payment-free self-hosted audio-to-video app with YouTube upload",
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"license": "MIT",
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"dev:all": "concurrently -n web,worker -c blue,green \"npm run dev\" \"npm run worker\"",
|
||||
|
||||
Reference in New Issue
Block a user