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