##################################################

		    RMP
	(R)emote (M)usic (P)layer

By Kirk Waingrow - (05/2011)
Version 3.2
##################################################

1. What is rmp?
2. Features
3. Files And Directories
4. Installation
   a. Dependancies
   b. Install Process
   c. Configure rmp.cfg
   d. Playlist Syntax
   e. Basic Testing
   f. Configure for rmpweb
   g. Configure for file downloads
5. Instructions for rmpweb
6. Instructions for rmp
7. Instructions for Time
8. Instructions for Promos
9. F.A.Q. 
   a. How does it all work
   b. How do I stop rmp?
   c. I just updated my playlist when will rmp see it 
   d. Something stopped working, what do I do?
   e. When can/can't I use spaces.
   f. Why does the volume partially work or not work
10. New Features Developed
11. KNOWN BUGS

---------------------------------------------------------

1. WHAT IS RMP?

RMP is a Remote Music Player that allows remote control over
music playing on a local Linux computer. The music can be   
controlled remotely with a web interface, cellphone  or 
through a command line shell interface. 



2. FEATURES

 * Supports m3u playlists.
 * Display playlists, Artists, Title, Genre of playing song.
 * Download remote music to a cellphone or local computer.
 * Speak the current time 
 * Play Promo, Commercial, or short audio clips 
 * Control volume remotely
 * Search/play specific tunes throughout all the playlists
 * Select next song anytime (without commercials -lol)
 * multiple ways to control (web / command line)
 * Easy to set up



3. FILES AND DIRECTORIES

Manditory Files:
 * rmpd - Main daemon that controls the music to play
 * rmp.ctrld - Daemon that interfaces web, command line, and rmpd
 * rmp.cfg - rmp configuration settings
 * rmp - Command line interface to rmp.ctrl and rmpd
 * rmpweb - Web interface to rmp.ctrl and rmpd
 * playlists - directory containing all the playlists

Optional:
 * runrmp - Starts rmpd and rmp.ctrld in backgroud.
 * killrmp - quickly stops everything related to rmp
 * depsrmp - autoinstall dependant packages needed to run rmp



4. INSTALLATION
rmp has only been tested on UBUNTU so far, but should work on other
flavors of Linux with minimul changes.

4a. DEPENDANCIES

The following need to be installed:

alsa - ALSA (Advanced Linux Sound Architecture) 
  http://www.alsa-project.org/main/index.php/Main_Page
     # apt-get install alsa

mplayer - Music Player. Others like mpg123 should work no problem.
     # apt-get install mplayer

Test under perl 5.10.x

The following CPAN Modules are needed:
     # perl -MCPAN -e 'install File::Copy'
     # perl -MCPAN -e 'install MP3::Tag'
     # perl -MCPAN -e 'install Proc::Killall'
     # perl -MCPAN -e 'install File::Basename'



4b. INSTALL PROCESS

  1) Create a directory for rmp to live in
     # mkdir /usr/local/rmp

  2) Extract rmp anywhere
     # untar rmp.tar.gz

  3) Go into the extract rmp directory:
     # cd rmp-v###         (whe v### is the version number)

  4) copy all the contents to /usr/local/rmp
     # cp * /usr/local/rmp

  5) Create a playlist directory:  
     # mkdir /usr/local/rmp/playlists
 
  6) Verify perl is pointing to the the path of perl at the 
     top of the following files:
     rmp
     rmpd
     rmp.ctrld
     rmpweb

  7) Verify that the "require" line points to the rmp.cfg file in
     the following files:
     rmp
     rmpd
     rmp.ctrld
     rmpweb
      
  8) Edit the rmp.cfg file appropriately to match your settings:
     (SEE BELOW FOR COMPLETE DESCRIPTION OF ALL VARIABLES IN rmp.cfg)

  9) Add crontab entry for rmp.watchdog
	*/1 * * * * /usr/local/rmp/rmp.watchdog >  /dev/null 2>&1

 10) Allow apache to restart rmp with a sudo entry. Yes this can be
     dangerous, but rmp runs as root to control devices. This can be
     locked down to sudo specific commands, but this is the simplest mod.
	apacehe ALL=(ALL) NOPASSWD:ALL
    


