libvlc_media_player.h 88.4 KB
Newer Older
1 2 3
/*****************************************************************************
 * libvlc_media_player.h:  libvlc_media_player external API
 *****************************************************************************
4
 * Copyright (C) 1998-2015 VLC authors and VideoLAN
5 6 7 8 9
 *
 * 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
10 11 12
 * 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
13 14 15 16
 * (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
17 18
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
19
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
20 21 22
 * 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.
23 24 25 26 27
 *****************************************************************************/

#ifndef VLC_LIBVLC_MEDIA_PLAYER_H
#define VLC_LIBVLC_MEDIA_PLAYER_H 1

28 29
# ifdef __cplusplus
extern "C" {
30 31
# else
#  include <stdbool.h>
32 33
# endif

34
/** \defgroup libvlc_media_player LibVLC media player
35
 * \ingroup libvlc
36
 * A LibVLC media player plays one media (usually in a custom drawable).
37
 * @{
38 39
 * \file
 * LibVLC simple media player external API
40 41 42 43
 */

typedef struct libvlc_media_player_t libvlc_media_player_t;

44
/**
45
 * Description for titles
46
 */
47 48 49 50 51 52
enum
{
    libvlc_title_menu          = 0x01,
    libvlc_title_interactive   = 0x02
};

53 54
typedef struct libvlc_title_description_t
{
55 56
    int64_t i_duration; /**< duration in milliseconds */
    char *psz_name; /**< title name */
57
    unsigned i_flags; /**< info if item was recognized as a menu, interactive or plain content by the demuxer */
58 59
} libvlc_title_description_t;

60
/**
61
 * Description for chapters
62 63 64
 */
typedef struct libvlc_chapter_description_t
{
65 66 67
    int64_t i_time_offset; /**< time-offset of the chapter in milliseconds */
    int64_t i_duration; /**< duration of the chapter in milliseconds */
    char *psz_name; /**< chapter name */
68 69
} libvlc_chapter_description_t;

70 71 72 73 74 75 76 77 78
/**
 * Description for audio output. It contains
 * name, description and pointer to next record.
 */
typedef struct libvlc_audio_output_t
{
    char *psz_name;
    char *psz_description;
    struct libvlc_audio_output_t *p_next;
79

80 81
} libvlc_audio_output_t;

82 83 84 85 86 87 88 89 90 91 92
/**
 * Description for audio output device.
 */
typedef struct libvlc_audio_output_device_t
{
    struct libvlc_audio_output_device_t *p_next; /**< Next entry in list */
    char *psz_device; /**< Device identifier string */
    char *psz_description; /**< User-friendly device description */
    /* More fields may be added here in later versions */
} libvlc_audio_output_device_t;

93
/**
94
 * Marq options definition
95
 */
96
typedef enum libvlc_video_marquee_option_t {
97
    libvlc_marquee_Enable = 0,
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
98
    libvlc_marquee_Text,                  /** string argument */
99 100 101 102 103 104 105
    libvlc_marquee_Color,
    libvlc_marquee_Opacity,
    libvlc_marquee_Position,
    libvlc_marquee_Refresh,
    libvlc_marquee_Size,
    libvlc_marquee_Timeout,
    libvlc_marquee_X,
106
    libvlc_marquee_Y
107
} libvlc_video_marquee_option_t;
108

109 110 111 112 113 114 115 116 117
/**
 * Navigation mode
 */
typedef enum libvlc_navigate_mode_t
{
    libvlc_navigate_activate = 0,
    libvlc_navigate_up,
    libvlc_navigate_down,
    libvlc_navigate_left,
118 119
    libvlc_navigate_right,
    libvlc_navigate_popup
120 121
} libvlc_navigate_mode_t;

122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
/**
 * Enumeration of values used to set position (e.g. of video title).
 */
typedef enum libvlc_position_t {
    libvlc_position_disable=-1,
    libvlc_position_center,
    libvlc_position_left,
    libvlc_position_right,
    libvlc_position_top,
    libvlc_position_top_left,
    libvlc_position_top_right,
    libvlc_position_bottom,
    libvlc_position_bottom_left,
    libvlc_position_bottom_right
} libvlc_position_t;

138 139 140 141 142 143 144 145 146 147 148 149
/**
 * Enumeration of teletext keys than can be passed via
 * libvlc_video_set_teletext()
 */
typedef enum libvlc_teletext_key_t {
    libvlc_teletext_key_red = 'r' << 16,
    libvlc_teletext_key_green = 'g' << 16,
    libvlc_teletext_key_yellow = 'y' << 16,
    libvlc_teletext_key_blue = 'b' << 16,
    libvlc_teletext_key_index = 'i' << 16,
} libvlc_teletext_key_t;

Mark Lee's avatar
Mark Lee committed
150 151 152 153 154 155 156
/**
 * Opaque equalizer handle.
 *
 * Equalizer settings can be applied to a media player.
 */
typedef struct libvlc_equalizer_t libvlc_equalizer_t;

157 158 159 160 161
/**
 * Create an empty Media Player object
 *
 * \param p_libvlc_instance the libvlc instance in which the Media Player
 *        should be created.
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
162
 * \return a new media player object, or NULL on error.
163
 * It must be released by libvlc_media_player_release().
164
 */
165
LIBVLC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p_libvlc_instance );
166 167 168 169 170 171

/**
 * Create a Media Player object from a Media
 *
 * \param p_md the media. Afterwards the p_md can be safely
 *        destroyed.
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
172
 * \return a new media player object, or NULL on error.
173
 * It must be released by libvlc_media_player_release().
174
 */
175
LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *p_md );
176 177 178 179 180 181 182 183 184 185

