| 1 |
.\" Process this file with |
| 2 |
.\" groff -man -Tascii oggenc.1 |
| 3 |
.\" |
| 4 |
.TH oggenc 1 "2008 October 05" "Xiph.Org Foundation" "Vorbis Tools" |
| 5 |
|
| 6 |
.SH NAME |
| 7 |
oggenc \- encode audio into the Ogg Vorbis format |
| 8 |
|
| 9 |
.SH SYNOPSIS |
| 10 |
.B oggenc |
| 11 |
[ |
| 12 |
.B -hrQ |
| 13 |
] |
| 14 |
[ |
| 15 |
.B -B |
| 16 |
.I raw input sample size |
| 17 |
] |
| 18 |
[ |
| 19 |
.B -C |
| 20 |
.I raw input number of channels |
| 21 |
] |
| 22 |
[ |
| 23 |
.B -R |
| 24 |
.I raw input samplerate |
| 25 |
] |
| 26 |
[ |
| 27 |
.B -b |
| 28 |
.I nominal bitrate |
| 29 |
] |
| 30 |
[ |
| 31 |
.B -m |
| 32 |
.I minimum bitrate |
| 33 |
] |
| 34 |
[ |
| 35 |
.B -M |
| 36 |
.I maximum bitrate |
| 37 |
] |
| 38 |
[ |
| 39 |
.B -q |
| 40 |
.I quality |
| 41 |
] |
| 42 |
[ |
| 43 |
.B --resample |
| 44 |
.I frequency |
| 45 |
] |
| 46 |
[ |
| 47 |
.B --downmix |
| 48 |
] |
| 49 |
[ |
| 50 |
.B -s |
| 51 |
.I serial |
| 52 |
] |
| 53 |
[ |
| 54 |
.B -o |
| 55 |
.I output_file |
| 56 |
] |
| 57 |
[ |
| 58 |
.B -n |
| 59 |
.I pattern |
| 60 |
] |
| 61 |
[ |
| 62 |
.B -c |
| 63 |
.I extra_comment |
| 64 |
] |
| 65 |
[ |
| 66 |
.B -a |
| 67 |
.I artist |
| 68 |
] |
| 69 |
[ |
| 70 |
.B -t |
| 71 |
.I title |
| 72 |
] |
| 73 |
[ |
| 74 |
.B -l |
| 75 |
.I album |
| 76 |
] |
| 77 |
[ |
| 78 |
.B -G |
| 79 |
.I genre |
| 80 |
] |
| 81 |
[ |
| 82 |
.B -L |
| 83 |
.I lyrics file |
| 84 |
] |
| 85 |
[ |
| 86 |
.B -Y |
| 87 |
.I language-string |
| 88 |
] |
| 89 |
.I input_files \fR... |
| 90 |
|
| 91 |
.SH DESCRIPTION |
| 92 |
.B oggenc |
| 93 |
reads audio data in either raw, Wave, or AIFF format and encodes it into an |
| 94 |
Ogg Vorbis stream. |
| 95 |
.B oggenc |
| 96 |
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 |
| 97 |
read from |
| 98 |
.I stdin |
| 99 |
and the Vorbis stream is written to |
| 100 |
.I stdout |
| 101 |
unless the |
| 102 |
.B -o |
| 103 |
option is used to redirect the output. By default, disk files are |
| 104 |
output to Ogg Vorbis files of the same name, with the extension |
| 105 |
changed to ".ogg" or ".oga". This naming convention can be overridden |
| 106 |
by the |
| 107 |
.B -o |
| 108 |
option (in the case of one file) or the |
| 109 |
.B -n |
| 110 |
option (in the case of several files). Finally, if none of these |
| 111 |
are available, the output filename will be the input filename with the |
| 112 |
extension (that part after the final dot) replaced with ogg, so file.wav |
| 113 |
will become file.ogg. |
| 114 |
.br |
| 115 |
Optionally, lyrics may be embedded in the Ogg file, if Kate support was compiled in. |
| 116 |
.br |
| 117 |
Note that some old players mail fail to play streams with more than a single Vorbis stream |
| 118 |
(the so called "Vorbis I" simple profile). |
| 119 |
|
| 120 |
.SH OPTIONS |
| 121 |
.IP "-h, --help" |
| 122 |
Show command help. |
| 123 |
.IP "-V, --version" |
| 124 |
Show the version number. |
| 125 |
.IP "-r, --raw" |
| 126 |
Assume input data is raw little-endian audio data with no |
| 127 |
header information. If other options are not specified, defaults to 44.1kHz |
| 128 |
stereo 16 bit. See next three options for how to change this. |
| 129 |
.IP "-B n, --raw-bits=n" |
| 130 |
Sets raw mode input sample size in bits. Default is 16. |
| 131 |
.IP "-C n, --raw-chan=n" |
| 132 |
Sets raw mode input number of channels. Default is 2. |
| 133 |
.IP "-R n, --raw-rate=n" |
| 134 |
Sets raw mode input samplerate. Default is 44100. |
| 135 |
.IP "--raw-endianness n |
| 136 |
Sets raw mode endianness to big endian (1) or little endian (0). Default is |
| 137 |
little endian. |
| 138 |
.IP "--utf8 \ \ \ \ \ \ \ " |
| 139 |
Informs oggenc that the Vorbis Comments are already encoded as UTF-8. |
| 140 |
Useful in situations where the shell is using some other encoding. |
| 141 |
.IP "-k, --skeleton" |
| 142 |
Add a Skeleton bitstream. Important if the output Ogg is intended to carry |
| 143 |
multiplexed or chained streams. Output file uses .oga as file extension. |
| 144 |
.IP "--ignorelength" |
| 145 |
Support for Wave files over 4 GB and stdin data streams. |
| 146 |
.IP "-Q, --quiet" |
| 147 |
Quiet mode. No messages are displayed. |
| 148 |
.IP "-b n, --bitrate=n" |
| 149 |
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. |
| 150 |
.IP "-m n, --min-bitrate=n" |
| 151 |
Sets minimum bitrate to n (in kb/s). Enables bitrate management mode (see --managed). |
| 152 |
.IP "-M n, --max-bitrate=n" |
| 153 |
Sets maximum bitrate to n (in kb/s). Enables bitrate management mode (see --managed). |
| 154 |
.IP "--managed" |
| 155 |
Set bitrate management mode. This turns off the normal VBR encoding, but allows |
| 156 |
hard or soft bitrate constraints to be enforced by the encoder. This mode is |
| 157 |
much slower, and may also be lower quality. It is primarily useful for creating |
| 158 |
files for streaming. |
| 159 |
.IP "-q n, --quality=n" |
| 160 |
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. |
| 161 |
.IP "--resample n" |
| 162 |
Resample input to the given sample rate (in Hz) before encoding. Primarily |
| 163 |
useful for downsampling for lower-bitrate encoding. |
| 164 |
.IP "--downmix" |
| 165 |
Downmix input from stereo to mono (has no effect on non-stereo streams). Useful |
| 166 |
for lower-bitrate encoding. |
| 167 |
.IP "--advanced-encode-option optionname=value" |
| 168 |
Sets an advanced option. See the Advanced Options section for details. |
| 169 |
.IP "-s, --serial" |
| 170 |
Forces a specific serial number in the output stream. This is primarily useful for testing. |
| 171 |
.IP "--discard-comments" |
| 172 |
Prevents comments in FLAC and Ogg FLAC files from being copied to the |
| 173 |
output Ogg Vorbis file. |
| 174 |
.IP "-o output_file, --output=output_file" |
| 175 |
Write the Ogg Vorbis stream to |
| 176 |
.I output_file |
| 177 |
(only valid if a single input file is specified). |
| 178 |
|
| 179 |
.IP "-n pattern, --names=pattern" |
| 180 |
Produce filenames as this string, with %g, %a, %l, %n, %t, %d replaced by |
| 181 |
genre, artist, album, track number, title, and date, respectively (see below |
| 182 |
for specifying these). Also, %% gives a literal %. |
| 183 |
.IP "-X, --name-remove=s" |
| 184 |
Remove the specified characters from parameters to the -n format string. This is useful to ensure legal filenames are generated. |
| 185 |
.IP "-P, --name-replace=s" |
| 186 |
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). |
| 187 |
|
| 188 |
.IP "-c comment, --comment comment" |
| 189 |
Add the string |
| 190 |
.I comment |
| 191 |
as an extra comment. This may be used multiple times, and all |
| 192 |
instances will be added to each of the input files specified. The argument |
| 193 |
should be in the form "tag=value". |
| 194 |
|
| 195 |
.IP "-a artist, --artist artist" |
| 196 |
Set the artist comment field in the comments to |
| 197 |
.I artist. |
| 198 |
|
| 199 |
.IP "-G genre, --genre genre" |
| 200 |
Set the genre comment field in the comments to |
| 201 |
.I genre. |
| 202 |
|
| 203 |
.IP "-d date, --date date" |
| 204 |
Sets the date comment field to the given value. This should be the date of recording. |
| 205 |
|
| 206 |
.IP "-N n, --tracknum n" |
| 207 |
Sets the track number comment field to the given value. |
| 208 |
|
| 209 |
.IP "-t title, --title title" |
| 210 |
Set the track title comment field to |
| 211 |
.I title. |
| 212 |
|
| 213 |
.IP "-l album, --album album" |
| 214 |
Set the album comment field to |
| 215 |
.I album. |
| 216 |
|
| 217 |
.IP "-L filename, --lyrics filename" |
| 218 |
Loads lyrics from |
| 219 |
.I filename |
| 220 |
and encodes them into a Kate stream multiplexed with the Vorbis stream. |
| 221 |
Lyrics may be in LRC or SRT format, and should be encoded in UTF-8 or |
| 222 |
plain ASCII. Other encodings may be converted using tools such as iconv |
| 223 |
or recode. Alternatively, the same system as for comments will be used |
| 224 |
for conversion between encodings. |
| 225 |
So called "enhanced LRC" files are supported, and a simple karaoke style |
| 226 |
change will be saved with the lyrics. For more complex karaoke setups, |
| 227 |
.B kateenc(1) |
| 228 |
should be used instead. |
| 229 |
When embedding lyrics, the default output file extension is ".oga". |
| 230 |
Note that adding lyrics to a stream will automatically enable Skeleton |
| 231 |
(see the \fB-k\fR option for more information about Skeleton). |
| 232 |
|
| 233 |
.IP "-Y language-string, --lyrics-language language-string" |
| 234 |
Sets the language for the corresponding lyrics file to |
| 235 |
.I language-string. |
| 236 |
This should be an ISO 639-1 language code (eg, "en"), or a RFC 3066 language tag |
| 237 |
(eg, "en_US"), |
| 238 |
.B not |
| 239 |
a free form language name. Players will typically recognize this standard tag |
| 240 |
and display the language name in your own language. |
| 241 |
Note that the maximum length of this tag is 15 characters. |
| 242 |
.PP |
| 243 |
|
| 244 |
Note that the \fB-a\fR, \fB-t\fR, \fB-l\fR, \fB-L\fR, and \fB-Y\fR options |
| 245 |
can be given multiple times. They will be applied, one to each file, in the |
| 246 |
order given. If there are fewer album, title, or artist comments given than |
| 247 |
there are input files, |
| 248 |
.B oggenc |
| 249 |
will reuse the final one for the remaining files, and issue a warning |
| 250 |
in the case of repeated titles. |
| 251 |
|
| 252 |
.SH "ADVANCED ENCODER OPTIONS" |
| 253 |
|
| 254 |
Oggenc allows you to set a number of advanced encoder options using the |
| 255 |
.B --advanced-encode-option |
| 256 |
option. These are intended for very advanced users only, and should be |
| 257 |
approached with caution. They may significantly degrade audio quality |
| 258 |
if misused. Not all these options are currently documented. |
| 259 |
|
| 260 |
.IP "lowpass_frequency=N" |
| 261 |
Set the lowpass frequency to N kHz. |
| 262 |
|
| 263 |
.IP "impulse_noisetune=N" |
| 264 |
Set a noise floor bias N (range from -15. to 0.) for impulse blocks. |
| 265 |
A negative bias instructs the encoder to pay special attention to the |
| 266 |
crispness of transients in the encoded audio. The tradeoff for better |
| 267 |
transient response is a higher bitrate. |
| 268 |
|
| 269 |
.IP "bitrate_hard_max=N" |
| 270 |
Set the allowed bitrate maximum for the encoded file to N kilobits per |
| 271 |
second. This bitrate may be exceeded only when there is spare bits |
| 272 |
in the bit reservoir; if the bit reservoir is exhausted, frames will |
| 273 |
be held under this value. This setting must be used with --managed |
| 274 |
to have any effect. |
| 275 |
|
| 276 |
.IP "bitrate_hard_min=N" |
| 277 |
Set the allowed bitrate minimum for the encoded file to N kilobits per |
| 278 |
second. This bitrate may be underrun only when the bit reservoir is |
| 279 |
not full; if the bit reservoir is full, frames will be held over this |
| 280 |
value; if it impossible to add bits constructively, the frame will be |
| 281 |
padded with zeroes. This setting must be used with --managed to have |
| 282 |
any effect. |
| 283 |
|
| 284 |
.IP "bit_reservoir_bits=N" |
| 285 |
Set the total size of the bit reservoir to N bits; the default size of |
| 286 |
the reservoir is equal to the nominal number of bits coded in one |
| 287 |
second (eg, a nominal 128kbps file will have a bit reservoir of 128000 |
| 288 |
bits by default). This option must be used with --managed to have any |
| 289 |
effect and affects only minimum and maximum bitrate management. |
| 290 |
Average bitrate encoding with no hard bitrate boundaries does not use |
| 291 |
a bit reservoir. |
| 292 |
|
| 293 |
.IP "bit_reservoir_bias=N" |
| 294 |
Set the behavior bias of the bit reservoir (range: 0. to 1.). When |
| 295 |
set closer to 0, the bitrate manager attempts to hoard bits for future |
| 296 |
use in sudden bitrate increases (biasing toward better transient |
| 297 |
reproduction). When set closer to 1, the bitrate manager neglects |
| 298 |
transients in favor using bits for homogenous passages. In the |
| 299 |
middle, the manager uses a balanced approach. The default setting is \.2, |
| 300 |
thus biasing slightly toward transient reproduction. |
| 301 |
|
| 302 |
.IP "bitrate_average=N" |
| 303 |
Set the average bitrate for the file to N kilobits per second. When used |
| 304 |
without hard minimum or maximum limits, this option selects |
| 305 |
reservoirless Average Bit Rate encoding, where the encoder attempts to |
| 306 |
perfectly track a desired bitrate, but imposes no strict momentary |
| 307 |
fluctuation limits. When used along with a minimum or maximum limit, |
| 308 |
the average bitrate still sets the average overall bitrate of the |
| 309 |
file, but will work within the bounds set by the bit reservoir. When |
| 310 |
the min, max and average bitrates are identical, oggenc produces |
| 311 |
Constant Bit Rate Vorbis data. |
| 312 |
|
| 313 |
.IP "bitrate_average_damping=N" |
| 314 |
Set the reaction time for the average bitrate tracker to N seconds. |
| 315 |
This number represents the fastest reaction the bitrate tracker is |
| 316 |
allowed to make to hold the bitrate to the selected average. The |
| 317 |
faster the reaction time, the less momentary fluctuation in the |
| 318 |
bitrate but (generally) the lower quality the audio output. The |
| 319 |
slower the reaction time, the larger the ABR fluctuations, but |
| 320 |
(generally) the better the audio. When used along with min or max |
| 321 |
bitrate limits, this option directly affects how deep and how quickly |
| 322 |
the encoder will dip into its bit reservoir; the higher the number, |
| 323 |
the more demand on the bit reservoir. |
| 324 |
|
| 325 |
The setting must be greater than zero and the useful range is |
| 326 |
approximately \.05 to 10. The default is \.75 seconds. |
| 327 |
|
| 328 |
.IP "disable_coupling" |
| 329 |
Disable use of channel coupling for multichannel encoding. At present, |
| 330 |
the encoder will normally use channel coupling to further increase |
| 331 |
compression with stereo and 5.1 inputs. This option forces the encoder |
| 332 |
to encode each channel fully independently using neither lossy nor |
| 333 |
lossless coupling. |
| 334 |
|
| 335 |
.SH EXAMPLES |
| 336 |
|
| 337 |
Simplest version. Produces output as somefile.ogg: |
| 338 |
.RS |
| 339 |
oggenc somefile.wav |
| 340 |
.RE |
| 341 |
.PP |
| 342 |
|
| 343 |
Specifying an output filename: |
| 344 |
.RS |
| 345 |
oggenc somefile.wav -o out.ogg |
| 346 |
.RE |
| 347 |
.PP |
| 348 |
|
| 349 |
Specifying a high-quality encoding averaging 256 kbps (but still VBR): |
| 350 |
.RS |
| 351 |
oggenc infile.wav -b 256 -o out.ogg |
| 352 |
.RE |
| 353 |
.PP |
| 354 |
|
| 355 |
Specifying a maximum and average bitrate, and enforcing these: |
| 356 |
.RS |
| 357 |
oggenc infile.wav --managed -b 128 -M 160 -o out.ogg |
| 358 |
.RE |
| 359 |
.PP |
| 360 |
|
| 361 |
Specifying quality rather than bitrate (to a very high quality mode): |
| 362 |
.RS |
| 363 |
oggenc infile.wav -q 6 -o out.ogg |
| 364 |
.RE |
| 365 |
.PP |
| 366 |
|
| 367 |
Downsampling and downmixing to 11 kHz mono before encoding: |
| 368 |
.RS |
| 369 |
oggenc --resample 11025 --downmix infile.wav -q 1 -o out.ogg |
| 370 |
.RE |
| 371 |
.PP |
| 372 |
|
| 373 |
Adding some info about the track: |
| 374 |
.RS |
| 375 |
oggenc somefile.wav -t "The track title" -a "artist who performed this" -l |
| 376 |
"name of album" -c |
| 377 |
"OTHERFIELD=contents of some other field not explicitly supported" |
| 378 |
.RE |
| 379 |
.PP |
| 380 |
|
| 381 |
Adding embedded lyrics: |
| 382 |
.RS |
| 383 |
oggenc somefile.wav --lyrics lyrics.lrc --lyrics-language en -o out.oga |
| 384 |
.RE |
| 385 |
.PP |
| 386 |
|
| 387 |
This encodes the three files, each with the |
| 388 |
same artist/album tag, but with different title tags on each one. The |
| 389 |
string given as an argument to -n is used to generate filenames, as shown |
| 390 |
in the section above. This example gives filenames |
| 391 |
like "The Tea Party - Touch.ogg": |
| 392 |
.RS |
| 393 |
oggenc -b 192 -a "The Tea Party" -l "Triptych" -t "Touch" track01.wav -t |
| 394 |
"Underground" track02.wav -t "Great Big Lie" track03.wav -n "%a - %t.ogg" |
| 395 |
.RE |
| 396 |
.PP |
| 397 |
|
| 398 |
Encoding from stdin, to stdout (you can also use the various tagging |
| 399 |
options, like -t, -a, -l, etc.): |
| 400 |
.RS |
| 401 |
oggenc - |
| 402 |
.RE |
| 403 |
.PP |
| 404 |
|
| 405 |
.SH AUTHORS |
| 406 |
|
| 407 |
.TP |
| 408 |
Program Author: |
| 409 |
.br |
| 410 |
Michael Smith <[email protected]> |
| 411 |
|
| 412 |
.TP |
| 413 |
Manpage Author: |
| 414 |
.br |
| 415 |
Stan Seibert <[email protected]> |
| 416 |
|
| 417 |
.SH BUGS |
| 418 |
Reading type 3 Wave files (floating point samples) probably doesn't work other than on Intel (or other 32 bit, little endian machines). |
| 419 |
|
| 420 |
.SH "SEE ALSO" |
| 421 |
|
| 422 |
.PP |
| 423 |
\fBvorbiscomment\fR(1), \fBogg123\fR(1), \fBoggdec\fR(1), \fBflac\fR(1), \fBspeexenc\fR(1), \fBffmpeg2theora\fR(1), \fBkateenc\fR(1) |