Index
*****

OCP is a music file player.  It is derived from the _Cubic Player
2.0appe_ which was developed by Niklas Beisert.  The latest version of
UNIX port is 0.1.20 See install on how to get a copy of OCP.

   OCP is published under the GNU General Public License (GPL). That
means you can use this software without charging for it.  However OCP is
not in the public domain!

   The source code is available to the public and everybody is
encouraged to make changes to it.  Please send any modifications and
bugfixes to the authors.  The authors do not take any warranty for any
damages whatever kind produced by this software.  For further details
see the file <http://www.gnu.org/copyleft/gpl.html>

   This documentiation falls under the GPL license.

   Copyright (C) 2005 Stian Skjelstad.

   Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.

Users Manual

Developers Manual

1 Installation and files
************************

1.1 Installation
================

Some UNIX variants allready have Open Cubic Player in their packaging
systems.  If not, you are going to need to download the source and
extract it.

     wget http://stian.lunafish.org/ocp/ocp-0.1.20.tar.bz2 tar xfz
     ocp-0.1.20.tar.bz2

   Please make sure that you have development-packages of the following
libraries installed:

   libmad libsidplay 1.x libvorbis / libogg ncurses Xlib libXpm

   To compile and install do the following

     cd ocp-0.1.20 ./configure && make install

   If configure complains about any-missing headers/libraries, please
consule the list above needed libraries.

1.2 Files
=========

When OCP loads a module the information stored inside the file is read
and stored in a special file( the _module information cache_.)  Actually
the cache splits up into three files:
   * CPARCHS.DAT Information about archives and files stored inside
   * CONDZTAG.DAT Paths to '.MDZ' files (see appendix mdz.)
   * CPMODNFO.DAT Informations about various modules
   If you delete these files all file information gathered is
permanently lost.

   The 'doc' directory contains documentation files in various formats
and release notes etc.  You can safely delete this directory if you are
running out of disk space.

1.3 OCP and ALSA (linux)
========================

OCP doesn't support ALSA directly, since OCP is written for OSS which is
cross-platform.  Please load 'snd-pcm-oss' and 'snd-mixer-oss', to
provide a legacy OSS interface from ALSA.

2 Starting Open Cubic Player
****************************

When starting OCP, it first tries to setup a directory in your
home-directory where cache and configuration will be stored, aswell at
locating where OCP has installed its main files.

   OCP then tries to detect the sound cards defined in the 'ocp.ini'
file.  If the card is not found you cannot use it.  If more than one
sound card is installed and found by OCP the first one listed in the
'ocp.ini' is used as the default device.(1)

   By entering a filename as parameter onto the command line you can
load a module.  If a filename is given the file will be loaded and OCP
starts with the player.(2)  When the parameter is the name of a
directory the fileselector starts with the given directory.  If the
parameter equals a certain archive all files found inside the archive
will be played (by adding them to the playlist).

   If more than one parameter is given a playlist will be set up,
containing all found files.  You can mix filenames of archives, files in
archives and normal files on the hard disk.

   You normally don't have to supply the right file extensions, as they
are guessed by the fileselector.  If the filename is not complete the
file will not be processed (unlike the quickfind function).

   OCP can be configured using the command line, although the
configuration through the 'ocp.ini' file is more comfortable.  The
options split up into three main sections each starting with "-"
followed by a letter.  For each section different options are given,
which will configure the player accordingly.  You can precede each
option with the section prefix every time or supply multiple options
seperated with ",".  Some special options do not require the use of a
sections prefix, like the _help_ switch.

   The command line looks like:
     ocp [prefix option[,option]] [specialOption] [filename](3)

   Special options include:
   * -h show a help screen
   * -c<name> use a configuration defined in 'ocp.ini'

   Fileselector options are envoked with _-f_.  The values in square
brackets define a choice that must be made when using one of these
options.
   * -r[0|1] remove played files from playlist
   * -o[0|1] don't scramble playlist order
   * -l[0|1] loop modules

   Playback options are preceded by _-v_.  Values in sharp brackets
define a range in which the value must be taken.
   * -a<0..800> set amplification
   * -v<0..100> set volume
   * -b<-100..100> set balance
   * -p<-100..100> set panning
   * -r<-100..100> set reverb
   * -c<-100..100> set chorus
   * -s[0|1] set surround
   * -f[0|1|2] set filter (0=off, 1=AOI, 2=FOI)

   Device setting are accomplished with the suffix _-s_.
   * -p<name> use specific player device
   * -s<name> use specific sampler device
   * -w<name> use specific wavetable device
   * -r<0..64000> sample at specific rate
   * -8 play/sample/mix as 8bit
   * -m play/sample/mix mono

   Finally an example to illustrate the above features:
     ocp -fl0,r1 -va80,p50,f2 -spdevpdisk -sr44100 ftstar.xm

   This will start OCP and load the file 'ftstar.xm'(4).  The music will
be played once and will not loop _(-fl0, r1)_.  Further the player is
advised to amplify this file with 80%, set the panning to 50% and
interpolate every sample (_-va80, p50, f2_).  The mixed output will be
saved into '.wav' format through the Using the diskwriter,
device (_-spdevpdisk_) with a sample rate of 44.1KHz (_-sr44100_).

   You can burn this WAV file directly onto a CD-Audio and play it with
every normal CD player.  A much simpler and more convinient way to make
such a _sample image_ of a module is by using predefined configurations
with the _-c_ switch.  Have a look at Using the diskwriter.

   ---------- Footnotes ----------

   (1) You can change this in the player by using the 'setup:' device.
See page specialdrive, for detail.

   (2) This will work if the file is inside an archive located in the
current directory.  If no (unpacked) file is found all archives in the
current directory are searched for an appropriate filename.

   (3) Square brackets [] indicate an optional item that can be
repeated.

   (4) A marvelous piece of music composed by KB which won The Party
1997.

3 Fileselector
**************

If OCP is started without any command line arguments the fileselector
will be loaded.  With this powerful tool you can browse through your
modules and set up playlists to be processed by the player.  If you
switch to the player the selected files will be loaded and processed.

   Files can be stored inside compressed archives to save space on the
hard disk.  Those files are automatically unpacked to a temporary
directory before scanning or loading.  If you have many modules you
should use this feature, as storing modules inside archives is totally
transparent when using the fileselector.

3.1 Main screen
===============

The fileselector splits into three main windows: directory list,
playlist and module information as shown in figure bellow.

     ###### TITLE BAR #######
     X:/PATH/
     ------------------------
                     |  P
                     |  l
      Directory list |  a
                     |  y
                     |  l
                     |  i
                     |  s
                     |  t
     ------------------------
      Moduleinfo
           [Quickfind]

   The path window shows the current path and file mask.  If you started
OCP from the home directory you will get the following: 'file:/OPENCP/*'
means that the current directory is 'OPENCP' on your 'file:' driver and
all files are shown ('*').  You can edit the path and the mask by
pressing <ALT>+<Enter>.  After editing the path press <Enter> to change
to the appropriate directory.  You can edit the file mask to include
only some files.
     'file:/*.mod' will change to the root directory of filesystem and
     show all files ending with '.mod'.  The default setting should be
     the current directory with a file mask '*' to show all files.

   The most important window is the directory list.  Here you can see
all files in the current directory.  If the extension is known to OCP
the file information will be shown in different colors depending on the
file type.  Files not known to OCP will be shown in standard grey.

   Leftmost the file name provided by the operating system is shown.
The extension '.???' will specify the file type.  The next column shows
the title of the file if the file type includes a title.  In the third
column the number of channels is displayed.  Finally rightmost the
filesize is shown in bytes.  If the module is included in a ZIP archive
the _real_ file size is displayed.

   Right to the directory list you can see the play list.  All files
listed in this window will be played, after you change into the player.
The order of entries in this window determine the order in which files
are loaded unless you have enabled the _random_ option.

   The window at the bottom is the module information.  Many music
formats can store general information which is displayed here.  If the
file type does not support those information you can edit the fields
inside this window manually and OCP will store the information for you.

   Finally at the very bottom is the quick find feature, which lets you
easily find files in the current directory.

3.2 Usage of the fileselector
=============================

The directory list shows you all files in the current directory which
fit to the file mask set in the path window and OCP can detect.  Under
the alphabetically sorted files the directories and drives are shown.(1)
Use the <Up> and <Down> to browse through the files.  If you press
<Enter> the selected file will be loaded and played with the player.
Pressing <Enter> while selecting a directory or drive will switch to the
selected item and the directory will be read.  <Pgup>, <Pgdown>, <Home>
and <End> will work as expected.

   If a module is played and you are in the player <f> will beam you to
the fileselector.  You can always leave the fileselector by pressing
<Esc> twice!  If no module is playing the program will exit, while you
will get back to the player if a module is played in the background.

   Playlists are shown in the playlist window at the right side of the
screen.  The currently selected file is appended to the playlist by
pressing <Right> or <Ins>.  <Left> or <Del> will remove it again.  You
can insert files multiple times into the playlist by pressing the
appropriate keys more than once.  If you have files in the playlist exit
the fileselector by pressing <Esc>!  This might seem confusing in the
beginning, but you will notice the logic very soon.  In the player you
start the next song in the playlist by pressing <Enter>.

   Normally you will start the fileselector from the player by pressing
<f>.  The current module will continue playing in the background.  After
you have selected a file you have to choices:
   * <Enter> will stop the currently played module and load the selected
     one.  Then you will get back to the player.  Use this key if you
     want to play the selected module immiediatly.
   * <Esc> will change to the player.  Then you can start the next songs
     in the playlist by pressing <Enter>.  If you have inserted files
     into the playlist use this key to exit the fileselector.

   All files in the current directory will be inserted into the playlist
by pressing <CTRL>+<Right> or <CTRL>+<Ins>.  The playlist will be
deleted by pressing <CTRL>+<Left> or <CTRL>+<Del>.

   Although in the playlist window only the filename is shown, OCP
stores the complete path information.  So you can insert files into the
playlist from totally different directories and drives.  If files are
inserted into the playlist you can change to the playlist window by
pressing <Tab>.  Inside the playlist window all keys have full
functionality.  So you can load the selected module immiediatly by
pressing <Enter> or remove the file from the list by pressing <Left>.
If you are in the playlist window you can move the currently selected
file by pressing <CTRL>+<Up> and <CTRL>+<Down>.  This will affect the
order in which files are processed.
<CTRL>+{<Pgup>,<Pgdown>,<Home>,<End>} work as expected.

   If many files are inside a directory selecting a module with the
