{"id":36773156,"url":"https://github.com/obviyus/chanson.live","last_synced_at":"2026-04-01T19:08:01.174Z","repository":{"id":54910025,"uuid":"330421491","full_name":"obviyus/chanson.live","owner":"obviyus","description":"An ultra low-latency WebRTC radio","archived":false,"fork":false,"pushed_at":"2026-03-20T02:48:26.000Z","size":1683,"stargazers_count":27,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-20T18:43:27.810Z","etag":null,"topics":["bun","music","radio","webrtc","websocket","youtube","yt-dlp"],"latest_commit_sha":null,"homepage":"https://radio.superserio.us/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/obviyus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-01-17T15:23:44.000Z","updated_at":"2026-03-20T09:16:21.000Z","dependencies_parsed_at":"2023-02-10T10:45:55.178Z","dependency_job_id":"95fca5d5-5ab7-45b9-9aa5-bf342d4d3133","html_url":"https://github.com/obviyus/chanson.live","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/obviyus/chanson.live","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obviyus%2Fchanson.live","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obviyus%2Fchanson.live/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obviyus%2Fchanson.live/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obviyus%2Fchanson.live/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/obviyus","download_url":"https://codeload.github.com/obviyus/chanson.live/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obviyus%2Fchanson.live/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","music","radio","webrtc","websocket","youtube","yt-dlp"],"created_at":"2026-01-12T13:06:48.023Z","updated_at":"2026-04-01T19:08:01.164Z","avatar_url":"https://github.com/obviyus.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chanson.live\n\nShared low-latency radio. One stream, many listeners.\n\nEveryone hears the same thing at the same time. Submit a YouTube link, it gets queued, and when it plays, everyone listening hears it together.\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│                              chanson.live                               │\n├─────────────────────────────────────────────────────────────────────────┤\n│                                                                         │\n│   User submits YouTube URL                                              │\n│          │                                                              │\n│          ▼                                                              │\n│   ┌─────────────┐    ┌──────────────┐    ┌────────────────────┐         │\n│   │   yt-dlp    │───▶│    ffmpeg    │───▶│     mediasoup      │         │\n│   │  (download) │    │ (mp3→opus)   │    │   (WebRTC SFU)     │         │\n│   └─────────────┘    └──────────────┘    └─────────┬──────────┘         │\n│                                                    │                    │\n│                                                    ▼                    │\n│                                          ┌─────────────────┐            │\n│                                          │    Listeners    │            │\n│                                          │  (synchronized) │            │\n│                                          └─────────────────┘            │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n1. **Request**: User submits a YouTube URL via the web interface\n2. **Download**: `yt-dlp` fetches the audio (cached for future plays)\n3. **Transcode**: `ffmpeg` converts to Opus and streams via RTP\n4. **Distribute**: mediasoup (WebRTC SFU) fans out to all connected clients\n5. **Listen**: Everyone hears the same audio at the same time\n\n## Stack\n\n| Component | Purpose |\n|-----------|---------|\n| [Bun](https://bun.sh) | Runtime, HTTP server, WebSocket, SQLite |\n| [mediasoup](https://mediasoup.org) | WebRTC Selective Forwarding Unit |\n| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | YouTube audio extraction |\n| [ffmpeg](https://ffmpeg.org) | Audio transcoding (MP3 → Opus over RTP) |\n\n## Quick Start\n\n### Local Development\n\n```bash\n# Prerequisites: ffmpeg, yt-dlp\nbun install\nbun run dev\n# Open http://localhost:3000\n```\n\n### Docker (Recommended for Production)\n\n```bash\ndocker compose build\ndocker compose up\n```\n\nUses `network_mode: host` for UDP port range (required for WebRTC).\n\n## External Provider Mode\n\nYouTube may block downloads from VPS IP ranges. The **external provider** architecture solves this by running the downloader on a separate machine (e.g., your home network) while the VPS handles only streaming.\n\n```\n┌────────────────────┐         WebSocket          ┌────────────────────┐\n│    VPS (Server)    │◀──────────────────────────▶│   Home (Provider)  │\n│                    │                             │                    │\n│  • Serves clients  │    ◀─ track requests ──    │  • Runs yt-dlp     │\n│  • WebRTC stream   │    ── audio upload ──▶     │  • Sends audio     │\n│  • Queue/history   │                             │  • Avoids blocks   │\n└────────────────────┘                             └────────────────────┘\n```\n\n### VPS Configuration\n\n```bash\nPROVIDER_MODE=external\nPROVIDER_TOKEN=your_secure_token\nADMIN_TOKEN=your_secure_token\n```\n\n### Provider Configuration\n\n```bash\nBROADCASTER_URL=https://your-vps-domain\nPROVIDER_TOKEN=your_secure_token\nPROVIDER_DOWNLOAD_DIR=./provider-downloads\nAUDIO_QUALITY=5\n```\n\n### Running the Provider\n\n```bash\nbun run provider\n```\n\nThe provider connects to the VPS via WebSocket, receives download requests, fetches audio via `yt-dlp`, and uploads the file back over the same connection.\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `3000` | HTTP server port |\n| `PROVIDER_MODE` | `local` | `local` or `external` |\n| `PROVIDER_TOKEN` | n/a | Shared secret for provider auth |\n| `ADMIN_TOKEN` | n/a | Admin UI auth (defaults to `PROVIDER_TOKEN`) |\n| `MEDIASOUP_ANNOUNCED_IP` | auto | Public IP for WebRTC (required for production) |\n| `MEDIASOUP_LISTEN_IP` | `0.0.0.0` | Bind address |\n| `RTC_MIN_PORT` | `10000` | WebRTC UDP port range start |\n| `RTC_MAX_PORT` | `20000` | WebRTC UDP port range end |\n| `STUN_URLS` | Google STUN | ICE server URLs |\n| `AUDIO_QUALITY` | `5` | yt-dlp quality (1-10, lower = better) |\n| `CACHE_MAX_BYTES` | `5368709120` | Max cache size (5GB) |\n| `DOWNLOAD_DIR` | `./downloads` | Audio cache directory |\n\n## Admin\n\n- `/admin` uses `ADMIN_TOKEN` (falls back to `PROVIDER_TOKEN` if unset).\n- Blacklisted tracks cannot be queued or played in fallback rotation.\n\n## Architecture Highlights\n\n### Single Producer, Many Consumers\n\nUnlike per-user streaming, chanson.live uses a **single mediasoup producer** that all clients subscribe to. One `ffmpeg` process streams to one producer, and mediasoup efficiently fans out to hundreds of consumers.\n\n### Smart Cache Management\n\nDownloaded audio is cached locally. When cache exceeds `CACHE_MAX_BYTES`, the oldest files are pruned, but files currently in queue or playing are protected from deletion.\n\n### Fallback Playback\n\nWhen the queue is empty, the player shuffles through cached tracks automatically, keeping the radio alive.\n\n### RTP Health Monitoring\n\nThe server monitors the RTP score every 5 seconds. If `ffmpeg` stops sending audio (score drops to 0), the producer is closed automatically to prevent zombie streams.\n\n### Binary WebSocket Uploads\n\nExternal providers upload audio as raw binary chunks over WebSocket (not base64), minimizing overhead for large files.\n\n## Testing\n\n```bash\n# E2E test with a specific video\nbun run test:e2e \"https://www.youtube.com/watch?v=...\"\n\n# Test page\nopen http://localhost:3000/test\n```\n\n## Notes\n\n- `MEDIASOUP_ANNOUNCED_IP` **must** be your VPS public IP for clients behind NAT to connect\n- STUN helps NAT discovery but doesn't relay media; some restrictive networks may need TURN\n- SQLite runs in WAL mode for better concurrent read performance\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobviyus%2Fchanson.live","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobviyus%2Fchanson.live","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobviyus%2Fchanson.live/lists"}