/**
 * Release a media_player after use
 * Decrement the reference count of a media player object. If the
 * reference count is 0, then libvlc_media_player_release() will
 * release the media player object. If the media player object
 * has been released, then it should not be used again.
 *
 * \param p_mi the Media Player to free
 */
186
LIBVLC_API void libvlc_media_player_release( libvlc_media_player_t *p_mi );
187 188 189 190 191 192 193

/**
 * Retain a reference to a media player object. Use
 * libvlc_media_player_release() to decrement reference count.
 *
 * \param p_mi media player object
 */
194
LIBVLC_API void libvlc_media_player_retain( libvlc_media_player_t *p_mi );
195 196 197 198 199 200 201 202 203

/**
 * Set the media that will be used by the media_player. If any,
 * previous md will be released.
 *
 * \param p_mi the Media Player
 * \param p_md the Media. Afterwards the p_md can be safely
 *        destroyed.
 */
204
LIBVLC_API void libvlc_media_player_set_media( libvlc_media_player_t *p_mi,
205
                                                   libvlc_media_t *p_md );
206 207 208 209 210 211 212 213

/**
 * Get the media used by the media_player.
 *
 * \param p_mi the Media Player
 * \return the media associated with p_mi, or NULL if no
 *         media is associated
 */
214
LIBVLC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t *p_mi );
215 216 217 218 219 220 221

/**
 * Get the Event Manager from which the media player send event.
 *
 * \param p_mi the Media Player
 * \return the event manager associated with p_mi
 */
222
LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *p_mi );
223 224 225 226 227

/**
 * is_playing
 *
 * \param p_mi the Media Player
228 229
 * \retval true media player is playing
 * \retval false media player is not playing
230
 */
231
LIBVLC_API bool libvlc_media_player_is_playing(libvlc_media_player_t *p_mi);
232 233 234 235 236

/**
 * Play
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
237
 * \return 0 if playback started (and was already started), or -1 on error.
238
 */
239
LIBVLC_API int libvlc_media_player_play ( libvlc_media_player_t *p_mi );
240

241 242 243 244 245
/**
 * Pause or resume (no effect if there is no media)
 *
 * \param mp the Media Player
 * \param do_pause play/resume if zero, pause if non-zero
246
 * \version LibVLC 1.1.1 or later
247
 */
248
LIBVLC_API void libvlc_media_player_set_pause ( libvlc_media_player_t *mp,
249 250
                                                    int do_pause );

251
/**
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
252
 * Toggle pause (no effect if there is no media)
253 254 255
 *
 * \param p_mi the Media Player
 */
256
LIBVLC_API void libvlc_media_player_pause ( libvlc_media_player_t *p_mi );
257 258

/**
259 260 261 262 263
 * Stop asynchronously
 *
 * \note This function is asynchronous. In case of success, the user should
 * wait for the libvlc_MediaPlayerStopped event to know when the stop is
 * finished.
264 265
 *
 * \param p_mi the Media Player
266 267
 * \return 0 if the player is being stopped, -1 otherwise (no-op)
 * \version LibVLC 4.0.0 or later
268
 */
269
LIBVLC_API int libvlc_media_player_stop_async ( libvlc_media_player_t *p_mi );
270

271 272 273 274 275 276 277 278 279 280 281 282 283 284
/**
 * Set a renderer to the media player
 *
 * \note must be called before the first call of libvlc_media_player_play() to
 * take effect.
 *
 * \see libvlc_renderer_discoverer_new
 *
 * \param p_mi the Media Player
 * \param p_item an item discovered by libvlc_renderer_discoverer_start()
 * \return 0 on success, -1 on error.
 * \version LibVLC 3.0.0 or later
 */
LIBVLC_API int libvlc_media_player_set_renderer( libvlc_media_player_t *p_mi,
285
                                                 libvlc_renderer_item_t *p_item );
286

287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
/**
 * Enumeration of the Video color primaries.
 */
typedef enum libvlc_video_color_primaries_t {
    libvlc_video_primaries_BT601_525 = 1,
    libvlc_video_primaries_BT601_625 = 2,
    libvlc_video_primaries_BT709     = 3,
    libvlc_video_primaries_BT2020    = 4,
    libvlc_video_primaries_DCI_P3    = 5,
    libvlc_video_primaries_BT470_M   = 6,
} libvlc_video_color_primaries_t;

/**
 * Enumeration of the Video color spaces.
 */
typedef enum libvlc_video_color_space_t {
    libvlc_video_colorspace_BT601  = 1,
    libvlc_video_colorspace_BT709  = 2,
    libvlc_video_colorspace_BT2020 = 3,
} libvlc_video_color_space_t;

/**
 * Enumeration of the Video transfer functions.
 */
typedef enum libvlc_video_transfer_func_t {
    libvlc_video_transfer_func_LINEAR     = 1,
    libvlc_video_transfer_func_SRGB       = 2,
    libvlc_video_transfer_func_BT470_BG   = 3,
    libvlc_video_transfer_func_BT470_M    = 4,
    libvlc_video_transfer_func_BT709      = 5,
    libvlc_video_transfer_func_PQ         = 6,
    libvlc_video_transfer_func_SMPTE_240  = 7,
    libvlc_video_transfer_func_HLG        = 8,
} libvlc_video_transfer_func_t;


Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
323
/**
324
 * Callback prototype to allocate and lock a picture buffer.
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
325 326 327 328 329 330
 *
 * Whenever a new video frame needs to be decoded, the lock callback is
 * invoked. Depending on the video chroma, one or three pixel planes of
 * adequate dimensions must be returned via the second parameter. Those
 * planes must be aligned on 32-bytes boundaries.
 *
331 332 333 334 335 336 337 338 339 340 341 342 343 344 345
 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
 * \param planes start address of the pixel planes (LibVLC allocates the array
 *             of void pointers, this callback must initialize the array) [OUT]
 * \return a private pointer for the display and unlock callbacks to identify
 *         the picture buffers
 */
