songs2vid/README.md

Songs2VID

Create YouTube videos from an image and audio files.

Stack

• Next.js 15 (App Router, TypeScript, Tailwind)
• PostgreSQL + Prisma
• Redis + BullMQ
• NextAuth (Google OAuth 2.0 with YouTube scopes)
• FFmpeg for video encoding
• YouTube Data API v3

Editions

Edition	How	Limits
Hosted (default)	Leave S2VID_EDITION unset	Free / Pro quotas and API gates
Self-hosted / OSS	S2VID_EDITION=selfhosted	No video quota, no API rate caps; playlists + API unlocked

Docker Compose sets S2VID_EDITION=selfhosted automatically.

Quick start (Docker)

1. Copy env and set Google OAuth + secrets:

cp .env.example .env

2. Build and run the full stack (web, worker, Postgres, Redis):

docker compose up -d --build

Open http://localhost:3000.

Add Google OAuth redirect URI: http://localhost:3000/api/auth/callback/google (or your public URL).

Local development

1. Copy environment variables:

cp .env.example .env

2. Start Postgres and Redis only:

docker compose -f docker-compose.dev.yml up -d

3. Install dependencies and push the schema:

npm install
npm run db:push

4. Configure Google OAuth in Google Cloud Console:

   • Enable YouTube Data API v3
   • Create OAuth 2.0 credentials
   • Add redirect URI: http://localhost:3000/api/auth/callback/google
   • Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env

5. Optional for unlimited local use: S2VID_EDITION=selfhosted in .env

6. Start the app, worker, and docs:

npm run dev:all

• App: http://localhost:3000
• Docs: http://localhost:3001

Or run them separately with npm run dev, npm run worker, and npm run docs:dev.

Authentication

Users sign in with Google via OAuth 2.0. The app handles YouTube channel connection automatically end users never enter API keys for YouTube.

Self-hosted edition

Set S2VID_EDITION=selfhosted (Docker Compose does this by default):

• Unlimited video allowance
• API access and playlists
• Art-track layouts with blur backgrounds and fine-tuning (padding, gaps, text offsets)
• Custom watermarks (text/logo), curated or uploaded fonts

Composition details: see website/docs/video-editing.md (or open Video editing in the docs site after npm run docs:dev).

Scripts

• npm run dev - Next.js dev server
• npm run worker - Background job processor
• npm run dev:all - App (3000) + worker + docs (3001) together
• npm run db:push - Push Prisma schema to database
• npm run build - Production build
• npm run docs:dev - Documentation site only (Docusaurus on port 3001)

Documentation

Docs live in website/ (Docusaurus). API reference:

npm run docs:dev

Open http://localhost:3001/docs/api/overview.

The app “Full API docs” link and /dashboard/api-docs redirect use local docs when NEXTAUTH_URL is localhost (or set NEXT_PUBLIC_DOCS_URL).

Source

• Gitea: https://git.atakanozban.com/Songs2VID
• Docker Hub: https://hub.docker.com/r/atakanozban/songs2vid