XMMS-Control
Manual

Table of Contents:
  • Legal Stuff
  • About XMMS-Control
  • Installation
  • API/Hooks
  • TODO
  • Questions/Comments
  • Thanks!

    • Legal Stuff

    XMMS-Control Copyright (C) 2001, 2002 by Joe Thielen
    XMMS-Control comes with NO WARRANTY, to the extent permitted by law.
    This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published be the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
    http://www.gnu.org

    SUPPORT THE GNU AND FSF!!!

    About XMMS-Control

    XMMS-Control is a web-based interface to XMMS, using the XMMS-Shell command-line utility. It's written in PHP, and uses classes. Imagine being able to encode your entire CD collection into MP3 format, then having access to ALL of them, without having to flip CDs! You can hook your XMMS-Control server into all the stereo's in your home/garage/pool, and control them from any PC in your home! Also, if you have a wireless PDA (such as a PocketPC), you can control the playback from ANYWHERE you get wireless service!!! XMMS-Control is written and maintained by Joe Thielen and it's homepage can be found at: www.joethielen.com/xmms-control.

    List of features

  • Web-Based Interface - Use any browser to control, just uses HTML & tables!!!
  • Mobile/PDA Format - Looks better on smaller devices (like wireless PocketPCs and Palms)
  • Playlist management - Maintain your playlists via one interface!
  • Customizable - Without too much trouble, you can modify the title and colors of the page. If you're familiar with PHP & HTML, then you can modify the entire way the software looks! Also, themes will be along sometime...
  • API/Hooks - You can control XMMS-Control remotely from other software/servers!!! See the API section for more info!

    • Installation

    Requirements for XMMS-Control:
  • System running XMMS (Linux/Unix, etc...)
  • XMMS-Shell (http://xmms-shell.sourceforge.net)
  • Apache (or other webservier)
  • PHP (V4 or above is preferable).
    • Installation Steps:
    1. Install the XMMS-Control distribution package into a directory under the webserver (i.e. /home/httpd/html/xmms-control, or /var/www/html/xmms-control for newer Linux distro users)
    2. IMPORTANT: Make sure that XMMS-Shell is executable by the webserver... you can do this by issuing the following command: 'chmod a+s xmms-shell' (NOTE: This must be executed in the same directory as xmms-shell!!!).
    3. IMPORTANT: If you run XMMS as a different user than root, you will need to create a symbolic link from /tmp/xmms_XXXX.0 (where XXXX is the name of the user that XMMS is running under) to /tmp/xmms_root.0. You can do this by issuing the following command:
      ln -s /tmp/xmms_XXXX.0 /tmp/xmms_root.0
      This is due to the fact that XMMS-Shell only recognizes XMMS when it's running as root.
    4. Make sure your playlists and MP3 files are in directories that are accessable to the webserver. I would recommend creating a main directory (such as '/mp3') and placing all of your playlists into this directory. Then place your MP3s into sub-directories located under this directory. Since XMMS-Control needs to be able to read AND write to these playlists, the main directory AND all of the playlist files need to be modifiable by XMMS-Control. To do this, you should issue a command like this: 'chmod 777 /mp3', where /mp3 is the name of your MP3 playlist directory. In addition, the playlists need to be modifiable, so issue the following command: 'chmod 666 /mp3/*.m3u'.
    5. Modify the configuration variables in the vars.inc file in your XMMS-Control directory (typically):
    6. $version -- Don't touch this.
    7. $title -- This is the title that will display at the top of your XMMS-Control interface web page. You can make this say whatever you want!
    8. $xs_path -- This is where the XMMS-Shell program is located.
    9. $pl_path -- This is the playlist path. This is where all of your MP3 playlists are located (if you have any existing onces).
    10. $mp_path -- This is where your MP3s are located. This is usually the same as $pl_path, but may be different.
    11. Point your web browser to the server where XMMS-Control is located, and see if it works!!! Something like this: 'http://myserver/xmms-control'. Troubleshooting:
    12. If you do not see the XMMS-Control web page, then you've not installed the package correctly.
    13. If you do see the XMMS-Control web page, but there are no MP3s or playlists listed, then you either have the $pl_path and/or $mp_path variables in the vars.inc file set incorrectly, or you may not have any playlists and/or MP3 files. Please check the variables, and make sure the permissions are set correctly!!!
    14. If it still does not work, then you may not have XMMS-Shell installed correctly, or may not have the $xs_path variable set correctly in the vars.inc file. Also, make sure the XMMS-Shell program is executable by the web server. Try 'chmod a+s xmms-shell'.

    API/Hooks

    Let's say you're using XMMS-Control. But let's also say that you're developing a whole-house automation system, and the music software is just one small piece. You want to develop ONE consistent interface for your home with the basic functions, and you want it to be totally customized.

    Can XMMS-Control play nice???

    YES. You can control XMMS-Control, and not even use the XMMS-Control interface if you so wish. This is accomplished via a simple web script, in which you control how it works. The way it works is simple. Simply create links in your software to the http://myserver/xmms-control/hooks.php script, and pass it arguments! It will automatically forward you to a URL that you specify. If you so wish, you can even make XMMS-Control invisible... meaning those using your interface will never know that controlling music is done through another piece of software!

    Arguments to hooks.php:

  • backurl
  • This is the url you wish to return to. Substitute the tilde character (~) for the question mark (?), and the open-quote (`) for the ampersand (&). Hence, if you wish to return to the URL http://myserver/main.php?mode=1&id=2, you should code it like this: backurl=http://myserver/main.php~mode=1`id=2.
  • backurlpause
  • This is the amount of time (in seconds) to pause before redirecting back to backurl (0 is the default).
  • comm
  • The command/function to perform:
  • play
  • stop
  • pause
  • forward (aka 'next')
  • backward (aka 'prev' or 'previous')
  • clear
  • shuffle_on
  • shuffle_off
  • repeat_on
  • repeat_off
  • volume (comm2=volume level)
  • jump (comm2=song number)
  • loadplaylist (comm2=playlist filename)
  • comm2
  • The function modifier. For instance, if comm is 'volume', then comm2 should indicate the volume to set to (0-100).
  • splash
  • This will cause hooks.php to display a short splash screen with a message such as 'Command 'prev' executed'. This will only be displayed for as long as you have the backurl pause set to. This is disabled by default.

    • Examples:

  • Stop music playback, no splash screen, and return to 'http://myserver' immediately:
  • http://myserver/xmms-control/hooks.php?comm=stop&backurl=http://myserver
  • Move to the next song, display a splash screen for 5 seconds, then return to 'http://myserver/main.php?mode=1&id=2':
  • http://myserver/xmms-control/hooks.php?comm=forward&splash=X&backurl=http://myserver/main.php~mode=1`id=2&backurlpause=5
  • Set the volume to 50%, with no splash screen, and return to 'http://myserver' immediately:
  • http://myserver/xmms-control/hooks.php?comm=volume&comm2=50&backurl=http://myserver

    • TODO

  • API/Hooks - Security... username & password
  • Themes/Skins
  • HOWTO: Configuring a stand-alone networked XMMS-Control MP3 Server w/FTP & SMB file access..
  • CD to MP3 creation automation/interface (using Bladeenc, etc...)

    • Questions/Comments

    Please FEEL FREE to send me comments and/or questions about XMMS-Control!

    The web site for XMMS-Control is: http://www.joethielen.com/xmms-control.
    You can contact me by e-mail at: joe@joethielen.com.

    Thanks

    My thanks go out to:
  • The entire Linux community!
  • The people behind the Apache Web Server, PHP, and XMMS!
  • The GNU and FSF!
  • Do I really have to explain what these people have done???
  • Logan Hanks - www.loganh.com
  • For creating XMMS-Shell, upon which XMMS-Control communicates with XMMS
  • Monte Freeman <montef@bellsouth.net>
  • For spending a day sending feedback e-mail back and forth :). Helped get XMMS-Control working with XMMS-Shell 0.99, and inspired some other fixes...
  • Steve H.
  • For spending a few hours e-mailing feedback making XMMS-Control better suited towards more distros.

    • XMMS-Control Manual V1.1 by Joe Thielen
    Created: 10/14/2001
    Last Modified: 04/17/2002