VLC 4.0.0-dev
Loading...
Searching...
No Matches
LibVLC media

libvlc_media_t is an abstract representation of a playable media. More...

Collaboration diagram for LibVLC media:

Files

file  libvlc_media.h
 LibVLC media item/descriptor external API.
 

Data Structures

struct  libvlc_media_stats_t
 
struct  libvlc_media_slave_t
 A slave of a libvlc_media_t. More...
 

Macros

#define libvlc_media_filestat_mtime   0
 Type of stat that can be requested from libvlc_media_get_filestat()
 
#define libvlc_media_filestat_size   1
 
#define VLC_FORWARD_DECLARE_OBJECT(a)   struct a
 

Typedefs

typedef struct libvlc_media_t libvlc_media_t
 
typedef enum libvlc_meta_t libvlc_meta_t
 Meta data types.
 
typedef enum libvlc_state_t libvlc_state_t
 libvlc media or media_player state
 
typedef struct libvlc_media_stats_t libvlc_media_stats_t
 
typedef enum libvlc_media_type_t libvlc_media_type_t
 Media type.
 
typedef enum libvlc_media_parse_flag_t libvlc_media_parse_flag_t
 Parse flags used by libvlc_media_parse_request()
 
typedef enum libvlc_media_parsed_status_t libvlc_media_parsed_status_t
 Parse status used sent by libvlc_media_parse_request() or returned by libvlc_media_get_parsed_status()
 
typedef enum libvlc_media_slave_type_t libvlc_media_slave_type_t
 Type of a media slave: subtitle or audio.
 
typedef struct libvlc_media_slave_t libvlc_media_slave_t
 A slave of a libvlc_media_t.
 
typedef int(* libvlc_media_open_cb) (void *opaque, void **datap, uint64_t *sizep)
 Callback prototype to open a custom bitstream input media.
 
typedef ptrdiff_t(* libvlc_media_read_cb) (void *opaque, unsigned char *buf, size_t len)
 Callback prototype to read data from a custom bitstream input media.
 
typedef int(* libvlc_media_seek_cb) (void *opaque, uint64_t offset)
 Callback prototype to seek a custom bitstream input media.
 
typedef void(* libvlc_media_close_cb) (void *opaque)
 Callback prototype to close a custom bitstream input media.
 
typedef struct libvlc_media_thumbnail_request_t libvlc_media_thumbnail_request_t
 libvlc_media_thumbnail_request_t An opaque thumbnail request object
 
typedef enum libvlc_thumbnailer_seek_speed_t libvlc_thumbnailer_seek_speed_t
 

Enumerations

enum  libvlc_meta_t {
  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 ,
  libvlc_meta_TrackID , libvlc_meta_TrackTotal , libvlc_meta_Director , libvlc_meta_Season ,
  libvlc_meta_Episode , libvlc_meta_ShowName , libvlc_meta_Actors , libvlc_meta_AlbumArtist ,
  libvlc_meta_DiscNumber , libvlc_meta_DiscTotal
}
 Meta data types. More...
 
enum  libvlc_state_t {
  libvlc_NothingSpecial =0 , libvlc_Opening , libvlc_Buffering , libvlc_Playing ,
  libvlc_Paused , libvlc_Stopped , libvlc_Stopping , libvlc_Error
}
 libvlc media or media_player state More...
 
enum  { libvlc_media_option_trusted = 0x2 , libvlc_media_option_unique = 0x100 }
 
enum  libvlc_media_type_t {
  libvlc_media_type_unknown , libvlc_media_type_file , libvlc_media_type_directory , libvlc_media_type_disc ,
  libvlc_media_type_stream , libvlc_media_type_playlist
}
 Media type. More...
 
enum  libvlc_media_parse_flag_t {
  libvlc_media_parse_local = 0x01 , libvlc_media_parse_network = 0x02 , libvlc_media_parse_forced = 0x04 , libvlc_media_fetch_local = 0x08 ,
  libvlc_media_fetch_network = 0x10 , libvlc_media_do_interact = 0x20
}
 Parse flags used by libvlc_media_parse_request() More...
 
enum  libvlc_media_parsed_status_t {
  libvlc_media_parsed_status_none , libvlc_media_parsed_status_pending , libvlc_media_parsed_status_skipped , libvlc_media_parsed_status_failed ,
  libvlc_media_parsed_status_timeout , libvlc_media_parsed_status_done
}
 Parse status used sent by libvlc_media_parse_request() or returned by libvlc_media_get_parsed_status() More...
 
enum  libvlc_media_slave_type_t { libvlc_media_slave_type_subtitle , libvlc_media_slave_type_generic , libvlc_media_slave_type_audio = libvlc_media_slave_type_generic }
 Type of a media slave: subtitle or audio. More...
 
