1.1.1. Microsoft Windows

The following components are required to run Mr. Voice under Windows 95 or higher.

• An MP3 player. WinAmp version 5 is recommended. If you plan on playing Windows Media Audio (WMA) files, you will need at least WinAmp Version 5, Full install (not "Lite")

• The httpQ plugin for WinAmp. Optional, but recommended, since it allows you to fade-stop songs.

• The Ogg Vorbis plugin for WinAmp. Optional, but required if you want to play .ogg files.

• The AAC plugin for WinAmp. Optional, but required if you want to use AAC/MP4 files

If, for some reason, you do not want to run the prebuilt mrvoice.exe file, and want to install all of the Perl modules that Mr. Voice requires by hand, follow the Unix/Linux instructions below and either build the modules by hand, or install the appropriate ActiveState PPM packages. But I doubt many Windows users will want to do that.

1.1.2. Unix/Linux/BSD

The following components are required to run Mr. Voice under Unix systems.

• Perl version 5.8 (Should be provided with most modern Unix systems), plus the following perl modules (most available from CPAN):

  • Audio::Wav

  • Date::Manip

  • DBD driver for your database (DBD::SQLite 1.0 and higher supported)

  • DBI

  • MPEG::MP3-Info

  • MP4::Info

  • Ogg::Vorbis::Header::PurePerl

  • Time::HiRes

  • Tk version 804.x (Version 800.x is unsupported as of Mr. Voice version 1.10)

  • Tk::ProgressBar::Mac

• An MP3 player. xmms is recommended.

• AAC plugin for XMMS. Optional, but needed if you want to use AAC/MP4/M4A files.

1.2.1. Upgrading to Mr. Voice 2.0

If you are installing Mr. Voice on a new machine, one which does not contain an existing Mr. Voice 0.x or 1.x installation, skip these steps and go straight to the installation section.

Mr. Voice 2.0 involves a migration from the old database backend (MySQL) used in Mr. Voice 1.10.6 and before, to a new database backend (SQLite). In order to migrate your data from the old database to the new one, you need to run the migration utility.

Windows users should double-click on the upgrade20.exe file. It will open up a DOS box. Follow the instructions on-screen and, if there are no errors, it will create the new Mr. Voice database file and update your configuration to point to it. If there are errors, your MySQL database will not be modified, so you can always use 1.10.6 or lower as usual while I'm working on the problem.

Unix users should run the tools/upgrade20.pl script, and it will do the same as in the Windows instructions.

Once you are comfortable that the upgrade worked properly and that you're set up in Mr. Voice 2.0, you can delete your old MySQL installation to save disk space and system resources.

Windows users can disable the MySQL service, while keeping the software installed, by right-clicking on the stoplight in the system tray and choosing WinNT->Stop Service. This will leave your old data alone, but the MySQL service will not be running and using system resources. To completely remove MySQL from your system, go to Add/Remove Programs, choose MySQL, and hit "Remove". Then, you can delete the C:\mysql directory. Once that is done, MySQL is gone, along with your old database.

For Unix users, you may want to go into the MySQL command shell and "drop database mrvoice", and/or uninstall MySQL from your system completely (if it was only being used for Mr. Voice, of course)

1.2.2. Unix Installation Instructions

• Unpack the mrvoice-x.x.tar.gz archive. It will create a mrvoice-x.x directory. The mrvoice.pl file is the only one needed to run the program (meaning that you can move mrvoice.pl to another location after you're done configuring it), but there are other files in the archive, such as documentation, licenses, etc.

• Compile and/or install any required software from above (perl modules, etc.). I will skip the software setup, assuming that if you're trying to run this on a Unix system, you're geeky enough to install the required stuff by yourself. ;-) If you run into issues, feel free to email me or check the software's website.

At this point, all of the software should be set up and ready for configuration!

1.2.3. Windows Installation Instructions

First, download WinAmp and install it the normal way, by double-clicking the installer icon and using the defaults provided.

If you're using the httpQ plugin for WinAmp, download its zip file and install it. Then, do the following steps:

