Mod Disassembler v 0.00

Introduction:

This program is used to dis-assemble a .mod file.  It creates a human
readable file describing everything in the .mod file.

It can optionally dump the samples in separate files in .wav or raw
format.  The wav and raw formats can be used by other sound editing
programs, and can easily be converted into other formats by conversion
utilities such as sox.

The dis-assembled mod file can be viewed or edited.  A companion program
modcomp can re-assemble the mod file.  (modcomp is not yet available as of
the date of this writing).  Mod_dis and modcomp can be used to compose
or modify mod files using any standard text editor, and can be used on
any machine, even those that cant play the files.

Mod_dis has been successfully compiled and tested on
	* unix - IRIX (SGI), SunOs 4.1.1 (Sun)
	* msdos

The source code is provided.  Other ports are encouraged.  Send me some
e-mail if you successfully port to a machine mot listed above.

The msdos executable is included for immediate use by those without
compilers.

The program is freely distributible provided the copyright notices
remain intact.

Usage: mod_dis [options] file.mod >file.dis
 options:
  -c n = set number of channels (aka voices, tracks) to n
  -i n = set number of instruments (aka samples) to n
      without -c and -i, mod_dis will attempt to figure out
      the file format
	Note: you normally do not need to set a -c or -i, however in
	      rare circumstances where a mod file is known to be good,
	      however has an unknown tag, you can try setting -c and -i
	      to dis-assemble.

  -np = do not disassemble patterns
  -ns = do not disassemble samples
	Note: by default patterns and samples are dis-assembled.  However,
 	      if you want to just see some header information, you can
	      specify -np -ns to give you a more compact file.

  -u  = unused patterns
      sometimes there are more patterns in the file than are actually used
      in the song.  By default these are ignored.  With the -u flag they are
      disassembled.

	Note: If you specify -np, you will not get any patterns dis-assembled.

  -v = verbose (another -v = more verbose)

	Note: Normally only errors are reported to the error output (your
	      terminal).  -v will also report some internal program
	      diagnostics as well as warnings.  -v -v will give you even
	      more.

	Note:	Additional comments may be placed in the disassembled
		output when you use -v.

  -f x = format of samples, values of x are:
         i=internal, s=raw samples (.sam),
         a=ascii (.txt), w=Microsoft wave (.wav)
         w1=.wav at 11025 Hz

	Note:	-ns will override the -f flag.
	Note:	-f i is the default, causing sample values to be
		dumped in a textual format at the end of the
		dis-assembled output.  You can redirect the
		sample dump to another file by specifying one
		of the other -f switches.
	Note:	The name of the external file can be controlled
		with the -p switch.
	Note:	If there are more than one instrument in the source
		file (very likely), you will get multiple sample
		files.
	Note:	The .sam format is simply a stream of unsigned 8-bit
		values.
	Note:	The .wav file is encoded to play back at 16574 samples/sec.,
		which corresponds to the standard C-3 playback rate.  If your
		sound card or wav editor doesnt like this rate, you can
		use the -f w1 flag to create a .wav file which will
		play back at the standard 11025 Hz, the tone of the
		resultant sample will be lowered somewhat when played
		back, mod_dis does not adjust do any re-sampling to
		compensate.
	Note:	Some features of the instruments are not placed in
		the sample files, like finetune, repeats, volume, etc...
		Hence playback software is not likely to reproduce
		the same sound as the sample when played as part of the
		.mod file.
		However the standard .wav file will include an INFO block
		which will encode these values into the "comment" field.
		The modcomp software will make use of this specially
		formatted comment.
	Note:	It is not likely any of the other major sound file
		formats will be supported.  Thre are many tools which
		can convert to/from these formats.  However,
		I will make an effort to support any standard format which
		allows you to specify finetune, names, and loop points
		so that all of the sample information can be encoded.

  -p prefix = prefix of sample output files (defaults to inst)
  -s suffix = suffix of sample output files (override format default)

	Note:	Use the forward slash (/) to separate directories instead
		of the backward slash, even in MSDOS.
	Note:	-p and -s are only useful when the format is not
		internal.
	Note:	The name of the files created will be
			<prefix>nn<suffix>
		where nn is the sample # (0 thru 31 in most .mod files).
	Note: 	When specifying a prefix, you can give a leading
		directory path.  Use the forward slash (/) to separate
		directories instead of the backward slash, even in MSDOS.
	Note:	Make sure you leave enough room to hold the extra 2 digits
		generated.  Some filesystems (namely MSDOS) have filename
		length limits.
	Note:	The suffix defaults as follows:
			-f w or -f w1	.wav
			-f s		.sam
			-f a		.txt

 file.mod = input file

	Note:	MED, S3M, STM, and other formats are not supported at
		this time.  This is mainly due to the lack of useable
		documentation on the file formats.  If you have some
		docs, you are welcomed to send them to me.

 file.dis = output file

	Note:	The output normally goes to the terminal unless you redirect
		it.
	Note:	Some mod files can generate dis-assemblies over 4 Mb. in
		size.  Use the -np and -ns, or -f options to limit the
		material written to the dis-assembly.
	Note:	Some text editors may fail to load very large dis-assemblies.
		Get a better editor.

