--- name: youtube-music-cast description: Download music from YouTube/YouTube Music and stream to Chromecast via Home Assistant. Complete CLI toolset with web server integration, configuration wizard, and playback controls. version: "6.0.0" author: Wobo license: MIT homepage: https://github.com/clawdbot/skills repository: https://github.com/clawdbot/skills/tree/main/youtube-music-cast user-invocable: true triggers: - play music - cast to chromecast - youtube music - download music - cast music keywords: - youtube - music - chromecast - home-assistant - cast - media-player - streaming - yt-dlp - google-cast - audio - mp3 - free-music category: media requires: bins: - yt-dlp - python3 - curl - jq env: [] config: stateDirs: - ~/.youtube-music-cast metadata: clawdbot: emoji: "🎵"

---

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

# 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

| Command | Description | Example | |---------|-------------|----------| | cast-setup | Run configuration wizard | cast-setup | | cast-download [options] | Download from YouTube/YouTube Music | cast-download https://youtube.com/watch?v=... --video | | cast-radio [options] | Start radio mode with related songs | cast-radio https://youtube.com/watch?v=... --count 10 | | cast-server [start|stop|status] | Manage HTTP server | cast-server start | | cast-play [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

# 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.

...