1 '\" te 2 .\" Copyright (c) 2001, 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. 4 .\" 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. 5 .\" 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] 6 .TH AUDIOCONVERT 1 "Feb 16, 2001" 7 .SH NAME 8 audioconvert \- convert audio file formats 9 .SH SYNOPSIS 10 .LP 11 .nf 12 \fBaudioconvert\fR [\fB-pF\fR] [\fB-f\fR \fIoutfmt\fR] [\fB-o\fR \fIoutfile\fR] 13 [ [\fB-i\fR \fIinfmt\fR] [\fIfile\fR]...] ... 14 .fi 15 16 .SH DESCRIPTION 17 .sp 18 .LP 19 \fBaudioconvert\fR converts audio data between a set of supported audio 20 encodings and file formats. It can be used to compress and decompress audio 21 data, to add audio file headers to raw audio data files, and to convert between 22 standard data encodings, such as -law and linear PCM. 23 .sp 24 .LP 25 If no filenames are present, \fBaudioconvert\fR reads the data from the 26 standard input stream and writes an audio file to the standard output. 27 Otherwise, input files are processed in order, concatenated, and written to the 28 output file. 29 .sp 30 .LP 31 Input files are expected to contain audio file headers that identify the audio 32 data format. If the audio data does not contain a recognizable header, the 33 format must be specified with the \fB-i\fR option, using the \fBrate\fR, 34 \fBencoding\fR, and \fBchannels\fR keywords to identify the input data format. 35 .sp 36 .LP 37 The output file format is derived by updating the format of the first input 38 file with the format options in the \fB-f\fR specification. If \fB-p\fR is not 39 specified, all subsequent input files are converted to this resulting format 40 and concatenated together. The output file will contain an audio file header, 41 unless \fBformat\fR=\fIraw\fR is specified in the output format options. 42 .sp 43 .LP 44 Input files may be converted in place by using the \fB-p\fR option. When 45 \fB-p\fR is in effect, the format of each input file is modified according to 46 the \fB-f\fR option to determine the output format. The existing files are then 47 overwritten with the converted data. 48 .sp 49 .LP 50 The \fBfile\fR(1) command decodes and prints the audio data format of Sun audio 51 files. 52 .SH OPTIONS 53 .sp 54 .LP 55 The following options are supported: 56 .sp 57 .ne 2 58 .na 59 \fB\fB-p\fR\fR 60 .ad 61 .RS 14n 62 \fIIn Place\fR: The input files are individually converted to the format 63 specified by the \fB-f\fR option and rewritten. If a target file is a symbolic 64 link, the underlying file will be rewritten. The \fB-o\fR option may not be 65 specified with \fB-p\fR. 66 .RE 67 68 .sp 69 .ne 2 70 .na 71 \fB\fB-F\fR\fR 72 .ad 73 .RS 14n 74 \fIForce\fR: This option forces \fBaudioconvert\fR to ignore any file header 75 for input files whose format is specified by the \fB-i\fR option. If \fB-F\fR 76 is not specified, \fBaudioconvert\fR ignores the \fB-i\fR option for input 77 files that contain valid audio file headers. 78 .RE 79 80 .sp 81 .ne 2 82 .na 83 \fB\fB-f\fR \fIoutfmt\fR\fR 84 .ad 85 .RS 14n 86 \fIOutput Format\fR: This option is used to specify the file format and data 87 encoding of the output file. Defaults for unspecified fields are derived from 88 the input file format. Valid keywords and values are listed in the next 89 section. 90 .RE 91 92 .sp 93 .ne 2 94 .na 95 \fB\fB-o\fR \fIoutfile\fR\fR 96 .ad 97 .RS 14n 98 \fIOutput File\fR: All input files are concatenated, converted to the output 99 format, and written to the named output file. If \fB-o\fR and \fB-p\fR are not 100 specified, the concatenated output is written to the standard output. The 101 \fB-p\fR option may not be specified with \fB-o\fR. 102 .RE 103 104 .sp 105 .ne 2 106 .na 107 \fB\fB-i\fR \fIinfmt\fR\fR 108 .ad 109 .RS 14n 110 \fIInput Format\fR: This option is used to specify the data encoding of raw 111 input files. Ordinarily, the input data format is derived from the audio file 112 header. This option is required when converting audio data that is not preceded 113 by a valid audio file header. If \fB-i\fR is specified for an input file that 114 contains an audio file header, the input format string will be ignored, unless 115 \fB-F\fR is present. The format specification syntax is the same as the 116 \fB-f\fR output file format. 117 .sp 118 Multiple input formats may be specified. An input format describes all input 119 files following that specification, until a new input format is specified. 120 .RE 121 122 .sp 123 .ne 2 124 .na 125 \fB\fIfile\fR\fR 126 .ad 127 .RS 14n 128 \fIFile Specification\fR: The named audio files are concatenated, converted to 129 the output format, and written out. If no file name is present, or if the 130 special file name `\(mi' is specified, audio data is read from the standard 131 input. 132 .RE 133 134 .sp 135 .ne 2 136 .na 137 \fB\fB-?\fR\fR 138 .ad 139 .RS 14n 140 \fIHelp\fR: Prints a command line usage message. 141 .RE 142 143 .SS "Format Specification" 144 .sp 145 .LP 146 The syntax for the input and output format specification is: 147 .sp 148 .LP 149 \fIkeyword\fR=\fIvalue\fR[,\fIkeyword\fR=\fIvalue\fR \|.\|.\|.\|] 150 .sp 151 .LP 152 with no intervening whitespace. Unambiguous values may be used without the 153 preceding \fIkeyword\fR=. 154 .sp 155 .ne 2 156 .na 157 \fB\fBrate\fR\fR 158 .ad 159 .RS 12n 160 The audio sampling rate is specified in samples per second. If a number is 161 followed by the letter \fBk\fR, it is multiplied by 1000 (for example, 44.1k = 162 44100). Standard of the commonly used sample rates are: 8k, 16k, 32k, 44.1k, 163 and 48k. 164 .RE 165 166 .sp 167 .ne 2 168 .na 169 \fB\fBchannels\fR\fR 170 .ad 171 .RS 12n 172 The number of interleaved channels is specified as an integer. The words 173 \fBmono\fR and \fBstereo\fR may also be used to specify one and two channel 174 data, respectively. 175 .RE 176 177 .sp 178 .ne 2 179 .na 180 \fB\fBencoding\fR\fR 181 .ad 182 .RS 12n 183 This option specifies the digital audio data representation. Encodings 184 determine precision implicitly (\fBulaw\fR implies 8-bit precision) or 185 explicitly as part of the name (for example, \fBlinear16\fR). Valid encoding 186 values are: 187 .sp 188 .ne 2 189 .na 190 \fB\fBulaw\fR\fR 191 .ad 192 .RS 13n 193 \fBCCITT G.711\fR -law encoding. This is an 8-bit format primarily used for 194 telephone quality speech. 195 .RE 196 197 .sp 198 .ne 2 199 .na 200 \fB\fBalaw\fR\fR 201 .ad 202 .RS 13n 203 \fBCCITT G.711\fR A-law encoding. This is an 8-bit format primarily used for 204 telephone quality speech in Europe. 205 .RE 206 207 .sp 208 .ne 2 209 .na 210 \fB\fBlinear8\fR,\fR 211 .ad 212 .br 213 .na 214 \fB\fBlinear16\fR,\fR 215 .ad 216 .br 217 .na 218 \fB\fBlinear32\fR\fR 219 .ad 220 .RS 13n 221 Linear Pulse Code Modulation (PCM) encoding. The name identifies the number of 222 bits of precision. \fBlinear16\fR is typically used for high quality audio 223 data. 224 .RE 225 226 .sp 227 .ne 2 228 .na 229 \fB\fBpcm\fR\fR 230 .ad 231 .RS 13n 232 Same as \fBlinear16\fR. 233 .RE 234 235 .sp 236 .ne 2 237 .na 238 \fB\fBg721\fR\fR 239 .ad 240 .RS 13n 241 \fBCCITT G.721\fR compression format. This encoding uses Adaptive Delta Pulse 242 Code Modulation (ADPCM) with 4-bit precision. It is primarily used for 243 compressing -law voice data (achieving a 2:1 compression ratio). 244 .RE 245 246 .sp 247 .ne 2 248 .na 249 \fB\fBg723\fR\fR 250 .ad 251 .RS 13n 252 \fBCCITT G.723\fR compression format. This encoding uses Adaptive Delta Pulse 253 Code Modulation (ADPCM) with 3-bit precision. It is primarily used for 254 compressing -law voice data (achieving an 8:3 compression ratio). The audio 255 quality is similar to \fBG.721,\fR but may result in lower quality when used 256 for non-speech data. 257 .RE 258 259 The following encoding values are also accepted as shorthand to set the sample 260 rate, channels, and encoding: 261 .sp 262 .ne 2 263 .na 264 \fB\fBvoice\fR\fR 265 .ad 266 .RS 9n 267 Equivalent to \fBencoding=ulaw,rate=8k,channels=mono\fR. 268 .RE 269 270 .sp 271 .ne 2 272 .na 273 \fB\fBcd\fR\fR 274 .ad 275 .RS 9n 276 Equivalent to \fBencoding=linear16,rate=44.1k,channels=stereo\fR. 277 .RE 278 279 .sp 280 .ne 2 281 .na 282 \fB\fBdat\fR\fR 283 .ad 284 .RS 9n 285 Equivalent to \fBencoding=linear16,rate=48k,channels=stereo\fR. 286 .RE 287 288 .RE 289 290 .sp 291 .ne 2 292 .na 293 \fB\fBformat\fR\fR 294 .ad 295 .RS 12n 296 This option specifies the audio file format. Valid formats are: 297 .sp 298 .ne 2 299 .na 300 \fB\fBsun\fR\fR 301 .ad 302 .RS 7n 303 Sun compatible file format (the default). 304 .RE 305 306 .sp 307 .ne 2 308 .na 309 \fB\fBraw\fR\fR 310 .ad 311 .RS 7n 312 Use this format when reading or writing raw audio data (with no audio header), 313 or in conjunction with an \fBoffset\fR to import a foreign audio file format. 314 .RE 315 316 .RE 317 318 .sp 319 .ne 2 320 .na 321 \fB\fBoffset\fR\fR 322 .ad 323 .RS 12n 324 (\fB-i\fR \fIonly\fR) Specifies a byte offset to locate the start of the audio 325 data. This option may be used to import audio data that contains an 326 unrecognized file header. 327 .RE 328 329 .SH USAGE 330 .sp 331 .LP 332 See \fBlargefile\fR(5) for the description of the behavior of 333 \fBaudioconvert\fR when encountering files greater than or equal to 2 Gbyte ( 334 2^31 bytes). 335 .SH EXAMPLES 336 .LP 337 \fBExample 1 \fRRecording and compressing voice data before storing it 338 .sp 339 .LP 340 Record voice data and compress it before storing it to a file: 341 342 .sp 343 .in +2 344 .nf 345 example% \fBaudiorecord | audioconvert -f g721 > mydata.au\fR 346 .fi 347 .in -2 348 .sp 349 350 .LP 351 \fBExample 2 \fRConcatenating two audio files 352 .sp 353 .LP 354 Concatenate two Sun format audio files, regardless of their data format, and 355 output an 8-bit ulaw, 16 kHz, mono file: 356 357 .sp 358 .in +2 359 .nf 360 example% \fBaudioconvert -f ulaw,rate=16k,mono -o outfile.au infile1 infile2\fR 361 .fi 362 .in -2 363 .sp 364 365 .LP 366 \fBExample 3 \fRConverting a directory to Sun format 367 .sp 368 .LP 369 Convert a directory containing raw voice data files, in place, to Sun format 370 (adds a file header to each file): 371 372 .sp 373 .in +2 374 .nf 375 example% \fBaudioconvert -p -i voice -f sun *.au\fR 376 .fi 377 .in -2 378 .sp 379 380 .SH ATTRIBUTES 381 .sp 382 .LP 383 See \fBattributes\fR(5) for descriptions of the following attributes: 384 .sp 385 386 .sp 387 .TS 388 box; 389 c | c 390 l | l . 391 ATTRIBUTE TYPE ATTRIBUTE VALUE 392 _ 393 Architecture SPARC, x86 394 _ 395 Interface Stability Evolving 396 .TE 397 398 .SH SEE ALSO 399 .sp 400 .LP 401 \fBaudioplay\fR(1), \fBaudiorecord\fR(1), \fBfile\fR(1), \fBattributes\fR(5), 402 \fBlargefile\fR(5) 403 .SH NOTES 404 .sp 405 .LP 406 The algorithm used for converting multi-channel data to mono is implemented by 407 simply summing the channels together. If the input data is perfectly in phase 408 (as would be the case if a mono file is converted to stereo and back to mono), 409 the resulting data may contain some distortion.