(Recommended) Using OHAudio for Audio Playback (C/C++)

OHAudio is a set of C APIs introduced in API version 10. These APIs are normalized in design and support both common and low-latency audio channels. They support the PCM format only and are suitable for applications that implement audio output at the native layer.

OHAudio audio playback state transition

Prerequisites

To use the playback capability of OHAudio, you must first import the corresponding header files.

The examples in each of the following steps are code snippets. You can click the link at the bottom right of the sample code to obtain the complete sample codes.

Linking the Dynamic Library in the CMake Script

target_link_libraries(sample PUBLIC libohaudio.so)

Adding Header Files

Include the <native_audiostreambuilder.h> and <native_audiorenderer.h> header files so that the application can use the functions related to audio playback.

#include <ohaudio/native_audiorenderer.h>
#include <ohaudio/native_audiostreambuilder.h>

How to Develop

Read OHAudio for the API reference.

Building Audio Streams

OHAudio provides the OH_AudioStreamBuilder class, which complies with the builder design pattern and is used to build audio streams. You need to specify OH_AudioStream_Type based on your service scenarios.

OH_AudioStream_Type can be set to either of the following:

• AUDIOSTREAM_TYPE_RENDERER
• AUDIOSTREAM_TYPE_CAPTURER

The following code snippet shows how to use OH_AudioStreamBuilder_Create to create a builder:

OH_AudioStreamBuilder* builder;
// ...
    OH_AudioStreamBuilder_Create(&builder, AUDIOSTREAM_TYPE_RENDERER);

After the audio service is complete, call OH_AudioStreamBuilder_Destroy to destroy the builder.

OH_AudioStreamBuilder_Destroy(builder);

The following walks you through how to implement simple playback:

Implementing Audio Playback

1. Create an audio stream builder.

   OH_AudioStreamBuilder* builder;
   // ...
       OH_AudioStreamBuilder_Create(&builder, AUDIOSTREAM_TYPE_RENDERER);
   

   renderer.cpp

2. Set audio stream parameters.

   For details about the audio sampling rate, see Configuring the Appropriate Audio Sampling Rate.
   After creating the builder for audio playback, set the parameters required.

   // Set the audio sampling rate.
   const int SAMPLING_RATE_48K = 48000;
   OH_AudioStreamBuilder_SetSamplingRate(builder, SAMPLING_RATE_48K);
   // Set the number of audio channels.
   const int channelCount = 2;
   OH_AudioStreamBuilder_SetChannelCount(builder, channelCount);
   // Set the audio sampling format.
   OH_AudioStreamBuilder_SetSampleFormat(builder, AUDIOSTREAM_SAMPLE_S16LE);
   // Set the encoding type of the audio stream.
   OH_AudioStreamBuilder_SetEncodingType(builder, AUDIOSTREAM_ENCODING_TYPE_RAW);
   // Set the usage scenario of the audio renderer.
   OH_AudioStreamBuilder_SetRendererInfo(builder, AUDIOSTREAM_USAGE_MUSIC);
   

   renderer.cpp

   The audio data for playback must be written through a callback function, and you must implement the callback function. Starting from API version 12, you can use OH_AudioStreamBuilder_SetRendererWriteDataCallback to set the data callback function. For details about its declaration, see OH_AudioRenderer_OnWriteDataCallback.

3. Set the callback functions.

   For details about concurrent processing of multiple audio streams, see Processing Audio Interruption Events. The procedure is similar, and the only difference is the API programming language in use.

   • Starting from API version 12, you are advised to use OH_AudioRenderer_OnWriteDataCallback to write audio data.

     NOTE

     • When the amount of data is sufficient to meet the required buffer length of the callback, you should return AUDIO_DATA_CALLBACK_RESULT_VALID, and the system uses the entire data buffer for playback. Do not return AUDIO_DATA_CALLBACK_RESULT_VALID in this case, as this leads to audio artifacts such as noise and playback stuttering.

     • When the amount of data is insufficient to meet the required buffer length of the callback, you are advised to return AUDIO_DATA_CALLBACK_RESULT_INVALID. In this case, the system does not process this portion of audio data but requests data from the application again. Once the buffer is adequately filled, you can return AUDIO_DATA_CALLBACK_RESULT_VALID.

     • Once the callback function finishes its execution, the audio service queues the data in the buffer for playback. Therefore, do not change the buffered data outside the callback. Regarding the last frame, if there is insufficient data to completely fill the buffer, you must concatenate the available data with padding to ensure that the buffer is full. This prevents any residual dirty data in the buffer from adversely affecting the playback effect.

   • Starting from API version 12, you can call OH_AudioStreamBuilder_SetFrameSizeInCallback to set audioDataSize.

   // Customize a data writing function.
   static OH_AudioData_Callback_Result MyOnWriteData_New(
       OH_AudioRenderer* renderer,
       void* userData,
       void* audioData,
       int32_t audioDataSize)
   {
       // Write the data to be played to audioData by audioDataSize.
       // If you do not want to play a segment of audioData, return AUDIO_DATA_CALLBACK_RESULT_INVALID.
       return AUDIO_DATA_CALLBACK_RESULT_VALID;
   }
   
   // Customize an audio interruption event function.
   void MyOnInterruptEvent_New(
       OH_AudioRenderer* renderer,
       void* userData,
       OH_AudioInterrupt_ForceType type,
       OH_AudioInterrupt_Hint hint)
   {
       // Update the player status and UI based on the audio interruption information indicated by type and hint.
   }
   
   // Customize an exception callback function.
   void MyOnError_New(
       OH_AudioRenderer* renderer,
       void* userData,
       OH_AudioStream_Result error)
   {
       // Perform operations based on the audio exception information indicated by error.
   }
   // ...
       // Configure the callback function for interruption events.
       OH_AudioRenderer_OnInterruptCallback OnIntereruptCb = MyOnInterruptEvent_New;
       OH_AudioStreamBuilder_SetRendererInterruptCallback(builder, OnIntereruptCb, nullptr);
       
       // Configure the callback function for audio exceptions.
       OH_AudioRenderer_OnErrorCallback OnErrorCb = MyOnError_New;
       OH_AudioStreamBuilder_SetRendererErrorCallback(builder, OnErrorCb, nullptr);
       
       // Configure the callback function for writing audio data.
       OH_AudioRenderer_OnWriteDataCallback writeDataCb = MyOnWriteData_New;
       OH_AudioStreamBuilder_SetRendererWriteDataCallback(builder, writeDataCb, nullptr);
   

   renderer.cpp

