Pure Live v2.1.0 阶段更新:Twitch 与 SOOP Live 全平台接入及五端发布工程详解

原创2026-10-14 13:10:501,404 阅读
文章标签:音视频直播

Pure Live v2.1.0 阶段更新:Twitch 与 SOOP Live 全平台接入及五端发布工程详解

本篇文章以 Pure Live v2.1.0 阶段更新(docs/STAGE_UPDATE_2_1_0.md)为核心,梳理该版本将维护分支的弹幕、性能、播放、助眠、本地互动与发布工程整合为可向上游审阅大版本的全过程。你将看到 Twitch、SOOP Live 两个新平台的完整接入链路(从 GraphQL/HTTP 接口到 IRC 与二进制 WebSocket 弹幕协议)、弹幕纯文字模式的存储兼容设计,以及 Android/Windows/Linux/macOS/iOS 五平台构建矩阵、阶段标签补建策略与回归门禁的实战细节。文中所有结论均对照当前仓库源码,便于直接深入阅读验证。

一、阶段目标与上游同步基线

v2.1.0 阶段的定位非常明确:将维护分支中已经验证过的弹幕、性能、播放、助眠、本地互动与发布工程能力,整合为一个可向上游审阅的大版本,并同步上游 liuchuancong/pure_live@24ff92b6(2026-08-18)提交。

上游同步的内容可分为四类:

同步类别 具体内容
平台能力 Twitch 与 SOOP Live 平台、账号 Cookie 页面、原生搜索、直播详情、播放清晰度、弹幕协议
依赖升级 file_picker 12.0.0 稳定 API、windows_single_instance 1.2.0,并迁移到上游锁定的 flutter_inappwebview 6.2.0-beta.3 修订分支
行为修正 默认音量百分比修正、网页关闭清理、字体初始化顺序、弹幕纯文字模式
维护分支保留项 统一 px/s 弹幕速度、动态刷新率、积压淘汰、会话隔离、小窗实时预览、AGP 9 Built-in Kotlin 迁移

值得注意的工程约束是:升级依赖不能破坏维护分支已验证的运行时行为。因此文档明确列出"保留"清单——例如统一 px/s 弹幕速度(跨平台弹幕移动速度一致)、动态刷新率(按播放帧率调整弹幕刷新节奏)、积压淘汰(弹幕队列过长时丢弃旧消息而非拖垮 UI)、会话隔离(不同房间/平台的弹幕会话互不串扰)与小窗实时预览。这些能力在同步上游后必须原样保留,形成"上游能力 + 维护分支行为修正"的合并基线。

二、Twitch 完整接入:从平台目录到 IRC 弹幕

v2.1.0 将 Twitch 推进到了"完整接入"状态:平台目录、链接识别、分类、推荐、频道搜索、直播详情、清晰度、外部打开、录制配色与账号设置均已打通。目录、搜索与房间返回的 viewersCount 被明确建模为并发观看人数,可加入"真实在线人数优先"排行。

2.1 平台适配器与 GraphQL 持久化查询

Twitch 的核心实现位于 lib/shared/platforms/twitch/twitch_site.dart,它同时实现了 LiveSite、LiveSiteRoomRefresher、LiveSiteRecordRoomResolver、LiveSiteExternalRoomResolver 四类接口,覆盖浏览、刷新、录制解析与外部打开。

Twitch 的接口请求全部走 GraphQL,并且使用 persisted query(持久化查询) 方式:每个查询附带固定的 sha256Hash,客户端只发送操作名与哈希,服务端按哈希执行对应查询。源码中 buildPersistedRequest 封装了这一格式:

String buildPersistedRequest(String operationName, String sha265Hash, Map<String, dynamic> variables) {
  return jsonEncode({
    'operationName': operationName,
    'extensions': {
      'persistedQuery': {'version': 1, 'sha256Hash': sha265Hash},
    },
    'variables': variables,
  });
}

分类页使用 SearchCategoryTags 一次性拉取约 100 个分类,再通过 BrowsePage_AllDirectories 递归拉取每个分类的子分区(getAllSubCategores 以"本次返回数量等于页大小即继续翻页"判断是否还有更多);直播列表使用 DirectoryPage_Game,搜索使用 SearchResultsPage_SearchResults,房间详情则在一个请求中批量拼接 ChannelShell 与 StreamMetadata 两个查询。分页通过 cursorMap 按 类型_标识_页码 保存游标,避免多视图并发请求互相污染。

2.2 Client-Integrity 令牌与多级传输降级

