oggenc.1 11.1 KB
Newer Older
Jack Moffitt's avatar
Jack Moffitt committed
1 2
.\" Process this file with
.\" groff -man -Tascii oggenc.1
Manuel Lora's avatar
Manuel Lora committed
3
.\"
4
.TH oggenc 1 "2005 March 3" "Xiph.org Foundation" "Vorbis Tools"
Manuel Lora's avatar
Manuel Lora committed
5 6

.SH NAME
Jack Moffitt's avatar
Jack Moffitt committed
7 8
oggenc \- encode audio into the Ogg Vorbis format

Manuel Lora's avatar
Manuel Lora committed
9
.SH SYNOPSIS
Jack Moffitt's avatar
Jack Moffitt committed
10 11
.B oggenc
[
Manuel Lora's avatar
Manuel Lora committed
12
.B -hrQ
Jack Moffitt's avatar
Jack Moffitt committed
13 14
]
[
Manuel Lora's avatar
Manuel Lora committed
15
.B -B
16 17 18
.I raw input sample size
]
[
Manuel Lora's avatar
Manuel Lora committed
19
.B -C
20 21 22
.I raw input number of channels
]
[
Manuel Lora's avatar
Manuel Lora committed
23
.B -R
24 25 26
.I raw input samplerate
]
[
Manuel Lora's avatar
Manuel Lora committed
27
.B -b
28 29
.I nominal bitrate
]
30
[
Manuel Lora's avatar
Manuel Lora committed
31
.B -m
32 33 34
.I minimum bitrate
]
[
Manuel Lora's avatar
Manuel Lora committed
35
.B -M
36 37 38
.I maximum bitrate
]
[
Manuel Lora's avatar
Manuel Lora committed
39
.B -q
40 41
.I quality
]
Jack Moffitt's avatar
Jack Moffitt committed
42
[
Manuel Lora's avatar
Manuel Lora committed
43
.B --resample 
Michael Smith's avatar
Michael Smith committed
44 45 46
.I frequency
]
[
Manuel Lora's avatar
Manuel Lora committed
47
.B --downmix 
Michael Smith's avatar
Michael Smith committed
48 49
]
[
Manuel Lora's avatar
Manuel Lora committed
50
.B -s
51 52 53
.I serial
]
[
Manuel Lora's avatar
Manuel Lora committed
54
.B -o
Jack Moffitt's avatar
Jack Moffitt committed
55 56 57
.I output_file
]
[
Manuel Lora's avatar
Manuel Lora committed
58
.B -n
Jack Moffitt's avatar
Jack Moffitt committed
59 60 61
.I pattern
]
[
Manuel Lora's avatar
Manuel Lora committed
62
.B -c
Jack Moffitt's avatar
Jack Moffitt committed
63 64 65
.I extra_comment
]
[
Manuel Lora's avatar
Manuel Lora committed
66
.B -a
Jack Moffitt's avatar
Jack Moffitt committed
67 68 69
.I artist
]
[
Manuel Lora's avatar
Manuel Lora committed
70
.B -t
Jack Moffitt's avatar
Jack Moffitt committed
71 72 73
.I title
]
[
Manuel Lora's avatar
Manuel Lora committed
74
.B -l
Jack Moffitt's avatar
Jack Moffitt committed
75 76
.I album
]
77
[
Manuel Lora's avatar
Manuel Lora committed
78
.B -G
79 80
.I genre
]
Jack Moffitt's avatar
Jack Moffitt committed
81 82
.I input_files \fR...

Manuel Lora's avatar
Manuel Lora committed
83
.SH DESCRIPTION
Jack Moffitt's avatar
Jack Moffitt committed
84
.B oggenc
85
reads audio data in either raw, WAV, or AIFF format and encodes it into an
Stan Seibert's avatar
Stan Seibert committed
86 87
Ogg Vorbis stream.
.B oggenc
Manuel Lora's avatar
Manuel Lora committed
88
may also read audio data from FLAC and Ogg FLAC files depending upon compile-time options.  If the input file "-" is specified, audio data is
Jack Moffitt's avatar
Jack Moffitt committed
89 90 91 92
read from
.I stdin
and the Vorbis stream is written to
.I stdout
93
unless the
Manuel Lora's avatar
Manuel Lora committed
94
.B -o
Jack Moffitt's avatar
Jack Moffitt committed
95 96 97
option is used to redirect the output.  By default, disk files are
output to Ogg Vorbis files of the same name, with the extension
changed to ".ogg".  This naming convention can be overridden by the
Manuel Lora's avatar
Manuel Lora committed
98
.B -o
Jack Moffitt's avatar
Jack Moffitt committed
99
option (in the case of one file) or the
Manuel Lora's avatar
Manuel Lora committed
100
.B -n
101
option (in the case of several files). Finally, if none of these
102 103 104
are available, the output filename will be the input filename with the
extension (that part after the final dot) replaced with ogg, so file.wav
will become file.ogg
Jack Moffitt's avatar
Jack Moffitt committed
105

