'\" te
.\"  Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 2020 Peter Tribble.
.\" 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 AUDIORECORD 1 "Feb 8, 2020"
.SH NAME
audiorecord \- record an audio file
.SH SYNOPSIS
.nf
\fBaudiorecord\fR [\fB-af\fR] [\fB-v\fR \fIvol\fR] [\fB-c\fR \fIchannels\fR] [\fB-s\fR \fIrate\fR]
     [\fB-e\fR \fIencoding\fR] [\fB-t\fR \fItime\fR] [\fB-i\fR \fIinfo\fR] [\fB-d\fR \fIdev\fR]
     [\fB-T\fR \fBau\fR|\fBaif\fR[\fBf\fR]|\fBwav\fR] [\fIfile\fR[.\fBau\fR|.\fBaif\fR[\fBf\fR]|.\fBwav\fR]]
.fi

.SH DESCRIPTION
The \fBaudiorecord\fR utility copies audio data from the audio device to a
named audio file, or to the standard output if no filename is present. If no
output file is specified and standard output is a tty, the program exits with
an error message.
.sp
.LP
By default, monaural audio data is recorded at 8 kHz and encoded in \fBu-law\fR
format. If the audio device supports additional configurations, the \fB-c\fR,
\fB-s\fR, and \fB-e\fR options may be used to specify the data format. The
output file is prefixed by an audio file header that identifies the format of
the data encoded in the file.
.sp
.LP
Recording begins immediately and continues until a \fBSIGINT\fR signal (for
example, Control-c) is received. If the \fB-t\fR option is specified,
\fBaudiorecord\fR stops when the specified quantity of data has been recorded.
.sp
.LP
If the audio device is unavailable, that is, if another process currently has
read access, \fBaudiorecord\fR prints an error message and exits immediately.
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-?\fR\fR
.ad
.RS 24n
\fIHelp\fR: Prints a command line usage message.
.RE

.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 24n
\fIAppend\fR: Appends the data on the end of the named audio file. The audio
device must support the audio data format of the existing file.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIchannels\fR\fR
.ad
.RS 24n
\fIChannels\fR: Specifies the number of audio channels (1 or 2). The value may
be specified as an integer or as the string \fBmono\fR or \fBstereo\fR. The
default value is \fBmono\fR.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR \fIdev\fR\fR
.ad
.RS 24n
\fIDevice\fR: The \fIdev\fR argument specifies an alternate audio device from
which input should be taken. 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-e\fR \fIencoding\fR\fR
.ad
.RS 24n
\fIEncoding\fR: Specifies the audio data encoding. This value may be one of
\fBulaw\fR, \fBalaw\fR, or \fBlinear\fR. The default encoding is \fBulaw\fR.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 24n
\fIForce\fR: When the \fB-a\fR flag is specified, the sample rate of the audio
device must match the sample rate at which the original file was recorded. If
the \fB-f\fR flag is also specified, sample rate differences are ignored, with
a warning message printed on the standard error.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIinfo\fR\fR
.ad
.RS 24n
\fIInformation\fR: The `information' field of the output file header is set to
the string specified by the \fIinfo\fR argument. This option cannot be
specified in conjunction with the \fB-a\fR argument.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIrate\fR\fR
.ad
.RS 24n
\fISample Rate\fR: Specifies the sample rate, in samples per second. If a
number is followed by the letter \fBk\fR, it is multiplied by 1000 (for
example, 44.1k = 44100). The default sample rate is 8 kHz.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fItime\fR\fR
.ad
.RS 24n
\fITime\fR: The \fItime\fR argument specifies the maximum length of time to
record. Time can be specified as a floating-point value, indicating the number
of seconds, or in the form: \fIhh:mm:ss.dd\fR, where the hour and minute
specifications are optional.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fBau\fR | \fBaif\fR[\fBf\fR] | \fBwav\fR\fR
.ad
.RS 24n
Specifies the audio file type to create. If the \fB-a\fR option is used, the
file type must match the file to which it is being appended. Regardless of the
file suffix, the type is set as specified in this option. If this option is not
specified, the file suffix determines the type.
.RE

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

.SH OPERANDS
.ne 2
.na
\fIfile\fR[\fB\&.au\fR|\fB\&.aif\fR[\fBf\fR]|\fB\&.wav\fR]
.ad
.sp .6
.RS 4n
\fIFile Specification\fR: The named audio file is rewritten, or appended. If no
filename is present, and standard output is not a tty, or if the special
filename "\fB\(mi\fR" is specified, output is directed to the standard
output.
.sp
If the \fB-T\fR option is not specified, the file suffix determines the type of
file. If the suffix is not recognized, the default is \fB\&.au\fR. If the
\fB-T\fR option \fBis\fR specified, that file type is used regardless of the
file suffix.
.RE

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

.SH SEE ALSO
\fBaudioconvert\fR(1), \fBaudioplay\fR(1),
\fBlargefile\fR(5), \fBaudio\fR(7I)