libvlc_media.h 14.9 KB
Newer Older
1 2 3
/*****************************************************************************
 * libvlc.h:  libvlc external API
 *****************************************************************************
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
4
 * Copyright (C) 1998-2009 VLC authors and VideoLAN
5 6 7 8 9 10
 * $Id$
 *
 * Authors: Clément Stenac <zorglub@videolan.org>
 *          Jean-Paul Saman <jpsaman@videolan.org>
 *          Pierre d'Herbemont <pdherbemont@videolan.org>
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
11 12 13
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
14 15 16 17
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
18 19
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
20
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
21 22 23
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24 25 26 27 28 29 30 31 32 33
 *****************************************************************************/

/**
 * \file
 * This file defines libvlc_media external API
 */

#ifndef VLC_LIBVLC_MEDIA_H
#define VLC_LIBVLC_MEDIA_H 1

34 35 36 37
# ifdef __cplusplus
extern "C" {
# endif

38
/** \defgroup libvlc_media LibVLC media
39
 * \ingroup libvlc
40 41
 * @ref libvlc_media_t is an abstract representation of a playable media.
 * It consists of a media location and various optional meta data.
42 43 44 45 46
 * @{
 */

typedef struct libvlc_media_t libvlc_media_t;

47
/** defgroup libvlc_meta LibVLC meta data
48 49 50 51
 * \ingroup libvlc_media
 * @{
 */

52
/** Meta data types */
53
typedef enum libvlc_meta_t {
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
    libvlc_meta_Title,
    libvlc_meta_Artist,
    libvlc_meta_Genre,
    libvlc_meta_Copyright,
    libvlc_meta_Album,
    libvlc_meta_TrackNumber,
    libvlc_meta_Description,
    libvlc_meta_Rating,
    libvlc_meta_Date,
    libvlc_meta_Setting,
    libvlc_meta_URL,
    libvlc_meta_Language,
    libvlc_meta_NowPlaying,
    libvlc_meta_Publisher,
    libvlc_meta_EncodedBy,
    libvlc_meta_ArtworkURL,
70
    libvlc_meta_TrackID
71
    /* Add new meta types HERE */
72
} libvlc_meta_t;
73 74 75 76 77

/** @}*/

/**
 * Note the order of libvlc_state_t enum must match exactly the order of
78
 * \see mediacontrol_PlayerStatus, \see input_state_e enums,
79 80 81 82 83 84
 * and VideoLAN.LibVLC.State (at bindings/cil/src/media.cs).
 *
 * Expected states by web plugins are:
 * IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4,
 * STOPPING=5, ENDED=6, ERROR=7
 */
85
typedef enum libvlc_state_t
86 87 88 89 90 91 92 93 94
{
    libvlc_NothingSpecial=0,
    libvlc_Opening,
    libvlc_Buffering,
    libvlc_Playing,
    libvlc_Paused,
    libvlc_Stopped,
    libvlc_Ended,
    libvlc_Error
95
} libvlc_state_t;
96

97
enum
98 99 100
{
    libvlc_media_option_trusted = 0x2,
    libvlc_media_option_unique = 0x100
101
};
102

103
typedef enum libvlc_track_type_t
104
{
105 106 107
    libvlc_track_unknown   = -1,
    libvlc_track_audio     = 0,
    libvlc_track_video     = 1,
108
    libvlc_track_text      = 2
109
} libvlc_track_type_t;
110

111
/** defgroup libvlc_media_stats_t LibVLC media statistics
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
 * \ingroup libvlc_media
 * @{
 */
typedef struct libvlc_media_stats_t
{
    /* Input */
    int         i_read_bytes;
    float       f_input_bitrate;

    /* Demux */
    int         i_demux_read_bytes;
    float       f_demux_bitrate;
    int         i_demux_corrupted;
    int         i_demux_discontinuity;

    /* Decoders */
    int         i_decoded_video;
    int         i_decoded_audio;

    /* Video Output */
    int         i_displayed_pictures;
    int         i_lost_pictures;

    /* Audio output */
    int         i_played_abuffers;
    int         i_lost_abuffers;

    /* Stream output */
    int         i_sent_packets;
    int         i_sent_bytes;
    float       f_send_bitrate;
} libvlc_media_stats_t;
/** @}*/

146
typedef struct libvlc_media_track_info_t
147 148 149
{
    /* Codec fourcc */
    uint32_t    i_codec;
150
    int         i_id;
151
    libvlc_track_type_t i_type;
152 153 154 155 156

    /* Codec specific */
    int         i_profile;
    int         i_level;

157 158 159 160 161 162 163 164 165 166 167 168
    union {
        struct {
            /* Audio specific */
            unsigned    i_channels;
            unsigned    i_rate;
        } audio;
        struct {
            /* Video specific */
            unsigned    i_height;
            unsigned    i_width;
        } video;
    } u;
169

170
} libvlc_media_track_info_t;
171

172

173
/**
174 175 176 177 178 179 180
 * Create a media with a certain given media resource location,
 * for instance a valid URL.
 *
 * \note To refer to a local file with this function,
 * the file://... URI syntax <b>must</b> be used (see IETF RFC3986).
 * We recommend using libvlc_media_new_path() instead when dealing with
 * local files.
181
 *
182 183
 * \see libvlc_media_release
 *
184
 * \param p_instance the instance
185
 * \param psz_mrl the media location
186
 * \return the newly created media or NULL on error
187
 */
188
LIBVLC_API libvlc_media_t *libvlc_media_new_location(
189
                                   libvlc_instance_t *p_instance,
190
                                   const char * psz_mrl );
191

192
/**
193
 * Create a media for a certain file path.
194
 *
195 196
 * \see libvlc_media_release
 *
197 198 199 200
 * \param p_instance the instance
 * \param path local filesystem path
 * \return the newly created media or NULL on error
 */
201
LIBVLC_API libvlc_media_t *libvlc_media_new_path(
202 203 204
                                   libvlc_instance_t *p_instance,
                                   const char *path );

Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228
/**
 * Create a media for an already open file descriptor.
 * The file descriptor shall be open for reading (or reading and writing).
 *
 * Regular file descriptors, pipe read descriptors and character device
 * descriptors (including TTYs) are supported on all platforms.
 * Block device descriptors are supported where available.
 * Directory descriptors are supported on systems that provide fdopendir().
 * Sockets are supported on all platforms where they are file descriptors,
 * i.e. all except Windows.
 *
 * \note This library will <b>not</b> automatically close the file descriptor
 * under any circumstance. Nevertheless, a file descriptor can usually only be
 * rendered once in a media player. To render it a second time, the file
 * descriptor should probably be rewound to the beginning with lseek().
 *
 * \see libvlc_media_release
 *
 * \version LibVLC 1.1.5 and later.
 *
 * \param p_instance the instance
 * \param fd open file descriptor
 * \return the newly created media or NULL on error
 */
229
LIBVLC_API libvlc_media_t *libvlc_media_new_fd(
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
230 231 232 233
                                   libvlc_instance_t *p_instance,
                                   int fd );


234
/**
235
 * Create a media as an empty node with a given name.
236
 *
237 238
 * \see libvlc_media_release
 *
239 240
 * \param p_instance the instance
 * \param psz_name the name of the node
241
 * \return the new empty media or NULL on error
242
 */
243
LIBVLC_API libvlc_media_t *libvlc_media_new_as_node(
244
                                   libvlc_instance_t *p_instance,
245
                                   const char * psz_name );
246 247 248 249 250 251 252 253 254 255

/**
 * Add an option to the media.
 *
 * This option will be used to determine how the media_player will
 * read the media. This allows to use VLC's advanced
 * reading/streaming options on a per-media basis.
 *
 * The options are detailed in vlc --long-help, for instance "--sout-all"
 *
256
 * \param p_md the media descriptor
257 258
 * \param ppsz_options the options (as a string)
 */
259
LIBVLC_API void libvlc_media_add_option(
260
                                   libvlc_media_t *p_md,
261 262
                                   const char * ppsz_options );

263
/**
264
 * Add an option to the media with configurable flags.
265 266 267 268 269 270 271
 *
 * This option will be used to determine how the media_player will
 * read the media. This allows to use VLC's advanced
 * reading/streaming options on a per-media basis.
 *
 * The options are detailed in vlc --long-help, for instance "--sout-all"
 *
272
 * \param p_md the media descriptor
273
 * \param ppsz_options the options (as a string)
274
 * \param i_flags the flags for this option
275
 */
276
LIBVLC_API void libvlc_media_add_option_flag(
277
                                   libvlc_media_t *p_md,
278
                                   const char * ppsz_options,
279
                                   unsigned i_flags );
280 281 282 283 284 285 286


/**
 * Retain a reference to a media descriptor object (libvlc_media_t). Use
 * libvlc_media_release() to decrement the reference count of a
 * media descriptor object.
 *
287
 * \param p_md the media descriptor
288
 */
289
LIBVLC_API void libvlc_media_retain( libvlc_media_t *p_md );
290 291 292 293 294 295 296 297

/**
 * Decrement the reference count of a media descriptor object. If the
 * reference count is 0, then libvlc_media_release() will release the
 * media descriptor object. It will send out an libvlc_MediaFreed event
 * to all listeners. If the media descriptor object has been released it
 * should not be used again.
 *
298
 * \param p_md the media descriptor
299
 */
300
LIBVLC_API void libvlc_media_release( libvlc_media_t *p_md );
301 302 303 304 305 306 307 308


/**
 * Get the media resource locator (mrl) from a media descriptor object
 *
 * \param p_md a media descriptor object
 * \return string with mrl of media descriptor object
 */
309
LIBVLC_API char *libvlc_media_get_mrl( libvlc_media_t *p_md );
310 311 312 313

/**
 * Duplicate a media descriptor object.
 *
314
 * \param p_md a media descriptor object.
315
 */
316
LIBVLC_API libvlc_media_t *libvlc_media_duplicate( libvlc_media_t *p_md );
317 318 319 320

/**
 * Read the meta of the media.
 *
321 322 323 324 325 326 327 328 329 330
 * If the media has not yet been parsed this will return NULL.
 *
 * This methods automatically calls libvlc_media_parse_async(), so after calling
 * it you may receive a libvlc_MediaMetaChanged event. If you prefer a synchronous
 * version ensure that you call libvlc_media_parse() before get_meta().
 *
 * \see libvlc_media_parse
 * \see libvlc_media_parse_async
 * \see libvlc_MediaMetaChanged
 *
331
 * \param p_md the media descriptor
332
 * \param e_meta the meta to read
333 334
 * \return the media's meta
 */
335
LIBVLC_API char *libvlc_media_get_meta( libvlc_media_t *p_md,
336
                                             libvlc_meta_t e_meta );
337

Rémi Duraffort's avatar
Rémi Duraffort committed
338 339 340 341 342
/**
 * Set the meta of the media (this function will not save the meta, call
 * libvlc_media_save_meta in order to save the meta)
 *
 * \param p_md the media descriptor
Rémi Duraffort's avatar
Rémi Duraffort committed
343
 * \param e_meta the meta to write
344
 * \param psz_value the media's meta
Rémi Duraffort's avatar
Rémi Duraffort committed
345
 */
346
LIBVLC_API void libvlc_media_set_meta( libvlc_media_t *p_md,
Rémi Duraffort's avatar
Rémi Duraffort committed
347 348 349 350 351 352 353 354
                                           libvlc_meta_t e_meta,
                                           const char *psz_value );


/**
 * Save the meta previously set
 *
 * \param p_md the media desriptor
Rémi Duraffort's avatar
Rémi Duraffort committed
355
 * \return true if the write operation was successfull
Rémi Duraffort's avatar
Rémi Duraffort committed
356
 */
357
LIBVLC_API int libvlc_media_save_meta( libvlc_media_t *p_md );
Rémi Duraffort's avatar
Rémi Duraffort committed
358 359


360 361 362 363 364 365 366
/**
 * Get current state of media descriptor object. Possible media states
 * are defined in libvlc_structures.c ( libvlc_NothingSpecial=0,
 * libvlc_Opening, libvlc_Buffering, libvlc_Playing, libvlc_Paused,
 * libvlc_Stopped, libvlc_Ended,
 * libvlc_Error).
 *
367 368
 * \see libvlc_state_t
 * \param p_md a media descriptor object
369 370
 * \return state of media descriptor object
 */
371
LIBVLC_API libvlc_state_t libvlc_media_get_state(
372
                                   libvlc_media_t *p_md );
373 374


375
/**
376 377 378
 * Get the current statistics about the media
 * \param p_md: media descriptor object
 * \param p_stats: structure that contain the statistics about the media
379
 *                 (this structure must be allocated by the caller)
380
 * \return true if the statistics are available, false otherwise
381 382
 *
 * \libvlc_return_bool
383
 */
384
LIBVLC_API int libvlc_media_get_stats( libvlc_media_t *p_md,
385 386
                                           libvlc_media_stats_t *p_stats );

387 388 389 390 391 392 393 394 395 396 397 398 399
/**
 * Get subitems of media descriptor object. This will increment
 * the reference count of supplied media descriptor object. Use
 * libvlc_media_list_release() to decrement the reference counting.
 *
 * \param p_md media descriptor object
 * \return list of media descriptor subitems or NULL
 */

/* This method uses libvlc_media_list_t, however, media_list usage is optionnal
 * and this is here for convenience */
#define VLC_FORWARD_DECLARE_OBJECT(a) struct a

400
LIBVLC_API VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t *)
401
libvlc_media_subitems( libvlc_media_t *p_md );
402 403 404 405 406 407 408 409

