ytm-cast

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

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

```yaml
# ✅ 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

```bash
# 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

```bash
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

```bash
# 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 <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]` | Manage HTTP server | `cast-server start` |
| `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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Stop default device
cast-stop

# Stop specific device
cast-stop media_player.living_room
```

### See What You've Downloaded

```bash
# 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

```bash
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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# Download seed + related songs as videos

... (truncated)