cursor keys can be annoying, because it takes a long time to browse
through the list.  If you know the filename you can start typing it on
the keyboard.  This enables the quickfind feature.  Characters already
typed are shown in the quickfind window.  The current directory is
searched for files matching the typed characters.  Often you don't have
to type the complete filename, as it can be already determined by the
leading chars.  The typed characters must not fit the file exactly as
small errors are neglected.

   At the bottom of the screen the fileinformation window is located.
If the file includes any additional information it will be shown at the
appropriate fields.  You can edit each entry manually.
All module information is read by
the fileselector once if it runs along this module the first time. The data
is stored in three files located in your home directory of OCP refered as the
_module information cache_. If the fileselector scans a directory and finds
a module already stored in the module information cache it will use the
information found in the cache. This way you can overwrite the information
fields of the module. If you change to a directory which has not been processed
by the fileselector it may take some time to read all file information out of
the files and store them in the module information cache.

   To switch to the module information window press <SHIFT>+<Tab>.  You
can use the cursor keys to select the entries.  After pressing <Enter>
the information can be edited.  When pressing <Enter> again the changes
are stored in the module information cache.  Note: _Do not change the
entry type as the file could not be loaded properly when the wrong
filetype is entered!  Normally you never have to change this entry,
except for old 15 instruments amiga noisetracker modules!_

3.3 Advanced usage
==================

The appearance and behaviour of the fileselector can be edited in the
'ocp.ini' (see ocp.ini) file or by pressing <ALT>+<c>.
Changes made to the 'ocp.ini' are permanently, while configuration
applied with <ALT>+<c> is only valid while OCP is running.

   Afer pressing <ALT>+<c> you can toggle 13 options with keys <1>..<9>
and <a>..<d>.  The following list will explain every option:
1       _screen mode:_ you can change the screen mode for the
        fileselector.  80x25 and 80x50 are standard screen modes and
        should be available on every vga card.  80x30, 80x60, 132x25,
        132x30, 132x50 and 132x60 are only available with a proper VESA
        bios installed.
2       _scramble module list order:_ if this options is enabled the
        files inside the playlist will be played in random order.
        Otherwise the order shown in the fileselector from top to
        bottom will be used.
3       _remove modules from playlist when played:_ normally you will
        want this enabled as modules are only played once.  If you
        disable this option you playlist can be processed foreever.
4       _loop modules:_ if the music file ends it will start again.
        The next file will be played after pressing <Enter>.  If you
        turn off this option the playlist will play all modules without
        any user interaction.
5       _scan module information:_ When entering a directory the files
        are processed to gather module information which can be shown.
        If you disable this option directories will be processed
        quicker.
6       _scan module information files:_ the module information cache
        in the home directory of OCP will be read if this option is
        enabled.
7       _scan archive contents:_ to save hard disk space you can store
        your files inside archives like 'ARJ' or 'ZIP'.  If the
        fileselector finds an archive it will open it to scan for
        files.
8       _scan module information in archives:_ if modules are found
        inside archives they will be decrunched to find any module
        information.  This option can take several minutes if many
        modules are stored in archives
9       _save module information to disk:_ toggles weather to save
        gathered informations in the module information chache.
A       _edit window:_ If you don't want the module information window
        at the bottom disable this option.  The directory and playlist
        windows will spawn over the complete screen.
B       _module type colors:_ different file types are shown in
        different colors on the screen.  When watched on monochrome
        monitors or laptops you might want to disable this option.
C       _module information display mode:_ changes the contents of the
        directory window.  You can also use <ALT>+<tab> or <ALT>+<i>
        inside the fileselector.
D       _put archives:_ Show archives, so they can be accessed like
        directories.  Normally this should be disabled if archives are
        scanned automatically.

   The screen size can be changed by pressing <ALT>+<z>.  In 132 columns
mode some additional module information can be shown in the directory
window.  If the fileselector is busy scanning the current directory for
files, you can interrupt the scanning with <ALT>+<s>.

   You can delete a file with <ALT>+<k>.  You will be prompted if you
really want to delete this file.  When pressing <y> the file will be
deleted.  If the file is stored inside an archive the file will be
deleted from the archive.(2)  The current file can be moved by
<ALT>+<m>.  You will have to type the new path in the path window into
which the file will be moved.  If the file is inside an archive it will
be extracted.  You can specify an existing '.ARJ' file and the file will
be packed into the archive.(3)

   The module information shown in the module information window can be
saved to a portable ascii file (see page mdz).  You may want
this feature if you are a composer of music and want to trade your music
together with already processed module information files.  Start the
fileselector and edit the information for the file.  Then switch back to
the directory window and press <ALT>+<w>.  The fileselector will save a
file with the extension '.MDZ' and the filename of the selected file,
which stores all module information seen in the module information
window.  If a directory is scanned and the fileselector finds such
'.MDZ' files they will be read and processed.  The module information
for all files in the current directory can be saved with <ALT>+<a>.  You
have to type the filename manually in the path window without extension!

   You may want to change the entry _type_ in the module information
window if you have old amiga modules or a non-standard midi file.  Very
old Noise- and SoundTracker modules only had 15 instruments and no file
identification.  So the fileselector is not able to detect those files
as valid modules and refuses to play them.  You have to insert 'M15' in
the _type_ entry.  If the module does not differ between tempo and speed
and is of the 15 instrument type insert 'M15t'.  Some ProTracker modules
do not differ between tempo and speed too.  If you have one of those
modules use 'MODt'.  A module player for PC called DMP introduced a
feature called panning.  To enable this (non-standard) feature insert
'MODd'.  If you want to play midi files with a second drum track on
channel 16 use the 'MIDd' option.  Any other file should be autodetected
correctly.
If you have renamed a module
to a different extension (say 'hello.mod' to 'hello.s3m') OCP
will refuse to play it, because the file type is wrong. You could correct this
by inserting the right file type in the module information as shown above. But
it is recommended to rename the file to the right extension instead of tweaking the
autodetetion of the player.

   The current playlist can be saved into the .PLS format by pressing
<ALT>+<p>.  You have to type the filename without extension in the path
window.  A standard extension '.PLS' is appended.  The playlist can be
loaded just like any other module from the fileselector or at startup.

   The drive 'setup:' is a special device which can be used to change
the hardware configuration without leaving the player.  If you access
this drive you will see two subdirectories.

   In the 'INPUTS' subdirectory you can choose the device which will be
used when sampling from external sources (when playing CD audio tracks
or starting OCP in sample mode).  The 'DEVICES' directory displays all
devices which where detected at startup.  Normally you might want to
change this if you want to save the next file as a '.WAV' or '.MP2' file
to the harddisk.(4)

3.4 bigmodules
==============

The above behaviour can be avoided if a file is marked _big_ by pressing
<ALT>+<b> in the fileselector.  The filesize will turn red.  Now a file
will not be loaded into the soundcard memory, but played with the
internal mixing routines.  This limits the size of files only to the
size of physical memory.(5)

3.5 Reference
=============

<a>..<z>                  quickfind
<ALT>+<a>                 write module information '.mdz' for directory
<ALT>+<b>                 mark module "big"
<ALT>+<c>                 configure fileselector
<ALT>+<d>                 goto DOS
<ALT>+<i>                 change display mode for directory window
<ALT>+<k>                 delete file
<ALT>+<m>                 move file
<ALT>+<s>                 stop scanning module information
<ALT>+<w>                 write module information '.mdz' for selected
                          file
<ALT>+<z>                 toggle screen mode
<Up>, <Down>              move cursor one entry up/down
<CTRL>+{<Up>, <Down>}     move module up/down on playlis
<Right>, <Ins>            add file to playlist
<Left>, <Del>             remove file from playlist
<CTRL>+{<Right>, <Ins>}   add all files to playlist
<CTRL>+{<Left>, <Del>}    clear playlist
<Pgup>, <Pgdown>          move cursor one page up/down
<CTRL>+{<Pgup>,           move module one page up/down in playlist
<Pgdown>}
<Home>, <End>             move cursor to top/bottom of the list
<CTRL>+{<Home>, <End>}    move module to top/bottom of playlist
<Enter>                   play selected file
                          change to directory/archive/drive
                          edit entry (in module info window)
<ALT>+<Enter>             edit path window
<Tab>                     change between directory and playlist
<ALT>+<Tab>               same as <ALT>+<i>
<SHIFT>+<Tab>             change to module info window
<Esc>                     exit fileselector

   Supported filetypes - valid options for the _type_ entry in the
module information window.
669     669 Composer module
AMS     Velvet Studio module
BPA     Death Ralley archive
CDA     compact disk CD audio track
DMF     X Tracker module
IT      Impulse Tracker module
MDL     Digi Tracker module
MID     standard midi file
MIDd    standard midi file, channel 16 is a second drum track
MOD     amiga ProTracker 1.1b module
MODt    amiga ProTracker 1.1b module, effect Fxx is tempo
MODd    amiga ProTracker 1.1b module with effect 8xx is panning
MODf    pc Fast Tracker II .mod file
M15     amiga NoiseTracker module with 15 instruments (plays like
        ProTracker 1.1b)
M15t    amiga NoiseTracker module with 15 instruments, effect Fxx is
        tempo (plays like ProTracker 1.1b)
MP3     MPEG audio format level 1-3
MTM     Multi Tracker module
MXM     Mxmplay module
OGG     Ogg Vorbis sound stream
OKT     Oktalyzer module
PLS     OCP playlist, works also with M3U and PLT playlist files
PTM     Poly Tracker module
S3M     Sream Tracker 3 module
SID     PSID sid file
UMX     Unreal module file
ULT     Ultra Tracker module
WAV     Microsoft RIFF wave file
WOW     WOW Tracker module
XM      Fast Tracker 2 module

   ---------- Footnotes ----------

   (1) 'setup:' is a special drive which lets you configure OCP without
editing the 'cp.ini' file, see page specialdrive.

   (2) If only one file was stored inside a '.ZIP' archive pkzip will
