TalkLikeYou 这类实时数字人本地部署，一键脚本最容易出现的现象是画面卡住或干脆没声音，而脚本把音频采集、模型推理、渲染输出三段串在一起跑，日志混在一起，报错往往指向最后崩掉的那一段。更稳的路径是拆开：先单独启动音频采集，确认设备名、采样率、时间戳在日志里连续出现；再喂一段已知采样率的音频验证音频块确实进程序；驱动日志稳定后才加载模型；最后开渲染并检查帧输出。三段各自能被验证之后，再合起来跑，出问题也知道先看哪一份日志。

适用本地部署、一键脚本启动后无声或画面卡住的场景。处理动作：按音频驱动、模型推理、渲染输出分段启动，先用音频设备列表和已知采样率的 wav 确认驱动层能收能打日志，再加载模型，最后开渲染。验证方式是看驱动日志中采样率与时间戳字段是否持续推进，以及渲染窗口或输出视频文件是否更新。设备名、启动参数以所用仓库和运行环境为准，日志关键字需按实际输出确认。

三段链路的建议启动顺序和判断依据可以先固定下来，后面每一步都对着这张表核对：

单独启动音频采集模块并让它打印设备列表

先不要启动模型和渲染，目标是确认输入设备被系统识别，并且程序能拿到它。列设备的命令和运行环境相关，下面是常见做法，实际设备名以运行环境输出为准，拿到后原样复制进配置，别手写。

# Linux/ALSA
arecord -l
# PulseAudio/PipeWire
pactl list short sources

# FFmpeg 列设备（Linux 常用 alsa，macOS 常用 avfoundation）
ffmpeg -f alsa -list_devices true -i ''
# macOS: ffmpeg -f avfoundation -list_devices true -i ''

如果采集模块基于 Python 音频库，用库自己的枚举更贴近实际运行时的设备编号：

# sounddevice 设备枚举骨架
import sounddevice as sd
print(sd.query_devices())
print('default input:', sd.default.device)

# PyAudio 设备枚举骨架
import pyaudio
pa = pyaudio.PyAudio()
for i in range(pa.get_device_count()):
    info = pa.get_device_info_by_index(i)
    print(i, info.get('name'), info.get('maxInputChannels'), info.get('defaultSampleRate'))

判断方式：输入设备列表里有预期设备，且 default input 指向它，通道数和默认采样率与话筒或声卡标称一致。如果列表为空、名字是占位设备，或者打开时报权限错误，先处理设备与权限，不要带着这个前提往下走。设备名后面要写进配置，建议原样复制。

用一段已知采样率的音频喂给驱动模块

设备能被列出，不等于音频块能按预期进入程序。用一段自己生成的音频最省事：采样率、通道数、时长都是已知的，出问题时容易判断是驱动丢块，还是程序没读到。

# 生成 2 秒 16kHz 单声道正弦波，写入 wav
import numpy as np
import soundfile as sf

sr = 16000
t = np.arange(sr * 2) / sr
wave = (0.2 * np.sin(2 * np.pi * 440 * t)).astype('float32')
sf.write('probe_16k.wav', wave, sr, subtype='PCM_16')

# 按固定块长喂给驱动入口
data, sr = sf.read('probe_16k.wav', dtype='float32')
print('loaded', sr, data.shape)
block = 1600  # 100ms
for i in range(0, len(data), block):
    chunk = data[i:i + block]
    # 替换成实际的驱动写入或回调入口
    drive_handle.feed(chunk)
    print(f't={i / sr:.3f} sr={sr} frames={len(chunk)}')

也可以不用 wav 文件，直接在代码里构造块，例如 np.zeros((1600, 1), dtype='float32') 按固定间隔送入，边界更清楚。日志里建议能看到采样率、块序号或时间戳字段，例如 sample_rate=16000、chunk=12、ts=1.200。字段名以所用仓库的日志格式为准，先用管道过滤看有没有这类字段。