typedef void *(*libvlc_video_lock_cb)(void *opaque, void **planes);

/**
 * Callback prototype to unlock a picture buffer.
 *
 * When the video frame decoding is complete, the unlock callback is invoked.
 * This callback might not be needed at all. It is only an indication that the
 * application can now read the pixel values if it needs to.
 *
346
 * \note A picture buffer is unlocked after the picture is decoded,
347 348 349
 * but before the picture is displayed.
 *
 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
350
 * \param picture private pointer returned from the @ref libvlc_video_lock_cb
351
 *                callback [IN]
352 353
 * \param planes pixel planes as defined by the @ref libvlc_video_lock_cb
 *               callback (this parameter is only for convenience) [IN]
354 355 356 357 358 359
 */
typedef void (*libvlc_video_unlock_cb)(void *opaque, void *picture,
                                       void *const *planes);

/**
 * Callback prototype to display a picture.
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
360 361
 *
 * When the video frame needs to be shown, as determined by the media playback
362 363 364
 * clock, the display callback is invoked.
 *
 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
365
 * \param picture private pointer returned from the @ref libvlc_video_lock_cb
366 367 368 369
 *                callback [IN]
 */
typedef void (*libvlc_video_display_cb)(void *opaque, void *picture);

370 371 372 373 374 375 376 377 378 379
/**
 * Callback prototype to configure picture buffers format.
 * This callback gets the format of the video as output by the video decoder
 * and the chain of video filters (if any). It can opt to change any parameter
 * as it needs. In that case, LibVLC will attempt to convert the video format
 * (rescaling and chroma conversion) but these operations can be CPU intensive.
 *
 * \param opaque pointer to the private pointer passed to
 *               libvlc_video_set_callbacks() [IN/OUT]
 * \param chroma pointer to the 4 bytes video format identifier [IN/OUT]
380 381
 * \param width pointer to the buffer width in pixels[IN/OUT]
 * \param height pointer to the buffer height in pixels[IN/OUT]
382 383 384 385 386
 * \param pitches table of scanline pitches in bytes for each pixel plane
 *                (the table is allocated by LibVLC) [OUT]
 * \param lines table of scanlines count for each plane [OUT]
 * \return the number of picture buffers allocated, 0 indicates failure
 *
387 388 389 390
 * \version LibVLC 4.0.0 and later.
 * \param (width+1) - pointer to display width in pixels[IN]
 * \param (height+1) - pointer to display height in pixels[IN]
 *
391 392 393 394 395 396
 * \note
 * For each pixels plane, the scanline pitch must be bigger than or equal to
 * the number of bytes per pixel multiplied by the pixel width.
 * Similarly, the number of scanlines must be bigger than of equal to
 * the pixel height.
 * Furthermore, we recommend that pitches and lines be multiple of 32
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
397
 * to not break assumptions that might be held by optimized code
398 399 400 401 402 403 404 405 406 407
 * in the video decoders, video filters and/or video converters.
 */
typedef unsigned (*libvlc_video_format_cb)(void **opaque, char *chroma,
                                           unsigned *width, unsigned *height,
                                           unsigned *pitches,
                                           unsigned *lines);

/**
 * Callback prototype to configure picture buffers format.
 *
408
 * \param opaque private pointer as passed to libvlc_video_set_format_callbacks()
409 410 411 412 413
 *               (and possibly modified by @ref libvlc_video_format_cb) [IN]
 */
typedef void (*libvlc_video_cleanup_cb)(void *opaque);


414 415
/**
 * Set callbacks and private data to render decoded video to a custom area
416 417 418
 * in memory.
 * Use libvlc_video_set_format() or libvlc_video_set_format_callbacks()
 * to configure the decoded format.
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
419
 *
420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443
 * \warning Rendering video into custom memory buffers is considerably less
 * efficient than rendering in a custom window as normal.
 *
 * For optimal perfomances, VLC media player renders into a custom window, and
 * does not use this function and associated callbacks. It is <b>highly
 * recommended</b> that other LibVLC-based application do likewise.
 * To embed video in a window, use libvlc_media_player_set_xid() or equivalent
 * depending on the operating system.
 *
 * If window embedding does not fit the application use case, then a custom
 * LibVLC video output display plugin is required to maintain optimal video
 * rendering performances.
 *
 * The following limitations affect performance:
 * - Hardware video decoding acceleration will either be disabled completely,
 *   or require (relatively slow) copy from video/DSP memory to main memory.
 * - Sub-pictures (subtitles, on-screen display, etc.) must be blent into the
 *   main picture by the CPU instead of the GPU.
 * - Depending on the video format, pixel format conversion, picture scaling,
 *   cropping and/or picture re-orientation, must be performed by the CPU
 *   instead of the GPU.
 * - Memory copying is required between LibVLC reference picture buffers and
 *   application buffers (between lock and unlock callbacks).
 *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
444
 * \param mp the media player
445 446 447
 * \param lock callback to lock video memory (must not be NULL)
 * \param unlock callback to unlock video memory (or NULL if not needed)
 * \param display callback to display video (or NULL if not needed)
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
448 449 450
 * \param opaque private pointer for the three callbacks (as first parameter)
 * \version LibVLC 1.1.1 or later
 */
451
LIBVLC_API
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
452
void libvlc_video_set_callbacks( libvlc_media_player_t *mp,
453 454 455 456
                                 libvlc_video_lock_cb lock,
                                 libvlc_video_unlock_cb unlock,
                                 libvlc_video_display_cb display,
                                 void *opaque );
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
457

