include/vlc/libvlc_vlm.h

   1 /*****************************************************************************
   2  * libvlc_vlm.h:  libvlc_* new external API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2008 VLC authors and VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Clément Stenac <zorglub@videolan.org>
   8  *          Jean-Paul Saman <jpsaman _at_ m2x _dot_ nl>
   9  *
  10  * This program is free software; you can redistribute it and/or modify it
  11  * under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation; either version 2.1 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with this program; if not, write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  23  *****************************************************************************/
  24
  25 #ifndef LIBVLC_VLM_H
  26 #define LIBVLC_VLM_H 1
  27
  28 # ifdef __cplusplus
  29 extern "C" {
  30 # endif
  31
  32 /** \defgroup libvlc_vlm LibVLC VLM
  33  * \ingroup libvlc
  34  * @{
  35  * \file
  36  * LibVLC stream output manager external API
  37  */
  38
  39 /**
  40  * Release the vlm instance related to the given libvlc_instance_t
  41  *
  42  * \param p_instance the instance
  43  */
  44 LIBVLC_API void libvlc_vlm_release( libvlc_instance_t *p_instance );
  45
  46 /**
  47  * Add a broadcast, with one input.
  48  *
  49  * \param p_instance the instance
  50  * \param psz_name the name of the new broadcast
  51  * \param psz_input the input MRL
  52  * \param psz_output the output MRL (the parameter to the "sout" variable)
  53  * \param i_options number of additional options
  54  * \param ppsz_options additional options
  55  * \param b_enabled boolean for enabling the new broadcast
  56  * \param b_loop Should this broadcast be played in loop ?
  57  * \return 0 on success, -1 on error
  58  */
  59 LIBVLC_API int libvlc_vlm_add_broadcast( libvlc_instance_t *p_instance,
  60                                              const char *psz_name, const char *psz_input,
  61                                              const char *psz_output, int i_options,
  62                                              const char * const* ppsz_options,
  63                                              int b_enabled, int b_loop );
  64
  65 /**
  66  * Add a vod, with one input.
  67  *
  68  * \param p_instance the instance
  69  * \param psz_name the name of the new vod media
  70  * \param psz_input the input MRL
  71  * \param i_options number of additional options
  72  * \param ppsz_options additional options
  73  * \param b_enabled boolean for enabling the new vod
  74  * \param psz_mux the muxer of the vod media
  75  * \return 0 on success, -1 on error
  76  */
  77 LIBVLC_API int libvlc_vlm_add_vod( libvlc_instance_t * p_instance,
  78                                        const char *psz_name, const char *psz_input,
  79                                        int i_options, const char * const* ppsz_options,
  80                                        int b_enabled, const char *psz_mux );
  81
  82 /**
  83  * Delete a media (VOD or broadcast).
  84  *
  85  * \param p_instance the instance
  86  * \param psz_name the media to delete
  87  * \return 0 on success, -1 on error
  88  */
  89 LIBVLC_API int libvlc_vlm_del_media( libvlc_instance_t * p_instance,
  90                                          const char *psz_name );
  91
  92 /**
  93  * Enable or disable a media (VOD or broadcast).
  94  *
  95  * \param p_instance the instance
  96  * \param psz_name the media to work on
  97  * \param b_enabled the new status
  98  * \return 0 on success, -1 on error
  99  */
 100 LIBVLC_API int libvlc_vlm_set_enabled( libvlc_instance_t *p_instance,
 101                                            const char *psz_name, int b_enabled );
 102
 103 /**
 104  * Set the output for a media.
 105  *
 106  * \param p_instance the instance
 107  * \param psz_name the media to work on
 108  * \param psz_output the output MRL (the parameter to the "sout" variable)
 109  * \return 0 on success, -1 on error
 110  */
 111 LIBVLC_API int libvlc_vlm_set_output( libvlc_instance_t *p_instance,
 112                                           const char *psz_name,
 113                                           const char *psz_output );
 114
 115 /**
 116  * Set a media's input MRL. This will delete all existing inputs and
 117  * add the specified one.
 118  *
 119  * \param p_instance the instance
 120  * \param psz_name the media to work on
 121  * \param psz_input the input MRL
 122  * \return 0 on success, -1 on error
 123  */
 124 LIBVLC_API int libvlc_vlm_set_input( libvlc_instance_t *p_instance,
 125                                          const char *psz_name,
 126                                          const char *psz_input );
 127
 128 /**
 129  * Add a media's input MRL. This will add the specified one.
 130  *
 131  * \param p_instance the instance
 132  * \param psz_name the media to work on
 133  * \param psz_input the input MRL
 134  * \return 0 on success, -1 on error
 135  */
 136 LIBVLC_API int libvlc_vlm_add_input( libvlc_instance_t *p_instance,
 137                                          const char *psz_name,
 138                                          const char *psz_input );
 139
 140 /**
 141  * Set a media's loop status.
 142  *
 143  * \param p_instance the instance
 144  * \param psz_name the media to work on
 145  * \param b_loop the new status
 146  * \return 0 on success, -1 on error
 147  */
 148 LIBVLC_API int libvlc_vlm_set_loop( libvlc_instance_t *p_instance,
 149                                         const char *psz_name,
 150                                         int b_loop );
 151
 152 /**
 153  * Set a media's vod muxer.
 154  *
 155  * \param p_instance the instance
 156  * \param psz_name the media to work on
 157  * \param psz_mux the new muxer
 158  * \return 0 on success, -1 on error
 159  */
 160 LIBVLC_API int libvlc_vlm_set_mux( libvlc_instance_t *p_instance,
 161                                        const char *psz_name,
 162                                        const char *psz_mux );
 163
 164 /**
 165  * Edit the parameters of a media. This will delete all existing inputs and
 166  * add the specified one.
 167  *
 168  * \param p_instance the instance
 169  * \param psz_name the name of the new broadcast
 170  * \param psz_input the input MRL
 171  * \param psz_output the output MRL (the parameter to the "sout" variable)
 172  * \param i_options number of additional options
 173  * \param ppsz_options additional options
 174  * \param b_enabled boolean for enabling the new broadcast
 175  * \param b_loop Should this broadcast be played in loop ?
 176  * \return 0 on success, -1 on error
 177  */
 178 LIBVLC_API int libvlc_vlm_change_media( libvlc_instance_t *p_instance,
 179                                             const char *psz_name, const char *psz_input,
 180                                             const char *psz_output, int i_options,
 181                                             const char * const *ppsz_options,
 182                                             int b_enabled, int b_loop );
 183
 184 /**
 185  * Play the named broadcast.
 186  *
 187  * \param p_instance the instance
 188  * \param psz_name the name of the broadcast
 189  * \return 0 on success, -1 on error
 190  */
 191 LIBVLC_API int libvlc_vlm_play_media ( libvlc_instance_t *p_instance,
 192                                            const char *psz_name );
 193
 194 /**
 195  * Stop the named broadcast.
 196  *
 197  * \param p_instance the instance
 198  * \param psz_name the name of the broadcast
 199  * \return 0 on success, -1 on error
 200  */
 201 LIBVLC_API int libvlc_vlm_stop_media ( libvlc_instance_t *p_instance,
 202                                            const char *psz_name );
 203
 204 /**
 205  * Pause the named broadcast.
 206  *
 207  * \param p_instance the instance
 208  * \param psz_name the name of the broadcast
 209  * \return 0 on success, -1 on error
 210  */
 211 LIBVLC_API int libvlc_vlm_pause_media( libvlc_instance_t *p_instance,
 212                                            const char *psz_name );
 213
 214 /**
 215  * Seek in the named broadcast.
 216  *
 217  * \param p_instance the instance
 218  * \param psz_name the name of the broadcast
 219  * \param f_percentage the percentage to seek to
 220  * \return 0 on success, -1 on error
 221  */
 222 LIBVLC_API int libvlc_vlm_seek_media( libvlc_instance_t *p_instance,
 223                                           const char *psz_name,
 224                                           float f_percentage );
 225
 226 /**
 227  * Return information about the named media as a JSON
 228  * string representation.
 229  *
 230  * This function is mainly intended for debugging use,
 231  * if you want programmatic access to the state of
 232  * a vlm_media_instance_t, please use the corresponding
 233  * libvlc_vlm_get_media_instance_xxx -functions.
 234  * Currently there are no such functions available for
 235  * vlm_media_t though.
 236  *
 237  * \param p_instance the instance
 238  * \param psz_name the name of the media,
 239  *      if the name is an empty string, all media is described
 240  * \return string with information about named media, or NULL on error
 241  */
 242 LIBVLC_API const char* libvlc_vlm_show_media( libvlc_instance_t *p_instance,
 243                                                   const char *psz_name );
 244
 245 /**
 246  * Get vlm_media instance position by name or instance id
 247  *
 248  * \param p_instance a libvlc instance
 249  * \param psz_name name of vlm media instance
 250  * \param i_instance instance id
 251  * \return position as float or -1. on error
 252  */
 253 LIBVLC_API float libvlc_vlm_get_media_instance_position( libvlc_instance_t *p_instance,
 254                                                              const char *psz_name,
 255                                                              int i_instance );
 256
 257 /**
 258  * Get vlm_media instance time by name or instance id
 259  *
 260  * \param p_instance a libvlc instance
 261  * \param psz_name name of vlm media instance
 262  * \param i_instance instance id
 263  * \return time as integer or -1 on error
 264  */
 265 LIBVLC_API int libvlc_vlm_get_media_instance_time( libvlc_instance_t *p_instance,
 266                                                        const char *psz_name,
 267                                                        int i_instance );
 268
 269 /**
 270  * Get vlm_media instance length by name or instance id
 271  *
 272  * \param p_instance a libvlc instance
 273  * \param psz_name name of vlm media instance
 274  * \param i_instance instance id
 275  * \return length of media item or -1 on error
 276  */
 277 LIBVLC_API int libvlc_vlm_get_media_instance_length( libvlc_instance_t *p_instance,
 278                                                          const char *psz_name,
 279                                                          int i_instance );
 280
 281 /**
 282  * Get vlm_media instance playback rate by name or instance id
 283  *
 284  * \param p_instance a libvlc instance
 285  * \param psz_name name of vlm media instance
 286  * \param i_instance instance id
 287  * \return playback rate or -1 on error
 288  */
 289 LIBVLC_API int libvlc_vlm_get_media_instance_rate( libvlc_instance_t *p_instance,
 290                                                        const char *psz_name,
 291                                                        int i_instance );
 292 #if 0
 293 /**
 294  * Get vlm_media instance title number by name or instance id
 295  * \bug will always return 0
 296  * \param p_instance a libvlc instance
 297  * \param psz_name name of vlm media instance
 298  * \param i_instance instance id
 299  * \return title as number or -1 on error
 300  */
 301 LIBVLC_API int libvlc_vlm_get_media_instance_title( libvlc_instance_t *,
 302                                                         const char *, int );
 303
 304 /**
 305  * Get vlm_media instance chapter number by name or instance id
 306  * \bug will always return 0
 307  * \param p_instance a libvlc instance
 308  * \param psz_name name of vlm media instance
 309  * \param i_instance instance id
 310  * \return chapter as number or -1 on error
 311  */
 312 LIBVLC_API int libvlc_vlm_get_media_instance_chapter( libvlc_instance_t *,
 313                                                           const char *, int );
 314
 315 /**
 316  * Is libvlc instance seekable ?
 317  * \bug will always return 0
 318  * \param p_instance a libvlc instance
 319  * \param psz_name name of vlm media instance
 320  * \param i_instance instance id
 321  * \return 1 if seekable, 0 if not, -1 if media does not exist
 322  */
 323 LIBVLC_API int libvlc_vlm_get_media_instance_seekable( libvlc_instance_t *,
 324                                                            const char *, int );
 325 #endif
 326 /**
 327  * Get libvlc_event_manager from a vlm media.
 328  * The p_event_manager is immutable, so you don't have to hold the lock
 329  *
 330  * \param p_instance a libvlc instance
 331  * \return libvlc_event_manager
 332  */
 333 LIBVLC_API libvlc_event_manager_t *
 334     libvlc_vlm_get_event_manager( libvlc_instance_t *p_instance );
 335
 336 /** @} */
 337
 338 # ifdef __cplusplus
 339 }
 340 # endif
 341
 342 #endif /* <vlc/libvlc_vlm.h> */