名称： youtube-music-cast
描述： 从 YouTube/YouTube Music 下载音乐，并通过 Home Assistant 串流至 Chromecast。完整的 CLI 工具集，包含 Web 服务器集成、配置向导和播放控制。
版本： "6.0.0"
作者： Wobo
许可证： MIT
主页： https://github.com/clawdbot/skills
仓库： https://github.com/clawdbot/skills/tree/main/youtube-music-cast
user-invocable: true
触发器：
- play music
- cast to chromecast
- youtube music
- download music
- cast music
关键词：
- 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
元数据：
clawdbot:
emoji: "🎵"

YouTube Music Cast

YouTube 音乐 → 你的 Chromecast。简单、免费、可用。

从 YouTube 或 YouTube Music 下载音频，并通过 Home Assistant 串流到任何支持 Cast 的设备。无需订阅，无需云服务，仅限你的本地网络。

特性

• ✅ 永久免费 — 无需订阅，无需高级账户
• ✅ 高品质音频 — 320K MP3，音质清晰
• ✅ 视频模式 — 创建带专辑封面和文字叠加的 MP4 视频
• ✅ 电台模式 — 自动发现并播放相关歌曲
• ✅ 本地存储 — 音乐保存在你的设备上，不上传云端
• ✅ 多房间播放 — 可串流至家中的任意 Chromecast 设备
• ✅ 批量下载 — 下载整个播放列表，随时串流
• ✅ 简单 CLI — 快速命令，无需浏览器
• ✅ 离线可用 — 下载后，音乐即归你所有

使用场景

日常音乐

早晨下载喜爱的曲目，全天播放。无需等待，无需缓冲。

派对模式

在客人到达前下载播放列表，然后轻松排队播放歌曲，无需在手机或应用间切换。

背景音乐

工作时播放氛围音乐或播客，无需担心广告或中断。

多房间同步

将同一首歌曲同时串流到多个 Chromecast 设备（卧室 + 客厅 + 厨房）。

为什么选择它而非付费服务？

快速开始

# 1. 设置（一次性，约2分钟）
cast-setup

# 2. 下载你的第一首歌
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ

# 3. 启动 Web 服务器
cast-server start

# 4. 串流到默认设备
cast-play never-gonna-give-you-up.mp3

完成。你的音乐正在通过 Chromecast 播放。

工作原理

三个简单步骤，每个步骤一个命令：

1. 下载

yt-dlp 从 YouTube 或 YouTube Music 抓取音频，并提取为 MP3（320K 品质）。

2. 托管

一个轻量级的 Python HTTP 服务器使你的下载文件在本地网络可访问。无需额外设置——只需 Python 3。

3. 串流

Home Assistant 的 media_player.play_media 服务将 HTTP URL 发送到你的 Chromecast，由其串流音频。

为什么需要 Web 服务器？

Home Assistant 的 play_media 服务需要一个 URL，而不是文件路径。Web 服务器填补了这个鸿沟。

# ✅ 这个有效 — HA 可以通过 HTTP 获取
media_content_id: "http://192.168.1.81:8735/song.mp3"

# ❌ 这个失败 — HA 无法读取文件路径
media_content_id: "/tmp/youtube-music/song.mp3"

架构：

YouTube URL → yt-dlp → MP3 文件 → Python HTTP 服务器 → Home Assistant API → Chromecast

安装

所需条件

• Home Assistant 并已启用 Google Cast 集成
• Chromecast 或支持 Cast 的设备（Nest 音箱、Google Home、电视）
• 系统工具： yt-dlp、Python 3、curl、jq

步骤 1：安装脚本

# 克隆或下载技能
cd youtube-music-cast

