'\" te
.\"  Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH AUDIOPLAY 1 "May 1, 2009"
.SH NAME
audioplay \- play audio files
.SH SYNOPSIS
.LP
.nf
\fBaudioplay\fR [\fB-iV\fR] [\fB-v\fR \fIvol\fR] [\fB-d\fR \fIdev\fR] [\fIfile\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBaudioplay\fR utility copies the named audio files (or the standard input
if no filenames are present) to the audio device. If no input file is specified
and standard input is a tty, the program exits with an error message.
.sp
.LP
The input files must contain a valid audio file header. The encoding
information in this header is matched against the capabilities of the audio
device and, if the data formats are incompatible, an error message is printed
and the file is skipped. Compressed \fBADPCM\fR (G.721) monaural audio data is
automatically uncompressed before playing.
.sp
.LP
Minor deviations in sampling frequency (that is, less than 1%) are ordinarily
ignored. This allows, for instance, data sampled at 8012 Hz to be played on an
audio device that only supports 8000 Hz. If the \fB-V\fR option is present,
such deviations are flagged with warning messages.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-d\fR \fIdev\fR\fR
.ad
.RS 11n
\fIDevice\fR: The \fIdev\fR argument specifies an alternate audio device to
which output should be directed. If the \fB-d\fR option is not specified, the
\fBAUDIODEV\fR environment variable is consulted (see below). Otherwise,
\fB/dev/audio\fR is used as the default audio device.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 11n
\fIImmediate\fR: If the audio device is unavailable (that is, another process
currently has write access), \fBaudioplay\fR ordinarily waits until it can
obtain access to the device. When the \fB-i\fR option is present,
\fBaudioplay\fR prints an error message and exits immediately if the device is
busy.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR \fIvol\fR\fR
.ad
.RS 11n
\fIVolume\fR: The output volume is set to the specified value before playing
begins, and is reset to its previous level when \fBaudioplay\fR exits. The
\fIvol\fR argument is an integer value between 0 and 100, inclusive. If this
argument is not specified, the output volume remains at the level most recently
set by any process.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.RS 11n
\fIVerbose\fR: Prints messages on the standard error when waiting for access to
the audio device or when sample rate deviations are detected.
.RE

.sp
.ne 2
.na
\fB\fB\(mi\e?\fR\fR
.ad
.RS 11n
\fIHelp\fR: Prints a command line usage message.
.RE

.SH OPERANDS
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 8n
\fIFile Specification\fR: Audio files named on the command line are played
sequentially. If no filenames are present, the standard input stream (if it is
not a tty) is played (it, too, must contain an audio file header). The special
filename \fB\(mi\fR can be used to read the standard input stream instead of a
file. If a relative path name is supplied, the \fBAUDIOPATH\fR environment
variable is consulted (see below).
.RE

.SH USAGE
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBaudioplay\fR
when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH ENVIRONMENT VARIABLES
.sp
.ne 2
.na
\fB\fBAUDIODEV\fR\fR
.ad
.RS 13n
The full path name of the audio device to write to, if no \fB-d\fR argument is
supplied. If the \fBAUDIODEV\fR variable is not set, \fB/dev/audio\fR is used.
.RE

.sp
.ne 2
.na
\fB\fBAUDIOPATH\fR\fR
.ad
.RS 13n
A colon-separated list of directories in which to search for audio files whose
names are given by relative pathnames. The current directory (\fB\&.\fR) can be
specified explicitly in the search path. If the \fBAUDIOPATH\fR variable is not
set, only the current directory is searched.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Architecture	SPARC, x86
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBaudioconvert\fR(1), \fBaudiorecord\fR(1), \fBmixerctl\fR(1),
\fBattributes\fR(5), \fBlargefile\fR(5), \fBaudio\fR(7I)
.SH BUGS
.sp
.LP
\fBaudioplay\fR currently supports a limited set of audio format conversions.
If the audio file is not in a format supported by the audio device, it must
first be converted. For example, to convert to voice format on the fly, use the
command:
.sp
.in +2
.nf
example% \fBaudioconvert -f voice myfile | audioplay\fR
.fi
.in -2
.sp

.sp
.LP
The format conversion is not always be able to keep up with the audio output.
If this is the case, you should convert to a temporary file before playing the
data.