YouTube Music Cast
YouTube music → your Chromecast. Simple, free, works.
Download audio from YouTube or YouTube Music and stream it through Home Assistant to any Cast-enabled device. No subscriptions, no cloud services, just your local network.
Features
- ✅ Free forever — No subscriptions, no premium accounts needed
- ✅ High quality — 320K MP3, crystal clear audio
- ✅ Video mode — Create MP4 videos with album art and text overlays
- ✅ Radio mode — Auto-discover and play related songs
- ✅ Local storage — Your music stays on your machine, no cloud
- ✅ Multi-room — Cast to any Chromecast device in your home
- ✅ Batch download — Download entire playlists, stream anytime
- ✅ Simple CLI — Fast commands, no browser required
- ✅ Works offline — Once downloaded, music is yours to keep
Use Cases
Daily Music
Download your favorite tracks in the morning, cast them throughout the day. No waiting, no buffering.
Party Mode
Download a playlist before guests arrive, then queue up songs without fumbling with phones or apps.
Background Audio
Play ambient music or podcasts while you work without worrying about ads or interruptions.
Multi-Room Sync
Stream the same track to multiple Chromecasts simultaneously (bedroom + living room + kitchen).
Why This Over Premium Services?
| Feature | YouTube Music Cast | Spotify Premium | YouTube Premium |
|---|
| Cost | Free forever | $10.99/month | $13.99/month |
| Quality | 320K MP3 | Up to 320K | Up to 1080p video |
| Offline | Yes, forever | Download limit | Download limit |
| Ads | None | None | None |
| Platforms | Any Chromecast | Spotify Connect devices | YouTube apps |
| Privacy | Local only | Cloud-based | Cloud-based |
Quick Start
cast-setup
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ
cast-server start
cast-play never-gonna-give-you-up.mp3
That's it. Your music is playing through your Chromecast.
What This Does
Three simple steps, one command each:
1. Download
yt-dlp grabs audio from YouTube or YouTube Music, extracts it as MP3 (320K quality).
2. Host
A lightweight Python HTTP server makes your downloaded files accessible over your local network. No setup required — just Python 3.
3. Cast
Home Assistant's media_player.play_media service sends the HTTP URL to your Chromecast, which streams the audio.
Why a Web Server?
Home Assistant's play_media service requires a URL, not a file path. The web server bridges that gap.
media_content_id: "http://192.168.1.81:8735/song.mp3"
media_content_id: "/tmp/youtube-music/song.mp3"
Architecture:
YouTube URL → yt-dlp → MP3 file → Python HTTP server → Home Assistant API → Chromecast
Installation
What You Need
- Home Assistant with Google Cast integration
- Chromecast or Cast-enabled device (Nest speakers, Google Home, TV)
- System tools:
yt-dlp, Python 3, curl, jq
Step 1: Install Scripts
cd youtube-music-cast
chmod +x scripts/*
./install.sh --global
./install.sh
Step 2: Run Setup Wizard
cast-setup
The wizard will ask for:
- Home Assistant URL — e.g.,
http://homeassistant.local:8123
- Long-Lived Access Token — Generate in HA → Profile → Long-Lived Access Tokens
- Server IP — The machine running these scripts
- Default media player — e.g.,
media_player.bedroom_display
Step 3: Test Your Setup
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ
cast-server start
cast-play song.mp3
If music plays, you're ready!
Commands
| Command | Description | Example |
|---|
cast-setup | Run configuration wizard | cast-setup |
cast-download <URL> [options] | Download from YouTube/YouTube Music | cast-download https://youtube.com/watch?v=... --video |
cast-radio <URL> [options] | Start radio mode with related songs | cast-radio https://youtube.com/watch?v=... --count 10 |
| `cast-server [start | stop | status]` |
cast-play <file> [device] | Cast music or video file to device | cast-play song.mp4 |
cast-stop [device] | Stop playback | cast-stop |
cast-status [device] | Show player status | cast-status |
cast-devices | List all available media players | cast-devices |
cast-list | List downloaded files | cast-list |
cast-help | Show help | cast-help |
Usage Guide
Your First Song
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ
mv "/tmp/youtube-music/Rick Astley - Never Gonna Give You Up.mp3" \
"/tmp/youtube-music/never-gonna-give-you-up.mp3"
cast-server start
cast-play never-gonna-give-you-up.mp3
Cast to Different Rooms
cast-play song.mp3 media_player.living_room
cast-play song.mp3 media_player.kitchen_speaker
cast-play song.mp3 media_player.bedroom_display
cast-play song.mp3 media_player.living_room & \
cast-play song.mp3 media_player.bedroom_display
Check What's Playing
cast-status
cast-status media_player.bedroom_display
Output:
📺 media_player.bedroom_display
State: playing
Friendly Name: Bedroom display
Volume: 22%
Now Playing:
Title: Never Gonna Give You Up
Artist: Rick Astley
Duration: 3:32
App: Default Media Receiver
Stop Playback
cast-stop
cast-stop media_player.living_room
See What You've Downloaded
cast-list
Output:
🎵 Downloaded Music
boneheads-bank-holiday.mp3 9.3M
never-gonna-give-you-up.mp3 8.2M
song-for-nary.mp3 7.8M
Total: 3 files
See Available Devices
cast-devices
Output:
📺 Available Media Players
media_player.bedroom_display
Name: Bedroom display
State: idle
Supported: play_media, volume_set, volume_mute, ...
media_player.living_room
Name: Living room TV
State: off
Supported: play_media, volume_set, ...
Default device: media_player.bedroom_display
New Features: Radio Mode & Video Mode
📻 Radio Mode
Radio mode automatically discovers and downloads related songs based on YouTube recommendations. After downloading a seed song, it searches for similar tracks and adds them to your queue.
Start radio mode:
cast-radio https://youtube.com/watch?v=dQw4w9WgXcQ
cast-radio https://youtube.com/watch?v=dQw4w9WgXcQ --count 10
cast-radio https://youtube.com/watch?v=dQw4w9WgXcQ --video --count 5
Or use cast-download with --radio flag:
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ --radio
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ --radio --radio-count 5
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ --radio --video
How it works:
- Downloads the seed song you specify
- Extracts artist/title from metadata
- Searches YouTube for similar videos
- Downloads related songs (prefixed with
radio_)
- Related songs are ready to cast in sequence
Play your radio queue:
cast-server start
cast-play $(ls -t /tmp/youtube-music/*.mp3 | head -n 1 | xargs basename)
cast-play radio_some-song.mp3
cast-play radio_another-song.mp3
Tips:
- Related songs are prefixed with
radio_ for easy identification
- The radio mode searches based on the artist name from the seed song
- Use
--count to control how many related songs to download
- Combine with
--video flag for visual radio mode
🎬 Video Mode with Visuals
Video mode creates MP4 videos instead of plain MP3 files. Each video includes:
- The original audio track
- Album art thumbnail from YouTube
- Text overlay showing song title and artist
- Smooth, high-quality encoding
Download a video:
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ --video
cast-server start
cast-play "Never Gonna Give You Up.mp4"
Radio mode with videos:
cast-radio https://youtube.com/watch?v=dQw4w9WgXcQ --video --count 5
cast-play "Never Gonna Give You Up.mp4"
cast-play "radio_Together Forever.mp4"
How it works:
- Downloads the audio track (320K MP3 quality)
- Downloads the album art thumbnail from YouTube
- Uses ffmpeg to create an MP4 video with:
- Looping album art background
- Audio track encoded as AAC
- Text overlay (song title and artist name) at bottom
- Cast the MP4 to your Chromecast (TVs with video support)
Video output:
- Codec: H.264 (libx264)
- Audio: AAC (192K)
- Resolution: Same as thumbnail (usually 480p or 720p)
- Text: White text with semi-transparent black box
- Compatible with all Chromecast devices with video support
Notes:
- Videos take more space than MP3s (~2-3x larger)
- Requires ffmpeg to be installed on your system
- Text overlay uses DejaVu Sans Bold font (included on most Linux systems)
- Chromecast audio devices (like Google Home Mini) will play audio only
- Chromecast with displays (TVs, Google Nest Hub) will show the full video
Requirements for video mode:
Mixed MP3 and MP4
cast-play automatically detects the file type:
.mp3, .wav, .ogg, .m4a, .flac → music.mp4, .mkv, .webm, .mov → video
You can mix both formats in the same directory:
cast-download https://youtube.com/watch?v=VIDEO_ID_1
cast-download https://youtube.com/watch?v=VIDEO_ID_2 --video
cast-play song.mp3
cast-play video.mp4
Configuration
Config file: ~/.youtube-music-cast/config.sh
HA_URL="http://homeassistant.local:8123"
HA_TOKEN="your-long-lived-access-token-here"
SERVER_IP="192.168.1.81"
SERVER_PORT="8735"
DEFAULT_DEVICE="media_player.bedroom_display"
DOWNLOAD_DIR="/tmp/youtube-music"
CAST_DIR="$HOME/.youtube-music-cast"
Edit the file directly or re-run cast-setup to update.
File Naming Best Practices
Keep URLs clean. Simple filenames save you from headaches later.
The Problem
❌ Bad filenames:
http://192.168.1.81:8735/Bonehead's%20Bank%20Holiday%20(Remastered).mp3
This URL is messy, hard to type, and prone to encoding errors.
The Solution
✅ Good filenames:
http://192.168.1.81:8735/boneheads-bank-holiday.mp3
Clean, easy to type, no issues.
Practical Tips
mv "Oasis - Bonehead's Bank Holiday (Remastered 1995).mp3" \
"oasis-boneheads-bank-holiday.mp3"
mv "My Awesome Song.mp3" "my-awesome-song.mp3"
mv "song@remix#.mp3" "song-remix.mp3"
Rule of thumb:
- Lowercase
- Hyphens instead of spaces
- No special characters (@, #, ?, etc.)
- Keep it short
Troubleshooting
Chromecast Not in Home Assistant
Problem: cast-devices shows no Chromecast devices.
Solution: Add Google Cast integration
- Home Assistant → Settings → Devices & Services
- Click "+ Add Integration"
- Search "Google Cast" → Select it
- Follow the discovery wizard
If discovery fails:
- Ensure Chromecast and Home Assistant are on the same network
- Try adding manually with Chromecast IP address
Server Won't Start
Problem: cast-server start fails or says "port in use".
Solution:
netstat -tlnp | grep 8735
ss -tlnp | grep 8735
cast-server stop
cd /tmp/youtube-music
python3 -m http.server 8735
If port is in use by another process:
Edit ~/.youtube-music-cast/config.sh:
SERVER_PORT="8736"
"File Not Found" Error
Problem: cast-play song.mp3 says file not found.
Solution:
cast-list
cast-play "Exact-Filename.mp3"
cast-server status
Common mistakes:
- Wrong case:
Song.mp3 vs song.mp3
- Wrong extension:
song.MP3 vs song.mp3
- File in wrong directory: Check
DOWNLOAD_DIR in config
Download Fails
Problem: cast-download errors or hangs.
Solution:
pip install --upgrade yt-dlp
yt-dlp --version
yt-dlp --verbose "URL"
If it's a geo-blocked video:
Use a VPN or find an alternative upload of the same track.
Home Assistant Connection Error
Problem: curl errors when contacting HA.
Solution:
curl -H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
"http://homeassistant.local:8123/api/states"
Regenerate token if needed:
HA → Profile → Scroll down → Long-Lived Access Tokens → Generate new
Video Mode Issues
Problem: cast-download --video fails with "ffmpeg not found" or similar error.
Solution:
ffmpeg -version
sudo apt install ffmpeg
brew install ffmpeg
Problem: Video creation is slow or takes too long.
Solution:
- Video encoding is CPU-intensive. First-time creation may take 10-30 seconds per song.
- Use MP3 mode (
cast-download without --video) for faster downloads.
- Consider lowering video quality in the script (edit
cast-download and change -preset ultrafast to -preset fast for better quality but slower encoding).
Problem: Text overlay doesn't appear or looks wrong.
Solution:
Problem: Chromecast audio device plays video without visuals.
Solution:
- This is expected behavior. Audio-only Chromecast devices (Google Home Mini, Chromecast Audio) will play the audio track from MP4 files but cannot display video.
- Use MP3 mode for audio-only devices to save bandwidth and storage.
Problem: MP4 files are too large.
Solution:
- Videos are larger than MP3s (typically 2-3x the size).
- Reduce video bitrate by editing
cast-download and changing -b:a 192k to -b:a 128k for audio, or adjust video codec settings.
- Use MP3 mode if storage is a concern.
Radio Mode Issues
Problem: Radio mode downloads unrelated songs.
Solution:
- Radio mode searches YouTube using the artist name from the seed song.
- Sometimes the search may return mixed results due to ambiguous artist names.
- Try using a different seed song with a clearer artist name.
- The
radio_ prefix makes it easy to identify and remove unwanted downloads.
Problem: Radio mode doesn't find any related songs.
Solution:
- Ensure you have a stable internet connection.
- Check that the seed song has proper metadata (title/uploader).
- Try a different seed song — some videos have limited search results.
- Increase the count with
--radio-count 10 to get more results.
Problem: Related songs don't play in sequence automatically.
Solution:
Cast Commands Hang
Problem: cast-play doesn't return or music never starts.
Common causes:
- Media player is offline — Check
cast-devices for state
- Server isn't accessible from HA — Verify
SERVER_IP in config matches current IP
- Chromecast network issue — Restart Chromecast
- Wrong device ID — Copy exact ID from
cast-devices output
Quick fix:
cast-server stop
cast-server start
cast-play song.mp3
cast-devices
Project Structure
youtube-music-cast/
├── scripts/
│ ├── cast-setup # Configuration wizard (interactive)
│ ├── cast-download # Download from YouTube (uses yt-dlp)
│ ├── cast-server # HTTP server manager (start/stop/status)
│ ├── cast-play # Cast to device (HA API)
│ ├── cast-stop # Stop playback
│ ├── cast-status # Player status query
│ ├── cast-devices # List all HA media players
│ ├── cast-list # List downloaded files
│ └── cast-help # Help documentation
├── install.sh # Installation script (--global, --help)
├── SKILL.md # This file (ClawdHub skill definition)
├── README.md # User-facing documentation
├── CHANGELOG.md # Version history
├── LICENSE # MIT license
├── .gitignore # Protects secrets and state
└── .clawdhub/
└── origin.json # ClawdHub metadata
~/.youtube-music-cast/
└── config.sh # Your configuration (don't commit to Git)
/tmp/youtube-music/
└── *.mp3 # Downloaded music files
Requirements
yt-dlp (YouTube downloader)
pip install yt-dlp
Update regularly: pip install --upgrade yt-dlp
Python 3 (HTTP server)
python3 --version
curl (HTTP client for HA API)
curl --version
jq (JSON processor)
sudo apt install jq
brew install jq
ffmpeg (Video mode - optional)
Required for --video flag to create MP4 videos with album art and text overlays.
sudo apt install ffmpeg
brew install ffmpeg
Check installation:
ffmpeg -version
Note: Video mode is optional. If you only download MP3s, you don't need ffmpeg.
Performance Tips
1. Batch Downloads
Download multiple tracks or entire playlists at once:
yt-dlp -x --audio-format mp3 --audio-quality 320K \
-o "/tmp/youtube-music/%(playlist_index)s-%(title)s.%(ext)s" \
"https://youtube.com/playlist?list=PLAYLIST_ID"
cast-play 01-song.mp3
cast-play 02-song.mp3
cast-play 03-song.mp3
2. Keep Server Running
The HTTP server is lightweight (~5MB RAM). No need to stop/start between casts:
cast-server start
cast-play song1.mp3
cast-play song2.mp3
3. Use Default Device
Set DEFAULT_DEVICE in config to avoid typing it every time:
DEFAULT_DEVICE="media_player.bedroom_display"
cast-play song.mp3
4. Clean Up Occasionally
Files in /tmp/ are cleared on reboot by design, but you can manually clean:
cast-list
rm /tmp/youtube-music/*.mp3
5. WiFi Matters
If streaming glitches:
- Move Chromecast to 5GHz WiFi
- Reduce distance between Chromecast and server
- Check for WiFi interference
6. Alias Commands
Add shell aliases for faster access:
alias cs='cast-server'
alias cd='cast-download'
alias cp='cast-play'
alias cl='cast-list'
alias cst='cast-status'
cs
cd URL
cp song
cl
Notes
- Files are stored in
/tmp/youtube-music/ — cleared on reboot (by design)
- Web server runs in background, persists across sessions
- Keep filenames simple: lowercase, hyphens, no spaces/special chars
- Server and Chromecast must be on same network
- HA token is stored locally in
config.sh — don't commit to Git
- Quality is 320K MP3 — good balance of quality and file size
- No cloud services, no subscriptions, no tracking
Comparison: This vs Alternatives
| Feature | YouTube Music Cast | Spotify Free | YouTube Premium |
|---|
| Cost | Free | Free (with ads) | $13.99/month |
| Ads | None | Yes, every few songs | None |
| Offline | Yes, forever | No (premium only) | Yes, with limit |
| Quality | 320K MP3 | 160K (variable) | Up to 1080p video |
| Privacy | Local only | Cloud-based | Cloud-based |
| Platform | Any Chromecast | Spotify Connect | YouTube apps |
| Queue management | Manual | Built-in | Built-in |
| Multi-room | Manual | Premium feature | No |
Bottom line: If you value privacy, want to own your music, and don't need cloud features, this is for you.
License
MIT License — use it, modify it, share it.
Version: 6.0.0
Author: Wobo
License: MIT