Manuel Lora's avatar
Manuel Lora committed
106 107
.SH OPTIONS
.IP "-h, --help"
Jack Moffitt's avatar
Jack Moffitt committed
108
Show command help.
109 110
.IP "-v, --version"
Show the version number.
Manuel Lora's avatar
Manuel Lora committed
111 112
.IP "-r, --raw"
Assume input data is raw little-endian audio data with no
113 114
header information. If other options are not specified, defaults to 44.1kHz
stereo 16 bit. See next three options for how to change this.
Manuel Lora's avatar
Manuel Lora committed
115
.IP "-B n, --raw-bits=n"
Michael Smith's avatar
Michael Smith committed
116
Sets raw mode input sample size in bits. Default is 16.
Manuel Lora's avatar
Manuel Lora committed
117
.IP "-C n, --raw-chan=n"
Michael Smith's avatar
Michael Smith committed
118
Sets raw mode input number of channels. Default is 2.
Manuel Lora's avatar
Manuel Lora committed
119
.IP "-R n, --raw-rate=n"
Michael Smith's avatar
Michael Smith committed
120
Sets raw mode input samplerate. Default is 44100.
Manuel Lora's avatar
Manuel Lora committed
121
.IP "--raw-endianness n
Michael Smith's avatar
Michael Smith committed
122 123
Sets raw mode endianness to big endian (1) or little endian (0). Default is
little endian.
Manuel Lora's avatar
Manuel Lora committed
124
.IP "-Q, --quiet"
Jack Moffitt's avatar
Jack Moffitt committed
125
Quiet mode.  No messages are displayed.
Manuel Lora's avatar
Manuel Lora committed
126
.IP "-b n, --bitrate=n"
127
Sets target bitrate to n (in kb/s). The encoder will attempt to encode at approximately this bitrate. By default, this remains a VBR encoding. See the --managed option to force a managed bitrate encoding at the selected bitrate.
Manuel Lora's avatar
Manuel Lora committed
128
.IP "-m n, --min-bitrate=n"
129
Sets minimum bitrate to n (in kb/s). Enables bitrate management mode (see --managed).
Manuel Lora's avatar
Manuel Lora committed
130
.IP "-M n, --max-bitrate=n"
131
Sets maximum bitrate to n (in kb/s). Enables bitrate management mode (see --managed).
Manuel Lora's avatar
Manuel Lora committed
132
.IP "--managed"
Michael Smith's avatar
Michael Smith committed
133 134 135 136
Set bitrate management mode. This turns off the normal VBR encoding, but allows
hard or soft bitrate constraints to be enforced by the encoder. This mode is
much slower, and may also be lower quality. It is primarily useful for creating
files for streaming.
Manuel Lora's avatar
Manuel Lora committed
137
.IP "-q n, --quality=n"
138
Sets encoding quality to n, between -1 (very low) and 10 (very high). This is the default mode of operation, with a default quality level of 3. Fractional quality levels such as 2.5 are permitted. Using this option allows the encoder to select an appropriate bitrate based on your desired quality level.
Manuel Lora's avatar
Manuel Lora committed
139
.IP "--resample n"
Michael Smith's avatar
Michael Smith committed
140
Resample input to the given sample rate (in Hz) before encoding. Primarily
Manuel Lora's avatar
Manuel Lora committed
141 142 143 144 145
useful for downsampling for lower-bitrate encoding.
.IP "--downmix"
Downmix input from stereo to mono (has no effect on non-stereo streams). Useful
for lower-bitrate encoding.
.IP "--advanced-encode-option optionname=value"
Michael Smith's avatar
Michael Smith committed
146
Sets an advanced option. See the Advanced Options section for details.
Manuel Lora's avatar
Manuel Lora committed
147
.IP "-s, --serial"
148
Forces a specific serial number in the output stream. This is primarily useful for testing.
Manuel Lora's avatar
Manuel Lora committed
149
.IP "--discard-comments"
Stan Seibert's avatar
Stan Seibert committed
150 151
Prevents comments in FLAC and Ogg FLAC files from being copied to the
output Ogg Vorbis file.
Manuel Lora's avatar
Manuel Lora committed
152
.IP "-o output_file, --output=output_file"
Jack Moffitt's avatar
Jack Moffitt committed
153
Write the Ogg Vorbis stream to
154 155
.I output_file
(only valid if a single input file is specified).
Jack Moffitt's avatar
Jack Moffitt committed
156

