View source for MediaControlAPI

== Description ==

The MediaControl API is the extended API to control VLC from external applications (extension of LibVLC). Its core part (playback control) has been taken from the [http://www.omg.org/docs/formal/00-01-03.pdf OMG Audio/Video Stream specification], and extended with additional functionalities. An [http://liris.cnrs.fr/advene/download/MediaControl.idl IDL specification MediaControl.idl] has been the base of this work.

The idea is to define a generic video-player API, that could be reused with other players.

The API is defined in [http://trac.videolan.org/vlc/browser/trunk/include/vlc/control.h "include/vlc/control.h"] and implemented in 
[http://trac.videolan.org/vlc/browser/trunk/src/control "src/control"].

The Doxygen documentation can be found at [http://developers.videolan.org/vlc/vlc/doc/doxygen/html/control_8h.html].

== Current status ==

The API currently includes functions for the following things:
* Playback
** Basic features (play/pause/stop)
** Seeking
** Basic playlist interaction
** Stream information
* Audio/Video
** Snapshot control (requires the use of the snapshot vout module via the clone video filter; invoke with: vlc --video-filter clone --clone-vout-list default,snapshot )
** OSD display (of text and SVG graphics through the svg rendering module)
** Volume setting
** Setting the visual ID of an embedding window

== Current uses ==

The MediaControl API is used by the following modules :
* the [[PythonBinding]]
* the [http://trac.videolan.org/vlc/browser/trunk/bindings/modules/control/corba CORBA interface module]
* the [[JavaBinding]]

== Foreseen evolutions ==

The following evolutions should be integrated in the API, but discussion is necessary to ensure that they are sufficiently flexible to match various needs :
* sound_[sg]et_volume: normalize volume in [0..100]
* implement get_api_version() or get_capabilities() (which would return the list of capabilities supported by the player: ("core", "svg", "snapshot", etc)
* Complete the implementation. For instance, the frame-by-frame unit (mediacontrol_SampleCount) is not implemented, and the stop/pause do not take the Position parameter into account (they are applied immediately).
* Fix VLC initialization on Win32 so that it uses the registry key to find the default plugins directory by default. Currently, it uses the vlc.exe path, which it cannot find when using VLC embedded. A workaround is to chdir to the vlc.exe directory before instanciating the MediaControl() object.

== Todo ==

* Add missing features (see next section)
* Bind the new API to .NET

== Full API ==

=== Initialization ===
* mediacontrol_new ''Create a new instance of a MediaControl object''
* '''mediacontrol_get_version''' ''Return the version of the API''
* mediacontrol_new_from_object(object_id) ''Use an existing VLC object id to initialize the MediaControl object''
* mediacontrol_exit ''Stop VLC''

=== Playback control ===

''Playback control methods use a Position object as parameter to specify start or stop position.''

* mediacontrol_start( position )
* mediacontrol_pause( position ) ''The position parameter may be ignored by bindings. In this case, it defaults to a 0-relative position.''
* mediacontrol_resume( position )
* mediacontrol_stop( position )
* mediacontrol_get_media_position( origin, key )
* mediacontrol_set_media_position( position )
* '''mediacontrol_set_rate'''
* '''mediacontrol_get_rate'''

=== Media info ===

* mediacontrol_get_stream_information 

See [[Talk:MediaControlAPI]]

=== Playlist ===

* mediacontrol_playlist_add_item ( MRL ) '''should return item id'''
* mediacontrol_playlist_clear()
* mediacontrol_playlist_get_list
* '''mediacontrol_playlist_next'''
* '''mediacontrol_playlist_prev'''
* '''mediacontrol_playlist_play( id )'''
* '''mediacontrol_playlist_remove( id )'''
* '''mediacontrol_playlist_sort( int )''' <- int is a const, the rule to sort with

See [[Talk:MediaControlAPI]]


=== Video ===
* mediacontrol_snapshot(position) <-- returns an RGB picture '''should probably use vout_Snapshot instead of the snapshot module''' (but cf discussion in [[VoutReworkUserRequirements]] and [[PythonBinding]])
* mediacontrol_all_snapshots() ''Return a list of RGB pictures contained in the cache. Could allow for precise selection of a snapshot.''
* mediacontrol_display_text( text, start_time, stop_time ) ''Send a text to the text renderer.''
* mediacontrol_set_visual(visual_id) ''Set the visual ID when embedding VLC''
* '''mediacontrol_toggle_fullscreen'''
* '''mediacontrol_set_fullscreen( boolean )'''
* '''mediacontrol_get_fullscreen( boolean )''' <-- Maybe integrate a variable get facility -> Too VLC-specific
* '''mediacontrol_apply_filter ( filter, position )''' <-- is there a filter structure in VLC? -> Too VLC-specific

=== Audio ===
* mediacontrol_sound_get_volume
* mediacontrol_sound_set_volume
* '''mediacontrol_sound_mute'''

=== VLM ===
* '''mediacontrol_vlm_add_broadcast( name, input, output, options)'''
* '''mediacontrol_vlm_add_vod'''
* '''mediacontrol_vlm_get_broadcasts'''
* '''mediacontrol_vlm_get_vods'''
* '''mediacontrol_vlm_delete_broadcast( name )'''
* '''mediacontrol_vlm_delete_vod( name )'''
* '''mediacontrol_vlm_load( file )'''
* '''mediacontrol_vlm_save( file )'''