unmo3 (opensource) v0.5
-----------------------

26 Feb 2006

Copyright Laurent Clevy (lclevy()club-internet.fr)
This code is under GPLv2 license. Not for any commercial usage.

* Introduction

The piece of code has been written as a compagnion (validation code) of the
document "the unofficial MO3 specification".
See http://lclevy.free.fr/mo3
It is targeted to developpers or technical people, not for end users. It can be
used by IT/XM/S3M modules
specialists (tracker editor developper or modules players) to write a MO3 import
loader, or more generally 
to handle MO3 modules in any way.

The MO3 format has been created by Ian Luck (http://www.un4seen.com).
If you are looking for a good encoder and decoder (but without the source code)
and a good module player,
Ian's web site is the right place to go.  

* Features of unmo3 (opensource version)

Here they are:
- uncompress the MO3 header and samples with lossless compression
- able to save uncompressed header and samples
- able to extract mp3 and ogg compressed samples
- can display a channel of a given pattern into 2 forms
- as encoded inside MO3 file
- as it is usually appears in a tracker editor

This code has been written under Cygwin/IA32, should work under Linux/IA32, and
is supposed portable under other architectures.
It will be tested under Solaris/Ultrasparc.

If you want to run the auto tests, you have to download "unmo3_test.zip".

* Syntax

unmo3 [options] filename.mo3

available options are:

-a parselevel (from 1-4)
Display content of the MO3 file with more (-a 4) or less (-a 1) details

-d debuglevel (2)
Display some inner-working information

-v pattern_number voice_number
Display a channel of a given pattern as encoded inside MO3 module (technical
output)

-o 
Must be combined with -v. Display a given channel, but as seen in any tracker
editor (user friendly output).

-h header_output_filename
Write the uncompressed MO3 header into a file, for further study for example.

-s sample_number | all
Save one sample, or all samples of the MO3 module.

* Usage

- to build the executable

#make dep
#make

- demo
you can try 
#make demo
to see a 'demo'

- tests
#make test
for the auto tests : mainly to check the decompression routines
("unmo3_test.zip" archive is required).


* Not provided with this code

There is remaining work to do to interpret how all IT/XM and S3M effects and
samples/instruments parameters are stored AND interpreted by a player. But
80-90% of this work has been done in the documentation.

And maybe in a future release I'll write a .mod module writer.

Have fun,
Laurent

 PERMSSN    UID  GID    PACKED    SIZE  RATIO METHOD CRC     STAMP          NAME
---------- ----------- ------- ------- ------ ---------- ------------ -------------
[generic]                  167     273  61.2% -lh5- ad5f Feb 23  2006 unmo3/16to8.c
[generic]               185939  193266  96.2% -lh5- cae5 Jan  6  2006 unmo3/dannyelf_ll.mo3
[generic]                  269    1300  20.7% -lh5- 7a43 Feb 25  2006 unmo3/demo.sh
[generic]                  193     417  46.3% -lh5- f5bc Feb  5  2006 unmo3/endian_macros.h
[generic]                  402     655  61.4% -lh5- 4505 Aug  9  2007 unmo3/Makefile
[generic]                  790    2090  37.8% -lh5- 78f8 Feb 11  2006 unmo3/mo3_mp3.c
[generic]                   90     108  83.3% -lh5- b328 Feb 11  2006 unmo3/mo3_mp3.h
[generic]                 1819    4596  39.6% -lh5- 95fa Aug  9  2007 unmo3/mo3_mp3.o
[generic]                 2816   10842  26.0% -lh5- 14d7 Feb 26  2006 unmo3/mo3_parse.c
[generic]                  488    1365  35.8% -lh5- 1ede Feb 25  2006 unmo3/mo3_parse.h
[generic]                 6865   21384  32.1% -lh5- 5a67 Aug  9  2007 unmo3/mo3_parse.o
[generic]                 2920   12102  24.1% -lh5- 43e4 Feb 24  2006 unmo3/mo3_unpack.c
[generic]                  157     603  26.0% -lh5- f1e7 Feb 12  2006 unmo3/mo3_unpack.h
[generic]                 3606   13000  27.7% -lh5- 0d64 Aug  9  2007 unmo3/mo3_unpack.o
[generic]                 1332    2685  49.6% -lh5- 954b Feb 26  2006 unmo3/README.txt
[generic]                 8664   18992  45.6% -lh5- e1f7 Aug  9  2007 unmo3/sample024.dat
[generic]                17089   49751  34.3% -lh5- e74c Aug  9  2007 unmo3/unmo3
[generic]                 2189    6623  33.1% -lh5- 48fd Feb 25  2006 unmo3/unmo3.c
[generic]                 5113   12200  41.9% -lh5- 0833 Aug  9  2007 unmo3/unmo3.o
---------- ----------- ------- ------- ------ ---------- ------------ -------------
 Total        19 files  240908  352252  68.4%            Feb  8 17:29