volodarskij/yandex-station-local-streaming
GitHub: volodarskij/yandex-station-local-streaming
一份通过逆向工程 Glagol 协议实现 Yandex.Station 本地音频流播放的技术规范与实战指南。
Stars: 1 | Forks: 0
# Yandex.Station 的本地音频流播放
**技术指南与规范**：如何在 Yandex.Station 上播放来自本地网络的任意音频流 —— 无需 Bluetooth，无需云端中介服务，也无需绑定特定音源。音源可以是任何形式：Spotify、自建媒体服务器、麦克风、网络电台、磁盘上的文件。
本文的所有内容均为逆向工程及数月实际运行经验的结晶。这里不仅记录了行之有效的机制，还记录了那些**死胡同** —— 即看起来显而易见却行不通的方案（以及原因）。
```
Ваш источник звука (любой)
↓ PCM
Энкодер → MP3 CBR
↓
HTTP-сервер в локальной сети ←──── Станция скачивает поток
↑ streamUrl ↑
Glagol WSS-клиент ── radio_play ── Яндекс.Станция (:1961)
```
涉及两个通道：
1. **控制** —— Station 的本地 WebSocket 协议（**Glagol**，WSS :1961）：未公开文档的 `radio_play` 命令可强制 Station 播放任意 URL。
2. **音频** —— Station 会自行连接到您的 HTTP 服务器并获取 MP3。它的播放器对流有着严格且未曾公开记录的要求 —— 本指南的一半篇幅都在专门讨论这一点。
## 目录
| 文档 | 内容 |
|----------|-------|
| [docs/01-discovery-and-auth.md](docs/01-discovery-and-auth.md) | 如何发现 Station（device_id、platform、mDNS）并进行身份验证（Session_id → Glagol token） |
| [docs/02-glagol-websocket.md](docs/02-glagol-websocket.md) | WSS 连接：消息格式、命令、`playerState`、keep-alive、重连机制 |
| [docs/03-radio-play.md](docs/03-radio-play.md) | `radio_play` 命令：protobuf wire format、`externalCommandBypass`、可用代码片段 |
| [docs/04-http-stream.md](docs/04-http-stream.md) | **核心规范**：Station 对 HTTP 流的要求、Content-Length 计算公式、stream token |
| [docs/05-lifecycle.md](docs/05-lifecycle.md) | 生命周期：启动、切换曲目、跳转、暂停、检测“Alice, stop”、Bluetooth、音量 |
| [docs/06-pitfalls.md](docs/06-pitfalls.md) | 死胡同汇总，所有时序与常量汇总表 |
## TL;DR — 最简方案
1. 获取 Station 的 `device_id` 和 `platform`（通过 [quasar.iot.yandex.ru/glagol/device_list](https://quasar.iot.yandex.ru/glagol/device_list) 或 mDNS `_yandexio._tcp.local`）。
2. 获取生命周期短暂的 Glagol token：使用您账户的 `Session_id` cookie 请求 `GET https://quasar.yandex.ru/glagol/token?device_id=…&platform=…`。
3. 打开 `wss://:1961`（证书为自签名 —— 需禁用校验）。
4. 搭建一个提供 **MP3 CBR** 且 **Content-Length 精确**的 HTTP 服务器（不要使用 chunked/ICY/无限流 —— Station 会拒绝这些格式）。
5. 发送 `radio_play` 命令（位于 `externalCommandBypass` 内的 base64 protobuf），包含您服务器的 `streamUrl`。
6. Station 将连接到服务器，缓冲约 2.5 秒后开始播放。
每个步骤都在相应的文档中进行了详细说明。
## 测试环境
- Yandex.Station（第 1 代，platform `yandexstation`），2024–2026 年固件版本。
- 该协议在 Quasar 设备中通用 —— Station Mini/Max/2 的表现应该相同（作者未进行测试）。
## 参考实现与链接
- [alice-spotify-bridge](https://github.com/volodarskij/alice-spotify-bridge) —— 基于本规范的 Rust 实现（音源为 Spotify Connect）+ Alice 语音技能。
- [AlexxIT/YandexStation](https://github.com/AlexxIT/YandexStation) —— Home Assistant 集成，独立的社区版 Glagol 文档。
- [Yandex 关于音箱本地 API 的官方文档](https://yandex.ru/dev/quasar) —— 涵盖了基础命令（`ping`、`stop`、`setVolume`...），但不包含 `radio_play`。
## 安全性
`Session_id` cookie 意味着**拥有 Yandex 账户的完整访问权限**。它仅被一个组件使用（用于获取 Glagol token），且仅用于向 `quasar.yandex.ru` 发送外发请求。请勿记录日志、提交到代码库或包含在 bug 报告中。更多详情请参阅 [docs/01-discovery-and-auth.md](docs/01-discovery-and-auth.md#безопасность-session_id)。
## 许可证
文本采用 [CC BY 4.0](LICENSE.md)，代码片段采用 MIT。本项目与 Yandex 无任何关联。Glagol 协议未公开，且随时可能随固件更新而发生改变。
标签：云资产清单, 内核驱动, 可视化界面, 智能音箱, 物联网, 网络协议, 逆向工程, 音频流媒体