1# AVSession Provider (C/C++)
2
3The 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.
4
5## Prerequisites
6
7To use the OHAVSession module to implement an AVSession provider, add the corresponding header files.
8
9### Linking the Dynamic Libraries in the CMake Script
10
11``` cmake
12target_link_libraries(entry PUBLIC libohavsession.so)
13```
14
15### Including Header Files
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## How to Develop
24
25To access a local session with the NDK, perform the following steps:
261. Create a session and activate the media. Specifically, pass the session type (specified by **AVSession_Type**), custom tag, bundle name, and ability name.
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** can be set to any of the following types:
34
35   - SESSION_TYPE_AUDIO
36   - SESSION_TYPE_VIDEO
37   - SESSION_TYPE_VOICE_CALL
38   - SESSION_TYPE_VIDEO_CALL
39
40
412. Set the metadata of the media asset to be played.
42
43   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.
44
45   The code snippet below shows how to call **OH_AVMetadataBuilder** to construct metadata:
46
47   ```c++
48   // Create an 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 can only be set to a network address.
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 can only be set to the lyric content. (The application must combine the lyric content into a string.)
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.
72    */
73   OH_AVMetadataBuilder_GenerateAVMetadata(builder, &ohMetadata);
74   ```
75
76   When the OH_AVMetadataBuilder is no longer needed, call **OH_AVMetadataBuilder_Destroy** to destroy it and do not use it any more.
77
78   ```c++
79   OH_AVMetadata_Destroy(ohMetadata);
80   OH_AVMetadataBuilder_Destroy(builder);
81   ```
82
833. Update the media playback status information.
84
85   The information includes the playback state, playback position, playback speed, and favorite status. You can use the APIs to set the information.
86
87   ```c++
88   AVSession_ErrCode ret = AV_SESSION_ERR_SUCCESS;
89
90   // Set the playback state, which is in the range [0,11].
91   AVSession_PlaybackState state = PLAYBACK_STATE_PREPARING;
92   ret = OH_AVSession_SetPlaybackState(avsession, state);
93
94   // Set the playback position.
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. Listen for playback control commands delivered by the controller, for example, Media Controller.
102
103   > **NOTE**
104   >
105   > 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 (not used temporarily) 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.
106
107   Currently, the following playback control commands are supported:
108   - Play
109   - Pause
110   - Stop
111   - Play previous
112   - Play next
113   - Rewind
114   - Fast forward
115   - Seek
116   - Favorite
117
118   ```c++
119   // Register the callbacks for the commands of play, pause, stop, play previous, and play next.
120   // CONTROL_CMD_PLAY = 0; play
121   // CONTROL_CMD_PAUSE = 1; pause
122   // CONTROL_CMD_STOP = 2; stop
123   // CONTROL_CMD_PLAY_NEXT = 3; play previous
124   // CONTROL_CMD_PLAY_PREVIOUS = 4; play next
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   // Register the callback for the fast-forward operation.
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   The related callbacks are as follows:
142
143   | API                                                        | Description        |
144   | ------------------------------------------------------------ | ------------ |
145   |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.    |
146   |OH_AVSession_RegisterForwardCallback(OH_AVSession* avsession,   OH_AVSessionCallback_OnFastForward callback, void* userData); | Registers a callback for the fast-forward operation.  |
147   |OH_AVSession_RegisterRewindCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnRewind   callback, void* userData); | Registers a callback for the rewind operation.    |
148   |OH_AVSession_RegisterSeekCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnSeek   callback, void* userData); | Registers a callback for the seek operation. |
149   |OH_AVSession_RegisterToggleFavoriteCallback(OH_AVSession* avsession,   OH_AVSessionCallback_OnToggleFavorite callback, void* userData)| Registers a callback for the favorite operation. |
1505. 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:
151
152   ```c++
153   OH_AVSession_Destroy(avsession);
154   ```
155
156