enum  libvlc_thumbnailer_seek_speed_t { libvlc_media_thumbnail_seek_precise , libvlc_media_thumbnail_seek_fast }
 

Functions

LIBVLC_API libvlc_media_tlibvlc_media_new_location (const char *psz_mrl)
 Create a media with a certain given media resource location, for instance a valid URL.
 
LIBVLC_API libvlc_media_tlibvlc_media_new_path (const char *path)
 Create a media for a certain file path.
 
LIBVLC_API libvlc_media_tlibvlc_media_new_fd (int fd)
 Create a media for an already open file descriptor.
 
LIBVLC_API libvlc_media_tlibvlc_media_new_callbacks (libvlc_media_open_cb open_cb, libvlc_media_read_cb read_cb, libvlc_media_seek_cb seek_cb, libvlc_media_close_cb close_cb, void *opaque)
 Create a media with custom callbacks to read the data from.
 
LIBVLC_API libvlc_media_tlibvlc_media_new_as_node (const char *psz_name)
 Create a media as an empty node with a given name.
 
LIBVLC_API void libvlc_media_add_option (libvlc_media_t *p_md, const char *psz_options)
 Add an option to the media.
 
LIBVLC_API void libvlc_media_add_option_flag (libvlc_media_t *p_md, const char *psz_options, unsigned i_flags)
 Add an option to the media with configurable flags.
 
LIBVLC_API libvlc_media_tlibvlc_media_retain (libvlc_media_t *p_md)
 Retain a reference to a media descriptor object (libvlc_media_t).
 
LIBVLC_API void libvlc_media_release (libvlc_media_t *p_md)
 Decrement the reference count of a media descriptor object.
 
LIBVLC_API char * libvlc_media_get_mrl (libvlc_media_t *p_md)
 Get the media resource locator (mrl) from a media descriptor object.
 
LIBVLC_API libvlc_media_tlibvlc_media_duplicate (libvlc_media_t *p_md)
 Duplicate a media descriptor object.
 
LIBVLC_API char * libvlc_media_get_meta (libvlc_media_t *p_md, libvlc_meta_t e_meta)
 Read the meta of the media.
 
LIBVLC_API void libvlc_media_set_meta (libvlc_media_t *p_md, libvlc_meta_t e_meta, const char *psz_value)
 Set the meta of the media (this function will not save the meta, call libvlc_media_save_meta in order to save the meta)
 
LIBVLC_API char * libvlc_media_get_meta_extra (libvlc_media_t *p_md, const char *psz_name)
 Read the meta extra of the media.
 
LIBVLC_API void libvlc_media_set_meta_extra (libvlc_media_t *p_md, const char *psz_name, const char *psz_value)
 Set the meta of the media (this function will not save the meta, call libvlc_media_save_meta in order to save the meta)
 
LIBVLC_API unsigned libvlc_media_get_meta_extra_names (libvlc_media_t *p_md, char ***pppsz_names)
 Read the meta extra names of the media.
 
LIBVLC_API void libvlc_media_meta_extra_names_release (char **ppsz_names, unsigned i_count)
 Release a media meta extra names.
 
LIBVLC_API int libvlc_media_save_meta (libvlc_instance_t *inst, libvlc_media_t *p_md)
 Save the meta previously set.
 
LIBVLC_API bool libvlc_media_get_stats (libvlc_media_t *p_md, libvlc_media_stats_t *p_stats)
 Get the current statistics about the media.
 
LIBVLC_API struct libvlc_media_list_tlibvlc_media_subitems (libvlc_media_t *p_md)
 Get subitems of media descriptor object.
 
LIBVLC_API libvlc_event_manager_tlibvlc_media_event_manager (libvlc_media_t *p_md)
 Get event manager from media descriptor object.
 
LIBVLC_API libvlc_time_t libvlc_media_get_duration (libvlc_media_t *p_md)
 Get duration (in ms) of media descriptor object item.
 
LIBVLC_API int libvlc_media_get_filestat (libvlc_media_t *p_md, unsigned type, uint64_t *out)
 Get a 'stat' value of media descriptor object item.
 
LIBVLC_API int libvlc_media_parse_request (libvlc_instance_t *inst, libvlc_media_t *p_md, libvlc_media_parse_flag_t parse_flag, int timeout)
 Parse the media asynchronously with options.
 
LIBVLC_API void libvlc_media_parse_stop (libvlc_instance_t *inst, libvlc_media_t *p_md)
 Stop the parsing of the media.
 
