harmony 鸿蒙AVSession Provider (C/C++)

2025-06-12
浏览 (4)

AVSession Provider (C/C++)

The OHAVSession module provides C APIs to implement an AVSession provider. An audio and video application needs to access the AVSession service as a provider in order to display media information in the controller (for example, Media Controller) and respond to playback control commands delivered by the controller.

Prerequisites

To use the OHAVSession module to implement an AVSession provider, add the corresponding header files.

Linking the Dynamic Libraries in the CMake Script

target_link_libraries(entry PUBLIC libohavsession.so)

Including Header Files

#include <multimedia/av_session/native_avmetadata.h>
#include <multimedia/av_session/native_avsession.h>
#include <multimedia/av_session/native_avsession_errors.h>

How to Develop

To access a local session with the NDK, perform the following steps: 1. Create a session and activate the media. Specifically, pass the session type (specified by AVSession_Type), custom tag, bundle name, and ability name.

   OH_AVSession* avsession;
   OH_AVSession_Create(SESSION_TYPE_AUDIO, "testsession", "com.example. application",   "MainAbility", &avsession);

AVSession_Type can be set to any of the following types:

SESSION_TYPE_AUDIO
SESSION_TYPE_VIDEO
SESSION_TYPE_VOICE_CALL
SESSION_TYPE_VIDEO_CALL
Set the metadata of the media asset to be played.

To set metadata, use OH_AVMetadataBuilder to construct specific data, generate an OH_AVMetadata instance, and then call the APIs of OH_AVMetadata to set the asset.

The code snippet below shows how to call OH_AVMetadataBuilder to construct metadata:

   // Create an OH_AVMetadataBuilder.
   OH_AVMetadataBuilder* builder;
   OH_AVMetadataBuilder_Create(&builder);
   
   OH_AVMetadata* ohMetadata;
   OH_AVMetadataBuilder_SetTitle(builder, "Anonymous title");
   OH_AVMetadataBuilder_SetArtist(builder, "Anonymous artist");
   OH_AVMetadataBuilder_SetAuthor(builder, "Anonymous author");
   OH_AVMetadataBuilder_SetAlbum(builder, "Anonymous album");
   OH_AVMetadataBuilder_SetWriter(builder, "Anonymous writer");
   OH_AVMetadataBuilder_SetComposer(builder, "Anonymous composer");
   OH_AVMetadataBuilder_SetDuration(builder, 3600);
   // MediaImageUri can only be set to a network address.
   OH_AVMetadataBuilder_SetMediaImageUri(builder, "https://xxx.xxx.xx");
   OH_AVMetadataBuilder_SetSubtitle(builder, "Anonymous subtitle");
   OH_AVMetadataBuilder_SetDescription(builder, "For somebody");
   // Lyric can only be set to the lyric content. (The application must combine the lyric content into a string.)
   OH_AVMetadataBuilder_SetLyric(builder, "balabala");
   OH_AVMetadataBuilder_SetAssetId(builder, "000");
   OH_AVMetadataBuilder_SetSkipIntervals(builder, SECONDS_30);
   OH_AVMetadataBuilder_SetDisplayTags(builder,  AVSESSION_DISPLAYTAG_AUDIO_VIVID);
   
   /**
    * Generate an AVMetadata.
    */
   OH_AVMetadataBuilder_GenerateAVMetadata(builder, &ohMetadata);

When the OH_AVMetadataBuilder is no longer needed, call OH_AVMetadataBuilder_Destroy to destroy it and do not use it anymore.

   OH_AVMetadata_Destroy(ohMetadata);
   OH_AVMetadataBuilder_Destroy(builder);

Update the media playback status information.

The information includes the playback state, playback position, playback speed, and favorite status. You can use the APIs to set the information.

   AVSession_ErrCode ret = AV_SESSION_ERR_SUCCESS;
   
   // Set the playback state, which is in the range [0,11].
   AVSession_PlaybackState state = PLAYBACK_STATE_PREPARING;
   ret = OH_AVSession_SetPlaybackState(avsession, state);
   
   // Set the playback position.
   AVSession_PlaybackPosition* playbackPosition = new  AVSession_PlaybackPosition;
   playbackPosition->elapsedTime = 1000;
   playbackPosition->updateTime = 16111150;
   ret = OH_AVSession_SetPlaybackPosition(avsession, playbackPosition);

Listen for playback control commands delivered by the controller, for example, Media Controller.

NOTE

After the provider registers a listener for fixed playback control commands, the commands will be reflected in getValidCommands() of the controller. In other words, the controller determines that the command is valid and triggers the corresponding event as required. To ensure that the playback control commands delivered by the controller can be executed normally, the provider should not use a null implementation for listening.

Currently, the following playback control commands are supported: - Play - Pause - Stop - Play previous - Play next - Rewind - Fast forward - Seek - Favorite

   // Register the callbacks for the commands of play, pause, stop, play previous, and play next.
   // CONTROL_CMD_PLAY = 0; play.
   // CONTROL_CMD_PAUSE = 1; pause.
   // CONTROL_CMD_STOP = 2; stop.
   // CONTROL_CMD_PLAY_NEXT = 3; play previous.
   // CONTROL_CMD_PLAY_PREVIOUS = 4; play next.
   AVSession_ControlCommand command = CONTROL_CMD_PLAY;
   OH_AVSessionCallback_OnCommand commandCallback = [](OH_AVSession* session, AVSession_ControlCommand command,
       void* userData) -> AVSessionCallback_Result
   {
       return AVSESSION_CALLBACK_RESULT_SUCCESS;
   };
   OH_AVSession_RegisterCommandCallback(avsession, command, commandCallback, (void *)(&userData));
   
   // Register the callback for the fast-forward operation.
   OH_AVSessionCallback_OnFastForward fastForwardCallback = [](OH_AVSession* session, uint32_t seekTime,
       void* userData) -> AVSessionCallback_Result
   {
       return AVSESSION_CALLBACK_RESULT_SUCCESS;
   };
   OH_AVSession_RegisterForwardCallback(avsession, fastForwardCallback, (void *)(&userData));

The related callbacks are as follows:

|API |Description | |————————————————————|————| |OH_AVSession_RegisterCommandCallback(OH_AVSession* avsession, AVSession_ControlCommand command, OH_AVSessionCallback_OnCommand callback, void* userData)|Registers a callback for a common playback control command, which can be play, pause, stop, play previous, or play next. | |OH_AVSession_RegisterForwardCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnFastForward callback, void* userData)|Registers a callback for the fast-forward operation.| |OH_AVSession_RegisterRewindCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnRewind callback, void* userData)|Registers a callback for the rewind operation. | |OH_AVSession_RegisterSeekCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnSeek callback, void* userData)|Registers a callback for the seek operation.| |OH_AVSession_RegisterToggleFavoriteCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnToggleFavorite callback, void* userData)|Registers a callback for the favorite operation.| 5. When the audio and video application exits and does not need to continue playback, cancel the listener and destroy the AVSession object. The sample code is as follows: