1# 使用OpenSL ES开发音频录制功能(C/C++) 2<!--Kit: Audio Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @songshenke--> 5<!--Designer: @caixuejiang; @hao-liangfei; @zhanganxiang--> 6<!--Tester: @Filger--> 7<!--Adviser: @zengyawen--> 8 9OpenSL ES全称为Open Sound Library for Embedded Systems，是一个嵌入式、跨平台、免费的音频处理库。为嵌入式移动多媒体设备上的应用开发者提供标准化、高性能、低延迟的API。OpenHarmony的Native API基于[Khronos Group](https://www.khronos.org/)开发的[OpenSL ES](https://www.khronos.org/opensles/) 1.0.1 API 规范实现，开发者可以通过<OpenSLES.h>和<OpenSLES_OpenHarmony.h>在OpenHarmony上使用相关API。 10 11## 使用OHAudio替代OpenSL ES 12OpenHarmony上的OpenSL ES接口，是早期SDK8版本开始提供，用于支持应用Native层音频开发的接口。但随着版本演进，接口定义的可扩展性不足，不再能满足音频系统的能力拓展，因此当前已不再推荐应用开发者继续使用此接口进行音频功能开发，可能存在一些接口能力不足的缺陷。 13 14在SDK10版本，OpenHarmony推出了OHAudio接口，并将系统具备的所有音频功能都通过此接口开放。OHAudio接口已能够覆盖OpenSL ES在OpenHarmony中已提供的所有能力，并拓展支持音频焦点事件，低时延等新版本特性。 15 16OHAudio的开发指南见[使用OHAudio开发音频录制功能(C/C++)](using-ohaudio-for-recording.md)。 17 18考虑到一些接入OpenHarmony较早的应用开发者，这里提供了一份OpenSL ES接口切换到OHAudio的对照参考[OpenSL ES接口切换OHAudio参考](replace-opensles-by-ohaudio.md)，便于开发者能够更快的在新版本切换到使用新接口。 19 20## OpenHarmony上的OpenSL ES 21 22OpenSL ES中提供了以下的接口，OpenHarmony当前仅实现了部分[接口](https://gitee.com/openharmony/third_party_opensles/blob/master/api/1.0.1/OpenSLES.h)，可以实现音频录制的基础功能。 23 24调用未实现接口后会返回**SL_RESULT_FEATURE_UNSUPPORTED，**当前没有相关扩展可以使用。 25 26以下列表列举了OpenHarmony上已实现的OpenSL ES的接口，具体说明请参考[OpenSL ES](https://www.khronos.org/opensles/)规范： 27 28- **OpenHarmony上支持的SLInterfaceID：** 29 30 | SLInterfaceID | 说明 | 31 | -------- | -------- | 32 | SL_IID_ENGINE | 通用引擎，提供创建录音对象接口。 | 33 | SL_IID_RECORD | 提供录音状态接口。 | 34 | SL_IID_OH_BUFFERQUEUE | 提供音频录制流数据回调注册接口。 | 35 36- **OpenHarmony上支持的Engine接口：** 37 - SLresult (\*CreateAudioPlayer) (SLEngineItf self, SLObjectItf \* pPlayer, SLDataSource \*pAudioSrc, SLDataSink \*pAudioSnk, SLuint32 numInterfaces, const SLInterfaceID \* pInterfaceIds, const SLboolean \* pInterfaceRequired) 38 - SLresult (\*CreateAudioRecorder) (SLEngineItf self, SLObjectItf \* pRecorder, SLDataSource \*pAudioSrc, SLDataSink \*pAudioSnk, SLuint32 numInterfaces, const SLInterfaceID \* pInterfaceIds, const SLboolean \* pInterfaceRequired) 39 - SLresult (\*CreateOutputMix) (SLEngineItf self, SLObjectItf \* pMix, SLuint32 numInterfaces, const SLInterfaceID \* pInterfaceIds, const SLboolean \* pInterfaceRequired) 40 41- **OpenHarmony上支持的Object接口：** 42 - SLresult (\*Realize) (SLObjectItf self, SLboolean async) 43 - SLresult (\*GetState) (SLObjectItf self, SLuint32 \* pState) 44 - SLresult (\*GetInterface) (SLObjectItf self, const SLInterfaceID iid, void \* pInterface) 45 - void (\*Destroy) (SLObjectItf self) 46 47- **OpenHarmony上支持的Recorder接口：** 48 - SLresult (\*SetRecordState) (SLRecordItf self, SLuint32 state) 49 - SLresult (\*GetRecordState) (SLRecordItf self,SLuint32 \*pState) 50 51- **OpenHarmony上支持的BufferQueue接口：** 52 53 以下接口需引入<OpenSLES_OpenHarmony.h>使用。 54 55 | 接口 | 说明 | 56 | -------- | -------- | 57 | SLresult (\*Enqueue) (SLOHBufferQueueItf self, const void \*buffer, SLuint32 size) | 根据情况将buffer加到相应队列中。<br/>如果是播放操作，则将带有音频数据的buffer插入到filledBufferQ_队列中；如果是录音操作，则将录音使用后的空闲buffer插入到freeBufferQ_队列中。<br/>self：表示调用该函数的BufferQueue接口对象。<br/>buffer：播放时表示带有音频数据的buffer，录音时表示已存储完录音数据后的空闲buffer。<br/>size：表示buffer的大小。 | 58 | SLresult (\*Clear) (SLOHBufferQueueItf self) | 释放BufferQueue接口对象。<br/>self：表示调用该函数的BufferQueue接口对象将被释放。 | 59 | SLresult (\*GetState) (SLOHBufferQueueItf self, SLOHBufferQueueState \*state) | 获取BufferQueue接口对象状态。<br/>self：表示调用该函数的BufferQueue接口对象。<br/>state：BufferQueue的当前状态。 | 60 | SLresult (\*RegisterCallback) (SLOHBufferQueueItf self, SlOHBufferQueueCallback callback, void\* pContext) | 注册回调函数。<br/>self：表示调用该函数的BufferQueue接口对象。<br/>callback：播放/录音时注册的回调函数。<br/>pContext：播放时传入待播放音频文件，录音时传入将要录制的音频文件。 | 61 | SLresult (\*GetBuffer) (SLOHBufferQueueItf self, SLuint8\*\* buffer, SLuint32\* size) | 根据情况获取相应的buffer。<br/>如果是播放操作，则从freeBufferQ_队列中获取空闲buffer；如果是录音操作，则从filledBufferQ_队列中获取携带录音数据的buffer。<br/>self：表示调用该函数的BufferQueue接口对象。<br/>buffer：播放时表示空闲的buffer，录音时表示携带录音数据的buffer。<br/>size：表示buffer的大小。 | 62 63## 完整示例 64 65### 在 CMake 脚本中链接动态库 66 67``` cmake 68target_link_libraries(sample PUBLIC libOpenSLES.so) 69``` 70 71参考下列示例代码，完成音频录制。 72 731. 添加头文件。 74 75 ```cpp 76 #include "SLES/OpenSLES.h" 77 #include "SLES/OpenSLES_OpenHarmony.h" 78 #include "SLES/OpenSLES_Platform.h" 79 ``` 80 812. 使用slCreateEngine接口创建引擎对象和实例化引擎对象engine。 82 83 ```cpp 84 SLObjectItf engineObject = nullptr; 85 slCreateEngine(&engineObject, 0, nullptr, 0, nullptr, nullptr); 86 (*engineObject)->Realize(engineObject, SL_BOOLEAN_FALSE); 87 ``` 88 893. 获取接口SL_IID_ENGINE的引擎接口engineEngine实例。 90 91 ```cpp 92 SLEngineItf engineItf = nullptr; 93 (*engineObject)->GetInterface(engineObject, SL_IID_ENGINE, &engineItf); 94 ``` 95 964. 配置录音器信息（配置输入源audiosource、输出源audiosink），创建录音对象pcmCapturerObject。 97 98 ```cpp 99 SLDataLocator_IODevice io_device = { 100 SL_DATALOCATOR_IODEVICE, 101 SL_IODEVICE_AUDIOINPUT, 102 SL_DEFAULTDEVICEID_AUDIOINPUT, 103 NULL 104 }; 105 SLDataSource audioSource = { 106 &io_device, 107 NULL 108 }; 109 SLDataLocator_BufferQueue buffer_queue = { 110 SL_DATALOCATOR_BUFFERQUEUE, 111 3 112 }; 113 // 具体参数需要根据音频文件格式进行适配。 114 SLDataFormat_PCM format_pcm = { 115 SL_DATAFORMAT_PCM, // 输入的音频格式。 116 1, // 单声道。 117 SL_SAMPLINGRATE_44_1, // 采样率: 44100HZ。 118 SL_PCMSAMPLEFORMAT_FIXED_16, // 音频采样格式, 小端, 带符号的16位整数。 119 16, 120 SL_SPEAKER_FRONT_LEFT, 121 SL_BYTEORDER_LITTLEENDIAN 122 }; 123 SLDataSink audioSink = { 124 &buffer_queue, 125 &format_pcm 126 }; 127 128 SLObjectItf pcmCapturerObject = nullptr; 129 (*engineItf)->CreateAudioRecorder(engineItf, &pcmCapturerObject, 130 &audioSource, &audioSink, 0, nullptr, nullptr); 131 (*pcmCapturerObject)->Realize(pcmCapturerObject, SL_BOOLEAN_FALSE); 132 ``` 133 1345. 获取录音接口SL_IID_RECORD的recordItf接口实例。 135 136 ```cpp 137 SLRecordItf recordItf; 138 (*pcmCapturerObject)->GetInterface(pcmCapturerObject, SL_IID_RECORD, &recordItf); 139 ``` 140 1416. 获取接口SL_IID_OH_BUFFERQUEUE的bufferQueueItf实例。 142 143 ```cpp 144 SLOHBufferQueueItf bufferQueueItf; 145 (*pcmCapturerObject)->GetInterface(pcmCapturerObject, SL_IID_OH_BUFFERQUEUE, &bufferQueueItf); 146 ``` 147 1487. 注册BufferQueueCallback回调。 149 150 ```cpp 151 static void BufferQueueCallback(SLOHBufferQueueItf bufferQueueItf, void *pContext, SLuint32 size) 152 { 153 // 可从pContext获取注册时传入的使用者信息。 154 SLuint8 *buffer = nullptr; 155 SLuint32 pSize = 0; 156 (*bufferQueueItf)->GetBuffer(bufferQueueItf, &buffer, &pSize); 157 if (buffer != nullptr) { 158 // 可从buffer内读取录音数据进行后续处理。 159 (*bufferQueueItf)->Enqueue(bufferQueueItf, buffer, size); 160 } 161 } 162 void *pContext; // 可传入自定义的上下文信息，会在Callback内收到。 163 (*bufferQueueItf)->RegisterCallback(bufferQueueItf, BufferQueueCallback, pContext); 164 ``` 165 1668. 开始录音。 167 168 ```cpp 169 (*recordItf)->SetRecordState(recordItf, SL_RECORDSTATE_RECORDING); 170 ``` 171 1729. 结束音频录制。 173 174 ```cpp 175 (*recordItf)->SetRecordState(recordItf, SL_RECORDSTATE_STOPPED); 176 (*pcmCapturerObject)->Destroy(pcmCapturerObject); 177 (*engineObject)->Destroy(engineObject); 178 ``` 179