leave an empty archive of 22 bytes on your harddisk.  See ocp.ini
on how to avoid this.

   (3) this works only with ARJ archives by now.

   (4) See Using the diskwriter.

   (5) You have to apply a valid _playback-_ and _mix-device_ to use
this feature.  See ocp.ini for details.

4 Player
********

When OCP is started with a valid filename the file is loaded and the
player interface is started.  This is the main part of OCP and you have
various ways to display all kinds of music information and data.

4.1 General
===========

OCP displays general (status) information in the first 4 rows.  Some of
these entries can be changed by the user, others are static for each
module.  The following list will explain every entry.(1)
vol     The bar display the current playback volume.  The default value
        is 100% or full volume.  To change the volume press <F2> and
        <F3>.  This will change the volume by one dot each time you
        press a key.  The keys <+> and <-> on the numeric keypad will
        change the volume smoother.
srnd    Toggle this option with <F4> to enable a simple surround
        effect.
pan     If a voice should be played on the right speaker you can
        rearrange the stereo panning with this entry and <F5>,<F6>.  To
        get mono sound adjust the two _riders_ to the middle.
bal     Just like the device on your stereo this option works.  Press
        <F7>,<F8> to adjust the stereo balance between full left and
        full right.
spd     The playback speed can be changed with <F9>,<F10>.  (2)
ptch    The pitch of the file can be altered with <F11>,<F12>
row     Most files of the module type are divided into rows and
        patterns.  The first number shows the currently played row.
        The second number shows the total number of rows in the current
        pattern.  All numbers are shown in hexadecimal format.
ord     Modules are divided into several orders consisting of patterns.
        The first number shows the currently played order.  The second
        number shows the total number of orders.(3)  All Numbers are
        shown in hex.
tempo   the current tempo of the file.
bpm     These are not the physical beats per minute, but rather the
        speed at which the file is played (only valid for module
        types).  This option is often refered by Trackers as BPM.
gvol    Some file formats allow a global volume to be set.
amp     This option lets you adjust an amplification.  You can adjust
        this value with <CTRL>+<F2>, <CTRL>+<F3>.(4)
filter  You can select different types of interpolation by pressing
        <Backspace>:
        off - no interpolation
        AOI - OCP tries to determine if interpolation is neccessary for
        each note and sample indepentantly.  This is the default option
        and should be enabled.
        FOI - every sample is always interpolated.  This option uses
        more processor power as AOI.
module  shows the filename currently played and the title of the file
time    time since starting the current file

4.2 Global functions
====================

Below the general information is a dark grey line.  On the left side of
the line the current screen mode is shown.  In the middle a list of
channels.  Each file type has a maximum number of channels played
simultaneously.  For example simple file formats as '.WAV' can have one
or two channels (responding to a mono or stereo sample).  An audio CD
always has 2 channels (left and right).  Module file types can have many
channels typically ranging from 4 to 32 channels.

   The currently selected channel is displayed in light grey.  To select
another channel use <Left>,<Right>.  You can also use <Up>,<Down> which
will loop through the channels if the left or right end is reached.

   Pressing <q> will _quiet_ the selected channel.  This key is valid in
every part of the player.  To enable the channel press <q> a second
time.  The reverse logic can be accomplished with <s>.  This disables
all other channels than the selected, so only one channel plays solo.
Another hit on <s> will _unsolo_ the channel again, so playing all
channels.  You can use any combination of the above keys.  An example:
Select channel 1 and press <s>.  Now you will hear only channel 1.  Go
with the cursor keys to channel 3 and press <q>.  As the channel is
currently turned of (quiet) is it now played again.  so you hear
channels 1 and 3.  Now switch to channel 2 and press <s>.  Now only
channel 2 will be played, whiche channel 1 and 3 are turned off again.
By pressing <s> again all channels are enabled.

   You can directly _solo_ the first 10 channels by pressing keys
<1>..<0>.  This will act as if you had changed to the appropriate
channel and pressed <s>.  Channels 11-20 are accessed through
<ALT>+<1>..<ALT>+<0>.

   To pause the file press <p>.

   The current file can be restarted by pressing <CTRL>+<Home>.  To move
a bit forward use <CTRL>+<Right>.  If a module is played this will skip
the current order and start playing the next order.  In other file types
this command skips a certain amount of time, depending on the estimated
playing time.  <CTRL>+<Left> will rewind the music.  This is not
possible for all file type (midi or sid files).  When playing modules
the current order is skipped and the previous order is playing from the
beginning.  To skip a smaller amount of the file use <CTRL>+<Up> and
<CTRL>+<Down>.  This will skip 8 rows when playing modules.  If the
files support jump or loop command using these functions can lead you to
patterns not included in the original play order!  Be aware that using
these funtions can lead to somewhat crashed files.(5)

   The next file in the playlist can be loaded with <Enter>.  If no more
files are left in the playlist the fileselector will be started so you
can choose the next files.  However the current module will continue
playing.  By pressing <Esc> you can switch back to the player again.
The fileselector can also be invoked with <f>.  The current playlist is
shown and can be edited.  When exiting the fileselector with <Esc> you
can load the next module in the playlist with <Enter>.  Leaving the
fileselector with <Enter> will load the currently selected module and
switching back to the player.

   By default a module is looped after its end was reached.  You can
change this behaviour by configuring the file selector (6) or with
<CTRL>+<l>.  When looping is disabled the next module in the playlist
will be loaded once a module has ended.  If no modules are left in the
playlist the fileselector is started.

   A DOS-Shell will be started when typing <d>.  Note that OCP uses
about 200KB so not all programs might start or execute properly.
However it should be enough to make simple tasks like copying, deleting
etc.  When running under Windows95 the free amount of memory should be
the usual size.

   The screen mode can be changed by pressing <z>.  This will toggle
between 25 and 50 rows textmode, while <CTRL>+<z> toggle between 30 and
60 row textmode.  <ALT>+<z> will toggle between 80 and 132 column
mode.(7)

   The current configuration can be "saved" with <ALT>+<F2>.  It is not
stored permanently on hard disk, but only valid until OCP is quit.
Normally the default configuration is loaded every time a new file is
loaded.  This function makes the current configuration the new default
configuration.  A previously saved configuration can be loaded with
<ALT>+<F3>.  The _real_ default values are loaded with <ALT>+<F4>.  To
modify the default values permanently you have to change the 'ocp.ini'
file as explained on page ocp.ini.

   An online help is shown by <h>, <?> or <F1>.  Use <Pgup> and <Pgdown>
to scroll through this screen.

   Users of SoundBlasterAWE, Terratex EWS and Gravis Ultrasound PnP can
use <CTRL>+<F5> and <CTRL>+<F6> to adjust the onboard reverb effect.
The SBAWE can also add a chorus effect which is controlled via
<CTRL>+<F7> and <CTRL>+<F8>.

4.3 Text mode functions
=======================

The player has two different operating modes.  Text mode and graphics
mode.  In text mode you can enable various functions at once, while in
graphics mode only a single function can be shown.

   Because there can be more than one text mode funtion visible at the
same time you might have to press the according key more than once to
get the wanted effect.  Each function can be in one of the following
states:
   * invisible - inactive
   * invisible - active
   * visible - inactive
   * visible - active
   When pressing a key the according funtion is made active, but left
invisible.  By pressing the same key a second time the function will be
made visible.  An active function can be recognized by their title
string displayed in bright blue, while inactive functions have their
title string displayed in dark blue.  Keys affecting the funtions are
only processed for the currently active mode.  So it might be necessary
to change to the appropriate mode by pressing its key once to manipulate
its behaviour.

   In the 132 column mode only one of the instruments* and channels*
fields is active and used by the appropriate function.  If a function is
not visible the space is used by the other visible functions.

4.3.1 Channels
--------------

The channel function is invoked with <c>.  The channels appear in two
different modes.  By default the short mode is enabled.  Two channels
are shown in one row.  A grey number shows the channel number.  Left to
it a white number shows the currently played instrument / sample on this
channel followed by the note.  If the note starts to play it is shown in
cyan for a short while.  The third number shows the current volume at
which the intrument / sample is played.  Behind the volume the current
effect is shown.(8)  At the rightmost of each entry the current
(physical) volume splitted among left and right output channel is
displayed in a bar graph.

   The currently selected channel is indicated by a small white $>$ to
the left side of the channel number.  When a channel is muted with <s>
or <q> it is shown in dark grey.  However OCP continues to play this
channel, so that the music sounds correctly when turning on this channel
again.

   When pressing <c> twice the channel function switches to the long
format.  Each channel now uses a single row as more information is
beeing displayed.  From left to right this is as follows: channel
number, instrument / sample name, current note, instrument / sample
volume, pan position, current, volume.  (9)

   If the textmode is changed to 132 column mode the channel function
can be displayed in short form at the upper right corner of the desktop.

   If there are more channels than space inside the screen area OCP will
scroll automatically through the channel list when you use the cursor
keys.  This is indicated by white up and down characters.

The channel function has no title string which could indicate
if it is active or inactive. So you might have to press <c> one
time more often if the channel function was previously inactive.

4.3.2 Instruments
-----------------

If the current file a module (or midi) the used instruments / samples
are shown with the instruments function.  The instruments are shown with
<i>.  Just like channels instruments come in two formats, short and
long.

   In the short view only the intrument names are shown giving you space
for two instruments per row in 80 column mode (4 instruments are shown
in 132 column mode).  An instrument / sample that is currently played is
shown in bright cyan.  If the sample is played ont the currently
selected channel it is shown in bright green.  All inactive intruments
are drawn dark grey.  If a sample has been played once a rectangular dot
is placed left to the intrument number.

   When the intruments are switched to long mode various information is
displayed.  From left to right this is as follows:
   * a number from 00h to FFh giving the instrument number
   * instrument name
   * sample number (when using multiple samples per instrument)
   * sample name (only in 132 column mode)
   * length of the sample in bytes
   * length of the loop in bytes
   * bits per sample
   * the base note.  For modules the default is C-4
   * finetune value
   * standard volume at which the sample is played
   * standard pan position
   * various flags (volume, pan envelopes etc.)
   * fadeout value (only in 132 column mode)

   Often a file includes more instruments than can be shown on the
screen.  Use <Pgup>,<Pgdown> to scroll through the instruments.  If the
instrument function is active <CTRL>+{<Pgup>, <Pgdown>} will scroll for
a complete page.  When inactive you can scroll single lines by using
<CTRL>+{<Pgup>,<Pgdown>}.  This is very useful if you have enabled more
than one textmode function.

   The instrument flags (the rectangular dots left to the instrument
number) are cleared with <ALT>+<i>.  By pressing <Tab> you can toggle
between the color mode and pure grey.

4.3.3 Pattern view
------------------

Modules are arranged in patterns.  You can view these patterns with the
pattern view function envoked with <t>.  When enabling this funtion OCP
tries to display all channels at once using the best display possible.
For modules using few channels (<8) this default display is normally
acceptable, but you might want to change it when playing modules with
many channels.

   The pattern is shown in different columns.  At the leftmost the row
number is shown in hex.  If the screen mode and pattern view allows the
row number is shown again at the right side of the screen.  Then follow
some fields for global commands the module might contain.  The biggest
section of the screen use the channel columns, each one displaying on
single channel indicated by the number on top of the column.  Inside
such a channel column various information can be displayed depending on
the amount of space available.  You can see the format of a channel
column in the status line of the pattern view.  The format of the column
can be changed by pressing <Tab>.  As there are many combinations of
screen mode, channels and formats I will not go into detail here.

   The number of channel rows displayed at once can be changed by
pressing <Pgup>, <Pgdown>.  Normally the pattern view will follow the
music as it progresses.  With <Space> the pattern view will stop.  The
current play position is now displayed with a white special char.  You
can now browse through the module with <Pgup>,<Pgdown>.  <Space> will
enable the follow mode again, bringing the pattern view to the current
play position.

   The pattern view displays the different effects used in modules with
different colors.  Green is used for effects affecting the pitch of the
sample, while blue command change the volume.  Effects drawn in purple
change the pan position.  Red colors indicate the manipulition of the
timeslice effected with this samples.  Other effects are drawn white.
Please have a look inside the online help <h>, <?> or <F1> for a
complete reference on the effects shown.

4.3.4 Spectrum Analyzer
-----------------------

The spectrum analyzer uses the fast fourier transformation to gather
information on the audio spectrum used in sample data.  The analyzer is
started with <a>.  This function splits the sound data into many _bands_
of pure sine waves.  This is called the spectrum of the sample.

   The status bar of this function shows you the range each bar covers
and the highest frequency processed (the rightmost bar corresbonds to
this frequency).  Use <Pgup>, <Pgdown> to change the range.  <Home> will
set the default value of 2756Hz.(10)

   With <ALT>+<a> the mode of the spectrum function can be toggled.
Stereo using two analyzers, mono using only one and a single mode are
available.  In the single mode the currently selected channel is used as
sound source for the analyzer.

   <Tab> changes the color used for the analyzer.

To get a smooth view the default charset of the graphics
adapter is modified. This is working fine with every graphics card
under MS-DOS. However Windows95 does not allow the manipulition of
characters, so the spectrum analyzer function is not shown properly
when running under Windows95 (window-mode only). If you see a
distorted screen while using the spectrum analyzer function this is
normal.

4.3.5 peak power levels
-----------------------

This function shows the current physical volume of the output channels
in a bar graph.  You can use <v> to make this function visible -
invisible.  In the 132 column mode the levels can also be shown at the
right side of the screen.

4.3.6 Volume control
--------------------

You can browse through the different items with <Up> and <Down>.  If you
want to change a value, try <Left> and <Right>.  You can also toggle
between a short mode, a long mode (only in 132 column modes) and
invisible mode with <m> (Volume control is disabled in 80 column modes
and enabled in 132 column modes by default).

4.3.7 Module message
--------------------

Some file types store messages which can be viewed with <ALT>+<F9> like
in Multi Tracker.  If the message is long use <Pgup>, <Pgdown> to
scroll.

4.3.8 eXtended mode
-------------------

All four text mode functions can be displayed simultaneously.  This
function enables channel, instrument, spectrum analyzer, pattern view
and volume control function with a good preset in text mode.  <x> will
enable 132 column mode.  <ALT>+<x> will switch to the default 80x25 mode
with channel and instrument functions enabled.(11)

4.4 Graphic mode functions
==========================

The default graphics mode is 640x480x256.  Only one graphics mode
function can be shown at once.  The screen therefore splits into the
general window at the top side showing the usual informatin and the
function window covering the rest of the screen.

   If you have included a background picture in the 'ocp.ini' it will be
shown in the graphics modes (expect the graphical spectrum analyzer).

4.4.1 Oscilloscopes
-------------------

The oscilloscopes are started with <o> and come in 4 different modes:
logical (the channels are sorted with the default panning position),
physical (channels 1 to n from top to bottom), master (the mixed output
channel(s)) and single (the currently selected channel is shown).

   By pressing <Tab> you can enable/disable triggering of the scopes.
If the output is triggered a wave on the screen always starts with the
upper halvwave.  If triggering is turned off the wave will be drawn from
the current position.

   The scale of the scopes can be altered with <Pgup>, <Pgdown>.

4.4.2 Note dots
---------------

<n> starts the note dots function.  Each channel is displayed on a
horizontal row.  The current note is represented by a dot or bar.  Low
notes are placed on the left side.  High notes appear on the right side
of the screen.  By pressing <Pgup>, <Pgdown> the scale of the rows can
be changed.  However the default scale fits the usual note scale of
modules exactly, so there should be no need to change.

   By pressing <n> you can alter the output appearance of the dots.  In
the modes _stereo note cones_ and _stereo note dots_ the current pan
position is indicated by the left / right half of the icon.

4.4.3 Graphical Spectrum Analyzer
---------------------------------

The graphical spectrum function works in two video modes.  By pressing
<g> you will see the standard 640x480 mode.  <SHIFT>+<g> will start the
spectrum in 1024x768 mode.  Apart from this difference the two video
modes are equal.

   Pressing <g> more than once toggles between the usual stereo, mono
and single channel mode for calculating and showing the spectrum.
<Pgup> and <Pgdown> adjust the frequency range.  <Home> will set the
frequency to 2756Hz.  To half the resolution (and yet speed up the
calculation) press <ALT>+<g>.

   <Tab> change the palette of the graphical spectrum.  <SHIFT>+<Tab> do
the same for the standard spectrum analyzer at the bottom.

If you have difficulties interpreting this function here is a
short explanation.  The standard spectrum analyzer at the bottom shows
you the frequency spectrum at the current moment. The higher a single
bar, the louder the frequency. Now imagine looking at this spectrum
from top, now every bar becomes a single dot.  The height of the bar
is now coded into different colors (from black leftrightarrow low
to yellow leftrightarrow high). Now we can draw these point along
the screen and see the spectrum as is progresses over time. This is
somewhat a "3D" view of the spectrum, with the frequency coded along
the y-axis, intensity coded in different colors and the time along the
x-axis.

4.4.4 Phase graphs
------------------

The last graphical function is started with <b>.  You can toggle between
four modes which correspond exactly to those in the oscilloscope mode.
This function displays the currently played samples in a phase graph.
One full wave of the sample is drawn over the complete angle of a
circle.  The louder the sample the greater the radius of the circle.  A
sine sample would respond to a normal circle.

4.4.5 Wurfel mode
-----------------

