Youtube Music Cast

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?

Quick Start

# 1. Setup (one time, takes 2 minutes)
cast-setup

# 2. Download your first song
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ

# 3. Start the web server
cast-server start

# 4. Cast it to your default device
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.

# ✅ This works — HA can fetch via HTTP
media_content_id: "http://192.168.1.81:8735/song.mp3"

# ❌ This fails — HA can't read file paths
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

# Clone or download the skill
cd youtube-music-cast

# Make all scripts executable
chmod +x scripts/*

# Install globally (recommended)
./install.sh --global

# Or install locally
./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

# Download a test song
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ

# Start the server
cast-server start

# Cast it
cast-play song.mp3

If music plays, you're ready!

Commands

Usage Guide

Your First Song

# Download from YouTube
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ

# Rename for cleaner URL (recommended)
mv "/tmp/youtube-music/Rick Astley - Never Gonna Give You Up.mp3" \
   "/tmp/youtube-music/never-gonna-give-you-up.mp3"

# Start the web server
cast-server start

# Cast to your default device
cast-play never-gonna-give-you-up.mp3

Cast to Different Rooms

# Living room TV
cast-play song.mp3 media_player.living_room

# Kitchen speaker
cast-play song.mp3 media_player.kitchen_speaker

# Bedroom Chromecast
cast-play song.mp3 media_player.bedroom_display

# Multiple rooms at once (run multiple commands)
cast-play song.mp3 media_player.living_room & \
cast-play song.mp3 media_player.bedroom_display

Check What's Playing

# Default device
cast-status

# Specific device
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

# Stop default device
cast-stop

# Stop specific device
cast-stop media_player.living_room

See What You've Downloaded

# List all music files with sizes
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:

# Basic radio (downloads seed + 3 related songs)
cast-radio https://youtube.com/watch?v=dQw4w9WgXcQ

# Custom number of related songs
cast-radio https://youtube.com/watch?v=dQw4w9WgXcQ --count 10

# Radio mode with video files
cast-radio https://youtube.com/watch?v=dQw4w9WgXcQ --video --count 5

Or use cast-download with --radio flag:

# Download with radio mode
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ --radio

# Download with custom count
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ --radio --radio-count 5

# Radio + video mode combined
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ --radio --video

How it works:

1. Downloads the seed song you specify
2. Extracts artist/title from metadata
3. Searches YouTube for similar videos
4. Downloads related songs (prefixed with radio_)
5. Related songs are ready to cast in sequence

Play your radio queue:

# Start server
cast-server start

# Play the first song
cast-play $(ls -t /tmp/youtube-music/*.mp3 | head -n 1 | xargs basename)

# Or play related songs sequentially
cast-play radio_some-song.mp3
cast-play radio_another-song.mp3
# ... etc

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:

# Download as MP4 with album art and text
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ --video

# Cast the MP4 file
cast-server start
cast-play "Never Gonna Give You Up.mp4"

Radio mode with videos:

# Download seed + related songs as videos
cast-radio https://youtube.com/watch?v=dQw4w9WgXcQ --video --count 5

# Cast videos
cast-play "Never Gonna Give You Up.mp4"
cast-play "radio_Together Forever.mp4"
# ... etc

How it works:

1. Downloads the audio track (320K MP3 quality)
2. Downloads the album art thumbnail from YouTube
3. 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
4. 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:

• ffmpeg must be installed on your system

  # Debian/Ubuntu
  sudo apt install ffmpeg
  
  # macOS
  brew install ffmpeg
  

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:

# Download some as MP3
cast-download https://youtube.com/watch?v=VIDEO_ID_1

# Download some as MP4
cast-download https://youtube.com/watch?v=VIDEO_ID_2 --video

# Play both - cast-play handles the difference
cast-play song.mp3
cast-play video.mp4

Configuration

Config file: ~/.youtube-music-cast/config.sh

# Home Assistant
HA_URL="http://homeassistant.local:8123"
HA_TOKEN="your-long-lived-access-token-here"

# Web Server
SERVER_IP="192.168.1.81"
SERVER_PORT="8735"

# Default Device (override per command)
DEFAULT_DEVICE="media_player.bedroom_display"

# Directories
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: