##############################################################################
#                        #     Imp3web.php    #                        
#			 #        v0.1	      #	
#                        ######################
#
#                                                                            
#
#	This program is a php frontend to the imp3sh program that 
#  interacts with the i/o pipes that imp3sh uses.  Imp3web is meant do be 
#  a flexible LAN jukebox interface.  It does not stream mp3s/oggs, but allows
#  multiple users to request songs on a network jukebox to play locally.
#
#      Imp3web and imp3sh are under development, so everything might 
#  not work as advertised.  Im3web is released under the terms of the GPL 
#  v2.0.  I would also humbly  request that you send all modifications 
#  back to me at: spatula@linuxfreemail.com so that I can work them in to 
#  future releases of imp3web
#                                                                            
#
##############################################################################

====== CONTENTS ======
1. Introduction
2. Requirements 
3. Feature Rundown
4. Example Usage
5. Contact info


1. Introduction

The Imp3web.php script is meant to turn imp3sh into an easy to use Network 
JukeBox interface.  Here's the scenario I built imp3web.php for:
  I share an office with several people, we all like to listen to the same 
  music, but we hate lugging in cd's to work every day.  I use imp3sh as 
  an ogg server...but some of my officemates aren't very commandline 
  oriented.  Using imp3sh directly is not something they want to do.  So I 
  wrote imp3web.php to they could interact with imp3sh from a web browser.
  Now everyone in the office can que up albums to play off the ogg server 
  sitting in the corner.

2. Requirements:
   I have only tested this only on a Redhat 7.1 System.
   Here are the relavent rpm's I have
     apache-1.3.19-5
     php-4.0.4pl1-9
  You will also need something atleast new as the imp3sh-0.2.1-beta 
  release.

  Higher revisions of these programs will probably work, but I can't be 
  sure.  If problems arise with program versions newer than the ones 
  listed, please contact spatula@linuxfreemail.com so I can check it out. 
  
3. Feature Rundown
   Off the top of my head, here are the things Imp3web.php can do right 
   now:
     * Browse imp3sh playlists by genre/artist/album-title/label/year via 
       structured imp3sh playlist names.    
     * Volume control via the web interface
     * next previous play pause resume control
     * Somewhat configurable look and feel to the interface (This will get 
       better as development continues)
     * Current song information 
     * Play individual songs or albums, or que up songs or albums for 
       later

   In the works right now is a multiple-user request list system.  
   Basically, there will be 3 classes of users: admin, dj, listener.
   Admins will have full control of the imp3sh backend. dj's will have 
   some limited control over song playback. Listeners will be restricted 
   to making a limited number of song requests per time interval with a 
   maximum per day.  The listener request system will be able to 
   automagically roll in user requests.  The idea is to give imp3web the 
   ability to conform to the radio broadcast standards that the RIAA set, 
   that limit the # of requests and the # of songs per album or artists 
   you an play per hour.  All the time-intervals involved will be 
   configurable so you dont have to conform to broadcast standards if you 
   arent brodcasting.
   
4. Example Usage:

   
   4.1) You need to get imp3sh running and using the i/o named pipes 
        interface.  See the imp3sh documentation on how to do this.  I'm 
        going to assume you have the inpipe=/var/tmp/tempin and 
        outpipe=/var/tmp/tempout  locally on the same machine as you are 
        running the imp3web.php script so you don't need to use the 
        tcp/ip network interface.  If this confuses you, read the imp3sh 
        documentation

   4.2) Create playlists in imp3sh of the form:
           genre/artist/album-title
        The "/"'s are important in the playlist name structure. 

   4.3) Get apache and php installed and working.  I'm not going to go 
        through how to do that here, there are better places to learn how 
        to do that.   Make sure the inpipe and outpipe that is used by 
        imp3sh is read-writable by the user that apache runs as

   4.4) Place the imp3web.php script in a directory that the apache web 
        server can see.  On redhat /var/www/html/  is a good place for 
        testing  purpuses.


   4.5) now the fun part:  You need to configure the imp3web.php script a 
        little.  
        Lets asumme the following 
          imp3web.php in in the root web directory
          the local imp3sh pipe client is named /usr/bin/imp3client 
          the inpipe is named /var/tmp/tempin
          and the outpipe is named /var/tmp/tempout     
        Lets also assume the imp3sh playlist take the form:
           genre/artist/album-title

        The variables settings you "NEED" to change in imp3web.php are:
        $impVars["script"]     = "/imp3web.php";
        $impVars["localclient"]= "/usr/bin/imp3client";
        $impVars["inpipe"]     = "/var/tmp/tempin";
        $impVars["outpipe"]    = "/var/tmp/tempout";
        $impVars["method"]     = "local";
        $impVars["genre"]      = 0;
        $impVars["artist"]     = 1;
        $impVars["title"]      = 2;
        $impVars["year"]       = -1;
        $impVars["label"]       = -1;

    4.6) Load up http://servername/imp3web.php
        
         The navbar at the top should have options for:
         Home: loads the status page
 	 albums: browse the whole set of playlists
         genre: browse by genre
         artist: browse by artist

         Click albums, and you should see a list of the imp3sh playlist
         with option to playalbum, listsongs, or addalbum to the que.          

I think that's enugh of a startup example.


5) For bugs, feature requests, and code modifications please contact 
   spatula@linuxfreemail.com







