[vlc-commits] Add warnings in the doc about options not available at the media level

[Olivier Aubert]

vlc/python | branch: master | Olivier Aubert <contact at olivieraubert.net> | Sun Feb 15 20:32:53 2015 +0100| [d1d364a693a1242bb94f9b2a916b25d2a541beb1] | committer: Olivier Aubert

Add warnings in the doc about options not available at the media level

Fixes #4

> http://git.videolan.org/gitweb.cgi/vlc/python.git/?a=commit;h=d1d364a693a1242bb94f9b2a916b25d2a541beb1
---

 override.py |   28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/override.py b/override.py
index 5869de4..9db36ee 100644
--- a/override.py
+++ b/override.py
@@ -55,13 +55,14 @@ class Instance:
         local path. If you need more control, directly use
         media_new_location/media_new_path methods.
 
-        Options can be specified as supplementary string parameters, e.g.
+        Options can be specified as supplementary string parameters,
+        but note that many options cannot be set at the media level,
+        and rather at the Instance level. For instance, the marquee
+        filter must be specified when creating the vlc.Instance or
+        vlc.MediaPlayer.
 
-        C{m = i.media_new('foo.avi', 'sub-filter=marq{marquee=Hello}', 'vout-filter=invert')}
-
-        Alternatively, the options can be added to the media using the Media.add_options method:
-
-        C{m.add_options('foo.avi', 'sub-filter=marq at test{marquee=Hello}', 'video-filter=invert')}
+        Alternatively, options can be added to the media using the
+        Media.add_options method (with the same limitation).
 
         @param options: optional media option=value strings
         """
@@ -144,13 +145,10 @@ class Media:
     def add_options(self, *options):
         """Add a list of options to the media.
 
-        Options must be written without the double-dash, e.g.:
-
-        C{m.add_options('sub-filter=marq at test{marquee=Hello}', 'video-filter=invert')}
-
-        Alternatively, the options can directly be passed in the Instance.media_new method:
-
-        C{m = instance.media_new('foo.avi', 'sub-filter=marq at test{marquee=Hello}', 'video-filter=invert')}
+        Options must be written without the double-dash. Warning: most
+        audio and video options, such as text renderer, have no
+        effects on an individual media. These options must be set at
+        the vlc.Instance or vlc.MediaPlayer instanciation.
 
         @param options: optional media option=value strings
         """
@@ -232,6 +230,10 @@ class MediaPlayer:  #PYCHOK expected (comment is lost)
     def set_mrl(self, mrl, *options):
         """Set the MRL to play.
 
+        Warning: most audio and video options, such as text renderer,
+        have no effects on an individual media. These options must be
+        set at the vlc.Instance or vlc.MediaPlayer instanciation.
+
         @param mrl: The MRL
         @param options: optional media option=value strings
         @return: the Media object