• Start WinAmp by itself, right-click on the "OAIDV" bar on the left of the window, choose Options->Preferences.

• Go down to Plugins->General Purpose. You should see the httpQ plugin listed. Highlight that, and hit "configure".

• Under the General tab, put in a password (your choosing), leave the port at 4800, and check the box to start the service automatically. Hit the Apply button, then the x at the top-right. Close the preferences, and exit from WinAmp. Remember the password you just set up - you will need it later.

Any other WinAmp plugins (OGG, AAC, etc.) should be installed in the default way following the instructions provided with the package.

2.1.1. Database Options

• Database Filename (db_file) - The file on your hard drive that contains the Mr. Voice SQLite database (C:\mrvoice.db by default on Windows, ~/mrvoice.db by default on Unix)

2.1.2. File Paths

• MP3 Directory (filepath) - The path information that will be prepended to the filename retrieved from the database or, in other words, the directory where you store your MP3 files. Used to find the actual MP3 files on the local system. The user who is running Mr. Voice must have read/write permission into this directory.

• Hotkey Directory (savepath) - This will be the default directory that hotkey save files will go into. The user running the program as must have read/write permission into that directory. Recommended to be different than the Mr. Voice install directory.

2.1.3. Search Options

• Search ASCAP songs (search_ascap) - Enables searches of songs that have ASCAP set as the publisher field. Only needed if you are using song publishers in your database.

• Search BMI songs (search_bmi) - Enables searches of songs that have BMI set as the publisher field. Only needed if you are using song publishers in your database.

• Show Song Publisher (show_publisher) - Enables the display of the song publisher in the search results. Only needed if you are using song publishers in your database.

• Search Other songs (search_other) - Enables searches of songs that have "Other" set as the publisher field. Only needed if you are using song publishers in your database.

2.1.4. Online Options

• Enable Online Functionality (enable_online) - Enable this option if you want to use any of the online functionality (such as version checks or Mr. Voice Online). If this is not enabled, you will not get the menu items that offer online functionality. Obviously, enabling this without an internet connection on your Mr. Voice computer is a bit silly.

• Check For New Versions (check_version) - If enabled, will check the Mr. Voice website once a week and alert you if a new version of Mr. Voice is available.

• Mr. Voice Online key (online_key) - When you register for Mr. Voice online, you will be given a key password. Enter that here, or your Mr. Voice online functionality will fail. For information on how to get a key, see the Mr. Voice Online section in this manual.

2.1.5. Other

• MP3 Player (mp3player) - The path to your MP3 player. Likely options are /usr/bin/xmms for Unix systems, and C:\Program Files\WinAmp\WinAmp.exe for Windows systems. This option is not used on Mac OS X, as it uses AppleScript to launch the Audion MP3 player.

• Number of Dynamic Documents To Show (savefile_max) - The number of "most recently accessed hotkey files" to keep available under the File menu. Defaults to 4.

• httpQ Password (httpq_pw) - The password used to connect to the httpQ plugin for WinAmp. Only useful under Windows if you're using the httpQ plugin. Otherwise it's ignored.

• Write Access Password (write_password) - If this option is set, any attempt to perform an action that will modify the Mr. Voice system (adding a song, deleting a song, renaming a category, etc) will prompt for the password (once per session).

  

  No password, no changes. Useful if you have people running Mr. Voice that you don't trust not to break things.

2.1.6. Manual Configuration

To troubleshoot, fine-tune changes, or skip the GUI alltogether, you can manually set up the configuration file. The configuration file consists of lines in the following format:

variable_name::value

Where variable_name is the name in parenthesis in the configuration listing above, followed by two colons, followed by the value you want to set the variable to. A sample file on Unix would look like this:

db_file::/home/mrvoice/mrvoice.db
filepath::/mp3/
savedir::/tmp/
mp3player::/usr/bin/xmms
savefile_max::4
httpq_pw::mypass
search_ascap::1
search_bmi::1
search_other::1
show_publisher::0
        

The Windows C:\MRVOICE.CFG file will look similar, but with Windows pathnames instead of Unix ones. The Mac config file (named mrvoice.cfg in your home folder) will look similar to the Unix one.

