songs2vid/website/docs/getting-started.md

sidebar_position

sidebar_position
2

Getting started

Run Songs2VID locally for development or self-hosting. The OSS edition is payment-free and always has full entitlements (no Stripe, credits, or plans).

Source: Gitea — Songs2VID/songs2vid (main).
Image: atakanozban/songs2vid:latest.

Fastest path: Docker Compose

1. Copy the template, then edit only .env:

cp .env.example .env

Set NEXTAUTH_SECRET, GOOGLE_CLIENT_ID, and GOOGLE_CLIENT_SECRET. See Environment variables.

2. Configure Google OAuth (below), then start the full stack:

docker compose up -d --build

Or pull the published image:

docker pull atakanozban/songs2vid:latest

Open http://localhost:3000, sign in with Google, and use the dashboard.

Compose is not required; any Postgres + Redis that match your .env works. See Docker Compose.

Local development (app + worker)

1. Environment file

cp .env.example .env

2. PostgreSQL and Redis

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

3. Install and migrate

npm install
npm run db:migrate

(npm run db:push is an alternative if you prefer schema push without migrations.)

4. Google OAuth

In Google Cloud Console (server-side only — end users never enter credentials):

1. Enable YouTube Data API v3
2. Create OAuth 2.0 Web credentials (OAuth 2.0 for web server apps)
3. Add an authorized redirect URI (URI validation):
   • Local: http://localhost:3000/api/auth/callback/google
   • Production: https://YOUR_DOMAIN/api/auth/callback/google
4. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env

Also set NEXTAUTH_URL to the same origin users open in the browser.

5. FFmpeg and fonts

The worker needs FFmpeg. The Docker image includes system FFmpeg; locally, ffmpeg-static is used by default. Set FFMPEG_PATH only if you want a system binary instead.

For curated watermark fonts (Inter, Montserrat, etc.), ensure files exist under assets/fonts (see assets/fonts/README.md in the repo). Custom .ttf / .otf uploads work without that step. See Video editing.

6. Start app and worker

npm run dev:all

Process	URL / role
Next.js app	http://localhost:3000
BullMQ worker	Encodes videos and uploads to YouTube

Or run them separately:

npm run dev
npm run worker

This docs site (Docusaurus) is maintained separately and published at docs.songs2vid.com.

Authentication and settings

Users sign in with Google via OAuth 2.0. The app connects their YouTube channel automatically — end users do not need Google Cloud credentials.

After sign-in you go straight to the dashboard. Settings includes:

• Account
• YouTube connection
• API key

There is no billing, pricing, or credit UI in the self-hosted OSS build.

Production

For public HTTPS, OAuth redirect URIs, and worker checklist, see Production notes.

Useful scripts

Script	Purpose
npm run dev:all	App (3000) + worker together
npm run dev	Next.js dev server only
npm run worker	Background job processor only
npm run db:migrate	Apply Prisma migrations
npm run db:push	Push Prisma schema to the database
npm run build	Production build