Difference between revisions of "MediaControlAPI"

From VideoLAN Wiki
Jump to navigation Jump to search
m
m (See also: MediaControlIDL)
 
(38 intermediate revisions by 18 users not shown)
Line 1: Line 1:
== Description ==
+
{{See also|MediaControlIDL}}
 +
{{Historical|The MediaControl API was removed from VLC in 2010.}}
 +
== Description ==
  
The MediaControl API is a generic Media player API. The idea is to define a generic video-player API, that could be reused with other players. It will be implemented in VLC by using the [[ExternalAPI#VLC_Control|New libvlc API]].
+
The MediaControl API is a generic Media player API. The idea is to define a generic video-player API, that could be reused with other players. It is implemented in VLC by using the new [[LibVLC]] API, and both APIs can cooperate (i.e. you can instanciate a MediaControl object from an existing libvlc instance, and vice-versa).  
  
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.
+
Its core part (playback control) has been taken from the [http://www.omg.org/cgi-bin/doc?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.  
  
FIXME : The API is defined in [http://trac.videolan.org/vlc/browser/trunk/include/vlc/control.h "include/vlc/control.h"] and implemented in  
+
FIXME : The API is defined in [https://trac.videolan.org/vlc/browser/trunk/include/vlc/mediacontrol.h "include/vlc/mediacontrol.h"] and implemented in [https://trac.videolan.org/vlc/browser/trunk/src/control "src/control"].  
[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].
+
The Doxygen documentation can be found at [https://www.videolan.org/developers/vlc/doc/doxygen/html/mediacontrol_8h.html].  
  
== Current status ==
+
== Current status ==
  
The API currently includes functions for the following things:
+
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 ==
+
*Playback
 +
**Basic features (play/pause/stop)
 +
**Seeking
 +
**Setting/getting the played media
 +
**Getting stream information
 +
*Audio/Video
 +
**Snapshot control (on the fly only)
 +
**OSD display (of text and SVG graphics through the svg rendering module)
 +
**Volume setting
 +
**Setting the visual ID of an embedding window
  
The MediaControl API is used by the following modules :
+
== Current uses  ==
* the [[PythonBinding]]
 
* the [http://trac.videolan.org/vlc/browser/trunk/bindings/modules/control/corba CORBA interface module]
 
* the [[JavaBinding]]
 
  
== Foreseen evolutions ==
+
The MediaControl API is used by the following modules :
  
The following evolutions should be integrated in the API, but discussion is necessary to ensure that they are sufficiently flexible to match various needs :
+
*the [[PythonBinding]]  
* sound_[sg]et_volume: normalize volume in [0..100]
+
*the [[JavaBinding]]
* 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.
 
  
== Full API ==
+
== Foreseen evolutions  ==
  
Here is an IDL description of the MediaControlAPI
+
The following evolutions should be integrated in the API, but discussion is necessary to ensure that they are sufficiently flexible to match various needs :
  
<pre>
+
*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.
 +
 
 +
== Current API  ==
 +
 
 +
Here is an IDL description of the current version of MediaControlAPI (from git rev. 445d63e0e38053, on 20080423). In case of doubt, refer to the [http://trac.videolan.org/vlc/browser/trunk/include/vlc/mediacontrol.h mediacontrol.h file].
 +
<syntaxhighlight lang="c">/*
 +
  Module inspired by the MediaControl IDL
 +
*/
 
module VLC {
 
module VLC {
  
   const float VERSION = 1.0;
+
   const float VERSION = 0.2;
  
 
   enum PositionOrigin {
 
   enum PositionOrigin {
     AbsolutePosition,  
+
     AbsolutePosition, RelativePosition, ModuloPosition
    RelativePosition,  
 
    // Like relative, but wraps at the end of a file for instance:
 
    ModuloPosition
 
 
   };
 
   };
 
+
 
 
   enum PositionKey {
 
   enum PositionKey {
    // For raw access
+
     ByteCount, SampleCount, MediaTime
     ByteCount,  
 
    // Frame number
 
    SampleCount,
 
    // In milliseconds
 
    MediaTime
 
 
   };
 
   };
 
+
 
 
   struct Position {
 
   struct Position {
 
     PositionOrigin origin;
 
     PositionOrigin origin;
Line 69: Line 65:
 
     long long value;
 
     long long value;
 
   };
 
   };
 
+
 
   exception PositionKeyNotSupported   { string message; };
+
   exception PositionKeyNotSupported { string message; };
 
   exception PositionOriginNotSupported { string message; };
 
   exception PositionOriginNotSupported { string message; };
   exception InvalidPosition           { string message; };
+
   exception InvalidPosition         { string message; };
  exception PlaylistException          { string message; };
+
   exception InternalException       { string message; };
   exception InternalException         { string message; };
 
  
  typedef sequence<string> PlaylistSeq;
 
 
   typedef sequence<octet> ByteSeq;
 
   typedef sequence<octet> ByteSeq;
 
+
 
 
   struct RGBPicture {
 
   struct RGBPicture {
 
     short width;
 
     short width;
Line 84: Line 78:
 
     long type;
 
     long type;
 
     ByteSeq data;
 
     ByteSeq data;
    // Timestamp (absolute position in the movie) in ms
 
 
     long long date;
 
     long long date;
 
   };
 
   };
 
+
    
   struct StreamInformation {
 
    short width;
 
    short height;
 
    float aspect_ratio;
 
    long bitrate;
 
    string codec;
 
    string author;
 
  };
 
 
 
 
   typedef sequence<RGBPicture> RGBPictureSeq;
 
   typedef sequence<RGBPicture> RGBPictureSeq;
 
+
 
 +
  /* Cf stream_control.h */
 
   enum PlayerStatus { PlayingStatus, PauseStatus, ForwardStatus, BackwardStatus, InitStatus, EndStatus, UndefinedStatus };
 
   enum PlayerStatus { PlayingStatus, PauseStatus, ForwardStatus, BackwardStatus, InitStatus, EndStatus, UndefinedStatus };
 
+
 
   struct StatusInformation {
+
   struct StreamInformation {
 
     PlayerStatus streamstatus;
 
     PlayerStatus streamstatus;
     string url;             /* The URL of the current media stream   */
+
     string url;       /* The URL of the current media stream */
     long long position;    /* actual location in the stream (in ms) */
+
    long mux_rate;    /* the rate we read the stream in bytes/s */   
     long long length;       /* total length of the stream (in ms)   */
+
     long long position;    /* actual location in the area (in arbitrary units) */
 +
     long long size;         /* total size of the area (in arbitrary units) */
 
   };
 
   };
 
+
    
  interface Playlist
+
  // MediaControl interface is similar to
   {
+
  // ControlledStream interface in MSS.
    // Return a playlist item id
+
  // It can be inherited by flow endpoints or
    int add(in string a_file)
+
  // FlowConnection interfaces.
      raises (PlaylistException);
 
 
 
    void next(in string a_file)
 
      raises (PlaylistException);
 
 
 
    void prev(in string a_file)
 
      raises (PlaylistException);
 
 
 
    // Set the new current item
 
    void set(int item_id)
 
      raises (PlaylistException);
 
 
 
    void remove(int item_id)
 
      raises (PlaylistException);
 
 
 
    // Clear the whole playlist
 
    void clear ()
 
      raises (PlaylistException);
 
 
 
    // Return the list of files in playlist
 
    PlaylistSeq get_list ()
 
      raises (PlaylistException);
 
  }
 
 
 
  // MediaControl interface is similar to
 
  // ControlledStream interface in MSS.
 
  // It can be inherited by flow endpoints or
 
  // FlowConnection interfaces.
 
 
   interface MediaControl
 
   interface MediaControl
 
   {
 
   {
     // *** Initialization
+
     Position get_media_position(in PositionOrigin an_origin,
    // Exit the player
+
in PositionKey a_key)
    oneway void exit ();
+
      raises (InternalException, PositionKeyNotSupported);
 
+
      
     // Return the IDL API version
+
     void set_media_position(in Position a_position)
     string get_api_version();
+
      raises (InternalException, PositionKeyNotSupported, InvalidPosition);
 
+
   
    // Return the player version (player name + version)
 
    string get_player_version();
 
 
 
    // *** Playback control
 
    // The a_position parameters are facultative.
 
 
     void start(in Position a_position)
 
     void start(in Position a_position)
 
       raises (InternalException, InvalidPosition, PlaylistException);
 
       raises (InternalException, InvalidPosition, PlaylistException);
 
 
     void pause(in Position a_position)
 
     void pause(in Position a_position)
 
       raises (InternalException, InvalidPosition);
 
       raises (InternalException, InvalidPosition);
 
 
     void resume(in Position a_position)
 
     void resume(in Position a_position)
 
       raises (InternalException, InvalidPosition);
 
       raises (InternalException, InvalidPosition);
 
 
     void stop(in Position a_position)
 
     void stop(in Position a_position)
 
       raises (InternalException, InvalidPosition);
 
       raises (InternalException, InvalidPosition);
  
     Position get_media_position(in PositionOrigin an_origin,
+
     oneway void exit (); // Exits the player (not in the original spec)
in PositionKey a_key)
 
      raises (InternalException, PositionKeyNotSupported);
 
 
 
    void set_media_position(in Position a_position)
 
      raises (InternalException, PositionKeyNotSupported, InvalidPosition);
 
  
     // Rate control. The rate is a signed value, corresponding to
+
     // Set/get the current media file/URL
    // the percentage of the speed (+100 = normal, -100 = reverse...)
+
     void set_mrl (in string a_file)
 
+
       raises (PlaylistException);
    int get_rate()
+
     string get_mrl ()
      raises (InternalException);
+
       raises (PlaylistException);
 
 
     void set_rate(int rate)
 
       raises (InternalException);
 
 
 
    // *** Media information
 
 
 
     StatusInformation get_status_information ()
 
       raises (InternalException);
 
 
 
    // Return information about the current stream
 
    StreamInformation get_stream_information ()
 
      raises (InternalException);
 
 
 
    // *** Playlist handling
 
    Playlist playlist()
 
      raises (InternalException);
 
 
 
    // *** Video
 
  
     // Return a snapshot of the currently displayed picture
+
     // Returns a snapshot of the currently displayed picture
 
     RGBPicture snapshot (in Position a_position)
 
     RGBPicture snapshot (in Position a_position)
 
       raises (InternalException);
 
       raises (InternalException);
  
    // Return the whole snapshot cache contents
 
 
     RGBPictureSeq all_snapshots ()
 
     RGBPictureSeq all_snapshots ()
 
       raises (InternalException);
 
       raises (InternalException);
  
     // Display the message string as caption,  
+
     // Displays the message string, between "begin" and "end" positions
    // between "begin" and "end" positions
+
     void display_text (in string message, in Position begin, in Position end)
     void render_text (in string message, in Position begin, in Position end)
 
 
       raises (InternalException);
 
       raises (InternalException);
  
     // Set the visual ID (XID in X-Window, HWIN on Win32, ??? on MacOS
+
     StreamInformation get_stream_information ()
    // X) for the player window
 
    void set_visual(long xid)
 
 
       raises (InternalException);
 
       raises (InternalException);
 
+
      
     boolean get_fullscreen()
 
      raises (InternalException);
 
 
 
    void set_fullscreen(boolean full)
 
      raises (InternalException);
 
 
 
    // *** Audio
 
 
 
    // Volume is normalized in [0..100]
 
 
     unsigned short sound_get_volume()
 
     unsigned short sound_get_volume()
 
       raises (InternalException);
 
       raises (InternalException);
Line 230: Line 144:
 
       raises (InternalException);
 
       raises (InternalException);
  
    void sound_mute()
 
      raises (InternalException);
 
 
   };
 
   };
 
};
 
};
</pre>
+
</syntaxhighlight>
 +
 
 +
[[Category:Bindings]]

Latest revision as of 06:09, 29 March 2019

See also: MediaControlIDL
This page is obsolete and kept only for historical interest. It may document features that are obsolete, superseded, or irrelevant. Do not rely on the information here being up-to-date.
Additional information: The MediaControl API was removed from VLC in 2010.

Description

The MediaControl API is a generic Media player API. The idea is to define a generic video-player API, that could be reused with other players. It is implemented in VLC by using the new LibVLC API, and both APIs can cooperate (i.e. you can instanciate a MediaControl object from an existing libvlc instance, and vice-versa).

Its core part (playback control) has been taken from the OMG Audio/Video Stream specification, and extended with additional functionalities. An IDL specification MediaControl.idl has been the base of this work.

FIXME : The API is defined in "include/vlc/mediacontrol.h" and implemented in "src/control".

The Doxygen documentation can be found at [1].

Current status

The API currently includes functions for the following things:

  • Playback
    • Basic features (play/pause/stop)
    • Seeking
    • Setting/getting the played media
    • Getting stream information
  • Audio/Video
    • Snapshot control (on the fly only)
    • 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 :

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.

Current API

Here is an IDL description of the current version of MediaControlAPI (from git rev. 445d63e0e38053, on 20080423). In case of doubt, refer to the mediacontrol.h file.

/*
  Module inspired by the MediaControl IDL
 */
module VLC {

  const float VERSION = 0.2;

  enum PositionOrigin {
    AbsolutePosition, RelativePosition, ModuloPosition
  };
  
  enum PositionKey {
    ByteCount, SampleCount, MediaTime
  };
  
  struct Position {
    PositionOrigin origin;
    PositionKey key;
    long long value;
  };
  
  exception PositionKeyNotSupported { string message; };
  exception PositionOriginNotSupported { string message; };
  exception InvalidPosition         { string message; };
  exception InternalException       { string message; };

  typedef sequence<octet> ByteSeq;
  
  struct RGBPicture {
    short width;
    short height;
    long type;
    ByteSeq data;
    long long date;
  };
  
  typedef sequence<RGBPicture> RGBPictureSeq;
  
  /* Cf stream_control.h */
  enum PlayerStatus { PlayingStatus, PauseStatus, ForwardStatus, BackwardStatus, InitStatus, EndStatus, UndefinedStatus };
  
  struct StreamInformation {
    PlayerStatus streamstatus;
    string url;        /* The URL of the current media stream */
    long mux_rate;     /* the rate we read the stream in bytes/s */    
    long long position;     /* actual location in the area (in arbitrary units) */
    long long size;         /* total size of the area (in arbitrary units) */
  };
  
   // MediaControl interface is similar to
   // ControlledStream interface in MSS.
   // It can be inherited by flow endpoints or
   // FlowConnection interfaces.
  interface MediaControl
  {
    Position get_media_position(in PositionOrigin an_origin,
				in PositionKey a_key)
      raises (InternalException, PositionKeyNotSupported);
    
    void set_media_position(in Position a_position)
      raises (InternalException, PositionKeyNotSupported, InvalidPosition);
     
    void start(in Position a_position)
      raises (InternalException, InvalidPosition, PlaylistException);
    void pause(in Position a_position)
      raises (InternalException, InvalidPosition);
    void resume(in Position a_position)
      raises (InternalException, InvalidPosition);
    void stop(in Position a_position)
      raises (InternalException, InvalidPosition);

    oneway void exit (); // Exits the player (not in the original spec)

    // Set/get the current media file/URL
    void set_mrl (in string a_file)
      raises (PlaylistException);
    string get_mrl ()
      raises (PlaylistException);

    // Returns a snapshot of the currently displayed picture
    RGBPicture snapshot (in Position a_position)
      raises (InternalException);

    RGBPictureSeq all_snapshots ()
      raises (InternalException);

    // Displays the message string, between "begin" and "end" positions
    void display_text (in string message, in Position begin, in Position end)
      raises (InternalException);

    StreamInformation get_stream_information ()
      raises (InternalException);
    
    unsigned short sound_get_volume()
      raises (InternalException);

    void sound_set_volume(in unsigned short volume)
      raises (InternalException);

  };
};