With <w> the wurfel mode is enabled.  It's only purpose is to display an
animation located in the home directory of OCP. The <Tab> key will
change the play direction.
To save
diskspace no animations are included in the distribution of OCP.  They
can be found on the OCP homepage (page <http://www.cubic.org/player>).
Animations can be generated with the wap program from bitmap
files.(12)

4.5 Using the diskwriter
========================

OCP can write all sound output directly to hard disk.  Data is written
in standard '.wav' format.  You can use this feature to burn audio cds
from any sound format supported by OCP.

   Although you can write '.wav' files in every possible sample format
you should not alter the default of 44100KHz, 16bit, stereo.  You should
disable module looping so each module is written once onto harddisk.
You can disable looping in the 'ocp.ini' with the directive _loop=on_ in
the fileselector section.  You can also change looping
temporarily with the fileselector configuration while OCP is running.
See the fileselector advance usage Advanced usage.
for details.

   To enable the diskwriter device you can change the 'ocp.ini' file and
select the _devpDisk_ as default device by moving it to the start of the
playerdevices directive in the [sound]
section.  You can also select the _devpDisk_ device
temporarily by selecting the 'setup:/DEVICES/DEVPDISK.DEV' device.

   Now simply start OCP and select a module to play.  You will hear no
output and notice that the module is played with maximum speed(13).  In
the directory where you have started OCP (not necessaryly the directory
where the module is located) subsequent '.wav' files named
'CPOUT000.WAV', 'CPOUT001.WAV' will be created.

4.6 Using the Compo mode
========================

If you enable the _Compo mode_ in the 'ocp.ini' file all title and
instrument string from modules will not be displayed.

4.7 MIDI files
==============

OCP is able to play MIDI files.  However there is a certain problem.
Unlike the other file formats MIDI does not store the sample information
needed to produce a sound output.  The midi file only contains which
instrument out of a set of 127(14) should play which note at a given
time.  This is the reason why '.MID' files are much smaller than other
file types.

   This has of course some disadvantages.  To hear a MIDI file you need
to have some information how to play the used instruments.  Back in the
old days the OPL2 sound chip which was present on the SoundBlaster cards
was used to play the midi instruments.  Most people find the sound
capabilites of the OPL series rather limited and midi files were no big
deal back then.

   Things changed when so called wavetable cards became popular.  Those
card have sample data stored onboard in a ROM plus a hardware mixer
capable of mixing several midi channels.  The MPU-401 interface from
Roland is the de facto standard for accessing those cards, but this
feature is not supported by OCP yet.(15)  A disadvantage is that those
wavetable cards only have a very limited memory for sample data
typically 4MB. If you imagine 127 instruments and 64 drums fitting into
just 4MB you can guess what sound quality these cards have.  Modern
cards have normally much more onboard ROM/RAM, but in our opinion even
32MB are far too less for a good sound quality.

   OCP goes a different way.  Instead of using the onboard ROM samples,
the samples needed for a specific '.MID' file are loaded on demand from
the harddisk into main memory and then processed by either the hardware
mixer (if you have such a card and the samples fit into its memory) or
by the software mixers.  This has the advantage that you can easily
change a single instrument, if you don't like the default sound.

   The instruments are stored in so called _GUS-patches_, a file format
introduced by Gravis with their UltraSound cards.  At first you have to
get a complete patch set.  If you own a GUS classic or GUS max you will
probably have those files already on your harddisk.  All instruments are
stored in files ending with '.PAT'.

   The original GUS patches are found on Advanced Gravis ftp server:
<ftp://ftp.gravis.com/Public/Sound/Patches>

   However I recommend looking at the following patch set:
<http://www.stardate.bc.ca/eawpatches/html/default.htm>

   If you unpack any of those archives to a folder on your harddrive,
you have to adjust the path in the 'ocp.ini' file.  The configuratoin
directive
     ultradir=/usr/share/ultradir  ; path to ULTRASND.INI
   should be set to the folder where you extracted the patch files.
Please check that a file called 'ULTRASND.INI' is located in this
folder, as OCP needs this file, to load the patch files.

4.7.1 Mixer
-----------

If your computer is too slow to play with proper speed remember that the
new Float Mixer is the default device used by OCP when dealing with
software mixing.  If you enable the Normal Mixer you will gain a good
speed up of your system.

   Look in the [sound] section of your 'ocp.ini'
file for the following line:
     wavetabledevices=devwMixF devwMixQ (...) devwMix devwNone
   The leftmost device is used as default.  So change the line to the
following to enable the Normal Mixer:
     wavetabledevices=devwMix devwMixF (...) devwNone

   If you don't understand all this right now, read chapter
ocp.ini on how to configure OCP.

4.7.2 Interpolation
-------------------

If the player still runs to slow you can disable the use of
interpolation with software mixing.  Look for the following line in the
[sound] section of the configuration file:
     filter=1
   and change it to:
     filter=0

   Now the use of interpolation is disabled.  You can enable the filters
again in the player with <backspace>.

4.7.3 still to slow?
--------------------

If you applied the above 4 tips and OCP is still running too slow,
there's hardly anything left to tune.  Remember that graphic modes are
generally slower than text modes.  And in text mode the analyzer uses
most ressources.  If you only display channels, instruments and track
list there's almost no cpu consumption by visuals.

   If the player is still too slow your last chance is to lower the
mixing / playing rate of the player.  Locate the following line in the
[sound] section of 'ocp.ini':
     mixrate=44100
   Use the table mixingrate as a guideline to set this
value.

4.7.4 mixingrate
----------------

44100          CD Quality
33000          very close
               to CD
22050          Radio
               Quality
11025          Telefon
               Quality
8000           '.au'
               Quality

   While applying those patches please remember that modules with more
channels will _always_ need more cpu power than those with few.  If your
Impulse Tracker modules ('.it') always click and pop while old Amiga
modules ('.mod') play fine that's normal, because the modern trackers
allow more than 4 channels.

4.8 Key Reference
=================

<ESC>                  quit the player
<F1>                   help
<F2>, <F3>             volume up/down
<CTRL>+{<F2>, <F3>}    change amplification
<ALT>+<F2>             _save_ current configuration
<ALT>+<F3>             load previously saved configuration
<F4>                   surround on/off
<ALT>+<F4>             load default configuration
<F5>, <F6>             change panning
<CTRL>+{<F5>, <F6>}    adjust reverb
<F7>, <F8>             change balance
<CTRL>+{<F7>, <F8>}    adjust chorus
<F9>, <F10>            change speed
<ALT>+<F9>             song message
<F11>, <F12>           change pitch
<F11>                  toggle between 6581 and 8580 (sidplayer only)
<F12>                  toggle between PAL and NTSC (sidplayer only)
<CTRL>+<F12>           (un)lock speed and pitch
<1>..<0>               solo channel 1..10
<ALT>+<1>..<0>         solo channel 11..20
<CTRL>+<1>..<0>        solo channel 21..30
<a>                    textmode spectrum analyzer
<ALT>+<a>              toggle analyzer mode
<b>                    phase graphs
<c>                    channel mode
<d>                    goto DOS
<f>                    goto fileselector
<g>                    graphic spectrum analyzer
<SHIFT>+<g>            graphic spectrum analyzer in 1024x768
<ALT>+<g>              toggle fast/fine algorithm
<h>                    help
<i>                    instrument mode
<CTRL>+<i>             instrument mode colors on/off
<ALT>+<i>              remove _played_ dots
<CTRL>+<j>             same as <Enter>
<CTRL>+<l>             song looping on/off
<ALT>+<l>              pattern looping on/off
<m>                    volume control
<CTRL>+<m>             same as <Enter>
<n>                    note dots
<o>                    oscilloscopes mode
<ALT>+<o>              behaves like <Tab> in this mode
<p>                    pause
<ALT>+<p>              pause screen
<q>                    quiet current channel
<s>                    solo current channel
<t>                    track/pattern mode
<v>                    peak power level mode
<w>                    wurfel mode
<x>                    eXtended mode
<ALT>+<x>              normal mode
<z>                    toggle between 25/50 or 30/60 rows
<CTRL>+<z>             change between 25/50 and 30/60 rows
<ALT>+<z>              change between 80 and 132 column mode
<Enter>                play next song in playlist
<Space>                stop pattern mode flow
<Pause>                pause screen output
<Backspace>            toggle filter
<Tab>                  change option of the activated mode
<'>                    link view
<,>, <.>               fine panning
<+>, <->               fine volume
<*>, </>               fine balance
<Right>, <Left>,       change current channel
<Up>, <Down>
<CTRL>+<Right>         skip the current pattern
<CTRL>+<Left>          restart current pattern / goto previous pattern
<CTRL>+<Down>          skip 8 rows
<CTRL>+<Up>            skip -8 rows
<Ins>                  goto fileselector
<Pgup>, <Pgdown>       scroll in current window
<CTRL>+{<Pgup>,        scroll in instruments window (eXtended mode)
<Pgdown>}
<Home>, <End>          goto top/bottom of current window
<CTRL>+<Home>          restart song

   ---------- Footnotes ----------

   (1) Some special file types modify the appearance of the general
field, but only static data is affected.

   (2) By default the speed and pitch options are linked (indicated by a
small arrow).  To disable linkage press <\>.  Note that this will not
work with all supported file types.

   (3) Not all orders have to be played, as modules can jump between
different orders.

   (4) This is not the same as Volume and <F2>, <F3>, because you are
able to make the complete file louder than 100% with this option.  Note
that setting to values above 100% might harm sound quality.

   (5) This does not mean that OCP itself crashed, but that the order of
the music file can be disturbed so heavily, that the player is not able
to play the correct music anymore.

   (6) see Advanced usage for details

   (7) 80x25 and 80x50 textmode are available on every VGA card.  All
other modes require a proper VESA bios (at least version 1.2) and may
not be available on all cards.

   (8) All these informations are only shown when a module or similar
type of file is played.  The nature of file like '.WAV' or '.MP3'
permits those displays.

   (9) This layout is only valid for module type files.  Other file
types like '.SID' have a different layout, but basically showing the
same information.

   (10) The highest possible frequency is half the output frequency
(22KHz when playing at 44Khz).

   (11) If your VESA bios does not support 132 columns a 80x50 mode is
used.

   (12) See appendix wap.

   (13) depending on your cpu power

   (14) a set of drums is defined aswell

   (15) however this might change in the near future

5 Configuration
***************

5.1 ocp.ini
===========

OCP can be widely configured using the 'ocp.ini' file, which should
reside in the home directory of the player itself.  This file is
processed at every startup and informs the player about various modules
/ plugins and their respective configuration.  For average users the
default configuration should be sufficient.  However if you want to
change certain aspects of the player permanently you have to modify this
file.  You can use every ascii editor to edit the ini file.

   The 'ocp.ini' consists of many sections.  Each section starts with a
section identifier tag in square brackets [ ].  Examples of sections are
[general] or [sound].  The
sections id tag should be followed by a newline.  After a section has
been declared with the id tag the options describing the sections
follow.  Each options takes a single line and consists of a keyword
followed by a "=" and the parameters.  Example:
     mixrate=44100

   All options following a section id are options for that section.  If
a new section starts with a id tag all forthcoming options are assigned
to the new section.  All options for a section have to be grouped
together.  Multiple declarations of sections are not valid.
     [general]
       link=dos4gfix
     [defaultconfig]
       link=mchasm
     [general]
       dos4gfix=off
   the above example has to be written as:
     [general]
       link=dos4gfix
       dos4gfix=off
     [defaultconfig]
       link=mchasm
Note that in the above example the option _link_ has not
been overridden by the _defaultconfig_ section. Both sections now
can access an options named _link_, but both options are totally
independant of each other.

   Comments can be placed anywhere in the configuration file and are
marked by a _;_.  The rest of the line starting from the _;_ is
considered as a comment and not processed.

   Normally the definition for an option ends with the end of the line.
If many parameters are needed to specify an option they may exceed the
default line width of 80 characters.  Although this is no problem for
OCP it is not nice looking.  You can extend a line logically by using
the unix like _backquote_ at the end of a line to begin a newline
without interupting the current option definition.
     [example]
       option1=parameter1 parameter2
       option2=parameter1 \
               parameter2
   Both options contain exactly the same parameters.

   When modifying the configuration you should always start with the
default configuration file and configure it to your needs.  Building a
bug free config file from scratch is difficult.  (1)

   We will now have a look at the individual sections and their options.

5.2 [general]
=============

The _general_ section describes which internal modules or plugins to
load at startup.  Most of them are required for normal operation of OCP
so you should not remove any of the contents.  All options listed in
this section are loaded every time OCP starts!  The default _general_
section looks like:
     [general]
       link=cpiface cphlpif fstypes
       prelink=framelock pfilesel

link                   this options describes the modules to load when
                       starting OCP. There is no need to change this
                       option, unless you have coded a basic internal
                       module.
datapath               OCP searches for background pictures and
                       animations in its home directory.  If you want
                       to store your artwork at a different place use
                       this option to set the right directory.
tempdir                this directory is used for extracting modules
                       from archives.  If you have set a DOS
                       environment variable called either _TEMP_ or
                       _TMP_ these will be used.

5.3 [defaultconfig]
===================

The _defaultconfig_ section is very similar to the _general_ section.
But unlike the _general_ section which is always processed the settings
in the _defaultconfig_ section can be ommited with an alternative
section and the _-c_ flag from the command line.  If the _-c_ flag is
not present the _defaultconfig_ section will be processed.(2)

     [defaultconfig] ; default configuration
       link=devi plrbase mcpbase smpbase arctar mixclip medialib cdrom
       prelink=poutput hardware cphelper sets mchasm compat

link           just like in the _general_ section this option defines
               which modules should be loaded at startup.  You can
               delete some entries if you will not need them - however
               this is not recommended as they do not use much memory
               and do not require any processor power.
prelink        these files will be loaded before starting the main
               module.  If something goes wrong here OCP will continue
               to work.

5.4 [sound]
===========

This section is the most important one for using OCP. If you want to
change the configuration permanently you have to modify the entries of
this section.

     [sound]
       playerdevices=devpOSS devpNone devpDisk
       samplerdevices=devsOSS devsNone
       wavetabledevices=devwMixF devwmixQ devwMix devwNone
       mixrate=44100
       mixprocrate=4096000
       mix16bit=on
       mixstereo=on
       plrbufsize=200
       mixbufsize=200
       samprate=44100
       samp16bit=on
       sampstereo=on
       smpbufsize=2000
       defplayer=
       defsampler=
       defwavetable=
       midichan=64
       itchan=64
       cdsamplelinein=off
       bigmodules=devwMixF
       wavetostereo=1
       waveratetolerance=50
       amplify=100
       panning=100
       volume=100
       balance=0
       reverb=0
       chorus=0
       surround=off
       filter=2

playerdevices          OCP uses three different devices to communicate
                       with the hardware.  The _playerdevices_ are used
                       to play a stream of samples.  As all sound cards
                       support this feature you will find
                       _playerdevices_ for every sound card supported
                       by OCP. This device is needed for playing
                       '.ogg', '.wav' and '.mp3' files and if you
                       want/have to use the software (quality) mixer.
                       OCP searches for all devices listed in this
                       option at startup and only those found are
                       actually loaded.  You can delete all devices you
                       have not installed to speed up to startup
                       procedure.  If you have multiple sound cards
                       installed be sure to list all devices if you
                       want to use more than one sound card.(3)  If
                       more than one device is listed the first in the
                       list will be used as default.
samplerdevices         these devices are the least important ones.
                       They are only needed if you want to use OCP when
                       playing cd audio tracks or start the player in
                       sample mode.  The sample data is not calculated
                       from files, but sampled from either the cd, line
                       or microphone jack of the sound card.  You can
                       then use the graphical screens to view the
                       sounds.
wavetabledevices       for mixing several channels you have to use
                       _wavetabledevices_.  Most sound cards are only
                       able to play to channels simultaneously normally
                       assigned to the left and right channel or your
                       home stereo.  The _mixer_ devices are used to
                       mix the sample data of module files to those two
                       channels.  However modern sound cards have
                       special hardware to mix channels "onboard".  But
                       all hardware mixers have a maximum amount of
                       channels to mix(4).  Especially '.it' files
                       often use more than 32 channels so an errorfree
                       playback can not be guaranteed when using
                       hardware mixing.  You should include one of the
                       software mixers for this case.
mixrate                the default mixrate.  Unless you have a very old
                       sound card(5) or a very old processor(6) there
                       is no need to change this option.
mixprocrate            if you have a slow cpu(7) you might not be able
                       to play 32 channels at full mixrate.  This value
                       defines the maximum "calculation power" to which
                       OCP tries to use the full mixrate.
mix16bit               Leave this option enabled unless you have a 8bit
                       sound card.
mixstereo              dito for stereo cards
plrbufsize             When using a _playerdevice_ to play sample
                       streams a DMA buffer is used to minimize cpu
                       resources for handling the sample stream.  This
                       option sets the DMA buffer length in
                       miliseconds.
mixbufsize             When running in a multitasking environment there
                       is no guarantee for constant cpu resources.  To
                       avoid a break in the sample stream OCP will
                       calculate in advance.  This option sets the
                       buffer lenth in miliseconds.
samprate               When using a _samplerdevice_ this value will be
                       used.
samp16bit              dito
sampstereo             dito
smpbufsize             this options sets the length of the sample DMA
                       buffer in miliseconds.
defplayer              with this option you can override the default
                       _playerdevice_.  Normally you don't need to set
                       this option, as the default device can also be
                       set by the order in the _playerdevice_ option.
                       This option can also be specified by using the
                       _-sp_ options from command line.
defwavetable           this option sets the default _wavetabledevice_.
                       Can also be set with _-sw_ command.
defsampler             the same as the _-ss_ command line option.
midichan               unlike the module file types the MIDI file
                       format does not specify the exact amount of
                       channles to use.  Complex '.mid' files can
                       easily try to play several dozens of channels
                       simultaniously.  This option sets the maximum
                       amount of channels to mix when playing '.mid'
                       files.  Note that this value has no effect when
                       a hardware mixing device is used, as the maximum
                       number is limited by the hardware.
itchan                 the '.it' format can play more than one sample
                       per channel simultaniously.  A maximum number of
                       channels to mix is required for this file type
                       too.  When playing '.it' files using a hardware
                       mixer the maximum number of channels is again
                       limited to the hardware.
cdsamplelinein         If you select a '.cda' file the cd input of your
                       sound card is used to sample the current music.
                       If you do not have a cd input or if you have
                       connected your cd-rom to the line-in jack enable
                       this option to change to sample input.
bigmodules             This option is of interest for users of hardware
                       mixing devices only.  Sound cards capable of
                       mixing channels are not only limited by the
                       amount of channels played simultaniously, but by
                       the amount of onboard memory to store the sample
                       data too.  If files are marked as "big" in the
                       fileselector this device listed in this option
                       will be used for mixing this module.(8)
wavetostereo           When playing a mono wave the sound card can
                       either be switched to mono mode or the wave can
                       be played as a stereo file.(9)
waveratetolerance      if the sample rate of the wave file is not equal
                       to a sample rate supported by your sound card,
                       OCP will not resample unless this value is
                       exceeded.  Divide the value by 1000 to get the
                       percentage.
amplify                the default amplification to use within the
                       player.  The following options are described in
                       section General in detail.  The
                       command line option _-va_ overrides this option.
panning                the default panning (command _-vp_)
volume                 the default volume (command _-vv_)
balance                the default balance (command _-vb_)
reverb                 some sound cards have an onboard effect
                       processor (10) which features a reverb effect.
                       This option controls the intensity of the
                       onboard effect.  (command _-vr_)
chorus                 dito as reverb (command _-vc_)
surround               this options controls the fake surround effect
                       (11) (command _-vs_)
filter                 The software mixer can use a software filter to
                       enhance the playback quality.  Different
                       algorithms can be used.  (command _-vf_)
                          * 0 - no filter
                          * 1 AOI - only filter samples when filtering
                            is necessary
                          * 2 FOI - filter every sample even if
                            filtering has no effect

5.5 [screen]
============

When the player starts it will use the options in this section as the
initial appearance.

     [screen]
       usepics=*.gif *.tga
       compomode=off
       startupmode=text
       screentype=7
       analyser=on
       mvoltype=1
       pattern=on
       insttype=0
       channeltype=1
       palette=0 1 2 3 4 5 6 7 8 9 a b c d e f
       fps=20

usepics                When using graphics modes you can use a picture
                       to show in the background.  OCP will load any
                       TGA files with 640x384 dimensions and 256
                       colors.  As the TGA format is poorly implemented
                       in modern graphic programs this might change in
                       the future.  As some colors out of the 256 are
                       used by OCP you should leave either the first or
                       the last 16 colors in the palette black.  The
                       pictures should be copied to the home directory
                       of ocp, unless you specify a different location
                       in the _defaultconfig_ section.
compomode              this option will enable the compo mode.  Section
                       Using the Compo mode describes
                       the details.
startupmode            start the player in either text or graphic mode:
                          * coolhelp - show help screen
                          * dots - show note nots
                          * graph - show graphical spectrum analyzer
                          * links - show currenty linked DLLs/shared
                            libraries
                          * msg - show module message
                          * phase - show phase analyzer
                          * scope - show oscilloscopes
                          * text - show standard text screen
                          * wuerfel2 - show animation
screentype             the default screentextmode:
                          * 0 - 80x25
                          * 1 - 80x30
                          * 2 - 80x50
                          * 3 - 80x60
                          * 4 - 132x25
                          * 5 - 132x30
                          * 6 - 132x50
                          * 7 - 132x60
analyzer               if the player starts in textmode show the
                       analyzer (or not)
mvoltype               the appearance of the peak power levels:
                          * 1 - big
                          * 2 - small
pattern                show the tracklist when starting OCP in textmode
insttype               the appearance of the instrument function:
                          * 0 - short
                          * 1 - long
                          * 2 - side (only in 132 column modes)
channeltype            the appearance of the channels in textmode:
                          * 0 - short
                          * 1 - long
                          * 2 - side (only in 132 column mode)
palette                with this options you can redefine the default
                       colors used in textmode.  The first entry
                       defines which color to use for the original
                       color with number 0.  Leave things as they are
                       if you are satisfied with the visual appearance
                       of OCP. We will provide new color schemes in the
                       future.
fps                    This tells how many frames per second OCP should
                       try to use, since UNIX isn't a real-time system,
                       this is needed.

5.6 [fileselector]
==================

Except the first two options all options can also be specified at
runtime by pressing <ALT>+<z> in the fileselector.  However to make
changes permanent you have to modify the _fileselector_ section.

     [fileselector] ; default fileselector section
       modextensions=MOD S3M XM IT MDL DMF ULT AMS MTM 669 NST WOW \
                     OKT PTM MXM MID WAV RMI MP1 MP2 MP3 OGG SID DAT \
     		PLS M3U PLT OGG
       movepath=  ; default path to move files
       screentype=2
       typecolors=on
       editwin=on
       writeinfo=on
       scanmdz=on
       scaninarcs=on
       scanmnodinfo=on
       scanarchives=on
       putarchives=on
       playonce=on
       randomplay=on
       loop=on
       path=.

modextensions          files containing these extensions will be
                       scanned by the fileselector.  Only those files
                       will be shown.  If you want to load files with
                       different extensions you have to specify them at
                       the command line.(12)
movepath               the standard path to move files into.  This is
                       describend in section
                       Advanced usage.
screentype             the textmode to use within the fileselector.
                       The options are the same as in the _screen_
                       section.
typecolors             show files in different colors depending on the
                       file type
editwin                show the edit window at the bottom of the screen
writeinfo              write the info to the information database
                       located in the home directory of OCP. This
                       speeds up the processing of directories, as
                       files have to be scanned only once.
scanmdz                if '.mdz' files are found in the current
                       directory, they will be scanned and the included
                       information used.
scanmodinfo            scan inside the music files for module
                       information.
scanarchives           if archives (like '.zip' or '.rar') are found in
                       the current directory the are scanned for
                       modules.
putarchives            show archives in the fileselector, so they can
                       be used just like subdirectories.
playonce               play every file only once (thus not looping it)
                       and then procede with the next file in the
                       playlist.  If the file contains a loop command
                       the loop command is ignored.
randomplay             play files in the playlist in random order.
loop                   loop files after the end.
path                   the default path to use when starting the
                       fileselector the first time.  The default is the
                       current directory (.).  If you keep all your
                       music files in one directory you can specfiy
                       this directory here.

5.7 device configuration
========================

The following sections define the various devices for the player.
Unless you really know what to do you should not change the following
options.  As most entries are similar only some educational examples are
listed here.  For a complete reference have a look at your personal
'ocp.ini' file for details.

   The general form of a device looks like:
     [handle]
       link=...
       subtype=...
       port=...
       port2=...
       irq=...
       irq2=...
       dma=...
       dma2=...
       bypass=...
       keep=...

handle                 The internal name to use within the player.  The
                       'ocp.ini' file must contain all _handles_ listed
                       in the devices options of the _devices_ section.
link                   the name of the dll function this device will be
                       linked to.
port(2)                the primary/secondary port of the sound card.
                       This value has to be given in hexadecimal with
                       preceeding _0x_ or appending _h_!
irq(2)                 the primary/secondary IRQ of the sound card
dma(2)                 the primary/secondary DMA channel of the card
bypass                 skip the autodetection if it may encounter
                       problems
keep
keep the driver
resident in memory,
even it is not
currently needed.

   Most device functions of the standard dll contain autodetection
routines for the supported sound cards, so there is normally no need to
specify any of the port, irq or dma options.  However if OCP is not able
to detect your sound cards settings you can try to insert the
appropriate values in the configuration file.

   The next subsections will look at the special features the different
sound cards and drivers support.  The original order of the 'ocp.ini'
has been slightly modified for the purpose of documentation.

5.7.1 OSS
---------

Open Sound Sysstem is a generic portable UNIX sound interface for
playing/recording pcm data, and adjusting mixer settings.

     [devpOSS]
       link=devposs
       revstereo=on
       path=/dev/dsp
       mixer=/dev/mixer

     [devsOSS]
       link=devsoss
       revstereo=on
       path=/dev/dsp
       mixer=/dev/mixer
       igain=1

path                   where /dev/dsp is located.  If you have more
                       soundcards, this can be set to for instance
                       /dev/dsp3.  You can override config with the DSP
                       environment variable.
mixer                  what mixerdevice to use.  Override with the
                       MIXER environment variable.
igain                  if you don't input from cdrom, try to set igain.
                       With this option, you can automatically set
                       igain to a given value (or -1 for not touching
                       it)

5.7.2 software mixers
---------------------

By default OCP will use its own routines for mixing several channels to
the two stereo output channels.  You have the choice between to mixers.
The normal mixer is faster in calculating, thus can mix more channels at
the same time.  The quality mixer however produces better sound ouput.
For average modules and a pentium processor the quality mixer should be
fast enough for sufficient playback.  If many channels are used you may
have to change back to the normal mixer (13)

   Both mixers take identical options.  As the mixers will be rewritten
in the future the options are likely to change.  Therefore they are not
documented here.  Please have a look at future versions of this document
if you want to change to mixer settings.  However these devices never
have caused any trouble/bugs and there should be no need for change.

5.8 archivers
=============

When processing files inside archives OCP has to know how to call the
programs.  The following sections define the usage of different
archivers supported by the OCP fileselector.

   When substituting the command line 4 special variables are processed
by the fileselector for accessing the archives:
%%      evaluates to "%"
%a      evaluates to the archiv name preceeded by the path to process.
%n      evaluates to the filename of the file to process inside the
        archive.
%d      evaluates to the destination directory used to extract files
        out of archive.

   Three default command are defined for the arc modules:
get                    this command is used when a file should be
                       extracted out of an archive.
put                    if a file should be added to the archive this
                       command line is used.
delete                 with <ALT>+<k> you can delete files out of
                       archives.

   The following two archivers contain special options described below:
     [arcZIP]
       get=pkunzip %a %d %n
       put=pkzip %a %n
       delete=pkzip -d %a %n
       deleteempty=on
deleteempty            the program pkzip/pkunzip used by OCP to process
                       '.zip' files have a bug when deleting the last
                       file inside an archive.  An empty archive of 22
                       bytes is left on the hard disk.  With this
                       option enabled the fileselector will delete
                       those "zip zombies".

     [arcACE]
       get=ace32 e %a %n %d
       scaninsolid=false
scaninsolid            scan in solid archives.  As this takes more time
                       you can disable this feature.

5.9 Filetypes
=============

The 'ocp.ini' file contains descriptions for all supported file types.
These features will be included in the file loader devices in the next
version of OCP, so these options will soon be obsolete.  There should be
no need to modify any of the file types.

5.10 MIDI
=========

If you want to hear MIDI music you need samples for the general midi
instrument set.(14)  This secion contains the paths to the midi patches.
Section MIDI files describes how to set up OCP for midi
playback.  For use of timidity, '/etc/timidity.cfg' must be configured.
     [midi]
       use=....  to force which option to use [ultradir fff freepats timidity]
       fff=c:\iw\gsfull4m.fff
       ultradir=/home/user/ultradir
       freepats=/usr/local/share/freepats
use                    if you want to force usage of a specific
                       patch-system, set this variable to one of these
                       values: ultradir fff freepats timidity
fff                    path where the fff font is located
ultradir               path where ULTRADIR.INI is stored.  Please
                       checkout 'ultrafix.sh' for fixing cases in
                       filenames.
freepats               path to where freepats is located

   ---------- Footnotes ----------

   (1) And remember to make backups before changing vital parts of the
'ocp.ini'

   (2) Therefore it was named _defaultconfig_...

   (3) you can change devices by using the special 'setup:' drive
described in section fileselector.

   (4) mostly 32 channels

   (5) SoundBlaster 1.x or SoundBlaster Pro and compatibles

   (6) Something like 386SX

   (7) _<_486DX

   (8) See section bigmodules for details about
this feature

   (9) switching the soundcard may cause problems so enable this option.

   (10) currently the SoundBlasterAWE and the TerraTecEWS

   (11) this has little to do with real Dolby Surround although there
should be a certain effect if you have such an amplifier

   (12) however files with different extensions are likely to be no
valid module format, so they will be refused to load

   (13) You can toggle by using the _bigmodule_ feature described in
bigmodules.

   (14) a so called midi patch set

6 Support
*********

The official internet homepage of OCP can be found under:
<http://www.cubic.org/player>

   Please send any suggestions and bug reports via electronic mail to
Tammo Hinrichs <opencp@gmx.net> and comments about this documentation to
Dirk Jagdmann <doj@cubic.org>.

   If you encountered a bug in OCP please send a detailed bug report to
Tammo Hinrichs.  Many people complain about music files not being played
properly (especially with module formats).  Please keep in mind that the
original tracking/sequencing program is _always_ the reference for
correct playback.  If a music file sound different compared to another
player, please keep in mind that perhaps the other program does not play
it correct.  This is especially true for Amiga 4channel modules.  As
those files can be produced using various trackers (Noise-, Sound-,
Protracker and many, many more) and sadly all of those trackers play
slightly different, a general player like OCP can not play _all_ modules
correctly.  We try to emulate the behaviour of ProTracker 1.1b, so that
most modules are played correctly.  However certain features of one
tracker permit another feature of a different player.

6.1 The Team
============

Currently the core team of OCP devolopers consists of 5 people:

   Tammo Hinrichs - main coder & ruler Felix Domke - coder Fabian Giesen
- coder Dirk Jagdmann - generic support, this and that Stian Skjelstad -
unix port

7 Freqently Asked Questions
***************************

This chapter was initially written by Mom/Cubic.

  1. What is OCP?

     OCP is a music player which plays a variety of sound formats on
     several sound cards.

  2. What sound cards are supported?

     OSS, Open Sound System

     ALSA, via OSS legacy interface

     Disk Writer, writes .WAV output on disk.

     Quiet Player

  3. What music formats are supported?

     MOD/NST/WOW, XM, S3M, DMF, MTM, ULT, 669, OKT, PTM, AMS, MDL, IT,
     MIDI, SID, OGG and MPEG 1 audio layer 1/2/3

  4. Which is the last version of OCP for Unix?

     The last OCP version is the 0.1.20 Version.

  5. Are you going to release new versions?

     Windows/DOS: Perhaps not.  We are all busy doing other things.

     UNIX: Yes

  6. Now, how does that MIDI player thing work?

     OCP's MIDI player does not, like other programs, use the MIDI
     capabilities of your sound card / Korg Trinity or whatever, but
     uses the patch files of the famous Gravis Ultrasound to synthesize
     the MIDI output itself (just like Timidity or kmidi under KDE) via
     it"s normal wavetable system.  So the only thing you need are the
     GUS patch files which are available at our site.  Simply open a new
     subdir called "MIDI" in OCP's directory, copy all patch files
     ".PAT" into it and there you go.

     Users of a Gravis Ultrasound only have to make sure their ULTRADIR
     environment variable is set correctly or state the patch file and
     "ULTRASND.INI" location in "ocp.ini".

  7. Does that mean I can listen to MIDI files even with my old SBPro?

     Of course - if your soundcard works with the rest of OCP, you will
     be able to play MIDI files, too - as long you as got the GUS Patch
     files as written above.

  8. Hey, I have a module which OCP plays wrong!  You SUCK!

     Well, it's in fact YOU who sucks, as you didn't send that module
     together with a bug report to <mailto:doj@cubic.org>.  How the hell
     can we fix bugs if we don't know them?

  9. OCP plays my ".it" files much too soft, IT's internal mixer sounds
     a lot better, why don't you just fix it?

     Because this is a religious question.  OCP's mixing routines are
     designed for maximum sound quality which also includes things like
     declicking and quadratic interpolation, IT's mixing routines are
     just optimized for speed without really caring about sound quality
     (speaking of the non-MMX routines).  So OCP's sound differs a bit,
     if you are not pleased with it, feel free to use IT again ;)

  10. Can you give me the source or a part of the source from OCP?

     The complete source code can be found on the official OCP sites,
     covered under the GNU GPL.

  11. I have a problem finding a small routine that will play mod files.
     I wanted to know if you can help finding a routine, lib or
     something like this.

     Try our Tiny XM Player, a free XM Player inc.  source.

  12. Why don't you implement Nibbles, or similar game, in Cubic?  Like
     FT2-nibbles?  Or just plain Snake...

     Get ahold of a coder, give him the source and force him to
     implement it, if it's a GOOD nibbles version, we might include it
     into the "official" release ;)

  13. What does "Wurfel Mode" actually do?

     "Wurfel" is german word for cube/dice.  The mode plays an
     animation.

  14. Can I make my own "Wurfel Mode" animation?

     Of course you can.  On our site you'll find the program WAP
     (WurfelAnimator Professional) which can convert ".pcx" frames to a
     Wurfel Mode animation.

  15. How can I put a picture to the background on OCP?

     Convert your Picture to a TGA-file, these pics have to be
     640x384x208 TGAs, the first or the last 48 colors must not be used.
     You can also save your image as a 640x384x208 gif87 picture.
     Either the first or the last 48 colors of the palette have to be
     black.

