
Modo - ultra simple mod player
==============================
powered by libmikmod
           libsidplay2 / resid
           libgme
           libtremor
           libym
           libsc68
           libmpg123


Supported formats
-----------------
Trackers: 669, IT, MED, MOD, MTM, S3M, STM and XM module format.
     C64: SID and MUS
Atari ST: YM, SNDH and SC68
  Others: SPC        (Snes)
          GYM & VGMz (Sega Master System / Sega Genesis aka Mega Drive / some derivats)
          GBS        (Gameboy)
          NSF & NSFe (Nes)
          AY         (Spectrum / Amstrad CPC)
          SAP        (Atari XL)
  Modern: Vorbis/Ogg
          MP3
  
For MED, only MMD0 and MMD1 without Synthsounds supported.
For SID, only PSID. No BASIC / RSID playback, player skips these (see C64 section for details why).


1. Browsing folders
-------------------

Select a folder and the player loops through all modules found in the selected
directory.

Keymapping in this mode:

 D-Pad left - Navigate through directories
D-Pad right - Navigate through directories
   D-Pad up - Navigate through files (hold to go faster)
 D-Pad down - Navigate through files (hold to go faster)
      Cross - Navigate through directories
   Triangle - Add/remove highlighted file/directory to playlist
     Square - Play all files in current directory
     Circle - Play all files in highlighted directory
              -OR-
              Start playlist
      Start - Toggle shuffle on/off
     Select - Exit player
   
If you press Square or Circle and nothing happens, then the player could not find
any modules in the choosen directory. Otherwise the player starts playback.

You can optional create a textfile 'modo.cfg' (put it in the directory where this
readme.txt is) which tells Modo to go to specific directory after first start.
You can also enable shuffle by default through the file. Please see modo.cfg.example
for more details.

2. Remote controls
-------------------

Remote control in directory browser:
    Forward - Navigate through files
   Backward - Navigate through files
       Play - Play all modules in highlighted directory
              -OR-
              Start playlist

Remote control in playback modes:
      Forward - Load and play next file in directory / playlist
     Backward - Load and play previous file in directory / playlist
 Hold Forward - Fast forward / seek forward
Hold Backward - Goto start of song / seek backward (depends on the music format)
         Play - Toggle pause
              

2. Playback modes
-----------------

The playback knows three modes: module mode, C64 format mode and Console mode.
There are few difference and some buttons have different meaning.

Playback timer
--------------

You can set the upper limit how long a song should play. If the song is shorter
it will not forced by this setting to play longer. Push the analog stick
up / down to adjust timer.

This is useful for some formats, eg if you listen to C64 tunes, but you have no
songlengths.txt available.

2.1 Playback mode: Module formats
---------------------------------

Before the player loads the file, it shows for about two second the mod title,
press now L or R to switch to next mod file. This way you can browse faster.
If you do nothing, the player starts loading & playing.

Keymapping in this mode:

           L - Load and play previous file in directory / playlist (hold to go faster)
           R - Load and play next file in directory / playlist (hold to go faster)
  D-Pad left - Seek backward
 D-Pad right - Seek forward
       Cross - Cycle through instruments / samples and comment section
  Hold Cross - Setup how often a endless module should loop, does only apply
               if the module loop. Default is to loop it three times. If a
               module does not loop, this setting does nothing. 
   Up / Down - Scroll messages
    Triangle - Add one minute to sleep timer (hold to more)
      Circle - Toggle volume boost
 Hold Circle - Abort sleep timer
      Square - Switch through speed / power saving
       Start - Abort playback and go back to directory browser
      Select - (un)pause

If a mod file supports instruments / samples / comment section and the author put
messages in more than one section, then you can press the cross button to cycle
through. In the right bottom corner you can see what section is currently displayed:
- "INS"  - Instruments
- "SMPL" - Samples
- "CMT"  - Comment

INS, SMPL, CMT are only displayed if you can use the cross button. If none is displayed
you already view the only available section.

The player shows little arrows in the right bottom corner if there are more messages
in a section than the PSP can display. Use the up / down button to scroll in that
case.
           
