.TH MODTRACKER 1
.SH NAME
track, decode, sample, edsamp \- mod music tracker and tools
.SH SYNOPSIS
.B mod/track
[
.I module
]
.br
.B mod/decode
.br
.B mod/sample
[
.B -i
.I fmt
]
[
.B -l
.I length
]
[
.I note
]
.br
.B mod/edsamp
[
.I sample
]
.PP
.SH DESCRIPTION
These programs operate on music modules and samples
in the Amiga Protracker format.
.SS Tracking
.PP
.I Track
opens
.I module
for editing or starts a new module from scratch.
The song's title is shown in the top left corner.
The song's length, current sequence position, and current pattern
are displayed in the top right corner.
All numbers are printed in hexadecimal.
The current sample number is displayed in the bottom left corner.
This is followed by the current sample's name, 
which is often a message from the composer instead.
The current input octave and scroll distance
are displayed in the bottom right corner.
.PP
The rest of the display is taken up with a partial view of the current pattern.
Each pattern has 64 rows and four tracks:
the current row and track are highlighted.
Each track has a column for sample number, note value, and effect parameters.
Tracks 1 & 4 are panned left, tracks 2 & 3 right.
.PP
Notes from the current sample and input octave are entered with the keyboard:
.PP
.B "key:		    y       u           o       p       ["
.br
.B "key:		g       h       j   k       l       ;       '"
.br
.B "note:	C   C#  D   D#  E   F   F#  G   G#  A   A#  B"
.PP
If shift is down only the pitch is entered.
The remaining keyboard commands are:
.TF Insert/Delete
.TP
.B t
Edit song title
.TP
.B Insert/Delete
Change song length (alters position if at end)
.TP
.B Home/End
Change sequence position
.TP
.B PgUp/PgDn
Change pattern at current sequence position
.TP
.B ←/→
Change track
.TP
.B ↑/↓
Change row
.TP
.B F5-F12
Set scroll distance (1-8)
.TP
.B ^A/^B/^E
Jump to beginning/middle/end of pattern
.TP
.B M/m
Set/jump to row mark m
.TP
.B N/n
Set/jump to row mark n
.TP
.B =/-
Change sample (works during playback)
.TP
.B s
Edit sample settings
.TP
.B r
Rip current sample to disk
.TP
.B R
Rip all samples to disk
.TP
.B "` (backtick)"
Set note to current sample number
.TP
.B ~
Clear note's sample number
.TP
.B Tab
Cycle input octave (1-3)
.TP
.B [0-9a-f]
Set note's effect parameters (see below)
.TP
.B Backspace
Cut
.TP
.B Esc
Paste (see mouse commands below)
.TP
.B Space
Start playback from current row: stop with any key
.TP
.B F1-F4
Mute/unmute the corresponding track (works during playback)
.TP
.B w
Write module to disk
.TP
.B q
Quit: press again to confirm
.PD
.PP
Effects parameters are represented by three digit hex values:
.TF XXX
.TP
.BI 0 xy
Arpeggio on 0,
.I x
, y semitones above base note
.TP
.BI 1 xx
Slide pitch up by subtracting
.I xx
from period each tick
.TP
.BI 2 xx
Slide pitch down by adding
.I xx
to period each tick
.TP
.BI 3 xx
Portamento towards note with speed
.I xx
(300 continues previous settings)
.TP
.BI 4 xy
Vibrato with speed
.I x
and depth
.I y
(400 continues previous settings)
.TP
.BI 5 xy
Continue portamento with
.RI A xy -style
volume slide
.TP
.BI 6 xy
Continue vibrato with
.RI A xy -style
volume slide
.TP
.BI 7 xy
Tremolo with speed
.I x
and depth
.I y
(700 continues previous settings)
.TP
.BI 9 xx
Set sample offset to
.I "xx * 256"
bytes (900 uses last offset)
.TP
.BI A xy
Slide volume by adding
.I x
or subtracting
.I y
each tick
.TP
.BI B xx
Jump to sequence position
.I xx
after playing this row
.TP
.BI C xx
Set volume to
.I xx
(maximum 0x40)
.TP
.BI D xy
Break to row
.I "x * 10 + y"
in next sequence position after playing this row
.TP
.BI E1 x
Increase pitch by subtracting
.I x
from period
.TP
.BI E2 x
Decrease pitch by adding
.I x
to period
.TP
.BI E3 x
Glissando on/off (makes portamento lock to semitones)
.TP
.BI E4 x
Set vibrato waveform (0 = sine, 1 = ramp down, 2 = square)
.TP
.BI E5 x
Set sample finetune to
.I x
(two's complement signed nibble)
.TP
.BI E6 x
Set pattern loop point
.RI ( x
= 0) or loop
.I x
times
.TP
.BI E7 x
Set tremolo waveform (0 = sine, 1 = ramp down, 2 = square)
.TP
.BI E9 x
Retrigger sample every
.I x
ticks
.TP
.BI EA x
Increase volume by
.I x
.TP
.BI EB x
Decrease volume by
.I x
.TP
.BI EC x
Cut sample after
.I x
ticks
.TP
.BI ED x
Delay sample trigger by
.I x
ticks
.TP
.BI EE x
Stay on this row
.I x
times longer than usual
.TP
.BI F xx
If
.I xx
< 0x20, set speed to
.I x
ticks per row (default 6),
.br
else set tempo to
.I xx
beats per minute (default 125; 1 beat = 4 rows)
.PD
.PP
The mouse button 3 menu contains snarf commands:
snarfing part of a note masks only that part for pasting;
the block snarf has its own buffer and prompts for dimensions.
The mouse button 2 menu contains the corresponding paste commands,
as well as commands for filling a track with the snarf buffer
and transposing a track up/down by a semitone.
The block paste, fill, and transpose commands
only affect the current row and every
.I "scroll distance"
row after that.
Clicking with mouse button 1 jumps to that part of the pattern.
.PP
.SS Decoding
.PP
.I Decode
reads a module file from standard input
and produces PCM on standard output at a sampling frequency of 44.1KHz,
in the manner of the audio decoders in 
.IR audio (1).
.SS Sampling
Samples are 8-bit mono pcm audio with a maximum size of 128KB.
A sample's length, repeat point, and repeat length must be even numbers of bytes.
If the repeat length is greater than 2
the sample will be looped after first being played through.
.PP
.I Sample
is a wrapper for
.I audio/pcmconv
which reads pcm on standard input and puts the sample format on standard ouput.
The
.B -i
and
.B -l
options are passed to pcmconv.
.I Note
should be a string like
.L C-3
or
.L F#2
and specifies the note at which the sample will be played at its original frequency.
If
.I note
is not specified
.L C-2
is assumed.
.PP
.I Edsamp
provides a 128KB buffer for editing a sample.
If
.I sample
is specified it is read into the beginning of the buffer.
The sample range, playback note and finetune, repeat point, and repeat length
are shown at the top of the window.
The visible range and selection are shown at the bottom of the window.
All numbers are printed in hexadecimal.
The rest of the display is taken up with a view of the waveform.
The selection is shaded and its start and end points
may be set by clicking mouse button 1 and 3.
Mouse button 2 edits the waveform directly.
The waveform is coloured according to whether it is part of the sample/loop.
.PP
Keyboard commands:
.TF Backspace
.TP
.B ↑/↓
Zoom view in/out
.TP
.B ←/→
Scroll view
.TP
.B s
Set sample to selection and zoom to view
.TP
.B S
Set loop to selection and zoom to view
.TP
.B Home
Set selection to sample and zoom to view
.TP
.B End
Set selection to loop and zoom to view
.TP
.B f
Fit selection on screen
.TP
.B Backspace
Zero selection
.TP
.B ~/^//
Add a sine/triangle/sawtooth wave to selection (unshifted keys also work)
.TP
.B r
Read a sample from disk and add it to the selection; if the length of the selection is zero it will be extended to the length of the sample
.TP
.B a
Apply an amplitude envelope to the selection
.TP
.B x
Reverse the selection
.TP
.B c
Copy the sample to the selection
.TP
.B Space
Play the sample back: the pitch may be controlled as in
.I track
above
.TP
.B t
Change the playback finetune value
.TP
.B w
Write the sample to disk
.TP
.B q
Quit: press again to confirm
.PD
.PP
Numbers prompted for are decimal doubles.
A square wave may be produced by creating a sine/tri/saw wave with exponent 0.
Noise may be produced by reading from /dev/random.
.SH "SEE ALSO"
.IR audio (1),
.IR play (1)
.br
.B MODFIL12.TXT
.br
.B http://modarchive.org
.SH BUGS
MOD is a venerable and much-abused format:
not every quirk exploitable on the Amiga will be faithfully reproduced.
Patterns higher than the highest pattern in the song sequence are not saved.
There is no edit history or undo function: work is easily lost.
Audio output is not filtered.