驱动日志关键字清单可以先按下面几组词抓，命中后再看上下文，不要只看单个词：

• 设备相关：device、device_name、input、opened、closed、permission
• 音频格式：sample_rate、samplerate、channels、blocksize、chunk、frames、dtype
• 时间推进：ts、timestamp、pts、frame_index、seq
• 异常迹象：underrun、overflow、drop、late、timeout、queue full

验证标准是：同一采样率与时间戳字段连续出现，没有频繁跳变或中断。可以先跑 grep -E 'sample_rate|ts|chunk' audio.log 看它是不是在循环打印。

在驱动日志稳定后再启动模型推理模块

音频驱动日志跑起来并保持一段时间后，再启动推理。这样模型加载失败、权重路径错误、显存不足这类问题会单独暴露，而不是把驱动层没声音的问题掩盖掉。多数实时数字人仓库会提供只跑音频或只做推理的入口，具体参数名以仓库为准，先在启动脚本或帮助信息里确认。

# 只跑音频链路，参数名以仓库实际为准
python main.py `--audio-only` `--config` configs/local.yaml
python realtime.py `--no-render` `--audio-device` '你的输入设备名'

# 不确定参数时先看帮助
python main.py `--help`

启动推理后，回头观察音频采集那段日志是否还在继续推进。如果推理一加载，驱动日志就停住或报错，优先按上一节重新验证音频块，而不是去调模型参数。反过来，如果驱动日志正常、推理日志停在权重加载或显存申请，再处理模型侧。这样来回对照，能把两段链路的边界划清楚。

最后启动渲染模块并检查帧输出

渲染放在最后开。渲染单独启动，或者先用配置项把它关掉，能让画面卡住的原因收敛到推理输出和渲染参数上。常见做法是配置里关渲染、命令行加开关，或者单独跑一个渲染进程消费推理结果，字段名以仓库为准。

# 配置项骨架，字段名以仓库为准
render:
  enabled: false      # 先关渲染，跑通前两段
  fps: 25
  output: out.mp4     # 也可能是 window / rtsp 等

# 命令行骨架
python main.py `--config` configs/local.yaml `--no-render`
python main.py `--config` configs/local.yaml `--render-only`

打开渲染后，检查输出窗口是否刷新，或者输出视频文件是否在增长。可以看文件大小和最后写入时间，也可以看渲染日志里的帧序号、分辨率、fps 字段是否递增。如果渲染帧号不动，而音频驱动和推理日志都正常，问题基本落在渲染模块及其输入上；如果三边都不动，回到音频块那一步重来。

把三段日志按时间戳拼起来定位断点

分段跑通之后通常还会一起启动。这时用重定向把三段日志分文件保存，再按时间戳对齐，找“第一个不再输出的模块”比翻混合日志快得多。Python 建议加 -u 避免缓冲，管道和 tee 也要留意缓冲，否则日志会延迟出现，误导先后顺序的判断。

# 分开跑、分开记日志
python audio_capture.py -u 2>&1 | tee audio.log
python infer.py         -u 2>&1 | tee infer.log
python render.py        -u 2>&1 | tee render.log

# 合跑时先整体留一份
python main.py 2>&1 | tee full.log
# 只看驱动关键字
grep -E 'sample_rate|chunk|ts|underrun' audio.log | tail -n 50

比对方式是：在各段日志里找到最后一次推进的时间戳，正常情况下三段应该交替或按顺序出现。如果 audio.log 在某个时间点之后再无新行，而 infer.log、render.log 还在报错或空转，断点就在音频采集；如果音频日志持续到结束、推理日志停在加载或首帧输出，断点就在推理；三段日志都正常刷新但画面不动，再回到渲染输出这一层。日志时间戳的精度和格式各仓库不同，比对时以同一进程内的相对时间为主，跨进程只看先后顺序。每次只改一段的配置，改完重新按顺序启动，避免把新引入的问题和原问题混在一起。