openharmony 鸿蒙 capi-native-audio-converter-h

2026-08-25 浏览 (1)

native_audio_converter.h

概述

声明输入音频格式、输出音频格式底层数据结构和格式转换接口的定义。

引用文件： <ohaudiosuite/native_audio_converter.h>

库： libohaudiosuite.so

系统能力： SystemCapability.Multimedia.Audio.SuiteEngine

起始版本： 26.0.0

相关模块： AudioConverter

汇总

结构体

名称typedef关键字描述
OH_AudioConverter_FormatOH_AudioConverter_Format定义音频转换器格式数据结构，用于描述基本音频格式。
OH_AudioConverterStructOH_AudioConverter声明音频格式转换器。
音频转换器的句柄用于执行与音频转换器相关的功能。

枚举

名称typedef关键字描述
OH_AudioConverter_ResultOH_AudioConverter_Result定义函数执行的返回结果。
OH_AudioConverter_InputStatusOH_AudioConverter_InputStatus定义回调函数OH_AudioConverter_RequestDataCallback提供的输入音频数据的状态。转换器使用此状态来确定如何处理后续的转换逻辑。例如，继续提取数据，暂停或清除缓存数据。
注意：即使回调返回AUDIOCONVERTER_INPUT_DATA_FINISHED，也必须重复调用OH_AudioConverter_Process，直到OH_AudioConverter_Process返回AUDIOCONVERTER_SUCCESS，并且outputSize=0（表示所有缓存数据均已处理完成）。

函数

名称typedef关键字描述
OH_AudioConverter_Result OH_AudioConverter_Create(const OH_AudioConverter_Format* inputFormat, const OH_AudioConverter_Format* outputFormat, OH_AudioConverter** converter)-创建音频转换器。
void OH_AudioConverter_Destroy(OH_AudioConverter* converter)-请求释放转换器。
typedef int32_t (*OH_AudioConverter_RequestDataCallback)(void* userData, const void** outInputData, OH_AudioConverter_InputStatus* outStatus)OH_AudioConverter_RequestDataCallback请求数据的回调函数。转换器在OH_AudioConverter_Process期间调用此回调函数以主动请求输入音频数据。
调用者必须填充输出参数（outInputData，outStatus），并返回通过回调函数读取的数据大小。
单个回调返回的最大数据大小为400KB。
outInputData指向的内存必须保持有效，直到OH_AudioConverter_Process返回处理完成为止。
OH_AudioConverter_Result OH_AudioConverter_SetInputCallback(OH_AudioConverter* converter, OH_AudioConverter_RequestDataCallback callback, void* userData)-设置转换器请求数据回调函数。此函数绑定音频转换器的输入数据回调函数。回调函数由OH_AudioConverter_Process调用，获取输入音频数据并进行处理。
OH_AudioConverter_Result OH_AudioConverter_Process(OH_AudioConverter* converter, void* outputData, int32_t outputCapacity, int32_t* outputSize)-执行音频格式转换处理函数。该函数执行音频转换过程，将输入音频转换为目标格式，需要注意：该函数必须在OH_AudioConverter_SetInputCallback之后调用，并且最终转换结果写入的输出缓冲区必须由调用方分配和管理。

枚举类型说明

OH_AudioConverter_Result

enum OH_AudioConverter_Result

描述

定义函数执行的返回结果。

起始版本： 26.0.0

枚举项描述
AUDIOCONVERTER_SUCCESS = 0调用成功。
起始版本： 26.0.0
AUDIOCONVERTER_ERROR_INVALID_PARAM = 1函数输入参数无效。
起始版本： 26.0.0
AUDIOCONVERTER_ERROR_UNSUPPORTED_FORMAT = 2不支持的音频格式。例如不支持的编码类型、采样格式等。
起始版本： 26.0.0
AUDIOCONVERTER_ERROR_SYSTEM = 3系统通用错误。
起始版本： 26.0.0
AUDIOCONVERTER_ERROR_MEMORY_ALLOC_FAILED = 4内存分配失败。
起始版本： 26.0.0
AUDIOCONVERTER_ERROR_BUFFER_TOO_SMALL = 5缓冲容量不足。
起始版本： 26.0.0
AUDIOCONVERTER_ERROR_NOT_INITIALIZED = 6音频转换器实例未初始化。
起始版本： 26.0.0
AUDIOCONVERTER_ERROR_CALLBACK_INVALID = 7回调函数无效。
起始版本： 26.0.0
AUDIOCONVERTER_ERROR_CALLBACK_NOT_SET = 8未设置回调函数。
起始版本： 26.0.0

OH_AudioConverter_InputStatus

enum OH_AudioConverter_InputStatus

描述

