Gmu: Wejp's Gp2x MUsic player
Copyright (c) 2006-2007 Johannes Heimansberg
http://wejp.k.vu/projects/gmu/

Gmu is a music player with a file browser and a playlist.
Gmu is freeware and comes without any warranty.

Installation:
-------------

Extract the .zip archive on the SD card.
The obj and libs directories are not needed.
You can delete them.

To run the player start gmu.gpu.
To configure Gmu run gmu-setup.gpu.

Supported formats:
------------------

- Ogg Vorbis
- MP3
- Musepack (MPC)
- FLAC
- Some module formats (MOD, IT, STM, S3M, XM, 669, ULT)
- Lots of ADBLIB module formats (A2M, ADL, AMD, BAM, CFF, CMF, DFM, DMO,
                                 DRO, DTM, HSC, HSP, IMF, KSM, LAA, LDS, M,
                                 MAD, MID, MSC, MTK, RAD, RIX, ROL, SA2,
                                 SAT, SCI, SNG, XAD, XAS, XSM)
- M3U (Gmu can open M3U playlists)

Controls:
---------
These are the default controls. You can remap all button
by  fileting your own keymap file. See below for details.

Global:
R            - Skip to next track in playlist/Start playback
L            - Skip to previous track in playlist
START        - Pause/resume playback
X            - Stop playback
CLICK+START  - Exit player
SELECT       - Toggle file browser/playlist view/track info
VOL+/-       - Change volume
CLICK+SELECT - Toggle hold (LCD is turned off in hold state)
CLICK+A      - Program info
CLICK+VOL-   - Toggle time elapsed/remaining

File browser:
A            - Play file without adding it to the playlist
B            - Add selected file to the playlist/Change directory
Y            - Add selected directory and all sub directories
CLICK+B      - Insert selected file after selected playlist item
CLICK+X      - Delete selected file (*)

Playlist:
A            - Toggle random mode
B            - Play selected track
Y            - Remove selected track
CLICK+Y      - Clear playlist
CLICK+X      - Delete selected file (*)

Track info viewer:
A            - Show/hide cover artwork
B            - Show/hide text

(*) These actions are disabled by default. If you want 
to be able to delete files from the file browser and/or
playlist browser, you need to uncomment these lines in
your default.keymap file:

#FileBrowserDeleteFile=Mod+X
#PlaylistDeleteFile=Mod+X

Simply remove the '#' to enable these key mappings.


Custom key mappings:
--------------------
You can customize Gmu's key mappings if you don't like
the defaults. To do that open the default.keymap file in 
a text editor or copy it to a new file with the .keymap 
extension (such as my.keymap) and open that one in an 
editor.
The first thing you need to know is, that Gmu uses one
button as a meta key (modifier). If that key is pressed,
all other buttons have a different meaning. This way you
can have twice as many functions mapped to the keys as 
you could have without a meta key. Ok, actually it is 
only twice as many minus one, as the meta key itself does 
not have a function anymore.
First you should choose one of the buttons as you meta
key. You can change it by editing the Modifier= line.
By default it is set to

Modifier=STICK_CLICK

If you prefer to use the SELECT button for example, you
would have to change it to

Modifier=SELECT

It is the same for all other keys except that you can use
the previously defined meta key for actions. You can do that
by prepending "Mod+" followed by the button name.
Lets say you want to map the random function to the Y
button when the modifier (meta) button is pressed you would
do it by changing the PlaylistToggleRandomMode line as follows:

PlaylistToggleRandomMode=Mod+Y

Possible buttons are:
A, B, X, Y, START, SELECT, L, R, VOL+, VOL-, STICK_CLICK,
STICK_LEFT, STICK_RIGHT, STICK_UP and STICK_DOWN.

There are a few alternate keymap example files included.
To use them, either edit your gmu.conf and change the
KeyMap=default.keymap line accordingly or use the Gmu
setup tool to change it.

Command line arguments:
-----------------------

Gmu now accepts files to be added through the command line.
This can be useful, if you want to run Gmu through a file
manager.
You can add multiple files on the command line and they
will be added to the playlist and playback will be started
automatically.

Example:
./gmu song1.mp3 another_song.ogg cool_tune.s3m list.m3u

This would add the three files and the contents of the 
playlist file "list.m3u" to the playlist in the 
given order and start playback with the first song.

To enable the random playback mode you can use the -r flag.

Example:
./gmu -r list.m3u