LIBVLC_API libvlc_media_parsed_status_t libvlc_media_get_parsed_status (libvlc_media_t *p_md)
 Get Parsed status for media descriptor object.
 
LIBVLC_API void libvlc_media_set_user_data (libvlc_media_t *p_md, void *p_new_user_data)
 Sets media descriptor's user_data.
 
LIBVLC_API void * libvlc_media_get_user_data (libvlc_media_t *p_md)
 Get media descriptor's user_data.
 
LIBVLC_API libvlc_media_tracklist_tlibvlc_media_get_tracklist (libvlc_media_t *p_md, libvlc_track_type_t type)
 Get the track list for one type.
 
LIBVLC_API const char * libvlc_media_get_codec_description (libvlc_track_type_t i_type, uint32_t i_codec)
 Get codec description from media elementary stream.
 
LIBVLC_API libvlc_media_type_t libvlc_media_get_type (libvlc_media_t *p_md)
 Get the media type of the media descriptor object.
 
LIBVLC_API libvlc_media_thumbnail_request_tlibvlc_media_thumbnail_request_by_time (libvlc_instance_t *inst, libvlc_media_t *md, libvlc_time_t time, libvlc_thumbnailer_seek_speed_t speed, unsigned int width, unsigned int height, bool crop, libvlc_picture_type_t picture_type, libvlc_time_t timeout)
 libvlc_media_request_thumbnail_by_time Start an asynchronous thumbnail generation
 
LIBVLC_API libvlc_media_thumbnail_request_tlibvlc_media_thumbnail_request_by_pos (libvlc_instance_t *inst, libvlc_media_t *md, double pos, libvlc_thumbnailer_seek_speed_t speed, unsigned int width, unsigned int height, bool crop, libvlc_picture_type_t picture_type, libvlc_time_t timeout)
 libvlc_media_request_thumbnail_by_pos Start an asynchronous thumbnail generation
 
LIBVLC_API void libvlc_media_thumbnail_request_destroy (libvlc_media_thumbnail_request_t *p_req)
 libvlc_media_thumbnail_destroy destroys a thumbnail request
 
LIBVLC_API int libvlc_media_slaves_add (libvlc_media_t *p_md, libvlc_media_slave_type_t i_type, unsigned int i_priority, const char *psz_uri)
 Add a slave to the current media.
 
LIBVLC_API void libvlc_media_slaves_clear (libvlc_media_t *p_md)
 Clear all slaves previously added by libvlc_media_slaves_add() or internally.
 
LIBVLC_API unsigned int libvlc_media_slaves_get (libvlc_media_t *p_md, libvlc_media_slave_t ***ppp_slaves)
 Get a media descriptor's slave list.
 
LIBVLC_API void libvlc_media_slaves_release (libvlc_media_slave_t **pp_slaves, unsigned int i_count)
 Release a media descriptor's slave list.
 

Detailed Description

libvlc_media_t is an abstract representation of a playable media.

It consists of a media location and various optional meta data.

Macro Definition Documentation

◆ libvlc_media_filestat_mtime

#define libvlc_media_filestat_mtime   0

Type of stat that can be requested from libvlc_media_get_filestat()

◆ libvlc_media_filestat_size

#define libvlc_media_filestat_size   1

◆ VLC_FORWARD_DECLARE_OBJECT

#define VLC_FORWARD_DECLARE_OBJECT (   a)    struct a

Typedef Documentation

◆ libvlc_media_close_cb

typedef void(* libvlc_media_close_cb) (void *opaque)

Callback prototype to close a custom bitstream input media.

Parameters
opaqueprivate pointer as set by the libvlc_media_open_cb callback

◆ libvlc_media_open_cb

typedef int(* libvlc_media_open_cb) (void *opaque, void **datap, uint64_t *sizep)

Callback prototype to open a custom bitstream input media.

The same media item can be opened multiple times. Each time, this callback is invoked. It should allocate and initialize any instance-specific resources, then store them in *datap. The instance resources can be freed in the libvlc_media_close_cb callback.

Parameters
opaqueprivate pointer as passed to libvlc_media_new_callbacks()
datapstorage space for a private data pointer [OUT]
sizepbyte length of the bitstream or UINT64_MAX if unknown [OUT]
Note
For convenience, *datap is initially NULL and *sizep is initially 0.
Returns
0 on success, non-zero on error. In case of failure, the other callbacks will not be invoked and any value stored in *datap and *sizep is discarded.

◆ libvlc_media_parse_flag_t

◆ libvlc_media_parsed_status_t

◆ libvlc_media_read_cb

typedef ptrdiff_t(* libvlc_media_read_cb) (void *opaque, unsigned char *buf, size_t len)

Callback prototype to read data from a custom bitstream input media.