8 Writing plugins
*****************

The capabilities of OCP can be extended by plugins.  The type of plugin
is not limited, so new graphics modes, file types and even enhanced
players may be added by the user.  As development for OCP is done using
GNU C/C++, it is recommended to use this compiler for developing plugins
aswell.  We have not tested the plugin interface with other
compilers.(1)

   As of UNIX version, we refer to the source-code and GNU tool-chain
documentations when it comes to compiling and linking and to look at
other plugins as templates for making new ones.

   ---------- Footnotes ----------

   (1) This might change in the future.

9 .MDZ files
************

This was written by Fabian Giesen, based on the original '.MDZ'
description by Niklas Beisert.

9.1 What are '.MDZ' files?
==========================

'.MDZ' files are Module Description files (the _MDZ_ is a short form of
_DIZ_, which is in turn a short form of Description).  The '.MDZ' format
can, however, contain much more information than normal Module/Sound
files, which normally only contain the song's title and sometimes a
"song message", which can be freely entered by the author.  Things like
the name of the author of a song, its playtime, a comment about it etc.
which can be entered in OCP's Fileselector cannot be stored inside the
module file, so they have to be stored somewhere else.  Usually this is
in the file 'CPMODNFO.DAT', which normally perfectly suits this task.

   However, this format has some disadvantages.  Imagine you give a
