PyXMMS-remote
*************

This manual documents PyXMMS-remote (version VERSION, UPDATED), a command-line interface to XMMS.

Introduction
************

PyXMMS-remote is a Python (http://www.python.org/) program using PyXMMS to control an XMMS session. PyXMMS-remote is free software. PyXMMS-remote is licensed under the GNU GPL version 2.

Notes:

  * XMMS (the X MultiMedia System) is a multimedia player written for the X Window System. XMMS provides a library (libxmms) that contains functions providing full control over an XMMS session from an external program. The official XMMS home page is located at http://www.xmms.org/.

  * PyXMMS is a set of Python bindings for libxmms, including higher-level interfaces than that provided by libxmms.

With PyXMMS-remote, you can tell or retrieve quite a lot of things to/from an XMMS session with shell commands (or shell scripts or whatever you want, but if what you want to do is really complex, you'd better use PyXMMS directly).

The following command tells the XMMS session 0 (default) to start playing the current playlist entry:

     pyxmms-remote play

The following command tells the XMMS session number 2 to stop playing:

     pyxmms-remote -s 2 stop

Here is a way to:

  * start XMMS if necessary

  * add some entries (files or URLs) to the playlist

  * start playing from the first entry added

     pyxmms-remote E entry...

equivalent to the not-so-short following command:

     pyxmms-remote enqueue_and_play_launch_if_session_not_started entry...

How to use this program
***********************

The general form of a valid invocation of PyXMMS-remote is:

     pyxmms-remote [OPTION]... COMMAND [COMMAND_ARGUMENT]...

where the valid options are:

-s SESSION
--session=SESSION
     The XMMS session to control. If you simply launched one instance of XMMS, it should be your session 0 (each Unix user has its own session numbering scheme). This setting defaults to 0.

-p PROGRAM
--program=PROGRAM
     The executable to invoke with the command enqueue_and_play_launch_if_session_not_started (or E) if the selected XMMS session (as defined by the -s option) is not already running. The default is xmms. The PATH variable is searched if necessary.

--poll-delay=DELAY
     When PyXMMS-remote is called with the enqueue_and_play_launch_if_session_not_started (or E) command, it will spawn an XMMS process if the requested session (The one specified with the --session option.) is not already running. Then, it will tell the requested session to add the specified files to the playlist and start playing, but that cannot be done before the session is ready to handle requests. Therefore, PyXMMS-remote will try to contact this XMMS session at regular intervals of DELAY seconds and give up if the session didn't answer after TIMEOUT seconds, as specified with the --timeout option.

     DELAY must be a non-negative floating-point number.

--timeout=TIMEOUT
     Timeout in seconds when checking whether an XMMS session started by the enqueue_and_play_launch_if_session_not_started (or E) command is ready to handle requests (see --poll-delay).

     TIMEOUT must be a non-negative floating-point number.

-f DECIMALS
--floats-precision=DECIMALS
     The number of decimals displayed for floats by commands such as get_eq. The default is 2.

--help
     Display usage information and exit.

Command reference
*****************

Commands from libxmms
=====================

subsubsection without subsection
................................

The following commands are direct bindings to the xmms_remote_* functions of libxmms.

playlist FILE_OR_URL... ENQUEUE
     Set the playlist contents or enqueue files/URLs in it.

     ENQUEUE should be a boolean (0 = false, 1 = true). If false, the playlist is set and XMMS starts playing from the first entry; if true, the files or URLs are simply added to the playlist and the playing/not playing status is left unchanged.

playlist_add FILE_OR_URL...
     Add files/URLs to the playlist.

playlist_delete ENTRY_NUMBER
     Delete the playlist entry number ENTRY_NUMBER (starting at 0).

playlist_clear
     Clear the playlist.

playlist_add_url_string STRING
add_url_to_playlist STRING
     Add STRING (file or URL) to the playlist.

playlist_ins_url_string STRING POS
insert_url_into_playlist_at_pos STRING POS
     Insert STRING (file or URL) at position POS (index starting at 0) in the playlist.

get_playlist_length
     Get the playlist length (number of files/URLs).

get_playlist_pos
     Get the current playlist position (index starting at 0).

set_playlist_pos POS
     Set the current playlist position to POS (index starting at 0).

get_playlist_file ENTRY
     Get the absolute file name corresponding to the entry ENTRY (index starting at 0) in the playlist.

get_playlist_title ENTRY
     Get the title of the entry ENTRY (index starting at 0) in the playlist.

get_playlist_time ENTRY
     Get the duration in milliseconds of a the entry ENTRY in the playlist.

play
     Play the current playlist entry.

pause
     Pause.

play_pause
     Play or pause (toggle).

stop
     Stop.

eject
     Show the eject dialog box.

playlist_prev
     Jump to the previous entry in the playlist.

playlist_next
     Jump to the next entry in the playlist.

jump_to_time MILLISECONDS
     Jump to the given time since the beginning of the current playlist entry.

     Note: at least in XMMS 1.2.7, the resolution seems to be 1 second although the time to jump to is given in milliseconds.

is_running
     Tell whether the selected XMMS session is running (0 means ``no'', 1 means ``yes'').

is_playing
     Tell whether the selected XMMS session is playing (0 means ``no'', 1 means ``yes''). When in pause, XMMS is considered to be playing for this command.

is_paused
     Tell whether the selected XMMS session is paused (0 means ``no'', 1 means ``yes'').

get_output_time
     Get the time in milliseconds since the beginning of the current playlist entry.

get_info
     Get information about the current playlist entry, namely its rate (in bps), its frequency (in Hz) and its number of channels (1 = mono, 2 = stereo...).

get_volume
     Get left and right volumes.

set_volume LEFT_VOLUME RIGHT_VOLUME
     Set left and right volumes.

get_main_volume
     Get the greater of left and right volumes.

set_main_volume VOLUME
     Set the ``main'' volume. The left and right volumes are calculated (and set) from the supplied VOLUME argument and the current balance.

get_balance
     Get the balance value.

set_balance VALUE
     Set the balance according to VALUE (-100 means ``100 % left'', 0 means ``centered'', 100 means ``100 % right'').

get_eq
     Get the equalizer settings (preamp and gain in dB for the ten frequency bands defined in XMMS).

set_eq PREAMP BAND0 BAND1... BAND9
     Set the equalizer settings (preamp and gain in dB for the ten frequency bands defined in XMMS). BAND0 corresponds to the lowest frequency and BAND9 to the highest frequency.

get_eq_preamp
     Get the equalizer preamp value in dB.

set_eq_preamp GAIN
     Set the equalizer preamp value to GAIN (in dB).

get_eq_band BAND_NUMBER
     Get the gain (in dB) for band BAND_NUMBER (between 0 and 9, both inclusive).

set_eq_band BAND_NUMBER GAIN
     Set the gain for band BAND_NUMBER (between 0 and 9, both inclusive) to GAIN (in dB).

get_skin
     Get the current skin absolute file name.

set_skin ABSOLUTE_FILE_NAME
     Set the skin from ABSOLUTE_FILE_NAME.

main_win_toggle DISPLAY
main_win_set_visible DISPLAY
     Hide (if DISPLAY is 0) or show (if DISPLAY is 1) the main window (yes, this is not a real toggle function).

pl_win_toggle DISPLAY
playlist_win_set_visible DISPLAY
     Hide (if DISPLAY is 0) or show (if DISPLAY is 1) the playlist window (yes, this is not a real toggle function).

eq_win_toggle DISPLAY
equalizer_win_set_visible DISPLAY
     Hide (if DISPLAY is 0) or show (if DISPLAY is 1) the equalizer window (yes, this is not a real toggle function).

is_main_win
     Tell whether the main window is visible (0 means ``no'', 1 means ``yes'').

is_pl_win
     Tell whether the playlist window is visible (0 means ``no'', 1 means ``yes'').

is_eq_win
     Tell whether the equalizer window is visible (0 means ``no'', 1 means ``yes'').

show_prefs_box
     Show the preferences dialog box.

show_about_box
     Show about box. Does not to work in XMMS 1.2.6 and 1.2.8 (at least).

toggle_aot ALWAYS
set_always_on_top_state ALWAYS
     Set the always-on-top flag for the main window. ALWAYS should be a boolean (0 or 1), but the implementation of this function in XMMS 1.2.6 looks weird to me, so I cannot tell you more about ALWAYS than ``it seems not to be used''. This function still does not seem to work in XMMS 1.2.8.

toggle_repeat
     Toggle repeat mode.

toggle_shuffle
     Toggle shuffle mode.

is_repeat
     Tell whether repeat mode is active (0 means ``no'', 1 means ``yes'').

is_shuffle
     Tell whether shuffle mode is active (0 means ``no'', 1 means ``yes'').

get_version
     Get version (of what?).

     The code fragment that answers 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.

quit
     Quit the selected XMMS session.

play_files FILE_OR_URL... (deprecated in libxmms)
     Clear the playlist, add the specified files/URLs to it and start playing. This function is deprecated. Use a combination of playlist and play instead.

Commands specific to PyXMMS
===========================

The following commands are bindings to functions of PyXMMS which are not defined in libxmms---but very likely to be implemented with functions of libxmms.

a FILE_OR_URL...
playlist_add_allow_relative FILE_OR_URL...
     Add files/URLs to the playlist, allowing relative file names.

e FILE_OR_URL...
enqueue_and_play FILE_OR_URL...
     Add files/URLs to the playlist and start playing from the first one (that is, the first FILE_OR_URL argument specified).

E FILE_OR_URL...
enqueue_and_play_launch_if_session_not_started FILE_OR_URL...
     Add files/URLs to the playlist and start playing from the first one (that is, the first FILE_OR_URL argument specified). This command is identical to enqueue_and_play except that it spawns an XMMS process if the selected session is not running.

fade_out [ACTION [NB_STEPS [STEP_DURATION [RESTORE_VOLUME]]]]
     Progressively decrease the main volume, then stop or pause (depending on ACTION), then optionally restore the original main volume setting.

     action
          Whether to stop or pause the playback after the fade out. Valid values are stop and pause. Default is stop.

     nb_steps
          Number of decrease-volume steps to use (default is 20)

     step_duration
          Duration of a step (floating point number, in seconds; default is 0.5)

     restore_volume
          Whether to restore the main volume after the fade out. Valid values are 1 to have the volume restored and 0 to have it remain at 0. Default is 1.

Environment variables
*********************

There is currently one environment variable specific to PyXMMS-remote: PYXMMS_REMOTE_XMMS_PRG. This sets the XMMS executable name (absolute or relative) just as the -p option.

Note: command-line options take precedence over environment variables.

Setup tips
**********

Midnight commander
==================

You can use a rule like:

     regex/\.([mM][pP]3|[oO][gG][gG]|[mM]3[uU])$
             Open=pyxmms-remote E %s
             View=pyxmms-remote E %s
     	Icon=sound.xpm

in your ~/.mc/bindings (personal) or /etc/mc/mc.ext (system-wide, and might be located elsewhere in your system---this is the Debian (http://www.debian.org/) location).

This way, you will enqueue and play (as well as launch XMMS before if necessary) the selected file(s) when you press Enter or F3.

MIME support
============

You can associate a PyXMMS-remote invocation with the MIME types ``application/ogg'' (cf. RFC 3534), ``application/x-ogg'' (used when ``application/ogg'' was not yet registered as an official MIME type), ``audio/mpeg'' and ``audio/x-mpegurl''. On a Debian (http://www.debian.org/) system (with the mime-support package), this can be done with the following lines in your ~/.mailcap or the system-wide /etc/mailcap (if for some reason you did not install the Debian package for PyXMMS-remote):

     application/ogg; pyxmms-remote E "%s"; test=test -n "$DISPLAY"
     application/x-ogg; pyxmms-remote E "%s"; test=test -n "$DISPLAY"
     audio/mpeg; pyxmms-remote E "%s"; test=test -n "$DISPLAY"
     audio/x-mpegurl; pyxmms-remote E "%s"; test=test -n "$DISPLAY"

first appendix
**************

first section of appendix
=========================

saaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e ersaaaa dg dfg dfg ert ertr e er

sdkfpksd opsdif poisdpofisopd ifposid fpoisdpof iposdif sdf ksopdkf posdkfop ksdopfk psdokfopsdfsd f sdfko sdokf sdkof kosdkf opsdkf oskdf oksdofo sdkfoüsdkf oüsdkf ksdfk opsdkfoksdpfok sdpokf opsdkfoksdopfk sodkfop sdfoksdof ksdopkf opsdkf pojsdojpf osjdf jsodkfj jsdlf jsdlkjf sdjlkf lsdkjf sdjkfjsdjkf j skdjflsdjf lksdjf ljsdlkfj lskdjflk sdjflkjskd. fjklsdjf lksdjf lkjsdkf j skdjflsdjf lksdjf ljsdlkfj lskdjflk sdjflkjskd. fjklsdjf lksdjf lkjsdkf jk sdjflsd jflksdj flksjdflkj sdlkfjsdlkfj lksdjf lksdjflk sjdflkjsdjlkf j sojf lksdjflkjsd fllksdjf lsdkjf sldkjfl ksdjf lksdjflkjsd lkfjsdlkfjlks jksd jflsdjf lksdjflksdjflkjsd lfkjsdkfj lksdjf slkdjf sdlkjf sdkjf j oksjdflksdjfljsdlkjf sdlkjf klsdjfj sdljkf lksdjf klsdjfljksdfj sdlkjf sdkjf j skdjflsdjf lksdjf ljsdlkfj lskdjflk sdjflkjskd. fjklsdjf lksdjf lkjsdkf jk sdjflsd jflksdj flksjdflkj sdlkfjsdlkfj lksdjf lksdjflk sjdflkjsdjlkf j sojf lksdjflkjsd fllksdjf lsdkjf sldkjfl ksdjf lksdjflkjsd lkfjsdlkfjlks jksd jflsdjf lksdjflksdjflkjsd lfkjsdkfj lksdjf slkdjf sdlkjf sdkjf j oksjdflksdjfljsdlkjf sdlkjf klsdjfj sdljkf lksdjf klsdjfljksdfj sdlkjf sdkjf j skdjflsdjf lksdjf ljsdlkfj lskdjflk sdjflkjskd. fjklsdjf lksdjf lkjsdkf jk sdjflsd jflksdj flksjdflkj sdlkfjsdlkfj lksdjf lksdjflk sjdflkjsdjlkf j sojf lksdjflkjsd fllksdjf lsdkjf sldkjfl ksdjf lksdjflkjsd lkfjsdlkfjlks jksd jflsdjf lksdjflksdjflkjsd lfkjsdkfj lksdjf slkdjf sdlkjf sdkjf j oksjdflksdjfljsdlkjf sdlkjf klsdjfj sdljkf lksdjf klsdjfljksdfj sdlkjf sdkjf jk sdjflsd jflksdj flksjdflkj sdlkfjsdlkfj lksdjf lksdjflk sjdflkjsdjlkf j sojf lksdjflkjsd fllksdjf lsdkjf sldkjfl ksdjf lksdjflkjsd lkfjsdlkfjlks jksd jflsdjf lksdjflksdjflkjsd lfkjsdkfj lksdjf slkdjf sdlkjf sdkjf j oksjdflksdjfljsdlkjf sdlkjf klsdjfj sdljkf lksdjf klsdjfljksdfj sdlkjf sdkjf j sojdfjsdlkjfl ksdjf klsdjf klsjdlkfj sdlkfjsd ljkfjsdflj lslfdjl sjf

subsection
----------

puooo

second section of appendix
==========================

Zoooo

third section of appendix
=========================

Voilà, quoi...