/**
 * Get event manager from media descriptor object.
 * NOTE: this function doesn't increment reference counting.
 *
 * \param p_md a media descriptor object
 * \return event manager object
 */
410
LIBVLC_API libvlc_event_manager_t *
411
    libvlc_media_event_manager( libvlc_media_t *p_md );
412 413

/**
414
 * Get duration (in ms) of media descriptor object item.
415 416
 *
 * \param p_md media descriptor object
417
 * \return duration of media item or -1 on error
418
 */
419
LIBVLC_API libvlc_time_t
420
   libvlc_media_get_duration( libvlc_media_t *p_md );
421

422 423 424 425 426 427 428 429
/**
 * Parse a media.
 *
 * This fetches (local) meta data and tracks information.
 * The method is synchronous.
 *
 * \see libvlc_media_parse_async
 * \see libvlc_media_get_meta
430
 * \see libvlc_media_get_tracks_info
431
 *
432
 * \param p_md media descriptor object
433
 */
434
LIBVLC_API void
435
libvlc_media_parse( libvlc_media_t *p_md );
436 437 438 439 440

/**
 * Parse a media.
 *
 * This fetches (local) meta data and tracks information.
441
 * The method is the asynchronous of libvlc_media_parse().
442
 *
443 444
 * To track when this is over you can listen to libvlc_MediaParsedChanged
 * event. However if the media was already parsed you will not receive this
445 446 447
 * event.
 *
 * \see libvlc_media_parse
448
 * \see libvlc_MediaParsedChanged
449
 * \see libvlc_media_get_meta
450
 * \see libvlc_media_get_tracks_info
451
 *
452
 * \param p_md media descriptor object
453
 */
