MOD

Section: User Commands (1)
Updated: 1994 Nov 29
Index Return to Main Contents

NAME

mod - plays music stored in various "module-formats" mod_mklist - create a script that plays a sequence of modules

SYNOPSIS

mod [global options] file [options] file [options] ...

mod_mklist [global options] file [options] file [options] ...

DESCRIPTION

Mod is a program that can play modules created by the Amiga Protracker and similar composers (file-extensions .MOD and .NST ). It supports all effects available in Amiga Protracker 3.0 (hereafter PT) except those mentioned in the BUGS - section of this manual. Other module-formats supported are: Ultratracker ( .ULT ), Multitracker ( .MTM ) and Scream Tracker III modules ( .S3M ). Files compressed with compress / gzip , lharc , zip and arj are uncompressed automatically if the appropriate unpacking-programs are installed. Currently Gravis Ultrasound is the only supported soundcard. Mod uses /dev/sequencer for sequencing data, but at some point in time there _might_ be support for /dev/dsp and /dev/pcdsp (and thus also for Sound-Blasters and DACs/PC-speaker).

Mod_mklist is used to create a shell-script that plays a sequence of modules. You pass exactly the same options you would pass mod if playing them directly. Typically you would like to pipe the output to a file and make that file executable. The produced script is very easy to change using a normal editor if you want to add/remove options for some modules. When running the script you can give it options just like when you invoke mod normally and these will be put in the global section just before the first module.
This way you can have all your modules (even those which require special options) easily available for listening even if the modules are located in different directories.

OPERATION

There are several modes of operation in mod. Normally you use the interactive interface to control the player. If you don't want this you can use -q to make it work in "batch-mode". Only errors and warnings will be printed on standard output. If you want absolute silence use -Q instead (it won't say a peep no matter what errors occurs). This can be used to put the player in the background.

If you are having trouble loading a module you can use verbose mode ( -v ). This mode will behave exactly like interactive mode, except that you are "blind" and can't see what is happening on the screen (you typically pass the name of the file you want to check on the commandline). Instead you will see some informative messages while loading the module that may help you locate the problem. Note that in this mode the screen-output may be a bit messy as it is just there for debugging.

To make it easier for you to use mod as a background process you can use -z to put it in the background (no ampersand in the shell needed). When you want to stop the playing just issue the command "mod -k". Note that this command will only work when mod was put in the background using -z.

Unless you are using interactive mode the program will terminate after the last module has been played.
When the program exits the total time spent playing music will be displayed.

Finally, there are two different "modes" when you are using mod interactively. When there are no files specified on the commandline you will be allowed to browse the file-system for files to play. When a playlist is specified on the commandline, these modules are the only ones available for playing. Some options have different defaults depending on which of the two "modes" you are operating in. See the OPTIONS - section below for more details on this.

KEYS

The following keys are available in interactive mode to control the player.

Always:
h, F1: Allows you to display the different help pages.
l: Toggles you in or out of load-mode (where you can select files to load).
+, -: Increases/decreases the volume if a mixer-device is available.
m: Toggles mute on and off.
q: Exits the program.
In load-mode:
Enter: Loads and starts playing the highlighted file. If it is a directory you will enter it instead.
n, p, N, P, Down, Up, Page-Down, Page-Up, Home, End: Allows movement among the available files.
u: Will select '..' if available and thus move you up in the filetree.
Otherwise:
r: Restart the current module.
f: Fast-forwards the module one pattern.
b: Rewinds the module one pattern.
Enter: Will stop or resume playing of the module.
n, space: Load next module. If there is no playlist , the next file in the directory of the currently loaded module will be loaded.
p: Same as the above, but takes the previous file instead.
Down,Up, Page-Down, Page-Up, Home, End: Allows movement in the sample-list.
s: Will toggle the scrolling of notes on or off.
v: Changes how much information is displayed about each voice.
Left, Right: Allows you to change which voices are displayed on the screen.
0-9: Allows you to toggle voices on or off. If a module with less than 10 voices is loaded, keys 1 through 9 toggle the voices. If there are more voices you will have to use two keypresses. For example '02' or '13' to toggle voices 2 and 13 respectively. Note that the keypresses must be consecutive.
The player will restart the pattern each time a voice is toggled if the song is still playing. This is unfortunate, but it is a consequence of the scheme used to minimize skips in the sound output (which is more important).