You can use the -m flag if you do not want gmu to start the
gp2xmenu on exit. Only use this from a script unless you
want to reboot your gp2x.

With the -s option you can load another skin file instead of
the default.skin.

Example:

./gmu -s another.skin

The Gmu setup tool can be launched by using the -c parameter.
There is a shell script called gmu-setup.gpu included in the
Gmu archive that runs Gmu with the -c parameter.


Config file:
------------

Gmu's config file is called gmu.conf. It is a plain text file.
Please note: Most of the following options can be changed 
through the Gmu setup tool without editing the config file.

Supported options:

* DefaultFileBrowserPath

You can use this to define the path where the file browser
will start. It is set to "." by default, which is the
current directory. You can set it to any path you like.
Both absolute and relative paths can be used. Make sure
the path exists otherwise gmu will fall back to its current
directory.

* DefaultSkin

With this option you can specify the default skin which Gmu
loads if no -s parameter is used. By default it is set to
default.skin. There are a few other skins included with Gmu
by default, such as dark_small_lcd.skin and old-default.skin.

* KeyMap

With this option you can specify the key map file Gmu loads
on start up. By default it is set to default.keymap.

* RememberLastPlaylist

This option can be set to "yes" or "no". If set to yes
(which is the default) gmu will save its playlist on exit
and restore it the next time gmu is started. Gmu stores
the playlist in a file called "playlist.m3u" located in
Gmu's directory.
You can disable this behaviour by setting it to "no".

* AutoSelectCurrentPlaylistItem

This option can be set to "yes" or "no". If set to yes
Gmu moves the cursor to the current playlist item each
time a new track begins.

* AllowVolumeControlInHoldState

This option can be set to "yes" or "no". When set to yes
you can adjust the volume even if the player is in the
hold state. The default is "no".

* SecondsUntilBacklightPowerOff

When this option is set to any number greater than zero,
the screen backlight will be turned of after the given
number of seconds of inactivity. Any key press turns it 
back on again. The action of the key you used to turn 
it on again is executed normally. If you just want to 
turn the screen on again, press the stick button.

* EnableCoverArtwork

This option can be set to "yes" or "no". If set to "yes"
Gmu tries to find a cover artwork for the current track
and displays it in the track info view.

* CoverArtworkFilePattern

This option tells Gmu for what files it should search as
a cover image. It is set to "cover.jpg;*.jpg" by default.
Gmu will use the first file that matches the given patterns.
Allowed wildcards are * (which means any number of 
arbitrary characters), the ? (which means exactly one
arbitrary character) and the $ sign (which stands for the 
file name of the current file without its extension). Besides
those you can use any other character. Those characters match
themselves.
Gmu searches for the cover image in the same directory
where the current file is located.
You can use multiple patterns each seperated by a semicolon
(;). The first pattern given has the highest priority.
With "cover.jpg;*.jpg" Gmu would try to find a cover.jpg in 
the directory first and if it is not found it would try any 
other jpg file.   

Examples:

CoverArtworkFilePattern=cover*.jpg matches every filename
that starts with "cover" followed by any number of characters
including 0), followed by ".jpg".

CoverArtworkFilePattern=cover?a.png matches every filename
that starts with "cover" followed by one arbitrary character,
followed by "a.png".

CoverArtworkFilePattern=cover.jpg matches the file called
"cover.jpg" and nothing else.

Assuming the current file is calles great_song.ogg with this
pattern:

CoverArtworkFilePattern=$.jpg;$.png;cover.jpg 

Gmu tries to find a file called great_song.jpg first, then 
(if the first one was not found) great_song.png and if even
that was not found, it tries to find cover.jpg. 


If no file is found that matches the given pattern, no cover
will be displayed.
Gmu will resize the image to fit on the screen if neccessary,
but using HUGE images should be avoided as it slows down
the cover loading and can even cause Gmu to run out of memory
if the dimensions of the image are very large (such as 
3000 x 2000 pixels which would need 17 MB in memory even
if the jpg file is much smaller in file size).

* CoverArtworkLarge

This option can be set to "yes" or "no". If set to "yes"
Gmu scales the cover image to fit the screen's width.
You can scroll up and down to see the whole image if its
height is larger than the screen height.
If the option is set to "no" (which is the default) Gmu
scales the image so that its width is at most half the
screen width. The actual width depends on the image 
proportions as Gmu keeps the aspect ratio of the image.

