
                              muzikQ 0.3
                           <*//////////////*>

                  Tim A. Brown <greendayzero@gmail.com>

                              August 2008

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

Copyright Notice
<*////////////*>

     Copyright (C)2008 Tim A. Brown

     This file is part of muzikQ.

     muzikQ is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.

     muzikQ is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with Foobar.  If not, see <http://www.gnu.org/licenses/>.


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

Contents
<*/////*>

     1.        Introduction
     1.1.      What's new in 0.3

     2.        Installation
     2.1.      How to obtain muzikQ
     2.2.      Requirements
     2.3.      Compilation and installation

     3.        Usage
     3.1.      Command line options
     3.2.      Config file
     3.3.      In-program controls
     3.4.      Song ratings and volume

     4.        Q & A
     4.1.      How am I supposed to add files to a playlist?
     4.2.      I've found a bug or thought of a feature). What do I do?
     4.3.      What are those .mkq files?
     4.4.      Why three different methods for random play?
     4.5.      Why the name muzikQ?

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

1. Introduction
<*////////////*>

     muzikQ is an curses-based Audio player.  Based on some code from the
     old ksmp3play, it is the official upgrade from that software.
     Features are rating system, random play, playlist, tag viewing & 
     editing, & minial networking capabilities for telnet or ssh.

     REMEMBER THAT muzikQ IS BETA SOFTWARE!  IT MAY WORK POORLY, NOT
     WORK AT ALL, SCREW UP YOUR MUSIC COLLECTION, OR EVEN DAMAGE YOUR
     COMPUTER!  USE AT OWN RISK! .. but it shouldn't =)

1.1. What's new in 0.3
<*////////////////////*>

	*  configuration menu has been added.  Access this by pressing 'C'

	*  pressing 'T' will goto the top of the playlist.

        *  when editing tags, pressing enter on an empty line fills variable with
	   current value.
      
	*  Many major & minor bug fixes.


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

2. Installation
<*/////////////*>

2.1. How to obtain muzikQ
<*//////////////////////*>

     muzikQ can be downloaded from http://sourceforge.net/projects/ksmp3play/

2.2. Requirements
<*///////////////*>

     muzikQ requires the following[1]:

        * SDL 1.1.5+

        * SDL_mixer 1.2.8+

        * ncurses 5+

        * SMPEG 0.4+

        * libvorbis 1.2.0+
        
        * Taglib 1.5+

[1]  muzikQ may compile with older versions, but this has not been
     tested. 


2.3. Compilation and installation
<*//////////////////////////////*>

     muzikQ uses the GNU autotools, which should make the installation
     easy.  For more detailed installation instructions read the `INSTALL'
     file included in the package.  However, for most people the following
     should work:

          % ./configure
          % make
          % make install

     If you encounter into problems please report them to the the author at
     <greendayzero@gmail.com>


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

3. Usage
<*//////*>

3.1. Command line options
<*///////////////////////*>

          Usage: muzikQ [OPTION ...] FILE1 [FILE2 ...]
          Options:
            -h, --help                 display this help and exit
            -v, --version              output version information and exit
            -r, --random               start in random play mode
            -l, --loop                 start in loop play mode
            -t, --title                set xterm title (0/1, default=1)
            -d, --delay                delay between songs (in seconds)
            -m, --rmethod              method used for random play (1/2/3)
            -p, --playlist             default playlist to save to
            -c, --cdrom		       enable cdrom audio (0/1, default=1)
	    -a, --channels	       define audio channels (1-8)
	    -b, --buffers	       define audio buffers (0-4096)

     You may specify as many files as you wish at the command line.  These
     can be either mp3, m3u, ogg, or mkq files, or even an URL for http
     streaming.  It's not necessary to use the --playlist option if only
     one mkq file is specified, since this file will be considered the
     default playlist.

3.2. Config file
<*//////////////*>

     muzikQ looks for a dot-file in the user's home dir called
     .muzikQrc.  The format of this file is <variable> = <value>, one
     variable on each line.  Empty lines and lines beginning with # are
     ignored.  

     ** This can now be created in the program by pressing 'C' **


3.2.1. General config variables
<*/////////////////////////////*>

     The general config variables you can set in the config file are:

        * Random (0/1) - Start in random play mode

        * Loop (0/1) - Start in loop play mode

        * Volume (0-100) - Default volume

        * Set_xterm_title (0/1) - Set xterm title to currently playing song

        * Delay_between_songs (0-5) - How many seconds to pause between
          songs

        * Random_method (1-3) - Method used for random play, See Section
          4.4, `Why three different methods for random play?'  for more
          details.

     Here's an example:

          #
          # Conf file for muzikQ
          #
          
          # Start in random play mode (0/1)
          Random = 1
          
          # Start in loop play mode (0/1)
          Loop = 1
          
          # Set xterm title to currently playing song
          Set_xterm_title = 1
          
          # Default volume (0-100)
          Volume = 80


3.3. In-program controls
<*/////////////////////*>

     These are the default controls.

3.3.1. Controls
<*/////////////*>

        * LEFT/RIGHT - Seek within song.

        * UP/DOWN - Move up/down in playlist.

        * PGUP/PGDN - Jump up/down in playlist.

        * ENTER - Select song.

        * HOME - Jump to the currently playing song.  *

        * SPACE - Pause/unpause.  *

3.3.2. Song options
<*////////////////*>

        * 1-9 - Set rating of selected song.

        * +/- - Change volume for currently playing song.  *

        * E - Edit tags for selected song.  *