定义回调函数OH_AudioConverter_RequestDataCallback提供的输入音频数据的状态。转换器使用此状态来确定如何处理后续的转换逻辑。例如，继续提取数据，暂停或清除缓存数据。
注意：即使回调返回AUDIOCONVERTER_INPUT_DATA_FINISHED，也必须重复调用OH_AudioConverter_Process，直到OH_AudioConverter_Process返回AUDIOCONVERTER_SUCCESS，并且outputSize=0（表示所有缓存数据均已处理完成）。

起始版本： 26.0.0

枚举项描述
AUDIOCONVERTER_INPUT_HAVE_DATA = 1提供的输入数据有效。
AUDIOCONVERTER_INPUT_NO_AVAILABLE_DATA = 2暂时没有可用的输入数据。
AUDIOCONVERTER_INPUT_DATA_FINISHED = 3输入数据流已完成。

函数说明

OH_AudioConverter_Create()

OH_AudioConverter_Result OH_AudioConverter_Create(const OH_AudioConverter_Format* inputFormat, const OH_AudioConverter_Format* outputFormat, OH_AudioConverter** converter)

描述

创建音频转换器。

说明：

  • 此函数创建的转换器实例必须通过OH_AudioConverter_Destroy的显式方式销毁。
  • 支持的音频格式规范（适用于输入/输出）： 该转换器仅支持PCM（脉冲编码调制）音频格式。
  • 支持采样率：8000 Hz、11025 Hz、12000 Hz、16000 Hz、22050 Hz、24000 Hz、32000 Hz、44100 Hz、48000 Hz、 64000 Hz、88200 Hz、96000 Hz、176400 Hz和192000 Hz。
  • 支持声道布局：CH_LAYOUT_MONO、CH_LAYOUT_STEREO、CH_LAYOUT_STEREO_DOWNMIX、 CH_LAYOUT_2POINT1、CH_LAYOUT_3POINT0、CH_LAYOUT_SURROUND、CH_LAYOUT_3POINT1、CH_LAYOUT_4POINT0、CH_LAYOUT_QUAD_SIDE、 CH_LAYOUT_QUAD、CH_LAYOUT_2POINT0POINT2、CH_LAYOUT_4POINT1、CH_LAYOUT_5POINT0、CH_LAYOUT_5POINT0_BACK、 CH_LAYOUT_2POINT1POINT2、CH_LAYOUT_3POINT0POINT2、CH_LAYOUT_5POINT1、CH_LAYOUT_5POINT1_BACK、CH_LAYOUT_6POINT0、 CH_LAYOUT_3POINT1POINT2、CH_LAYOUT_6POINT0_FRONT、CH_LAYOUT_HEXAGONAL、CH_LAYOUT_6POINT1、CH_LAYOUT_6POINT1_BACK、 CH_LAYOUT_6POINT1_FRONT、CH_LAYOUT_7POINT0、CH_LAYOUT_7POINT0_FRONT、CH_LAYOUT_7POINT1、CH_LAYOUT_OCTAGONAL、 CH_LAYOUT_5POINT1POINT2、CH_LAYOUT_7POINT1_WIDE和CH_LAYOUT_7POINT1_WIDE_BACK。
  • 支持采样格式（位深）：SAMPLE_U8 （Unsigned 8位 PCM）、 SAMPLE_S16LE（Short 16位小端 PCM）、SAMPLE_S24LE（Short 24位小端 PCM）、 SAMPLE_S32LE（Short 32位小端 PCM）和SAMPLE_F32LE（Float 32位小端 PCM）。

起始版本： 26.0.0

参数：

参数项描述
const OH_AudioConverter_Format* inputFormat配置指向输入音频格式的指针。
inputFormat配置指向输入音频格式的指针。
const OH_AudioConverter_Format* outputFormat配置指向输出音频格式的指针。
OH_AudioConverter** converter指向可用的音频转换器的指针。

返回：

类型说明
OH_AudioConverter_ResultAUDIOCONVERTER_SUCCESS：函数执行成功。
AUDIOCONVERTER_ERROR_INVALID_PARAM：输入参数无效。
AUDIOCONVERTER_ERROR_UNSUPPORTED_FORMAT：音频输入/输出格式组合不支持。
AUDIOCONVERTER_ERROR_MEMORY_ALLOC_FAILED：内存分配失败。
AUDIOCONVERTER_ERROR_SYSTEM：如果系统存在内存分配失败等其他异常情况。

OH_AudioConverter_Destroy()

void OH_AudioConverter_Destroy(OH_AudioConverter* converter)

描述

请求释放转换器。

起始版本： 26.0.0

参数：

参数项描述
OH_AudioConverter* converter由OH_AudioConverter_Create函数创建的转换器。

