This is ocp, produced by makeinfo version 4.8 from ocp.texi.

   This documentiation falls under the GPL license.

   Copyright (C) 2019-'22 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.

INFO-DIR-SECTION Audio
START-INFO-DIR-ENTRY
* OCP: (ocp).                   Open Cubic Player
END-INFO-DIR-ENTRY


File: ocp,  Node: Top,  Next: starting,  Up: (dir)

Index
*****

OpenCubicPlayer is a music file player. It is derived from the _Cubic
Player 2.0appe_ for DOS which was developed by Niklas Beisert, which
you can find at `https://www.cubic.org/player/'

   OpenCubicPlayer is published under the GNU General Public License
(GPL). That means you can use this software without charging for it.

   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'

   For reporting bugs (issues), submitting patches, or looking for more
recent versions, please check out
`https://github.com/mywave82/opencubicplayer/' and
`https://stian.cubic.org/project-ocp.php'

   If you encountered a bug in OpenCubicPlayer please report in the
link above.  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 sounds different compiled to another
player, please keep in mind that perhaps the other program does not
play it correct. This is espicially 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 are
slighty different, a general player like OpenCubicPlayer can not play
~all~ modules correctly. We try to come as close to a reasonable
mixture of them all, so that most modules are played correctly. However
certain features of one tracker permit another feature of a different
tracker.

   e-Mail contacts: Stian Skjelstad       <stian.skjelstad@gmail.com>
              Niklas Beisert        <nbeisert@physik.tu-muenchen.de>
              Tammo Hinrichs        <kb@nwn.de>                  Dirk
Jagdmann         <doj@cubic.org>

   This documentiation falls under the GPL license.

   Copyright (C) 2019-'22 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.

* Menu:

Users Manual
* starting::
* fileselector::
* player::
* configuration::
* support::
* faq::

Developers Manual
* wap::


File: ocp,  Node: starting,  Next: fileselector,  Prev: Top,  Up: Top

1 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 card/driver defined in the
`ocp.ini' file. If the card/driver is not found you cannot use it. If
more than one sound card/driver 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.

   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

   * -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 *Note Using the diskwriter:
player, 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 *Note Using the diskwriter: player.

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

   (1) You can change this in the player by using the `setup:' device.
See page *Note 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.


File: ocp,  Node: fileselector,  Next: player,  Prev: starting,  Up: Top

2 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.

2.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:/home/user/*' means that the current directory is `/home/user' on
your `file:' drive and all files are shown (`*'). You can edit the path
and the mask by pressing <ALT>+<Enter> or <CTRL>+<Enter> depending on
the UI renderer in use. After editing the path press <Enter> to change
to the appropriate directory. You can edit the file mask to include
only some files.

     `file:/media/music/*.mod' will change to the `/media/music'
     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 side 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.

2.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. 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 do not have to match the filename
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 which has not been processed by the fileselector it may take some
minutes 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!_

2.3 Advanced usage
==================

The appearance and behaviour of the fileselector can be edited in the
`ocp.ini' (*note ocp.ini: configuration.) 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 14 options with keys
<1>..<9>, <a>..<d>, <+> and <->. If pressing <ALT-S> the settings can
be flushed into `ocp.ini'. The following list will explain every option:
1       _screen mode:_ This is output-driver specific. Most common you
        can adjust the font-size here between sizes like 8x8 or 8x16.
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. (currently not implemented)
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.
+/-     _framerate:_ Adjust the target framerate.

   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 select `M15' in
the _type_ entry. If the module does not differ between tempo and speed
and is of the 15 instrument type select `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 select
`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 selecting 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.(2)

2.4 Reference
=============

<a>..<z>                  quickfind
<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
<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>, <Pgdown>} move module one page up/down in playlist
<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
AY      Ayley-library compatible
BPA     Death Ralley archive
CDA     compact disk CD audio track
DMF     X Tracker module
HVL     HivelyTracker / Abyss Highest Experience module
FLAC    FLAC
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)
M31     miga NoiseTracker module with 31 instruments
MPx     MPEG audio format level 1-3
MTM     Multi Tracker module
MXM     Mxmplay module
OGG     Ogg Vorbis sound stream
OKT     Oktalyzer module
OPL     Adplug-library compatible
PLS     OCP playlist, works also with M3U and PLT playlist files
PTM     Poly Tracker module
SID     PSID SID file
STM     Scream Tracker 2 module
S3M     Scream 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
YM      ST-Sound (YM files player library)

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

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

   (2) See *Note Using the diskwriter: player.


File: ocp,  Node: player,  Next: configuration,  Prev: fileselector,  Up: Top

3 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.

3.1 General
===========

OCP displays general (status) information in the top 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

3.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>.

   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 shell will be started when typing <d> if the current renderer
supports it.

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

3.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.

3.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.(7) 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.  (8)

   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.

3.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 on 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.

3.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.

3.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.(9)

   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.

3.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.

3.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 using <m> (Volume control is disabled in 80 column modes
and enabled in 132 column modes by default).

3.3.7 Module message
--------------------

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

3.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.(10)

3.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).

3.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>.

3.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.

3.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.

3.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.

3.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.(11)

3.5 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.

3.6 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(12) 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.

   OCP uses a fork of Timidity that uses this approach, using what is
called a sound font. So for MIDI to work, this needs to be installed.
The most easy method is probably to make sure that Timidity installed
in the operating system, since this usually includes installing atleast
a sound font, and to configure the needed configuration files.

3.6.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 *note [sound]: configuration. 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 *note
ocp.ini: configuration. on how to configure OCP.

3.6.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
*note [sound]: configuration.  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>.

3.6.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
*note [sound]: configuration.  section of `ocp.ini':
     mixrate=44100
   Use the table *Note mixingrate: player. as a guideline to set this
