YouTube Music Cast

核心用法

youtube-music-cast 是一套基于 yt-dlp 和 Home Assistant 的本地音乐下载与投射工具链，将 YouTube/YouTube Music 内容转为 320K MP3 后，通过自建 HTTP 服务器推送至任意 Chromecast 设备。完整流程为：cast-download <URL> → cast-server start → cast-play <file>，三步即可播放。

主要功能包括：

• 下载：yt-dlp 提取音频为 320K MP3 或带封面/歌词叠加的 MP4 视频
• 电台模式：基于种子歌曲自动发现并下载相关推荐曲目
• 多房间投射：支持任意 Home Assistant 集成的 Chromecast 设备
• 本地托管：Python HTTP 服务器桥接本地文件与 HA play_media API

显著优点

| 维度 | 表现 |

|------|------|

| **成本** | 完全免费，无订阅、无广告 |

| **音质** | 固定 320K MP3，优于 Spotify 免费版的 160K |

| **隐私** | 纯本地操作，零云端依赖，Token 仅存本地配置文件 |

| **离线** | 下载后永久保留（默认存 `/tmp`，可配置持久化） |

| **扩展性** | 支持视频模式（MP4 + 封面）、批量下载、播放列表 |

潜在缺点与局限性

1. 版权灰色地带：下载 YouTube 内容违反其 ToS，存在 DMCA 风险
2. 功能依赖 Home Assistant：需自行部署 HA 并配置 Google Cast 集成
3. 网络拓扑限制：HTTP 服务器与 Chromecast 必须在同一局域网
4. 无自动队列：电台模式仅批量下载，需手动串行播放
5. 临时文件设计：默认 /tmp 目录重启清空，需手动迁移防丢失
6. 维护负担：yt-dlp 需频繁更新以应对 YouTube 反爬变更

适合人群

• 已运行 Home Assistant 的智能家居玩家
• 重视隐私、拒绝云音乐订阅的技术用户
• 拥有 Chromecast/Nest 音箱且希望离线听歌的 Linux/macOS 用户
• 能接受 CLI 操作、具备基础网络调试能力的进阶用户

常规风险

• 法律风险：下载受版权保护内容可能面临服务商封禁或法律追责
• 安全风险：HTTP 服务器默认无认证，同一局域网内任意设备可访问下载目录
• Token 泄露：HA Long-Lived Token 明文存储于 ~/.youtube-music-cast/config.sh，需严格保密
• 依赖风险：yt-dlp 项目若停止维护，核心功能将失效

核心用法

YouTube Music Cast 是一套完整的 CLI 工具集，通过三步实现"下载-托管-投播"闭环：首先使用 cast-download 调用 yt-dlp 从 YouTube/YouTube Music 抓取 320K MP3 音频；其次 cast-server 启动轻量级 Python HTTP 服务器，将本地文件转换为 Chromecast 可访问的 URL；最后 cast-play 通过 Home Assistant 的 media_player.play_media 服务推送到指定设备。整个过程无需浏览器、无云端依赖，支持批量下载、多房间同步及 Radio/Video 两种扩展模式。

显著优点

成本优势突出：完全免费，无需 YouTube Premium 或 Spotify 订阅，永久本地存储无下载限制。音质与隐私兼顾：320K MP3 品质与付费服务相当，且所有数据流转均在本地网络完成，无用户行为追踪。生态兼容性强：依托 Home Assistant 打通 Google Cast 生态，支持 Nest 音箱、Chromecast、智能电视等全系列设备。扩展功能实用：Radio 模式基于 YouTube 推荐算法自动发现相关曲目；Video 模式通过 ffmpeg 生成带专辑封面和歌词字幕的 MP4，适配带屏设备。运维门槛低：纯 Shell 脚本架构，依赖均为标准系统工具（yt-dlp/curl/jq），配置向导 cast-setup 可在 2 分钟内完成初始化。

潜在缺点与局限性

技术门槛较高：需自行部署 Home Assistant 并配置 Google Cast 集成，对非技术用户不够友好。网络架构受限：HTTP 服务器与 Chromecast 必须处于同一局域网，跨 VLAN 或复杂拓扑场景下可能失效。功能完整性差距：缺乏付费服务的智能推荐、社交分享、歌词实时同步等云端特性，播放列表管理完全依赖手动操作。版权灰色地带：下载 YouTube 受版权保护内容存在法律风险，工具本身不验证内容授权状态。临时存储设计：默认 /tmp 路径在系统重启后清空，长期收藏需手动迁移或修改配置。依赖维护负担：yt-dlp 需频繁更新以应对 YouTube 接口变更，ffmpeg 视频编码对 CPU 消耗较大。

适合的目标群体

智能家居爱好者：已运行 Home Assistant 且拥有多房间 Chromecast 设备的家庭用户。隐私敏感型用户：拒绝云端音乐服务、追求数据自主可控的技术从业者。离线场景需求者：网络条件不稳定或希望建立本地音乐库的户外/偏远地区用户。极简主义者：厌倦流媒体 App 臃肿界面和广告干扰，偏好命令行高效操作的老派极客。派对/商业场景：需要预先缓存播放列表、避免现场网络依赖的活动策划者。

使用风险与注意事项

Token 泄露风险：Home Assistant 长生命周期令牌以明文形式存储于 ~/.youtube-music-cast/config.sh，文件权限不当或误提交 Git 将导致智能家居控制权外泄。本地服务器暴露：8735 端口 HTTP 服务若被错误映射至公网，可能暴露下载内容甚至成为内网渗透跳板。供应链安全隐患：yt-dlp 作为关键依赖若从非官方渠道安装，存在被植入恶意代码的可能；建议通过 pip 官方源并校验哈希。版权合规风险：用户需自行确保下载内容的合法性，工具不提供内容过滤机制。网络稳定性依赖：Chromecast 与 Home Assistant、HTTP 服务器之间的时序耦合较强，WiFi 波动可能导致投播失败或状态同步异常。