Manuel Lora's avatar
Manuel Lora committed
157
.IP "-n pattern, --names=pattern"
158 159 160
Produce filenames as this string, with %g, %a, %l, %n, %t, %d replaced by
genre, artist, album, track number, title, and date, respectively (see below
for specifying these). Also, %% gives a literal %.
161 162 163 164
.IP "-X, --name-remove=s"
Remove the specified characters from parameters to the -n format string. This is useful to ensure legal filenames are generated.
.IP "-P, --name-replace=s"
Replace characters removed by --name-remove with the characters specified. If this string is shorter than the --name-remove list, or is not specified, the extra characters are just removed. The default settings for this option, and the -X option above, are platform specific (and chosen to ensure legal filenames are generated for each platform).
Jack Moffitt's avatar
Jack Moffitt committed
165

Manuel Lora's avatar
Manuel Lora committed
166
.IP "-c comment, --comment comment"
167
Add the string
Jack Moffitt's avatar
Jack Moffitt committed
168
.I comment
169
as an extra comment.  This may be used multiple times, and all
170 171
instances will be added to each of the input files specified. The argument
should be in the form "tag=value".
Jack Moffitt's avatar
Jack Moffitt committed
172

Manuel Lora's avatar
Manuel Lora committed
173
.IP "-a artist, --artist artist"
Jack Moffitt's avatar
Jack Moffitt committed
174 175 176
Set the artist comment field in the comments to
.I artist.

Manuel Lora's avatar
Manuel Lora committed
177
.IP "-G genre, --genre genre"
178 179 180
Set the genre comment field in the comments to
.I genre.

Manuel Lora's avatar
Manuel Lora committed
181
.IP "-d date, --date date"
182 183
Sets the date comment field to the given value. This should be the date of recording.

Manuel Lora's avatar
Manuel Lora committed
184
.IP "-N n, --tracknum n"
185 186
Sets the track number comment field to the given value.

Manuel Lora's avatar
Manuel Lora committed
187
.IP "-t title, --title title"
Jack Moffitt's avatar
Jack Moffitt committed
188 189 190
Set the track title comment field to
.I title.

Manuel Lora's avatar
Manuel Lora committed
191
.IP "-l album, --album album"
Jack Moffitt's avatar
Jack Moffitt committed
192 193
Set the album comment field to
.I album.
Manuel Lora's avatar
Manuel Lora committed
194
.PP
Jack Moffitt's avatar
Jack Moffitt committed
195

Manuel Lora's avatar
Manuel Lora committed
196
Note that the \fB-a\fR, \fB-t\fR, and \fB-l\fR options can be given
Jack Moffitt's avatar
Jack Moffitt committed
197 198 199 200 201 202 203
multiple times.  They will be applied, one to each file, in the order
given.  If there are fewer album, title, or artist comments given than
there are input files,
.B oggenc
will reuse the final one for the remaining files, and issue a warning
in the case of repeated titles.

Manuel Lora's avatar
Manuel Lora committed
204 205
.SH ADVANCED ENCODER OPTIONS

Michael Smith's avatar
Michael Smith committed
206
Oggenc allows you to set a number of advanced encoder options using the
Manuel Lora's avatar
Manuel Lora committed
207
.B --advanced-encode-option
Michael Smith's avatar
Michael Smith committed
208 209 210 211
option. These are intended for very advanced users only, and should be
approached with caution. They may significantly degrade audio quality
if misused. Not all these options are currently documented.

Monty's avatar
 
Monty committed
212 213
.IP "lowpass_frequency=N"
Set the lowpass frequency to N kHz. 
Michael Smith's avatar
Michael Smith committed
214

Monty's avatar
 