4c. Configure rmp.cfg

  DEBUG Provides useful information if there is a problem running rmp.
  To activate $DEBUG should equal "1". 
  $DEBUG="";

  This is where all the temporary files are stored
  $TMP="/tmp";

  The location of everything that makes up rmp
  $RMPDIR="/usr/local/rmp";

  The location of all the playlists
  $PLAYDIR="$RMPDIR/playlists"; 

  The name of the default playlist that will always start at launch.
  The extension (m3u,dat,txt) can be anything or nothing.
  $DEFAULT_PLAYLIST="Default.txt";

  The music player to use and play the tunes.
  $MPLAYER="/usr/bin/mplayer"; 

  Any options that are needed by the music player.
  $MPLAYEROPTS="-really-quiet"; 

  Play this number of tunes until a Promo audio clip is played.
  Example: A Promo audio clip will not play until 5 tunes have been played.
  $PROMOTUNES="5";			

  When it is time to play a Promo audio clip, how many will be played
  If NO Promo audio clips are wanted, set $NUMPROMO="".
  Example: 1 Promo will be played. 
  $NUMPROMO="1";

  The location of the Promo's Playlist located. The Promo audio clip MUST
  be in "mp3" format. The syntax in the Promos.txt file is the same as a 
  normal playlest: [path]/[audio_clip].mp3
  $PROMO_PLAYLIST="Promos.txt";	

  If the file rmp_[playlist] doesn't exist, then copy the 
  playlist to this temp file and manipulate it instead of 
  the original file.
  $PLAYFILE="$TMP/rmp_";

  This file always contains the Artist, Title, Genre, Playlist 
  $RMPDAT="$TMP/rmp.dat";

  Commands from the web / command line are proccessed to/from this file
  $RMPCMD="$TMP/rmp.cmd";	

  The volume setting placed in this file
  $RMPVOL="$TMP/rmp.vol";

  The search results are placed in this file
  $RMPSCH="$TMP/rmp.sch";

  When reset needs to be performed this tmp file is set
  $RMPRST="$TMP/rmp.reset";

  When this file exists, it disables the Promo files from being played
  $RMPPRM="$TMP/rmp.promos";		# toggle playing promos

  When this file exists, it disables the Time from being spoken
  $RMPTIM="$TMP/rmp.time";		# toggle saying the time

  While rmp or rmpweb initiates playing a "Next File". This is used
  so the Time counter is not affected by jumping to the next song.
  $RMPKIL="$TMP/rmp.kil";

  The Title of the web page
  $PAGE_TITLE="Personal Music Player";     

  The CGI that drives the web interface
  $PROG="/cgi-bin/rmpweb";

  The directory will the css files live
  $CSSDIR="/var/www/css";

  The volume control is driven by "amixer" which is not supported on
  all machines. This setting turns off the controls so it isn't 
  displayed on the web interface.  Set to "1" to turn it on, leave it 
  blank to turn it off.
  $DISPVOL="1";	

  The time is spoken after the number tunes that have been played.
  Selecting "Next Song" in rmp or rmpweb will not count against a tune played.
  Example: The time will be spoken once 3 songs have played in their entirety
  $TIMETUNES="3";

  The number of times that the time will be spoken. To turn off the time
  being spoken, set $NUMTIME="".
  $NUMTIME="1";	

  The speech synthesizer that is being used
  $SPEAK="/usr/bin/espeak";
  $SPEAKOPTS="-a 300 -p 90 -s 120 -v en-us"; 



4d. Playlist Syntax

   The playlist is simply a list of mp3 files with their complete path. 
   /music/rock/Scorpions-Blackout.mp3

   Lines starting with "#". 
   
4e. Basic Testing

   1) Turn on DEBUG="1" in the rmp.cfg
   2) Start rmp.ctrld: 
	# ./rmp.ctrld

   There should be no errors and display every 2 seconds:
      rmp.ctrld: Watching rmpd...

   3) Break out with ctrl-C

   4) Start rmpd: 
	# ./rmpd
  
   The output should display the playlists information and 
   if all goes well, start playing a tune off the default list.  

	# ./rmpd
	rmpd: Starting Remote Music Player...
	rmpd: TOTAL # Playlist = 1
	rmpd: Default.txt
	rmpd: Promos.txt
	rmpd: Opening up /tmp/rmp.dat
	rmpd: Playlist: Default.txt
	rmpd: COPY /usr/local/rmp/playlists/Default.txt to /tmp/rmp_Default.txt
	rmpd: PLAYFILE/PLAYLIST = /tmp/rmp_Default.txt
	rmpd: LENGTH=4
	rmpd: Saying TIME: 1 of 1
	rmpd: PLAYLIST = /tmp/rmp_Default.txt
	rmpd: LENGTH=4
	rmpd: RANDOM=1
	rmpd: TUNE = /usr/local/rmp/audio/Kenny Wayne Shepherd-Blue On Black.mp3
	rmpd: LENGTH = 4
	rmpd: TUNENUM = 1
	rmpd: PLAYLIST = Default.txt
	rmpd: ARTIST = Kenny Wayne Shepherd
	rmpd: TITLE = Blue On Black (Album Version)
	rmpd: GENRE = Pop
	rmpd: TIME Count: 0 of 3
	rmpd: /usr/bin/mplayer -really-quiet /usr/local/rmp/audio/Kenny Wayne Shepherd-Blue On Black.mp3
	

   5) Break out with ctrl-C

   6) Fix any issues, If all runs smooth, then put rmpd and 
      rmp.ctrld in backgroud.
	# ./runrmp