Parameters
opaqueprivate pointer as set by the libvlc_media_open_cb callback
bufstart address of the buffer to read data into
lenbytes length of the buffer
Returns
strictly positive number of bytes read, 0 on end-of-stream, or -1 on non-recoverable error
Note
If no data is immediately available, then the callback should sleep.
Warning
The application is responsible for avoiding deadlock situations.

◆ libvlc_media_seek_cb

typedef int(* libvlc_media_seek_cb) (void *opaque, uint64_t offset)

Callback prototype to seek a custom bitstream input media.

Parameters
opaqueprivate pointer as set by the libvlc_media_open_cb callback
offsetabsolute byte offset to seek to
Returns
0 on success, -1 on error.

◆ libvlc_media_slave_t

A slave of a libvlc_media_t.

See also
libvlc_media_slaves_get

◆ libvlc_media_slave_type_t

Type of a media slave: subtitle or audio.

◆ libvlc_media_stats_t

◆ libvlc_media_t

◆ libvlc_media_thumbnail_request_t

libvlc_media_thumbnail_request_t An opaque thumbnail request object

◆ libvlc_media_type_t

◆ libvlc_meta_t

Meta data types.

◆ libvlc_state_t

libvlc media or media_player state

◆ libvlc_thumbnailer_seek_speed_t

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
libvlc_media_option_trusted 
libvlc_media_option_unique 

◆ libvlc_media_parse_flag_t

Parse flags used by libvlc_media_parse_request()

Enumerator
libvlc_media_parse_local 

Parse media if it's a local file.

libvlc_media_parse_network 

Parse media even if it's a network file.

libvlc_media_parse_forced 

Force parsing the media even if it would be skipped.

libvlc_media_fetch_local 

Fetch meta and cover art using local resources.

libvlc_media_fetch_network 

Fetch meta and cover art using network resources.

libvlc_media_do_interact 

Interact with the user (via libvlc_dialog_cbs) when preparsing this item (and not its sub items).

Set this flag in order to receive a callback when the input is asking for credentials.

◆ libvlc_media_parsed_status_t

Parse status used sent by libvlc_media_parse_request() or returned by libvlc_media_get_parsed_status()

Enumerator
libvlc_media_parsed_status_none 
libvlc_media_parsed_status_pending 
libvlc_media_parsed_status_skipped 
libvlc_media_parsed_status_failed 
libvlc_media_parsed_status_timeout 
libvlc_media_parsed_status_done 

◆ libvlc_media_slave_type_t

Type of a media slave: subtitle or audio.

Enumerator
libvlc_media_slave_type_subtitle 
libvlc_media_slave_type_generic 
libvlc_media_slave_type_audio 

◆ libvlc_media_type_t

Media type.

See also
libvlc_media_get_type
Enumerator
libvlc_media_type_unknown 
libvlc_media_type_file 
libvlc_media_type_directory 
libvlc_media_type_disc 
libvlc_media_type_stream 
libvlc_media_type_playlist 

◆ libvlc_meta_t

Meta data types.

Enumerator
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 
libvlc_meta_TrackID 
libvlc_meta_TrackTotal 
libvlc_meta_Director 
libvlc_meta_Season 
libvlc_meta_Episode 
libvlc_meta_ShowName 
libvlc_meta_Actors 
libvlc_meta_AlbumArtist 
libvlc_meta_DiscNumber 
libvlc_meta_DiscTotal 

◆ libvlc_state_t

libvlc media or media_player state

Enumerator
libvlc_NothingSpecial 
libvlc_Opening 
libvlc_Buffering 
libvlc_Playing 
libvlc_Paused 
libvlc_Stopped 
libvlc_Stopping 
libvlc_Error 

◆ libvlc_thumbnailer_seek_speed_t

Enumerator
libvlc_media_thumbnail_seek_precise 
libvlc_media_thumbnail_seek_fast 

Function Documentation

◆ libvlc_media_add_option()

LIBVLC_API void libvlc_media_add_option ( libvlc_media_t p_md,
const char *  psz_options 
)

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.

Note
The options are listed in 'vlc –longhelp' from the command line, e.g. "--sout-all". Keep in mind that available options and their semantics vary across LibVLC versions and builds.
Warning
Not all options affects libvlc_media_t objects: Specifically, due to architectural issues most audio and video options, such as text renderer options, have no effects on an individual media. These options must be set through libvlc_new() instead.
Parameters
p_mdthe media descriptor
psz_optionsthe options (as a string)

◆ libvlc_media_add_option_flag()

LIBVLC_API void libvlc_media_add_option_flag ( libvlc_media_t p_md,
const char *  psz_options,
unsigned  i_flags 
)

