.\"	$NetBSD: audioplay.1,v 1.30.6.2 2024/03/12 10:04:23 martin Exp $
.\"
.\" Copyright (c) 1998, 1999, 2002, 2010, 2019, 2024 Matthew R. Green
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd March 3, 2024
.Dt AUDIOPLAY 1
.Os
.Sh NAME
.Nm audioplay
.Nd play audio files
.Sh SYNOPSIS
.Nm
.Op Fl hinqV
.Op Fl B Ar buffersize
.Op Fl b Ar balance
.Op Fl d Ar device
.Op Fl p Ar port
.Op Fl v Ar volume
.Oo
.Fl f
.Op Fl c Ar channels
.Op Fl e Ar encoding
.Op Fl P Ar precision
.Op Fl s Ar sample-rate
.Oc
.Op files ...
.Sh DESCRIPTION
The
.Nm
program copies the named audio files, or the standard input if no files are
named, to the audio device.
The special name
.Dq -
is assumed to mean the standard input.
The input files must contain a valid audio header, and the encoding must be
understood by the underlying driver.
.Sh OPTIONS
The following options are available:
.Bl -tag -width 123456
.It Fl B
Set the write block size to
.Ar buffersize .
The default value is the play.buffer_size of the audio device.
.It Fl b
Set the balance to
.Ar balance .
This value must be between 0 and 63.
.It Fl c
When combined with the
.Fl f
option, sets the number of channels to its argument.
.It Fl d
Set the audio device to be
.Ar device .
The default is
.Pa /dev/sound .
.It Fl e
When combined with the
.Fl f
option, sets the encoding to its argument.
Possible values are
.Cm mulaw ,
.Cm ulaw ,
.Cm alaw ,
.Cm slinear ,
.Cm linear ,
.Cm ulinear ,
.Cm adpcm ,
.Cm ADPCM ,
.Cm slinear_le ,
.Cm linear_le ,
.Cm ulinear_le ,
.Cm slinear_be ,
.Cm linear_be ,
.Cm ulinear_be ,
.Cm mpeg_l1_stream ,
.Cm mpeg_l1_packets ,
.Cm mpeg_l1_system ,
.Cm mpeg_l2_stream ,
.Cm mpeg_l2_packets ,
and
.Cm mpeg_l2_system .
.It Fl f
Force playing, even if the format is unknown.
The
.Fl f
flag can be used in addition with the
.Fl c ,
.Fl e ,
.Fl P ,
and
.Fl s
flags to change the number of channels, encoding, precision, and
sample rate.
.It Fl h
Print a help message.
.It Fl i
If the audio device cannot be opened, exit now rather than wait for it.
.It Fl n
Do not write audio data, only parse files for sanity.
.It Fl P
When combined with the
.Fl f
option, sets the precision to its argument.
This value must be either 4, 8, 16, 24 or 32.
.It Fl p
Set the output port to
.Ar port .
The valid values of
.Ar port
are
.Dq speaker ,
.Dq headphone
and
.Dq line .
.It Fl q
Be quiet.
.It Fl s
When combined with the
.Fl f
option, sets the sample rate to its argument.
This value must be a valid value for the audio device or an error will
be returned.
.It Fl V
Be verbose.
.It Fl v
Set the volume (gain) to
.Ar volume .
This value must be between 0 and 255.
.El
.Sh ENVIRONMENT
.Bl -tag -width AUDIOCTLDEVICE
.It AUDIOCTLDEVICE
the audio control device to be used.
.It AUDIODEVICE
the audio device to be used.
.El
.Sh EXAMPLES
Play a raw dump taken from an audio CD ROM:
.Pp
.Dl "audioplay -f -c 2 -P 16 -s 44100 -e slinear_le filename"
.Pp
The
.Xr audioctl 1
program can be used to show the available supported encodings:
.Pp
.Dl "audioctl encodings"
.Sh NOTES
.Nm
can be used to play Sun/NeXT audio files, and also RIFF WAVE audio files.
.Nm
can be configured in a web browser as the program to use when playing audio
files.
.Pp
In addition to the audio driver encodings list in the EXAMPLES section,
.Nm
supports playing IEEE floating point data in RIFF WAVE audio files
(with one caveat that the floating point size must be native).
In this case
.Nm
converts the floating point data into signed linear samples before
they are passed to the chosen audio device.
.Sh ERRORS
If the audio device or the control device can not be opened, an error is
returned.
.Pp
If an invalid parameter is specified, an error is returned.
The set of valid values for any audio parameter is specified by the
hardware driver.
.Sh SEE ALSO
.Xr audioctl 1 ,
.Xr audiorecord 1 ,
.Xr audio 4
.Sh HISTORY
The
.Nm
program was first seen in SunOS 5.
The
.Nx
.Nm
was first made available in
.Nx 1.4 .
Support for RIFF WAVE recording was introduced in
.Nx 1.6 .
Support for RIFF WAVE IEEE floating point data was introduced in
.Nx 10.0 .
.Sh AUTHORS
The
.Nm
program was written by
.An Matthew R. Green Aq Mt mrg@eterna23.net .