% OpenCP Module Player
%
% Documentation LaTeX source
%
% revision history: (please note changes here)
% -doj990413  Dirk Jagdmann  <doj@cubic.org>
%   -initial release

\chapter{Starting OpenCP}
After starting \cp\ from the command line the dos extender is loaded. By
default \cp\ looks for a file \texttt{dos4gw.exe} in all
directories included in the path statement and the home directory.
When it cannot find this file, \cp\ exists with the error message
\texttt{could not execute: No such file or directory}.

\cp\ then tries to detect the sound cards defined in the \texttt{cp.ini} file.
If the card is not found you cannot use it. If more than one sound card is
installed and found by \cp\ the first one listed in the \texttt{cp.ini} is
used as the default device.\footnote{You can change this in the player by using
the \texttt{@:} device. See page \pageref{specialdrive} for detail.}

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 \cp\ starts with the
player.\footnote{This will work if the file is inside an archivr located in the
current directory. If no (unpacked) file is found all archives in the current
directory are searched for an appropriate filename.} When the parameter is
the name of a directory the fileselector starts with the given directory.
If the parameter equals a certain archive all files found inside the archive
will be played (by adding them to the playlist).

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

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

\cp\ can be configured using the command line, although the configuration
through the \texttt{cp.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 \emph{help} switch.

The command line looks like: \\
\texttt{cp [prefix option[,option]] [specialOption] [filename]}\footnote{Square
brackets [] indicate an optional item that can be repeated.}

Special options include: 
\begin{dojlist}
\item[\texttt{-h}] show a help screen 
\item[\texttt{-m}] use a monochrome graphics card (hercules or mda). Useful
when starting \cp\ under windows.
\item[\texttt{-c<name>}] use a configuration defined in \texttt{cp.ini} 
\end{dojlist}

Fileselector options are envoked with \texttt{-f}. The values in square brackets define
a choice that must be made when using one of these options. 
\begin{dojlist}
\item[\texttt{r[0|1]}] remove played files from playlist 
\item[\texttt{o[0|1]}] don't scramble playlist order 
\item[\texttt{l[0|1]}] loop modules 
\end{dojlist}

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

Device setting are accomplished with the suffix \texttt{-s}. 
\begin{dojlist}
\item[\texttt{p<name>}]            use specific player device 
\item[\texttt{s<name>}]            use specific sampler device 
\item[\texttt{w<name>}]            use specific wavetable device 
\item[\texttt{r<0{\dojdots}64000>}]  sample at specific rate 
\item[\texttt{8}]                  play/sample/mix as 8bit 
\item[\texttt{m}]                  play/sample/mix mono 
\end{dojlist}

Finally an example to illustrate the above features:
\begin{quote}
\texttt{cp -fl0,r1 -va80,p50,f2 -spdevpdisk -sr44100 ftstar.xm}
\end{quote}
This will start \cp\ and load the file \texttt{ftstar.xm}\footnote{A marvelous piece of
music composed by KB which won The Party 1997.}. The music will be played once
and will not loop (\texttt{-fl0, r1}). Further the player is advised to amplify
this file with 80\%, set the panning to 50\% and interpolate every sample
(\texttt{-va80, p50, f2}). The mixed output will be saved into \texttt{.wav}
format through the \emph{diskwriter} device (\texttt{-spdevpdisk}) with a
sample rate of 44.1KHz (\texttt{-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
\emph{sample image} of a module is by using predefined configurations with
the \texttt{-c} switch. Have a look at the section \emph{Using the diskwriter}
on page \pageref{diskwriter}.
