songs2vid/integrations/n8n/README.md

# n8n-nodes-songs2vid

Official community node for **[Songs2VID](https://git.atakanozban.com/Songs2VID)** — turn audio + cover art into YouTube-ready videos from [n8n](https://n8n.io/).

**Primary source hub:** [git.atakanozban.com/Songs2VID](https://git.atakanozban.com/Songs2VID)  
**Documentation:** [https://docs.songs2vid.com/docs/n8n](https://docs.songs2vid.com/docs/n8n) · in-repo [docs/n8n.md](../../docs/n8n.md)  
**Web UI (secondary mirror):** [songs2vid.com](https://songs2vid.com)

Self-hosted OSS: set **Base URL** to your instance. API keys work without a paid plan (YouTube must be connected).

## Install

### From n8n (recommended)

1. Open n8n → **Settings → Community nodes**
2. **Install a community node**
3. Enter:

```text
n8n-nodes-songs2vid
```

4. Confirm and restart n8n if prompted
5. Search the canvas for **Songs2VID**

Self-hosted n8n needs community packages enabled (`N8N_COMMUNITY_PACKAGES_ENABLED=true`).

### From npm (manual)

```bash
cd ~/.n8n
npm install n8n-nodes-songs2vid
```

Restart n8n.

## Credentials

1. Create an API key under [Dashboard → Settings](https://songs2vid.com/dashboard/settings) (`s2yt_live_…`)
2. Cloud requires **Developer & Automation** (€15) or **Enterprise**, plus YouTube connected
3. In n8n: create a **Songs2VID API** credential
   - **API Key:** your token
   - **Base URL:** `https://songs2vid.com` (or your self-hosted origin, no trailing slash)

Requests use `Authorization: Bearer …` only.

## Quick start

1. **File → Upload** — cover (`type=image`) → save `path`
2. **File → Upload** — audio (`type=audio`) → save `path` / `filename`
3. **Render → Create Render** — paths + privacy + resolution  
   Optional: **Additional Fields → Webhook URL** for async completion
4. Handle `job.completed` / `job.item.completed` on an n8n **Webhook** node, or poll **Get Render Status**

## Operations

| Resource | Operation | API |
|----------|-----------|-----|
| Discovery | Get API Catalog | `GET /api/v1` |
| File | Upload | `POST /api/v1/upload` |
| Render | Create Render | `POST /api/v1/render` |
| Render | Create Job (alias) | `POST /api/v1/jobs` |
| Render | Create Batch | `POST /api/v1/jobs/batch` |
| Render | Get Render Status | `GET /api/v1/jobs/:id` |
| Render | List Renders | `GET /api/v1/jobs` |
| Playlist | List / Create | `/api/v1/playlists` |
| API Key | List / Create / Delete | `/api/v1/user/api-keys` |

Layout, watermark, playlist, and multi-track options are under **Additional Fields** on Create Render.

There is no Delete Render endpoint — finished videos live on YouTube.

## Links

- **Primary source hub:** https://git.atakanozban.com/Songs2VID
- Guide: https://docs.songs2vid.com/docs/n8n
- REST endpoints: https://docs.songs2vid.com/docs/api/endpoints
- Workflow template: [`workflows/workflow-template.json`](./workflows/workflow-template.json)
- npm: https://www.npmjs.com/package/n8n-nodes-songs2vid
- Web UI: https://songs2vid.com

## Development

```bash
npm install
npm run build
```

`prepublishOnly` runs the build before `npm publish`.

## License

MIT