Monty committed
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255
.IP "impulse_noisetune=N"
Set a noise floor bias N (range from -15. to 0.) for impulse blocks.
A negative bias instructs the encoder to pay special attention to the
crispness of transients in the encoded audio.  The tradeoff for better
transient response is a higher bitrate.

.IP "bitrate_hard_max=N"
Set the allowed bitrate maximum for the encoded file to N bits per 
second.  This bitrate may be exceeded only when there is spare bits
in the bit reservoir; if the bit reservoir is exhausted, frames will
be held under this value.  This setting must be used with --managed 
to have any effect.

.IP "bitrate_hard_min=N"
Set the allowed bitrate minimum for the encoded file to N bits per
second.  This bitrate may be underrun only when the bit reservoir is
not full; if the bit reservoir is full, frames will be held over this
value; if it impossible to add bits constructively, the frame will be
padded with zeroes.  This setting must be used with --managed to have
any effect.

.IP "bit_reservoir_bits=N"
Set the total size of the bit reservoir to N bits; the default size of
the reservoir is equal to the nominal number of bits coded in one
second (eg, a nominal 128kbps file will have a bit reservoir of 128000
bits by default).  This option must be used with --managed to have any
effect and affects only minimum and maximum bitrate management.
Average bitrate encoding with no hard bitrate boundaries does not use
a bit reservoir.

.IP "bit_reservoir_bias=N"
Set the behavior bias of the bit reservoir (range: 0. to 1.).  When
set closer to 0, the bitrate manager attempts to hoard bits for future
use in sudden bitrate increases (biasing toward better transient
reproduction).  When set closer to 1, the bitrate manager neglects
transients in favor using bits for homogenous passages.  In the
middle, the manager uses a balanced approach.  The default setting is \.2, 
thus biasing slightly toward transient reproduction.

.IP "bitrate_average=N"
Set the average bitrate for the file to N bits per second.  When used
carsten's avatar
Typos.  
carsten committed
256 257 258
without hard minimum or maximum limits, this option selects
reservoirless Average Bit Rate encoding, where the encoder attempts to
perfectly track a desired bitrate, but imposes no strict momentary
Monty's avatar
 
Monty committed
259 260 261 262
fluctuation limits.  When used along with a minimum or maximum limit,
the average bitrate still sets the average overall bitrate of the
file, but will work within the bounds set by the bit reservoir.  When
the min, max and average bitrates are identical, oggenc produces
carsten's avatar
Typos.  
carsten committed
263
Constant Bit Rate Vorbis data.
Monty's avatar
 
Monty committed
264 265 266 267 268 269 270 271 272 273 274 275 276 277 278

.IP "bitrate_average_damping=N"
Set the reaction time for the average bitrate tracker to N seconds.
This number represents the fastest reaction the bitrate tracker is
allowed to make to hold the bitrate to the selected average.  The
faster the reaction time, the less momentary fluctuation in the
bitrate but (generally) the lower quality the audio output.  The
slower the reaction time, the larger the ABR fluctuations, but
(generally) the better the audio.  When used along with min or max
bitrate limits, this option directly affects how deep and how quickly
the encoder will dip into its bit reservoir; the higher the number,
the more demand on the bit reservoir.

The setting must be greater than zero and the useful range is
approximately \.05 to 10.  The default is \.75 seconds.
Michael Smith's avatar
Michael Smith committed
279

Manuel Lora's avatar
Manuel Lora committed
280 281
.SH EXAMPLES

Jack Moffitt's avatar
Jack Moffitt committed
282 283 284 285
Simplest version. Produces output as somefile.ogg:
.RS
oggenc somefile.wav
.RE
Manuel Lora's avatar
Manuel Lora committed
286
.PP
Jack Moffitt's avatar
Jack Moffitt committed
287 288 289

Specifying an output filename:
.RS
Manuel Lora's avatar
Manuel Lora committed
290
oggenc somefile.wav -o out.ogg
Jack Moffitt's avatar
Jack Moffitt committed
291
.RE
Manuel Lora's avatar
Manuel Lora committed
292
.PP
Jack Moffitt's avatar
Jack Moffitt committed
293

Manuel Lora's avatar
Manuel Lora committed
294
Specifying a high-quality encoding averaging 256 kbps (but still VBR).
Jack Moffitt's avatar
Jack Moffitt committed
295
.RS
Manuel Lora's avatar
Manuel Lora committed
296
oggenc infile.wav -b 256 out.ogg
Jack Moffitt's avatar
Jack Moffitt committed
297
.RE
Manuel Lora's avatar
Manuel Lora committed
298
.PP
Jack Moffitt's avatar
Jack Moffitt committed
299

