1 '\" te
   2 .\"  Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\"  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
   5 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH AUDIOPLAY 1 "May 13, 2017"
   7 .SH NAME
   8 audioplay \- play audio files
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBaudioplay\fR [\fB-iV\fR] [\fB-v\fR \fIvol\fR] [\fB-d\fR \fIdev\fR] [\fIfile\fR]...
  13 .fi
  14 
  15 .SH DESCRIPTION
  16 .LP
  17 The \fBaudioplay\fR utility copies the named audio files (or the standard input
  18 if no filenames are present) to the audio device. If no input file is specified
  19 and standard input is a tty, the program exits with an error message.
  20 .sp
  21 .LP
  22 The input files must contain a valid audio file header. The encoding
  23 information in this header is matched against the capabilities of the audio
  24 device and, if the data formats are incompatible, an error message is printed
  25 and the file is skipped. Compressed \fBADPCM\fR (G.721) monaural audio data is
  26 automatically uncompressed before playing.
  27 .sp
  28 .LP
  29 Minor deviations in sampling frequency (that is, less than 1%) are ordinarily
  30 ignored. This allows, for instance, data sampled at 8012 Hz to be played on an
  31 audio device that only supports 8000 Hz. If the \fB-V\fR option is present,
  32 such deviations are flagged with warning messages.
  33 .SH OPTIONS
  34 .LP
  35 The following options are supported:
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fB-d\fR \fIdev\fR\fR
  40 .ad
  41 .RS 11n
  42 \fIDevice\fR: The \fIdev\fR argument specifies an alternate audio device to
  43 which output should be directed. If the \fB-d\fR option is not specified, the
  44 \fBAUDIODEV\fR environment variable is consulted (see below). Otherwise,
  45 \fB/dev/audio\fR is used as the default audio device.
  46 .RE
  47 
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fB-i\fR\fR
  52 .ad
  53 .RS 11n
  54 \fIImmediate\fR: If the audio device is unavailable (that is, another process
  55 currently has write access), \fBaudioplay\fR ordinarily waits until it can
  56 obtain access to the device. When the \fB-i\fR option is present,
  57 \fBaudioplay\fR prints an error message and exits immediately if the device is
  58 busy.
  59 .RE
  60 
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fB-v\fR \fIvol\fR\fR
  65 .ad
  66 .RS 11n
  67 \fIVolume\fR: The output volume is set to the specified value before playing
  68 begins, and is reset to its previous level when \fBaudioplay\fR exits. The
  69 \fIvol\fR argument is an integer value between 0 and 100, inclusive. If this
  70 argument is not specified, the output volume remains at the level most recently
  71 set by any process.
  72 .RE
  73 
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fB-V\fR\fR
  78 .ad
  79 .RS 11n
  80 \fIVerbose\fR: Prints messages on the standard error when waiting for access to
  81 the audio device or when sample rate deviations are detected.
  82 .RE
  83 
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fB\(mi\e?\fR\fR
  88 .ad
  89 .RS 11n
  90 \fIHelp\fR: Prints a command line usage message.
  91 .RE
  92 
  93 .SH OPERANDS
  94 .ne 2
  95 .na
  96 \fB\fIfile\fR\fR
  97 .ad
  98 .RS 8n
  99 \fIFile Specification\fR: Audio files named on the command line are played
 100 sequentially. If no filenames are present, the standard input stream (if it is
 101 not a tty) is played (it, too, must contain an audio file header). The special
 102 filename \fB\(mi\fR can be used to read the standard input stream instead of a
 103 file. If a relative path name is supplied, the \fBAUDIOPATH\fR environment
 104 variable is consulted (see below).
 105 .RE
 106 
 107 .SH USAGE
 108 .LP
 109 See \fBlargefile\fR(5) for the description of the behavior of \fBaudioplay\fR
 110 when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
 111 .SH ENVIRONMENT VARIABLES
 112 .ne 2
 113 .na
 114 \fB\fBAUDIODEV\fR\fR
 115 .ad
 116 .RS 13n
 117 The full path name of the audio device to write to, if no \fB-d\fR argument is
 118 supplied. If the \fBAUDIODEV\fR variable is not set, \fB/dev/audio\fR is used.
 119 .RE
 120 
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBAUDIOPATH\fR\fR
 125 .ad
 126 .RS 13n
 127 A colon-separated list of directories in which to search for audio files whose
 128 names are given by relative pathnames. The current directory (\fB\&.\fR) can be
 129 specified explicitly in the search path. If the \fBAUDIOPATH\fR variable is not
 130 set, only the current directory is searched.
 131 .RE
 132 
 133 .SH ATTRIBUTES
 134 .LP
 135 See \fBattributes\fR(5) for descriptions of the following attributes:
 136 .sp
 137 
 138 .sp
 139 .TS
 140 box;
 141 c | c
 142 l | l .
 143 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 144 _
 145 Architecture    SPARC, x86
 146 _
 147 Interface Stability     Committed
 148 .TE
 149 
 150 .SH SEE ALSO
 151 .LP
 152 \fBaudioconvert\fR(1), \fBaudiorecord\fR(1),
 153 \fBattributes\fR(5), \fBlargefile\fR(5), \fBaudio\fR(7I)
 154 .SH BUGS
 155 .LP
 156 \fBaudioplay\fR currently supports a limited set of audio format conversions.
 157 If the audio file is not in a format supported by the audio device, it must
 158 first be converted. For example, to convert to voice format on the fly, use the
 159 command:
 160 .sp
 161 .in +2
 162 .nf
 163 example% \fBaudioconvert -f voice myfile | audioplay\fR
 164 .fi
 165 .in -2
 166 .sp
 167 
 168 .sp
 169 .LP
 170 The format conversion is not always be able to keep up with the audio output.
 171 If this is the case, you should convert to a temporary file before playing the
 172 data.