Add an option to the media with configurable flags.

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 –longhelp, for instance "--sout-all". Note that all options are not usable on medias: specifically, due to architectural issues, video-related options such as text renderer options cannot be set on a single media. They must be set on the whole libvlc instance instead.

Parameters
p_mdthe media descriptor
psz_optionsthe options (as a string)
i_flagsthe flags for this option

◆ libvlc_media_duplicate()

LIBVLC_API libvlc_media_t * libvlc_media_duplicate ( libvlc_media_t p_md)

Duplicate a media descriptor object.

Warning
the duplicated media won't share forthcoming updates from the original one.
Parameters
p_mda media descriptor object.

◆ libvlc_media_event_manager()

LIBVLC_API libvlc_event_manager_t * libvlc_media_event_manager ( libvlc_media_t p_md)

Get event manager from media descriptor object.

NOTE: this function doesn't increment reference counting.

Parameters
p_mda media descriptor object
Returns
event manager object

◆ libvlc_media_get_codec_description()

LIBVLC_API const char * libvlc_media_get_codec_description ( libvlc_track_type_t  i_type,
uint32_t  i_codec 
)

Get codec description from media elementary stream.

Note, you need to call libvlc_media_parse_request() or play the media at least once before calling this function.

Version
LibVLC 3.0.0 and later.
See also
libvlc_media_track_t
Parameters
i_typei_type from libvlc_media_track_t
i_codeci_codec or i_original_fourcc from libvlc_media_track_t
Returns
codec description

◆ libvlc_media_get_duration()

LIBVLC_API libvlc_time_t libvlc_media_get_duration ( libvlc_media_t p_md)

Get duration (in ms) of media descriptor object item.

Note, you need to call libvlc_media_parse_request() or play the media at least once before calling this function. Not doing this will result in an undefined result.

Parameters
p_mdmedia descriptor object
Returns
duration of media item or -1 on error

◆ libvlc_media_get_filestat()

LIBVLC_API int libvlc_media_get_filestat ( libvlc_media_t p_md,
unsigned  type,
uint64_t *  out 
)

Get a 'stat' value of media descriptor object item.

Note
'stat' values are currently only parsed by directory accesses. This mean that only sub medias of a directory media, parsed with libvlc_media_parse_request() can have valid 'stat' properties.
Version
LibVLC 4.0.0 and later.
Parameters
p_mdmedia descriptor object
typea valid libvlc_media_stat_ define
outfield in which the value will be stored
Returns
1 on success, 0 if not found, -1 on error.

◆ libvlc_media_get_meta()

LIBVLC_API char * libvlc_media_get_meta ( libvlc_media_t p_md,
libvlc_meta_t  e_meta 
)

Read the meta of the media.

Note, you need to call libvlc_media_parse_request() or play the media at least once before calling this function. If the media has not yet been parsed this will return NULL.

See also
libvlc_MediaMetaChanged
Parameters
p_mdthe media descriptor
e_metathe meta to read
Returns
the media's meta

◆ libvlc_media_get_meta_extra()

LIBVLC_API char * libvlc_media_get_meta_extra ( libvlc_media_t p_md,
const char *  psz_name 
)

Read the meta extra of the media.

If the media has not yet been parsed this will return NULL.

See also
libvlc_media_parse
libvlc_media_parse_with_options
Parameters
p_mdthe media descriptor
psz_namethe meta extra to read (nonnullable)
Returns
the media's meta extra or NULL

◆ libvlc_media_get_meta_extra_names()

LIBVLC_API unsigned libvlc_media_get_meta_extra_names ( libvlc_media_t p_md,
char ***  pppsz_names 
)

Read the meta extra names of the media.

Parameters
p_mdthe media descriptor
pppsz_namesthe media's meta extra name array you can access the elements using the return value (count) must be released with libvlc_media_meta_extra_names_release()
Returns
the meta extra count

◆ libvlc_media_get_mrl()

LIBVLC_API char * libvlc_media_get_mrl ( libvlc_media_t p_md)

Get the media resource locator (mrl) from a media descriptor object.

Parameters
p_mda media descriptor object
Returns
string with mrl of media descriptor object

◆ libvlc_media_get_parsed_status()

LIBVLC_API libvlc_media_parsed_status_t libvlc_media_get_parsed_status ( libvlc_media_t p_md)

Get Parsed status for media descriptor object.

See also
libvlc_MediaParsedChanged
libvlc_media_parsed_status_t
libvlc_media_parse_request()
Parameters
p_mdmedia descriptor object
Returns
a value of the libvlc_media_parsed_status_t enum
Version
LibVLC 3.0.0 or later

◆ libvlc_media_get_stats()

