Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Mr. Voice improv audio software
Perl

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
COPYING
ChangeLog
Credits
README
README.windows
TODO
UPGRADING
dbinit.sql
mrvoice.php
mrvoice.pl

README

				Mr. Voice
				by H. Wade Minter
				minter@lunenburg.org

--------------------------------------------------------------------------
TABLE OF CONTENTS:
I.    About This Software
II.   Required Components
III.  Installing
IV.   Configuration
  A. Configuring mrvoice.pl
    1. The .mrvoicerc file
  B. Configuring the PHP frontend
V.    Populating the database
  A. The Easy Way
    1. Adding Categories
    2. Deleting Categories
    3. Adding Songs
    4. Deleting Songs
    5. Editing Songs
  B. The Hard Way (or:  Database internals)
VI.   Running the program
  A. Hotkeys
VII.  Contributing
VIII. Bug Reports

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

I.   ABOUT THIS SOFTWARE:
     This program was written with a very specific purpose in mind - to be 
     the GUI frontend for an MP3 database I designed for the Great American
     Comedy Company in Raleigh, NC.  As such, it may not be much use for 
     anyone else, but I figured I'd put it out there in case anyone wanted it.

II.  REQUIRED COMPONENTS:
     * Unix-like operating system (Linux/*BSD/etc.).  A Windows port should
       also be available with release 1.0.
     * Perl 5 
       REQUIRED PERL MODULES (tested versions in parentheses) 
       Get them from http://www.cpan.org/
       + DBI (DBI-1.14)
       + DBD driver for your database (Msql-Mysql-modules-1.2215)
       + Data-Dumper (Data-Dumper-2.101)
       + TK (Tk800.022)
       + MPEG-MP3Info (MPEG-MP3Info-0.71)
       + Tk::FileDialog (Tk-FileDialog-1.3)
     * Relational database, with available perl DBI module (Tested with MySQL)
       If you use something other than MySQL, you'll need to do some
       modifications.
     * TK version 8
     * xmms, or other MP3 player that plays songs from the command line.
     * class.id3.php (http://leknor.com/code/) if you're using the PHP
       frontend.

III. INSTALLING:
     1) Compile and/or install any required software from above (perl 
        modules, etc.)
     2) Set up a database for the program to use.  It needs two tables in a
        database, so you can either use an existing database or create one
        expressly for mrvoice.
     3) Run the following MySQL command from the mrvoice-x.x directory, where 
        DATABASE_USER is the name of a user with administrative access over 
        the database named 
        DATABASE_NAME:
 
        mysql -u DATABASE_USER -p DATABASE < dbinit.sql

        For other databases (Postgres, etc.), adjust to taste.  This creates 
        two tables in DATABASE_NAME: mrvoice and categories.
     4) If you will be using the PHP frontend, install class.id3.php3 
        (available from the URL above) into your PHP include path.
     5) If you will be using the PHP frontend, copy the mrvoice.php files 
        into your web tree.  

IV.  CONFIGURING:
     A. CONFIGURING MRVOICE.PL
        The following configuration settings can/should be adjusted in the 
        mrvoice.pl file itself:

        First, make sure that the first line of the file points to your 
        perl binary.  It is set up by default to look for /usr/bin/perl.  

        The following variables need to be altered to reflect your setup:
        $db_name - This should be set to the name of the database containing 
                   the mrvoice and categories tables.  If the database is 
                   local to the machine that you are running mrvoice on, you 
                   simply need to supply the database name.  If it is on a 
                   remote server, the variable takes the form of 
                   "DATABASENAME:HOSTNAME:PORT".
        $db_username - Set to a username that has SELECT access on the tables.
        $db_pass - The password for user $db_username
        $mp3player - The path to your MP3 player.  Set to /usr/bin/xmms by 
                     default.
        $category - The default category to search.  Set to "Any" by default, 
                    a meta-category that means, shockingly enough, any 
                    category.  This string must match a category code as set 
                    up in the categories database, or "Any".
        $filepath - The path information that will be prepended to the filename
                    retrieved from the database.  Used to find the actual MP3 
                    files on the local system.  If a directory, it MUST 
                    contain a trailing "/".  (ie. "/usr/local/mp3/" is valid, 
                    but "/usr/local/mp3" is not).
        $savepath - This will be the default directory that hotkey save files
                    will go into.  The user you're running the program as must
                    have write permission into that directory.

       1. THE .MRVOICERC FILE
         If the file ".mrvoicerc" exists in your home directory, any variables
         that you define in that file will override the ones in the mrvoice.pl
         script itself.  The variables take the form:
           variable_name::value
         so, for example, to define a $savepath of /tmp/ in the .mrvoicerc
         file, you would include the line:
           savepath::/tmp/

     B. CONFIGURING THE PHP FRONTEND:
        To configure the PHP frontend, edit the file mrvoice.php.  At the 
        top, you will find variables similar to the ones in mrvoice.pl.  Set 
        them appropriately.  The PHP frontend only provides a search interface 
        to the database - playing music, adding, deleting, and editing must 
        all be done from within the program itself.

        The PHP frontend provides a link to download the MP3.  To use this 
        feature, you must have an alias in your HTTPD config file pointing
        $pathname in your web tree to $pathname on the disk.  So, if your
        MP3 files live in /mp3/ on your disk, then http://www.yourhost.com/mp3/
        must point to /mp3/ on the disk.  You can do this with either an
        Alias declaration in your httpd.conf file, or a symlink.

V.   POPULATING THE DATABASE:
     Before you can use mrvoice, you must populate two tables in the 
     database.  The first is the categories table, the second is the mrvoice 
     table itself.

     A. THE EASY WAY:
        The mrvoice.pl program has a "Categories" menu item and a "Songs" menu
        item.  Under each you will find ways to add/delete/modify.

        1. ADDING CATEGORIES
           Under "Categories", you can add and delete.  To add, select
           "Categories-->Add Category".  You will have to enter a code and a
           description.  The code is a short (under 6 character) code used 
           internally by the database, and the description is what you'll 
           actually see.

        2. DELETING CATEGORIES
           To delete a category, choose "Categories-->Delete Category", and 
           select the category you wish to delete.  The program won't let you 
           delete a category that still has song entries using it, so make 
           sure you empty the category out before you try to delete it.

        3. ADDING SONGS
           To add a song, choose "Songs-->Add New Song".  A window will pop up 
           with the standard information (title, artist, category, extra info, 
           etc.).  You will also need to choose the file to add.  You can 
           either enter the file path into the "File to add" box, or press 
           the "Select File" button to bring up an "explorer"-type file 
           selector.  Once you have everything you need filled in, press "Ok" 
           to add.  
           NOTE: You must provide at least a title, a filename, and a category.

        4. DELETING SONGS
           To delete an entry from the database, choose "Songs-->Delete 
           Currently Selected Song".  Note that you will have to have a song 
           selected in the search result box for anything to happen.  If so, 
           a box will pop up asking you to confirm that you wish to delete the 
           song.  There is also a checkbox asking you if you wish to delete 
           the MP3 file from the disk as well.  
           Pressing the "Delete" button will remove the song from the database 
           and (if selected) the file from your disk.

        5. EDITING SONGS
           To edit a song, choose "Songs-->Edit Currently Selected Song".  
           Much like the Delete Song function above, you must have an entry 
           selected in the search result box for anything to happen.  If you 
           do, the Edit box will pop up, and allow you to edit the title, 
           artist, extra info, or category.

     B. THE HARD WAY:
        The categories table has two fields: the "code" field and the 
        "description" field.  To populate it, use the mysql tool to log into 
        the database that contains the categories table, and run:

     "INSERT INTO categories VALUES ('CODE','The description of the code');"

        where CODE is an 8-letter-or-less code, and the description is the 
        more verbose description.  For example, if I had a category for 
        general games stuff, I may use:

     "INSERT INTO categories VALUES ('GAMES','General Games');"

        Note that the description is what you will actually see in all of the 
        frontends, so don't make it too long.

        For the mrvoice table, there are the following fields:
        id - An auto-increment field that will contain a unique number for the 
             entry.
        title - The title of the entry
        artist - Performing artist of the entry
        category - A category that matches a CODE entry in the categories 
                   table.
        info - Extra info for the entry.
        filename - The filename of the MP3.  Must match what you have on disk.
        modtime - Records the last time the database information for this entry
                  was modified.

        A typical manual entry will look like this:

     "INSERT INTO mrvoice VALUES (NULL,'Fly South','Eddie From Ohio','GAMES',
      '','EddieFromOhio-FlySouth.mp3',NULL);"

        The NULL in the first field tells the database to assign the next free 
        number for ID, and the NULL at the end says to update the timestamp 
        with the current time.
    
        After adding the entry to the mrvoice table, you must then copy the
        file to the directory pointed to by the $filepath variable.

VI.   RUNNING THE PROGRAM:
      After you've done all of the above, it's time to run the program!  Make
      sure that the mrvoice.pl program has execute permissions, and run it. 
      If all has gone well, you should see the mrvoice window, along with 
      XMMS (or your MP3 player of choice).  Congratulations!

     A. HOTKEYS
        Hotkeys are a quick and easy way to play songs.  When you have a 
        song selected in the search results box, you can press the "Assign
        Hotkey" button to assign that song to a hotkey.  The hotkeys are
        F1 through F12.
         
        After you assign the song to a hotkey, you can press that key to 
        begin playing the song immediately.
        
        To see the hotkeys you have currently defined, use the "Show Hotkeys"
        function that is under the "Hotkeys" menu item.  It will bring up
        a box listing the keys and the songs assigned to them.  From this
        box you may also activate the checkbox beside a hotkey and press 
        the "Clear Selected" button to reset just the hotkeys that you have
        selected.  If you wish to clear all of the hotkeys in one fell 
        swoop, choose "Clear All Hotkeys" from under the Hotkeys menu.

VII.  CONTRIBUTING: 
      If you like this program, and know of a way to make it better, feel free
      to modify it.  This software is released under the GNU General Public
      License, so read the COPYING file or visit http://www.gnu.org/ for
      information on license conditions.

      If you make a cool modification to this program, feel free to send a 
      diff to me, and I'll incorporate it into the main body of the program.

      Considering I'm probably the only person using this program, if you
      even USE this software, feel free to send me an email and let me 
      know that you've found it useful.  Otherwise, I'm just talking to
      myself.  :-)

VIII. REPORTING BUGS:
      Feel free to report any bugs, feature requests, etc. to me at 
      minter@lunenburg.org.  As this is a specific-purpose project, there's no
      guarantee that I'll do it, but I'm glad to listen to any suggestions.  
      Check the TODO file to see stuff I'm currently working on.

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

CVS ID: $Id: README,v 1.13 2001/05/08 22:37:56 minter Exp $
Something went wrong with that request. Please try again.