# 使所有脚本可执行
chmod +x scripts/*

# 全局安装（推荐）
./install.sh --global

# 或本地安装
./install.sh

步骤 2：运行设置向导

cast-setup

向导将询问：
- Home Assistant URL — 例如：http://homeassistant.local:8123
- 长期访问令牌 — 在 HA → 个人资料 → 长期访问令牌中生成
- 服务器 IP — 运行这些脚本的机器 IP
- 默认媒体播放器 — 例如：media_player.bedroom_display

步骤 3：测试你的设置

# 下载一首测试歌曲
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ

# 启动服务器
cast-server start

# 串流它
cast-play song.mp3

如果音乐开始播放，说明你已准备就绪！

命令

使用指南

你的第一首歌

# 从 YouTube 下载
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ

# 重命名以获得更简洁的 URL（推荐）
mv "/tmp/youtube-music/Rick Astley - Never Gonna Give You Up.mp3" \
   "/tmp/youtube-music/never-gonna-give-you-up.mp3"

# 启动 Web 服务器
cast-server start

# 串流到默认设备
cast-play never-gonna-give-you-up.mp3

串流到不同房间

# 客厅电视
cast-play song.mp3 media_player.living_room

# 厨房音箱
cast-play song.mp3 media_player.kitchen_speaker

# 卧室 Chromecast
cast-play song.mp3 media_player.bedroom_display

# 同时播放到多个房间（运行多个命令）
cast-play song.mp3 media_player.living_room & \
cast-play song.mp3 media_player.bedroom_display

查看正在播放的内容

# 默认设备
cast-status

# 指定设备
cast-status media_player.bedroom_display

输出示例：

📺 media_player.bedroom_display

状态：正在播放
友好名称：Bedroom display
音量：22%

正在播放：
  标题：Never Gonna Give You Up
  艺术家：Rick Astley
  时长：3:32

应用：Default Media Receiver

停止播放

# 停止默认设备
cast-stop

# 停止指定设备
cast-stop media_player.living_room

查看已下载内容

# 列出所有音乐文件及其大小
cast-list

输出示例：

🎵 已下载音乐

boneheads-bank-holiday.mp3                                    9.3M
never-gonna-give-you-up.mp3                                 8.2M
song-for-nary.mp3                                          7.8M

总计：3 个文件

查看可用设备

cast-devices

输出示例：

📺 可用媒体播放器

media_player.bedroom_display
  名称：Bedroom display
  状态：空闲
  支持：play_media, volume_set, volume_mute, ...

media_player.living_room
  名称：Living room TV
  状态：关闭
  支持：play_media, volume_set, ...

默认设备：media_player.bedroom_display

新特性：电台模式与视频模式

📻 电台模式

电台模式基于 YouTube 推荐，自动发现并下载相关歌曲。下载种子歌曲后，它会搜索相似曲目并添加到你的队列中。

启动电台模式：

# 基本电台（下载种子 + 3 首相关歌曲）
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

或使用带 --radio 标志的 cast-download：

# 使用电台模式下载
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

工作原理：
1. 下载你指定的种子歌曲
2. 从元数据中提取艺术家/标题信息
3. 在 YouTube 上搜索相似视频
4. 下载相关歌曲（前缀为 radio_）
5. 相关歌曲已准备好按顺序串流

播放你的电台队列：

# 启动服务器
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
# ... 等等

提示：
- 相关歌曲前缀为 radio_，便于识别
- 电台模式基于种子歌曲的艺术家名称进行搜索
- 使用 --count 控制要下载的相关歌曲数量
- 与 --video 标志结合使用，实现可视化电台模式

🎬 带视觉效果的视频模式

视频模式创建 MP4 视频文件，而非纯 MP3 文件。每个视频包含：
- 原始音轨
- 来自 YouTube 的专辑封面缩略图
- 显示歌曲标题和艺术家的文字叠加层
- 流畅、高质量的编码

下载视频：

# 下载带专辑封面和文字的 MP4
cast-download https://youtube.com/watch?v=dQw4w9WgXcQ --video

# 串流 MP4 文件
cast-server start
cast-play "Never Gonna Give You Up.mp4"

视频电台模式：

# 将种子及相关歌曲下载为视频
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"
# ... 等等

工作原理：
1. 下载音轨（320K MP3 品质）
2. 从 YouTube 下载专辑封面缩略图
3. 使用 ffmpeg 创建 MP4 视频，包含：
- 循环播放的专辑封面背景
- 编码为 AAC 的音轨
- 底部的文字叠加层（歌曲标题和艺术家名称）
4. 将 MP4 串流到你的 Chromecast（支持视频的电视）

视频输出：
- 编解码器：H.264 (libx264)
- 音频：AAC (192K)
- 分辨率：与缩略图相同（通常为 480p 或 720p）
- 文字：白色文字，带半透明黑色背景框
- 兼容所有支持视频的 Chromecast 设备

注意事项：
- 视频比 MP3 占用更多空间（约大 2-3 倍）
- 需要系统上安装 ffmpeg
- 文字叠加层使用 DejaVu Sans Bold 字体（大多数 Linux 系统已包含）
- 音频 Chromecast 设备（如 Google Home Mini）将仅播放音频
- 带显示屏的 Chromecast（电视、Google Nest Hub）将显示完整视频

视频模式要求：
- 系统必须安装 ffmpeg
```bash
# Debian/Ubuntu
sudo apt install ffmpeg

# macOS
brew install ffmpeg
```

混合 MP3 和 MP4

cast-play 会自动检测文件类型：
- .mp3、.wav、.ogg、.m4a、.flac → 音乐
- .mp4、.mkv、.webm、.mov → 视频

你可以在同一目录中混合两种格式：

# 下载一些 MP3
cast-download https://youtube.com/watch?v=VIDEO_ID_1

# 下载一些 MP4
cast-download https://youtube.com/watch?v=VIDEO_ID_2 --video

# 播放两者 - cast-play 会处理差异
cast-play song.mp3
cast-play video.mp4

配置

配置文件：~/.youtube-music-cast/config.sh

# Home Assistant
HA_URL="http://homeassistant.local:8123"
HA_TOKEN="你的长期访问令牌"

# Web 服务器
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"

直接编辑文件或重新运行 cast-setup 来更新配置。

文件命名最佳实践

保持 URL 简洁。简单的文件名可以避免后续的麻烦。

问题

❌ 糟糕的文件名：

http://192.168.1.81:8735/Bonehead's%20Bank%20Holiday%20(Remastered).mp3

这个 URL 混乱、难以输入，且容易产生编码错误。

解决方案

✅ 好的文件名：

http://192.168.1.81:8735/boneheads-bank-holiday.mp3

简洁、易于输入、没有问题。

实用技巧

# 下载后立即重命名
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"

经验法则：
- 小写
- 用连字符代替空格
- 无特殊字符（@、#、? 等）
- 保持简短

故障排除

Chromecast 不在 Home Assistant 中

问题： cast-devices 未显示 Chromecast 设备。

解决方案： 添加 Google Cast 集成
1. Home Assistant → 设置 → 设备与服务
2. 点击“+ 添加集成”
3. 搜索“Google Cast” → 选择它
4. 按照发现向导操作

如果发现失败：
- 确保 Chromecast 和 Home Assistant 在同一网络
- 尝试使用 Chromecast IP 地址手动添加

服务器无法启动

问题： cast-server start 失败或显示“端口被占用”。

解决方案：

# 检查端口 8735 是否被占用
netstat -tlnp | grep 8735
# 或
ss -tlnp | grep 8735

# 停止任何现有服务器
cast-server stop

# 尝试手动启动以查看错误
cd /tmp/youtube-music
python3 -m http.server 8735

如果端口被其他进程占用：
编辑 ~/.youtube-music-cast/config.sh：
```bash
SERVER_PORT="8736" #