Files
CyberGril/samples/companion
..

HEL-714 日常成片+本地半身交谈样机,基于远端 main 1e9b08a 和 P10 6a5e155。独立交付,不合并、不部署。PR #1 仍是旧分层小样,目标 main;本目录不依赖其尚未合并代码。

模块边界

  • src/main.ts:日常选片、可切点、真实进退素材、WebRTC、麦克风/能量 VAD、原生 PCM AudioWorklet、取消、恢复和浏览器音画录制。
  • runtime/server.py:aiohttp 同源网关;既有 FunASR WebSocket、LLM HTTP、CosyVoice HTTP、LiveTalking WebRTC 信令与音频上传。只读素材 manifest。不写人格、八字、记忆、关系或生活数据。
  • src/tokens.css 原样复用 HEL-711 的唯一 token 表;controls.css 从已确认雨夜界面的基础控件抽取,未另造主题。页面布局在 style.css,无追加覆盖旧样式。没有引入动画库;Emil animate 模块的目的为避免场景跳变,主体过渡依赖真实正向素材,减少动态偏好下 UI 无按压位移。
  • tools/patch_driver.py 仅修改独立 LiveTalking 代码副本,给 peer 记录 session id,并增加精确关闭该 peer 的端点。模型权重复用,不改 P10 安装、18080/18081、ASR/TTS 或系统环境。

运行候选

先解压本卡复核包,恢复 assets/personas/wanwan-v2-cream-night(整个外观包)。素材二进制不入 Git。依赖锁来自既有小样,没有新增 npm 依赖。

npm ci --ignore-scripts --no-audit --no-fund
python3 tools/pack_assets.py
npm run build

在 .12 复用 /opt/hel715-verify/venv(aiohttp 3.14.5、aiortc 1.15.0、PyAV 17.1.0、torch 2.8.0+cu128、numpy 2.5.4、resampy 0.4.3),不安装或升级系统依赖。先检查 8010、8014 没有其他监听者。

python3 tools/prepare_driver.py --destination /opt/hel714-review/LiveTalking
python3 tools/patch_driver.py /opt/hel714-review/LiveTalking

把构建结果、runtime 和素材放在独立样机目录后,在独立 LiveTalking 目录生成本包 avatar(仓库中没有权重或预处理张量):

cd /opt/hel714-review/LiveTalking
/opt/hel715-verify/venv/bin/python -m avatars.musetalk.genavatar \
  --file /path/to/sample/dist/assets/talk/gaze.mp4 --avatar_id hel714-gaze-v1
/opt/hel715-verify/venv/bin/python app.py --model musetalk \
  --avatar_id hel714-gaze-v1 --batch_size 8 --transport webrtc --tts cosyvoice \
  --REF_FILE xiaoyun --TTS_SERVER http://127.0.0.1:9880 \
  --listenport 8010 --stun ''

另一个前台终端在本目录启动网关;Ctrl-C 后确认两个自测进程都退出。禁止 pkill、fuser -k 或停止共享服务。runtime/config.json 是本样机唯一模型/端点配置。

/opt/hel715-verify/venv/bin/python runtime/server.py --port 8014

浏览器在 .12 本机可打开 http://localhost:8014。远程麦克风需要 HTTPS;本次自测只读复用已有 /opt/voice-agent/web/certs/cert.pem、key.pem,给网关传 --host 0.0.0.0 --cert ... --key ...。未改系统证书信任、防火墙或开机启动。自动化使用 Chromium 的忽略证书检查,仅作用于该测试浏览器;普通浏览器是否能授权须实际确认。

行为和取消契约

日常片目前只有一份雨夜阅读。活动、手动天气、时段全部匹配才选中;无匹配时明确回退默认片。没有接真实天气,没有批量换装或跨人物验证。

进入时等阅读第 96 帧,播真实正向进场,再交谈;返回用独立正向生成回程,续播原日常切点。v2 新底板来自已确认的 04-交谈近景-v2.png,有微动作和目视镜头候选;表情/身体/目光来自底板,只有口型实时驱动。全部仍待总工人工观感审核,不能据“可播放”判断自然。

每轮回复拥有独立 peer。取消首先断开浏览器音频图、静音/暂停旧视频、关闭 peer、递增轮次;后端取消 LLM/TTS HTTP 任务,关闭上游响应,再精确销毁该 driver session(含其推理/输出队列)。旧 peer 的 RTP 和旧轮异步错误不进入新轮。这个选择增加建连成本,换来不复用难以完整清理的上游队列。共享 CosyVoice 服务不由本样机管理:客户端断开不等于已证明共享模型内部 GPU 生成即时停止。

LLM 和整句 TTS 生成与 ICE/转场并行。网关等浏览器 /api/ready 才把音频送入驱动器,防止转场期间提前说话。整句缓冲减少标点分句空隙,代价是长回复要等整句生成;未声称首包 SLA 或流式生成性能通过。前端的“等待首声”是真实等待。

麦克风请求 AEC/降噪,原生 Worklet 输出 16k PCM;150ms 连续能量启动会立即停止旧回复,650ms 静音发送 ASR 端点。FunASR 2pass-online 仅展示,2pass-offline 收集终稿后提交。失败不伪造文字。长停顿、轻声、扬声器回声仍需真人校准;请用耳机。按钮和合成 WAV 结果均不冒充真人自然抢话通过。

