HarmonyOS 7 音频配件输入流怎么对齐时延：20ms 写入、帧位置与单调时钟

蓝牙麦克风、USB 声卡或其他音频配件接入后，最难排查的故障通常不是“完全没有数据”，而是声音慢半拍、时间戳偶尔倒退，或者停止后再次启动就持续返回非法状态。只盯着写入函数，很容易把生命周期、帧格式和时钟基准混成一个问题。

HarmonyOS 7 的 API 26 新增音频配件输入流管理接口。官方约束很具体：输入流相关回调需要在打开输入流回调执行期间注册；每次写入必须是一整帧 20ms 数据；帧位置时间戳使用 CLOCK_MONOTONIC，单位为纳秒；同一输入流不支持并发写入。这四条需要作为一个协议实现，少一条都可能在边界状态出错。

证据边界：本文依据华为开发者官网 2026-08-29 更新的 API 26 C API 文档整理。当前本机 DevEco SDK 为 API 24，且没有连接 HDC 真机，不能宣称本文已经完成 API 26 编译或配件真机实测。文中的帧长计算、时间戳单调性、状态机和写入决策已用宿主逻辑测试；正式接入仍需使用 API 26 SDK、真实配件和目标机型验证。

先看清楚五个回调的职责

打开输入流时，系统把流句柄和格式交给配件侧。应用要在这个窗口内注册启动、停止、释放、时延查询和帧位置查询回调。启动回调返回后才可以写数据；停止回调返回后应停止写入，但句柄仍可再次启动；释放回调是最后一次通知，返回后句柄不再有效。

bool OnOpen(OH_AudioAccessory* accessory,
            OH_AudioAccessoryInputStream* stream,
            OH_AudioStreamInfo* streamInfo) {
  bool ok = true;
  ok &= RegisterStart(stream);
  ok &= RegisterStop(stream);
  ok &= RegisterRelease(stream);
  ok &= RegisterLatency(stream);
  ok &= RegisterFramePosition(stream);
  return ok && ValidateFormat(streamInfo);
}

这里用包装函数省略了具体返回码处理，目的不是替代官方签名，而是突出注册必须完整且发生在正确窗口。工程实现应逐项检查 OH_AudioCommon_Result；任何一项失败都不要继续把流标记为可用。

20ms 完整帧到底有多少字节

写入接口要求每次提交当前格式下完整的 20ms 数据，不支持部分帧。需要的字节数取决于采样率、声道数和单采样字节数。

int64_t BytesPer20Ms(int32_t sampleRate,
                     int32_t channels,
                     int32_t bytesPerSample) {
  if (sampleRate <= 0 || sampleRate % 50 != 0) return -1;
  if (channels <= 0 || bytesPerSample <= 0) return -1;
  return static_cast<int64_t>(sampleRate / 50) * channels * bytesPerSample;
}

例如 48kHz、双声道、16 位 PCM，一帧 20ms 包含 960 个采样时刻，需要 960 x 2 x 2 = 3840 字节。若最后一块不足 20ms，官方给出的选择是丢弃或补零到完整帧，再调用写入接口。

错误做法	直接结果	正确处理
固定写 4096 字节	格式变化后长度不匹配	按流格式计算完整帧
拆成两次各写一半	接口不支持部分帧	在业务缓冲区拼成完整帧
两个线程同时写	同一流不支持并发写入	单写线程串行提交
看到可写空间就永久缓存	查询结果会立刻变化	仅作为当次写入前的提示

案例一：系统时间被校准后，时间戳突然倒退

配件驱动把当前墙上时间写给帧位置回调。设备自动校时后，下一帧时间戳比上一帧更小，录音波形出现重叠，后续音画同步也开始漂移。问题不在采样帧本身，而是使用了会被校准的时钟。

帧位置回调中的时间戳必须基于 CLOCK_MONOTONIC，表示采集到对应帧位置的时间点。它不应该受时区、手动改时间或网络校时影响。