Twitch 的 GraphQL 请求在部分网络环境下要求 Client-Integrity 令牌。源码实现了完整的令牌生命周期:_ensureIntegrityToken 在令牌缺失或距过期不足 5 分钟时触发刷新,刷新写入 _integrityToken 与 _integrityExpiresAt;_usableIntegrityToken 则在剩余有效期不足 30 秒时视为不可用。值得注意的是 normalizeIntegrityExpirationMilliseconds 同时兼容 Unix 秒与毫秒两种时间戳格式(小于 100000000000 视为秒并乘以 1000),这是针对 Twitch/Streamlink 字段差异做的兼容处理。

getGplResponse 展示了清晰的四级传输降级链路:

  1. 先以普通 dart:io 发送 GraphQL 请求(无 Cookie 绑定时 Twitch 网页端本身也先试公开请求,速度更快);
  2. 若失败或返回 integrity 错误,在 Android 上改用系统 TLS 通道 AndroidNativeHttp.postTwitchJson 重试(处理部分代理路径 CONNECT 后 dart:io TLS 被重置的问题);
  3. 若仍失败,则暂时绕过已保存账号 Cookie(_bypassStoredSessionForIntegrity,不污染用户存储的 Cookie),以匿名会话重试;
  4. 最后在支持环境下交给 Chromium/KPSDK 的 TwitchWebIntegrityProvider 执行浏览器级请求,并把浏览器错误作为最终诊断抛出。

2.3 播放清晰度:usher HLS 主播放列表解析

清晰度获取遵循 Twitch 网页播放器流程:先用 PlaybackAccessToken 查询换取 value(token)与 signature(签名),再拼参数请求 https://usher.ttvnw.net/api/channel/hls/{roomId}.m3u8,最后解析返回的主播放列表。

源码中的 parseMasterPlaylist 特别处理了此前实现的一个缺陷:旧代码把所有 #EXT-X-STREAM-INF 的 URL 与 BANDWIDTH 分别收集到独立数组中,遇到多余 URI/注释或相对路径变体时数组错位、清晰度标签张冠李戴。新实现改为"状态机"式解析——每读到一条 #EXT-X-STREAM-INF 暂存属性,读到随后的 URI 时立即合并为一条质量记录,并以 height:帧率:带宽:videoGroup 作为去重键,支持同一清晰度多个 CDN 地址共存。排序上,原画(chunked)被赋予 1 << 30 的语义优先级,因为其瞬时平均带宽可能低于转码流,语义优先级比裸带宽更可靠。

2.4 IRC 弹幕协议:保留完整显示名与消息 ID

Twitch 弹幕走 IRC over WebSocket,实现在 lib/shared/platforms/twitch/twitch_danmaku.dart。连接 wss://irc-ws.chat.twitch.tv 后,按 Twitch 官方握手流程发送 PASS/NICK/CAP REQ/JOIN;心跳用 PING :tmi.twitch.tv 并由服务器 PONG 应答。未登录时使用 justinfan + 随机数字的匿名昵称,登录后从 Cookie 中提取 auth-token 与 login 走 OAuth 通道。

IRC 行解析保留的字段包括:display-name(完整显示名,缺失时回退到登录名)、user-id、id(消息 ID,用于撤回定位)、tmi-sent-ts(平台时间戳)以及 color(无颜色用户回退为白色)。三类撤回事件均有独立处理:CLEARMSG(单条撤回)、CLEARCHAT 带 target-user-id(按用户撤回)与不带目标的全屏清除。登录被拒(login authentication failed)时会转为 _loginRefused,并只播报一次 twitch_cookie_expired_notice 提示,避免重复打扰。

三、SOOP Live 接入:播放令牌与二进制弹幕协议

SOOP Live(原 AfreecaTV 国际版)同样在本阶段完成完整接入,覆盖分类、推荐、搜索、房间信息、播放线路、Cookie、弹幕、链接识别、录制配色、并发在线人数与本地互动资源包。核心实现在 lib/shared/platforms/soop/soop_site.dart。

3.1 目录、推荐与搜索的并发在线人数

SOOP 的目录与推荐接口在 sch.sooplive.co.kr/api.php(m=categoryList / m=categoryContentsList)与 live.sooplive.co.kr/api/main_broad_list_api.php。其观众数字段存在 PC 与移动端拆分问题:current_view_cnt 仅统计 PC 端,total_view_cnt(或显式 PC/移动字段之和)才是真实并发。源码为此专门实现了 parseOnlineViewers:

  • 优先读取 total_view_cnt、view_cnt、VIEW_CNT;
  • 其次尝试 pc_view_cnt + mobile_view_cnt、current_view_cnt + m_current_view_cnt 两对字段求和;
  • 全程容忍逗号/中文逗号分隔的千位符,并区分"字段缺失"与"显式为 0"。

3.2 播放令牌按真实广播编号生成