458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492
/**
 * Set decoded video chroma and dimensions.
 * This only works in combination with libvlc_video_set_callbacks(),
 * and is mutually exclusive with libvlc_video_set_format_callbacks().
 *
 * \param mp the media player
 * \param chroma a four-characters string identifying the chroma
 *               (e.g. "RV32" or "YUYV")
 * \param width pixel width
 * \param height pixel height
 * \param pitch line pitch (in bytes)
 * \version LibVLC 1.1.1 or later
 * \bug All pixel planes are expected to have the same pitch.
 * To use the YCbCr color space with chrominance subsampling,
 * consider using libvlc_video_set_format_callbacks() instead.
 */
LIBVLC_API
void libvlc_video_set_format( libvlc_media_player_t *mp, const char *chroma,
                              unsigned width, unsigned height,
                              unsigned pitch );

/**
 * Set decoded video chroma and dimensions. This only works in combination with
 * libvlc_video_set_callbacks().
 *
 * \param mp the media player
 * \param setup callback to select the video format (cannot be NULL)
 * \param cleanup callback to release any allocated resources (or NULL)
 * \version LibVLC 2.0.0 or later
 */
LIBVLC_API
void libvlc_video_set_format_callbacks( libvlc_media_player_t *mp,
                                        libvlc_video_format_cb setup,
                                        libvlc_video_cleanup_cb cleanup );

493

494 495 496 497 498 499 500 501
typedef struct
{
    bool hardware_decoding; /** set if D3D11_CREATE_DEVICE_VIDEO_SUPPORT is needed for D3D11 */
} libvlc_video_setup_device_cfg_t;

typedef struct
{
    union {
502 503 504 505 506 507 508
        struct {
            void *device_context; /** ID3D11DeviceContext* */
        } d3d11;
        struct {
            void *device;         /** IDirect3D9* */
            int  adapter;         /** Adapter to use with the IDirect3D9* */
        } d3d9;
509 510 511
    };
} libvlc_video_setup_device_info_t;

512 513
/**
 * Callback prototype called to initialize user data.
514
 * Setup the rendering environment.
515
 *
516 517
 * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks()
 *               on input. The callback can change this value on output to be
518 519
 *               passed to all the other callbacks set on @a libvlc_video_set_output_callbacks().
 *               [IN/OUT]
520 521
 * \param cfg requested configuration of the video device [IN]
 * \param out libvlc_video_setup_device_info_t* to fill [OUT]
522 523
 * \return true on success
 * \version LibVLC 4.0.0 or later
524
 *
525
 * For \ref libvlc_video_engine_d3d9 the output must be a IDirect3D9*.
526 527 528
 * A reference to this object is held until the \ref LIBVLC_VIDEO_DEVICE_CLEANUP is called.
 * the device must be created with D3DPRESENT_PARAMETERS.hDeviceWindow set to 0.
 *
529
 * For \ref libvlc_video_engine_d3d11 the output must be a ID3D11DeviceContext*.
530 531
 * A reference to this object is held until the \ref LIBVLC_VIDEO_DEVICE_CLEANUP is called.
 * The ID3D11Device used to create ID3D11DeviceContext must have multithreading enabled.
532
 */
533
typedef bool (*libvlc_video_output_setup_cb)(void **opaque,
534 535
                                      const libvlc_video_setup_device_cfg_t *cfg,
                                      libvlc_video_setup_device_info_t *out);
536 537 538 539 540


/**
 * Callback prototype called to release user data
 *
541
 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
542 543
 * \version LibVLC 4.0.0 or later
 */
544
typedef void (*libvlc_video_output_cleanup_cb)(void* opaque);
545

546 547 548 549
typedef struct
{
    unsigned width;                        /** rendering video width in pixel */
    unsigned height;                      /** rendering video height in pixel */
550 551 552 553 554 555
    unsigned bitdepth;      /** rendering video bit depth in bits per channel */
    bool full_range;          /** video is full range or studio/limited range */
    libvlc_video_color_space_t colorspace;              /** video color space */
    libvlc_video_color_primaries_t primaries;       /** video color primaries */
    libvlc_video_transfer_func_t transfer;        /** video transfer function */
    void *device;   /** device used for rendering, IDirect3DDevice9* for D3D9 */
556 557
} libvlc_video_render_cfg_t;

558 559
typedef struct
{
560
    union {
561
        int dxgi_format;  /** the rendering DXGI_FORMAT for \ref libvlc_video_engine_d3d11*/
562
        uint32_t d3d9_format;  /** the rendering D3DFORMAT for \ref libvlc_video_engine_d3d9 */
563
        int opengl_format;  /** the rendering GLint GL_RGBA or GL_RGB for \ref libvlc_video_engine_opengl and
564 565 566
                            for \ref libvlc_video_engine_gles2 */
        void *p_surface; /** currently unused */
    };
567 568 569 570 571 572
    bool full_range;          /** video is full range or studio/limited range */
    libvlc_video_color_space_t colorspace;              /** video color space */
    libvlc_video_color_primaries_t primaries;       /** video color primaries */
    libvlc_video_transfer_func_t transfer;        /** video transfer function */
} libvlc_video_output_cfg_t;