module file to a friend.  Simply copying your 'CPMODNFO.DAT' together
with the song on the disk is impractical, because this file overwrites
your friend's 'CPMODNFO.DAT' when he simply copies it.  So he could take
your description, write it down somewhere, and take it with him, but
that is pretty uncomfortable.

   That's why the '.MDZ' files were invented.  '.MDZ' files contain the
description of one or more module file(s), just like the 'CPMODNFO.DAT',
but have attributes which make them interesting:

   * '.MDZ' files are normal text files and therefore human readable
   * The content of '.MDZ' files gets automatically inserted in the
     module description database 'CPMODNFO.DAT' without need for user
     interaction
   * '.MDZ' files can be exported from within the OCP fileselector with
     one keystroke (see section Reference.)

9.2 Why should I use them?
==========================

(This section is intended for composers)

   There are of course some good reasons for using them:

   * Every OCP user sees your description automatically when he moves
     the cursor over the file
   * The module type is also stored in '.MDZ' files, so you can
     explicitely force OCP to play your Module in Protracker (or
     FastTracker) mode, for example.
   * Even if the user does not use OCP, he can still read your
     description, because '.MDZ' is a simple, human readable text format
   * Creating '.MDZ' files is almost no extra work (you can create a
     complete '.MDZ' file from within OCP in less than one minute)

   So, as you see, using '.MDZ' files has many advantages, but (almost)