素材版本和回滚

assets/personas/wanwan-v2-cream-night/manifest.json:稳定 companion_id=wanwan、外观 persona_id、服装/光线/天气标签、avatar id、帧级切点、v2 版本、v1 前版和逐文件 SHA256。换包不创建伴侣或写入身份状态。

先把候选完整包解压到新目录,用 tools/pack_assets.py --assets <目录> 校验,再整体替换 assets/personas/<persona_id>,在 assets/active.json 选择它,再构建、重启独立测试服务。禁止把不同版本的单文件混放。avatar 按 manifest 的 id 重新生成或复用对应缓存;网关从 manifest 指定 avatar,不使用别的脸兜底。构建先校验再把所选整包挂载到生成目录 public/assets,该目录可由构建重建,勿作为用户素材唯一副本。回滚对旧完整包执行同样步骤。复核包另附 packs/hel714-v1,仓库只保留它的 manifest 元数据;当前包为 hel714-v2。

检查

npm run build
python3 -m ruff check samples/companion/runtime samples/companion/tools  # 仓库根目录
python3 -m pytest -q  # 仓库根目录,原78项
/opt/hel715-verify/venv/bin/python tools/check_gateway.py  # .12,5项取消/音色/模型故障检查
LD_LIBRARY_PATH=/home/xiaomo/pwlibs/root/usr/lib/x86_64-linux-gnu python3 tools/check_browser.py
LD_LIBRARY_PATH=/home/xiaomo/pwlibs/root/usr/lib/x86_64-linux-gnu python3 tools/check_races.py
LD_LIBRARY_PATH=/home/xiaomo/pwlibs/root/usr/lib/x86_64-linux-gnu python3 tools/check_microphone.py
LD_LIBRARY_PATH=/home/xiaomo/pwlibs/root/usr/lib/x86_64-linux-gnu python3 tools/soak.py

浏览器脚本依赖运行机已安装 Playwright/Chromium;麦克风脚本需复核包内的 evidence/synthetic-microphone.wav。它是 CosyVoice 合成的测试句,经 Chromium 假麦克风送入实际 Worklet→ASR→LLM→TTS→口型链路,绝不是人现场说话。录制用页面实际绘制画面和实际播放的 WebAudio 输出、同一个 MediaRecorder 时钟,不按帧数重建时间戳;静音时钟从开头持续输出零样本,保留进入前的日常画面。连续音画是浏览器播放图的合成采集,不是物理屏幕/扬声器校准。

实测结果和未通过项见 REPORT.md。生成工作流、history、原始候选片、浏览器证据和资源采样放复核附件,不在主仓库存大文件。

HEL-718 驱动器补丁(候选,尚未通过同步门槛)

tools/patch_driver.py 追加类型透传:AudioFrameData.type 经 BaseAvatar.process_frames → WebRTCOutput → HumanPlayer 到未赋 PTS 的 PendingAudio。仅合成空闲 type=1 且无事件的块限至3块(60ms); 真实语音(包括零值 PCM)、自定义音频和事件保留,100块队列提供背压。 首次音频随真实首帧建立时间原点,此后轨道每20ms从队列取最新待播块, 饥饿时补320样本静音;所有已输出包保持320步长,不在 RTP 队列跳时间戳。 时钟改用 monotonic,warm_up 排空左右全部上下文,不移动 Whisper 特征窗。 取消仍销毁本轮 peer,补丁不改变前后端取消协议。

先用 prepare_driver.py 新建私有副本,再运行补丁;源为已选 c726943。 已验证从 P10 干净副本首次及重复应用,拒绝直接修改 P10 复用目录。 driver_audio.py 必须与 patch_driver.py 一起携带。回滚时停止自己的候选 服务,重建全新 c726943 副本,使用 git show ae4fd5c:samples/companion/tools/patch_driver.py 导出的旧版补丁恢复 HEL-714 endpoint,再指向原 avatar/权重;不要原地混用新旧文件。

新增有效检查(使用原有 P10 venv,无新增依赖):

/opt/hel715-verify/venv/bin/python tools/check_driver_audio.py /path/to/private/LiveTalking
# 按真实 RTP PTS 录制刚进入、空闲15秒、连续多轮、打断后再次送入相同音频
/opt/hel715-verify/venv/bin/python tools/record_driver.py \
  --wav fixed.wav --out server-rounds.mp4 --rounds 0,15,1,1 --post 9

trace_driver.py 仅用于隔离测试,以 PYTHONPATH=私有驱动器目录 从该目录运行, 首参为 JSONL 路径,其余为原 app.py 参数。记录逐块生产/接收 RMS、类型、深度、 丢弃合成静音计数、PTS 和 monotonic 墙钟,不随产品默认开启。 record_graph.html/graph_server.py/record_graph.py 复现浏览器产品音频图; record_product.py 记录三轮日常→进场→交谈→说话中取消→正向回程→续读。 measure_sync.py 固定 ROI 和阈值并保存检测器 SHA256、完整命令、offset、窗口、 idle-until、输入/底板哈希、检测误差及逐 lag 相关性。相关性很低时不能把最佳 lag 当作可靠对齐。

本轮仍未达到服务端绝对偏差≤0.15秒/浏览器≤0.25秒,详见 REPORT-HEL718.md。 本补丁解决的是可确认的空闲队列/时钟问题,不能据此宣称音画同步已修好。