573
/**
574 575
 * Callback prototype called on video size changes.
 * Update the rendering output setup.
576
 *
577
 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
578
 * \param cfg configuration of the video that will be rendered [IN]
579
 * \param output configuration describing with how the rendering is setup [OUT]
580
 * \version LibVLC 4.0.0 or later
581 582 583 584 585 586 587 588
 *
 * \note the configuration device for Direct3D9 is the IDirect3DDevice9 that VLC
 *       uses to render. The host must set a Render target and call Present()
 *       when it needs the drawing from VLC to be done. This object is not valid
 *       anymore after Cleanup is called.
 *
 * Tone mapping, range and color conversion will be done depending on the values
 * set in the output structure.
589
 */
590
typedef bool (*libvlc_video_update_output_cb)(void* opaque, const libvlc_video_render_cfg_t *cfg,
591
                                              libvlc_video_output_cfg_t *output );
592 593 594 595 596


/**
 * Callback prototype called after performing drawing calls.
 *
597 598 599
 * This callback is called outside of libvlc_video_makeCurrent_cb current/not-current
 * calls.
 *
600
 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
601 602
 * \version LibVLC 4.0.0 or later
 */
603
typedef void (*libvlc_video_swap_cb)(void* opaque);
604 605

/**
606 607
 * Callback prototype to set up the OpenGL context for rendering.
 * Tell the host the rendering is about to start/has finished.
608
 *
609
 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
610 611 612
 * \param enter true to set the context as current, false to unset it [IN]
 * \return true on success
 * \version LibVLC 4.0.0 or later
613 614 615 616 617 618 619 620 621 622 623 624 625 626 627
 *
 * On Direct3D11 the following may change on the provided ID3D11DeviceContext*
 * between \ref enter being true and \ref enter being false:
 * - IASetPrimitiveTopology()
 * - IASetInputLayout()
 * - IASetVertexBuffers()
 * - IASetIndexBuffer()
 * - VSSetConstantBuffers()
 * - VSSetShader()
 * - PSSetSamplers()
 * - PSSetConstantBuffers()
 * - PSSetShaderResources()
 * - PSSetShader()
 * - RSSetViewports()
 * - DrawIndexed()
628
 */
629
typedef bool (*libvlc_video_makeCurrent_cb)(void* opaque, bool enter);
630 631 632 633

/**
 * Callback prototype to load opengl functions
 *
634
 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
635 636 637 638
 * \param fct_name name of the opengl function to load
 * \return a pointer to the named OpenGL function the NULL otherwise
 * \version LibVLC 4.0.0 or later
 */
639
typedef void* (*libvlc_video_getProcAddress_cb)(void* opaque, const char* fct_name);
640

641 642 643 644 645 646 647 648 649 650 651
typedef struct
{
    /* similar to SMPTE ST 2086 mastering display color volume */
    uint16_t RedPrimary[2];
    uint16_t GreenPrimary[2];
    uint16_t BluePrimary[2];
    uint16_t WhitePoint[2];
    unsigned int MaxMasteringLuminance;
    unsigned int MinMasteringLuminance;
    uint16_t MaxContentLightLevel;
    uint16_t MaxFrameAverageLightLevel;
652
} libvlc_video_frame_hdr10_metadata_t;
653 654

typedef enum libvlc_video_metadata_type_t {
655
    libvlc_video_metadata_frame_hdr10, /**< libvlc_video_frame_hdr10_metadata_t */
656 657 658 659 660 661 662 663 664 665 666 667
} libvlc_video_metadata_type_t;

/**
 * Callback prototype to receive metadata before rendering.
 *
 * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() [IN]
 * \param type type of data passed in metadata [IN]
 * \param metadata the type of metadata [IN]
 * \version LibVLC 4.0.0 or later
 */
typedef void (*libvlc_video_frameMetadata_cb)(void* opaque, libvlc_video_metadata_type_t type, const void *metadata);

668
/**
669 670
 * Enumeration of the Video engine to be used on output.
 * can be passed to @a libvlc_video_set_output_callbacks
671
 */
672
typedef enum libvlc_video_engine_t {
673 674
    /** Disable rendering engine */
    libvlc_video_engine_disable,
675 676
    libvlc_video_engine_opengl,
    libvlc_video_engine_gles2,
677
    /** Direct3D11 rendering engine */
678
    libvlc_video_engine_d3d11,
679
    /** Direct3D9 rendering engine */
680
    libvlc_video_engine_d3d9,
681
} libvlc_video_engine_t;
682

683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699
/** Set the callback to call when the host app resizes the rendering area.
 *
 * This allows text rendering and aspect ratio to be handled properly when the host
 * rendering size changes.
 *
 * It may be called before the \ref libvlc_video_output_setup_cb callback.
 *
 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
 * \param report_size_change callback which must be called when the host size changes. [IN]
 *        The callback is valid until another call to \ref libvlc_video_output_set_resize_cb
 *        is done. This may be called from any thread.
 * \param report_opaque private pointer to pass to the \ref report_size_change callback. [IN]
 */
typedef void( *libvlc_video_output_set_resize_cb )( void *opaque,
                                                    void (*report_size_change)(void *report_opaque, unsigned width, unsigned height),
                                                    void *report_opaque );

700 701 702 703 704 705 706
/** Tell the host the rendering for the given plane is about to start
 *
 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
 * \param plane number of the rendering plane to select
 * \return true on success
 * \version LibVLC 4.0.0 or later
 *
707
 * \note This is only used with \ref libvlc_video_engine_d3d11.
708 709
 *
 * The host should call OMSetRenderTargets for Direct3D11. If this callback is
710
 * not used (set to NULL in @a libvlc_video_set_output_callbacks()) OMSetRenderTargets
711 712 713 714 715 716
 * has to be set during the @a libvlc_video_makeCurrent_cb()
 * entering call.
 *
 * The number of planes depend on the DXGI_FORMAT returned during the
 * \ref LIBVLC_VIDEO_UPDATE_OUTPUT call. It's usually one plane except for
 * semi-planar formats like DXGI_FORMAT_NV12 or DXGI_FORMAT_P010.
717 718 719
 *
 * This callback is called between libvlc_video_makeCurrent_cb current/not-current
 * calls.
720 721 722
 */