LIBVLC_API bool libvlc_media_get_stats ( libvlc_media_t p_md,
libvlc_media_stats_t p_stats 
)

Get the current statistics about the media.

Parameters
p_mdmedia descriptor object
p_statsstructure that contain the statistics about the media (this structure must be allocated by the caller)
Return values
truestatistics are available
falseotherwise

◆ libvlc_media_get_tracklist()

LIBVLC_API libvlc_media_tracklist_t * libvlc_media_get_tracklist ( libvlc_media_t p_md,
libvlc_track_type_t  type 
)

Get the track list for one type.

Version
LibVLC 4.0.0 and later.
Note
You need to call libvlc_media_parse_request() or play the media at least once before calling this function. Not doing this will result in an empty list.
See also
libvlc_media_tracklist_count
libvlc_media_tracklist_at
Parameters
p_mdmedia descriptor object
typetype of the track list to request
Returns
a valid libvlc_media_tracklist_t or NULL in case of error, if there is no track for a category, the returned list will have a size of 0, delete with libvlc_media_tracklist_delete()

◆ libvlc_media_get_type()

LIBVLC_API libvlc_media_type_t libvlc_media_get_type ( libvlc_media_t p_md)

Get the media type of the media descriptor object.

Version
LibVLC 3.0.0 and later.
See also
libvlc_media_type_t
Parameters
p_mdmedia descriptor object
Returns
media type

◆ libvlc_media_get_user_data()

LIBVLC_API void * libvlc_media_get_user_data ( libvlc_media_t p_md)

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

See also
libvlc_media_set_user_data
Parameters
p_mdmedia descriptor object

◆ libvlc_media_meta_extra_names_release()

LIBVLC_API void libvlc_media_meta_extra_names_release ( char **  ppsz_names,
unsigned  i_count 
)

Release a media meta extra names.

Parameters
ppsz_namesmeta extra names array to release
i_countnumber of elements in the array

◆ libvlc_media_new_as_node()

LIBVLC_API libvlc_media_t * libvlc_media_new_as_node ( const char *  psz_name)

Create a media as an empty node with a given name.

See also
libvlc_media_release
Parameters
psz_namethe name of the node
Returns
the new empty media or NULL on error

◆ libvlc_media_new_callbacks()

LIBVLC_API libvlc_media_t * libvlc_media_new_callbacks ( libvlc_media_open_cb  open_cb,
libvlc_media_read_cb  read_cb,
libvlc_media_seek_cb  seek_cb,
libvlc_media_close_cb  close_cb,
void *  opaque 
)

Create a media with custom callbacks to read the data from.

Parameters
open_cbcallback to open the custom bitstream input media
read_cbcallback to read data (must not be NULL)
seek_cbcallback to seek, or NULL if seeking is not supported
close_cbcallback to close the media, or NULL if unnecessary
opaquedata pointer for the open callback
Returns
the newly created media or NULL on error
Note
If open_cb is NULL, the opaque pointer will be passed to read_cb, seek_cb and close_cb, and the stream size will be treated as unknown.
The callbacks may be called asynchronously (from another thread). A single stream instance need not be reentrant. However the open_cb needs to be reentrant if the media is used by multiple player instances.
Warning
The callbacks may be used until all or any player instances that were supplied the media item are stopped.
See also
libvlc_media_release
Version
LibVLC 3.0.0 and later.

◆ libvlc_media_new_fd()

LIBVLC_API libvlc_media_t * libvlc_media_new_fd ( int  fd)

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 not 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 also
libvlc_media_release
Version
LibVLC 1.1.5 and later.
Parameters
fdopen file descriptor
Returns
the newly created media or NULL on error

◆ libvlc_media_new_location()

LIBVLC_API libvlc_media_t * libvlc_media_new_location ( const char *  psz_mrl)

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 must be used (see IETF RFC3986). We recommend using libvlc_media_new_path() instead when dealing with local files.
See also
libvlc_media_release
Parameters
psz_mrlthe media location
Returns
the newly created media or NULL on error

◆ libvlc_media_new_path()

LIBVLC_API libvlc_media_t * libvlc_media_new_path ( const char *  path)

Create a media for a certain file path.

See also
libvlc_media_release
Parameters
pathlocal filesystem path
Returns
the newly created media or NULL on error

◆ libvlc_media_parse_request()

LIBVLC_API int libvlc_media_parse_request ( libvlc_instance_t inst,
libvlc_media_t p_md,
libvlc_media_parse_flag_t  parse_flag,
int  timeout 
)

Parse the media asynchronously with options.

This fetches (local or network) art, meta data and/or tracks information.