* SmallCoverArtworkAlignment

This option can be set to "left" or "right". If set to
"left" and large cover artwork is disabled, the cover 
artwork will be aligned on the left side and the text
on the right side. When set to "right" it is the other
way round. It is set to "right" by default.

* LoadEmbeddedCoverArtwork

This option can be set to "first", "last" or "no". If set
to "first" Gmu tries to load a cover image embedded in 
the audio file first and if that is not available Gmu 
tries to load an image file matching the given pattern.
If set to "last" Gmu will try to load a cover image from
file first and if none is found it tries to load an image
from the song meta data.
If set to "no" Gmu will not try to load a cover from the
meta data at all.
This option has no effect if EnableCoverArtwork is set to
"no".
LoadEmbeddedCoverArtwork is set to "first" by default.

* FileSystemCharset

This option can be either set to UTF-8 or ISO-8859-1. It
selects the charset of the file system. By default it is
set to UTF-8. If file names appear with weird characters
in Gmu's file browser you might want to try setting it
to ISO-8859-1.

* PlaylistSavePresets

This option is a semicolon separated list of .m3u 
file names. Up to ten file names can be specified here.
When saving a playlist in Gmu you can choose one filename
out of this list as the target file name.

* DefaultPlayMode

This option can be set to "continue", "repeatall", "repeat1",
"random" or "random+repeat".
In continue mode Gmu plays one track after another and stops
after playing the last track in the playlist.
In repeatall mode Gmu repeatedly plays all tracks in the 
playlist.
In repeat1 mode Gmu repeatedly plays the currently selected
track.
In random mode Gmu plays all tracks in the playlist in random
order.
In random+repeat mode Gmu repeatedly plays all tracks in the
playlist in random order.
No matter which play mode has been selected through this option,
you can still select another play mode from within Gmu. When
"RemeberSettings" is set to "yes" Gmu stores the selected play
mode on exit as the new "DefaultPlayMode".

* TimeDisplay

This option can be either set to "elapsed" or "remaining".
When set to "elapsed" Gmu shows the elapsed time of each
track by default, otherwise Gmu shows the remaining time
(if total track time is available). This option is set
to "elapsed" by default. No matter what this option is
set to, you can always toggle the time display from
within Gmu. The default keymapping for this is 
STICK_CLICK + VOL-.

* Scroll

This option can be set to "auto", "always or "never". 
If it is set to "auto" Gmu decides if it is neccessary to
scroll the title or not depending on the title's length
and the available display space. If set to "always" the 
title scrolls no matter if it fits into the display's 
width or not. If it is set to "never" the title never 
scrolls, even if it does not fit into the display's width.

* CPUCLock

This option can be set to either "default" or "reduced".
When set to "reduced" Gmu lowers the cpu frequency to
increase the battery lifetime. You might want to turn
of the display backlight to increase it further. To
do that you can either turn on hold manually or select
a display power off time-out to automatically turn of
the backlight after a given time. Look at the
"SecondsUntilBacklightPowerOff" option for details.

* BacklightPowerOnOnTrackChange

This option can be set to either "yes" or "no". When set
to "yes" that display backlight is turned on again each
time a new track starts. If "SecondsUntilBacklightPowerOff"
is set to 0 this option does not do anything.

* FileBrowserFoldersFirst

This option can be set to either "yes" or "no". When set
to "yes" all folder will be shown before the regular files.
When set to "no" all files are shown in alphabetical order.

* RememberSettings

This option can be set to either "yes" or "no". When set
to "yes" Gmu remembers settings such as the time display
setting and the selected play mode.

* Volume

This option can be set to any integer value from 0 to 21.
Higher values result in higher volumes. You don't need to
set this manually in the config file. Gmu remembers its
volume setting on exit when the "RememberSettings" option
is set to "yes".

* AutoPlayOnProgramStart

This option can be set to either "yes" or "no". When set
to "yes" Gmu starts playback right after the program has 
been started. You don't need to press a button unless the
playlist is empty.


Libraries used by Gmu (see "libs" directory for details):
---------------------------------------------------------

- SDL 1.2.9
- SDL_image 1.2.4
- SDL_gfx 2.0.13
- tremor 1.0.0
- libmikmod 3.1.11
- libmpegsound 0.8.2-fp1
- libmpcdec 1.2.6
- libFLAC 1.1.4
- AdPlug 2.1
- libjpeg and libpng (used by SDL_image)