OPTIONS

Options specified before the first filename are considered global and will be applied to all modules played. All other options are used together with the closest filename to the left of the options in question. Global options are parsed before all other options and can thus be negated by options belonging to a specific file.

Options may be grouped after a single hyphen. If an option takes an argument, the argument can be placed immediately after the option or it can be preceeded by spaces.

The following options can be placed anywhere on the line, but will always be considered global.

-a: Enables the auto-next function. This means that when a module is played to the end the next module will automatically be loaded and started. If there is a playlist the first module will be loaded and started automatically when mod starts up. This option is default when there is a playlist specified.
-A: Disables the auto-next function. This is the default when there is no playlist specified.
-b: Modules containing infinite loops will have these loops removed. Default when there is a playlist specified.
-B: Infinite loops allowed. Default when there is no playlist specified.
-C: Causes the sequence of modules to be played over and over again indefinitely (if used in conjunction with -r it will be the same sequence every time). This option only works if there is a playlist specified.
-D: Specifies the directory that mod should be starting in. Defaults to current directory.
-h: Gives a list of available options and brief descriptions of them. If this option is present anywhere on the commandline no modules will be played.
-k: This option must be the only argument on the commandline. It will terminate a copy of mod running in the background. See also option -z.
-l lines: With this option you set how many lines on the screen are used to display notes and files.
-n: This options disables scrolling of notes (it can still be toggled using the 's' key).
-q: Quiet batch mode. Only errors and warnings are printed.
-Q: Totally silent batch mode. Nothing is ever printed.
-r: This option will play the modules in random order.
-v: Verbose mode.
-z: This option puts mod in the background. See also option -k.

The following options are applied only to one module (unless they are specified in the global section of the commandline).

-c size: Try this option if a sample clicks or pops repeatedly in a module. It attempts to minimize clicking on looped samples. size specifies how long a sample must be to be modified. Short samples that are looped may sound distorted if they are modified and specifying an approprite size will make sure these doesn't get modified. The default setting is 0 (click removal turned off). Note that this option may very well distort long samples too, so it shouldn't be used unless it is necessary.
-f format: This option specifies what format the module is stored in. Valid values of format are currently mod , mtm , ult and s3m. If this option isn't specified mod will try to determine the format by examining the filename. If no known prefix/suffix is found the file is assumed to be a standard PT module ( mod ).
-L: The module will be replayed indefinitely when this option is present.
-m time: This option can be used to set the maximum time spent on playing a module. Useful when playing a sequence of modules and some of them have a long silent part at the end. It can also be used to browse through a bunch of modules. time should be specified in seconds.
-M: Many Amiga modules are composed using sound coming from the mono-speaker of a monitor or TV-set. Some of these may have sounds jumping left and right (unintentionally) if played in stereo. This option will turn on mono output to allow such modules to be played better.
-N: Same as -P but sets NTSC playbackrate of samples instead.
-o
-O: These two options decide what octaves are valid to portamento notes within (it does not affect triggering of notes). The Amiga PT only uses octave 1-3, but other trackers has support for more octaves. -o specifies 1-3, and -O allows use of octaves 0-4. If neither is explicitly supplied mod tries to guess the correct setting. These options only affects MODs.
-p position: Starts playing at a particular songposition. If position is an invalid value the module will be started at position 0.
-P: PAL and NTSC Amigas have slightly different playbackrates of samples. This option is the default and will play samples the same way a PAL Amiga would. The difference between the PAL and the NTSC playbackrate is very small, but modules that use long samples might sound a bit "off-beat" if the wrong setting is used. This option has no meaning for certain formats. Also see -N.
-T: This option makes the loader a bit more tolerant. It will allow loading of modules that has it's last sample significantly truncated (normally only eight truncated bytes are allowed).
-s speed: Starts playing at a specified speed (useful together with -p ).
-t tempo: Starts playing at a specified tempo (useful together with -p ). Valid values are 32 through 255.
-x detail: Changes how much information is displayed about each voice. detail should be a number between 1 (high detail) and 3 (low detail). If nothing is supplied mod will lower the detail as much as needed to maximize the number of voices shown on the screen.
-0: Causes speedchanges to zero to be ignored (this is how older trackers did it). The default behaviour of PT (and thus mod ) is to stop playing the module when such an effect is encountered.
-5: Normally modules are played using tempo as the timingsource, but some older modules use vertical blanking for tempo. This option will consider all tempo-changes in the module as speed-changes instead. The tempo will be syncronized with a PAL 50 Hz timer (=125 BPM).
-6: Same as -5 but a NTSC 60 Hz timer (=150 BPM) will be used instead.