To track when this is over you can listen to libvlc_MediaParsedChanged event. However if this functions returns an error, you will not receive any events.

It uses a flag to specify parse options (see libvlc_media_parse_flag_t). All these flags can be combined. By default, media is parsed if it's a local file.

Note
Parsing can be aborted with libvlc_media_parse_stop().
See also
libvlc_MediaParsedChanged
libvlc_media_get_meta
libvlc_media_get_tracklist
libvlc_media_get_parsed_status
libvlc_media_parse_flag_t
Parameters
instLibVLC instance that is to parse the media
p_mdmedia descriptor object
parse_flagparse options:
timeoutmaximum time allowed to preparse the media. If -1, the default "preparse-timeout" option will be used as a timeout. If 0, it will wait indefinitely. If > 0, the timeout will be used (in milliseconds).
Returns
-1 in case of error, 0 otherwise
Version
LibVLC 4.0.0 or later

◆ libvlc_media_parse_stop()

LIBVLC_API void libvlc_media_parse_stop ( libvlc_instance_t inst,
libvlc_media_t p_md 
)

Stop the parsing of the media.

When the media parsing is stopped, the libvlc_MediaParsedChanged event will be sent with the libvlc_media_parsed_status_timeout status.

See also
libvlc_media_parse_request()
Parameters
instLibVLC instance that is to cease or give up parsing the media
p_mdmedia descriptor object
Version
LibVLC 3.0.0 or later

◆ libvlc_media_release()

LIBVLC_API void libvlc_media_release ( libvlc_media_t p_md)

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. If the media descriptor object has been released it should not be used again.

Parameters
p_mdthe media descriptor

◆ libvlc_media_retain()

LIBVLC_API libvlc_media_t * libvlc_media_retain ( libvlc_media_t p_md)

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.

Parameters
p_mdthe media descriptor
Returns
the same object

◆ libvlc_media_save_meta()

LIBVLC_API int libvlc_media_save_meta ( libvlc_instance_t inst,
libvlc_media_t p_md 
)

Save the meta previously set.

Parameters
instLibVLC instance
p_mdthe media descriptor
Returns
true if the write operation was successful

◆ libvlc_media_set_meta()

LIBVLC_API void libvlc_media_set_meta ( libvlc_media_t p_md,
libvlc_meta_t  e_meta,
const char *  psz_value 
)

Set the meta of the media (this function will not save the meta, call libvlc_media_save_meta in order to save the meta)

Parameters
p_mdthe media descriptor
e_metathe meta to write
psz_valuethe media's meta

◆ libvlc_media_set_meta_extra()

LIBVLC_API void libvlc_media_set_meta_extra ( libvlc_media_t p_md,
const char *  psz_name,
const char *  psz_value 
)

Set the meta of the media (this function will not save the meta, call libvlc_media_save_meta in order to save the meta)

Parameters
p_mdthe media descriptor
psz_namethe meta extra to write (nonnullable)
psz_valuethe media's meta extra (nullable) Removed from meta extra if set to NULL

◆ libvlc_media_set_user_data()

LIBVLC_API void libvlc_media_set_user_data ( libvlc_media_t p_md,
void *  p_new_user_data 
)

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

Parameters
p_mdmedia descriptor object
p_new_user_datapointer to user data

◆ libvlc_media_slaves_add()

LIBVLC_API int libvlc_media_slaves_add ( libvlc_media_t p_md,
libvlc_media_slave_type_t  i_type,
unsigned int  i_priority,
const char *  psz_uri 
)

Add a slave to the current media.

A slave is an external input source that may contains an additional subtitle track (like a .srt) or an additional audio track (like a .ac3).

Note
This function must be called before the media is parsed (via libvlc_media_parse_request()) or before the media is played (via libvlc_media_player_play())
Version
LibVLC 3.0.0 and later.
Parameters
p_mdmedia descriptor object
i_typesubtitle or audio
i_priorityfrom 0 (low priority) to 4 (high priority)
psz_uriUri of the slave (should contain a valid scheme).
Returns
0 on success, -1 on error.

◆ libvlc_media_slaves_clear()

LIBVLC_API void libvlc_media_slaves_clear ( libvlc_media_t p_md)

Clear all slaves previously added by libvlc_media_slaves_add() or internally.

Version
LibVLC 3.0.0 and later.
Parameters
p_mdmedia descriptor object

◆ libvlc_media_slaves_get()

LIBVLC_API unsigned int libvlc_media_slaves_get ( libvlc_media_t p_md,
libvlc_media_slave_t ***  ppp_slaves 
)

Get a media descriptor's slave list.

The list will contain slaves parsed by VLC or previously added by libvlc_media_slaves_add(). The typical use case of this function is to save a list of slave in a database for a later use.

