path: root/usr/src/man/man1/audioconvert.1

'\" te
.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved
.\" 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 AUDIOCONVERT 1 "Feb 8, 2020"
.SH NAME
audioconvert \- convert audio file formats
.SH SYNOPSIS
.nf
\fBaudioconvert\fR [\fB-pF\fR] [\fB-f\fR \fIoutfmt\fR] [\fB-o\fR \fIoutfile\fR]
     [ [\fB-i\fR \fIinfmt\fR] [\fIfile\fR]...] ...
.fi

.SH DESCRIPTION
\fBaudioconvert\fR converts audio data between a set of supported audio
encodings and file formats. It can be used to compress and decompress audio
data, to add audio file headers to raw audio data files, and to convert between
standard data encodings, such as u-law and linear PCM.
.sp
.LP
If no filenames are present, \fBaudioconvert\fR reads the data from the
standard input stream and writes an audio file to the standard output.
Otherwise, input files are processed in order, concatenated, and written to the
output file.
.sp
.LP
Input files are expected to contain audio file headers that identify the audio
data format.  If the audio data does not contain a recognizable header, the
format must be specified with the \fB-i\fR option, using the \fBrate\fR,
\fBencoding\fR, and \fBchannels\fR keywords to identify the input data format.
.sp
.LP
The output file format is derived by updating the format of the first input
file with the format options in the \fB-f\fR specification. If \fB-p\fR is not
specified, all subsequent input files are converted to this resulting format
and concatenated together. The output file will contain an audio file header,
unless \fBformat\fR=\fIraw\fR is specified in the output format options.
.sp
.LP
Input files may be converted in place by using the \fB-p\fR option. When
\fB-p\fR is in effect, the format of each input file is modified according to
the \fB-f\fR option to determine the output format. The existing files are then
overwritten with the converted data.
.sp
.LP
The \fBfile\fR(1) command decodes and prints the audio data format of Sun audio
files.
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 14n
\fIIn Place\fR: The input files are individually converted to the format
specified by the \fB-f\fR option and rewritten. If a target file is a symbolic
link, the underlying file will be rewritten. The \fB-o\fR option may not be
specified with \fB-p\fR.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR\fR
.ad
.RS 14n
\fIForce\fR: This option forces \fBaudioconvert\fR to ignore any file header
for input files whose format is specified by the \fB-i\fR option. If \fB-F\fR
is not specified, \fBaudioconvert\fR ignores the \fB-i\fR option for input
files that contain valid audio file headers.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIoutfmt\fR\fR
.ad
.RS 14n
\fIOutput Format\fR: This option is used to specify the file format and data
encoding of the output file. Defaults for unspecified fields are derived from
the input file format. Valid keywords and values are listed in the next
section.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIoutfile\fR\fR
.ad
.RS 14n
\fIOutput File\fR: All input files are concatenated, converted to the output
format, and written to the named output file. If \fB-o\fR and \fB-p\fR are not
specified, the concatenated output is written to the standard output. The
\fB-p\fR option may not be specified with \fB-o\fR.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIinfmt\fR\fR
.ad
.RS 14n
\fIInput Format\fR: This option is used to specify the data encoding of raw
input files. Ordinarily, the input data format is derived from the audio file
header. This option is required when converting audio data that is not preceded
by a valid audio file header. If \fB-i\fR is specified for an input file that
contains an audio file header, the input format string will be ignored, unless
\fB-F\fR is present. The format specification syntax is the same as the
\fB-f\fR output file format.
.sp
Multiple input formats may be specified. An input format describes all input
files following that specification, until a new input format is specified.
.RE