value.

3.6.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.

3.7 Key Reference
=================

<ESC> <ESC>            quit the player
<F1>                   help
<F2>, <F3>             volume up/down
<SHIFT>+{<F2>, <F3>}   change amplification
<CTRL>+<SHIFT>+<F2>    _save_ current configuration
<CTRL>+<SHIFT>+<F3>    load previously saved configuration
<F4>                   surround on/off
<CTRL>+<SHIFT>+<F4>    load default configuration
<F5>, <F6>             change panning
<SHIFT>+{<F5>, <F6>}   adjust reverb
<F7>, <F8>             change balance
<SHIFT>+{<F7>, <F8>}   adjust chorus
<F9>, <F10>            change speed
<|>                    song message
<F11>, <F12>           change pitch
<CTRL>+<F12>           (un)lock speed and pitch
<1>..<0>               select and toggle channel 1..10
<a>                    textmode spectrum analyzer
<ALT>+<a>              toggle analyzer mode
<b>                    phase graphs
<c>                    channel mode
<d>                    open a shell
<f>                    open fileselector
<g>                    graphic spectrum analyzer
<SHIFT>+<g>            graphic spectrum analyzer in 1024x768
<ALT>+<g>              toggle fast/fine algorithm in graphic spectrum
                       analyzer
<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
<n>                    note dots
<o>                    oscilloscopes mode
<ALT>+<o>              behaves like <Tab> in this mode
<p>                    pause
<q>                    quiet current channel
<s>                    solo current channel
<t>                    track/pattern mode
<v>                    peak power level mode
<w>                    wurfel 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 a page in instruments window
<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 *note Advanced usage: fileselector. for details

   (7) All these informations are only shown when a module or similar
type of file is played.

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

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

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

   (11) See appendix *Note wap::.

   (12) a set of drums is defined aswell


File: ocp,  Node: configuration,  Next: support,  Prev: player,  Up: Top

4 Configuration
***************

4.1 ocp.ini
===========

OCP can be widely configured using the `ocp.ini' file, which should
reside in the home directory ($HOME/.ocp/ocp.ini). 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 any text 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
*Note [general]: configuration. or *Note [sound]: configuration. 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.

   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.

4.2 [general]
=============

The _general_ section describes which internal modules or plugins to
load at startup. The required modules for for normal operation of OCP
is placed in a special directory, causing them to be automatically
loaded. All options listed in this section are loaded every time OCP
starts!  _general_ section looks like:
     [general]
     ;  link=
     ;  prelink=
     ;  datapath=     ; path to opencp's pictures and animations.
     ;  tempdir=

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 system 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.

4.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=medialib
     ;  prelink=

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.

4.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=devpALSA devpOSS devpCA devpSDL2 devpSDL devpNone devpDisk
       wavetabledevices=devwMixF devwmixQ devwMix devwNone
       mixrate=44100
       mixprocrate=4096000
       plrbufsize=200
       samprate=44100
       defwavetable=
       itchan=64
       cdsamplelinein=off
       bigmodules=devwMixF
       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.
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.
plrbufsize              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 diskwriter, this value will be used.
defwavetable            this option sets the default _wavetabledevice_.
                       Can also be set with _-sw_ command.
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)
amplify                 the default amplification to use within the
                       player. The following options are described in
                       section *note General: player. 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 (9) 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
                       (10) (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
4.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
                       *note Using the Compo mode: player. 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:
                          * 0 - none
                       
                          * 1 - big
                       
                          * 2 - side (only in 132 column modes)
pattern                 show the tracklist when starting OCP in textmode
insttype                the appearance of the instrument function:
                          * 0 - none
                       
                          * 1 - short
                       
                          * 2 - long
                       
                          * 3 - side (only in 132 column modes)
channeltype             the appearance of the channels in textmode:
                          * 0 - none
                       
                          * 1 - short
                       
                          * 2 - long
                       
                          * 3 - 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.

4.6 [fileselector]
==================

Except the first two options all options can also be specified at
runtime by pressing <ALT>+<z> in the fileselector.

     [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 OGA SID \
     		DAT AY  YM  HVL AHX PLS M3U PLT OGG
       movepath=  ; default path to move files
       screentype=2
       typecolors=on
       editwin=on
       writeinfo=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.(11)
movepath                the standard path to move files into. This is
                       describend in section *Note Advanced usage:
                       fileselector.
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.
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.

4.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]
       path=...
       mixer=...

   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.

   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.

4.7.1 ALSA
----------

ALSA is the modern sound architecture in Linux that can give direct
access to sound hardware. For many modern systems, the default output
driver might be a virtual sound card like PulseAudio making it possible
for the desktop volume applet to adjust volume per application.
     [devpALSA]
       card=default
       mixer=default

4.7.2 CA
--------

CoreAudio is the sound arcitecture for MacOS / OSX. The current state
of this driver might be non-working, as the main developer do not have
access to the given hardware. Testing/patching are welcome.

     [devpCA]

4.7.3 OSS
---------

Open Sound System is the common legacy sound API for most unix systems.
This driver should work on most unix-like operating systems like
different variants of BSD, old versions of Linux, etc.

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

4.7.4 SDL / SDL2
----------------

SDL/SDL2 is a cross-platform library that gives a common simple API for
playing audio, hiding the underlaying operating system. This library
will work on almost all systems.

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.

4.7.5 SDL/SDL2
--------------

SDL/SDL2 is a cross-platform library that gives a common simple API for
playing audio, hiding the underlaying operating system. This library
will work on almost all systems.

     [devpSDL]

     [devpSDL2]

4.7.6 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 *note fileselector:: section. You can also change looping
temporarily with the fileselector configuration while OCP is running.
See the fileselector advance usage *note Advanced usage: fileselector.
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 *note playerdevices: configuration. directive in the *note
[sound]: configuration.  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(12). In
the directory where you have started OCP (not necessaryly the directory
where the module is located) subsequent `.wav' files named after the
original filename will be created.

     [devpDisk]
       stereo=on
       16bit=on

