This file documents version 2.0 of XModule, a music module processing utility. Copyright (C) 1993 by Bernardo Innocenti, Freeware. This file documents CrossModule version 2.0 2 Nov 93 Copyright (C) 1993 Bernardo Innocenti, Freeware. Overview of XModule ******************* The Amiga computer has standard file formats almost for everything. Graphics, text, animations, hypertext and so on are easily imported into any program that supports the given standards. But this isn't true for music. The music interchange file format defined by Electronic Arts (the old IFF SMUS) was too poor to be usable in high-quality music sequencers. Therefore, every music editor created its own proprietary module format, so that, for instance, you cannot load into ProTracker music written with Oktalyzer. XModule (pronounced Cross Module) is a music module conversion utility that tries to solve this problem. The project started in early 1993, as a friend of mine (Fabio), who wrote a lot of (good) music on Oktalyzer, needed ProTracker to obtain certain effects. He had an old PD conversion program called `Tracker', that worked only in particular conditions and was really bogus. So, I decided to contact the author and he let me have the source for Lit30000 (about $20). The original program has been completely rewritten from scratch, as the source was really poorly coded. At the moment, Oktalyzer, ProTracker, NoiseTracker and SoundTracker are the only supported formats, but I'm still developing XModule, so contact me if you want to see your favorite music editor added to this (short) list (see Author). Distribution ************ XModule is a Freeware program. This means that you (probably) have got it free and you should not ask any money for it if you decide to copy it to someone else. If, instead, someone sold you XModule for a price higher than the media used to store it on (i.e. $1 for a DD disk), tell him he should try to make money in a more honest way. I'm not asking you to pay for XModule because I never paied for a ShareWare program, so I felt that I had to pay somehow for my debt: this program is my gift to all the Amiga community. If you intend to include XModule in a commercial product, please at least send me a free copy. I would be honored to see one of my programs being part of a commercial package. Fred Fish, SAN and ADS are especially granted permission to include XModule into their PD libraries. Other PD libraries are welcome too. Fill free to distribute XModule to anybody, but, if you do, you must keep the documentation and the other distribution files together with the executable. The source code is not required, but I'm distributing it to let others take advantage of my work, so, if possible, try to include the source too. You can modify or improve XModule, but, please, return me the new source code, so I can put the new features in the next release of XModule. And, please, do not strip my name away from the documentation, the program source, or the executable. See Programmers. This product is provided as is without warranties of any kind: the author of this program cannot be held liable for any defects in the executable nor in the documentation or in any other files contained in this package. Any damage directly or indirectly caused by the use/misuse of XModule is the sole responsibility of the user her/him self. In other words: XModule never formatted my hard disk nor killed my dog, so I suppose it won't cause any damage to your system too, but, just in case, do not blame me if something nasty happens. Usage ***** XModule was originally written to work under KickStart 1.3, as Fabio is still running this obsolete operative system, but, as of XModule 2.0, XModule, sports a nice 2.0 style GUI, thus requiring OS 2.0. I hate programming on 1.3 and I wont do it any more. If you have still not upgraded to 2.0 you'll miss the chance to run XModule and lots of other wonderful programs. So what are you waiting for? XModule can be run either from the Shell or the Workbench. The full template in the standard Amiga format is: XModule FROM/A,TO/A,DESTMODE,OPTIMIZE/S,VERBOSE/S,QUIET/S where the FROM and TO keywords specifies the path of the source and destination files respectively. Specifying OPTIMIZE causes XModule to try to reduce the size of the module discarding useless information. For detailed information on module optimizations, consult the How it works section. VERBOSE and QUIET are quite self-explicative and DESTMODE can be one of the following (case does not matter): -NTRACKER or NT Noise/ProTracker 31 instruments module. This is the default. -PTRACKER or PT ProTracker 2.3 new 100 patterns module. XModule will automatically switch to PTRACKER whenever the converted module exceeds the 64 patterns limit. Warning: You must load such a module with ProTracker 2.3 or better in order to play/edit it. Older players will either refuse to load or turn the module into scratch dance. -STRACKER or ST SoundTracker 15 instrument module. This is pretty useless as SoundTracker is becoming quite rare. Do not save SoundTracker modules unless you really need it, because most players/editors will stop to support this format soon. SoundTracker format has no way to identify a module, therefore XModule will default to SoundTracker when the file matchs no other module format. -OKTALYZER or OK Oktalyzer V1.1 module For example, typing XModule Music:Modules/Studio3.okt RAM:Studio3.mod NTRACKER the program will read the Oktalyzer module Music:Modules/Studio3 and will save the NoiseTracker file to RAM:Mod.Studio3. Entering XModule ? will display some help on the command line options. 2.0 users will see a template and will be prompted for the arguments. Inserting another ? here will show the help text. Important: Command line parsing for 1.3 users is very limited because XModule cannot take advantage of the new KS2.0 powerful features. Therefore, parameters must be specified in the given order without the keyword name (e.g.: you cannot type FROM=Music:Modules/Tetriadis). How it works ************ XModule's module processing consists essentially in three steps: * The program first reads the source file and converts it into its internal format. All data is allocated into fast ram if available, as XModule does not play it. * If you specified OPTIMIZE, the module is then processed to save as much space as possible, removing useless data (if any): -Unused patterns Some formats (e.g.: Sound/Noise/ProTracker) store empty patterns in a module if a pattern with a greater number is used. For instance, a song using patterns 1, 2 and 5 will contain patterns 3 and 4 as well. Warning: if the unused patterns contain a part of a song that, say, is not yet finished, you will loose them. -Unused instruments Instruments that are never played are simply stripped away. -Sample data after a loop The part of an instrument following a loop is never played and is therefore discarded. -Instruments zero tails Long zero tails eat up memory and produce no sound. This optimization is performed only on loopless instruments, as a zero sequence inside a loop does make difference. XModule leaves At least two zero bytes to avoid the click produced by the speaker dropping its volume to zero too quickly. * And is at last the module is converted and saved to the required destination file format. If the module exceeds one of more of the destination format limitaitons, or makes use of features not implemented, some data will be stripped away to allow at least a partial conversion. See Limitations. Limitations *********** As a matter of fact, there are things that simply cannot be done because of the big differences between module formats. Following is a list of the internal limitations of each module player. If a module exceeds one of this values, it either won't be converted or will be truncated. Program Instr MaxPatt PattLen SongLen InstrLen -------------------------------------------------------- Oktalyzer 36 128 128 128 128K Sound Tracker 15 64 64 128 128K Noise Tracker 31 64 64 128 128K Pro Tracker 31 100 64 128 128K MED/OctaMED 63 256 256 256 ??? Where: #Instr is the maximum number of instruments, MaxPatt is the maximum number of patterns, PattLen is the maximum number of lines per pattern, SongLen is the maximum number of positions in a song, InstrLen is the maximum size of an instrument in bytes. Effects are the hardest thing to convert. While Speed and Volume are almost the same between module formats, some effects have no equivalents. Therefore, you will have to modify the score manually if you intend to convert a module keeping such effects. In addiction, some effects behave in different ways even if they claim to do the same thing. Last but not least, some players support synthetic or hybrid instruments. Fortunately, none of the module formats known by XModule implement such instruments, because I hardly can think how to implement a sample to synthetic conversion (any idea?). I used to like synthetic music, but it seems that all those great composers on the good old C64 have disappeared... Why have you musicians became so lazy? 8-( Known bugs ********** Murphy's laws states that nothing can be perfect, even computer programs. XModule is far from being perfect and I need your help to fix as much bugs as possible. If you discover a bug not reported in the list below, please, notify me. When you report a bug, state exactly what happens and indicate how to reproduce the conditions that generated the problem. Reports like `XModule sometimes crashes converting my favorite module' does not help at all. Include your name if you want to be credited in future XModule releases. If the program refuses to convert a module, mail it to me on a disk or upload it to a BBS I can reach and I'll try to fix the problem as soon as possible. TiTanic, whose address can be found in Author chapter, will do. If you want the disk back with the fixed version of XModule, send me a self-addressed envelope with enough Italian stamps or enough money for a reply. XModule has been tested on several machines running KickStart 2.0 and 3.0. XModule should work on any 68K family processor (tested on 68000, 68020 and 68040) and is Enforcer and Mungwall proof. Future plans ************ * OctaMED This will probably be the next format I'll work on. I think this is the best music editor available on the Amiga, but I haven't yet enough documentation on its file format to code a conversion routine. If you have such information, please contact me (see Author). * TeX Another format I would like to add is AmigaTeX. If you know TeX, you will surely be wondering what a typesetting program can be used for in music. Well, AmigaTeX is at the moment is the best implementation available on any computer of the TeX typesetting program, and its distribution includes MusicTeX, a powerful music language witch can output notes in a great standard staff notation. I know no other program on the Amiga that can print notes in such a fine quality (if you do, let me know!), so I think that many musicians should appreciate such an option. * Other module formats If you have documentation regarding a format you would like to see in a next release, please send it to me together with a couple of modules and, if possible, the program that created them. I'll try to implement the new format only if it is somewhat easy: it is very hard to convert, say, Future Composer to SoundTracker. Do not send a module without a text file describing its structure, as I'm not willing to spend my nights hex-dumping modules :). How to contact the author ************************* If you want to make me aware about your suggestions, bug reports, ideas or you want to send me a gift, a good module or some money :-), reach me in any of the following ways: *Mail Bernardo Innocenti Via Ventiquattro Maggio, 14 50129 - Firenze ITALY *FAX +39-55-8877615 Attn: Bernardo Innocenti Obj: Amiga/XModule *E-Mail (AmigaNet preferred ;-) FidoNet: Bernardo Innocenti 2:331/315 AmigaNet: Bernardo Innocenti 39:101/102 InterNet: Bernardo.Innocenti@f315.n331.z2.fidonet.org I will try to reply all my E-Mail, but I'm too lazy to reply old-style mail. Your suggestions will be taken into account unless they are `I want XModule to do ice tea'-style. Programmer notes **************** XModule has been written in C and compiled with SAS C version 6.3, Other compilers may require some changes to the source. The program is written respecting the Amiga multitasking system and following Commodore guidelines. All allocated resources will be (hopefully) freed before program termination. I wrote XModule with the goal in mind to keep the executable fast and small. This manual has been typeset using MakeInfo, a GNU PD utility ported to the Amiga by Reinhard Spisser and Sebastiano Vigna. I found that the time I saved writing one file for three was nearly compensated by the time I spent to learn how to operate MakeInfo. As I'm not that much skilled in using TeX and MakeInfo, you will probably find this document a bit silly in its typesetting style. Besides, English is not my first language (as you could have guessed) and I bet this document is full of grammar mistakes. If you intend to translate, improve or somewhat edit this document, please work on the supplied TexInfo file and then process it with the utilities supplied in the MakeGuide distribution. You can find MakeGuide in several PD libraries such as BBSs. Do not hesitate forwarding critics to my work, and, even better, advises on how to improve the program and the documentation. See Author. Credits ******* * Fabio Barzagli, for beta testing XModule, for the money he payed me for it and, last but not least, for letting me have (or steal?) his awesome modules! Drop this old & buggy Oktalyzer and keep on making good music, Fabio! * Gerardo Iula, for letting me have the source of Tracker (by paying :-( ). I assumed the money I paid covered the rights of modifying the original source and distributing modified versions of your program. Hope you won't worry about it, Gerardo. * Sebastiano Vigna & his buddy Reinhard Spisser, for porting GNU MakeInfo to the Amiga and for Reinhard's e-mail technical support. Please, continue developing this usefull (and hard to learn) tool. By the way, MakeInfo crashed my Amiga really bad a couple of times! Are my docs that boring? * The Amiga, for being the best computer in the world. :^) Commodore: Why don't you sell the Amiga project to someone serious as GVP or NewTek?