Version
LibVLC 3.0.0 and later.
See also
libvlc_media_slaves_add
Parameters
p_mdmedia descriptor object
ppp_slavesaddress to store an allocated array of slaves (must be freed with libvlc_media_slaves_release()) [OUT]
Returns
the number of slaves (zero on error)

◆ libvlc_media_slaves_release()

LIBVLC_API void libvlc_media_slaves_release ( libvlc_media_slave_t **  pp_slaves,
unsigned int  i_count 
)

Release a media descriptor's slave list.

Version
LibVLC 3.0.0 and later.
Parameters
pp_slavesslave array to release
i_countnumber of elements in the array

◆ libvlc_media_subitems()

LIBVLC_API struct libvlc_media_list_t * libvlc_media_subitems ( libvlc_media_t p_md)

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.

Parameters
p_mdmedia descriptor object
Returns
list of media descriptor subitems or NULL

◆ libvlc_media_thumbnail_request_by_pos()

LIBVLC_API libvlc_media_thumbnail_request_t * libvlc_media_thumbnail_request_by_pos ( libvlc_instance_t inst,
libvlc_media_t md,
double  pos,
libvlc_thumbnailer_seek_speed_t  speed,
unsigned int  width,
unsigned int  height,
bool  crop,
libvlc_picture_type_t  picture_type,
libvlc_time_t  timeout 
)

libvlc_media_request_thumbnail_by_pos Start an asynchronous thumbnail generation

If the request is successfully queued, the libvlc_MediaThumbnailGenerated is guaranteed to be emitted (except if the request is destroyed early by the user). The resulting thumbnail size can either be:

  • Hardcoded by providing both width & height. In which case, the image will be stretched to match the provided aspect ratio, or cropped if crop is true.
  • Derived from the media aspect ratio if only width or height is provided and the other one is set to 0.
Parameters
instLibVLC instance to generate the thumbnail with
mdmedia descriptor object
posThe position at which the thumbnail should be generated
speedThe seeking speed
See also
{libvlc_thumbnailer_seek_speed_t}
Parameters
widthThe thumbnail width
heightthe thumbnail height
cropShould the picture be cropped to preserve source aspect ratio
picture_typeThe thumbnail picture type
See also
{libvlc_picture_type_t}
Parameters
timeoutA timeout value in ms, or 0 to disable timeout
Returns
A valid opaque request object, or NULL in case of failure. It must be released by libvlc_media_thumbnail_request_destroy().
Version
libvlc 4.0 or later
See also
libvlc_picture_t
libvlc_picture_type_t

◆ libvlc_media_thumbnail_request_by_time()

LIBVLC_API libvlc_media_thumbnail_request_t * libvlc_media_thumbnail_request_by_time ( libvlc_instance_t inst,
libvlc_media_t md,
libvlc_time_t  time,
libvlc_thumbnailer_seek_speed_t  speed,
unsigned int  width,
unsigned int  height,
bool  crop,
libvlc_picture_type_t  picture_type,
libvlc_time_t  timeout 
)

libvlc_media_request_thumbnail_by_time Start an asynchronous thumbnail generation

If the request is successfully queued, the libvlc_MediaThumbnailGenerated is guaranteed to be emitted (except if the request is destroyed early by the user). The resulting thumbnail size can either be:

  • Hardcoded by providing both width & height. In which case, the image will be stretched to match the provided aspect ratio, or cropped if crop is true.
  • Derived from the media aspect ratio if only width or height is provided and the other one is set to 0.
Parameters
instLibVLC instance to generate the thumbnail with
mdmedia descriptor object
timeThe time at which the thumbnail should be generated
speedThe seeking speed
See also
{libvlc_thumbnailer_seek_speed_t}
Parameters
widthThe thumbnail width
heightthe thumbnail height
cropShould the picture be cropped to preserve source aspect ratio
picture_typeThe thumbnail picture type
See also
{libvlc_picture_type_t}
Parameters
timeoutA timeout value in ms, or 0 to disable timeout
Returns
A valid opaque request object, or NULL in case of failure. It must be released by libvlc_media_thumbnail_request_destroy() and can be cancelled by calling it early.
Version
libvlc 4.0 or later
See also
libvlc_picture_t
libvlc_picture_type_t

◆ libvlc_media_thumbnail_request_destroy()

LIBVLC_API void libvlc_media_thumbnail_request_destroy ( libvlc_media_thumbnail_request_t p_req)

libvlc_media_thumbnail_destroy destroys a thumbnail request

Parameters
p_reqAn opaque thumbnail request object.

This will also cancel the thumbnail request, no events will be emitted after this call.