order make

[ITMCK.git] / itmck_manual.tex

% ITMCK manual v0.1
% This manual is in public domain.

\def\ecall#1{\bgroup\edef\next{\egroup#1}\next}

\font\ninerm=cmr9
\font\titlefont=cmr7 scaled\magstep4
\font\headIfont=cmr10 scaled\magstep3
\font\headIIfont=cmr10 scaled\magstep2
\font\headIIIfont=cmr10 scaled\magstep1
\font\bigtt=cmtt10 scaled\magstep2
\font\mediumtt=cmtt10 scaled\magstep1

\shipout\vbox to\vsize{
  \vss
  \centerline{\titlefont ITMCK Manual}
  \smallskip
  \centerline{v0.1}
  \vss
}
\pageno=2

\newif\ifnotbeginchapter \notbeginchapterfalse

\newcount\secnoI
\newcount\secnoII
\newcount\secnoIII

\let\tocI=\relax
\let\tocII=\relax
\let\tocIII=\relax

\newwrite\tocfile \immediate\openout\tocfile=\jobname.toc

\def\headblock#1#2#3#4{\moveright#4pt\vbox{%
  \hrule%
  \hbox{%
    \vrule%
    #1%
    \phantom{\'(}%
    \ecall{#2}%
    \phantom{\c)}%
    \ecall{\write\tocfile{#3{#2}{\folio}}}%
  }%
}}%

\def\esecI{\uppercase{\romannumeral\secnoI}}
\def\esecII{\esecI.\the\secnoII}
\def\esecIII{\esecII.\char\the\secnoIII}

\def\headI: #1\par{%
  \advance\secnoI by 1 \secnoII=0
  \vfill\eject%
  \headblock\headIfont{\esecI.\quad#1}\tocI0%
  \penalty600\bigskip\penalty600%
  \mark{\esecI}%
  \global\notbeginchapterfalse%
}%
\def\headII: #1\par{%
  \advance\secnoII by 1 \secnoIII=96
  \bigbreak%
  \headblock\headIIfont{\esecII.\quad#1}\tocII3%
  \penalty600\medskip\penalty600%
  \mark{\esecII}%
}%
\def\headIII: #1\par{%
  \advance\secnoIII by 1
  \medbreak%
  \headblock\headIIIfont{\esecIII.\quad#1}\tocIII6%
  \penalty600\smallskip\penalty600%
  \mark{\esecIII}%
}%

\def\cdotl{\ \cleaders\hbox{ \vrule height4.5pt depth-3.5pt width1pt\ }\hss\ }
\headline={\ninerm\ifnotbeginchapter\topmark\fi\cdotl\folio\cdotl\firstmark}
\footline={\ninerm\firstmark\cdotl\folio\cdotl\botmark}
\output={\plainoutput\global\notbeginchaptertrue}

\parskip=6pt plus 6pt minus 0.5pt
\parindent=1pc

\let\TT=\bigtt
\let\Tt=\mediumtt

% === Begin main document text ===

\headI: Introduction

This is the documentation for ITMCK. ITMCK is a program to take an input
MML (Music Macro Language) file to make Impulse Tracker compatible file
output.

\headII: Compiling

This program is written in C89 with GNU extensions and there is a UNIX
shell script named {\tt compile} to make compile into executable file. If
you have Microsoft Windows (or ReactOS), you should be able to run the
executable file directly, but on Linux you can compile it using the C
compiler and then it should work.

\headII: Invoking

This program must receive the MML code on standard input and then the
binary output on standard output. Usually you would redirect input from a
file having {\tt.mml} extension and redirect output to a file having
{\tt.it} extension.

For example: {\tt itmck < song.mml > song.it}

There are command-line parameters which can be activated as follows:

{\tt-c}\quad Set compatibility setting. Give it an argument which is the
number for the compatibility setting. Compatibility setting is described
later in this document.

{\tt-e}\quad Export raw sample data to standard output. The parameter will
be the number of the sample to export. This can only be used with
synthesized samples and cannot be used with external samples. The normal
output is suppressed when this mode is used.

{\tt-p}\quad Set prefix for external samples. When loading an external
file, the text here will be given as a prefix for the filename when
accessing the external files. It is necessary to include the trailing
slash if it is the name of a directory.

{\tt-t}\quad Trace input. No parameter is used. This will display each
line of input on standard error when it is being processed, including the
preprocessing, and errors for that line will appear with that line so that
you can debug the input file.

{\tt-v}\quad Version number. No parameter is used. No input is requested
and the standard output will include the version number of ITMCK.

{\tt-x}\quad Volume 0 mix optimization. No parameter is used. This command
will activate the ``volume 0 mix optimization'' flag in the output file.

\headII: License

ITMCK is licensed under GNU GPL v3 or later version. This document is
licensed under public domain. A copy of the GNU GPL v3 should have been
made available in a file named {\tt COPYING} in the same media that you
received the program with.

\headI: Syntax

\headII: Comments

\headII: Musical Notes

A music note, wherever it is expected, consists of a lowercase letter from
{\tt a} to {\tt h} followed by modifiers, or the letter {\tt n} followed
by a direct note number. In some cases (but not in the tracks), this is
followed by the octave number (unless it is a direct note entry).

The modifiers are: {\tt-} to lower the note by one semitone, {\tt+} to
raise the note by one semitone, and {\tt'} to raise the note by one
octave (the number of ``semitones'' in an ``octave'' can be reconfigured,
although it is normally twelve). It is allowed to have multiple modifiers.
Modifiers must come before the octave number (if applicable).

In a track, the note is optionally followed by the length. Modifiers also
come before the length, although the length is optional, and whether or
not it is included you may have optional full stops afterward, which act
like a dotted note in a sheet music.

Remember that even these direct note numbers, octave numbers, and length
numbers may include access the values of variables; for example,
{\tt@=x50[n\$x@+x1]13} will play a chromatic scale.

\headII: Numbers

There are three ways to write numbers in ITMCK wherever they are expected.

If multiple parameters are expected, you cannot normally separate numbers
by spaces. However, you can use commas if it would be ambiguous to put
them directly next to each other.

\headIII: Decimal

Write a decimal number optionally prefixed by a minus sign or plus sign.
(If the number is omitted, it is treated as zero.)

Example: {\tt42}

\headIII: Hexadecimal

Hexadecimal numbers are prefixed by a dollar sign, and the letters must
be written in uppercase.

Example: {\tt\$2A03}

\headIII: Variables

To use the value of a variable where a number is expected, use the
variable letter in lowercase after a dollar sign. There are 27 variables,
labeled {\tt\$a} to {\tt\$z} and the backquote variable {\tt\$`} (use of
the backquote variable is explained later).

Example: {\tt\$x}

\headI: Hash Directives

\headII: \TT\#AMIGA-SLIDES

If you select this mode, the portamento slides will be linear by period
(as they normally are on Amiga computers) instead of by frequency.

N.B.: Auto-portamento does not work if this is selected.

\headII: \TT\#CHANNEL

\headII: \TT\#COMPATIBILITY

Set compatibility setting (same as {\tt-c} switch). Currently the only
valid setting is zero which has no effect.

\headII: \TT\#GATE-DENOM

\headII: \TT\#INCLUDE

Specify a filename. It include a file with that name from the same
directory as another input file, which will be processed before continuing
with the current input file.

\headII: \TT\#LINEAR-SLIDES

This is the default setting and it makes portamento slides to be
``linear'' (actually exponential by frequency).

\headII: \TT\#MINIMUM-VERSION

Check the version of ITMCK. This number must be hex number of form
{\tt\$xyz} corresponding to version x.y.z of ITMCK. It is a fatal error if
the current version of ITMCK is less than the value given on this line.

\headII: \TT\#MIXER

Set master volume, which must range from 1 to 128. Default setting is 48.

\headII: \TT\#MONO

Select mono audio.

\headII: \TT\#OCTAVE-REV

Specify a number 0 or 1. If you specify 0 (default) then {\tt>} means high
octave and {\tt<} means low octave. If you specify 1 then {\tt<} means
high octave and {\tt>} means low octave.

\headII: \TT\#OLD-EFFECTS

\headII: \TT\#PANNING-SEPARATION

\headII: \TT\#PORTAMENTO-SHARE

\headII: \TT\#SCALE

This command is used to customize the scale of notes. You can use the
letters {\tt a} to {\tt j} up to once each (although you need not use all
of them, and they need not be in order). Use full stops to indicate no
letters for that position (they can still be accessed by sharp/flat).
However many letter and dot is the number of tones per octave. You can
include a vertical bar to indicate what will be zero of scale (points
before that one are negative).

The default setting is: {\tt a.b|c.d.ef.g.} (including full stop at end)

As an example, the default setting means that there are twelve notes per
octave (don't count the vertical bar), {\tt a} has value $-3$, {\tt b} has
value $-1$, {\tt c} has value $0$, {\tt g} has value $7$, and so on. This
corresponds to the standard keys on a piano.

You cannot comment anything out on this line.

N.B.: If you change the scale other than twelve, you must affect the key
tables to reflect this.

\headII: \TT\#SCALE-BASE

Allows to define which letter should be considered the lowest note of the
octave. The default value is `{\tt c}'. If you set it to `{\tt a}', then
entering `{\tt a}' where a note is expected will use the A note below C
instead of the A note above C.

Scale bases use alphabetical order of the notes, rather than the order
specified in the {\tt\#SCALE} definition. Usually it is the same, although
this can differ so you should be careful about it.

\headII: \TT\#STEREO

Select stereo audio (default).

\headII: \TT\#SYNTH-LENGTH

\headII: \TT\#SYNTH16

If this command is activated, it causes raw samples that are imported and
any samples which are internally synthesized to use 16-bits, which can
result higher quality audio but larger file.

\headII: \TT\#TEMPO

Define initial tempo of song, in beats per minute, which must range from
32 to 255. The default value is 120.

The tempo can be changed later in the song by the {\tt t} command.

\headII: \TT\#TITLE

Set the song title, which will probably be displayed in a program that
plays this music. There is a maximum of 25 ASCII characters. You cannot
comment anything out on this line.

\headII: \TT\#TRACKER-VERSION

Allows you to change the value of ``Cwt'' field in the header of output.
By default it uses the hexadecimal number {\tt\$7xyz} for ITMCK version
x.y.z although you can change it to pretend to be a different program or
a different version.

\headII: \TT\#VOL0MIXOPT

This has the same effect as the {\tt-v} command-line switch.

\headII: \TT\#VOLUME

Set initial global volume, which must range from 0 to 128. Default setting
is 128.

\headII: \TT\#WHOLE-NOTE

Set the number of frames of a whole note, which must be greater than zero.
The default is 48 frames.

\headI: Channels

There are up to sixteen channels, labeled with the uppercase letters
{\tt A} to {\tt P}. Each channel plays notes individually and can have its
own settings for volume, panning, note length, transpose, special effects,
etc.

To define initial channel volume and panning, you can use the
{\tt\#CHANNEL} command or you may use a macro definition as follows:

{\tt@A = 30 40}

In this example, the channel being assigned is {\tt A} and the volume is
30 and the panning is 40. The volume ranges from 0 to 64. The panning
ranges from 0 to 64 (where 32 is centered), or enter 100 for surround
sound.

\headI: Song Message

A song message consists of any number of lines starting with {\tt"} and
followed by the text to place on that line. The text can include any ASCII
text, including semicolons and leading spaces. All of them are then put
together in the song message. This song message may be displayed in the
player. (Do not include another quotation mark at the end unless you want
it a part of the message.)

You cannot comment anything out on this line.

The song message should not exceed 8000 characters (counting line breaks
as one character each).

\headI: Samples

\headII: Synthesizer

\headI: Instruments

\headI: Music Entry

\headII: {\TT a}--{\TT j} (note letters)

\headII: {\TT l} (length)

\headII: {\TT n} (direct note entry)

\headII: {\TT o} (select octave)

\headII: {\TT q} (quantize)

\headII: {\TT r} (rest)

\headII: {\TT t} (tempo)

\headII: {\TT v} (volume)

\headII: {\TT z} (cancel effects)

\headII: {\TT C} (set note cuts)

\headII: {\TT G} (global volume)

\headII: {\TT I} (tremor)

\headII: {\TT J} (arpeggio)

\headII: {\TT K} (transpose)

\headII: {\TT L} {\TT||} {\TT|L} (song loop)

\headII: {\TT P} (panning)

\headII: {\TT Q} (retrigger)

\headII: {\TT R} (portamento)

\headII: {\TT T} (tremolo)

\headII: {\TT V} (vibrato)

\headII: {\TT X} (call macro)

\headII: {\TT Y} (panbrello)

\headII: {\TT[} {\TT]} (repeat)

\headII: {\TT<} {\TT>} (low octave/high octave)

\headII: {\TT\&} (slur)

\headII: {\TT\char`^} (tie)

\headII: {\TT/} (auto-portamento)

\headII: {\TT\char`\\} (synchronize channel)

\headII: {\TT@} (instrument select)

\headII: {\TT@@} (key table select)

\headII: {\TT@e} (direct effect entry)

\headII: {\TT@q} (quantize)

\headII: {\TT@u} (effect table select)

\headII: {\TT@A}--{\TT@P} (channel select)

\headII: {\TT@`} (ask status)

\headII: {\TT@=} {\TT@+} {\TT@-} {\TT@*} (assign variable)

\headI: Macros

\headI: Key Tables

\headI: Effect Tables

% === End main document text ===

\let\TT=\tentt
\let\Tt=\tentt

\vfill\eject
\immediate\closeout\tocfile

\headline={}
\footline={}

\def\dotleaders{\leaders\hbox{ . }\hfill}
\def\tocI#1#2{\line{#1 \dotleaders\ #2}}
\def\tocII#1#2{\line{\quad#1\rm\ \dotleaders\ #2}}
\def\tocIII#1#2{\line{\qquad#1\ \dotleaders\ #2}}

\vfill
\line{\headIfont Table of Contents\hfil}
\bigskip
\input\jobname.toc
\vfill

\bye