typedef bool( *libvlc_video_output_select_plane_cb )( void *opaque, size_t plane );

723
/**
724
 * Set callbacks and data to render decoded video to a custom texture
725 726 727 728 729
 *
 * \warning VLC will perform video rendering in its own thread and at its own rate,
 * You need to provide your own synchronisation mechanism.
 *
 * \param mp the media player
730
 * \param engine the GPU engine to use
731 732
 * \param setup_cb callback called to initialize user data
 * \param cleanup_cb callback called to clean up user data
733
 * \param resize_cb callback to set the resize callback
734
 * \param update_output_cb callback to get the rendering format of the host (cannot be NULL)
735
 * \param swap_cb callback called after rendering a video frame (cannot be NULL)
736
 * \param makeCurrent_cb callback called to enter/leave the rendering context (cannot be NULL)
737
 * \param getProcAddress_cb opengl function loading callback (cannot be NULL for \ref libvlc_video_engine_opengl and for \ref libvlc_video_engine_gles2)
738 739
 * \param metadata_cb callback to provide frame metadata (D3D11 only)
 * \param select_plane_cb callback to select different D3D11 rendering targets
740
 * \param opaque private pointer passed to callbacks
741 742 743
 *
 * \retval true engine selected and callbacks set
 * \retval false engine type unknown, callbacks not set
744 745 746
 * \version LibVLC 4.0.0 or later
 */
LIBVLC_API
747
bool libvlc_video_set_output_callbacks( libvlc_media_player_t *mp,
748
                                        libvlc_video_engine_t engine,
749
                                        libvlc_video_output_setup_cb setup_cb,
750
                                        libvlc_video_output_cleanup_cb cleanup_cb,
751
                                        libvlc_video_output_set_resize_cb resize_cb,
752 753 754 755
                                        libvlc_video_update_output_cb update_output_cb,
                                        libvlc_video_swap_cb swap_cb,
                                        libvlc_video_makeCurrent_cb makeCurrent_cb,
                                        libvlc_video_getProcAddress_cb getProcAddress_cb,
756 757
                                        libvlc_video_frameMetadata_cb metadata_cb,
                                        libvlc_video_output_select_plane_cb select_plane_cb,
758 759
                                        void* opaque );

760
/**
761 762
 * Set the NSView handler where the media player should render its video output.
 *
763 764
 * Use the vout called "macosx".
 *
765
 * The drawable is an NSObject that follow the VLCVideoViewEmbedding
766
 * protocol:
767
 *
768
 * @code{.m}
769
 * @protocol VLCVideoViewEmbedding <NSObject>
770 771
 * - (void)addVoutSubview:(NSView *)view;
 * - (void)removeVoutSubview:(NSView *)view;
772
 * @end
773
 * @endcode
774
 *
775 776
 * Or it can be an NSView object.
 *
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
777
 * If you want to use it along with Qt see the QMacCocoaViewContainer. Then
778
 * the following code should work:
779
 * @code{.mm}
780 781 782 783 784 785 786 787
 * {
 *     NSView *video = [[NSView alloc] init];
 *     QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
 *     libvlc_media_player_set_nsobject(mp, video);
 *     [video release];
 * }
 * @endcode
 *
788
 * You can find a live example in VLCVideoView in VLCKit.framework.
789
 *
790
 * \param p_mi the Media Player
791
 * \param drawable the drawable that is either an NSView or an object following
792
 * the VLCVideoViewEmbedding protocol.
793
 */
794
LIBVLC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable );
795 796

/**
797
 * Get the NSView handler previously set with libvlc_media_player_set_nsobject().
798
 *
799
 * \param p_mi the Media Player
800
 * \return the NSView handler or 0 if none where set
801
 */
802
LIBVLC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi );
803

804 805
/**
 * Set an X Window System drawable where the media player should render its
806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825
 * video output. The call takes effect when the playback starts. If it is
 * already started, it might need to be stopped before changes apply.
 * If LibVLC was built without X11 output support, then this function has no
 * effects.
 *
 * By default, LibVLC will capture input events on the video rendering area.
 * Use libvlc_video_set_mouse_input() and libvlc_video_set_key_input() to
 * disable that and deliver events to the parent window / to the application
 * instead. By design, the X11 protocol delivers input events to only one
 * recipient.
 *
 * \warning
 * The application must call the XInitThreads() function from Xlib before
 * libvlc_new(), and before any call to XOpenDisplay() directly or via any
 * other library. Failure to call XInitThreads() will seriously impede LibVLC
 * performance. Calling XOpenDisplay() before XInitThreads() will eventually
 * crash the process. That is a limitation of Xlib.
 *
 * \param p_mi media player
 * \param drawable X11 window ID
826
 *
827
 * \note
828
 * The specified identifier must correspond to an existing Input/Output class
829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845
 * X11 window. Pixmaps are <b>not</b> currently supported. The default X11
 * server is assumed, i.e. that specified in the DISPLAY environment variable.
 *
 * \warning
 * LibVLC can deal with invalid X11 handle errors, however some display drivers
 * (EGL, GLX, VA and/or VDPAU) can unfortunately not. Thus the window handle
 * must remain valid until playback is stopped, otherwise the process may
 * abort or crash.
 *
 * \bug
 * No more than one window handle per media player instance can be specified.
 * If the media has multiple simultaneously active video tracks, extra tracks
 * will be rendered into external windows beyond the control of the
 * application.
 */