OH_AudioConverter_RequestDataCallback()

typedef int32_t (*OH_AudioConverter_RequestDataCallback)(void* userData, const void** outInputData, OH_AudioConverter_InputStatus* outStatus
)

描述

请求数据的回调函数。转换器在OH_AudioConverter_Process期间调用此回调函数以主动请求输入音频数据。
调用者必须填充输出参数（outInputData，outStatus），并返回通过回调函数读取的数据大小。
单个回调返回的最大数据大小为400KB。
outInputData指向的内存必须保持有效，直到OH_AudioConverter_Process返回处理完成为止。

起始版本： 26.0.0

参数：

参数项描述
void* userData传递给回调函数的用户自定义数据。
const void** outInputData指向回调函数设置的指向输入音频数据缓冲区的指针。
OH_AudioConverter_InputStatus* outStatus通过回调函数设置，以通知转换器数据流状态是否可用。

返回：

类型说明
int32_t通过outInputData指针指向有效的输入数据的大小。

OH_AudioConverter_SetInputCallback()

OH_AudioConverter_Result OH_AudioConverter_SetInputCallback(OH_AudioConverter* converter, OH_AudioConverter_RequestDataCallback callback, void* userData
)

描述

设置转换器请求数据回调函数。此函数绑定音频转换器的输入数据回调函数。回调函数由OH_AudioConverter_Process调用，获取输入音频数据并进行处理。

起始版本： 26.0.0

参数：

参数项描述
OH_AudioConverter* converter由OH_AudioConverter_Create函数创建转换器。
OH_AudioConverter_RequestDataCallback callback回调函数用于写入音频数据。
userData指向将传递给回调函数的应用程序数据结构的指针。

返回：

类型说明
OH_AudioConverter_ResultAUDIOCONVERTER_SUCCESS：如果执行成功。
AUDIOCONVERTER_ERROR_INVALID_PARAM：如果参数无效，例如转换器指针为nullptr等。
AUDIOCONVERTER_ERROR_NOT_INITIALIZED：如果转换器实例未初始化。
AUDIOCONVERTER_ERROR_CALLBACK_INVALID：如果回调函数无效，例如回调函数返回无效等。
AUDIOCONVERTER_ERROR_SYSTEM：如果系统存在内存分配失败的异常情况。

OH_AudioConverter_Process()

OH_AudioConverter_Result OH_AudioConverter_Process(OH_AudioConverter* converter, void* outputData, int32_t outputCapacity, int32_t* outputSize
)

描述

执行音频格式转换处理函数。该函数执行音频转换过程，将输入音频转换为目标格式，需要注意：该函数必须在OH_AudioConverter_SetInputCallback之后调用，并且最终转换结果写入的输出缓冲区必须由调用方分配和管理。

起始版本： 26.0.0

参数：

参数项描述
OH_AudioConverter* converter由OH_AudioConverter_Create函数创建转换器。
void* outputData指向调用者分配的输出缓冲区的指针。
int32_t outputCapacity调用者指定的输出缓冲区大小。
outputSize系统实际写入输出缓冲区数据的大小。

返回：

类型说明
OH_AudioConverter_ResultAUDIOCONVERTER_SUCCESS：如果执行成功。
AUDIOCONVERTER_ERROR_INVALID_PARAM：如果参数无效，例如转换器指针为nullptr等。
AUDIOCONVERTER_ERROR_NOT_INITIALIZED：如果转换器实例未初始化。
AUDIOCONVERTER_ERROR_CALLBACK_INVALID：如果回调函数无效，例如回调函数返回了无效值等。
AUDIOCONVERTER_ERROR_CALLBACK_NOT_SET：转换器未绑定任何输入回调函数。
AUDIOCONVERTER_ERROR_BUFFER_TOO_SMALL：输出缓冲区容量不足。
AUDIOCONVERTER_ERROR_SYSTEM：如果系统存在调用底层转换函数失败和内存分配失败的异常情况。

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 capi-native-audiostreambuilder-h

openharmony 鸿蒙 capi-ohaudiosuite

openharmony 鸿蒙 js-apis-inner-multimedia-systemSoundPlayer

openharmony 鸿蒙 arkts-apis-audio-i

openharmony 鸿蒙 capi-ohaudio

openharmony 鸿蒙 capi-ohmidi

openharmony 鸿蒙 arkts-apis-audio-AudioManager

openharmony 鸿蒙 capi-ohaudiosuite-oh-audiosuite-spacerenderpositionparams

openharmony 鸿蒙 capi-ohaudio-oh-audiostreaminfo

openharmony 鸿蒙 capi-ohmidi-oh-midideviceinformation

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/uSkdHKWV