♪

cc-music

Self-hosted YouTube music streaming for CC:Tweaked.
yt-dlp + ffmpeg on your server. No mods beyond CC:Tweaked.

✓ Free & open source
✓ Self-hostable
✓ Public instance at cc-music.shelfwood.co
Quick Install via MPM

MPM is a package manager for CC:Tweaked. If you don't have it yet, install it first:

-- Install MPM
wget run https://shelfwood-mpm.netlify.app/install.lua

Then install and run cc-music:

mpm install cc-music
mpm run cc-music

cc-music is also featured in the mpm intro tutorial.

Manual Install

Download music.lua directly to your ComputerCraft computer:

-- In your CC terminal
wget https://raw.githubusercontent.com/j-shelfwood/cc-music/main/music.lua music
music

Connects to the public backend at cc-music.shelfwood.co/api/ by default. No setup required.

Requirements
⚡
CC:Tweaked
v1.100.0+
★
Advanced Computer
For colour UI
♪
Speaker
Direct or wired network
▪
Monitor
Optional — now-playing display

Features

⟳
Shuffle & Queue
Fisher-Yates shuffle for queue. Per-item remove, clear queue, and scroll. Loop queue or loop single song.
▶
Live Volume Control
Volume changes apply on the next audio chunk (~0.34s). No track restart required.
⚡
Wired Speaker Networks
Automatically discovers speakers across wired modem networks — not just directly attached.
▪
Monitor Display
Auto-scaling now-playing view on any connected Advanced Monitor. Shows track, artist, queue, and volume.
⊞
Search Pagination
10 search results with 5-per-page pagination and scroll wheel navigation. Paste YouTube URLs or playlist links directly.
∞
No Time Limits
PHP backend with set_time_limit(0). Stream full albums, long mixes, anything — audio is segmented and streamed in chunks.
Controls
Control Action
Click result → Play now Stop current, play immediately
Click result → Play next Insert at front of queue
Click result → + Queue Append to queue
Stop / Play button Pause and resume
Loop button Cycle: Off → Loop Queue → Loop Song
Shuf button Toggle shuffle (also shuffles existing queue)
Volume bar Click or drag to adjust — applies live
[x] next to queue item Remove that track
Paste YouTube URL Resolves single video or entire playlist

Self-Host the Backend

PHP-FPM + Caddy (Recommended)

Requirements: PHP 8.x + FPM, yt-dlp, ffmpeg, Caddy.
⚠ Do not use php -S — it's single-process and breaks on concurrent requests.

bash
apt install php8.1-fpm ffmpeg
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp \
  -o /usr/local/bin/yt-dlp && chmod +x /usr/local/bin/yt-dlp
git clone https://github.com/j-shelfwood/cc-music.git /opt/cc-music

Caddyfile:

caddyfile
your-domain.com {
  handle /api/* {
    root * /opt/cc-music/server
    php_fastcgi unix//run/php/php8.1-fpm.sock {
      read_timeout 86400s
    }
    rewrite * /index.php
  }
}
Docker

Runs php-fpm inside the container. Point Caddy or Nginx at port 3001.

bash
git clone https://github.com/j-shelfwood/cc-music.git
cd cc-music
docker compose up -d

Point your reverse proxy at 127.0.0.1:3001. Set read_timeout 86400s (Caddy) or proxy_read_timeout 86400 (Nginx).

Point music.lua at Your Server

Edit line 4 of music.lua:

lua
local api_base_url = "https://your-domain.com/api/"

Troubleshooting

Symptom Fix
"No speakers found" Connect a speaker directly or via wired modem; restart Minecraft
"Network error" Check yt-dlp and ffmpeg are in PATH; run yt-dlp -U to update
Audio stops after ~30s You're using php -S — it's single-process and drops concurrent requests. Switch to php-fpm.
Audio stops mid-track Reverse proxy timeout too low. Set read_timeout 86400s (Caddy) or proxy_read_timeout 86400 (Nginx).
Search returns empty Run yt-dlp -U on the server; YouTube occasionally breaks yt-dlp
Monitor shows nothing Must be an Advanced Monitor; plain monitors don't support colour