1 /*
2  * Copyright (c) 2020-2021 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 /**
17  * @addtogroup MultiMedia_Player
18  * @{
19  *
20  * @brief Defines the <b>Player</b> class and provides functions related to media playback.
21  *
22  *
23  * @since 1.0
24  * @version 1.0
25  */
26 
27 /**
28  * @file player.h
29  *
30  * @brief Declares the <b>Player</b> class, which is used to implement player-related operations.
31  *
32  *
33  * @since 1.0
34  * @version 1.0
35  */
36 
37 #ifndef PLAYER_H
38 #define PLAYER_H
39 
40 #include "source.h"
41 #include "format.h"
42 #include <memory>
43 #include <vector>
44 #ifndef SURFACE_DISABLED
45 #include "surface.h"
46 #endif
47 
48 namespace OHOS {
49 namespace Media {
50 /**
51  * @brief Enumerates player seek modes. You can move the current playback position of the media to a given time
52  * position using the specified mode.
53  *
54  * @since 1.0
55  * @version 1.0
56  */
57 enum PlayerSeekMode : int32_t {
58     /** Moves the media position to the latest synchronization frame located before the given time position. */
59     PLAYER_SEEK_PREVIOUS_SYNC = 0,
60     /** Moves the media position to the latest synchronization frame located after the given time position. */
61     PLAYER_SEEK_NEXT_SYNC,
62     /** Moves the media position to the latest synchronization frame located before or after the given time position. */
63     PLAYER_SEEK_CLOSEST_SYNC,
64     /** Moves the media position to the latest frame located before or after the given time position. */
65     PLAYER_SEEK_CLOSEST,
66 };
67 
68 /**
69  * @brief Enumerates player states.
70  *
71  * @since 1.0
72  * @version 1.0
73  */
74 enum PlayerStates : uint32_t {
75     /** Error */
76     PLAYER_STATE_ERROR = 0,
77     /** Idle */
78     PLAYER_IDLE = 1 << 0,
79     /** Initialized */
80     PLAYER_INITIALIZED = 1 << 1,
81     /** Preparing */
82     PLAYER_PREPARING = 1 << 2,
83     /** Prepared */
84     PLAYER_PREPARED = 1 << 3,
85     /** Playback started */
86     PLAYER_STARTED = 1 << 4,
87     /** Playback paused */
88     PLAYER_PAUSED = 1 << 5,
89     /** Playback stopped */
90     PLAYER_STOPPED = 1 << 6,
91     /** Playback completed */
92     PLAYER_PLAYBACK_COMPLETE = 1 << 7
93 };
94 
95 /**
96  * @brief Provides listeners for events and exception notifications that occur during media playback.
97  *
98  * @since 1.0
99  * @version 1.0
100  */
101 class PlayerCallback {
102 public:
103     enum PlayerInfoType : int32_t {
104         /** Pushed the first video frame for rendering */
105         PLAYER_INFO_RENDER_START = 0,
106     };
107 
108     enum PlayerErrorType : int32_t {
109         PLAYER_ERROR_UNKNOWN = 0,
110     };
111 
112     PlayerCallback() = default;
113     virtual ~PlayerCallback() = default;
114 
115     /**
116     * @brief Called when the playback is complete.
117     *
118     * @since 1.0
119     * @version 1.0
120     */
121     virtual void OnPlaybackComplete() = 0;
122 
123     /**
124     * @brief Called when a playback error occurs.
125     *
126     * @param errorType Indicates the error type. For details, see {@link PlayerErrorType}.
127     * @param errorCode Indicates the error code.
128     * @since 1.0
129     * @version 1.0
130     */
131     virtual void OnError(int32_t errorType, int32_t errorCode) = 0;
132 
133     /**
134     * @brief Called when playback information is received.
135     *
136     * @param type Indicates the information type. For details, see {@link PlayerInfoType}.
137     * @param extra Indicates the information code.
138     * @since 1.0
139     * @version 1.0
140     */
141     virtual void OnInfo(int type, int extra) = 0;
142 
143     /**
144     * @brief Called when the video image size changes.
145     *
146     * @param width Indicates the video width.
147     * @param height Indicates the video height.
148     * @since 1.0
149     * @version 1.0
150     */
151     virtual void OnVideoSizeChanged(int width, int height) = 0;
152 
153     /**
154     * @brief Called when the rewind is complete.
155     *
156     * @since 1.0
157     * @version 1.0
158     */
159     virtual void OnRewindToComplete() = 0;
160 };
161 
162 /**
163  * @brief Provides functions for playing online movies, offline movies, and streams, for example, playing local
164  * movies and advanced audio coding (AAC) streams.
165  *
166  * @since 1.0
167  * @version 1.0
168  */
169 class Player {
170 public:
171     Player();
172     ~Player();
173 
174     /**
175      * @brief Sets the playback source for the player. The corresponding source can be the file descriptor (FD) of the
176      * local file, local file URI, network URI, or media stream.
177      *
178      * @param source Indicates the playback source. Currently, only local file URIs and media streams are supported.
179      * For details, see {@link Source}.
180      * @return Returns <b>0</b> if the setting is successful; returns <b>-1</b> otherwise.
181      * @since 1.0
182      * @version 1.0
183      */
184     int32_t SetSource(const Source &source);
185 
186     /**
187      * @brief Prepares the playback environment and buffers media data.
188      *
189      * This function must be called after {@link SetSource}.
190      *
191      * @return Returns <b>0</b> if the playback environment is prepared and media data is buffered;
192      * returns <b>-1</b> otherwise.
193      * @since 1.0
194      * @version 1.0
195      */
196     int32_t Prepare();
197 
198     /**
199      * @brief Starts or resumes playback.
200      *
201      * This function must be called after {@link Prepare}. If the player state is <b>Prepared</b>, this function is
202      * called to start playback. If the player state is <b>Playback paused</b>, this function is called to resume
203      * playback. If the media is playing in an abnormal speed, this function is called to restore the playback speed
204      * to normal.
205      *
206      * @return Returns <b>0</b> if the playback starts or resumes; returns <b>-1</b> otherwise.
207      * @since 1.0
208      * @version 1.0
209      */
210     int32_t Play();
211 
212     /**
213      * @brief Checks whether the player is playing.
214      *
215      * @return Returns <b>true</b> if the player is playing; returns <b>false</b> otherwise.
216      * @since 1.0
217      * @version 1.0
218      */
219     bool IsPlaying();
220 
221     /**
222      * @brief Pauses playback.
223      *
224      * @return Returns <b>0</b> if the playback is paused; returns <b>-1</b> otherwise.
225      * @since 1.0
226      * @version 1.0
227      */
228     int32_t Pause();
229 
230     /**
231      * @brief Stops playback.
232      *
233      * @return Returns <b>0</b> if the playback is stopped; returns <b>-1</b> otherwise.
234      * @since 1.0
235      * @version 1.0
236      */
237     int32_t Stop();
238 
239     /**
240      * @brief Changes the playback position.
241      *
242      * This function can be used during playback or pause.
243      *
244      * @param mSeconds Indicates the target playback position, accurate to second.
245      * @param mode Indicates the player seek mode. For details, see {@link PlayerSeekMode}.
246      * @return Returns <b>0</b> if the playback position is changed; returns <b>-1</b> otherwise.
247      * @since 1.0
248      * @version 1.0
249     */
250     int32_t Rewind(int64_t mSeconds, int32_t mode);
251 
252     /**
253      * @brief Sets the volume of the player.
254      *
255      * This function can be used during playback or pause. The value <b>0</b> indicates no sound, and <b>100</b>
256      * indicates the original volume. If no audio device is started or no audio stream exists, the value <b>-1</b>
257      * is returned.
258      *
259      * @param leftVolume Indicates the target volume of the left audio channel to set, ranging from 0 to 300.
260      * @param rightVolume Indicates the target volume of the right audio channel to set, ranging from 0 to 300.
261      * @return Returns <b>0</b> if the setting is successful; returns <b>-1</b> otherwise.
262      * @since 1.0
263      * @version 1.0
264      */
265     int32_t SetVolume(float leftVolume, float rightVolume);
266 
267     /**
268      * @brief Sets a surface for video playback.
269      *
270      * @param surface Indicates the surface to set. For details, see {@link Surface}.
271      * @return Returns <b>0</b> if the setting is successful; returns <b>-1</b> otherwise.
272      * @since 1.0
273      * @version 1.0
274      */
275 #ifndef SURFACE_DISABLED
276     int32_t SetVideoSurface(Surface *surface);
277 #endif
278 
279     /**
280      * @brief Sets loop playback.
281      *
282      * @param loop Specifies whether to enable loop playback. The value <b>true</b> means to enable loop playback,
283      * and <b>false</b> means to disable loop playback.
284      * @return Returns <b>0</b> if the setting is successful; returns <b>-1</b> otherwise.
285      * @since 1.0
286      * @version 1.0
287      */
288     int32_t EnableSingleLooping(bool loop);
289 
290     /**
291      * @brief Checks whether the player is looping.
292      *
293      * @return Returns <b>true</b> if the player is looping; returns <b>false</b> otherwise.
294      * @since 1.0
295      * @version 1.0
296      */
297     bool IsSingleLooping();
298 
299     /**
300      * @brief Obtains the playback position, accurate to millisecond.
301      *
302      * @param time Indicates the playback position.
303      * @return Returns <b>0</b> if the playback position is obtained; returns <b>-1</b> otherwise.
304      * @since 1.0
305      * @version 1.0
306      */
307     int32_t GetCurrentTime(int64_t &time) const;
308 
309     /**
310      * @brief Obtains the total duration of media files, in milliseconds.
311      *
312      * @param duration Indicates the total duration of media files.
313      * @return Returns <b>0</b> if the total duration is obtained; returns <b>-1</b> otherwise.
314      * @since 1.0
315      * @version 1.0
316      */
317     int32_t GetDuration(int64_t &duration) const;
318 
319     /**
320      * @brief Obtains the width of the video.
321      *
322      * @param videoWidth Indicates the video width.
323      * @return Returns <b>0</b> if the video width is obtained; returns <b>-1</b> otherwise.
324      * @since 1.0
325      * @version 1.0
326      */
327     int32_t GetVideoWidth(int32_t &videoWidth);
328 
329     /**
330      * @brief Obtains the height of the video.
331      *
332      * @param videoHeight Indicates the video height.
333      * @return Returns <b>0</b> if the video height is obtained; returns <b>-1</b> otherwise.
334      * @since 1.0
335      * @version 1.0
336      */
337     int32_t GetVideoHeight(int32_t &videoHeight);
338 
339     /**
340      * @brief Restores the player to the initial state.
341      *
342      * @return Returns <b>0</b> if the player is restored; returns <b>-1</b> otherwise.
343      * @since 1.0
344      * @version 1.0
345      */
346     int32_t Reset();
347 
348     /**
349      * @brief Releases player resources.
350      *
351      * @return Returns <b>0</b> if player resources are released; returns <b>-1</b> otherwise.
352      * @since 1.0
353      * @version 1.0
354      */
355     int32_t Release();
356 
357     /**
358      * @brief Registers a listener to receive events and exception notifications from the player.
359      *
360      * @param cb Indicates the listener to register. For details, see {@link PlayerCallback}.
361      * @since 1.0
362      * @version 1.0
363      */
364     void SetPlayerCallback(const std::shared_ptr<PlayerCallback> &cb);
365 
366     /**
367      * @brief Obtains the player state.
368      *
369      * @param state Indicates the player state. For details, see {@link PlayerStates}.
370      * @return Returns <b>0</b> if the player state is obtained; returns <b>-1</b> otherwise.
371      * @since 1.0
372      * @version 1.0
373      */
374     int32_t GetPlayerState(int32_t &state) const;
375 
376     /**
377      * Sets the playback speed.
378      *
379      * @param speed Indicates the playback speed to set, which support {-128/-64/-32/-16/-8/-4/-2/1/2/4/8/16/32/64/128}
380      * @return Returns {@code 0} if the playback speed is set; returns {@code -1} otherwise.
381      */
382     int32_t SetPlaybackSpeed(float speed);
383 
384     /**
385      * Obtains the playback speed.
386      *
387      * @param speed Indicates the playback speed.
388      * @return Returns {@code 0} if the playback speed is set; returns {@code -1} otherwise.
389      */
390     int32_t GetPlaybackSpeed(float &speed);
391 
392     /**
393      * Sets the audio type.
394      *
395      * @param type Indicates the audio type.
396      * @return Returns {@code 0} if the setting is successful; returns {@code -1} otherwise.
397      */
398     int32_t SetAudioStreamType(int32_t type);
399 
400     /**
401      * Obtains the audio type.
402      *
403      * @param type Indicates the audio type.
404      * @return Returns {@code 0} if the playback speed is set; returns {@code -1} otherwise.
405      */
406     void GetAudioStreamType(int32_t &type);
407 
408     /**
409      * set parameter through format, extended interface.
410      *
411      * @param params Indicates the extended-informations. Format see {@link Format}
412      * @return Returns {@code 0} if set parameter successfully; returns {@code -1} otherwise.
413      * @note not support on current version
414      */
415     int32_t SetParameter(const Format &params);
416 
417 private:
418     class PlayerClient;
419     PlayerClient* player_;
420 };
421 }  // namespace Media
422 }  // namespace OHOS
423 #endif  // PLAYER_H
424