songs2vid/README.md

Songs2VID OSS

Payment-free, self-hosted software that turns cover art and audio into YouTube videos (FFmpeg encoding + BullMQ jobs). Every deployment has full entitlements — there are no 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

Quick start (Docker)

Published image: atakanozban/songs2vid:latest

1. Clone this repo (or copy docker-compose.yml + .env.example).
2. Copy .env.example to .env and set at least:
   • NEXTAUTH_SECRET
   • GOOGLE_CLIENT_ID
   • GOOGLE_CLIENT_SECRET
3. In Google Cloud Console, enable YouTube Data API v3 and add an OAuth redirect URI:
   • Local: http://localhost:3000/api/auth/callback/google
   • Production: https://YOUR_DOMAIN/api/auth/callback/google
4. Start the stack (web + worker + Postgres + Redis):

docker compose up -d

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, billing env vars, or edition flags are required. Watermarks are optional; OSS does not force a free-tier SaaS badge paywall.

Features

• Batch: one cover (or per-track covers) + many audio files → YouTube uploads
• Classic letterbox and art-track layouts (blur backgrounds, typography, fine-tuning)
• Custom watermarks (badge, text, or logo) and curated or uploaded fonts
• YouTube playlists, privacy, tags, resolution, categories
• 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 and docs/api/endpoints.md
• Live site: docs.songs2vid.com/docs/api/overview
• Machine-readable discovery: GET /api/v1 (no auth; no billing routes)

Local development

docker compose -f docker-compose.dev.yml up -d
cp .env.example .env   # then edit secrets / Google OAuth
npm install
npm run db:migrate
npm run dev:all

• App: http://localhost:3000
• dev:all runs Next.js and the BullMQ worker

Environment

See .env.example for the required and optional variables. Matching guide: 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.

Stack

• Next.js 15, TypeScript, Tailwind
• PostgreSQL and Prisma
• Redis and BullMQ
• NextAuth with Google OAuth (YouTube scopes)
• FFmpeg
• YouTube Data API v3

Links

• Docs: docs.songs2vid.com
• Docker Hub: atakanozban/songs2vid
• Source: git.atakanozban.com/Songs2VID
• Hosted SaaS (separate product): songs2vid.com