Debian Codegraph @

upstream/debian-unstable/man1/oggenc.1

raw
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)