3.1.1. Categories

Category options are very simple. You can either add a category, edit its long (descriptive) name, or delete a category. All options can be found under the Categories menu on the main display.

To add a new category, choose Categories->Add Category. You will then have a box pop up where you can enter two items: The Category Code and the Category Description.

To delete a category, choose Categories->Delete Category. A box will pop up listing all of your defined categories. You can choose the button next to the category that you would like to delete, then press Ok to delete the category.

You cannot delete a category if it still has songs in it. Delete/edit all songs out of the category before trying to delete it.

Finally, you can edit a category, by choosing the Categories->Edit Category menu. Once there, you can edit the long name, but not the short code, of the category.

3.1.2. Songs

Songs are the audio data that you're trying to play. You can use any sort of audio data that your audio player can handle, but Mr. Voice can figure out things like playing time for MP3, WAV, Ogg Vorbis, AAC, and WMA files. If you're not trying to store, categorize, and play audio data, then you're probably using the wrong program! This manual will refer to the audio data that you are storing as "songs", even though they can, of course, be any kind of audio. To manipulate songs in the database, there are three main actions: adding songs, deleting songs, and editing songs.

To insert a new song into the database, choose Songs->Add New Song. A box will pop up for the needed information:

• Song Title: This is where you put the title of the song that you are adding.

• Artist: The artist responsible for the song. This is an optional item.

• Category: Pressing the Choose Category button beside this entry will give you a list of the categories that you currently have defined. You must choose one of these categories to place the song into.

• Category Extra Info: Kind of a "hodgepodge" entry, this information can be whatever you want. At ComedyWorx, we use it as a modifier for the category. So if the category is "Game", the Extra Info is the name of the game. If the category is for Player Intros, the Extra Info will tell us whether it's specifically for a referee, dimwit, or whatnot. So, basically it's just free-form for whatever you need, and is an optional field.

• Publisher: This field is for the publisher of the song. Current values are ASCAP, BMI, or Other. The default value is Other, which should be fine for people who don't want to bother with publisher information. But if you're using Mr. Voice in an organization that needs this information, here's where you can put it.

• File To Add: This is where you give Mr. Voice the path to the actual audio file that you want to add. Clicking the Select File button will bring up a familiar "file chooser" box. The screenshot below is from a Linux system - Windows users will see the familiar Windows file chooser box.

  Figure 3-5. The Add Song File Selection window

  

  Use this to go to the location of your file, left-click on the name of the file, then click Open. The name of the file should now be listed in the File To Add box. If the file you are adding is an MP3, OGG, AAC, or WMA with valid tag information, it will automatically fill in the Title and Artist fields with that information.

• Preview Song: Once you have selected a file, you can press this button to hear the song. Useful for making sure you have the song you want before you add it.

You can now press the Ok button to add the song. If all goes well, you should see a message that the file was added to the database. If not, Mr. Voice should tell you what went wrong, and let you go back and fix the entry.

Mr. Voice actually makes a copy of the file that you select, renames it to a standard form, and places the new copy in the location given by the $filepath variable that you defined in the setup. Your original audio file is not used after the copy is made, so you can feel free to delete it.

It can be tedious to add songs one at a time if you have many files to add. New in version 1.8 is the Songs->Bulk-Add Songs Into Category menu option. Upon choosing this, you will be prompted for a category and a directory. Select the category, and a directory that contains the set of MP3, OGG, AAC, or WMA files that you would like to add to that category. Mr. Voice will then use the title and artist tags stored in the files to automatically add those files into your selected category. If you need to add Extra Info or modify any other fields, you will need to do that after the fact, but this should be a good way to add lots of data at once. You can also specify a publisher here, useful when adding a whole CD's worth of songs with the same publisher.

There are two other ways to add songs. The first is that you can select song files on your desktop or file explorer, and drop them onto the main search box of Mr. Voice. When you do that, the Add New Song function will be launched on those files. Finally, you can choose the Songs->Add Songs From Bundle menu item. That will allow you to import a Mr. Voice "bundle" ZIP file. All songs in the bundle will be added, along with all information about the file, and any needed categories will be automatically created.