struct FrameClock {
  int64_t framePosition;
  int64_t timestampNs;
};

bool AcceptFrameClock(const FrameClock& previous,
                      const FrameClock& current) {
  return current.framePosition >= previous.framePosition &&
         current.timestampNs >= previous.timestampNs;
}

复现时可以给宿主测试输入三组数据：正常递增、时间戳倒退、帧位置倒退。后两组都应被拒绝并记录错误，但不能自动改成上一帧时间戳后继续假装正常。真机验收还要手动修改系统时间，确认采集时间线不受影响。

案例二：停止后写线程还在跑，再启动一直报非法状态

输入流收到停止回调后，消费线程已经停了，业务写线程却还在每 20ms 提交数据。更危险的是释放回调返回后，旧线程仍持有失效句柄。偶发问题通常出现在快速停止、立即重启，或设备拔出时。

不要只保存一个 isRunning 布尔值。给每次启动分配世代号，写任务执行前同时检查状态和世代；停止使当前世代失效，释放后再清空句柄。

enum class StreamState { Opened, Started, Stopped, Released };

bool CanWrite(StreamState state,
              uint64_t currentGeneration,
              uint64_t taskGeneration) {
  return state == StreamState::Started &&
         currentGeneration == taskGeneration;
}

第一组复现：启动后排队三个写任务，第二个任务执行前触发停止。预期第二、三个任务被本地状态机拦截。第二组复现：停止后再次启动，世代号递增；旧任务即使晚到，也不能写进新会话。

时延值、帧位置和写入节奏怎么联合验收

时延回调返回毫秒，帧位置时间戳返回纳秒，二者单位不同，不能直接相减。建议统一转成纳秒后只做观测，不在回调里临时修改配件节奏。连续写入间隔应接近 20ms，但 Windows 或普通宿主定时器不能作为真机实时性证据。

每次验收至少保留以下字段：流世代号、状态、帧位置、单调时间戳、时延毫秒值、计划写入字节数、实际返回码、写入耗时。不要记录用户原始音频数据。

type Sample = { frame: number; timestampNs: bigint; latencyMs: number };

function captureTimeNs(sample: Sample): bigint {
  return sample.timestampNs - BigInt(sample.latencyMs) * 1_000_000n;
}

这只是对齐观测时间的纯函数，不是官方 API。若时延值变化剧烈，应先确认配件报告是否稳定，再决定业务层是否需要平滑展示；不能静默篡改系统要求返回的数据。

可复用封装应该卡住哪些错误

可以把输入流包装为一个小型适配器：OnOpen 内完成全部回调注册和格式校验；OnStart 创建唯一写入世代；单写线程按 20ms 完整帧提交；OnStop 先阻止新任务，再等待在途写入收口；OnRelease 最后清空句柄。适配器对上层只暴露可解释结果：格式不支持、注册不完整、帧长不匹配、状态非法、服务异常。

这种封装可以复用到会议麦克风、直播声卡和助听配件，但不能假设所有配件都使用同一种采样率、声道数和固定时延。可复用的是生命周期与证据模型，不是写死的设备参数。

上线前检查清单

• 五类输入流回调都在打开回调期间注册并检查返回码。
• 每次写入严格等于当前格式的一整帧 20ms 数据。
• 同一输入流只有一个串行写入线程。
• 帧位置和时间戳都单调递增，时间戳使用 CLOCK_MONOTONIC。
• 停止后不再写，释放后任何旧任务都不能使用句柄。
• 快速停止重启、配件拔出、服务异常和格式变化都有回归用例。
• 日志只记录状态、规模、耗时和返回码，不保存原始音频。

官方资料

• native_audio_accessory_input_stream_manager.h
• Audio Kit（音频服务）
• Audio Kit 常见问题

API 26 的新接口并不只是多了几个回调。它把配件侧必须承担的完整生命周期、20ms 帧协议和时间基准写得很清楚。先把这三层做成可验证协议，音频慢半拍、重启失效和偶发非法状态才不会继续靠猜。