Configuration
*************

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

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.  (And remember to make backups before changing vital parts of the ocp.ini)

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

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

[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. (Therefore it was named defaultconfig...)

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

[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. (you
can change devices by using the special
setup: drive described in section see fileselector.) 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 (mostly 32
channels). 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 (SoundBlaster 1.x or SoundBlaster Pro and compatibles) or
a very old processor (Something like 386SX) there is no need
to change this option.
mixprocrate
if you have a slow cpu (<486DX) 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. (See section
see bigmodules for details about this feature)
amplify
the default amplification to use within the player. The
following options are described in section see 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  (currently
the SoundBlasterAWE and the TerraTecEWS) 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  (this
has little to do with real Dolby Surround although there should be a
certain effect if you have such an amplifier) (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

[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
see 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:

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

[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. (however files with different extensions are
likely to be no valid module format, so they will be refused to load)
movepath
the standard path to move files into. This is describend in
section see 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.
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.

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.

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

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]

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

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.

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]

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 see fileselector section. You can also change looping temporarily with the fileselector configuration while OCP is running. See the fileselector advance usage see 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 see playerdevices directive in the see [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 (depending on your cpu power). 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

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  (You can toggle by using the bigmodule feature described in see bigmodules.)

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.

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.