xmms.control
index
/home/flo/debian/pyxmms/pyxmms-2.04/build/lib.linux-i686-2.4/xmms/control.py

Python interface to XMMS --- control module.
 
This module provides a Python interface to control XMMS (the X
MultiMedia System), an audio and video player for Unix-like
platforms.
 
This module provides bindings for all the xmms_remote_* functions
accessible through the libxmms library (which comes with XMMS), plus
a few higher-level functions that I (Florent Rougon) find useful.
 
The function names and mappings between the calling syntax of the C
functions from libxmms and that of their Python bindings are meant to
be mechanical (see below).
 
Note: I use the expression "Python binding for foo()" for a Python
function that wraps (thus calls) directly, not doing additional work,
the C function foo() defined in libxmms.
 
 
Function names
--------------
 
The binding for the libxmms function xmms_remote_foo() will be called
foo; therefore, you will probably use it in this way:
 
  import xmms.control
 
  res = xmms.control.foo(arg, ...)
 
 
Calling syntax -- passing arguments and getting results
-------------------------------------------------------
 
Each xmms_remote_* function from libxmms takes as its first argument
the XMMS session to control. With xmms.control, this argument is
optional (defaulting to 0, which is generally what you want if you
don't launch multiple XMMS sessions at once) and comes last.
 
For the other arguments:
 - the type mapping should be obvious (if the C function expects a
   gint, the Python binding expects a Python integer, same for char *
   and strings, gfloats and floats, etc.); when the C function
   expects a list (such as a GList *), the Python binding expects a
   sequence (like a list or a tuple). gboolean types are mapped to
   Python integers (FALSE is mapped to 0 and TRUE to 1).
 
   Except for 'session', which has to come last so as to be optional,
   the order of the arguments is always preserved.
 
   Example:
 
     void xmms_remote_set_volume(gint session, gint vl, gint vr)
 
   is mapped to:
 
     set_volume(vl, vr, session)
 
   where 'vl' and 'vr' have to be Python integers and 'session' (also
   an integer), is optional and defaults to 0.
   Note: 'vl' and 'vr' stand for left and right volume, respectively.
   
 - if the C function returns values through the use of pointers,
   these are returned by the corresponding Python binding and
   therefore are removed from the argument list of the Python
   binding. The type/structure of the return value is the most
   obvious one I could think of (e.g. a single integer if the
   function returns a gboolean). The most non-obvious example is
   indeed quite simple, as you can see:
 
     void xmms_remote_get_eq(gint session, gfloat *preamp,
                             gfloat **bands)
 
   which returns a global preamp gain (in dB) and a list of gains for
   10 frequeny bands. It is called like this in Python:
 
     (preamp, bands) = get_eq(session)
 
   where 'session' is optional (see above), 'preamp' is a float and
   'bands' is a 10-tuple of floats.
 
   Note: this is written from this module's scope, but in real life,
   you would of course probably have:
 
     import xmms.control
 
     [...]
 
     (preamp, bands) = xmms.control.get_eq(session)
 
 
Functions exported by this module
---------------------------------
 
* From libxmms
 
  playlist
  playlist_add
  playlist_delete
  playlist_clear
  playlist_add_url_string
  playlist_ins_url_string
 
  get_playlist_length
  get_playlist_pos
  set_playlist_pos
 
  get_playlist_file
  get_playlist_title
  get_playlist_time
 
  play
  pause
  play_pause
  stop
  eject
  playlist_prev
  playlist_next
  jump_to_time
 
  is_running
  is_playing
  is_paused
 
  get_output_time
  get_info
 
  get_volume
  set_volume
  get_main_volume
  set_main_volume
 
  get_balance
  set_balance
 
  get_eq
  set_eq
  get_eq_preamp
  set_eq_preamp
  get_eq_band
  set_eq_band
 
  get_skin
  set_skin
 
  main_win_toggle
  pl_win_toggle
  eq_win_toggle
 
  is_main_win
  is_pl_win
  is_eq_win
 
  show_prefs_box
  show_about_box
 
  toggle_aot
 
  toggle_repeat
  toggle_shuffle
 
  is_repeat
  is_shuffle
 
  get_version
 
  quit
 
  play_files (deprecated in libxmms)
 
 
* Specific to this module (no direct binding in libxmms)
 
  playlist_add_allow_relative
  enqueue_and_play
  enqueue_and_play_launch_if_session_not_started
  fade_out
 
 
Exceptions specific to this module
----------------------------------
 
ExecutableNotFound
RequestedSessionDoesNotComeUp
InvalidFadeOutAction
 
They are all subclasses of xmms.error.

 
Modules
       
xmms.common
os
re
string
time

 
Classes
       
xmms.common.error(exceptions.Exception)
ExecutableNotFound
InvalidFadeOutAction
RequestedSessionDoesNotComeUp

 
class ExecutableNotFound(xmms.common.error)
    Exception raised when the XMMS executable can't be found.
 
 
Method resolution order:
ExecutableNotFound
xmms.common.error
exceptions.Exception

Data and other attributes defined here:
ExceptionShortDescription = 'Executable not found'

Methods inherited from xmms.common.error:
__init__(self, message=None)
__str__(self)
complete_message(self)

Methods inherited from exceptions.Exception:
__getitem__(...)

 
class InvalidFadeOutAction(xmms.common.error)
    Exception raised when fade_out is given an invalid action.
 
 
Method resolution order:
InvalidFadeOutAction
xmms.common.error
exceptions.Exception

Data and other attributes defined here:
ExceptionShortDescription = 'Invalid action'

Methods inherited from xmms.common.error:
__init__(self, message=None)
__str__(self)
complete_message(self)

Methods inherited from exceptions.Exception:
__getitem__(...)

 
class RequestedSessionDoesNotComeUp(xmms.common.error)
    Exception raised when a started XMMS session still doesn't answer after a specified timeout.
 
 
Method resolution order:
RequestedSessionDoesNotComeUp
xmms.common.error
exceptions.Exception

Data and other attributes defined here:
ExceptionShortDescription = "Requested session doesn't come up"

Methods inherited from xmms.common.error:
__init__(self, message=None)
__str__(self)
complete_message(self)

Methods inherited from exceptions.Exception:
__getitem__(...)

 
Functions
       
eject(...)
Show the eject dialog box.
 
eject(session=0) -> None
 
session -- the XMMS session to act on
enqueue_and_play(seq, session=0)
Add files/URLs to the playlist and start playing from the first one.
 
seq     -- a sequence of files/URLs
session -- the XMMS session to act on
 
The files/URLs in seq are added to the playlist and XMMS is asked
to play starting at the first element of seq.
 
Return None.
enqueue_and_play_launch_if_session_not_started(seq, xmms_prg='xmms', session=0, poll_delay=0.10000000000000001, timeout=10.0)
Add files/URLs to the playlist and start playing from the first one.
 
seq        -- a sequence of files/URLs
xmms_prg   -- the name (absolute or looked up in the PATH)
              of an XMMS binary to invoke in case the specified
              session is not running
session    -- the XMMS session to act on
poll_delay -- poll delay, in seconds (float, see below)
timeout    -- timeout while polling, in seconds (float, see below)
 
This function is identical to enqueue_and_play except that it
spawns an XMMS process if the requested session is not running.
 
When it does spawn an XMMS process, it has to wait until XMMS is
ready to handle requests (here, the first request will be
enqueue_and_play). It will therefore check every 'poll_delay'
seconds whether the requested session is ready, and abort after
'timeout' seconds of unsuccessful checks, raising
xmms.control.RequestedSessionDoesNotComeUp. If we get that far,
it may be that your system is very slow, or more likely that the
XMMS session that was started by this function is not the one
numbered 'session': there is currently no way to start an XMMS
session for a chosen number; we have to guess the number of the
session that will be started...
 
Return None.
 
Notable exceptions:
    - xmms.control.ExecutableNotFound is raised if 'xmms_prg'
      can't be found, read and executed.
    - xmms.control.RequestedSessionDoesNotComeUp is raised if the
      requested session is still unable to handle requests
      'timeout' seconds after the XMMS process was started by
      this function.
eq_win_toggle(...)
Hide or show the equalizer window.
 
eq_win_toggle(display, session=0) -> None
 
This is not a real toggle function: you have to specify the
`display' argument.
 
display -- 1 to display the window, 0 to hide it
session -- the XMMS session to act on
fade_out(action='stop', nb_steps=20, step_duration=0.5, restore_volume=1, session=0)
Fade out the volume to stop or pause the playback.
 
Progressively decrease the main volume, then stop or pause
(depending on the 'action' argument), then optionally restore
the original main volume setting.
 
action         -- a string, either "stop" or "pause"
nb_steps       -- number of decrease-volume steps to use
step_duration  -- duration of a step (float, in seconds)
restore_volume -- boolean (0 = false, 1 = true) telling whether
                  to restore the original main volume setting
                  after the fade out
session        -- the XMMS session to act on
 
Return None.
 
Notable exception: xmms.control.InvalidFadeOutAction is raised if
'action' is invalid.
get_balance(...)
Get the balance value.
 
get_balance(session=0) -> balance (integer)
 
session -- the XMMS session to contact
get_eq(...)
Get the equalizer settings.
 
get_eq(session=0) -> (preamp, (band0, band1, ... band9))
 
preamp, band0, ... band9 are all floats (gains in dB).
 
session -- the XMMS session to contact
get_eq_band(...)
Get the equalizer setting for a given band.
 
get_eq_band(band, session=0) -> gain in dB (float)
 
band    -- integer between 0 and 9 (both inclusive), specifying
           the equalizer band from which the setting is to be
           retrieved. 0 is for the lowest frequency and 9 for the
           highest one.
session -- the XMMS session to contact
get_eq_preamp(...)
Get the equalizer preamp value.
 
get_eq_preamp(session=0) -> preamp in dB (float)
 
session -- the XMMS session to contact
get_info(...)
Get information about the current playlist entry.
 
get_info(session=0) -> (rate, frequency, number_of_channels)
 
The elements of the returned tuple are all integers.
 
session -- the XMMS session to contact
get_main_volume(...)
Get the greater of left and right volumes.
 
get_main_volume(session=0) -> volume (integer)
 
session -- the XMMS session to contact
get_output_time(...)
Get the time since the beginning of the current playlist entry.
 
get_output_time(session=0) -> integer value in ms
 
session -- the XMMS session to contact
get_playlist_file(...)
Get the file name corresponding to a given entry in the playlist.
 
get_playlist_file(index, session=0) -> absolute filename (string)
 
index   -- index (starting at 0) of the playlist entry
session -- the XMMS session to contact
get_playlist_length(...)
Get the playlist length (number of files/URLs).
 
get_playlist_length(session=0) -> length (integer)
 
session -- the XMMS session to contact
get_playlist_pos(...)
Get the current playlist position.
 
get_playlist_pos(session=0) -> position (integer)
 
The count starts at 0 (first playlist entry).
 
session -- the XMMS session to contact
get_playlist_time(...)
Get the duration of a given entry in the playlist.
 
get_playlist_time(index, session=0) -> duration in ms (integer)
 
index   -- index (starting at 0) of the playlist entry
session -- the XMMS session to contact
get_playlist_title(...)
Get the title of a given entry in the playlist.
 
get_playlist_title(index, session=0) -> title (string)
 
index   -- index (starting at 0) of the playlist entry
session -- the XMMS session to contact
get_skin(...)
Get the current skin file.
 
get_skin(session=0) -> absolute file name for the skin (string)
 
session -- the XMMS session to contact
get_version(...)
Get version (of what?).
 
get_version(session=0) -> version of what? (integer)
 
The code fragment that answers to this request in XMMS 1.2.6 is:
 
  case CMD_GET_VERSION:
          ctrl_write_gint(pkt->fd, 0x09a3);
          ...
 
I suspect it is the version of the protocol in use through the
XMMS control socket (which is how libxmms talks to XMMS, by the
way).
 
If you understand this better than I, please let me know.
get_volume(...)
Get left and right volumes.
 
get_volume(session=0) -> (left volume, right volume)
 
The volumes are integers.
 
session -- the XMMS session to contact
is_eq_win(...)
Tell whether the equalizer window is visible.
 
is_eq_win(session=0) -> boolean (0 = false, 1 = true)
 
session -- the XMMS session to contact
is_main_win(...)
Tell whether the main window is visible.
 
is_main_win(session=0) -> boolean (0 = false, 1 = true)
 
session -- the XMMS session to contact
is_paused(...)
Tell whether XMMS is paused.
 
is_paused(session=0) -> boolean (0 = false, 1 = true)
 
session -- the XMMS session to contact
is_pl_win(...)
Tell whether the playlist window is visible.
 
is_pl_win(session=0) -> boolean (0 = false, 1 = true)
 
session -- the XMMS session to contact
is_playing(...)
Tell whether XMMS is playing (= not stopped).
 
is_playing(session=0) -> boolean (0 = false, 1 = true)
 
When in pause, XMMS is considered to be playing for this
function.
 
session -- the XMMS session to contact
is_repeat(...)
Tell whether repeat mode is active.
 
is_repeat(session=0) -> boolean (0 = false, 1 = true)
 
session -- the XMMS session to contact
is_running(...)
Tell whether the specified XMMS session is running.
 
is_running(session=0) -> boolean (0 = false, 1 = true)
 
session -- the XMMS session to contact
is_shuffle(...)
Tell whether shuffle mode is active.
 
is_shuffle(session=0) -> boolean (0 = false, 1 = true)
 
session -- the XMMS session to contact
jump_to_time(...)
Jump to a given time since the beginning of the current playlist entry.
 
jump_to_time(time, session=0) -> None
 
time    -- time to jump to, in ms (integer)
session -- the XMMS session to act on
main_win_toggle(...)
Hide or show the main window.
 
main_win_toggle(display, session=0) -> None
 
This is not a real toggle function: you have to specify the
`display' argument.
 
display -- 1 to display the window, 0 to hide it
session -- the XMMS session to act on
pause(...)
Pause.
 
pause(session=0) -> None
 
session -- the XMMS session to act on
pl_win_toggle(...)
Hide or show the playlist window.
 
pl_win_toggle(display, session=0) -> None
 
This is not a real toggle function: you have to specify the
`display' argument.
 
display -- 1 to display the window, 0 to hide it
session -- the XMMS session to act on
play(...)
Play the current playlist entry.
 
play(session=0) -> None
 
session -- the XMMS session to act on
play_files(...)
Set the playlist and play.
 
Warning: this function is deprecated in libxmms.
 
play_files(seq, session=0) -> None
 
Clear the playlist, add the specified files/URLs to it and start
playing.
 
seq     -- a sequence of files/URLs
session -- the XMMS session to act on
play_pause(...)
Play or pause (toggle).
 
play_pause(session=0) -> None
 
session -- the XMMS session to act on
playlist(...)
Set the playlist contents or enqueue files/URLs in it.
 
playlist(seq, enqueue, session=0) -> None
 
seq     -- a sequence of files/URLs
enqueue -- boolean (0 = false, 1 = true); false does not work in
           xmms 1.2.6.
session -- the XMMS session to act on
playlist_add(...)
Add files/URLs to the playlist.
 
playlist_add(seq, session=0) -> None
 
seq     -- a sequence of files/URLs
session -- the XMMS session to act on
playlist_add_allow_relative(seq, session=0)
Add files/URLs to the playlist, allowing relative file names.
 
seq     -- a sequence of files/URLs
session -- the XMMS session to act on
 
Return None.
playlist_add_url_string(...)
Append a file/URL to the playlist.
 
playlist_add_url_string(string, session=0) -> None
 
string  -- an absolute file name or a URL
session -- the XMMS session to act on
playlist_clear(...)
Clear the playlist.
 
playlist_clear(session=0) -> None
 
session -- the XMMS session to act on
playlist_delete(...)
Delete one element of the playlist.
 
playlist_delete(index, session=0) -> None
 
index   -- the index (starting at 0) of the playlist entry to
           delete
session -- the XMMS session to act on
playlist_ins_url_string(...)
Insert a file/URL at a given position in the playlist.
 
playlist_ins_url_string(string, pos, session=0) -> None
 
string  -- an absolute file name or a URL
pos     -- index (starting at 0) of the playlist entry before
           which the entry for `string' will be inserted
session -- the XMMS session to act on
playlist_next(...)
Jump to the next entry in the playlist.
 
playlist_next(session=0) -> None
 
session -- the XMMS session to act on
playlist_prev(...)
Jump to the previous entry in the playlist.
 
playlist_prev(session=0) -> None
 
session -- the XMMS session to act on
quit(...)
Quit the specified XMMS session.
 
quit(session=0) -> None
 
session -- the XMMS session to act on
set_balance(...)
Set the balance.
 
set_balance(balance, session=0) -> None
 
balance -- balance value (integer)
session -- the XMMS session to act on
set_eq(...)
Set all equalizer settings (preamp and all bands).
 
set_eq(preamp, seq, session=0) -> None
 
preamp  -- gain in dB (float)
seq     -- a sequence of 10 floats, which are the gains in dB of
           for the 10 frequency bands predefined in XMMS
           (first = lowest frequency, last = highest frequency)
session -- the XMMS session to act on
set_eq_band(...)
Set the equalizer setting for a given band.
 
set_eq_band(band, gain, session=0) -> None
 
band    -- number of the band (integer between 0 and 9, both
           inclusive, specifying the equalizer band from which
           the setting is to be set; 0 is for the lowest
           frequency and 9 for the highest one).
gain    -- value of the gain to set (float)
session -- the XMMS session to act on
set_eq_preamp(...)
Set the equalizer preamp value.
 
set_eq_preamp(preamp, session=0) -> None
 
preamp  -- gain in dB (float)
session -- the XMMS session to act on
set_main_volume(...)
Set the "main" volume.
 
set_main_volume(volume, session=0) -> None
 
The left and right volumes are calculated (and set) from the
supplied `volume' argument and the current balance.
 
volume  -- "main" volume (integer)
session -- the XMMS session to act on
set_playlist_pos(...)
Set the current playlist position.
 
set_playlist_pos(position, session=0) -> None
 
pos     -- the target playlist index (counting from 0)
session -- the XMMS session to act on
set_skin(...)
Set the skin from a specified file.
 
set_skin(skin_file, session=0) -> None
 
skin_file -- the target skin file
session   -- the XMMS session to act on
set_volume(...)
Set left and right volumes.
 
set_volume(left_volume, right_volume, session=0) -> None
 
left_volume  -- left volume (integer)
right_volume -- right volume (integer)
session      -- the XMMS session to act on
show_about_box(...)
Show about box.
 
show_about_box(session=0) -> None
 
Does not to work in XMMS 1.2.6.
 
session -- the XMMS session to act on
show_prefs_box(...)
Show the preferences dialog box.
 
show_prefs_box(session=0) -> None
 
session -- the XMMS session to act on
stop(...)
Stop.
 
stop(session=0) -> None
 
session -- the XMMS session to act on
toggle_aot(...)
Set the always-on-top flag for the main window.
 
toggle_aot(always, session=0) -> None
 
The implementation of this function in XMMS 1.2.6 is weird,
I cannot tell you more about `always' than "it seems not
to be used".
 
always  -- should be a boolean (0 or 1)
session -- the XMMS session to act on
toggle_repeat(...)
Toggle repeat mode.
 
toggle_repeat(session=0) -> None
 
session -- the XMMS session to act on
toggle_shuffle(...)
Toggle shuffle mode.
 
toggle_shuffle(session=0) -> None
 
session -- the XMMS session to act on