no disadvantages.  It is surely worth trying.

9.3 The '.MDZ' file format
==========================

This is not documented here.  If you want a complete description, wait
for the soon to be released OCP Technical Reference Manual.

10 WurfelAnimator WAP
*********************

This chapter is written by Felix Domke, the author of WAP.

10.1 What is the so called WurfelMode?
======================================

In version 1.0 of the famous Cubic Player, pascal got a nice idea of
playing silly animations inside the Player.

   He invented the _WurfelMode_ (_Wurfel_ is the german word for cube).
The WurfelMode was able to play animations with a resolution of 160x100
pixels in 256 colors in a special tweaked vga-mode.  The animation
format was a special one.

10.2 How can I create such animations by myself?
================================================

Long time, only the cubic team (or even only pascal?)  itself was able
to create such animations.  The reason for this was that, as said, the
animations had to be in a very special format, and the only tool that
was be able to create this format were the not-so-famous _WurfelTools_.
Included there was a tool called 'makedmp.exe'.  It took various '.tga'
files, and made a '.dat' animation out of them.  But noone checked how
this tools worked, mainly because it had no command-line-help and the
sources weren't available anymore.

   But times are changing.  Today, you don't have to guess how to use a
utility anymore.  You just have to read the documentation (yes, even
you, Realtime ;).  Today, you can even use a resolution of 320x200 (wow,
THAT's highres).

   For people who didn't guess how pascal's tool worked, I made a new
one.  This time _with_ source available to all interested people.  This
time with '.pcx' images, not _.tga_ one, because '.pcx' is much easier
to read, and also more widely supported.  This time even with some
palette-aligning, so you don't have to care about same palettes anymore.

10.3 And how can I use your tool?
=================================

First, you have to render/paint/rip a animation.  It HAS to be 320x200,
or, if you want to make an old, $<$ OCP 2.0q, animation, 160x100.  In
case you didn't notice, the OCP 2.0q and higher has a new WurfelMode,
called _WurfelMode ][_ , with support for 320x200 pixels images, instead
of the lowres 160x100 ones.

   Your animation should be in the form of many, many '.pcx' files,
called for example 'PIC000.PCX', 'PIC001.PCX', 'PIC002.PCX' and so on.
They must have only 256 colors, and they should have all the same
palette.  If they don't have the same palette, the palette will be
aligned.  But my calculation of this isn't very good (but it works :),
so for BEST results you have to do this in your favourite
picture-editing-program.  Next, you have to create a _script_.  This
script contains informations about the filenames of your frames, and a
some other stuff.

   The script has the following format:
     Version
     [SFO] RLECompression
     Title
     NumFrames Delay Filename
     [NumFrames Delay Filename]
     [NumFrames Delay Filename]
     [...                     ]

   _Version_ is either 0 or 1, 0 for 160x100 animations, 1 for 320x200.
If you want to create a Version 0-animation, _SFO_ should be set to 1,
if you want to create a Version 1-animtion, _SFO_ has to be left out.
(1) _RLECompression_ should be set to 1, it compresses the Animation a
little bit.  _Title_ is the title of the animation, it shouldn't be
longer than 31 chars, it's displayed inside the fileselector of OCP.

   After this _header_, a random number of section follows (but at least
ONE ;).

   Every section describes a sequence of some PCXs.  In the final
animation, all sections are joint together.

   _NumFrames_ is the number of frames in this sequence.  For example,
if you have PCXs that are named from 'PIC000.PCX' up to 'PIC199.PCX',
NumFrames should be 200.  _Delay_ is handled a little bit different in
the two versions.  If you want to create a Version 0-animation, a
_Delay_ of 1 means a framerate of about 21.3 frames per second, a
_Delay_ of 2 is about 10.65 fps (the half), a _Delay_ of 3 is about 7.1
(a third) and so on.

   If you want to create a Version 1-animation, _Delay_ is 65536/desired
fps, so if you want to have 15fps, "Delay" should be 4369.  This value
has to be BELOW 65536 (and above 0, of course :) _Filename_ is the
filename of your sequence.  Because most animations have more than 1
frame, you can use %d (and other C-printf placeholders).  For people
whose native language is not C, here some short examples:

filename                 framenumber              real filename
pic%d.pcx                0                        pic0.pcx
                         1                        pic1.pcx
                         2                        pic2.pcx
                         3                        pic3.pcx
                         9                        pic9.pcx
                         10                       pic10.pcx
                         11                       pic11.pcx
pic%03d.pcx              0                        pic000.pcx
                         1                        pic001.pcx
                         2                        pic002.pcx
                         3                        pic003.pcx
                         9                        pic009.pcx
                         10                       pic010.pcx
                         11                       pic011.pcx
   The framenumber always starts with 0, not with 1, keep this in mind!

   Here is an example script: (version 0)
     0
     1 1
     a basic cubic-player animation
     11 2 intro%d.pcx
     200 1 ani%03d.pcx

   This animation would have 211 frames ('intro0.pcx' to 'intro10.pcx',
then 'ani000.pcx' to 'ani199.pcx').

   And here again one for version 1:
     1
     1
     an enhanced OpenCP animation
     11 3072 intro%x.pcx
     200 1000 ani%03d.pcx

   To create the animation, just type in
     wap <scriptfilename.scr> <outputfilename.dat>
   and hit <Enter>.

   The WurfelAnimator will now try to make the animation.  To view the
animation inside OCP, rename the created '.DAT'-file to 'CPANU001.DAT'
(or 'CPANI002.DAT' and so on...)  and press <w> inside the player.

10.4 This tool doesn't work!
============================

No problem,I have always an open ear for your problems.  Just write your
problems to <mailto:tmbinc@gmx.net>.

   Maybe you have luck and meet me on IRC, usually I am in
<irc://#coders.ger> and some other channels, but if you don't know
those, well, maybe you're not welcome on them ;)

   Anyway, maybe you have some fun with this tool.

   ---------- Footnotes ----------

   (1) If you're interested what this value means, well, just get the
original documentation for professionals, it's described there