4.7.7 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.

     [arcACE]
       get=ace32 e %a %n %d
       scaninsolid=false

scaninsolid             scan in solid archives. As this takes more time
                       you can disable this feature.

4.8 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.

   ---------- 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 *Note fileselector::.

   (4) mostly 32 channels

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

   (6) Something like 386SX

   (7) _<_486DX

   (8) See section *note bigmodules: fileselector. for details about
this feature

   (9) currently the SoundBlasterAWE and the TerraTecEWS

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

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

   (12) depending on your cpu power

   (13) You can toggle by using the _bigmodule_ feature described in
*Note bigmodules: fileselector.


File: ocp,  Node: support,  Next: faq,  Prev: configuration,  Up: Top

5 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.

5.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


File: ocp,  Node: faq,  Next: wap,  Prev: support,  Up: Top

6 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

     SDL, giving support for virtually any sound system

     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, MIDI

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

     The last OCP version is the 0.2.107 Version.

  5. Are you going to release new versions?

     Windows/DOS: Perhaps not. The Cubic team are 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. The MIDI file is rendered to an
     audio stream using the Timidity+ rendering engine to perform this
     (special rendered version, since Timidity+ is designed to be a
     standalone application)

  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 a Timidity+
     sound font installed.

  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' or
     `mailto:stian.skjelstad@gmail.com'. 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.



File: ocp,  Node: wap,  Prev: faq,  Up: Top

7 WurfelAnimator WAP
********************

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

7.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.

7.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.

7.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.

7.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



Tag Table:
Node: Top451
Node: starting2925
Ref: starting-Footnote-16750
Ref: starting-Footnote-26865
Ref: starting-Footnote-37066
Ref: starting-Footnote-47141
Node: fileselector7217
Ref: specialdrive19661
Ref: fileselector-Footnote-123134
Ref: fileselector-Footnote-223266
Node: player23314
Ref: player-Footnote-149368
Ref: player-Footnote-249478
Ref: player-Footnote-349657
Ref: player-Footnote-449745
Ref: player-Footnote-549947
Ref: player-Footnote-650128
Ref: player-Footnote-750188
Ref: player-Footnote-850283
Ref: player-Footnote-950438
Ref: player-Footnote-1050537
Ref: player-Footnote-1150615
Ref: player-Footnote-1250650
Node: configuration50692
Ref: configuration-Footnote-174051
Ref: configuration-Footnote-274133
Ref: configuration-Footnote-374183
Ref: configuration-Footnote-474293
Ref: configuration-Footnote-574320
Ref: configuration-Footnote-674381
Ref: configuration-Footnote-774410
Ref: configuration-Footnote-874427
Ref: configuration-Footnote-974510
Ref: configuration-Footnote-1074568
Ref: configuration-Footnote-1174696
Ref: configuration-Footnote-1274818
Ref: configuration-Footnote-1374855
Node: support74957
Node: faq76460
Node: wap80158
Ref: wap-Footnote-186682

End Tag Table