454
LIBVLC_API void
455
libvlc_media_parse_async( libvlc_media_t *p_md );
456

457
/**
458 459 460
 * Get Parsed status for media descriptor object.
 *
 * \see libvlc_MediaParsedChanged
461 462
 *
 * \param p_md media descriptor object
463
 * \return true if media object has been parsed otherwise it returns false
464 465
 *
 * \libvlc_return_bool
466
 */
467
LIBVLC_API int
468
   libvlc_media_is_parsed( libvlc_media_t *p_md );
469 470 471 472 473 474 475 476 477

/**
 * Sets media descriptor's user_data. user_data is specialized data
 * accessed by the host application, VLC.framework uses it as a pointer to
 * an native object that references a libvlc_media_t pointer
 *
 * \param p_md media descriptor object
 * \param p_new_user_data pointer to user data
 */
478
LIBVLC_API void
479
    libvlc_media_set_user_data( libvlc_media_t *p_md, void *p_new_user_data );
480 481 482 483 484 485 486 487

/**
 * Get media descriptor's user_data. user_data is specialized data
 * accessed by the host application, VLC.framework uses it as a pointer to
 * an native object that references a libvlc_media_t pointer
 *
 * \param p_md media descriptor object
 */
488
LIBVLC_API void *libvlc_media_get_user_data( libvlc_media_t *p_md );
489

490 491 492
/**
 * Get media descriptor's elementary streams description
 *
493 494
 * Note, you need to call libvlc_media_parse() or play the media at least once
 * before calling this function.
495
 * Not doing this will result in an empty array.
496
 *
497
 * \param p_md media descriptor object
498 499
 * \param tracks address to store an allocated array of Elementary Streams
 * descriptions (must be freed by the caller)
500
 *
501
 * \return the number of Elementary Streams
502
 */
503
LIBVLC_API
504 505
int libvlc_media_get_tracks_info( libvlc_media_t *p_md,
                                  libvlc_media_track_info_t **tracks );
506

507 508
/** @}*/

509 510 511 512
# ifdef __cplusplus
}
# endif

513
#endif /* VLC_LIBVLC_MEDIA_H */