SOOP 的播放链路是"拿令牌再签名"两步式:房间详情返回 viewpreset(清晰度列表)、bno(广播编号)、rmd(分配服务器)、cdn(CDN 类型);随后 getCdnUrl 向 {rmd}/broad_stream_assign.html 请求分配真实播放地址(按 cdn 内容映射 gs_cdn/lg_cdn 到 gs_cdn_pc_web/lg_cdn_pc_web 返回类型),再通过 player_live_api.php(type=aid)换取 AID 签名,最终拼接为 {view_url}?aid={aid}。

与旧实现不同,播放令牌严格按真实房间广播编号(bno)生成,且播放线路并发读取并过滤空地址;多平台详情回退路径同步移除了"空房间强制解引用",避免错误房间对象被强转时崩溃。

3.3 弹幕:WebSocket TLS 端口映射与二进制帧解析

SOOP 弹幕实现在 lib/shared/platforms/soop/soop_danmaku.dart。房间详情里的 CHATNO、CHDOMAIN(或 CHIP)、CHPT 构成弹幕端点,源码中的 buildDanmakuWebSocketUrl 有一个关键细节:官方 HTTPS 播放器会把明文 WebSocket 端口 CHPT 映射到相邻的 TLS 端口(例如 9000 → 9001),直接对未加 1 的端口发 WSS 会在 TLS 握手阶段卡死。此外,当只有 IPv4 地址 CHIP 时,会按 chat-{每段十六进制大写拼接}.sooplive.co.kr 规则推导安全主机名。

连接后使用二进制协议:数据帧以 \x1b\x09(ESC 前缀)开头,头部 14 字节依次携带服务号与包体长度,decodeMessage 按该头结构循环切分;入房时依次发送连接包 \x1b\x09 000100000600... 与携带 chatNo 的 JOIN 包,心跳包固定为 \x1b\x09 000000000100...,心跳间隔 20 秒。弹幕参数 SoopDanmakuArgs(url, chatNo) 以 JSON 形式随房间数据持久化,便于录制与恢复场景复用。

四、弹幕纯文字模式与存储键兼容

v2.1.0 在弹幕体验上的核心改进是"纯文字模式":主画面与小窗分别提供开关,过滤图集表情,且开关实时作用于画面(无需重启播放或重连弹幕)。

  • 设置项定义在 lib/core/config/danmaku_settings_controller.dart:主画面键为 noEmojiMode(默认 false),小窗键为 pipDanmakuNoEmojiMode(默认 false),两者独立。
  • 小窗设置预览同步展示纯文字模式效果;手机端保持"上方固定预览、下方独立滚动参数"的既有布局。
  • 存储兼容方面,源码在解析配置时同时读取旧键 pipDanmaNoEmojiMode 与新键 pipDanmakuNoEmojiMode,即:
'pipDanmakuNoEmojiMode':
    danmaku['pipDanmakuNoEmojiMode'] ?? danmaku['pipDanmaNoEmojiMode'] ?? defaultPipDanmakuNoEmojiMode,
  • 备份导出统一收敛为新键名:在 lib/features/backup/backup_controller.dart 中,旧键 pipDanmaNoEmojiMode 被显式加入导出集合与导入判断,确保老用户升级后备份/恢复不丢配置、新旧版本备份可互相兼容。

五、本地互动资源包:Twitch 徽章、Bits 与 Hype Train

本地互动(Local Interaction)在本阶段为 Twitch 补齐了专属体验包,包括 Twitch 徽章、Bits、订阅等级、Cheer、订阅星标与 Hype Train。这些资源项在 lib/domains/live/presentation/playback/widgets/local_interaction/local_interaction_controller.dart 中登记:

  • twitch_cheer:Cheer(Bits 打赏)礼物,nameKey 为 local_gift_twitch_cheer;
  • twitch_hype_train:Hype Train(热度列车)事件,nameKey 为 local_gift_twitch_hype_train;
  • 平台徽章映射 Sites.twitchSite => 'local_badge_twitch'、Sites.soopSite => 'local_badge_soop',与通用徽章一起参与本地互动消息的组装与展示。

SOOP 侧同样配有本地互动资源包,两平台由此获得了与 B 站/虎牙/斗鱼等既有平台一致的本地互动呈现能力。

六、五平台构建矩阵与阶段标签补建

v2.1.0 的发布工程覆盖五个平台,构建矩阵如下:

平台 架构 产物 验证方式
Android arm64-v8a 正式包名 APK Windows 本机签名构建、ADB 覆盖安装与启动探测
Windows x64 便携 ZIP / 可选 EXE Windows 本机构建与进程/窗口启动探测
Linux x64 tar.gz 便携包 Ubuntu 24.04 阶段工作流编译与 ELF x86-64 核验
macOS universal .app ZIP macOS 15 编译,主程序含 x86_64 与 arm64
iOS arm64 device 无签名 .app ZIP macOS 15 flutter build ios --no-codesign

