This manual documents XModule version 2.4 released on 8 Feb 94. Copyright (C) 1993-1994 by Bernardo Innocenti, Freely distributable, all rights reserved. Overview ******** The Amiga computer has standard file formats almost for everything. Graphics, text, animations, hypertext and many other data types are easily imported into any program that supports the given standards. But this isn't true for music. Too bad 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). Now XModule sports many other features, like module optimization, a nice user interface and complex module editing. This is why I like to call XModule a module processor. XModule stands to the music processing like ADPro or ImageFX stand to image processing (am I a bit immodest?). 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 an honest way. I'm not asking you to pay for XModule because I never paied for a ShareWare program, so I felt that I somehow had to pay for my debt: so I decided to distribute XModule as a free software, a little gift to all the Amiga community. Feel free to distribute XModule to your friends and enemies, but, if you do so, 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. Fred Fish, SAN and ADS are especially granted permission to include XModule into their PD libraries. Other PD libraries are welcome too. 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. 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. The reason is that I hate programming on 1.3 and I won't do it any more. If you haven't still 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 also takes advantage of some 3.0 features, like DataTypes and some user interface enhancements. Getting Started *************** You can run XModule either from the Shell or the Workbench. XModule accepts both command line and ToolTypes arguments. Workbench and Shell parameters are the same. The full AmigaDOS template is: XModule FROM/M,PUBSCREEN/K,PORTNAME/K The FROM keyword specifies optional modules to load at startup time. Specifying the PUBSCREEN keyword, followed by a public screen name allows to open XModule on an existing public screen. The given name should match exactly (case matters), or the system won't be able to find the desired screen. If the screen does not exist, a new public screen will open, cloning Workbench resolution and palette. Note that this behavior is not standard: Commodore commodities will abort if the required public screen does not exist. The default for this option is "Workbench" that opens XModule on the Workbench screen. PORTNAME will change the name of XModule's ARexx port. If a port with this name already exists, a number (eg: ".1") will be appended to the name, until a unique name is found. The port name defaults to "XMODULE". For more about the ARexx port, consult the ARexx Interface chapter. User Interface ************** Sorry, XModule's documentation is still incomplete. The next release will hopefully be more accurate. But wait! Do not suicide for such a reason: XModule is very easy to use, and you will be able to operate it even without this chapter. Panels ****** Sorry, XModule's documentation is still incomplete. The next release will hopefully be more accurate. I know, I know: I'm sooo lazy! I promise not to do it again. Format Conversion ***************** XModule can load and save modules created by other music editors. Following is a list of supported module formats: * Noise Tracker Noise/ProTracker 31 instruments module. This is the default. * ProTracker 2.3 ProTracker 2.3 new 100 patterns module. XModule will automatically switch to Pro Tracker 100 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. * Sound Tracker 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 ask you to confirm a SoundTracker module when the file being loaded matchs no other module format. * Oktalyzer V1.1 Oktalyzer is an old editor witch can play up to 8 channels by mixing instruments in real time. Some Oktalyzer effects (as H and L) are not converted because there are no equivalents in other music editors. As a matter of fact, there are things that simply cannot be done because of the big differences between module formats. Below is a list of the internal limitations of each module formats, when saving to a particular format, if the module exceeds one of this values, or makes use of features not implemented, some data will be stripped away to have at least a partial conversion. 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 music editors support synthetic or hybrid instruments. Fortunately, none of the module formats known by XModule implement such instruments, because I hardly can think a way 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-( Optimization ************ Module optimization is achieved by removing all unused data in a way that the module will sound the same as before. XModule can process a module to reduce its size as much as possible. It is generally a good idea to optimize a module before distributing it, but never while you are composing it, because you could easly loose some data that you didn't mean to discard. Do not expect to gain a lot optimizing a module: saving 20% of the total size is usually a very good result. * 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 a song contains a part that has not been finished yet and has not already been inserted in the position table, you will loose it. Warning: When a song is saved to Noise/ProTracker, patterns beyond the last used patterns are discarded regardless of this switch. This is due to a limitation of Noise/ProTracker module format. * Unused instruments A composer may decide to use an instrument and then change his mind, but forget to clear the instrument. In this case the module will contain an instrument that is never played. These instruments 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 nasty click produced by the speaker dropping its volume to zero too quickly. ARexx Interface *************** Sorry, XModule's documentation is still incomplete. The next release will hopefully be more accurate. Anyway, XModule's ARexx port is not fully operative at the moment, so you're not missing a great deal. 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. Glass Globe BBA, 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 which 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 FidoNet: Bernardo Innocenti 2:332/118.4 AmigaNet: Bernardo Innocenti 39:102/201.4 InterNet: --- Unavailable yet. Sorry! --- (Glass Globe BBS +39-577-959054) 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.51, 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 version 1.x, for the money he payed me for it and, last but not least, for letting me have (or steal?) his awesome modules! Keep on making good music, Fabio! * Alessandro Lombardi, for 2.x beta testing. Stop deleting files! * Erno Tuomainen for his wonderful Finnish BBS, for his kindness and for all the support he gave me. Are there any more top-rating modules to leech? * 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 useful (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?