• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# AVSession Provider (C/C++)
2<!--Kit: AVSession Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @ccfriend; @liao_qian-->
5<!--SE: @ccfriend-->
6<!--TSE: @chenmingxi1_huawei-->
7
8The 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.
9
10## Prerequisites
11
12To use [OHAVSession](../../reference/apis-avsession-kit/capi-native-avsession-h.md) to implement media sessions, add the corresponding header files.
13
14### Linking the Dynamic Libraries in the CMake Script
15
16``` cmake
17target_link_libraries(entry PUBLIC libohavsession.so)
18```
19
20### Including Header Files
21
22```cpp
23#include <multimedia/av_session/native_avmetadata.h>
24#include <multimedia/av_session/native_avsession.h>
25#include <multimedia/av_session/native_avsession_errors.h>
26```
27
28## How to Develop
29
30To access a local session with the NDK, perform the following steps:
311. Create a session and activate the media. Specifically, pass the session type (specified by **AVSession_Type**), custom tag, bundle name, and ability name.
32
33   ```c++
34   OH_AVSession* avsession;
35   OH_AVSession_Create(SESSION_TYPE_AUDIO, "testsession", "com.example.application",   "MainAbility", &avsession);
36   ```
37
38   **AVSession_Type** can be set to any of the following types:
39
40   - SESSION_TYPE_AUDIO
41   - SESSION_TYPE_VIDEO
42   - SESSION_TYPE_VOICE_CALL
43   - SESSION_TYPE_VIDEO_CALL
44
45
462. Set the metadata of the media asset to be played.
47
48   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.
49
50   The code snippet below shows how to call **OH_AVMetadataBuilder** to construct metadata:
51
52   ```c++
53   // Create an OH_AVMetadataBuilder.
54   OH_AVMetadataBuilder* builder;
55   OH_AVMetadataBuilder_Create(&builder);
56
57   OH_AVMetadata* ohMetadata;
58   OH_AVMetadataBuilder_SetTitle(builder, "Anonymous title");
59   OH_AVMetadataBuilder_SetArtist(builder, "Anonymous artist");
60   OH_AVMetadataBuilder_SetAuthor(builder, "Anonymous author");
61   OH_AVMetadataBuilder_SetAlbum(builder, "Anonymous album");
62   OH_AVMetadataBuilder_SetWriter(builder, "Anonymous writer");
63   OH_AVMetadataBuilder_SetComposer(builder, "Anonymous composer");
64   OH_AVMetadataBuilder_SetDuration(builder, 3600);
65   // MediaImageUri can only be set to a network address.
66   OH_AVMetadataBuilder_SetMediaImageUri(builder, "https://xxx.xxx.xx");
67   OH_AVMetadataBuilder_SetSubtitle(builder, "Anonymous subtitle");
68   OH_AVMetadataBuilder_SetDescription(builder, "For somebody");
69   // Lyric can only be set to the lyric content. (The application must combine the lyric content into a string.)
70   OH_AVMetadataBuilder_SetLyric(builder, "balabala");
71   OH_AVMetadataBuilder_SetAssetId(builder, "000");
72   OH_AVMetadataBuilder_SetSkipIntervals(builder, SECONDS_30);
73   OH_AVMetadataBuilder_SetDisplayTags(builder,  AVSESSION_DISPLAYTAG_AUDIO_VIVID);
74
75   /**
76    * Generate an AVMetadata object.
77    */
78   OH_AVMetadataBuilder_GenerateAVMetadata(builder, &ohMetadata);
79
80   /**
81    * Set the AVMetadata object.
82    */
83   OH_AVSession_SetAVMetadata(avsession, ohMetadata);
84   ```
85
86   When the AVMetadata is no longer needed, call **OH_AVMetadataBuilder_Destroy** to destroy it and do not use it anymore.
87
88   ```c++
89   OH_AVMetadata_Destroy(ohMetadata);
90   OH_AVMetadataBuilder_Destroy(builder);
91   ```
92
933. Update the media playback status information.
94
95   The information includes the playback state, playback position, playback speed, and favorite status. You can use the APIs to set the information.
96
97   ```c++
98   AVSession_ErrCode ret = AV_SESSION_ERR_SUCCESS;
99
100   // Set the playback state, which is in the range [0,11].
101   AVSession_PlaybackState state = PLAYBACK_STATE_PREPARING;
102   ret = OH_AVSession_SetPlaybackState(avsession, state);
103
104   // Set the playback position.
105   AVSession_PlaybackPosition* playbackPosition = new  AVSession_PlaybackPosition;
106   playbackPosition->elapsedTime = 1000;
107   playbackPosition->updateTime = 16111150;
108   ret = OH_AVSession_SetPlaybackPosition(avsession, playbackPosition);
109   ```
110
1114. Listen for playback control commands delivered by the controller, for example, Media Controller.
112
113   > **NOTE**
114   >
115   > 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.
116   >
117   > To avoid any exception, call the API to unregister the listener when the service ends.
118
119   Currently, the following playback control commands are supported:
120   - Play
121   - Pause
122   - Stop
123   - Play previous
124   - Play next
125   - Rewind
126   - Fast forward
127   - Seek
128   - Favorite
129
130   ```c++
131   // Register the callbacks for the commands of play, pause, stop, play previous, and play next.
132   // CONTROL_CMD_PLAY = 0; play.
133   // CONTROL_CMD_PAUSE = 1; pause.
134   // CONTROL_CMD_STOP = 2; stop.
135   // CONTROL_CMD_PLAY_NEXT = 3; play next.
136   // CONTROL_CMD_PLAY_PREVIOUS = 4; play previous.
137   AVSession_ControlCommand command = CONTROL_CMD_PLAY;
138   OH_AVSessionCallback_OnCommand commandCallback = [](OH_AVSession* session, AVSession_ControlCommand command,
139       void* userData) -> AVSessionCallback_Result
140   {
141       return AVSESSION_CALLBACK_RESULT_SUCCESS;
142   };
143   OH_AVSession_RegisterCommandCallback(avsession, command, commandCallback, (void *)(&userData));
144
145   // Register the callback for the fast-forward operation.
146   OH_AVSessionCallback_OnFastForward fastForwardCallback = [](OH_AVSession* session, uint32_t seekTime,
147       void* userData) -> AVSessionCallback_Result
148   {
149       return AVSESSION_CALLBACK_RESULT_SUCCESS;
150   };
151   OH_AVSession_RegisterForwardCallback(avsession, fastForwardCallback, (void *)(&userData));
152   ```
153   The related callbacks are as follows:
154
155   | API                                                        | Description        |
156   | ------------------------------------------------------------ | ------------ |
157   |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.    |
158   |OH_AVSession_RegisterForwardCallback(OH_AVSession* avsession,   OH_AVSessionCallback_OnFastForward callback, void* userData) | Registers a callback for the fast-forward operation.  |
159   |OH_AVSession_RegisterRewindCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnRewind   callback, void* userData) | Registers a callback for the rewind operation.    |
160   |OH_AVSession_RegisterSeekCallback(OH_AVSession* avsession, OH_AVSessionCallback_OnSeek   callback, void* userData) | Registers a callback for the seek operation. |
161   |OH_AVSession_RegisterToggleFavoriteCallback(OH_AVSession* avsession,   OH_AVSessionCallback_OnToggleFavorite callback, void* userData) | Registers a callback for the favorite operation. |
1625. When the audio and video application exits and does not need to continue playback, cancel the listener and destroy the AVSession object. The example code is as follows:
163
164   ```c++
165   OH_AVSession_Destroy(avsession);
166   ```
167
168