{"id":46064352,"url":"https://github.com/noflowwater/yukebox","last_synced_at":"2026-03-08T19:09:10.428Z","repository":{"id":339940285,"uuid":"1163874195","full_name":"noFlowWater/yukebox","owner":"noFlowWater","description":"Self-hosted YouTube audio player for Bluetooth speakers","archived":false,"fork":false,"pushed_at":"2026-02-22T16:12:06.000Z","size":318,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-22T17:14:52.668Z","etag":null,"topics":["bluetooth","docker","fastify","music-player","nextjs","self-hosted","typescript","youtube"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/noFlowWater.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2026-02-22T09:38:23.000Z","updated_at":"2026-02-22T16:12:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/noFlowWater/yukebox","commit_stats":null,"previous_names":["noflowwater/yukebox"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/noFlowWater/yukebox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noFlowWater%2Fyukebox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noFlowWater%2Fyukebox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noFlowWater%2Fyukebox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noFlowWater%2Fyukebox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noFlowWater","download_url":"https://codeload.github.com/noFlowWater/yukebox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noFlowWater%2Fyukebox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29969243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T11:43:06.159Z","status":"ssl_error","status_checked_at":"2026-03-01T11:43:03.887Z","response_time":124,"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":["bluetooth","docker","fastify","music-player","nextjs","self-hosted","typescript","youtube"],"created_at":"2026-03-01T12:04:58.792Z","updated_at":"2026-03-08T19:09:10.422Z","avatar_url":"https://github.com/noFlowWater.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# YukeBox\n\n\u003e Self-hosted YouTube audio player for Bluetooth speakers\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Docker](https://img.shields.io/badge/Docker-ready-blue.svg)](docker-compose.yml)\n[![Version](https://img.shields.io/badge/version-0.2.4-green.svg)](https://github.com/noFlowWater/yukebox/releases)\n[![GHCR](https://img.shields.io/badge/GHCR-images-blue.svg)](https://github.com/noFlowWater/yukebox/pkgs/container)\n\nSearch or paste a YouTube URL — YukeBox streams audio directly to your Bluetooth speaker via the web.\nNo cloud. No subscriptions. Just your music, your speaker, your server.\n\n\u003c!-- TODO: Add screenshot or demo GIF here --\u003e\n\u003c!-- ![YukeBox Demo](docs/demo.gif) --\u003e\n\n---\n\n## Features\n\n- **Instant Playback** — Search YouTube or paste a URL, audio starts in seconds\n- **Queue Management** — Add, reorder, remove tracks with auto-advance\n- **Scheduled Playback** — Set alarms or timed playlists that auto-start\n- **Multi-Speaker** — Register and switch between Bluetooth speakers on the fly\n- **Bluetooth Management** — Scan, pair, and connect BT speakers from the web UI with auto-reconnect\n- **Favorites** — Save your favorite tracks for quick access\n- **Real-time Status** — Live playback updates via Server-Sent Events\n- **Multi-User Auth** — Role-based access control (Admin / User)\n- **Accessibility** — Dark/light theme, text scaling, reduced motion, timezone support\n- **One-Command Deploy** — Docker Compose with automated setup script\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Linux** (Ubuntu 22.04+, Fedora 34+, Debian 12+)\n- **Docker** + Docker Compose\n- **PulseAudio** or **PipeWire** (with `pipewire-pulse`)\n- **Bluetooth speaker** paired and connected\n\n### Install \u0026 Run\n\n```bash\ngit clone https://github.com/noFlowWater/yukebox.git\ncd yukebox\n./setup.sh\n```\n\n`setup.sh` handles everything: detects your audio socket, generates secrets, pulls pre-built images from GHCR, and launches the containers.\n\nOpen **http://localhost:3000** and create your first account.\n\n### Uninstall\n\n```bash\n./cleanup.sh          # interactive\n./cleanup.sh --all    # remove everything\n```\n\n---\n\n## Bluetooth Setup\n\nYukeBox can manage Bluetooth speakers directly from the **Admin Panel** — scan for devices, pair, connect, and disconnect without touching the terminal.\n\n1. Open the Admin Panel\n2. Scroll to **Bluetooth Devices**\n3. Click **Scan** to discover nearby speakers\n4. Click **Pair \u0026 Connect** on any discovered device\n\nConnected speakers are automatically registered and ready to use. Auto-reconnect handles temporary disconnections.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAlternative: CLI pairing (before running setup)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nbluetoothctl scan on\nbluetoothctl pair \u003cMAC\u003e\nbluetoothctl connect \u003cMAC\u003e\nbluetoothctl trust \u003cMAC\u003e\n\n# Verify PulseAudio sees it\npactl list sinks short\n# Should show: bluez_sink.XX_XX_XX_XX_XX_XX.*\n```\n\nOr use your desktop's Bluetooth settings (GNOME Settings, KDE System Settings, etc.)\n\u003c/details\u003e\n\n---\n\n## Configuration\n\nAll settings live in `.env` (auto-generated by `setup.sh`):\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `3000` | Web UI port |\n| `NODE_ENV` | `production` | Environment |\n| `PULSE_SOCKET` | (auto-detected) | Host PulseAudio socket path |\n| `PULSE_COOKIE` | (auto-detected) | PulseAudio cookie path |\n| `JWT_SECRET` | (auto-generated) | Auth token signing key |\n| `MPV_SOCKET` | `/tmp/mpv-socket` | mpv IPC socket (advanced) |\n| `DB_PATH` | `/app/data/yukebox.db` | SQLite database path (advanced) |\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────┐\n│  Browser (any device on network)            │\n│  http://host:3000                           │\n└──────────────┬──────────────────────────────┘\n               │\n┌──────────────▼──────────────────────────────┐\n│  Docker Compose                             │\n│  ┌────────────────┐  ┌───────────────────┐  │\n│  │  Frontend      │  │  Backend          │  │\n│  │  Next.js 15    │──│  Fastify + TS     │  │\n│  │  shadcn/ui     │  │  SQLite           │  │\n│  │  :3000         │  │  mpv + yt-dlp     │  │\n│  └────────────────┘  │  SSE streaming    │  │\n│                      │  :4000 (internal) │  │\n│                      └──────┬──┬─────────┘  │\n└─────────────────────────────┼──┼────────────┘\n                PulseAudio ───┘  └─── D-Bus (bluetoothctl)\n                       ┌─────────────────────┐\n                       │  Bluetooth Speaker  │\n                       └─────────────────────┘\n```\n\n| Layer | Stack |\n|-------|-------|\n| Backend | Fastify + TypeScript (ESM) |\n| Auth | JWT (jose) + httpOnly Cookie + bcryptjs |\n| Database | SQLite (better-sqlite3) |\n| Bluetooth | bluetoothctl via D-Bus system bus |\n| Frontend | Next.js 15 + shadcn/ui |\n| Real-time | Server-Sent Events (SSE) |\n| Deploy | Docker Compose |\n| Images | GHCR (linux/amd64, linux/arm64) |\n\nOnly port **3000** is exposed. The frontend proxies API requests internally — no CORS configuration needed.\n\n---\n\n## HTTPS (Optional)\n\nFor external access, use nginx as a reverse proxy. See [`nginx.example.conf`](nginx.example.conf) for a starter template.\n\n---\n\n## Development\n\n```bash\n# Backend (terminal 1)\ncd backend \u0026\u0026 npm install \u0026\u0026 npm run dev\n\n# Frontend (terminal 2)\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n```\n\nBackend runs on `:4000`, frontend on `:3000`. Next.js rewrites proxy `/api/*` to the backend.\n\n```bash\n# Run backend tests\ncd backend \u0026\u0026 npm test\n```\n\n---\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eNo sound from Bluetooth speaker\u003c/b\u003e\u003c/summary\u003e\n\n1. Check connection: `bluetoothctl devices Connected`\n2. Check PulseAudio: `pactl list sinks short`\n3. Restart audio: `systemctl --user restart pulseaudio`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e\"PulseAudio socket not found\" during setup\u003c/b\u003e\u003c/summary\u003e\n\n- PipeWire users: install `pipewire-pulse` and restart: `systemctl --user restart pipewire-pulse`\n- Verify socket: `ls ${XDG_RUNTIME_DIR}/pulse/native`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCan't connect from phone/other device\u003c/b\u003e\u003c/summary\u003e\n\n- Use `http://\u003chost-ip\u003e:3000` instead of `localhost`\n- Check firewall: `sudo ufw allow 3000`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eContainer can't access PulseAudio\u003c/b\u003e\u003c/summary\u003e\n\n- Verify `PULSE_SOCKET` in `.env` matches your socket path\n- Check audio group: your user must be in the `audio` group\n\u003c/details\u003e\n\n---\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoflowwater%2Fyukebox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoflowwater%2Fyukebox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoflowwater%2Fyukebox/lists"}