To delete a song, you must have at least one displayed and selected in the main search results box. Searching is covered later, but if you hit the Do Search button, it should show you all of the songs in your database.

Once you have some songs displayed, left-click once on the name of the song that you want to delete, or select several songs by pressing Control or Shift while selecting, then choose Songs->Delete Currently Selected Song. You can also right-click on the name of the song or songs and choose the Delete Song option. A box will pop up asking you to confirm the deletion, and also presenting a checkbox labeled Delete File On Disk.

If you do not have a song selected in the main display box and choose Songs->Delete Currently Selected Song or Songs->Edit Currently Selected Song, then nothing will happen. This is normal. If you are trying to edit or delete a song and don't get the repective boxes showing up on-screen, make sure that you have a song highlighted.

Finally, if you want to edit a song in the database, left-click a song in the main display window, and choose Songs->Edit Currently Selected Song. You can also right-click on a song and choose the Edit Song option. A box will pop up that is similar to the one for Songs->Add New Song, except without the file selector option. You can make any needed changes to the song, then press Ok to commit them.

	Shortcut!
	You can also right-click a song in the main display box to bring up a shortcut menu. From this menu, you can choose to edit or delete the selected song.

If you have multiple songs selected and choose to edit, you will only be able to edit the Extra Info, Category, or Artist fields, not the Title.

There is a menu choice named Songs->Update Song Times/MD5s. This will re-index all your song files, updating their play times and the MD5 sum (used in Mr. Voice online to see if two songs are the same). While in theory this information should be set when the song is added and never change, you may want to run it every once in a while to make sure the information is correct. If you edit a file in your MP3 directory manually, or replace a file in the MP3 directory directly with a new one, you will need to run this procedure. This process could take a while, depending on the speed of your computer, so you may not want to run it in the middle of a show.

3.2.1. Searching The Database

The search fields of the main Mr. Voice window contain the items that you can search for. You can use any combination of the fields to search, with the exception of the OR any field contains field, which overrides everything except the category. For the fields where you can type in text, there is an arrow icon to the right of the text entry box. If you click that arrow, a menu will pop up listing all the things you have searched for in that category. You can use this menu to quickly re-select something that you have already searched for. Let's look at the fields in detail:

• Choose Category: This allows you to set the category to search within. You can either choose a specific category, or the Any Category option, which will search all defined categories. The short name of the currently selected category will be displayed beside the menu.

• Extra info: Text placed in this box will be compared with the "Extra Info" field of each song. This, like each of the text entry fields, is a case-insensitive substring match, meaning that if you search for "eat", it will match the words "Eat", "Beatles", "EATING", etc.

• Artist: Text in this box will be compared with the "Artist" field of the songs.

• Title: Text in this box will be compared with the "Title" field of the songs.

• Any Field: Text in this box will be compared to the Title, Artist, and Extra Info fields of each song, and return any song that has a match in any of those fields. So searching the Any Field box for "eat" will return songs by The Beatles, the song titled "Masterpeace Theatre Theme", or one with the extra info of "Featured". The only thing that the Any Field does NOT search is the Category - you will need to select that manually.