3.3.3. Playlist options
<*////////////////////*>

        * F1 - Sort playlist according to Artist.  *

        * F2 - Sort playlist according to Song name.  *

        * F3 - Sort playlist according to Time.  *

        * F4 - Sort playlist according to Rating.  *

        * A - Add files to playlist.  *

        * D - Delete song from playlist.  *

        * S - Save playlist.  *

        * / - Search the playlist.  *

3.3.4. File browser
<*////////////////*>

        * UP/DOWN - Navigate up/down in the current dir.

        * PGUP/PGDN - Jump up/down in the current dir.

        * ENTER - Change to the highlighted directory.

        * LEFT - Same as hitting ENTER on '..'  (cd ..).

        * RIGHT - Same as hitting ENTER on a dir (cd dir).

        * SPACE - Select/unselect the highlighted file.

        * Q - Close the file browser and load the selected files into the
          playlist.
   
        * / - enter path manually.

3.3.5. Playmodes
<*//////////////*>

        * R - Enable/disable random play mode.  *

        * L - Enable/disable loop play mode.  *

3.3.6. Other
<*//////////*>

        * H - Show help screen.  *

        * Q - Quit.  *


3.4. Song ratings and volume
<*/////////////////////////*>

     muzikQ allows you to rate the songs in a playlist with a value
     between 1 and 9.  This affects the chance of that particular song
     being played in random play mode.  See Section 4.4, `Why three
     different methods for random play?'  for more details.

     The volume is individual for each song, with a default of 80 or what's
     specified in the config file.  This, along with the song rating, is
     saved in the .mkq playlist.

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

4. Q & A
<*//////*>


4.1. How am I supposed to add files to a playlist?
<*///////////////////////////////////////////////*>

     You can do this from the command-line.  The easiest way would be to
     run muzikQ like this:

          muzikQ playlist.mkq newfile1.mp3 newfile2.ogg

     Since muzikQ will not make duplicate entries in the playlist, you
     could even do this:

          muzikQ playlist.mkq *mp3 *ogg

     muzikQ includes a filebrowser for adding files during execution.

     If muzikQ is ran by itself, the filebrowser will be presented.

     NOTE: muzikQ will read the old ksmp3play playlist files.

4.2. I've found a bug or thought of a feature). What do I do?
<*//////////////////////////////////////////////////////////*>

     Open a ticket or report in message to http://sourceforge.net/projects/ksmp3play/
     Also, you can email greendayzero@gmail.com

4.3. What are those .mkq files?
<*////////////////////////////*>

     muzikQ's own playlist files have the .mkq extension.  You will
     probably not be able to load these playlists in another music player.
     The .mkq files are organized as follows:

<mp3 file 1> <song rating> <volume>
<mp3 file 2> <song rating> <volume> 
<ogg file 1> <song rating> <volume>
etc..   

     muzikQ can (at the moment) only save playlists in .mkq format.


4.4. Why three different methods for random play?
<*//////////////////////////////////////////////*>

     The obvious answer is: "it gives you more control".  Here are
     explanations of the three different methods used for random play.

4.4.1. Method 1
<*/////////////*>

     This is the simplest of the three methods.  It will make sure that a
     song with a rating of 5 will be played 5 times more often than a song
     with a rating of 1.  A song with a rating of 6 will be played 3 times
     more often than a song with a rating of 2, and so on.

4.4.2. Method 2
<*/////////////*>

     This is the default method in ksmp3play.  The difference compared to
     method 1 is that the rating will be squared before use.  This means
     that if you have two songs, one with a rating of 6 (6^2 = 36) and one
     with a rating of 4 (4^2 = 16), the song with a rating of 6 will be
     played 2.25 (36 / 16 = 2.25) times more often than the one with a
     rating of 4.

4.4.3. Method 3
<*/////////////*>

     Method 3 is the most advanced method.  It will not only do the same as
     method 2, but it will also divide the rating by the length (in
     minutes) of the song.  Let me give you an example:

     Let's say you have three songs in your playlist.  Two of them are 5
     minutes long, and one is 10 minutes.  They all have the same rating
     (5) , so if you used method 1 or 2 they would all get played just as
     often (at least in the long run).  Assume you listen to these three
     songs for one hour.  That means that you have heard each song three
     times.  However the song that's 10 minutes long would have been played
     for a total of 30 minutes, and the other two for 15 minutes each.
     That doesn't seem quite right since they all have the same rating.
     The answer to this is to compensate for the song length.

     If you use method 3 instead of method 2, the total, or final, rating
     of the song that's 10 minutes would be 2.5 (rating^2 / time = 5^2 / 10
     = 2.5) and the total rating of the 5-minute songs would be 5 (5^2 / 5
     = 5).  This means that if you listen to these songs for one hour, they
     would be played for a total of 20 minutes each.

4.5. Why the name muzikQ?
<*//////////////////////*>

     Well, the idea came about to add ogg support to ksmp3play.  Since mp3
     was in the name, it didn't fit once it became reality that it supported
     VorbisOgg.  So, a friend came up with muzikQ and it stuck.

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

 Acknowlegements
<*/////////////*>

     ksmp3play 0.5.1 - Copyright (C) 2001 Karl S�derstr�m
    
     Karl, the orginal code for ksmp3play is greatly appreciated and helped to mold muzikQ. -- Thank you.

     All other code, libraries, etc. Copyrights stand firm and are acknowledged. =)