.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 14n
\fIFile Specification\fR: The named audio files are concatenated, converted to
the output format, and written out. If no file name is present, or if the
special file name `\(mi' is specified, audio data is read from the standard
input.
.RE

.sp
.ne 2
.na
\fB\fB-?\fR\fR
.ad
.RS 14n
\fIHelp\fR: Prints a command line usage message.
.RE

.SS "Format Specification"
The syntax for the input and output format specification is:
.sp
.LP
\fIkeyword\fR=\fIvalue\fR[,\fIkeyword\fR=\fIvalue\fR \|.\|.\|.\|]
.sp
.LP
with no intervening whitespace. Unambiguous values may be used without the
preceding \fIkeyword\fR=.
.sp
.ne 2
.na
\fB\fBrate\fR\fR
.ad
.RS 12n
The audio sampling rate is specified in samples per second. If a number is
followed by the letter \fBk\fR, it is multiplied by 1000 (for example, 44.1k =
44100). Standard of the commonly used sample rates are: 8k, 16k, 32k, 44.1k,
and 48k.
.RE

.sp
.ne 2
.na
\fB\fBchannels\fR\fR
.ad
.RS 12n
The number of interleaved channels is specified as an integer. The words
\fBmono\fR and \fBstereo\fR may also be used to specify one and two channel
data, respectively.
.RE

.sp
.ne 2
.na
\fB\fBencoding\fR\fR
.ad
.RS 12n
This option specifies the digital audio data representation. Encodings
determine precision implicitly (\fBulaw\fR implies 8-bit precision) or
explicitly as part of the name (for example, \fBlinear16\fR). Valid encoding
values are:
.sp
.ne 2
.na
\fB\fBulaw\fR\fR
.ad
.RS 13n
\fBCCITT G.711\fR u-law encoding. This is an 8-bit format primarily used for
telephone quality speech.
.RE

.sp
.ne 2
.na
\fB\fBalaw\fR\fR
.ad
.RS 13n
\fBCCITT G.711\fR A-law encoding. This is an 8-bit format primarily used for
telephone quality speech in Europe.
.RE

.sp
.ne 2
.na
\fB\fBlinear8\fR,\fR
.ad
.br
.na
\fB\fBlinear16\fR,\fR
.ad
.br
.na
\fB\fBlinear32\fR\fR
.ad
.RS 13n
Linear Pulse Code Modulation (PCM) encoding. The name identifies the number of
bits of precision. \fBlinear16\fR is typically used for high quality audio
data.
.RE

.sp
.ne 2
.na
\fB\fBpcm\fR\fR
.ad
.RS 13n
Same as \fBlinear16\fR.
.RE

.sp
.ne 2
.na
\fB\fBg721\fR\fR
.ad
.RS 13n
\fBCCITT G.721\fR compression format. This encoding uses Adaptive Delta Pulse
Code Modulation (ADPCM) with 4-bit precision. It is primarily used for
compressing u-law voice data (achieving a 2:1 compression ratio).
.RE

.sp
.ne 2
.na
\fB\fBg723\fR\fR
.ad
.RS 13n
\fBCCITT G.723\fR compression format. This encoding uses Adaptive Delta Pulse
Code Modulation (ADPCM) with 3-bit precision. It is primarily used for
compressing u-law voice data (achieving an 8:3 compression ratio). The audio
quality is similar to \fBG.721,\fR but may result in lower quality when used
for non-speech data.
.RE

The following encoding values are also accepted as shorthand to set the sample
rate, channels, and encoding:
.sp
.ne 2
.na
\fB\fBvoice\fR\fR
.ad
.RS 9n
Equivalent to \fBencoding=ulaw,rate=8k,channels=mono\fR.
.RE

.sp
.ne 2
.na
\fB\fBcd\fR\fR
.ad
.RS 9n
Equivalent to \fBencoding=linear16,rate=44.1k,channels=stereo\fR.
.RE

.sp
.ne 2
.na
\fB\fBdat\fR\fR
.ad
.RS 9n
Equivalent to \fBencoding=linear16,rate=48k,channels=stereo\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fBformat\fR\fR
.ad
.RS 12n
This option specifies the audio file format. Valid formats are:
.sp
.ne 2
.na
\fB\fBsun\fR\fR
.ad
.RS 7n
Sun compatible file format (the default).
.RE

.sp
.ne 2
.na
\fB\fBraw\fR\fR
.ad
.RS 7n
Use this format when reading or writing raw audio data (with no audio header),
or in conjunction with an  \fBoffset\fR to import a foreign audio file format.
.RE

.RE

.sp
.ne 2
.na
\fB\fBoffset\fR\fR
.ad
.RS 12n
(\fB-i\fR \fIonly\fR) Specifies a byte offset to locate the start of the audio
data. This option may be used to import audio data that contains an
unrecognized file header.
.RE

.SH USAGE
See \fBlargefile\fR(5) for the description of the behavior of
\fBaudioconvert\fR when encountering files greater than or equal to 2 Gbyte
(2^31 bytes).
.SH EXAMPLES
\fBExample 1 \fRRecording and compressing voice data before storing it
.sp
.LP
Record voice data and compress it before storing it to a file:

.sp
.in +2
.nf
example% \fBaudiorecord | audioconvert -f g721 > mydata.au\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRConcatenating two audio files
.sp
.LP
Concatenate two Sun format audio files, regardless of their data format, and
output an 8-bit ulaw, 16 kHz, mono file:

.sp
.in +2
.nf
example% \fBaudioconvert -f ulaw,rate=16k,mono -o outfile.au infile1 infile2\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRConverting a directory to Sun format
.sp
.LP
Convert a directory containing raw voice data files, in place, to Sun format
(adds a file header to each file):

.sp
.in +2
.nf
example% \fBaudioconvert -p -i voice -f sun *.au\fR
.fi
.in -2
.sp

.SH SEE ALSO
\fBaudioplay\fR(1), \fBaudiorecord\fR(1), \fBfile\fR(1),
\fBlargefile\fR(5)
.SH NOTES
The algorithm used for converting multi-channel data to mono is implemented by
simply summing the channels together. If the input data is perfectly in phase
(as would be the case if a mono file is converted to stereo and back to mono),
the resulting data may contain some distortion.