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