Michael Smith's avatar
Michael Smith committed
300
Specifying a maximum and average bitrate, and enforcing these.
301
.RS
Manuel Lora's avatar
Manuel Lora committed
302
oggenc infile.wav --managed -b 128 -M 160 out.ogg
303
.RE
Manuel Lora's avatar
Manuel Lora committed
304
.PP
305

306 307
Specifying quality rather than bitrate (to a very high quality mode)
.RS
Manuel Lora's avatar
Manuel Lora committed
308
oggenc infile.wav -q 6 out.ogg
Michael Smith's avatar
Michael Smith committed
309
.RE
Manuel Lora's avatar
Manuel Lora committed
310
.PP
Michael Smith's avatar
Michael Smith committed
311 312 313

Downsampling and downmixing to 11 kHz mono before encoding.
.RS
Manuel Lora's avatar
Manuel Lora committed
314
oggenc --resample 11025 --downmix infile.wav -q 1 out.ogg
315
.RE
Manuel Lora's avatar
Manuel Lora committed
316
.PP
317

Jack Moffitt's avatar
Jack Moffitt committed
318 319
Adding some info about the track:
.RS
Manuel Lora's avatar
Manuel Lora committed
320 321
oggenc somefile.wav -t "The track title" -a "artist who performed this" -l
"name of album" -c
Conrad Parker's avatar
Conrad Parker committed
322
"OTHERFIELD=contents of some other field not explicitly supported"
Jack Moffitt's avatar
Jack Moffitt committed
323
.RE
Manuel Lora's avatar
Manuel Lora committed
324
.PP
Jack Moffitt's avatar
Jack Moffitt committed
325 326 327

This encodes the three files, each with the
same artist/album tag, but with different title tags on each one. The
Manuel Lora's avatar
Manuel Lora committed
328
string given as an argument to -n is used to generate filenames, as shown
329
in the section above. This example gives filenames
Manuel Lora's avatar
Manuel Lora committed
330
like "The Tea Party - Touch.ogg":
Jack Moffitt's avatar
Jack Moffitt committed
331
.RS
Manuel Lora's avatar
Manuel Lora committed
332 333
oggenc -b 192 -a "The Tea Party" -l "Triptych" -t "Touch" track01.wav -t
"Underground" track02.wav -t "Great Big Lie" track03.wav -n "%a - %t.ogg"
Jack Moffitt's avatar
Jack Moffitt committed
334
.RE
Manuel Lora's avatar
Manuel Lora committed
335
.PP
Jack Moffitt's avatar
Jack Moffitt committed
336 337

Encoding from stdin, to stdout (you can also use the various tagging
Manuel Lora's avatar
Manuel Lora committed
338
options, like -t, -a, -l, etc.):
Jack Moffitt's avatar
Jack Moffitt committed
339
.RS
Manuel Lora's avatar
Manuel Lora committed
340
oggenc -
Jack Moffitt's avatar
Jack Moffitt committed
341
.RE
Manuel Lora's avatar
Manuel Lora committed
342
.PP
Jack Moffitt's avatar
Jack Moffitt committed
343

Manuel Lora's avatar
Manuel Lora committed
344 345 346
.SH AUTHORS

.TP
Jack Moffitt's avatar
Jack Moffitt committed
347
Program Author:
Manuel Lora's avatar
Manuel Lora committed
348
.br
349
Michael Smith <msmith@xiph.org>
Jack Moffitt's avatar
Jack Moffitt committed
350

Manuel Lora's avatar
Manuel Lora committed
351
.TP
Jack Moffitt's avatar
Jack Moffitt committed
352
Manpage Author:
Manuel Lora's avatar
Manuel Lora committed
353
.br
Jack Moffitt's avatar
Jack Moffitt committed
354 355
Stan Seibert <indigo@aztec.asu.edu>

Manuel Lora's avatar
Manuel Lora committed
356
.SH BUGS
357
Reading type 3 wav files (floating point samples) probably doesn't work other than on intel (or other 32 bit, little endian machines). 
358

Manuel Lora's avatar
Manuel Lora committed
359 360
.SH SEE ALSO

Jack Moffitt's avatar
Jack Moffitt committed
361
.BR ogg123 (1)