After you have filled in the information that you would like to search for, you can either press the Enter key, or press the Do Search button. The status bar will tell you how many matching entries your search found, and display the results in the Search Results box. If you have any songs in your database where there is no matching audio file on disk, they will show up in red as "invalid" files. If you try to play these songs, nothing will happen (as there's no actual file to play!). Invalid songs should either be deleted, or the expected file should be moved into place. If all of your songs show up as invalid, that's a good sign that you have your MP3 Directory set incorrectly in the preferences.

If you have chosen in the File->Preferences menu to restrict searches based on the Publisher, that will affect your search results - only searches from your select publisher group will end up displayed.

If your mouse has a scroll-wheel on it, you can use the wheel to scroll the list of search results up and down.

There is also an Advanced Search menu. On that menu, you can choose to have Mr. Voice show you all the song that have changed during the current day, or over the past 7, 14, or 30 days. You can also search for songs that were added or changed over an arbitrary date range via the Advanced Date Search menu.

3.2.2. Playing Songs

At this point, you have added songs to the database, and you have searched for songs. Now, with some songs listed in the Search Results box, you're ready to play the songs!

To play a song, you can left-click on the song in the Search Results box (the song should become highlighed when you do this), and press the green Play Now button. While a song is highlighted, you can also press Control+P to start the song playing. You can also double-click the song in the Search Results box, or right-click the song and choose the Play Song option. When you do this, your audio player should spring to life, and you should hear the song coming out of the speakers. Congratulations! It works!

To stop the song, you can either press the red Stop Now button, or press the Esc key on your keyboard. Play should then stop.

Windows users who have installed the httpQ plugin (and entered its password under the File+Preferences->Other menu) have an additional option. Pressing the Shift key while either clicking on the Stop Now button or pressing the Escape key will cause the song to fade out before stopping, over a period of a couple of seconds.

3.2.3. Exiting Mr. Voice

To exit Mr. Voice, choose File->Exit, or press Control+X. Mr. Voice will prompt you to confirm that you want to exit, and if you do, the program will exit and your audio player will close.

3.3.1. Configuring Hotkeys

To set up a hotkey, you must first search for a song and have it displayed in the search results box. The available keys are the function keys F1 through F12. You can bind a song to more than one hotkey if you choose. To assign a song to a hotkey, open the Show Hotkeys window, left-click on a song within the Search Results box, and drag it over to the name of a hotkey (F1 through F12), and drop it on the name. The song you dragged will then be assigned to the hotkey that you dropped it on.

You can also drags songs from the Holding Tank onto a hotkey, just like you can from the main search box.

To see which hotkeys you currently have defined, choose Hotkeys->Show Hotkeys from the main menu. You can also press Control+H. That will bring up a menu showing each of the 12 hotkeys, and beside the key name, the title, artist, and time of the song that is bound to the key. If you leave this window up, you can see it change as you add or remove hotkeys.

To remove hotkeys, you have two choices: Remove keys individually, or remove them all in one fell swoop. To remove all hotkeys, choose Hotkeys->Clear All Hotkeys from the main menubar. This will do exactly what it implies - reset all hotkeys back to empty. You can also, from the Hotkeys->Show Hotkeys menu, press the buttons beside any key listing, and choose the Clear Selected button to clear out just the keys that you select, while leaving the others alone.

If you clear all hotkeys, the Hotkeys->Restore Hotkeys option becomes available. It allows you to return your hotkeys to the state they were in immediately prior to the clearing. This exists in case you accidentally clear hotkeys that you don't mean to. Note that the Restore Hotkeys feature currently only works for the Clear All Hotkeys and Open Hotkey File (discussed below) options.

You can also lock the hotkeys by choosing the Hotkeys->Lock Hotkeys option. When hotkeys are locked, a checkmark appears beside the menu item, and you will not be able to add or clear any hotkeys until you deselect the lock option.

3.3.2. Using Hotkeys

To use hotkeys once you have defined them, simply make sure that a Mr. Voice window is selected, and press the hotkey for the song that you want. The song should immediately begin playing.

3.3.3. Saving and Loading Hotkeys

To make the use of hotkeys more convenient, you can save groups of hotkeys to a file for later retrieval. To use this feature, first assign songs to hotkeys like you want. Then, choose File->Save Hotkeys To A File, or press Control+S. A box will pop up where you can select the filename to save the hotkeys under. The file by default will be saved in the directory that you defined in the $savedir variable during configuration. Simply enter the filename that you want in the box labeled Filename, and press the Save File button. The filename will have the extension ".mrv" appended to it, and get written to disk.

If you save a hotkey file with the name default.mrv, that hotkey file will be automatically loaded every time you start Mr. Voice.

To load a saved hotkey file, simply choose File->Open Hotkey File, or press Control+O. The file box will pop up, and you can choose the name of the hotkey file that you want to load. Choosing the filename and pressing the Open File button will load the hotkeys defined in the file, and will overwrite all hotkeys that you currently have defined. If you do this and want your old hotkeys back, choose Hotkeys->Restore Hotkeys. When you load a saved hotkeys file, the Hotkeys window will display (if it is not up already).

The most recent hotkey files that you have accessed via a save or open will be listed on the File->Recent Files menu. These filenames can be selected directly for one-click access that recently-used hotkey files. To adjust the number of files that are displayed, use the File->Preferences menu. Four is the default.

3.3.4. The Holding Tank

Somewhere in a netherworld between the search box and hotkeys exists the Holding Tank. The Holding Tank can be accessed via the Hotkeys->Show Holding Tank menu choice or by pressing Control+T. You can drag songs to it, like with the Hotkeys window. Unlike the Hotkeys window, though, you can have an unlimited number of songs in there at any time, but you can't get one-button access to playing those songs. New in Mr. Voice 1.10, you can save and load the contents of Holding Tanks to a file, just like hotkeys. Find those options under the File menu. You can also export the contents of the Holding Tank as a "bundle" - a special zip file that can be imported in another copy of Mr. Voice, while retaining all the information about the songs.

You populate the Holding Tank by dragging and dropping songs from the search results box onto it. The items in the Holding Tank will appear in the order you add them. To reorder the songs within the Holding Tank, highlight the song you want to move and press the Up Arrow or Down Arrow buttons to move it up and down in the list.

To play a song from the Holding Tank, you can either double-click the song in the Holding Tank window, or single-click the song and press the Play button.

You can use the up or down arrow buttons on either side of the Holding Tank to reorder the songs. That can come in handy when you press the blue Launch Playlist button, which will launch a playlist in WinAmp or XMMS of all the songs in your Holding Tank, in the order they are displayed.

To remove a song from the holding tank, click on the name of the song, then press the Clear Selected button. You can press the Control key while clicking to select more than one song, then use the Clear Selected button to clear all selected songs. Or, for a quicker way to clear all songs from the Holding Tank, use the Hotkeys->Flush the Holding Tank menu selection to wipe it with one fell swoop.

The Holding Tank allows you to easily move songs between installations of Mr. Voice, via a new feature called bundles. To create a bundle, move songs into the holding tank. Then, when you're finished, choose the Hotkeys->Export Holding Tank As Bundle option. That will write a .zip file to your root directory (see the status line of the Mr. Voice window for the specific path). That zip file contains the MP3 files for the songs you expored, plus a special XML file that contains the information for the songs (title, artist, extra info, category, etc).

You can then transfer that .zip file to another system, and import it into that installation of Mr. Voice. The songs will be copied into its database, with the song information from the original.

4.2.1. Downloading Songs

Once you have performed a search, and have some songs in the Mr. Voice Online window, you can download them. Currently downloads are limited to one at a time - multi-song downloads will be added in a future version. You will notice that the button that reads Play Now in the normal Mr. Voice window is now blue and reads Download/Add. Double-clicking a song in the Mr. Voice Online window, or clicking the Download/Add button, will download the song in the background (which could take some time, depending on the size of the file and the speed of your internet connection).

Once the song is downloaded, the standard Add New Song window will be displayed, loaded up with information about the downloaded song. You can preview the song here, to see if you want it. If you click Ok (be sure to select a category), the song will be added to your local system. If you click Cancel, nothing happens.

4.2.2. Uploading Songs

You upload songs from the normal Mr. Voice window. When you have a song listed in the main window, you can right-click on it to see a menu. On this menu will be an option named Upload to Mr. Voice Online. Song uploads are currently limited to one-at-a-time - multi-song uploads are planned for a future release.

Choosing that menu item will immediately attempt to upload the song to Mr. Voice online. It will check to be sure that file does not already exist, then start the upload (which could take a while, depending on the size of the file and the speed of your internet connection). Once the file is uploaded, the status bar will update with the new online song ID of the song, plus the time it took to upload.

Note that when you perform the Predefined Searches->Show Local Songs That Are Not Online search, the local songs will show up in the main Mr. Voice window, not the Mr. Voice online window. This is because you have to do uploads from the main window.