Examples:

	mod_dis -v -f w -p abc abc.mod > abc.dis

	- dis-assemble abc.mod to abc.dis, samples will be written
	  to abc0.wav, abc1.wav, etc...
	
	mod_dis -np -ns abc.mod > abc.dis

	- dis-assemble only the header information of abc.mod

Diagnostics:

	Generally speaking, if you get error messages, its likely that
	the .mod file is not in the standard mod format.  If you dont
	understand the error message, look at the documentation for
	mod file formats and the source code.

	mod_dis is fairly pessimistic when it finds something that is
	not standard.  Use the "-v -v" flag to see all the warnings.
	Due to the wide variety of Mod trackers in use, there are
	many interpretations of the mod format specification in popular
	programs.

	If you are absolutely sure your mod file is standard and contains
	no errors, send me some e-mail and I'll check it out.  It could
	well be that the program has bugs.

Disassembled mod output:

	The output is created in such a way as so it can be fed as input
	to the companion program "modcomp" to re-compile it into a .mod
	file.  The language specification is still evolving so whem
	modcomp is released, it is likely that an updated mod_dis will
	be released.  The output format may be changed slightly.

	The sample info (length, repeat offset, repeat length) is printed
	out in bytes.  This is the most portable.  The dummy amiga
	word is not included, only the real sample information.
	This avoids any confusion about whether to add or subtract, and
	converting from words to bytes.  Let modcomp do the work for you.

	It is common practice to have sample names which have nothing to 
	do with the sample itself, sometimes even have a sample name
	for a sample with no data.  These are included in the disassembly.

	Sometimes non-ascii characters are used in sample names, presumably
	they display as interesting graphical characters on some machines.
	Those characters may or may not be put in the disassembly
	correctly, and may or may not display right in your text editor.
	It is an unportable use and is discouraged.  Future implementations
	may strip unportable characters.

	C++ style comments are sometimes placed in the output.  Modcomp
	will ignore everything from the // to the end-of-line.

Bugs:

	mod_dis does not like backslash (\) in the prefix or suffix (-p and
	-s command line options).  Use / when you mean \.
	
	mod_dis and modcomp will NOT play mod files - there are plenty
	of programs out there that do.

	Some mod formats not supported.  Without detailed documentation
	and standardization, they may never be supported.  Perhaps you can
	convert it to a standard mod format for dis-assembly.  I would like
	to see a standard format for unlimited sample size, 16 bit sample
	width, unlimited pattern length and table.  It ought to make better
	quality mods.

	mod_dis doesn't understand any of the compression techniques used
	to pack mod files.

	mod_dis will not operate on mod files in archives.

Files:
	The executable 'mod_dis.exe' is supplied, which is an executable
	for MSDOS.  For all other systems, you will need to compile from 
	the sources.  The MSDOS executable is built using Microsoft
	Visual C++ 1.0, using the large memory model.

	The sources consist of misc.c, mod_dis.c, mod_disv.c, wav.h,
	wav.c, misc.h, modcomp.h.  makefile.unx is provided for unix
	systems, to compile just "make -f makefile.unx".
	
	Text files
	are provided in msdos text format, you will need to convert them
	to unix format for best results.  You can use this shell command:

		sed 's/^M//' < dos_text_file > unix_text_file
		 (the ^M is a control-M, you may need to escape it with
		  a backslash or control-V depending on the shell)

	mod_dis.mak is provided to use by the Microsoft Visual C++ 1.0
	compiler.  Use the .mak as the project file in the IDE, or
	on the command line you can "nmake -f mod_dis.mak".  I think
	debugging is enabled in the project.

	A sample mod file and dis-assembly is given as a reference
	example (taken from the Sound-Site CD-ROM).  It was generated
	using the shell command

		mod_dis -v -v drave.mod > drave.rpt 2> drave.err

	

