.\" -*- nroff -*-
.\" adplay is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; see the file COPYING.  If not, write to
.\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.TH ADPLAY 1 "May 24, 2020" "AdPlay/UNIX 1.8.1" "User Commands"
.SH NAME
adplay \- AdPlay/UNIX console-based OPL2 audio player
.SH SYNOPSIS
.B adplay
.RI "[OPTION]... FILE..."
.SH DESCRIPTION
AdPlay/UNIX is AdPlug's UNIX console-based frontend. It tries to play
back all given FILEs, using one of many available output mechanisms.
.PP
AdPlay/UNIX plays endlessly, if only one file is given. With multiple files,
it plays them in a sequence and exits after the last file. The same can
also be accomplished with only one file, by using the \fB-o\fP
option. When using the disk writer, \fB-o\fP is implied.
.SH EXIT STATUS
\fBadplay\fP returns 0 on successful operation. 1 is returned
otherwise.
.SH OUTPUT MECHANISMS
.PP
AdPlay/UNIX can play back using many different output mechanisms,
which can be selected with the \fB-O\fP argument. The availability of
a method depends on compile-time settings. Available methods are
printed out after the help text, displayed with \fB--help\fP.
.PP
Next is a brief description of all output mechanisms, following their
abbreviations:
.SS oss -- Open Sound System (OSS) driver
.PP
This output method is available on most Linux and other UNIX systems.
.SS null -- Total silence
.PP
Discards anything sent to it. It can be useful for testing purposes.
.SS disk -- Disk writer
.PP
Writes its output to a file in Microsoft RIFF WAVE format.
.SS esound -- EsounD output
.PP
Creates a socket connection to an EsounD server and streams the audio
to it.
.SS qsa -- QNX Sound Architecture (QSA) driver
.PP
Uses the QNX system's standard output method.
.SS sdl -- Simple Directmedia Layer (SDL) driver
.PP
Uses the SDL library for sound output. The library has a broader
platform support than any of the other output methods. Thus, it could
be useful on some exotic systems.
.SS alsa -- Advanced Linux Sound Architecture (ALSA) driver
.PP
Uses the standard output method on newer Linux systems.
.SS ao -- libao driver
.PP
Libao is a cross-platform audio library with very broad platform
support. Might be useful on systems, where SDL is not available, and
generally to do tricky things.
.SH OPTIONS
.PP
The order of the option commandline parameters is not important,
except for the \fB-d\fP option, which always has to be specified after
an \fB-O\fP option.
.SS "Output selection:"
.TP
.B -O, --output=OUTPUT
Specify output mechanism. Available mechanisms depend on compilation
settings and are printed on \fB--help\fP output. A reasonable default
is automatically selected, based on the availability of the output
mechanisms.
.SS "OSS driver (oss) specific:"
.TP
.B -d --device=FILE
Set sound output device file to FILE. This is \fB/dev/dsp\fP by
default.
.SS "Disk writer (disk) specific:"
.TP
.B -d --device=FILE
Write sound data to FILE. The data is written in Microsoft RIFF WAVE
format (little-endian). You can specify a single '-' to write to
stdout instead. This option has no default and must be specified when
the disk writer is to be used!
.SS "EsounD output (esound) specific:"
.TP
.B -d --device=URL
Connect to "hostname:port" combination in URL. Example:
"myhost.sound.net:1234". The default is "localhost:16001".
.SS "ALSA driver (alsa) specific:"
.TP
.B -d --device=DEVICE
Set sound output device to DEVICE. This is \fBplughw:0,0\fP by default.
.SS "Playback quality:"
.TP
.B -8, --8bit
Use only 8-bit samples for playback.
.TP
.B --16bit
Use only 16-bit samples for playback (default).
.TP
.B -f, --freq=FREQ
Set playback frequency to FREQ, in Hz. This is 44100Hz by default.
.TP
.B --stereo
Use only stereo samples for playback. The sound stream is just doubled, no
further audio processing is done. This option is pretty useless unless you
have very obscure audio hardware that only accepts stereo streams. AdPlug
only generates mono streams because the OPL2 only generates mono sound.
.TP
.B --mono
Use only mono samples for playback (default if AdPlug <= 2.1.)
.TP
.B --surround
Use only stereo samples for playback, but generate them from two mono OPL2
chips.  One OPL2 chip is very slightly transposed to produce a pleasant
harmonic/surround sound effect (default if AdPlug >= 2.2.)
.TP
.B -b --buffer=SIZE
Set sound buffer size to SIZE samples. If you notice sound skipping with the
default setting, try a greater buffer size. Note that this is measured in
samples, not bytes! This is 2048 samples by default. Only the OSS,
SDL, ALSA and libao output drivers support this option.
.SS "Informative output:"
.TP
.B -i --instruments
Display instrument names (if available).
.TP
.B -r --realtime
Display realtime playback information, while playing. This will display a
one-line status bar, containing essential playback information.
.TP
.B -m --message
Display the song message (if available).
.SS "Playback:"
.TP
.B -s --subsong=N
Play subsong number N, instead of the default subsong of the
file. Only useful for file formats that support multiple subsongs.
.TP
.B -o --once
Play just once, don't loop. This will exit \fBadplay\fP after the song
ended. This is the default when multiple \fBFILEs\fP are given.
.SS "Miscellaneous:"
.TP
.B -D, --database=FILE
Additionally use database file FILE. This option may be specified
multiple times. Each database file is additionally merged with the
others, creating one large database on the fly.
.TP
.B -q, --quiet
Be more quiet.
.TP
.B -v, --verbose
Be more verbose.
.TP
.B -h, --help
Show summary of options.
.TP
.B -V, --version
Show version of program.
.SH AUTHOR
Simon Peter <dn.tlp@gmx.net>