ENVIRONMENT

If the environment variable MOD_OPTIONS is defined its contents will parsed as global options before any options supplied on the commandline are parsed. You can only specify options here, not filenames (if you do, anything from that point in the variable will be ignored).
This will allow you to easily customize how mod behaves. A typical shell-command to set this variable would be:

export MOD_OPTIONS="-l25 -Pb"

MODULES

Modules may be compressed using compress / gzip , lharc , zip and arj. Note that if an archive contains several files the largest one will be assumed to be the module. If the format isn't explicitly passed with option -f filenames should contain a suffix/prefix specifying what format the file is in, or mod might fail to play it. The filename used to find out the type of module is the specified filename minus the compression-suffix. This unless it is an archive, in which case the name of the extracted file is used. Note that archives where the module is located in a subdirectory might not be handled correctly by mod.

EXAMPLES

Example filenames:

foo.mod.gz (gzipped with a format-suffix)
foo.lha (lha-compressed)
Mod_foo (uncompressed with format-prefix)
foo.Z (compressed without a valid format-suffix)

Example invokations:

mod -r mod_sahara -c200 klisje.mod -5 awesome1_mod -C

This will play the three modules in random order repeatedly. Sahara will have click-removal enabled and klisje will be played using a 50 Hz vertical blanking timer.

mod -m 10 *.mod

Here the first ten seconds of all modules in the current directory will be played.

NOTES

If you get "jumps" in the text output when playing modules, it is because the process isn't getting enough CPU-time allocated (modules playing at high speed prints lines more often). If the jumping is disturbing you can reduce the number of lines ( -l ), change the voice-detail ('v') or turn off scrolling (or buy a faster CPU :-). If the jumps are periodic, try terminating processes like 'top'.

If there are jumps in the sound output during disk-activity you may want to enable interrupt unmasking (use the hdparm-utility). This will (supposedly) decrease the interrrupt-latency and thus give the sounddriver a better chance to get its interrupts served. If this doesn't help there is little you can do.

When using winding the module may sound strange because notes and effects are not played in the order intended (for example, you could miss the silencing of a looped sample or a speedchange).

The displayed size of modules accounts for the bytes used in the (uncorrupted) file. This is most of the time the same as the filesize, but not always. Some modules are missing parts of samples, and S3M-modules can contain various data apart from the data needed to play the module.

VERSION

This manual-page is documenting version 0.61 of mod.

CONFORMS TO

Amiga Protracker 3.0, Multitracker 1.01a,
Ultratracker 1.60, Scream Tracker 3.01 BETA

BUGS

It is possible to set the tempo with -t after specifying vertical blanking as the timing-source (option -5 or -6 ). This may also be considered a feature.

There is no support for the samplemodifying effects (inverted loop/funk and karplus-strong).

No support for the Ultratracker "Special"-effects, or logarithmic volumes used in format version 1.

The lowpass-filter that can be toggled on/off on some Amigas is not implemented.

The Amiga PT is the base of the player, all other formats are supported as good as possible. If other trackers say they are PT-compatible they will be assumed to be just that. In other words, it may sound a bit different from the original tracker if they in reality are not 100% PT-3.0 compatible and I don't know about it. In some cases effects are converted to PT-effects as good as possible, in other new effects has been implemented separately. These differences are very subtle and shouldn't be a problem.

AUTHOR

Mikael Nordqvist (mech@df.lth.se, d91mn@efd.lth.se)

This document was created by man2html, using the manual pages.
Time: 22:25:50 GMT, July 01, 2025

MOD