If the sleep timer reaches zero, the PSP will go in suspend mode.

The player knows five speed settings (power saving):

1 - Normal A (CPU ~ 166 MHz), everything is rendered
    This should be good for most module files out there.

2 - Drain my battery (CPU ~ 222 MHz), everything is rendered
    This should be enough reserve for even the biggest module files out there.

3 - Normal B (CPU ~ 166 MHz), songname and position is rendered
    This should be enough reserve for even the biggest module files out there.
    Not rendering samples saves CPU cycles for playback routines.
    
4 - Reduced (CPU ~ 80 MHz), songname and position is rendered
    This should be enough for many modules, but there are a
    files which will not play to well.
    
    NOTE: If a module begins to stutter in this mode, go back to menu via Start button.
          Do not press Square button again, otherwise you will most likely get stuck
          in 25Mhz forever (even using Home button then takes forever).
    
5 - Extreme (CPU ~ 25 MHz), nothing rendered on screen
    Still enough for most simpler module files, but it is not for sure that
    a module play well. You have to test.
    My PSP played for 8h nonstop in this mode (Screen off, 50% speaker volume),
    battery was full when started, after 8h it was a 56%.


Known limits:
* You can not select / play indiviual files directly. You have to go through all
  files in the directory during playback.
  


2.2 Playback mode: C64 formats (.sid / .mus)
--------------------------------------------

Keymapping in this mode:

           L - Load and play previous file in directory
           R - Load and play next file in directory
  D-Pad left - Select next subsong
 D-Pad right - Select previos subsong
       Cross - Toggle SID model for current file: 6581 and 8580
          Up - Toggle fast forward (x1.5) / normal play
        Down - Toggle song length database support on / off
    Triangle - Add one minute to sleep timer (hold to add more)
      Circle - Toggle volume boost
 Hold Circle - Abort sleep timer
      Square - Switch through speed / power saving (166 Mhz A, 222 Mhz, 166 Mhz B only)
       Start - Abort playback and go back to directory browser
      Select - (un)pause

* If you toggle the SID model via cross button, it is only valid until you load a new file.
  It's there for fun, so you can hear if there is difference.
* If a SID tune is marked with SID model "Unknown", the player defaults to 6581.
* If a SID tune is marked with Clock speed "Unknown", the player defaults to PAL clock speed.
* To permanent change the SID model and/or clock speed use "SIDEdit" (or a hex editor):
  <http://transbyte.org/SID/SIDedit_download.html> (scroll down for windows binary)
* If current file was not found in the HVSC database or if the database is disabled,
  the player uses silence detection to skip to next subsong / file. If there is
  silence for approx. 2.5s, the player skips. If the song loops without a pause
  you have to advance manually.

HVSC song length database support
---------------------------------
Copy from the DOCUMENTS folder in the HVSC archive the file "Songlengths.txt"
into the modo directory.

Why no BASIC / RSID support?
----------------------------
These tunes need complete simulation of C64 environment.

The library (libsidplay2) is fully capable of playing these tunes, but I didn't
manage to get full speed on the PSP. At 333 Mhz it is still not good enough.
I tried many things (lower sampling freq, no filter, crazy GCC flags...).
If you know a trick, you welcome.

I have only tested with SIDs from HVSC and MUSs from CGSC.


2.3 Playback mode: Console & Others (.spc, .vgm, .vgmz, .gym, .gbs, .nsf, .nsfe, .ay)
-------------------------------------------------------------------------------------

Keymapping in this mode:

           L - Load and play previous file in directory
           R - Load and play next file in directory
  D-Pad left - Select next subsong (if supported by format)
 D-Pad right - Select previos subsong (if supported by format)
       Cross - No function
          Up - Seek forward, it can take a moment, depending on the format
        Down - Toggle song length support on / off
    Triangle - Add one minute to sleep timer (hold to add more)
      Circle - Toggle volume boost
 Hold Circle - Abort sleep timer
      Square - Switch through speed / power saving
       Start - Abort playback and go back to directory browser
      Select - (un)pause