LIBVLC_API void libvlc_media_player_set_xwindow(libvlc_media_player_t *p_mi,
                                                uint32_t drawable);
846 847 848 849 850 851 852

/**
 * Get the X Window System window identifier previously set with
 * libvlc_media_player_set_xwindow(). Note that this will return the identifier
 * even if VLC is not currently using it (for instance if it is playing an
 * audio-only input).
 *
853
 * \param p_mi the Media Player
854 855
 * \return an X window ID, or 0 if none where set.
 */
856
LIBVLC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi );
857 858 859 860 861 862 863 864 865

/**
 * Set a Win32/Win64 API window handle (HWND) where the media player should
 * render its video output. If LibVLC was built without Win32/Win64 API output
 * support, then this has no effects.
 *
 * \param p_mi the Media Player
 * \param drawable windows handle of the drawable
 */
866
LIBVLC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable );
867 868 869 870 871 872

/**
 * Get the Windows API window handle (HWND) previously set with
 * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC
 * is not currently outputting any video to it.
 *
873
 * \param p_mi the Media Player
874 875
 * \return a window handle or NULL if there are none.
 */
876
LIBVLC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );
877

878 879 880 881 882 883
/**
 * Set the android context.
 *
 * \version LibVLC 3.0.0 and later.
 *
 * \param p_mi the media player
884 885
 * \param p_awindow_handler org.videolan.libvlc.AWindow jobject owned by the
 *        org.videolan.libvlc.MediaPlayer class from the libvlc-android project.
886 887 888 889
 */
LIBVLC_API void libvlc_media_player_set_android_context( libvlc_media_player_t *p_mi,
                                                         void *p_awindow_handler );

890 891
/**
 * Callback prototype for audio playback.
892 893 894 895 896 897 898 899 900 901 902 903 904
 *
 * The LibVLC media player decodes and post-processes the audio signal
 * asynchronously (in an internal thread). Whenever audio samples are ready
 * to be queued to the output, this callback is invoked.
 *
 * The number of samples provided per invocation may depend on the file format,
 * the audio coding algorithm, the decoder plug-in, the post-processing
 * filters and timing. Application must not assume a certain number of samples.
 *
 * The exact format of audio samples is determined by libvlc_audio_set_format()
 * or libvlc_audio_set_format_callbacks() as is the channels layout.
 *
 * Note that the number of samples is per channel. For instance, if the audio
905 906
 * track sampling rate is 48000 Hz, then 1200 samples represent 25 milliseconds
 * of audio signal - regardless of the number of audio channels.
907
 *
908
 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
909
 * \param samples pointer to a table of audio samples to play back [IN]
910 911 912 913
 * \param count number of audio samples to play back
 * \param pts expected play time stamp (see libvlc_delay())
 */
typedef void (*libvlc_audio_play_cb)(void *data, const void *samples,
914
                                     unsigned count, int64_t pts);
915

916 917
/**
 * Callback prototype for audio pause.
918 919 920
 *
 * LibVLC invokes this callback to pause audio playback.
 *
921 922 923 924 925 926 927
 * \note The pause callback is never called if the audio is already paused.
 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 * \param pts time stamp of the pause request (should be elapsed already)
 */
typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts);

/**
928 929 930 931 932
 * Callback prototype for audio resumption.
 *
 * LibVLC invokes this callback to resume audio playback after it was
 * previously paused.
 *
933 934 935 936 937 938 939
 * \note The resume callback is never called if the audio is not paused.
 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 * \param pts time stamp of the resumption request (should be elapsed already)
 */
typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts);

/**
940 941 942 943 944 945
 * Callback prototype for audio buffer flush.
 *
 * LibVLC invokes this callback if it needs to discard all pending buffers and
 * stop playback as soon as possible. This typically occurs when the media is
 * stopped.
 *
946 947 948 949 950
 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 */
typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts);

/**
951 952 953 954 955 956
 * Callback prototype for audio buffer drain.
 *
 * LibVLC may invoke this callback when the decoded audio track is ending.
 * There will be no further decoded samples for the track, but playback should
 * nevertheless continue until all already pending buffers are rendered.
 *
957 958 959 960
 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 */
typedef void (*libvlc_audio_drain_cb)(void *data);

961 962 963
/**
 * Callback prototype for audio volume change.
 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
964
 * \param volume software volume (1. = nominal, 0. = mute)
965 966 967 968 969 970
 * \param mute muted flag
 */
typedef void (*libvlc_audio_set_volume_cb)(void *data,
                                           float volume, bool mute);

/**
971 972
 * Sets callbacks and private data for decoded audio.
 *
973 974 975
 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
 * to configure the decoded audio format.
 *
976 977 978
 * \note The audio callbacks override any other audio output mechanism.
 * If the callbacks are set, LibVLC will <b>not</b> output audio in any way.
 *
979 980
 * \param mp the media player
 * \param play callback to play audio samples (must not be NULL)
981 982 983 984 985
 * \param pause callback to pause playback (or NULL to ignore)
 * \param resume callback to resume playback (or NULL to ignore)
 * \param flush callback to flush audio buffers (or NULL to ignore)
 * \param drain callback to drain audio buffers (or NULL to ignore)
 * \param opaque private pointer for the audio callbacks (as first parameter)
986
 * \version LibVLC 2.0.0 or later
987 988 989 990
 */
LIBVLC_API
void libvlc_audio_set_callbacks( libvlc_media_player_t *mp,
                                 libvlc_audio_play_cb play,
991 992 993 994
                                 libvlc_audio_pause_cb pause,
                                 libvlc_audio_resume_cb resume,
                                 libvlc_audio_flush_cb flush,
                                 libvlc_audio_drain_cb drain,
995 996
                                 void *opaque );