4. Create an audio renderer instance.

   OH_AudioRenderer* audioRenderer;
   // ...
       OH_AudioStreamBuilder_GenerateRenderer(builder, &audioRenderer);
   

   renderer.cpp

5. Use the audio renderer.

   You can use the APIs listed below to control the audio streams.

   API	Description
   OH_AudioStream_Result OH_AudioRenderer_Start(OH_AudioRenderer* renderer)	Starts the audio renderer.
   OH_AudioStream_Result OH_AudioRenderer_Pause(OH_AudioRenderer* renderer)	Pauses the audio renderer.
   OH_AudioStream_Result OH_AudioRenderer_Stop(OH_AudioRenderer* renderer)	Stops the audio renderer.
   OH_AudioStream_Result OH_AudioRenderer_Flush(OH_AudioRenderer* renderer)	Flushes obtained audio data.
   OH_AudioStream_Result OH_AudioRenderer_Release(OH_AudioRenderer* renderer)	Releases the audio renderer instance.

   NOTE

   The execution of audio stream control APIs is time-consuming (for example, a single execution of OH_AudioRenderer_Stop generally takes more than 50 ms as it needs to play through the cache). Direct calls to these APIs on the main thread should be avoided to prevent interface display freezes.

6. Destroy the audio stream builder.

   When the builder is no longer used, release related resources.

   Applications must properly manage builders according to their needs, creating them as needed and releasing them promptly. This prevents excessive consumption of audio resources, which can lead to exceptions.

   OH_AudioStreamBuilder_Destroy(builder);
   

   renderer.cpp

Setting the Volume for an Audio Stream

You can use OH_AudioRenderer_SetVolume to set the volume for the current audio stream.

float volume = 0.5f;

// Set the volume for the audio stream.
OH_AudioRenderer_SetVolume(audioRenderer, volume);

Setting the Low Latency Mode

If the device supports the low-latency channel and the sampling rate is set to 48000 Hz, you can use the low-latency mode to create a player for a higher-quality audio experience.

The development process is similar to that in the common playback scenario (described in Implementing Audio Playback). The only difference is that you need to set the low delay mode by calling OH_AudioStreamBuilder_SetLatencyMode() when creating an audio stream builder in step 1.

NOTE

• In audio recording scenarios, if OH_AudioStream_Usage is set to AUDIOSTREAM_USAGE_VOICE_COMMUNICATION or AUDIOSTREAM_USAGE_VIDEO_COMMUNICATION, the low-latency mode cannot be set. The system determines the output audio channel based on the device capability.
• The low-latency mode requires robust data processing capabilities. If your application generates data slowly, it may lead to lag. Therefore, for typical music and video playback, this mode is not recommended. It is best suited for applications that are sensitive to latency, such as gaming and karaoke.

OH_AudioStreamBuilder_SetLatencyMode(builder, AUDIOSTREAM_LATENCY_MODE_FAST);

Setting the Audio Channel Layout

In the case of audio file playback, you can set the audio channel layout to specify the speaker position during rendering or playing for a better audio experience.

The development process is similar to that in the common playback scenario (described in Implementing Audio Playback). The only difference is that you need to set the audio channel layout by calling OH_AudioStreamBuilder_SetChannelLayout() when creating an audio stream builder in step 1.

If the audio channel layout does not match the number of audio channels, audio streams fail to be created. Therefore, you must ensure that the audio channel layout setting is correct.

