听老故事接入指导（comic_audio）¶

相关页：数据源目录 · 设备接入手册 · 播放流程与双缓冲细节见设备手册 §3.2

1. 用途¶

连环画语音收听：标签 → 故事 → 整本播放清单三级浏览，整本连续播放；带屏设备可另取页图清单。音频由 TTS 流水线合成，经服务端 /media 站内缓存中转下发（不下发源站真实地址与真实文件名）。

2. 端点与鉴权¶

GET https://api.wwzu.com/api/v1/data/comic_audio?action=<tags|stories|playlist|pages>&<业务参数>
X-Device-SN: XMBOX-2026-000001
X-Device-Token: <device_token>

设备鉴权同其他源；
需订阅（付费源）：自助订阅返回 40309，唯一开通途径 = 邀请码兑换——用户在用户中心「数据源订阅」页输入邀请码，或调 POST /api/v1/subscription/redeem（码一次即焚；40308 = 码无效/已用/过期/作废）。例外：绑定库内 VIP 设备的用户免邀请码直接订阅，VIP 设备端免订阅直接取数（2026-09-19）。

3. 请求参数¶

参数	说明
`action`	`tags`（默认）标签列表 / `stories` 标签下故事 / `playlist` 整本播放清单 / `pages` 页图清单（带屏设备）
`tag`	stories 必填：标签名（精确匹配，如 `英雄模范`）
`story_id`	playlist/pages 必填：书目对外标识（`htmlname`，见 stories 返回）
`page`	分页页码（默认 1）
`sort`	stories 排序：`hits`（默认，热度）/ `new`（最新）

4. 返回示例¶

① tags 标签列表（10 个/页，按收录量降序）：

{ "action": "tags", "page": 1, "total": 104,
  "tags": [ { "name": "英雄模范", "count": 161 }, { "name": "传统美德", "count": 125 } ],
  "source_name": "内容来自闲沐连环画（wwzu.com），语音由 TTS 流水线合成，仅供个人收听" }

② stories 故事列表（11 本/页；以 htmlname 为书目对外标识，不含内部数字 ID）：

{ "action": "stories", "tag": "英雄模范", "sort": "hits", "page": 1, "total": 161,
  "stories": [ { "htmlname": "200741113201", "title": "岳传之岳母刺字", "pages": 40, "intro_audio": true,
                 "cover_url": "https://photourl.wwzu.com/web_thumbs/…" } ] }

③ playlist 整本播放清单（一次返回全部有音页；128 条/页，超长书 more=true 时按 page 翻页）：

{ "action": "playlist", "story_id": "200741113201", "title": "岳传之岳母刺字",
  "base_url": "/media/comic_audio/2244/",
  "files": [ "001.mp3", "003.mp3", "004.mp3", "…" ],
  "total": 38, "page": 1, "more": false, "next_page": null,
  "source_name": "内容来自闲沐连环画（wwzu.com）…" }

story_id 回显请求传入的 htmlname；文件名与页号对齐（001.mp3 → 第 1 页，无音页号自然缺号，如内容提要页），顺序即播放顺序；完整下载地址 = 同主机 + base_url + 文件名；
清单从第 1 页正文语音开始（整本梗概语音不进清单）。

④ pages 页图清单（带屏设备按需另取，10 张/页；与语音无关，含无音页）：

{ "action": "pages", "story_id": "200741113201", "title": "岳传之岳母刺字", "page": 1, "total": 40,
  "pages": [ { "no": 1, "image_url": "https://photourl.wwzu.com/web_thumbs/…" } ] }

5. 注意事项¶

书目标识：对外标识 = htmlname（数字串）；内部数字 ID 绝不下发，story_id 一律传 htmlname（2026-09-19 契约改版，旧固件按数字 ID 请求将得 50401）；
音频中转：音频经 /media 站内缓存下发，固件 mp3dec/play_mp3() 解码播放（需固件支持），服务端不转码；
备货机制：清单返回时前 3 条已落盘（起播零等待），其余按播放顺序后台备货；个别条目 404 = 仍在备货（长书快进场景），退避 1 秒重试；服务端磁盘缓存上限 2GB（LRU）；
连贯播放：设备顺序播放 + 边播边预取下一条（双缓冲）即整本不中断——完整播放状态机见设备手册 §3.2；
收录范围：仅收录「语音完整」的书（正文页零语音缺失；内容提要/封底页本就不合成语音，不计缺失）；单书清单只含有音页；
缓存：TTL 3600 秒、按动作+参数分缓存；
合规：source_name 来源标注必须保留展示。