songs2vid/README.md

# Songs2VID (hosted / SaaS checkout)

Create YouTube videos from an image and audio files. This tree is the **hosted SaaS** codebase (billing, credits, marketing landing).

For the **payment-free self-hosted OSS** product (no Stripe), use Gitea branch `main` / image [`atakanozban/songs2vid:latest`](https://hub.docker.com/r/atakanozban/songs2vid) and the docs at [docs.songs2vid.com](https://docs.songs2vid.com). Self-host install guides in `website/docs/` describe that OSS path.

## 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 (this SaaS tree)

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

Prefer the published OSS image for new self-host installs. Docker Compose in this tree still sets `S2VID_EDITION=selfhosted` when you run it locally.

## Quick start (Docker)

1. Copy env and set Google OAuth + secrets:

```bash
cp .env.example .env
```

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

```bash
docker compose up -d --build
```

Open [http://localhost:3000](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:

```bash
cp .env.example .env
```

2. Start Postgres and Redis only:

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

3. Install dependencies and push the schema:

```bash
npm install
npm run db:push
```

4. Configure Google OAuth in [Google Cloud Console](https://console.cloud.google.com/):
   - 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:

```bash
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:

```bash
npm run docs:dev
```

Open [http://localhost:3001/docs/api/overview](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