低时延音频播放(C/C++)
==============

从API version 10开始支持低时延音频播放。

低时延音频播放是一种通过软硬芯协同设计实现的音频渲染方案。其核心机制是通过减少buffer大小、优化读写数据架构，使该模式下音频播放具有更低的时延。

#### 使用前提

*   支持低时延模式的音频输出设备。
*   可通过[OH\_AudioRenderer\_GetFastStatus()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-audiorenderer-h#oh_audiorenderer_getfaststatus)验证当前设备是否支持低时延模式。

#### 开发指导

以下各步骤示例为片段代码，可通过示例代码右下方链接获取[完整示例](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/Media/Audio/AudioRendererSampleC)。

#### \[h2\]简介

为使用低时延模式，开发者需要参考[推荐使用OHAudio开发音频播放功能(C/C++)](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/using-ohaudio-for-playback)进行音频开发。

当前OHAudio支持两种模式：普通模式（AUDIOSTREAM\_LATENCY\_MODE\_NORMAL）和低时延模式（AUDIOSTREAM\_LATENCY\_MODE\_FAST）。

#### \[h2\]设置低时延模式

开发者通过调用[OH\_AudioStreamBuilder\_SetLatencyMode()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-audiostreambuilder-h#oh_audiostreambuilder_setlatencymode)，设置[OH\_AudioStream\_LatencyMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-audiostream-base-h#oh_audiostream_latencymode)来决定音频流使用的模式。

设置低时延模式开发示例：

OH\_AudioStream\_LatencyMode latencyMode = AUDIOSTREAM\_LATENCY\_MODE\_FAST;
OH\_AudioStreamBuilder\_SetLatencyMode(builder, latencyMode);

针对OHAudio开发音频播放，有以下相关实例可供参考：

*   [OHAudio录制和播放](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/DocsSample/Media/Audio/OHAudio)。

#### 注意事项

#### \[h2\]低时延模式限制

在以下场景中，即使设置了低时延模式，系统仍会使用普通模式。

*   当前设备不支持低时延模式。
*   当前流格式不支持低时延模式。
*   系统低时延资源已被全部占用。
*   当前系统中存在更高优先级流（如：蜂窝通话）。

从API version 20开始，支持低时延相关查询接口。

*   开发者通过调用[OH\_AudioRenderer\_GetFastStatus()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-audiorenderer-h#oh_audiorenderer_getfaststatus)来获取音频播放流是否正在低时延状态下工作。
*   在部分特殊场景（如：存在更高优先级流、当前连接设备不支持等）下，开发者可以通过调用[OH\_AudioRenderer\_OnFastStatusChange()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-audiorenderer-h#oh_audiorenderer_onfaststatuschange)来获取低时延状态改变事件。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/83/v3/kKNRn_VkR6u_B9RTho-HQA/caution_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073504Z&HW-CC-Expire=86400&HW-CC-Sign=2F6581657CA127180D51EAA83474CD11AEC86AC66EDA4ECD810326DE27CCA5AB)

低时延模式下，不支持调整播放速度。

#### \[h2\]使用低时延流的场景

*   游戏、k歌、直播等对时延要求较高的场景，建议使用低时延模式。
*   视频播放、音乐播放等没有实时要求的场景，不建议使用低时延模式。

#### \[h2\]确保数据及时提供

低时延模式下，应用提供数据的频次比普通播放模式高，如果传送数据不及时可能导致杂音等问题。开发者应避免在数据回调线程中做耗时操作，确保数据回调线程可以及时返回。

#### \[h2\]数据回调线程

播放的音频数据需要通过回调接口写入。开发者要实现回调接口，使用[OH\_AudioStreamBuilder\_SetRendererWriteDataCallback](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-audiostreambuilder-h#oh_audiostreambuilder_setrendererwritedatacallback)设置写入音频数据的回调函数，在设置音频回调函数时，回调函数[OH\_AudioRenderer\_OnWriteDataCallback](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-audiostream-base-h#oh_audiorenderer_onwritedatacallback)（从API version 12开始支持）用于写入音频数据。

开发音频播放功能的示例代码请参考：[推荐使用OHAudio开发音频播放功能(C/C++)](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/using-ohaudio-for-playback)。

设置数据回调函数示例：

// 自定义写入数据函数。
static OH\_AudioData\_Callback\_Result MyOnWriteData\_New(
    OH\_AudioRenderer\* renderer,
    void\* userData,
    void\* audioData,
    int32\_t audioDataSize)
{
    // 将待播放的数据，按audioDataSize长度写入audioData。
    // 如果开发者不希望播放某段audioData，返回AUDIO\_DATA\_CALLBACK\_RESULT\_INVALID即可。
    int32\_t readCount = fread(audioData, audioDataSize, 1, g\_fp);
    if (readCount < 0) {
        return AUDIO\_DATA\_CALLBACK\_RESULT\_INVALID;
    }
    if (feof(g\_fp)) {
        fseek(g\_fp, 0, SEEK\_SET);
    }
    return AUDIO\_DATA\_CALLBACK\_RESULT\_VALID;
}
// ...
    // 配置写入音频数据回调函数。
    OH\_AudioRenderer\_OnWriteDataCallback writeDataCb = MyOnWriteData\_New;
    OH\_AudioStreamBuilder\_SetRendererWriteDataCallback(builder, writeDataCb, nullptr);

*   为避免音频卡顿，禁止在回调方法OH\_AudioRenderer\_OnWriteData中执行耗时操作。
    
*   为保证OH\_AudioRenderer\_OnWriteData与流状态控制逻辑独立正常运行，禁止在OH\_AudioRenderer\_OnWriteData回调方法中调用音频流控制接口。
    
    | 音频流控制接口 | 说明 |
    | :-- | :-- |
    | OH\_AudioStream\_Result OH\_AudioRenderer\_Start(OH\_AudioRenderer\* renderer) | 开始播放。 |
    | OH\_AudioStream\_Result OH\_AudioRenderer\_Pause(OH\_AudioRenderer\* renderer) | 暂停播放。 |
    | OH\_AudioStream\_Result OH\_AudioRenderer\_Stop(OH\_AudioRenderer\* renderer) | 停止播放。 |
    | OH\_AudioStream\_Result OH\_AudioRenderer\_Flush(OH\_AudioRenderer\* renderer) | 释放缓存数据。 |
    | OH\_AudioStream\_Result OH\_AudioRenderer\_Release(OH\_AudioRenderer\* renderer) | 释放播放实例。 |
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e4/v3/Ea7eYYJyRfOV8a8FutdwPw/caution_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073504Z&HW-CC-Expire=86400&HW-CC-Sign=48FCC557E3D8A62ED48ACB091DFFEB23597CFA1F9A70D12CC69DE26F1028D4AF)
    
    音频流控制接口执行会有耗时（例如OH\_AudioRenderer\_Stop接口需要播完缓存，单次执行普遍超过50ms），应避免在主线程中直接调用，以免造成界面显示卡顿。