3 @c $VER: XModule.texi 3.9 (21.1.97)
5 @c Remember to update these variables with each release
9 @setfilename XModule.guide
10 @settitle Documentation for XModule @value{prgver} (@value{prgdate})
11 @setchapternewpage odd
12 @c @set amiga_convert_nodes <-- this makes node names look like shit!
17 @subtitle @value{prgver} @today{}
18 @author by Bernardo Innocenti
20 Copyright @copyright{} 1993,94,95,96,97 by Bernardo Innocenti, all rights reserved.
24 @vskip 0pt plus 1filll
33 @node Top, Overview, , (dir)
36 This manual documents @value{prgname} version @value{prgver} released on
37 @w{@today{}}. It is formatted for viewing with @w{AmigaGuide V@value{agver}}.
39 Copyright @copyright{} 1993,94,95,96,97 by Bernardo Innocenti, all rights reserved.
42 If you haven't done it yet, please take a look to the release notes first.
43 @c does not work with latest GeekGadgets snapshot
44 @c @ref{Top, , release notes, README, README file}.
47 * Overview:: An overview of @value{prgname}.
48 * Distribution:: Licence & Disclaimer.
49 * Getting Started:: How to run @value{prgname}.
50 * User Interface:: General notes on the user interface.
52 * Panels:: Description of all @value{prgname} windows.
54 * Effects:: List of all the player effects.
55 * Format Conversion:: Description of module conversion with @value{prgname}.
56 * Optimization:: How to save memory and disk space with modules.
57 * ARexx Interface:: Every program should have one nowadays, doesn't it?
59 * Known Bugs:: Notes on things that are still not working@dots{}
60 * Future Plans:: What @value{prgname} should feature in the next releases.
61 * Programmers:: Notes on the C source and TexInfo documentation.
62 * XModule Format:: Description of the module format used by @value{prgname}.
64 * History:(History)Main. See what has changed since the last version of @value{prgname}. READ THIS!
66 * Credits:: Some people I wish to express my gratitude to.
67 * Author Info:: How to contact me.
77 @node Overview, Distribution, Top, Top
79 @cindex Overview of @value{prgname}
82 The Amiga computer has standard file formats for almost
83 everything. Graphics, text, animation, hypertext and many other
84 data types can be easily imported into any program that supports the
85 given standards, but this is not true for music. Too bad the music
86 interchange file format defined by Electronic Arts (the old IFF SMUS)
87 was too poor to be usable in high-quality music sequencers. Therefore,
88 every music editor created its own proprietary module format, so that,
89 for instance, you cannot load into ProTracker music written with
92 @dfn{@value{prgname}} (pronounced @dfn{Cross Module}) born as a simple
93 music module conversion utility that tried to solve this problem. The
94 project started in early 1993, as a friend of mine (FBY) needed to
95 convert his modules to ProTracker to perform some effects. He had an
96 old PD conversion utility called @dfn{Tracker} that worked only in
97 particular conditions and was very bogus. I decided to contact
98 the author and he let me have the source for Lit.30000 (about $20).
100 The original program has been completely rewritten from scratch, as the
101 source was poorly coded. Now @value{prgname} is a completely different
102 program, which sports many other features, as module optimization, a
103 nice user interface and complex module editing functions and it is
104 quickly turning into a full featured music editor.
106 This is why I like to call @value{prgname} a @dfn{module processor}. @value{prgname}
107 is to music processing what ADPro and ImageFX are to image processing.
111 @c ******************
113 @c ******************
115 @node Distribution, Getting Started, Overview, Top
116 @chapter Distribution
119 @value{prgname} is a @dfn{Freeware} program. This means that you (probably)
120 have got it free and @strong{you must not ask any money} if you
121 decide to copy it for someone else. If, instead, someone sold you
122 @value{prgname} for a price higher than the media used to store it on
123 (i.e.@:, $1 for a DD disk), tell him he should try making money honestly.
125 I am not asking you to pay for @value{prgname} because I hate the
126 Shareware concept. I use a lot of great PD software on my computer,
127 so I feel that I somehow have to pay my debt and I want to distribute
128 @value{prgname} as free software; a little gift to all the Amiga
129 community. Feel free to distribute @value{prgname} to your friends and
130 enemies, but, if you do so, you @strong{must} keep the documentation and
131 the other distribution files together with the executable. The source
132 code is not required, but I am distributing it to let others take advantage
133 of my work, so, if possible, try to also include the source.
135 Aminet and @w{Fred Fish} are especially granted permission to include
136 @value{prgname} into their PD libraries. Other PD libraries
139 If you intend to include @value{prgname} or parts of it in a commercial package,
140 please at least send me a free copy of the product. I would be honored
141 to see one of my programs being part of a commercial package.
143 You can modify or improve @value{prgname} (@pxref{Programmers}), only be
144 so kind to return the new source code to me, so I can put the new features
145 in the next release. @emph{Please}, do not strip my name from the
146 documentation, the program source, or the executable.
148 This product is provided @strong{as is}@footnote{In other words:
149 @value{prgname} never formatted my hard disk nor killed my dog, so I suppose
150 it won't cause any damage to your system either, but, just in case, do not
151 blame me if something nasty happens.}, without warranties of any kind: the
152 author of this program cannot be held liable for any defects in the executable
153 nor in the documentation or in any other files contained in this package.
154 Any damage directly or indirectly caused by the use/misuse of @value{prgname}
155 is the sole responsibility of the user her/him-self.
159 @c *******************
160 @c * Getting Started *
161 @c *******************
163 @node Getting Started, User Interface, Distribution, Top
164 @chapter Getting Started
167 @cindex Arguments, command line
168 @cindex Starting @value{prgname}
171 @value{prgname} requires Kickstart version 2.0 or greater. The reason is
172 that I hate programming on old 1.3 and I will not do it any more. If you
173 still have not upgraded to 2.0, you'll miss the chance to run
174 @value{prgname} and many other wonderful programs. So what are you
177 @value{prgname} also takes advantage of some 2.1 and 3.0 features, such as
178 DataTypes, AmigaGuide, Locale and many enhancements for the user
181 You can invoke @value{prgname} either from the Shell or Workbench.
182 @value{prgname} accepts both command line and ToolTypes arguments.
183 Workbench and Shell parameters are the same. The full AmigaDOS
188 @value{prgname} FROM/M,PUBSCREEN/K,PORTNAME/K,SETTINGS/K,
189 CX_POPUP/T,CX_POPKEY/K,CX_PRIORITY/K/N,
190 ICONXPOS/K/N,ICONYPOS/K/N,ICONNAME/K
195 The @code{FROM} keyword specifies modules to load at startup time.
196 Standard AmigaDOS wildcards can be used to match more than one module.
197 From Workbench, you multi-select module icons instead of specifying a
200 Specifying the @code{PUBSCREEN} keyword, followed by a public screen name,
201 allows you to open @value{prgname} on an existing public screen. The given
202 name should match exactly (case matters), or the system won't be able to
203 find the requested screen. If the requested screen does not exist, a new
204 public screen will be opened, cloning the resolution and colors of the default
205 public screen (usually the Workbench screen). Specifying an empty string
206 (@samp{""}) you will automatically pick the default public screen.
207 Note that this behavior is not standard: most commodities will abort if the
208 requested public screen does not exist. The default is to use or create a
209 public screen called @samp{@value{prgname}}.
211 @code{PORTNAME} will change the name of @value{prgname}'s ARexx port.
212 If a port with this name already exists, a number (eg: @samp{.1}) will be
213 appended to the name, until a unique name is found. You can disable the ARexx
214 port providing an empty string (eg: @samp{""}) for @code{PORTNAME}. The port name
215 defaults to @samp{XMODULE}. For more information about the ARexx port, see
216 @ref{ARexx Interface}.
218 @code{SETTINGS} causes @value{prgname} to use the given settings file instead
219 of looking for the default preferences file.
221 @code{CX_POPUP} controls wether the user interface should show when
222 @value{prgname} starts. The default is to always show the interface. When used
223 from the shell, @code{CX_POPUP} acts as a toggle, turning off the user interface.
224 From Workbench, you specify @code{CX_POPUP=YES} or @code{CX_POPUP=NO} to show and
225 hide the user interface, respectively. @xref{Commodities}.
227 @code{CX_POPKEY} specifies the hotkey that pops up @value{prgname}'s user interface.
228 The given string should be a valid Commodities input description. You can disable
229 @value{prgname}'s Commodities broker specifying an empty string (eg: @samp{""})
230 for @code{CX_POPUP}. The default is @samp{ctrl alt x}. @xref{Commodities}.
232 @code{CX_PRIORITY} sets the Commodities priority for the @value{prgname} broker.
233 An high priority causes the input to be processed by @value{prgname} before other
234 commodities with a lower priority. The priority ranges from +127 to -128.
235 The default priority is 0. @xref{Commodities}.
237 @code{ICONXPOS} specifies the X position of @value{prgname}'s AppIcon. The default is
238 to let Workbench choose a suitable position for the icon.
240 @code{ICONYPOS} specifies the Y position of @value{prgname}'s AppIcon. The default is
241 to let Workbench choose a suitable position for the icon.
243 @code{ICONNAME} specifies the name of @value{prgname}'s AppIcon. The default name is
244 @samp{@value{prgname}}.
247 @c ******************
248 @c * User Interface *
249 @c ******************
251 @node User Interface, Panels, Getting Started, Top
252 @chapter User Interface
253 @cindex User Interface
256 @value{prgname}'s GUI follows Commodore's 2.0 style guidelines. Under Kickstart 3.0
257 and above, @value{prgname} takes advantage of new OS capabilities to enhance some
270 @c ******************
271 @c * Windows Layout *
272 @c ******************
274 @node Windows Layout, Shortcut Keys, , User Interface
275 @section Windows Layout
276 @cindex Windows Layout
277 @cindex Layout, of Windows
278 @cindex Font Sensivity
280 Gadget and menu layout is font sensitive, but using some fancy fonts could
281 result in a somewhat weird look. If you are using a very big font and a
282 window becomes too big to fit in the screen, @file{topaz/8} will be used as
283 a fallback for rendering that window.
285 Most windows are completely scalable and their contents will adapt to the
286 size you choose, just like a MUI application. But @value{prgname} does
287 not use MUI, so I had to do all the GUI engine myself, and it was quite an
288 hard work for me. @value{prgname} GUI is not as nice as can be MUI, but
289 it's much faster and requires much less memory.
291 When you close a window, it will remember its position and size when you
292 open it again. The same is true for window zooming operations.
294 @value{prgname} will also try to make the active window visible by
295 scrolling the screen automatically. This feature comes handy if you use
296 a virtual screen which is wider and/or taller than the default.
299 @c ******************
301 @c ******************
303 @node Shortcut Keys, On-Line Help, Windows Layout, User Interface
304 @section Shortcut Keys
305 @cindex Shortcut Keys
306 @cindex Keys, Shortcuts
309 In all windows, the following shortcut keys are active:
313 Close the active window. Does not work with ToolBox window, as it would
314 make it too easy to accidentally exit the program.
317 Bring up AmigaGuide on-line help. @xref{On-Line Help}.
320 Cycles forward through string and numeric gadgets within the active
321 window. @kbd{SHIFT-TAB} will cycle backwards. @kbd{TAB} also
322 activates the first string or numeric gadget if none is selected.
325 Activates the next @value{prgname} window. @kbd{ALT-SHIFT-TAB}
326 activates the previous window.
329 Activate the first string or numeric gadget in the active window.
332 Move up and down in a viewlist whenever the active window contains one.
333 @kbd{SHIFT-Cursor} moves 5 items up/down. @kbd{ALT-Cursor} moves to the
334 top or to the bottom of the list. This shortcut requires at least
338 In addition, gadgets with underscored characters in labels, can be
339 operated hitting the highlighted key. @kbd{SHIFT-key} acts the opposite
340 of the unshifted key (sliders are decremented by one, cycle gadgets will
341 cycle backwards, etc.@:). Keyboard shortcuts will not work for all gadget
342 kinds under Kickstart 2.0.
346 @c ******************
348 @c ******************
350 @node On-Line Help, Localization, Shortcut Keys, User Interface
351 @section On-Line Help
353 @cindex Help, On-Line
355 This feature requires @file{amigaguide.library}, which is distributed
356 with Workbench version 2.1 and up, and @file{@value{prgname}.guide}
357 located in the current directory or in the same directory of
358 @value{prgname}'s executable or in the @file{HELP:language/} directory,
359 where @samp{language} is any of your Locale preferred languages.
360 AmigaGuide(TM) is also available as a freely distributable package
363 To get help on a gadget, press @key{HELP} while the mouse pointer is
364 over the gadget. To get help on a string gadget, activate it and
365 press @key{HELP}. Hitting @key{HELP} while the mouse isn't over a
366 gadget, will give you help on the active window.
368 To get help on a menu item, hilight the item and press @key{HELP} while
369 keeping the right mouse button pressed.
373 @c ******************
375 @c ******************
377 @node Localization, Commodities, On-Line Help, User Interface
378 @section Localization
380 @cindex Language selection
381 @cindex Writing a new language catalog
383 Localization requires @file{locale.library}, which is distributed
384 with Workbench version 2.1 and up, and the catalog file
385 @file{@value{prgname}.catalog} located in the same directory of
386 @value{prgname}'s executable or in the @file{LOCALE:catalogs/language/}
387 directory, where @samp{langage} is is any of your Locale preferred
390 If you speak a language for which a catalog isn't yet available, please
391 consider writing it yourself and then send it to me, so it will be
392 included in the next release of @value{prgname}. Look at the empty
393 catalog translation file @file{Empty.ct} in the @file{Catalogs/}.
394 It can be used to create new catalog descriptions for @value{prgname}.
395 Then, use a tool like @cite{FlexCat}, @cite{KitKat} or @cite{CatComp}
396 to compile it into a catalog file. Please read the @cite{HowToTranslate.doc}
397 before you start translating: it contains many tips and suggestions
398 which may come useful.
401 @c ******************
403 @c ******************
405 @node Commodities, Default Icons, Localization, User Interface
406 @section Commodities support
407 @cindex Break signals
409 @value{prgname} is a Commodity and can be controlled by the
410 Commodities Exchange program.
412 @value{prgname} will pop up when its hotkey is typed; the main window
413 will activate and the screen will move to the front. If
414 @value{prgname}'s interface is hidden, it will be revealed.
416 The user interface can be hidden with the Exchange program.
417 When the user interface is hidden, the only ways you have to still
418 operate @value{prgname} is through the ARexx port or the AppIcon.
420 You can also control @value{prgname} by sending the following
421 signals to its process:
425 Quit @value{prgname}.
428 Disable the Commodities broker (equivalent to selecting @code{Inactive}
429 with Commodities Exchange).
432 Enable the Commodities broker (equivalent to selecting @code{Active}
433 with Commodities Exchange).
436 Deiconify @value{prgname} (equivalent to double-clicking on the AppIcon).
441 @c ******************
443 @c ******************
445 @node Default Icons, , Commodities, User Interface
446 @section Default Icons
447 @cindex Icons, changing defaults
448 @cindex def_Instrument
451 When @value{prgname} creates an icon for a file, it looks for the user
452 preferred icon for the type of data being saved.
454 The template icons can be placed in the @file{Icons} drawer which is
455 located in the same drawer where the @value{prgname} executable resides.
456 @value{prgname} will also look for its icons in the @file{ENV:Sys/}
457 directory. If you choose to use @file{ENV:Sys/}, you will probably want
458 to store the icons in @file{ENVARC:Sys/} to have them copied automatically
459 to @file{ENV:Sys/} every time the system boots up.
461 Template icons should be only of type @dfn{Project}. When @value{prgname}
462 does not find a template icon, it uses the default Project icon instead.
464 Whenever the default icon does not have its own default tool, it will be
465 set to @value{prgname}'s executable.
467 The following default icons are supported:
470 @item @file{def_Module}
471 @item @file{def_Instrument}
480 @node Panels, Effects, User Interface, Top
485 Sorry, XModule's documentation is still incomplete. Not all
486 the following links are finished.
501 @c ******************
502 @c * ToolBox Window *
503 @c ******************
505 @node ToolBox, Pattern Editor, , Panels
506 @section ToolBox Window
512 Opens or activates the @ref{Pattern Editor} window.
514 @item Instruments (I)
515 Opens or activates the @ref{Instruments} window.
518 Opens or activates the @ref{Sequence} editor.
521 Opens or activates the @ref{Song Information} window.
523 @item Optimization (O)
524 Opens or activates the @ref{Optimization} window.
527 This option has not been implemented yet.
532 @subsection Project Menu
536 Creates a new empty song.
539 Opens a song over the current one. A file requester will be put
540 up to let you choose the module. The file requester is asynchronous,
541 so you can continue operating @value{prgname} while keeping the requester
542 open. You can use multiselection to open several modules at once.
545 Saves the current song to the same path it was loaded from.
547 @item Save As (Amiga-A)
548 Opens a file requester and saves the current song to the selected file
551 @item Clear Module (Amiga-K)
552 Opens or activates the @ref{Clear Song} panel.
554 @item About (Amiga-?)
555 Brings up a requester showing various information on @value{prgname}.
558 Shows the main node of the AmigaGuide on-line help. @xref{On-Line Help}.
560 @item Iconify (Amiga-I)
561 Closes all open windows and screens and puts an AppIcon on the Workbench.
562 You can De-Iconify @value{prgname} by double clicking on the icon or by
563 using @code{Show Interface} in the Commodities Exchange program.
567 Quits @value{prgname}. A requester will ask if you are sure if the
568 @code{Settings/Confirm Exit} menu item is checked.
573 @subsection Settings Menu
577 Opens or activates the @ref{Save Format} window.
580 Opens or activates the @ref{User Interface} window.
583 When this menu item is checked, @value{prgname} will automatically add
584 an icon to the files it saves. @xref{Default Icons}.
586 @item Confirm Overwrite?
587 When this menu item is checked, @value{prgname} will ask before
588 overwriting an existing file when saving something.
591 When this menu item is checked, @value{prgname} will ask
592 if you are really sure before quitting.
595 When this menu item is checked, @value{prgname} will be output more
596 detailed information on various operations.
599 Opens a file requester asking for an XModule preferences file. The
600 changes will take place immediately.
603 Saves the current settings to @file{PROGDIR:XModule.prefs}, which
604 is where preferences are looked for first.
606 @item Save Settings As
607 Opens a file requester and saves the current settings to the selected
613 @c ******************
614 @c * Pattern Editor *
615 @c ******************
617 @node Pattern Editor, Instruments, ToolBox, Panels
618 @section Pattern Editor Window
619 @cindex Pattern Editor Window
624 The pattern editor is used to actually edit notes into your song.
625 A song is made up of several patterns which are played one after the
626 other following the order defined in the @ref{Sequence} editor.
628 A pattern is subdivided into @dfn{tracks}. Each track is made of
629 several note slots. Each note slot has four basic fields: the
630 actual note, the number of the instrument used to play this note,
631 a field for the @dfn{effect} (also called @dfn{command}) and a
632 @dfn{value} for the effect, the meaning of which depends from
633 the type of effect (@pxref{Effects}). A @dfn{line} is an horizontal
634 set of note slots. The lines are numbered starting from 0 (line
635 numbers are displayed in the leftmost column of the pattern editor).
637 A pattern can have 1 to 32 tracks. The more the tracks, the more the
638 notes that can be played at the same time. When @value{prgname} plays
639 a pattern, it reads the lines one by one, playing all the notes and
640 executing all the effects as soon as it encounters them. A pattern
641 line can be imagined as one sixteenth of a beat when the pattern is
642 played at the default speed and tempo.
644 A pattern row looks like this:
650 | | |+---- Effect Value
651 | | +----- Effect Command
652 | +------- Instrument
656 Notes are shown in anglosaxon notation, followed by the octave number.
657 So @code{C-2} is a second octave @code{DO} in classic notation and
658 @code{A#3} is a third octave diesis @code{LA}. There are 5 octaves
659 numbered from 0 to 4; a @code{C-2} note is twice the frequency of a
660 @code{C-1}, and it's instrument will be played at double speed.
662 The duration of the note is determined by the space left from one note
663 to the next. For example, if a note is immediately followed by another
664 note on the same track, it's duration will be one sixteenth of a beat
665 at four quarters. If two notes are put one at line n and the other
666 at line n+4 (leaving three blank spaces between), the duration of the
667 first note will be exactly one quarter.
669 Calculating the duration of a note can become trickier when weird
670 combinations of speed and tempo are used. Also, notes can be
671 associated to instruments which have an endless loop (like a flute)
672 or to instruments that only last for a short time and then stop
673 (like a snare drum). In the latter case, the duration of a note could
674 be shorter than it's distance from the following note. Experience
675 will help understanding these simple rules.
678 @subsection Editor Keys
685 Move the cursor one position towards the respective direction. Keeping
686 cursor keys pressed will repeat the movement until the key is released.
688 Cursor keys in combination with the @kbd{SHIFT} key will move the cursor
689 a whole page up/down or one track left/right, keeping it on the same
692 Cursor keys in combination with the @kbd{ALT} key will move the cursor
693 to the top/bottom/leftmost/rightmost position.
695 Cursor keys in combination with the @kbd{CTRL} key will scroll the view
696 without moving the cursor. This is useful to reveal something without
697 having to reposition the cursor.
699 @strong{NOTE:} You can adjust the repeat speed and delay with the
700 @cite{Input} system preferences.
703 Move to the note column of the next track. Pressing @kbd{TAB} on the last
704 track, will bring the cursor to the first track. @kbd{SHIFT-TAB} moves
708 Delete the field under the cursor. @kbd{SHIFT-DEL} kills all the note slot
709 (note, effect and value).
714 @subsection Project Menu
717 @item Open Pattern (Amiga-O)
718 Opens a file requester where you can select a pattern to be loaded in
719 place of the current one.
721 @item Save Pattern (Amiga-S)
722 Saves the current pattern to a file with the same name of the pattern.
723 If the pattern has no name, a file requester will open.
725 @item Save Pattern As (Amiga-A)
726 Opens a file requester where you can select the file and path name where
727 the current pattern will be saved to.
732 @subsection Edit Menu
736 Toggles mark mode in the pattern editor.
739 Copies the currently marked region to the clipboard and erases it from
743 Copies the currently marked region to the clipboard.
745 @item Paste (Amiga-V)
746 Gets the last pattern stored into the clipboard and pastes it in the
747 current pattern starting at the current cursor position.
749 @item Erase (Amiga-E)
750 Clears the currently marked region.
753 Restores the pattern to the state it was before the last
757 Remakes the last change undone with the Undo function.
762 @c ******************
764 @c ******************
766 @node Instruments, Song Information, Pattern Editor, Panels
767 @section Instruments Editor Window
768 @cindex Instruments Editor Window
773 @item Instruments List (Cursor up/down)
774 This list shows all the instruments of a song. The leftmost column
775 is the instrument number (hexadecimal), followed by its name.
776 Some musicians usually use the instrument names to include short
777 texts inside the modules they distribute. Picking an instrument
778 from this list will set it as the current instrument. An empty
779 instrument slot with no name will have the word @samp{--empty--}
780 in place of its name.
782 @item Instrument Name (RETURN or TAB)
783 (The string gadget immediately below the Instruments list). Allows
784 editing the name of the currently selected instrument.
787 Default instrument volume. Ranges from 0 (mute) to 64 (maximum
791 Sets the instrument fine tune. 0 is the default tuning. Negative
792 values cause the instrument to be played at a slightly lower
793 frequency. Positive values cause the instrument to be played at
794 a slightly higher frequency.
797 Displays the instrument lenght in bytes.
800 This function has not yet been implemented.
803 Opens or activates the @ref{Sample Editor} panel.
808 @subsection Instruments Menu
812 Loads an instrument in the current intrument slot. A file requester
813 will be put up to let you choose the instrument. The file requester
814 is asynchronous, so you can continue operating @value{prgname} while
815 keeping the requester open.
817 Saves the current instrument to a file with its current name.
819 @item SaveAs (Amiga-A)
820 Opens a file requester and saves the current instrument to the
821 selected file name and path.
823 @item Remap (Amiga-R)
824 Remaps all the instruments removing all empty slots between them.
825 The song patterns are updated to keep the correct instruments.
826 This function is useful to save a module to a format which has a
827 limited number of instruments, like @ref{SoundTracker}.
832 @c ********************
833 @c * Song Information *
834 @c ********************
836 @node Song Information, Sequence, Instruments, Panels
837 @section Song Information Window
838 @cindex Song Information Window
844 Creates a new module and makes it the current module.
847 Deletes the current module from memory. If the module has been
848 modified since last saving, a requester will give you the chance
849 to abort the operation.
852 Opens a song over the current one. A file requester will be put
853 up to let you choose the module. The file requester is asynchronous,
854 so you can continue operating @value{prgname} while keeping the requester
855 open. You can use multiselection to open several modules at once.
856 This gadget behaves exactly like the @code{Open} menu item in the @ref{ToolBox}
860 Saves the current song to the same path it was loaded from.
861 This gadget behaves exactly like the @code{Save} menu item in the @ref{ToolBox}
865 Displays the name of the current song. You can use any character in the song
866 name, but keep in mind that the name you type will be used by default as the
867 filename for the song, so be careful with special characters such as @samp{/}
871 Displays the author of the current song. @value{prgname} tries to guess the
872 author when it loads a module whose format has no direct support for embedded
873 author name. @value{prgname} scans the instruments names looking for a line
874 beginning with a pound sign (@samp{#}). This convention started with
875 @cite{IntuiTracker}, an old module player for the Amiga. If the author name
876 can't still be found, @value{prgname} looks again for an occurence of @samp{by },
877 @samp{by:} or @samp{(c)}, which is usually followed by the author name.
878 The author name is ignored when saving to a format which does not support
879 embedding the author name.
882 Displays the default tempo for the current song. Valid range is 32-255, the
883 dafult is 125. The default tempo is used when the song starts playing and can
884 be overridden by the Set Tempo command. @xref{Effects}.
887 Displays the default speed for the current song. Valid range is 1-31, the
888 dafult is 6. The default speed is used when the song starts playing and can
889 be overridden by the Set Speed command. @xref{Effects}.
892 Displays the position where playback will continue once the song end has
893 been reached. The restart position is lost when saving to formats which
897 Displays the total number of patterns in the song.
900 Displays the maximum number of tracks in the song.
903 Displays the number of positions in the song sequence.
905 @item Total Module Size
906 Shows an approximation of the memory used up by the song and its data.
907 This value will usually be similar to the file size.
909 @item Total Instruments Size
910 Shows an approximation of the memory used by all the instruments of the
914 @subsection Song Menu
917 @item Merge Songs (Amiga-M)
919 @item Join Songs (Amiga-J)
921 @item Clear (Amiga-K)
931 @node Sequence, Save Format, Song Information, Panels
932 @section Sequence Editor Window
933 @cindex Sequence Editor Window
937 Had no time to write it, sorry. ;-)
941 Had no time to write it, sorry. ;-)
949 @node Save Format, Clear Song, Sequence, Panels
950 @section Save Format Window
951 @cindex Save Format Window
955 Had no time to write it, sorry. ;-)
959 Had no time to write it, sorry. ;-)
967 @node Clear Song, Sample Editor, Save Format, Panels
968 @section Clear Song Window
972 Had no time to write it, sorry. ;-)
976 Had no time to write it, sorry. ;-)
984 @node Sample Editor, , Clear Song, Panels
985 @section Sample Editor Window
989 Had no time to write it, sorry. ;-)
993 Had no time to write it, sorry. ;-)
997 @c *********************
999 @c *********************
1001 @node Effects, Format Conversion, Panels, Top
1006 Had no time to write it, sorry. ;-)
1010 @c *********************
1011 @c * Format Conversion *
1012 @c *********************
1014 @node Format Conversion, Optimization, Effects, Top
1015 @chapter Format Conversion
1016 @cindex Format Conversion
1017 @cindex Module Formats
1019 @value{prgname} can load and save modules created by other
1020 music editors. The following is a list of all supported module formats:
1023 * XModule: XModule Format.
1039 As a matter of fact, there are things that simply cannot be done
1040 because of the big differences between different module formats.
1041 Below is a list of the internal limitations of each module format.
1042 When you save to a particular format and the module exceeds one of
1043 these values, or makes use of features not implemented, some data
1044 will be stripped away to produce at least a partial conversion.
1048 @c Is there a better way to make a table like this?
1050 Program Instr MaxPatt PattLen SongLen InstrLen Tracks
1051 ---------------------------------------------------------------
1052 Oktalyzer 36 128 128 128 128K 4
1053 SoundTracker 15 64 64 128 64K 4
1054 NoiseTracker 31 64 64 128 64K 4
1055 StarTrekker 31 64 64 128 64K 4/8
1056 ProTracker 31 100 64 128 64K 4
1057 Fast Tracker I 31 100 64 128 64K 4/6/8
1058 MED/OctaMED 63 256 256 256 No Limit 1-64
1060 XModule 63 256 32768 32768 No Limit 1-32
1064 #Instr is the maximum number of instruments,
1065 MaxPatt is the maximum number of patterns,
1066 PattLen is the maximum number of lines per pattern,
1067 SongLen is the maximum number of positions in a song,
1068 InstrLen is the maximum size of an instrument in bytes,
1069 Tracks is the maximum number of tracks in a pattern.
1073 Effects are the hardest thing to convert. While Speed and Volume
1074 are almost the same between different music editors, some effects (such as
1075 Oktalyzer's H and L) cannot be converted because there are no equivalents in
1076 other music editors. Therefore, you will have to modify the score manually
1077 if you intend to convert a module while keeping such effects. In addition,
1078 some effects behave in different ways even if they claim to do the same
1081 Last but not least, some music editors support synthetic or hybrid
1082 instruments. @value{prgname} does not convert such instruments,
1083 because I can hardly think of a way to implement a sample to synth
1084 conversion (any ideas?). I used to like synthetic music, but it
1085 seems that all those great composers on the good old C64 have
1086 vanished@dots{} Why have you musicians become so lazy? 8-(
1090 @c ******************
1092 @c ******************
1094 @node NoiseTracker, ProTracker, , Format Conversion
1095 @section NoiseTracker
1096 @cindex NoiseTracker
1098 Noise/ProTracker 31 instruments module. This is absolutely the
1099 most common module format; almost any music editor and module
1100 player (even the crap ones for the PeeCee) understand this
1101 format. Noise/ProTracker modules can be recognized by looking for
1102 the ID @samp{M.K.} at offset 1080 ($438 in hex) in the file.
1103 Andrew Scott, the author of MidiMod, says that @samp{M.K.} are
1104 the initials of Mahoney & Kaktus, the two guys who designed this
1105 format. Peter Kunath, the author of DeliTracker, points out that
1106 @samp{M.K.} are more likely to be the initials of Michael Kleps
1109 Unfortunately, there is an infinite variety of standard
1110 NoiseTracker modules with fancy IDs. In fact, most tracker
1111 clones put their own ID instead of the standard one even if
1112 there is no reason to do it. If you find such a module, try
1113 replacing the ID with an hex editor and you will be able to
1114 load it most of the times.
1118 @c ******************
1120 @c ******************
1122 @node ProTracker, SoundTracker, NoiseTracker, Format Conversion
1123 @section ProTracker 100 Patterns
1126 @cindex 100 Patterns ProTracker modules
1128 @value{prgname} will automatically switch to @code{ProTracker 100}
1129 whenever the module being saved exceeds the 64 patterns limit of
1130 NoiseTracker modules.
1131 Modules with more than 64 patterns have the ID @samp{M!K!} instead
1132 of the standard Noise/ProTracker ID (@samp{M.K.}).
1134 @strong{Note:} You @emph{must} load such a module with ProTracker 2.3 or
1135 better in order to play/edit it. Older players will either refuse
1136 to load it or they'll turn the module into scratch dance.
1138 ProTracker 3.0+ has a completely new file format, but this isn't
1139 supported yet, as I've never seen a module of this kind yet.
1143 @c ******************
1145 @c ******************
1147 @node SoundTracker, StarTrekker, ProTracker, Format Conversion
1148 @section SoundTracker 15 Instruments
1149 @cindex SoundTracker
1151 This format is pretty useless as SoundTracker is becoming really rare.
1152 Do not save SoundTracker modules unless you really need to, because
1153 most players/editors will stop supporting this format very soon.
1154 There is no way to identify a SoundTracker module, therefore
1155 @value{prgname} will ask you to confirm a SoundTracker module when
1156 the file being loaded matches no other known module format.
1160 @c ******************
1162 @c ******************
1164 @node StarTrekker, UNIC-Tracker, SoundTracker, Format Conversion
1165 @section StarTrekker
1168 StarTrekker is another NoiseTracker clone, which is capable of
1169 playing modules with 4 or 8 channels and supports MIDI devices.
1170 The format of 4 channels modules is the same of NoiseTracker, except
1171 for the @samp{FLT4} ID. Modules with 8 channels have the ID
1172 @samp{FLT8}, and keep the extra data in a second file, whose
1173 structure I don't know. If you want support for 8 channels
1174 StarTrekker modules, please send me some information on its
1179 @c ******************
1181 @c ******************
1183 @node UNIC-Tracker, FastTracker, StarTrekker, Format Conversion
1184 @section UNIC-Tracker
1185 @cindex UNIC-Tracker
1187 Actually, I've never seen UnicTracker, but I sometimes ripp Unic modules
1188 with ExoticRipper, so I decided to give support for this weird Tracker
1189 clone too. The format is very similar to that of ProTracker modules,
1190 except for the @samp{EMW3} ID.
1194 @c ******************
1196 @c ******************
1198 @node FastTracker, TakeTracker, UNIC-Tracker, Format Conversion
1199 @section FastTracker 1.0
1204 The format of FastTracker 1.0 modules is exactly the same
1205 of @ref{TakeTracker}, but they can have only 6 or 8 channels.
1206 @value{prgname} does not support FastTracker 2.0 modules (those
1207 with extension @file{.xm}) yet.
1209 @c ******************
1211 @c ******************
1213 @node TakeTracker, Oktalyzer, FastTracker, Format Conversion
1214 @section TakeTracker
1216 @cindex 32 Channels ProTracker Modules
1218 These are Standard ProTracker modules, but they can have up to 32
1219 channels. Their ID is @dfn{5CHN}, @dfn{6CHN}, and so on, up to
1220 @dfn{32CH}. This format comes from some damn PeeCee tracker, which
1221 I've never seen. Anyway, adding this format was a matter of five
1225 @c ******************
1227 @c ******************
1229 @node Oktalyzer, MED, TakeTracker, Format Conversion
1230 @section Oktalyzer 1.1
1233 Oktalyzer is an old editor which can play up to 8 channels by mixing
1234 instruments in real time. Oktalyzer modules start with the ID
1235 @samp{OCTASONGGMOD}. Development of Oktalyzer has been
1236 discontinued, as the author seems to be programming on Windoze now.
1237 It's really a shame, as many musicians found that Oktalyzer was one
1238 of the most powerful trackers for the Amiga.
1242 @c ******************
1244 @c ******************
1246 @node MED, OctaMED, Oktalyzer, Format Conversion
1250 Not all features of MED are supported by @value{prgname}.
1251 Synthetic and hybrid instruments are ignored.
1255 @c ******************
1257 @c ******************
1259 @node OctaMED, ScreamTracker, MED, Format Conversion
1264 MMD2 modules are not supported. @value{prgname} will only
1265 load the first song in multisong modules.
1267 @value{prgname} currently has an internal limit of only
1268 32 tracks, while OctaMED can do up to 128 tracks. However,
1269 OctaMED can only play the first 8 tracks, so what are
1270 the other tracks for? ;-)
1274 @c ******************
1275 @c * ScreamTracker *
1276 @c ******************
1278 @node ScreamTracker, MIDI File, OctaMED, Format Conversion
1279 @section ScreamTracker
1280 @cindex ScreamTracker
1283 ScreamTracker 3.01 is a damn PeeCee program made by those Future Crew
1284 guys who are trying to turn clones into Amigas. ScreamTracker has the
1285 amazing feature of playing 32 tracks, 16 of which are for 8-bit
1286 digital samples. The other 16 tracks play ADLib FM synths (not
1287 supported by @value{prgname}).
1291 @c ******************
1293 @c ******************
1295 @node MIDI File, , ScreamTracker, Format Conversion
1299 MIDI is the industry standard musical score format (the same way Windoze
1300 is the industry standard graphic interface :-). The MIDI concept is very
1301 different from tracker modules. There are no sequence and patterns, but a
1302 long stream of events (notes) that have to be sent to some MIDI compliant
1303 device, one after the other, at specific time intrvals, based on the
1304 duration of each note. There are no instruments inside MIDI files;
1305 instead, each note is associated with a preset number that matches a
1306 particular instrument in the device to which the MIDI events are sent.
1308 @value{prgname}'s MIDI file saver is based on Andrew Scott's MidiMod
1309 program and I wish to thank him for granting me permission to use his
1310 code in @value{prgname}.
1314 @c ******************
1316 @c ******************
1318 @node Optimization, ARexx Interface, Format Conversion, Top
1319 @chapter Optimization
1320 @cindex Optimization
1322 Module optimization is achieved by removing all unused data in such a way
1323 that the module will sound the same as before. @value{prgname} can process a
1324 module to reduce its size as much as possible. It is generally a good idea
1325 to optimize a module before distributing it, but never while you are still
1326 composing it, because you could easily loose some data that you didn't want
1327 to discard. Do not expect to gain a lot of bytes optimizing modules: saving
1328 20% of the total size is usually a very good result.
1330 @table @bullet{} @code
1331 @item Unused patterns
1332 Some formats (e.g.: Sound/Noise/ProTracker) store empty patterns
1333 in a module if a pattern with a greater number is used. For instance,
1334 a song using patterns 1, 2 and 5 will contain patterns 3 and 4 as well.
1336 @strong{Warning}: If a song contains a part that has not been finished
1337 yet and has not already been inserted in the position table, you will
1340 @strong{Warning}: When a song is saved to Noise/ProTracker, patterns beyond
1341 the last used patterns are discarded regardless of this switch. This
1342 is due to a limitation of Noise/ProTracker module format.
1344 @item Pattern Cutting
1345 When a pattern is breaked with the Pattern Break effect, it is cut to the
1346 line containing the break. When saving to a format that does not support
1347 variable length patterns (eg.: @ref{SoundTracker}), the pattern is grown
1348 again, so this optimization won't help with such formats.
1350 @item Unused instruments
1351 A composer may decide to use an instrument and then change his mind,
1352 but forget to clear the instrument. In this case the module will
1353 contain an instrument that is never played. These instruments
1354 are simply stripped away.
1356 @item Sample data after a loop
1357 The part of an instrument following a loop is never played and is
1358 therefore discarded.
1360 @item Instruments zero tails
1361 Long zero tails eat up memory and produce no sound. This optimization
1362 is performed only on loopless instruments, as a zero sequence inside a
1363 loop @emph{does} make difference. @value{prgname} leaves at least two zero
1364 bytes to avoid the nasty click produced by the speaker dropping its volume
1365 to zero too quickly.
1369 @c *********************
1370 @c * ARexx Interface *
1371 @c *********************
1373 @node ARexx Interface, Known Bugs, Optimization, Top
1374 @chapter ARexx Interface
1376 WARNING: XModule's ARexx port is a little brain dead at the
1380 List of ARexx commands:
1383 * Activate: ARexx ACTIVATE. Not yet implemented
1384 * Clear: ARexx CLEAR. Not yet implemented
1385 * Close: ARexx CLOSE. Not yet implemented
1386 * Column: ARexx COLUMN. Not yet implemented
1387 * Copy: ARexx COPY. Not yet implemented
1388 * Cursor: ARexx CURSOR. Not yet implemented
1389 * Cut: ARexx CUT. Not yet implemented
1390 * Deactivate: ARexx DEACTIVATE. Not yet implemented
1391 * Erase: ARexx ERASE. Not yet implemented
1392 * GoToBookMark: ARexx GOTOBOOKMARK. Not yet implemented
1393 * Help: ARexx HELP. Displays help on a particular topic
1394 * Line: ARexx LINE. Not yet implemented
1395 * LockGUI: ARexx LOCKGUI. Blocks user input in @value{prgname} windows
1396 * New: ARexx NEW. Creates a new song
1397 * Open: ARexx OPEN. Opens a song over the current one
1398 * Optimize: ARexx OPTIMIZE. Performs an @ref{Optimization}
1399 * Paste: ARexx PASTE. Not yet implemented
1400 * Print: ARexx PRINT. Not yet implemented
1401 * Quit: ARexx QUIT. Exits @value{prgname}
1402 * RequestFile: ARexx REQUESTFILE. Not yet implemented
1403 * RequestResponse: ARexx REQUESTRESPONSE. Not yet implemented
1404 * RequestNotify: ARexx REQUESTNOTIFY. Not yet implemented
1405 * Save: ARexx SAVE. Saves the current song
1406 * SaveInstrument: ARexx SAVEINSTRUMENT. Saves the current instrument
1407 * ScreenToBack: ARexx SCREENTOBACK. Brings @value{prgname}'s screen to front
1408 * ScreenToFront: ARexx SCREENTOFRONT. Brings @value{prgname}'s screen to back
1409 * SelectInstrument: ARexx SELECTINSTRUMENT. Selects the current instrument
1410 * SetBookMark: ARexx SETBOOKMARK. Not yet implemented
1411 * ShowMessage: ARexx SHOWMESSAGE. Prints a message in the log window
1412 * UnLockGUI: ARexx UNLOCKGUI. Restores user input in the user interface
1413 * Version: ARexx VERSION. Returns version information about @value{prgname}
1423 @node ARexx ACTIVATE, ARexx CLEAR, , ARexx Interface
1426 @subsection Template
1431 @subsection Description
1435 @subsection See Also
1445 @node ARexx CLEAR, ARexx CLOSE, ARexx ACTIVATE, ARexx Interface
1448 @subsection Template
1453 @subsection Description
1457 @subsection See Also
1465 @node ARexx CLOSE, ARexx COLUMN, ARexx CLEAR, ARexx Interface
1468 @subsection Template
1473 @subsection Description
1477 @subsection See Also
1485 @node ARexx COLUMN, ARexx COPY, ARexx CLOSE, ARexx Interface
1488 @subsection Template
1493 @subsection Description
1497 @subsection See Also
1505 @node ARexx COPY, ARexx CURSOR, ARexx COLUMN, ARexx Interface
1508 @subsection Template
1513 @subsection Description
1517 @subsection See Also
1519 @xref{ARexx CUT,CUT}, @xref{ARexx PASTE,PASTE}, @xref{ARexx ERASE,ERASE}.
1527 @node ARexx CURSOR, ARexx CUT, ARexx COPY, ARexx Interface
1530 @subsection Template
1535 @subsection Description
1539 @subsection See Also
1547 @node ARexx CUT, ARexx DEACTIVATE, ARexx CURSOR, ARexx Interface
1550 @subsection Template
1555 @subsection Description
1559 @subsection See Also
1567 @node ARexx DEACTIVATE, ARexx ERASE, ARexx CUT, ARexx Interface
1570 @subsection Template
1575 @subsection Description
1579 @subsection See Also
1587 @node ARexx ERASE, ARexx GOTOBOOKMARK, ARexx DEACTIVATE, ARexx Interface
1590 @subsection Template
1595 @subsection Description
1599 @subsection See Also
1603 @c ******************
1605 @c ******************
1607 @node ARexx GOTOBOOKMARK, ARexx HELP, ARexx ERASE, ARexx Interface
1608 @section GOTOBOOKMARK
1610 @subsection Template
1615 @subsection Description
1619 @subsection See Also
1627 @node ARexx HELP, ARexx LINE, ARexx GOTOBOOKMARK, ARexx Interface
1630 @subsection Template
1635 @subsection Description
1639 @subsection See Also
1647 @node ARexx LINE, ARexx LOCKGUI, ARexx HELP, ARexx Interface
1650 @subsection Template
1655 @subsection Description
1659 @subsection See Also
1667 @node ARexx LOCKGUI, ARexx NEW, ARexx LINE, ARexx Interface
1670 @subsection Template
1675 @subsection Description
1679 @subsection See Also
1687 @node ARexx NEW, ARexx OPEN, ARexx LOCKGUI, ARexx Interface
1690 @subsection Template
1695 @subsection Description
1699 @subsection See Also
1707 @node ARexx OPEN, ARexx OPTIMIZE, ARexx NEW, ARexx Interface
1710 @subsection Template
1715 @subsection Description
1719 @subsection See Also
1727 @node ARexx OPTIMIZE, ARexx PASTE, ARexx OPEN, ARexx Interface
1730 @subsection Template
1735 @subsection Description
1739 @subsection See Also
1747 @node ARexx PASTE, ARexx PRINT, ARexx OPTIMIZE, ARexx Interface
1750 @subsection Template
1755 @subsection Description
1759 @subsection See Also
1767 @node ARexx PRINT, ARexx QUIT, ARexx PASTE, ARexx Interface
1770 @subsection Template
1775 @subsection Description
1779 @subsection See Also
1787 @node ARexx QUIT, ARexx REQUESTFILE, ARexx PRINT, ARexx Interface
1790 @subsection Template
1795 @subsection Description
1799 @subsection See Also
1803 @c *****************
1805 @c *****************
1807 @node ARexx REQUESTFILE, ARexx REQUESTRESPONSE, ARexx QUIT, ARexx Interface
1808 @section REQUESTFILE
1810 @subsection Template
1815 @subsection Description
1819 @subsection See Also
1823 @c *********************
1824 @c * REQUESTRESPONSE *
1825 @c *********************
1827 @node ARexx REQUESTRESPONSE, ARexx REQUESTNOTIFY, ARexx REQUESTFILE, ARexx Interface
1828 @section REQUESTRESPONSE
1830 @subsection Template
1835 @subsection Description
1839 @subsection See Also
1843 @c *******************
1844 @c * REQUESTNOTIFY *
1845 @c *******************
1847 @node ARexx REQUESTNOTIFY, ARexx SAVE, ARexx REQUESTRESPONSE, ARexx Interface
1848 @section REQUESTNOTIFY
1850 @subsection Template
1855 @subsection Description
1859 @subsection See Also
1867 @node ARexx SAVE, ARexx SAVEINSTRUMENT, ARexx REQUESTNOTIFY, ARexx Interface
1870 @subsection Template
1875 @subsection Description
1879 @subsection See Also
1883 @c ********************
1884 @c * SAVEINSTRUMENT *
1885 @c ********************
1887 @node ARexx SAVEINSTRUMENT, ARexx SCREENTOBACK, ARexx SAVE, ARexx Interface
1888 @section SAVEINSTRUMENT
1890 @subsection Template
1895 @subsection Description
1899 @subsection See Also
1903 @c ******************
1905 @c ******************
1907 @node ARexx SCREENTOBACK, ARexx SCREENTOFRONT, ARexx SAVEINSTRUMENT, ARexx Interface
1908 @section SCREENTOBACK
1910 @subsection Template
1915 @subsection Description
1919 @subsection See Also
1923 @c *******************
1924 @c * SCREENTOFRONT *
1925 @c *******************
1927 @node ARexx SCREENTOFRONT, ARexx SELECTINSTRUMENT, ARexx SCREENTOBACK, ARexx Interface
1928 @section SCREENTOFRONT
1930 @subsection Template
1935 @subsection Description
1939 @subsection See Also
1943 @c **********************
1944 @c * SELECTINSTRUMENT *
1945 @c **********************
1947 @node ARexx SELECTINSTRUMENT, ARexx SETBOOKMARK, ARexx SCREENTOFRONT, ARexx Interface
1948 @section SELECTINSTRUMENT
1950 @subsection Template
1955 @subsection Description
1959 @subsection See Also
1963 @c *****************
1965 @c *****************
1967 @node ARexx SETBOOKMARK, ARexx SHOWMESSAGE, ARexx SELECTINSTRUMENT, ARexx Interface
1968 @section SETBOOKMARK
1970 @subsection Template
1975 @subsection Description
1979 @subsection See Also
1983 @c *****************
1985 @c *****************
1987 @node ARexx SHOWMESSAGE, ARexx UNLOCKGUI, ARexx SETBOOKMARK, ARexx Interface
1988 @section SHOWMESSAGE
1990 @subsection Template
1995 @subsection Description
1999 @subsection See Also
2007 @node ARexx UNLOCKGUI, ARexx VERSION, ARexx SHOWMESSAGE, ARexx Interface
2010 @subsection Template
2015 @subsection Description
2019 @subsection See Also
2027 @node ARexx VERSION, , ARexx UNLOCKGUI, ARexx Interface
2030 @subsection Template
2035 @subsection Description
2039 @subsection See Also
2046 @c ******************
2048 @c ******************
2050 @node Known Bugs, Future Plans, ARexx Interface, Top
2053 @cindex Bugs, known ones
2056 Murphy's laws state that nothing can be perfect, not even computer
2057 programs. @value{prgname} is far from being perfect and I need
2058 your help to fix as many bugs as possible. If you discover a bug
2059 which isn't reported in the list below (note: there is no list at
2060 the moment; this is a beta release, remember?), please notify me.
2062 When you report a bug, state exactly what happens and indicate
2063 how to reproduce the conditions that generated the problem.
2064 Reports like @cite{@value{prgname} sometimes crashes converting my
2065 favorite module} does not help at all. Include your name if you want
2066 to be credited in future @value{prgname} releases.
2068 If the program refuses to convert a module, mail it to me on
2069 a disk or upload it somewhere I can reach it and I'll try to fix the
2070 problem as soon as possible.
2072 @value{prgname} has been tested on several machines running Kickstart 2.0,
2073 3.0 and 3.1. It should work on any 68K family processor (was tested on
2074 68000, 68030 and 68040) and is Enforcer and Mungwall proof. I have also
2075 tested @value{prgname} with virtual memory programs such as VMM and found
2076 that everything seems to work correctly.
2080 @c ******************
2082 @c ******************
2084 @node Future Plans, Programmers, Known Bugs, Top
2085 @chapter Future plans
2087 @table @bullet{} @code
2090 @item Other module formats
2091 Some formats I'd like to give support for in @value{prgname} as soon
2096 FastTracker II (@file{.XM})
2098 MultiTracker (@file{.MTM})
2102 Face The Music (@file{.FTM})
2107 If you have documentation regarding a format you would like to see in the
2108 next release, please send it to me together with a couple of modules and,
2109 if possible and legal, the program that created them. I'll try to
2110 implement the new format only if it is somewhat easy: it is very hard to
2111 convert, say, Future Composer to SoundTracker. Please, do not send a
2112 module without at least a text file describing its structure, as I am
2113 not willing to spend my nights hex-dumping modules :-).
2115 If you want to write a new loader/saver hook, please get the
2116 @value{prgame} developer package and read the included documentation.
2117 You will also find many examples and also the full source code of
2121 Another format I'd like to add is Amiga@TeX{}. If you know
2122 @TeX{}, you'll surely be wondering what a typesetting program can be
2123 used for in music. Well, Amiga@TeX{} is at the moment is the best
2124 implementation available on any computer of the @TeX{} typesetting
2125 environment, and its distribution includes @dfn{Music@TeX{}}, a powerful
2126 music language which can output notes in a great standard staff notation.
2127 I know no other program on the Amiga that can print notes of such fine
2128 quality (if you do, let me know!), so I think that many musicians would
2129 appreciate such an option.
2135 @c ******************
2137 @c ******************
2139 @node Programmers, XModule Format, Future Plans, Top
2140 @chapter Programmer notes
2141 @cindex Programmers, notes for
2142 @cindex Modifying @value{prgname}
2143 @cindex Compiling @value{prgname}
2145 @value{prgname} has been written in C and compiled with SAS C 6.51,
2146 Other compilers may require some changes in the source code.
2148 The program is written in respect of the Amiga multitasking operative system
2149 and complies with Commodore programming guidelines. All allocated resources
2150 will be (hopefully) freed before program termination. I wrote @value{prgname}
2151 with the goal in mind of keeping the executable fast and small.
2153 This manual has been typeset using MakeInfo, a GNU PD utility ported
2154 to the Amiga by Reinhard Spisser and Sebastiano Vigna.
2155 I found that the time I saved writing one file for three was nearly
2156 compensated by the time spent learning how to operate MakeInfo.
2158 Besides, English is not my first language (as you might have guessed) and
2159 I bet this document is full of grammar mistakes.
2161 If you intend to translate, improve or somewhat edit this document, please
2162 work on the supplied TexInfo file and then process it with the utilities
2163 supplied in the MakeGuide distribution. You can find MakeGuide in several
2164 PD libraries such as Aminet.
2166 Do not hesitate sending criticisms to my work, and, even better,
2167 advices on how to improve the program and its documentation. @xref{Author Info}.
2171 @c ******************
2172 @c * XModule Format *
2173 @c ******************
2175 @node XModule Format, Credits, Programmers, Top
2176 @chapter XModule Module Format
2177 @cindex File Format used by XModule
2179 Before going into the details of the @value{prgname} module format, I'd like to
2180 explain why I felt the need to invent yet another module format. There were
2181 plenty of them, but none had the flexibility I was looking for. The only one
2182 exception is in my opinion OctaMED's MMD. But the MMD file format is very
2183 complicated, hard to read and poorly documented. When I designed it, I wanted
2184 XMOD to be as flexible, easy, efficient and expandable as possible. If you are
2185 developing a music program, please consider supporting XMOD. If you have troubles
2186 with the following format description, contact me and I'll be glad to help you.
2188 @value{prgname} modules are standard IFF files. They consist of a sequence of chunks
2189 (also called @dfn{proprieties}) each storing a particular type of information related
2190 to the module. Text chunks, such as NAME and AUTH chunks are variable sized and NOT
2191 null terminated. When you read such a chunk, you should take care to clip the string
2192 to your maximum buffer size. NAME and AUTH fields are optional and should be assumed
2195 As with every IFF file, you should not depend on the order and size of any chunk.
2196 However, as usual with most IFF formats, header chunks must always precede related
2197 BODY chunks. XModule requires this for PHDR chunks because it isn't possible to load
2198 a pattern without knowing its length and number of tracks. Some chunks may grow in
2199 size in future versions of XModule.
2205 The name chunk contains the original name used to save the module.
2208 Module header. Contains a ModuleHeader structure as defined in
2212 Some XModule copyright information.
2215 The song FORM contains all data relative to one song. Any
2216 number of songs can be stored into one module.
2228 Song Header. Contains a SongHeader structure as defined in
2232 Song Sequence. The contents of this chunk are unsigned words
2233 representing the pattern to play at a particular position.
2234 The size of this chunk should be twice the Length field of
2236 When a song contains multiple sections, one SEQN chunk will
2237 be stored for each of the song sections (not yet implemented).
2240 Each occurrence of this FORM contains one pattern. Patterns
2241 are numbered starting from 0. Each pattern has its own
2242 length and number of tracks.
2245 Name of this Pattern.
2248 Pattern Header. Contains a PatternHeader structure as
2249 defined in <XModuleClass.h>.
2252 The BODY chunk is stored as an array of PatternNote
2253 structures. Tracks are stored one after the other.
2254 There are NumTracks*Length Note structures in the BODY
2260 Each SONG contains one or more occurences of this FORM,
2261 one for each sample. XModule currently saves and loads
2262 only the NAME, VHDR and BODY chunks. Be prepared to
2263 decode Fibonacci Delta Encoded BODY chunks. An additional
2264 non-standard chunk is saved:
2267 XModule instrument info. Contains an InstrumentInfo
2268 structure as defined in <XModuleClass.h>.
2270 When the BODY chunk is missing, the sample must be
2271 loaded from the instrument library using the contents
2272 of the NAME chunk as the file name.
2274 See the IFF 8SVX documentation for more details.
2285 @c ******************
2287 @c ******************
2289 @node Credits, Author Info, XModule Format, Top
2292 @cindex Acknowledgements
2295 These people have helped me in developing @value{prgname}:
2299 Fabio Barzagli, for beta testing @value{prgname} and for giving me
2300 all his awesome modules!
2302 Keep on making good music, Fabio!
2305 Jarno Paanen, for sending me the obfuscated source of his 32 channel
2306 replay engine and for the e-mail support.
2308 Perhaps I would have understood more by disassembling the PS3M executable. :-))
2311 Peter Kunath, for his unvaluable help.
2315 @item Stephen Cantini, Michael Reichenbach and Julien Wilk, respectively for
2316 writing the italian, german and french catalog.
2318 Thank you all! I'm sure @value{prgname} users in your countries will apreciate
2321 @item Pauli Porkka, for his kindness, for letting me win a free DASMP
2322 key, for the sources and for all the e-mails.
2324 Will you support my format in the next DASMP release?
2327 The Amiga, for being the best computer in the world. :^)
2329 Commodore: You've put really a lot of effort trying to kill the Amiga,
2330 but you didn't succeed!
2335 @c ******************
2337 @c ******************
2339 @node Author Info, Concept Index, Credits, Top
2340 @chapter How to contact the author
2341 @cindex How to contact the author
2342 @cindex Author's address
2343 @cindex Contact the author, how to
2345 If you want to make me aware of your suggestions, bug reports, ideas
2346 or you want to send me a gift, a good module or, why not, some money :-),
2347 reach me in any of the following ways:
2349 @table @bullet{} @code
2353 UseNet: xmodule@@shock.nervous.com (preferred)
2354 FidoNet: Bernardo Innocenti 2:332/125.1
2355 AmigaNet: Bernardo Innocenti 39:102/205.1
2359 @item SystemShock BBS
2362 Line 1: +39-55-499038 (28,800bps - V34)
2363 Line 2: +39-55-472514 (14,400bps - V32bis)
2364 Sysop: Bernardo Innocenti (me)
2365 Message area 300: XModule Support
2366 File Request magic name "XMODULE" to get the latest public version.
2374 Via Ventiquattro Maggio, 14
2384 Attn: Bernardo Innocenti
2385 Subj: Amiga/@value{prgname}
2391 I'll try to reply to all my e-mail, but I'm too lazy to reply
2392 snail-mail, unless it is very important. Your suggestions
2393 will be taken into account unless they are @cite{I want
2394 @value{prgname} to do ice tea}-style.
2397 @node Concept Index, , Author Info, Top
2398 @unnumbered Concept Index