4f. Configure for rmpweb. 

  NOTE: It is best to use either the rmp command line interface or the
        rmpweb. Some features may not work since the Web interface
        runs under a different account that what you execute the command
        lines with.

   *** The folowing assumes that the document root is /html ***
   
   1) Manually execut rmpweb:
   
   If rmpd and rmp.ctrld are not running you will see:
   # ./rmpweb

	Content-type: text/html


	<title>Relaxation Room Music Player</title>
    	<META HTTP-EQUIV="Refresh" CONTENT="3;URL=/cgi-bin/rmpweb">
    	<font size=4><u>Relaxation Room Music Player</u></font><p>

    	ERROR: RMP Daemons are not running.<p> 
    	Make sure that both are running:<br>
    	/usr/local/rmp/rmpd<br>
    	/usr/local/rmp/rmpd.ctrl<br>

  Start rmpd and rmp.ctrld and you should see clean html cold
  # ./rmpweb 

	Content-type: text/html


	<title>Relaxation Room Music Player</title>
    	<META HTTP-EQUIV="Refresh" CONTENT="3;URL=/cgi-bin/rmpweb">
    	<font size=4><u>Relaxation Room Music Player</u></font><p>
      	<font size=2> <a href="/cgi-bin/rmpweb?NXT=1">Next Song</a>
      	| <a href="/cgi-bin/rmpweb?SRCH=1">Search</a></font> <p>
    	<table cellspacing=0 cellpadding=0 border=0>
    	<tr align=left>
      	<td valign=top><font size=2>Playlist: <br>Artist: <br>Title: <br>Genre: </font></td> 
      	<td valign=top><font size=2>list<br>Goo Goo Dolls<br>Sympathy<br>Rock</font></td>
    	</table>
    	<font size=2>[<a href="/home/kwaingrow/music/Goo Goo Dolls - Sympathy.mp3"]>download</a>]</font>
    	<p>
      <font size=2>
	.
	.
	.


The following configuration has been validated on apache2 using the 
following configureations

   2) Modify /etc/apache2/sites-enabled/000-default
        ScriptAlias /cgi-bin/ /var/www/cgi-bin/
	<Directory "/var/www/cgi-bin">
		AllowOverride None
		Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
		Order allow,deny
		Allow from all
	</Directory>

   3) From /usr/local/rmp, copy webfiles into place
	# cp rmpweb /var/www/cgi-bin

	# mkdir /var/www/html/css
	# cp -pr css/* /var/www/html

	# mkdir /var/www/html/rmp
        # cp -pr html/* /var/www/html/rmp

   
   4) In apaches document root, create a html file that redirects 
      to the rmpweb CGI with these 2 lines of html code.
        # /var/www/html/rmp/index.html
        <TITLE>RMP</TITLE>
        <META HTTP-EQUIV="Refresh" CONTENT="0;URL=/cgi-bin/rmpweb">

Try it out! Hit it with a web browser


4g. Configure for file downloads

  To configure the file download you just need to add a symlink from
  the apache document root to match the exact path to the music path

  Here is an example if the document root is /var/www/html:
  - A playlist file MyTunes.m3u has the music files like:
	/music/list/The Fray - Save a Life.mp3

  - Symlink to music from the document root to the path of the music files.
        # ln -s /var/www/html/music/ /music



5. INSTRUCTIONS FOR rmpweb

The rmpweb has the following links:

* Next Song - Goto the next random song in the current playlist
* Search - Search all the playlist for a single song
* download - Download the current music file locally.
* Enable/Disable Promos from Playing
* Enable/Disable the Time from being spoken
* Volume - Set the volume from 1 - 10 or use + or - to increment the level
* Playlists - select a new playlist to play music from



6. INSTRUCTIONS FOR rmp

NOTE: It is best to use either the rmp command line interface or the
      rmpweb. Some features may not work since the Web interface
      runs under a different account that what you execute the command
      lines with.

To find all the available commands with rmp use the -h option:
./rmp -h

Syntax:  rmp [OPTION] [VALUE]
    -h		Display this Help
    -d [p|t]    Disable promos or saying time
    -e [p|t]    Enable promos or saying time
    -n		Next tune
    -p playlist	New Playlist 
    -s tune     Search tune pattern
    -t tune	Specific tune (with full path and "" if needed)
    -v [0..10]	Volume setting
  
Available Playlists are:
    
    list.m3u



7. INSTRUCTIONS FOR TIME