工程上的成本控制策略:Android 与 Windows 优先使用本机 5090 环境;Apple 平台仅使用一次 macOS 作业同时构建 macOS 与 iOS,控制 Actions 用量;五平台支持手动选择,显式阶段标签只补建指定平台,日常分支提交不会自动消耗构建分钟。

阶段标签规则:

  • stage-linux-*:只构建 Linux;
  • stage-ios-*:只构建 iOS;
  • stage-apple-*:在同一 macOS Runner 构建 macOS 与 iOS;
  • signed-build-*:只补建正式签名 Android arm64。

正式签名 APK 默认通过本机临时 Runner 注入 GitHub Secrets;signed-build-* 标签仅在临时 Runner 服务异常时作为一次托管构建回退。

七、回归门禁:从本机 CI 到安装探测

v2.1.0 建立了四道回归门禁:

  1. tool/local_ci.ps1:锁定依赖(pub get --enforce-lockfile)、Built-in Kotlin 审计、格式检查、Analyze、完整测试、25 项接口探测。脚本支持 Focused(针对指定测试路径快速反馈)与 Full(完整门禁)两种范围,并通过资源租约与资源监控(build_resource_guard.ps1)避免重型任务互相抢占;仓库预检阶段还会串行执行 validate_build_policy.ps1、test_subst_path.ps1、Android 录制/代理/活动状态等回归测试。
  2. tool/build_local_release.ps1 -RequireReleaseSigning:产出 Android arm64 与 Windows x64 正式产物。脚本从 pubspec.yaml 解析版本(version: 2.1.0+2048 形式),Windows 则从 assets/version.json 的 platforms.windows 项读取独立版本,避免把较新的 Android 版本号错误盖到 EXE 上。
  3. tool/install_android_local.ps1:自动枚举在线设备(优先唯一 IPv4 无线传输,避免一台手机被当作两台),执行覆盖安装、冷启动与前台窗口检查。
  4. manual-build:Linux、macOS、iOS 编译与短期构建归档。

25 项接口探测对应 tool/interface_probe.py,其中 Twitch 覆盖分类(twitch_categories_probe)、目录(twitch_directory_probe)、搜索(twitch_search_probe)、房间(twitch_room_probe)与播放令牌(twitch_playback_probe),SOOP 覆盖分类、推荐、搜索、房间与播放令牌,均为无依赖的轻量 HTTP 探测。

本阶段本机门禁结果:Built-in Kotlin 审计与 Flutter Analyze 零问题、64 项单元/Widget 测试通过、25/25 平台接口探测通过。

八、最终构建验收与产物核验

阶段收尾时对五平台产物做了逐一验收:

  • Android arm64 正式签名:包名 com.mystyle.purelive、版本 2.1.0 (2048)、单一 arm64-v8a,v2 签名证书与 v2.0.36 正式包一致;
  • Windows x64:本机完成便携 ZIP 与 EXE 安装器,程序持续启动 20 秒后进程存活、窗口句柄有效且 UI 线程响应;
  • Linux x64:归档含 1320 项,主程序为 x86-64 PIE ELF;
  • macOS universal 与 iOS arm64:macOS 主程序同时含 x86_64/arm64 双架构,iOS 主程序为 arm64,归档保持无签名状态;
  • 哈希一致性:所有正式附件均在本机重新计算 SHA-256,Android、Linux 与 Apple Actions 外层归档摘要和 GitHub Artifact 摘要一致,确保"本机构建 → 上传 → Actions 归档"链路无篡改、无漂移。

九、小结

v2.1.0 是维护分支能力向上游合并的关键节点:在 Twitch 侧实现了"GraphQL 持久化查询 + Client-Integrity 多级降级 + usher HLS 清晰度解析 + IRC 弹幕"的完整链路,在 SOOP 侧打通了"真实并发人数解析 + 按广播编号签发播放令牌 + WSS 端口映射与二进制弹幕帧"的全流程,同时以纯文字模式、备份键兼容、本地互动资源包补全了弹幕与互动体验,并用五平台构建矩阵、阶段标签和四道回归门禁把发布工程收敛为可重复、可审计的流程。

如需继续深入,可依次阅读:Twitch 适配器 lib/shared/platforms/twitch/twitch_site.dart 与弹幕 lib/shared/platforms/twitch/twitch_danmaku.dart;SOOP 适配器 lib/shared/platforms/soop/soop_site.dart 与弹幕 lib/shared/platforms/soop/soop_danmaku.dart;弹幕设置 lib/core/config/danmaku_settings_controller.dart;门禁脚本 tool/local_ci.ps1、tool/build_local_release.ps1、tool/install_android_local.ps1 与 tool/interface_probe.py。

返回文档索引。

登录后查看全文
pure_live