1 '\" te
   2 .\"  Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
   3 .\" Copyright 2020 Peter Tribble.
   4 .\" 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.
   5 .\"  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
   6 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH AUDIORECORD 1 "Feb 8, 2020"
   8 .SH NAME
   9 audiorecord \- record an audio file
  10 .SH SYNOPSIS
  11 .nf
  12 \fBaudiorecord\fR [\fB-af\fR] [\fB-v\fR \fIvol\fR] [\fB-c\fR \fIchannels\fR] [\fB-s\fR \fIrate\fR]
  13      [\fB-e\fR \fIencoding\fR] [\fB-t\fR \fItime\fR] [\fB-i\fR \fIinfo\fR] [\fB-d\fR \fIdev\fR]
  14      [\fB-T\fR \fBau\fR|\fBaif\fR[\fBf\fR]|\fBwav\fR] [\fIfile\fR[.\fBau\fR|.\fBaif\fR[\fBf\fR]|.\fBwav\fR]]
  15 .fi
  16 
  17 .SH DESCRIPTION
  18 The \fBaudiorecord\fR utility copies audio data from the audio device to a
  19 named audio file, or to the standard output if no filename is present. If no
  20 output file is specified and standard output is a tty, the program exits with
  21 an error message.
  22 .sp
  23 .LP
  24 By default, monaural audio data is recorded at 8 kHz and encoded in \fBu-law\fR
  25 format. If the audio device supports additional configurations, the \fB-c\fR,
  26 \fB-s\fR, and \fB-e\fR options may be used to specify the data format. The
  27 output file is prefixed by an audio file header that identifies the format of
  28 the data encoded in the file.
  29 .sp
  30 .LP
  31 Recording begins immediately and continues until a \fBSIGINT\fR signal (for
  32 example, Control-c) is received. If the \fB-t\fR option is specified,
  33 \fBaudiorecord\fR stops when the specified quantity of data has been recorded.
  34 .sp
  35 .LP
  36 If the audio device is unavailable, that is, if another process currently has
  37 read access, \fBaudiorecord\fR prints an error message and exits immediately.
  38 .SH OPTIONS
  39 The following options are supported:
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fB-?\fR\fR
  44 .ad
  45 .RS 24n
  46 \fIHelp\fR: Prints a command line usage message.
  47 .RE
  48 
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fB-a\fR\fR
  53 .ad
  54 .RS 24n
  55 \fIAppend\fR: Appends the data on the end of the named audio file. The audio
  56 device must support the audio data format of the existing file.
  57 .RE
  58 
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fB-c\fR \fIchannels\fR\fR
  63 .ad
  64 .RS 24n
  65 \fIChannels\fR: Specifies the number of audio channels (1 or 2). The value may
  66 be specified as an integer or as the string \fBmono\fR or \fBstereo\fR. The
  67 default value is \fBmono\fR.
  68 .RE
  69 
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fB-d\fR \fIdev\fR\fR
  74 .ad
  75 .RS 24n
  76 \fIDevice\fR: The \fIdev\fR argument specifies an alternate audio device from
  77 which input should be taken. If the \fB-d\fR option is not specified, the
  78 \fBAUDIODEV\fR environment variable is consulted (see below). Otherwise,
  79 \fB/dev/audio\fR is used as the default audio device.
  80 .RE
  81 
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fB-e\fR \fIencoding\fR\fR
  86 .ad
  87 .RS 24n
  88 \fIEncoding\fR: Specifies the audio data encoding. This value may be one of
  89 \fBulaw\fR, \fBalaw\fR, or \fBlinear\fR. The default encoding is \fBulaw\fR.
  90 .RE
  91 
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fB-f\fR\fR
  96 .ad
  97 .RS 24n
  98 \fIForce\fR: When the \fB-a\fR flag is specified, the sample rate of the audio
  99 device must match the sample rate at which the original file was recorded. If
 100 the \fB-f\fR flag is also specified, sample rate differences are ignored, with
 101 a warning message printed on the standard error.
 102 .RE
 103 
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fB-i\fR \fIinfo\fR\fR
 108 .ad
 109 .RS 24n
 110 \fIInformation\fR: The `information' field of the output file header is set to
 111 the string specified by the \fIinfo\fR argument. This option cannot be
 112 specified in conjunction with the \fB-a\fR argument.
 113 .RE
 114 
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fB-s\fR \fIrate\fR\fR
 119 .ad
 120 .RS 24n
 121 \fISample Rate\fR: Specifies the sample rate, in samples per second. If a
 122 number is followed by the letter \fBk\fR, it is multiplied by 1000 (for
 123 example, 44.1k = 44100). The default sample rate is 8 kHz.
 124 .RE
 125 
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fB-t\fR \fItime\fR\fR
 130 .ad
 131 .RS 24n
 132 \fITime\fR: The \fItime\fR argument specifies the maximum length of time to
 133 record. Time can be specified as a floating-point value, indicating the number
 134 of seconds, or in the form: \fIhh:mm:ss.dd\fR, where the hour and minute
 135 specifications are optional.
 136 .RE
 137 
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fB-T\fR \fBau\fR | \fBaif\fR[\fBf\fR] | \fBwav\fR\fR
 142 .ad
 143 .RS 24n
 144 Specifies the audio file type to create. If the \fB-a\fR option is used, the
 145 file type must match the file to which it is being appended. Regardless of the
 146 file suffix, the type is set as specified in this option. If this option is not
 147 specified, the file suffix determines the type.
 148 .RE
 149 
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fB-v\fR \fIvol\fR\fR
 154 .ad
 155 .RS 24n
 156 \fIVolume\fR: The recording gain is set to the specified value before recording
 157 begins, and is reset to its previous level when \fBaudiorecord\fR exits. The
 158 \fIvol\fR argument is an integer value between 0 and 100, inclusive. If this
 159 argument is not specified, the input volume remains at the level most recently
 160 set by any process.
 161 .RE
 162 
 163 .SH OPERANDS
 164 .ne 2
 165 .na
 166 \fIfile\fR[\fB\&.au\fR|\fB\&.aif\fR[\fBf\fR]|\fB\&.wav\fR]
 167 .ad
 168 .sp .6
 169 .RS 4n
 170 \fIFile Specification\fR: The named audio file is rewritten, or appended. If no
 171 filename is present, and standard output is not a tty, or if the special
 172 filename "\fB\(mi\fR" is specified, output is directed to the standard
 173 output.
 174 .sp
 175 If the \fB-T\fR option is not specified, the file suffix determines the type of
 176 file. If the suffix is not recognized, the default is \fB\&.au\fR. If the
 177 \fB-T\fR option \fBis\fR specified, that file type is used regardless of the
 178 file suffix.
 179 .RE
 180 
 181 .SH USAGE
 182 See \fBlargefile\fR(5) for the description of the behavior of \fBaudiorecord\fR
 183 when encountering files greater than or equal to 2 Gbyte (2^31 bytes).
 184 .SH ENVIRONMENT VARIABLES
 185 .ne 2
 186 .na
 187 \fB\fBAUDIODEV\fR\fR
 188 .ad
 189 .RS 12n
 190 The full path name of the audio device to record from, if no \fB-d\fR argument
 191 is supplied. If the \fBAUDIODEV\fR variable is not set, \fB/dev/audio\fR is
 192 used.
 193 .RE
 194 
 195 .SH SEE ALSO
 196 \fBaudioconvert\fR(1), \fBaudioplay\fR(1),
 197 \fBlargefile\fR(5), \fBaudio\fR(7I)