Porting:

	There is generous use of casts to avoid warnings emitted by
	the Microsoft compiler.

	There is a lot of kludgey code in MSDOS because "int" is 16 bits.

	The program prefers an ANSI compliant compiler, but does compile
	using the sunos compiler.  (__STDC__ not defined).  It has
	not been tested on a Solaris compiler, or the GNU compiler.

	Look in the misc.h file, you want to make sure the correct endian-ness
	is set.  Also there are a bunch of stuff that depends on __MSDOS__
	being set, which may or may not need to be set if you use a compiler
	other than Microsoft.

	There is a function "verify_port()" in mod_dis.c, look over the
	code and make sure it runs properly for the machine you port to.

	There seems to be 2 schools of thought on the interpretation of
	the repeat length.  The macro RPT_LENGTH_IS_INCR defines which
	way the program defaults to.  As currently set, repeat length
	is interpreted as including the amiga dummy word.

Testing:
	mod_dis is tested on approx 1000 mod files taken from the AMINET
	archive.  Of the 1000 files, there are approx 630 standard mod
 	format files (the rest predominently med, stm, packed).  Of the
	630 only 2 fail to disassemble.  I haven't looked in close detail
	at why.

	It has also been tested on 1365 mod files on the Sound-site 
	CD-ROM - only 2 files there fail to disassemble.  ( There are
	other failures but they are legitimate, they were on files
	in the bad and corrupt directories.) 

	The wav files generated have been tested on several .wav editors,
	and several .wav players playing on a SoundBlaster 16 on a PC
	running windows 3.1.  I've only found 1 program required the "-f w1"
	.wav files: Microsoft wavedit.exe - it didnt like the non-standard
	playback rate.

References:

	mod file format documentation, by THUNDER (kurtt@sfu.ca)
	Advanced Music Formats Document, By Jamal Hannah jamal@bronze.lcs.mit.edu
	mod format info, by Lars Hamre <larsha@lise.unit.no>
	RIFF WAVE (.WAV) file format, by Microsoft, transcribed by 
		Rob Ryan <ST802200@brownvm.brown.edu>


Special thanks to kurtt@sfu.ca for answering many questions on mod file format.


/* BEGIN DAVID LAI COPYRIGHT ********************************************* */
/*
(C) Copyright David Lai 1993, 1994.  All rights reserved.

The source code is copyright by David Lai, however it is freely
distributable and released for unrestricted use.  Users may copy or modify 
this source code without charge, provided all copyright
notices remain intact in all the source code.  Portions of the source code
copyright by their respective copyright holders and are covered
under different agreements, however the source code used has
specifically been marked distributable royalty-free.

You can do whatever you want with it, even charge money for it, if
you find a sucker willing to pay for it.  This is not shareware, the program
is not crippled in any way, do not send money.  You can e-mail comments
to the electronic mail address below, or fax to the fax number below.

If you add a feature thats useful, or do a new port, you can send
the context diffs to the e-mail address below.  I may include it in
subsequent releases.  Your code must specifically be marked
freely distributable, I will not include code marked otherwise.

THE SOURCE CODE IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING
THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.

The source code is provided with no support and without any obligation on
the part of David Lai to assist in its use, correction,
modification or enhancement.

DAVID LAI SHALL HAVE NO LIABILITY WITH RESPECT TO THE
INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS SOFTWARE
OR ANY PART THEREOF.

In no event will David Lai be liable for any lost revenue
or profits or other special, indirect and consequential damages, even if
David Lai has been advised of the possibility of such damages.  Etc, etc,
blah, blah, blah...

David Lai
1370 McKendrie St
San Jose, CA 95126
fax: 408-241-4615

lai%fastfood@daver.bungi.com

*/
/* END   DAVID LAI COPYRIGHT ********************************************* */