If you do not know the accurate audio channel layout or you want to use the default audio channel layout, do not call the API to set the audio channel layout. Alternatively, deliver CH_LAYOUT_UNKNOWN to use the default audio channel layout, which is specific to the number of audio channels.

For audio in Higher Order Ambisonics (HOA) format, to obtain the correct rendering and playback effect, you must specify the audio channel layout.

OH_AudioStreamBuilder_SetChannelLayout(builder, CH_LAYOUT_STEREO);

Playing Audio Files in Audio Vivid Format

In the case of audio file playback in Audio Vivid format, the callback function used for writing data is different from that in the common playback scenario. This callback function can write Pulse Code Modulation (PCM) data and metadata at the same time.

The development process is similar to that in the common playback scenario (described in Implementing Audio Playback). The only difference is that you need to call OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback() to set the callback function and call OH_AudioStreamBuilder_SetEncodingType() to set the encoding type to AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID when creating an audio stream builder in step 1.

When an audio file in Audio Vivid format is played, the frame size is fixed. Therefore, do not call OH_AudioStreamBuilder_SetFrameSizeInCallback() to set the frame size in the callback. In addition, when setting the number of audio channels and the audio channel layout, use the sum of the number of sound beds written into the audio source and the number of objects.

// Customize a callback function for simultaneously writing PCM data and metadata.
int32_t MyOnWriteDataWithMetadata_New(
    OH_AudioRenderer* renderer,
    void* userData,
    void* audioData,
    int32_t audioDataSize,
    void* metadata,
    int32_t metadataSize)
{
    // Write the PCM data and metadata to be played to the buffer by audioDataSize and metadataSize, respectively.
    return 0;
}
// ...
    // Set the encoding type.
    OH_AudioStreamBuilder_SetEncodingType(builder, AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID);
    // Set the callbacks.
    OH_AudioRenderer_WriteDataWithMetadataCallback metadataCallback = MyOnWriteDataWithMetadata_New;
    // Set the callback function for writing both PCM data and metadata.
    OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback(builder, metadataCallback, nullptr);

Samples

For details about the sample related to OHAudio audio playback, see OHAudio Recording and Playback.

Precautions

Starting from API version 12, the OH_AudioRenderer_Callbacks API is no longer recommended for setting audio callback functions. If this API must be used, you should ensure that the audio callback function is set properly to avoid unexpected behavior. You can do this in one of two ways:

• Initialize each callback in OH_AudioRenderer_Callbacks by a custom callback method or a null pointer.

  OH_AudioRenderer_Callbacks callbacks;
  // ...
  // Customize a data writing function.
  int32_t MyOnWriteData_Legacy(
      OH_AudioRenderer* renderer,
      void* userData,
      void* buffer,
      int32_t length)
  {
      // Write the data to be played to the buffer by length.
      return 0;
  }
  
  // Customize an audio interruption event function.
  int32_t MyOnInterruptEvent_Legacy(
      OH_AudioRenderer* renderer,
      void* userData,
      OH_AudioInterrupt_ForceType type,
      OH_AudioInterrupt_Hint hint)
  {
      // Update the player status and UI based on the audio interruption information indicated by type and hint.
      return 0;
  }
  // ...
      // Configure a callback function. If listening is required, assign a value.
      callbacks.OH_AudioRenderer_OnWriteData = MyOnWriteData_Legacy;
      callbacks.OH_AudioRenderer_OnInterruptEvent = MyOnInterruptEvent_Legacy;
  
      // (Mandatory) If no callback is triggered, use a null pointer for initialization. From API version 11, if you need to listen to device changes,
      // you can use OH_AudioRenderer_OutputDeviceChangeCallback instead.
      callbacks.OH_AudioRenderer_OnStreamEvent = nullptr;
      // (Mandatory) If listening is not required, use a null pointer for initialization.
      callbacks.OH_AudioRenderer_OnError = nullptr;
  

  renderer.cpp

• Initialize and clear the struct before using it.

  OH_AudioRenderer_Callbacks callbacks;
  // ...
  // Customize a data writing function.
  int32_t MyOnWriteData_Legacy(
      OH_AudioRenderer* renderer,
      void* userData,
      void* buffer,
      int32_t length)
  {
      // Write the data to be played to the buffer by length.
      return 0;
  }
  
  // Customize an audio interruption event function.
  int32_t MyOnInterruptEvent_Legacy(
      OH_AudioRenderer* renderer,
      void* userData,
      OH_AudioInterrupt_ForceType type,
      OH_AudioInterrupt_Hint hint)
  {
      // Update the player status and UI based on the audio interruption information indicated by type and hint.
      return 0;
  }
  // ...
      // Initialize and clear the struct before using it.
      OH_AudioRenderer_Callbacks callbacks = {0};
  
      // Configure the required callback functions.
      callbacks.OH_AudioRenderer_OnWriteData = MyOnWriteData_Legacy;
      callbacks.OH_AudioRenderer_OnInterruptEvent = MyOnInterruptEvent_Legacy;
  

  renderer.cpp