usr/src/man/man1/audioplay.1

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