997
/**
998 999
 * Set callbacks and private data for decoded audio. This only works in
 * combination with libvlc_audio_set_callbacks().
1000 1001 1002 1003 1004 1005
 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
 * to configure the decoded audio format.
 *
 * \param mp the media player
 * \param set_volume callback to apply audio volume,
 *                   or NULL to apply volume in software
1006
 * \version LibVLC 2.0.0 or later
1007 1008 1009 1010 1011
 */
LIBVLC_API
void libvlc_audio_set_volume_callback( libvlc_media_player_t *mp,
                                       libvlc_audio_set_volume_cb set_volume );

1012 1013
/**
 * Callback prototype to setup the audio playback.
1014
 *
1015 1016 1017 1018 1019 1020 1021 1022
 * This is called when the media player needs to create a new audio output.
 * \param opaque pointer to the data pointer passed to
 *               libvlc_audio_set_callbacks() [IN/OUT]
 * \param format 4 bytes sample format [IN/OUT]
 * \param rate sample rate [IN/OUT]
 * \param channels channels count [IN/OUT]
 * \return 0 on success, anything else to skip audio playback
 */
1023
typedef int (*libvlc_audio_setup_cb)(void **opaque, char *format, unsigned *rate,
1024 1025 1026 1027
                                     unsigned *channels);

/**
 * Callback prototype for audio playback cleanup.
1028
 *
1029 1030 1031 1032
 * This is called when the media player no longer needs an audio output.
 * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN]
 */
typedef void (*libvlc_audio_cleanup_cb)(void *data);
1033

1034
/**
1035 1036 1037
 * Sets decoded audio format via callbacks.
 *
 * This only works in combination with libvlc_audio_set_callbacks().
1038 1039 1040 1041
 *
 * \param mp the media player
 * \param setup callback to select the audio format (cannot be NULL)
 * \param cleanup callback to release any allocated resources (or NULL)
1042
 * \version LibVLC 2.0.0 or later
1043 1044 1045 1046 1047 1048 1049
 */
LIBVLC_API
void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp,
                                        libvlc_audio_setup_cb setup,
                                        libvlc_audio_cleanup_cb cleanup );

/**
1050 1051
 * Sets a fixed decoded audio format.
 *
1052 1053 1054 1055
 * This only works in combination with libvlc_audio_set_callbacks(),
 * and is mutually exclusive with libvlc_audio_set_format_callbacks().
 *
 * \param mp the media player
Rémi Duraffort's avatar
Rémi Duraffort committed
1056
 * \param format a four-characters string identifying the sample format
1057
 *               (e.g. "S16N" or "f32l")
1058 1059
 * \param rate sample rate (expressed in Hz)
 * \param channels channels count
1060
 * \version LibVLC 2.0.0 or later
1061 1062 1063 1064
 */
LIBVLC_API
void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format,
                              unsigned rate, unsigned channels );
1065 1066 1067 1068 1069 1070 1071

/** \bug This might go away ... to be replaced by a broader system */

/**
 * Get the current movie length (in ms).
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
1072
 * \return the movie length (in ms), or -1 if there is no media.
1073
 */
1074
LIBVLC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *p_mi );
1075 1076 1077 1078 1079

/**
 * Get the current movie time (in ms).
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
1080
 * \return the movie time (in ms), or -1 if there is no media.
1081
 */
1082
LIBVLC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *p_mi );
1083 1084

/**
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
1085 1086
 * Set the movie time (in ms). This has no effect if no media is being played.
 * Not all formats and protocols support this.
1087 1088
 *
 * \param p_mi the Media Player
Zhao Zhili's avatar
Zhao Zhili committed
1089
 * \param b_fast prefer fast seeking or precise seeking
1090
 * \param i_time the movie time (in ms).
Zhao Zhili's avatar
Zhao Zhili committed
1091
 * \return 0 on success, -1 on error
1092
 */
Zhao Zhili's avatar
Zhao Zhili committed
1093 1094
LIBVLC_API int libvlc_media_player_set_time( libvlc_media_player_t *p_mi,
                                             libvlc_time_t i_time, bool b_fast );
1095 1096

/**
1097
 * Get movie position as percentage between 0.0 and 1.0.
1098 1099
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
1100
 * \return movie position, or -1. in case of error
1101
 */
1102
LIBVLC_API float libvlc_media_player_get_position( libvlc_media_player_t *p_mi );
1103 1104

/**
1105
 * Set movie position as percentage between 0.0 and 1.0.
1106
 * This has no effect if playback is not enabled.
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
1107
 * This might not work depending on the underlying input format and protocol.
1108 1109
 *
 * \param p_mi the Media Player
Zhao Zhili's avatar
Zhao Zhili committed
1110
 * \param b_fast prefer fast seeking or precise seeking
Olivier Aubert's avatar
Olivier Aubert committed
1111
 * \param f_pos the position
Zhao Zhili's avatar
Zhao Zhili committed
1112
 * \return 0 on success, -1 on error
1113
 */
Zhao Zhili's avatar
Zhao Zhili committed
1114 1115
LIBVLC_API int libvlc_media_player_set_position( libvlc_media_player_t *p_mi,
                                                 float f_pos, bool b_fast );
1116 1117

/**
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
1118
 * Set movie chapter (if applicable).
1119 1120 1121 1122
 *
 * \param p_mi the Media Player
 * \param i_chapter chapter number to play
 */
1123
LIBVLC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *p_mi, int i_chapter );
1124 1125

/**
Rémi Denis-Courmont's avatar
good  
Rémi Denis-Courmont committed
1126
 * Get movie chapter.