1 /*****************************************************************
2  * gmerlin - a general purpose multimedia framework and applications
3  *
4  * Copyright (c) 2001 - 2011 Members of the Gmerlin project
5  * gmerlin-general@lists.sourceforge.net
6  * http://gmerlin.sourceforge.net
7  *
8  * This program is free software: you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation, either version 2 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
20  * *****************************************************************/
21 
22 #ifndef __BG_PLAYER_H_
23 #define __BG_PLAYER_H_
24 
25 #include <gmerlin/playermsg.h>
26 #include <gmerlin/pluginregistry.h>
27 #include <gmerlin/msgqueue.h>
28 
29 /** \defgroup player Player
30  *  \brief Multimedia player
31  */
32 
33 #define BG_PLAYER_VOLUME_MIN (-40.0)
34 
35 typedef struct bg_player_s bg_player_t;
36 
37 /* player.c */
38 
39 /** \ingroup player
40  *  \brief Create a player
41  *  \param plugin_reg A plugin registry
42  *  \returns A newly allocated player
43  *
44  *  The plugin registry is used for loading audio- and video filters
45  */
46 
47 bg_player_t * bg_player_create(bg_plugin_registry_t * plugin_reg);
48 
49 /** \ingroup player
50  *  \brief Get parameters
51  *  \param player A player
52  *  \returns An array of parameters
53  *
54  *  This returns only some internal parameters, which should never be
55  *  changed by the user. For user settable parameters, see
56  *  \ref bg_player_get_input_parameters,
57  *  \ref bg_player_get_audio_parameters,
58  *  \ref bg_player_get_audio_filter_parameters,
59  *  \ref bg_player_get_video_parameters,
60  *  \ref bg_player_get_video_filter_parameters
61  *  \ref bg_player_get_subtitle_parameters and
62  *  \ref bg_player_get_osd_parameters
63  */
64 
65 const bg_parameter_info_t * bg_player_get_parameters(bg_player_t * player);
66 
67 /** \ingroup player
68  *  \brief Get parameters
69  *  \param player A player cast to void
70  *  \param name The name of the parameter
71  *  \param val The parameter value
72  */
73 
74 void bg_player_set_parameter(void * player, const char * name,
75                              const bg_parameter_value_t * val);
76 
77 /** \ingroup player
78  *  \brief Set accelerators
79  *  \param player A newly created player
80  *  \param list A list of accelerators, terminated with BG_KEY_NONE
81  *
82  */
83 
84 void bg_player_add_accelerators(bg_player_t * player,
85                                 const bg_accelerator_t * list);
86 
87 /** \ingroup player
88  *  \brief Destroy a player
89  *  \param player A player
90  */
91 
92 void bg_player_destroy(bg_player_t * player);
93 
94 /** \ingroup player
95  *  \brief Attach a message queue to a player
96  *  \param player A player
97  *  \param message_queue A mesage queue
98  */
99 
100 void bg_player_add_message_queue(bg_player_t * player,
101                                  bg_msg_queue_t * message_queue);
102 
103 /** \ingroup player
104  *  \brief Detach a message queue from a player
105  *  \param player A player
106  *  \param message_queue A mesage queue
107  */
108 
109 void bg_player_delete_message_queue(bg_player_t * player,
110                                     bg_msg_queue_t * message_queue);
111 
112 /** \ingroup player
113  *  \brief Start the player thread
114  *  \param player A player
115  */
116 
117 void bg_player_run(bg_player_t * player);
118 
119 /** \ingroup player
120  *  \brief Quit the player thread
121  *  \param player A player
122  */
123 
124 void bg_player_quit(bg_player_t * player);
125 
126 /*
127  *  Thread save functions for controlling the player (see playercmd.c)
128  *  These just create messages and send them into the command queue
129  */
130 
131 /** \defgroup player_cmd Commands, which can be sent to the player
132  *  \ingroup player
133  *
134  *  Most of these are called in an aynchronous manner.
135  *
136  *  @{
137  */
138 
139 
140 #define BG_PLAY_FLAG_IGNORE_IF_PLAYING (1<<0) //!< Ignore play command, if the player is already playing
141 #define BG_PLAY_FLAG_IGNORE_IF_STOPPED (1<<1) //!< Ignore play command, if the player is stopped
142 #define BG_PLAY_FLAG_INIT_THEN_PAUSE   (1<<2) //!< Initialize but go to pause status after
143 #define BG_PLAY_FLAG_RESUME            (1<<3) //!< If the player is paused, resume currently played track
144 
145 /** \brief Play a track
146  *  \param player A player
147  *  \param handle Handle of an open input plugin
148  *  \param track Track index to select (starting with 0)
149  *  \param flags A combination of BG_PLAY_FLAG_* flags
150  *  \param track_name Name of the track to broadcast
151  *
152  */
153 
154 void bg_player_play(bg_player_t * player, bg_plugin_handle_t * handle,
155                     int track, int flags, const char * track_name);
156 
157 /** \brief Seek to a specific time
158  *  \param player A player
159  *  \param time Time to seek to
160  *  \param scale Timescale by which the time is scaled
161  */
162 
163 void bg_player_seek(bg_player_t * player, gavl_time_t time, int scale);
164 
165 /** \brief Seek relative by a specific time
166  *  \param player A player
167  *  \param time Time offset (can be negative to seek backwards)
168  */
169 
170 void bg_player_seek_rel(bg_player_t * player, gavl_time_t time);
171 
172 /** \brief Set the volume
173  *  \param player A player
174  *  \param volume Volume (in dB, max is 0.0)
175  */
176 
177 void bg_player_set_volume(bg_player_t * player, float volume);
178 
179 /** \brief Set the volume relative
180  *  \param player A player
181  *  \param volume Volume offset (in dB)
182  */
183 
184 void bg_player_set_volume_rel(bg_player_t * player, float volume);
185 
186 /** \brief Stop playback
187  *  \param player A player
188  */
189 
190 void bg_player_stop(bg_player_t * player);
191 
192 /** \brief Toggle pause
193  *  \param player A player
194  */
195 
196 void bg_player_pause(bg_player_t * player);
197 
198 /** \brief Trigger an error
199  *  \param player A player
200  */
201 
202 void bg_player_error(bg_player_t * player);
203 
204 /** \brief Set audio output plugin
205  *  \param player A player
206  *  \param handle A plugin handle
207  */
208 
209 void bg_player_set_oa_plugin(bg_player_t * player, bg_plugin_handle_t * handle);
210 
211 /** \brief Set video output plugin
212  *  \param player A player
213  *  \param handle A plugin handle
214  */
215 
216 void bg_player_set_ov_plugin(bg_player_t * player, bg_plugin_handle_t * handle);
217 
218 /** \brief Set audio stream
219  *  \param player A player
220  *  \param stream Stream index (starts with 0, -1 means no audio playback)
221  */
222 
223 void bg_player_set_audio_stream(bg_player_t * player, int stream);
224 
225 /** \brief Set video stream
226  *  \param player A player
227  *  \param stream Stream index (starts with 0, -1 means no video playback)
228  */
229 
230 void bg_player_set_video_stream(bg_player_t * player, int stream);
231 
232 /** \brief Set subtitle stream
233  *  \param player A player
234  *  \param stream Stream index (starts with 0, -1 means no subtitle playback)
235  */
236 
237 void bg_player_set_subtitle_stream(bg_player_t * player, int stream);
238 
239 /** \brief Shut down playback
240  *  \param player A player
241  *  \param flags A combination of BG_PLAY_FLAG_* flags
242  */
243 
244 void bg_player_change(bg_player_t * player, int flags);
245 
246 /** \brief Toggle mute
247  *  \param player A player
248  */
249 
250 void bg_player_toggle_mute(bg_player_t * player);
251 
252 /** \brief Goto a specified chapter
253  *  \param player A player
254  *  \param chapter Chapter index (starting with 0)
255  */
256 
257 void bg_player_set_chapter(bg_player_t * player, int chapter);
258 
259 /** \brief Goto the next chapter
260  *  \param player A player
261  */
262 
263 void bg_player_next_chapter(bg_player_t * player);
264 
265 /** \brief Goto the previous chapter
266  *  \param player A player
267  */
268 
269 void bg_player_prev_chapter(bg_player_t * player);
270 
271 /** \brief Interrupt playback
272  *  \param player A player
273  *
274  *  This function works synchonously, this means it
275  *  is garantueed, that all playback threads are stopped
276  *  until \ref bg_player_interrupt_resume is called.
277  */
278 
279 void bg_player_interrupt(bg_player_t * player);
280 
281 /** \brief Resume an interrupted playback
282  *  \param player A player
283  */
284 
285 void bg_player_interrupt_resume(bg_player_t * player);
286 
287 /** @} */
288 
289 /** \defgroup player_cfg Player configuration
290  * \ingroup player
291  * @{
292  */
293 
294 /** \brief Get input parameters
295  *  \param player A player
296  *  \returns Null terminated parameter array.
297  *
298  *  Returned parameters can be passed to \ref bg_player_set_input_parameter
299  */
300 
301 const bg_parameter_info_t * bg_player_get_input_parameters(bg_player_t *  player);
302 
303 /** \brief Set an input parameter
304  *  \param data Player casted to void*
305  *  \param name Name
306  *  \param val Value
307  */
308 void bg_player_set_input_parameter(void * data, const char * name,
309                                    const bg_parameter_value_t * val);
310 
311 /** \brief Get audio parameters
312  *  \param player A player
313  *  \returns Null terminated parameter array.
314  *
315  *  Returned parameters can be passed to \ref bg_player_set_audio_parameter
316  */
317 
318 const bg_parameter_info_t * bg_player_get_audio_parameters(bg_player_t * player);
319 
320 /** \brief Get audio filter parameters
321  *  \param player A player
322  *  \returns Null terminated parameter array.
323  *
324  *  Returned parameters can be passed to \ref bg_player_set_audio_filter_parameter
325  */
326 
327 const bg_parameter_info_t * bg_player_get_audio_filter_parameters(bg_player_t * player);
328 
329 /** \brief Set an audio parameter
330  *  \param data Player casted to void*
331  *  \param name Name
332  *  \param val Value
333  */
334 void bg_player_set_audio_parameter(void*data, const char * name,
335                                    const bg_parameter_value_t*val);
336 
337 /** \brief Set an audio filter parameter
338  *  \param data Player casted to void*
339  *  \param name Name
340  *  \param val Value
341  */
342 void bg_player_set_audio_filter_parameter(void*data, const char * name,
343                                           const bg_parameter_value_t*val);
344 
345 /** \brief Get video parameters
346  *  \param player A player
347  *  \returns Null terminated parameter array.
348  *
349  *  Returned parameters can be passed to \ref bg_player_set_video_parameter
350  */
351 const bg_parameter_info_t * bg_player_get_video_parameters(bg_player_t * player);
352 
353 /** \brief Get video filter parameters
354  *  \param player A player
355  *  \returns Null terminated parameter array.
356  *
357  *  Returned parameters can be passed to \ref bg_player_set_video_parameter
358  */
359 const bg_parameter_info_t * bg_player_get_video_filter_parameters(bg_player_t * player);
360 
361 /** \brief Set a video parameter
362  *  \param data Player casted to void*
363  *  \param name Name
364  *  \param val Value
365  */
366 void bg_player_set_video_parameter(void*data, const char * name,
367                                    const bg_parameter_value_t*val);
368 
369 /** \brief Set a video filter parameter
370  *  \param data Player casted to void*
371  *  \param name Name
372  *  \param val Value
373  */
374 void bg_player_set_video_filter_parameter(void*data, const char * name,
375                                           const bg_parameter_value_t*val);
376 
377 /** \brief Get subtitle parameters
378  *  \param player A player
379  *  \returns Null terminated parameter array.
380  *
381  *  Returned parameters can be passed to \ref bg_player_set_subtitle_parameter
382  */
383 
384 const bg_parameter_info_t * bg_player_get_subtitle_parameters(bg_player_t * player);
385 
386 /** \brief Set a subtitle parameter
387  *  \param data Player casted to void*
388  *  \param name Name
389  *  \param val Value
390  */
391 void bg_player_set_subtitle_parameter(void*data, const char * name, const bg_parameter_value_t*val);
392 
393 /** \brief Get OSD parameters
394  *  \param player A player
395  *  \returns Null terminated parameter array.
396  *
397  *  Returned parameters can be passed to \ref bg_player_set_osd_parameter
398  */
399 
400 const bg_parameter_info_t * bg_player_get_osd_parameters(bg_player_t * player);
401 
402 /** \brief Set an OSD parameter
403  *  \param data Player casted to void*
404  *  \param name Name
405  *  \param val Value
406  */
407 
408 void bg_player_set_osd_parameter(void*data, const char * name, const bg_parameter_value_t*val);
409 
410 /** \brief En- or disable music visualizations
411  *  \param p A player
412  *  \param enable 1 to enable visualizations, 0 to disable them
413  *
414  *  Visualizations are only enabled if you passed 1 to this function
415  *  and the video window is not used otherwise
416  */
417 
418 void
419 bg_player_set_visualization(bg_player_t * p, int enable);
420 
421 /** \brief Set plugin used for visualizations
422  *  \param p A player
423  *  \param plugin_info Plugin info
424  */
425 
426 void
427 bg_player_set_visualization_plugin(bg_player_t * p, const bg_plugin_info_t * plugin_info);
428 
429 
430 /** \brief Get visualization parameters
431  *  \param player A player
432  *  \returns Null terminated parameter array.
433  *
434  *  Returned parameters can be passed to
435  *  \ref bg_player_set_visualization_parameter
436  */
437 
438 const bg_parameter_info_t *
439 bg_player_get_visualization_parameters(bg_player_t *  player);
440 
441 /** \brief Set a visualization parameter
442  *  \param data Player casted to void*
443  *  \param name Name
444  *  \param val Value
445  */
446 
447 void
448 bg_player_set_visualization_parameter(void*data,
449                                       const char * name, const bg_parameter_value_t*val);
450 
451 /** \brief Set a parameter for a visuaization plugin
452  *  \param data Player casted to void*
453  *  \param name Name
454  *  \param val Value
455  */
456 void
457 bg_player_set_visualization_plugin_parameter(void*data,
458                                              const char * name,
459                                              const bg_parameter_value_t*val);
460 
461 
462 /** @} */
463 
464 
465 
466 #endif // __BG_PLAYER_H_
467