Why is this feature here?  This feature was added so when music is playing 
while you are working while listening to music, it is easy to lose track
of time. Sometimes when working you will not hear the time the
first time it is spoken, so $NUMTIME can be set to speak the time however
many consecutives needed. 

What is needed?  Time needs to utilize a speech synthesizer that needs to 
be installed. espeak has been tested, but rmp should work with others if 
installed. 

How is it set up?  Since songs vary in length, rmp is coded to speak the 
time based off of the number of songs played. Most songs are around 
4-5 minutes long so setting the $TIMETUNES to 3 songs will be close to 
every 15 minutes. Once the time is spoken, rmp will return to playing
music.

How to turn off hearing the time? The time is not be spoken if any of the
following conditions are met: $NUMTIME="" or The speech synthesizer program 
does not exit,

How do I hear the time twice after every 3 songs?
$TIMETUNES=4
$NUMTIME=2

How do I test the Time configs? when rmpd is launched the first thing it
does is say the time. Selecting "Next Song" will not work because
rmp is coded to ignore skipping of songs in this manner. In order to 
quickly test that TIMETUNES setting, from another shell simply kill
your music player (killall mplayer). rmpd will assume the song ended
and will play the next song. 



8. INSTRUCTIONS FOR PROMOS

Why is this feature here?  This feature was added to support commercials,
promo's, or just fun audio clips like famous movie quotes.

What is needed?  A file in the playlist directory called Promos.txt
that is defined in the rmp.cfg file.

How is it set up?  The Promos.txt file is set up like any other playlist
file. It contains a list [path]/[file].mp3 entries. That's it. A promo entry
will be selected at random from the Promos.txt file. Use the PROMOTUNES 
variable to set when a promo will be played after "x" number of tunes. 
NUMPROMO will set how many promo audio clips will be played when it is time
to play the promo audio clips. 

How do I hear 2 Promos after 5 tunes have played?
PROMOTUNES=5
NUMPROMO=2

How do I test the Promo configs? Just select "Next Song" in rmp or rmpweb.


9. F.A.Q.

9a. How does it all work?

* rmpd and rmp.ctrld run as root so they can control devices even after
you have logged out.

* rmp and rmpweb can run as any user. 

* Issuing a command through rmp or rmpweb writes out tht rmp.cmd
rmp.ctrl checks for rmp.cmd every 2 seconds. If there is a volume change
then rmp.ctrl adjusts the volume. If there is a playlist change or the
Next tune is requests, then rmp.ctrl kills the music player and 
the rmpd executes the change.

* rmpd write to rmp.dat and rmp.vol as root and sets the perm to 777
in the temporary directory.  Yeah, I know 777, but hey its only music 
lists. It doesn't modify any of the actual music files.

* rmp.watchdog watches to see if rmpd died. This happens if it hits a 
bad music file. It checks ever 5 seconds and ends after 55 seconds.
So the crontab restarts it at the top of each minute.


9b. How do I stop rmp?

rmp can be stopped by running /usr/local/rmp/killrmp as root or
clicking on reset in the web interface. It will kill rmpd, rmpctrld, 
and mplayer. However, if the rmp.watchdog is running in the cron it 
will start back up again.


9c. I just updated my playlist file in /usr/local/rmp/playlist, when will
rmp start using it.

rmp will start using the updated list when it has played all the songs in
the current playlist. If you can't wait, just delete the matching playlist 
file in the temporary directory (/tmp). When the current song ends or rmp 
is restarted, it will rebuild the index in /tmp from the updated playlist.


9d. Something stopped working, what do I do?

rmp can be reset by clicking on reset in the web interface. It will kill 
rmpd, rmpctrld, and mplayer and clean up the temporary files. To manually
clean things up, run /usr/rmp/killrmp and delete any file in the 
temporary directory that start with rmp_ (undescore) or rmp. (period)


9e. When can/can't I use spaces?

So far, rmp will break when the name of a playlist file has a space in it.
It is advisable to use "_" underscores. rmp will replace "_" with spaces
when it is displayed. Music file names within the playlist are allowed to
have spaces. There is nothing wrong with the actual music files having a 
space in their name. 


9f. Why does the volume work, not work, or only works between 7-10?

rmp makes use of the gnome alsa sound mixer. It seems that not all
sound cards are supported or act differently. More information can
be found at: http://www.alsa-project.org/main/index.php/Main_Page 



10. New Features Developed:

* Queuing will provide the ability to queue up a selection of songs 
so you can be the DJ and have more control. It will override the 
playlist, but once the queue is finished rmp will return to the 
current playlist.

* Ability to manipulate settings from rmp or rmpweb.

* If you would like to see more features let me know! wkrik@yahoo.com



11. KNOWN BUGS

* Any playlist file that has spaces in the filename

* If you find any bugs please let me know! wkrik@yahoo.com