* If you disable song length support the song plays forever if it loops.
* GYM and Genesis-VGM's are fixed at 222Mhz, square button does not work if one
  of these is played.
* 8bit machines can go down to 80Mhz (Master-System-VGM's, Gameboy, Spectrum / CPC, NES, Atari)


2.4 Playback mode: Modern MP3 (.mp3) & Vorbis/Ogg (.ogg)
--------------------------------------------------------

Keymapping in this mode:

           L - Load and play previous file in directory
           R - Load and play next file in directory
          Up - Scroll lyric up or seek forward
        Down - Scroll lyric down or seek backward
        Left - Seek backward
       Right - Seek backward
    Triangle - Add one minute to sleep timer (hold to add more)
      Circle - Toggle volume boost
 Hold Circle - Abort sleep timer
      Square - Switch through speed / power saving
       Start - Abort playback and go back to directory browser
      Select - (un)pause
      
* If you embed the song lyric in a MP3 file the player will display it, use
  Up / Down to scroll through it. The lyric has to be in the id3v2 tag USLT
  (Unsynchronized lyric transcription). Max. 80 lines.
* Keep in mind that nearly all .ogg files use variable bitrate, so in 80Mhz mode
  it can happen that the player stutters for a few milliseconds if the bitrate
  gets to high (>250 kbits).
* Ogg files which contains the following features are not loaded:
  - Surround sound
  - Frequency < 11khz
  - Frequency > 44.1khz
  - Multiple streams inside
  
  
2.5 Playback mode: Atari ST (.ym, .sndh, .sc68)
-----------------------------------------------

Keymapping in this mode:

           L - Load and play previous file in directory
           R - Load and play next file in directory
          Up - Seek forward (.ym) or fast forward (.sndh, .sc68)
        Down - Seek backward (.ym) or toggle song length support on / off (.sndh, .sc68)
    Triangle - Add one minute to sleep timer (hold to add more)
      Circle - Toggle volume boost
 Hold Circle - Abort sleep timer
      Square - Switch through speed / power saving
       Start - Abort playback and go back to directory browser
      Select - (un)pause

* A very few .sndh can cause the player to hang. Just keep it in mind.
* Some .sndh/.sc68 may stutter @ 80Mhz.


3. Mini-Playlist support for formats which supports subsongs
------------------------------------------------------------

You can create a textfile to select which subsongs you want to hear. 

Lets just look an example: "Cowboy_Kids.sid" has 4 subsongs. You want to hear
song 2 and 4 only. You create a text file named "Cowboy_Kids.m3u" and place it
in the same directory where Cowboy_Kids.sid is.

Open the textfile and write:

Cowboy_Kids.sid,2
Cowboy_Kids.sid,4

Save the file. Thats all.

You can also override the song title and song length:

Cowboy_Kids.sid,2,Dadaaddaaaadaaaaaaaaaaa,0:30
Cowboy_Kids.sid,4,Cowboy Kidz forever,25:00

You can replay also one song of course, we want to hear subsong 2, 3 and then 2 again:

Cowboy_Kids.sid,2
Cowboy_Kids.sid,4
Cowboy_Kids.sid,2

The file name is not really necessary, you can leave it blank but keep the comma:

,2
,4
,2

It's also a way skip those subsongs which are just some funky beeps, like 
a pause jingle or something. Eg, tetris.gbs or sml2.gbs (super mario land 2) has
quite a few of them. Create a mini-playlist which just contains the reals songs
or songs you like.

Good luck!


4. Tech stuff
-------------
The player uses the following libraries for playback:
* libmikmod   - http://mikmod.raphnet.net/
* libsidplay2 - http://sidplay2.sourceforge.net/
* libgme      - http://slack.net/~ant/libs/audio.html
* libtremor   - http://www.xiph.org
* libym       - http://leonard.oxg.free.fr/
* libsc68     - http://sc68.atari.org/
* libmpg123   - http://www.mpg123.org/

Thanks to their authors!


Enjoy some great music!
 
 
This is the 10th release - Jun 16, 2008

<http://www.illogical.de>
Bastian Pflieger (wbb)
<wb@illogical.de>
Jun 16, 2008
