1# 媒体会话提供方(C/C++) 2<!--Kit: AVSession Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @ccfriend; @liao_qian--> 5<!--Designer: @ccfriend--> 6<!--Tester: @chenmingxi1_huawei--> 7<!--Adviser: @zengyawen--> 8 9OHAVSession系统提供的通过使用C API实现媒体会话提供方，从而在媒体会话控制方（例如播控中心）中展示媒体相关信息，及响应媒体会话控制方下发的播控命令。 10 11## 使用入门 12 13开发者要使用[OHAVSession](../../reference/apis-avsession-kit/capi-native-avsession-h.md)实现媒体会话，需要添加对应的头文件。 14 15### 在 CMake 脚本中链接动态库 16 17``` cmake 18target_link_libraries(entry PUBLIC libohavsession.so) 19``` 20 21### 添加头文件 22 23```cpp 24#include <multimedia/av_session/native_avmetadata.h> 25#include <multimedia/av_session/native_avsession.h> 26#include <multimedia/av_session/native_avsession_errors.h> 27``` 28 29## 开发步骤及注意事项 30 31开发者可以通过以下几个步骤在NDK接入本地会话。 321. 创建会话并激活媒体，需要传入会话类型`AVSession_Type`，自定义的TAG，以及应用的包名、ability名字。 33 34 ```c++ 35 OH_AVSession* avsession; 36 OH_AVSession_Create(SESSION_TYPE_AUDIO, "testsession", "com.example.application", "MainAbility", &avsession); 37 OH_AVSession_Activate(avsession); 38 ``` 39 40 `AVSession_Type`包含如下四种类型： 41 42 - SESSION_TYPE_AUDIO 43 - SESSION_TYPE_VIDEO 44 - SESSION_TYPE_VOICE_CALL 45 - SESSION_TYPE_VIDEO_CALL 46 47 482. 应用内播放对应的媒体资源时，同步设置媒体元数据信息。 49 50 要设置元数据，要使用OH_AVMetadataBuilder构造具体的数据，最后生成一个 OH_AVMetadata。生成OH_AVMetadata后，使用OH_AVMetadata的各个功能接口进行资源的设置。 51 52 使用OH_AVMetadataBuilder构造元数据示例： 53 54 ```c++ 55 //创建OH_AVMetadataBuilder构造器。 56 OH_AVMetadataBuilder* builder; 57 OH_AVMetadataBuilder_Create(&builder); 58 59 OH_AVMetadata* ohMetadata; 60 OH_AVMetadataBuilder_SetTitle(builder, "Anonymous title"); 61 OH_AVMetadataBuilder_SetArtist(builder, "Anonymous artist"); 62 OH_AVMetadataBuilder_SetAuthor(builder, "Anonymous author"); 63 OH_AVMetadataBuilder_SetAlbum(builder, "Anonymous album"); 64 OH_AVMetadataBuilder_SetWriter(builder, "Anonymous writer"); 65 OH_AVMetadataBuilder_SetComposer(builder, "Anonymous composer"); 66 OH_AVMetadataBuilder_SetDuration(builder, 3600); 67 // MediaImageUri只支持网络地址。 68 OH_AVMetadataBuilder_SetMediaImageUri(builder, "https://xxx.xxx.xx"); 69 OH_AVMetadataBuilder_SetSubtitle(builder, "Anonymous subtitle"); 70 OH_AVMetadataBuilder_SetDescription(builder, "For somebody"); 71 // Lyric只支持媒体歌词内容（应用需将歌词内容拼接为一个字符串传入）。 72 OH_AVMetadataBuilder_SetLyric(builder, "balabala"); 73 OH_AVMetadataBuilder_SetAssetId(builder, "000"); 74 OH_AVMetadataBuilder_SetSkipIntervals(builder, SECONDS_30); 75 OH_AVMetadataBuilder_SetDisplayTags(builder, AVSESSION_DISPLAYTAG_AUDIO_VIVID); 76 77 /** 78 * generate an AVMetadata 构造AVMetadata对象 79 */ 80 OH_AVMetadataBuilder_GenerateAVMetadata(builder, &ohMetadata); 81 82 /** 83 * set AVMetadata 设置AVMetadata对象 84 */ 85 OH_AVSession_SetAVMetadata(avsession, ohMetadata); 86 ``` 87 88 在不使用AVMetadata之后，开发者应该执行OH_AVMetadataBuilder_Destroy接口来销毁元数据，且不要继续使用。 89 90 ```c++ 91 OH_AVMetadata_Destroy(ohMetadata); 92 OH_AVMetadataBuilder_Destroy(builder); 93 ``` 94 953. 跟随媒体播放状态的变化，及时更新媒体播放状态。 96 97 媒体播放状态，包含状态值、播放位置、播放速度、收藏状态等，可以按需使用对应的接口进行设置。 98 99 ```c++ 100 AVSession_ErrCode ret = AV_SESSION_ERR_SUCCESS; 101 102 // 设置播放状态，其中state范围应为[0,11]。 103 AVSession_PlaybackState state = PLAYBACK_STATE_PREPARING; 104 ret = OH_AVSession_SetPlaybackState(avsession, state); 105 106 // 设置播放位置。 107 AVSession_PlaybackPosition* playbackPosition = new AVSession_PlaybackPosition; 108 playbackPosition->elapsedTime = 1000; 109 playbackPosition->updateTime = 16111150; 110 ret = OH_AVSession_SetPlaybackPosition(avsession, playbackPosition); 111 ``` 112 1134. 注册播控命令事件监听，便于响应用户通过媒体会话控制方，例如播控中心下发的播控命令。 114 115 > **说明：** 116 > 117 > 媒体会话提供方在注册相关固定播控命令事件监听时，监听的事件会在媒体会话控制方的getValidCommands()方法中体现，即媒体会话控制方认为该方法有效，因此在需要时会触发相应的事件。为了保证媒体会话控制方下发的播控命令可以被正常执行，媒体会话提供方请勿进行无逻辑的空实现监听。 118 > 调用注册接口后，在业务结束时需要调用取消注册接口，避免出现异常。 119 120 Session侧目前支持的播控命令包括： 121 - 播放 122 - 暂停 123 - 停止 124 - 上一首 125 - 下一首 126 - 快退 127 - 快进 128 - 设置进度 129 - 设置收藏 130 131 ```c++ 132 // 设置播放/暂停/停止/上一首/下一首回调。 133 // CONTROL_CMD_PLAY = 0; 播放。 134 // CONTROL_CMD_PAUSE = 1; 暂停。 135 // CONTROL_CMD_STOP = 2; 停止。 136 // CONTROL_CMD_PLAY_NEXT = 3; 下一首。 137 // CONTROL_CMD_PLAY_PREVIOUS = 4; 上一首。 138 AVSession_ControlCommand command = CONTROL_CMD_PLAY; 139 OH_AVSessionCallback_OnCommand commandCallback = [](OH_AVSession* session, AVSession_ControlCommand command, 140 void* userData) -> AVSessionCallback_Result 141 { 142 return AVSESSION_CALLBACK_RESULT_SUCCESS; 143 }; 144 OH_AVSession_RegisterCommandCallback(avsession, command, commandCallback, (void *)(&userData)); 145 146 //设置快进回调。 147 OH_AVSessionCallback_OnFastForward fastForwardCallback = [](OH_AVSession* session, uint32_t seekTime, 148 void* userData) -> AVSessionCallback_Result 149 { 150 return AVSESSION_CALLBACK_RESULT_SUCCESS; 151 }; 152 OH_AVSession_RegisterForwardCallback(avsession, fastForwardCallback, (void *)(&userData)); 153 ``` 154 相关回调接口如下： 155 156 | 接口 | 说明 | 157 | ------------------------------------------------------------ | ------------ | 158 |OH_AVSession_RegisterCommandCallback(OH_AVSession* avsession, AVSession_ControlCommand command, OH_AVSessionCallback_OnCommand callback, void* userData) | 注册通用播控的回调，支持：播放、暂停、停止、上一首、下一首回调。 | 159 |OH_AVSession_RegisterForwardCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnFastForward callback, void* userData) | 注册快进的回调。 | 160 |OH_AVSession_RegisterRewindCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnRewind callback, void* userData) | 注册快退的回调。 | 161 |OH_AVSession_RegisterSeekCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnSeek callback, void* userData) | 注册跳转的回调。 | 162 |OH_AVSession_RegisterToggleFavoriteCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnToggleFavorite callback, void* userData) | 注册收藏的回调。 | 1635. 音视频应用在退出，并且不需要继续播放时，及时取消监听以及销毁媒体会话释放资源。示例代码如下所示： 164 165 ```c++ 166 OH_AVSession_Destroy(avsession); 167 ``` 168 169## 相关实例 170 171针对媒体会话提供方的NDK开发，有以下相关实例可供参考： 172 173- [媒体会话——提供方（C/C++）（API13）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVSession/MediaProvider) 174