dub-rip

A simple web app to download YouTube audio with rich metadata including song title, artist name, album name, artwork, and release year.

Features

• Download audio from YouTube videos
• Automatically embed metadata:
  • Song title
  • Artist name
  • Album name
  • Artwork/thumbnail
  • Release year
• Clean, simple UI
• Fast downloads with best audio quality

Tech Stack

• Frontend: Svelte 5 + SvelteKit
• Backend: SvelteKit API routes
• Deployment: Railway (with Cobalt + bgutil-pot)
• Audio Processing: Cobalt API (primary) + yt-dlp (fallback)

Development

Install dependencies:

bun install

Run the development server:

bun run dev

Build for production:

bun run build

Deployment

This project is configured to deploy on Railway with a self-hosted Cobalt instance for YouTube downloads.

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                         Railway Project                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────────────┐  │
│  │   dub-rip app   │──│     Cobalt      │  │     bgutil-pot       │  │
│  │   (SvelteKit)   │  │   (port 9000)   │  │     (port 4416)      │  │
│  └─────────────────┘  └─────────────────┘  └──────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘

Services Required

1. dub-rip - This app (SvelteKit + Node.js)
2. Cobalt - YouTube download API (ghcr.io/imputnet/cobalt:11.7.1)
3. bgutil-pot - PO token sidecar for yt-dlp fallback (brainicism/bgutil-ytdlp-pot-provider:1.3.1)

Environment Variables

# dub-rip service
COBALT_API_URL=http://cobalt.railway.internal:9000
COBALT_API_KEY=your-api-key-uuid
RAILPACK_DEPLOY_APT_PACKAGES=python3
# bgutil-ytdlp-pot-provider sidecar; required for yt-dlp PO tokens
BGUTIL_POT_URL=http://bgutil-pot.railway.internal:4416

# Cobalt service
API_URL=https://your-cobalt-url.up.railway.app/
API_KEY_URL=file://keys.json
YOUTUBE_SESSION_INNERTUBE_CLIENT=WEB_EMBEDDED
# YOUTUBE_SESSION_SERVER intentionally unset — see docs/deployment-strategy.md

See deployment-strategy.md for detailed setup instructions.

PR Preview Environments

Pull requests from the same repository automatically get isolated Railway environments for testing (secrets aren't exposed to forks). Each PR environment:

• Inherits production environment variables
• Gets a unique preview URL
• Is automatically cleaned up when the PR closes

Setup Requirements:

1. Add RAILWAY_API_TOKEN secret (Railway Account Token from Account Settings → Tokens, NOT a project token) to GitHub repository settings
2. Add RAILWAY_PROJECT_ID variable (Railway project ID) to GitHub repository settings

Note on adding new env vars: PR preview environments clone variables from the production env at creation time. If you add a new env var to the dub-rip service after a PR preview env was created, the preview env won't pick it up automatically. For env vars that the PR's code path depends on:

• Add the var to production before opening the PR (preview clones from current production state), OR
• Set the var manually on the PR preview env via the Railway dashboard / railway variables --set after the env is provisioned, OR
• Re-trigger the env-creation step in the GitHub Actions workflow (close + reopen the PR).

This caught us during the bgutil-pot rollout: BGUTIL_POT_URL was set on production after the bgutil-cutover PR's preview env was created, so the preview env failed fast on the yt-dlp fallback path even though production worked.

How It Works

1. User enters a YouTube URL
2. The frontend sends a request to /api/download-stream
3. The backend attempts to download via Cobalt API:
   • Cobalt fetches the audio stream from YouTube
   • On success: streams audio back to dub-rip
   • On failure: falls back to yt-dlp + ffmpeg, which requests a PO token from the bgutil-pot sidecar before downloading
4. Metadata is extracted (title, artist, album, artwork)
5. ID3 tags are embedded into the MP3
6. The file is streamed back to the user's browser

AI-Assisted Development

This project uses Claude Code with custom configuration for streamlined development.

Commands

Command	Description
/review	Code review for security, quality, and performance issues
/security	OWASP Top 10 security audit of the codebase
/test	Generate unit tests with Vitest
/e2e	Run Playwright E2E tests with failure analysis
/compound	Capture learnings to improve future development
/interview	Interactive planning and task breakdown

Plugins

These plugins are enabled for all contributors:

Plugin	Description
frontend-design	High-quality frontend interface generation
code-review	Automated code review for quality and standards
typescript-lsp	TypeScript language server integration
code-simplifier	Code clarity and maintainability improvements

Agents

Specialized agents available via the Task tool:

Agent	Description
code-reviewer	Reviews changed files for quality and security
debugger	Investigates errors and traces issues
test-generator	Generates Vitest unit tests
e2e-runner	Runs Playwright E2E tests
security-auditor	OWASP Top 10 vulnerability scanning
codebase-search	Semantic code search across the project
media-interpreter	Analyzes images, diagrams, and screenshots
open-source-librarian	Finds and evaluates open source libraries

Skills

Skill	Description
planning-with-files	Structured planning with todo files
svelte-code-writer	Official Svelte 5 docs lookup and autofixer CLI
svelte-patterns	Project-specific component templates and patterns

Hooks (Automatic)

Hook	Trigger	Description
format-on-save	PostToolUse (Edit/Write)	Auto-formats with Biome
keyword-detector	UserPromptSubmit	Suggests relevant commands
check-comments	PostToolUse (Edit/Write)	Validates code comments
todo-enforcer	Stop	Blocks exit with incomplete todos

Testing

bun run test        # Run unit tests
bun run test:e2e    # Run E2E tests
bun run test:e2e:ui # Run E2E tests with interactive UI

License

MIT