YouTube Music Cast

说明文档

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

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

```bash
# After download, rename immediately
mv "Oasis - Bonehead's Bank Holiday (Remastered 1995).mp3" \
   "oasis-boneheads-bank-holiday.mp3"

# Use lowercase, hyphens only
mv "My Awesome Song.mp3" "my-awesome-song.mp3"

# ...