1oggenc(1)                        Vorbis Tools                        oggenc(1)
2
3
4

NAME

6       oggenc - encode audio into the Ogg Vorbis format
7
8

SYNOPSIS

10       oggenc  [  -hrQ ] [ -B raw input sample size ] [ -C raw input number of
11       channels ] [ -R raw input samplerate ] [ -b nominal bitrate ] [ -m min‐
12       imum  bitrate ] [ -M maximum bitrate ] [ -q quality ] [ --resample fre‐
13       quency ] [ --downmix ] [ -s serial ] [ -o output_file ] [ -n pattern  ]
14       [ -c extra_comment ] [ -a artist ] [ -t title ] [ -l album ] [ -G genre
15       ] [ -L lyrics file ] [ -Y language-string ] input_files ...
16
17

DESCRIPTION

19       oggenc reads audio data in either raw, Wave, or AIFF format and encodes
20       it  into  an  Ogg  Vorbis stream.  oggenc may also read audio data from
21       FLAC and Ogg FLAC files depending upon compile-time  options.   If  the
22       input file "-" is specified, audio data is read from stdin and the Vor‐
23       bis stream is written to stdout unless the -o option is used  to  redi‐
24       rect the output.  By default, disk files are output to Ogg Vorbis files
25       of the same name, with the extension changed to ".ogg" or ".oga".  This
26       naming  convention  can  be overridden by the -o option (in the case of
27       one file) or the -n option (in the case of several files). Finally,  if
28       none  of  these  are  available,  the output filename will be the input
29       filename with the extension (that part after the  final  dot)  replaced
30       with ogg, so file.wav will become file.ogg.
31       Optionally, lyrics may be embedded in the Ogg file, if Kate support was
32       compiled in.
33       Note that some old players mail fail to play streams with more  than  a
34       single Vorbis stream (the so called "Vorbis I" simple profile).
35
36

OPTIONS

38       -h, --help
39              Show command help.
40
41       -V, --version
42              Show the version number.
43
44       -r, --raw
45              Assume input data is raw little-endian audio data with no header
46              information. If other options are  not  specified,  defaults  to
47              44.1kHz  stereo 16 bit. See next three options for how to change
48              this.
49
50       -B n, --raw-bits=n
51              Sets raw mode input sample size in bits. Default is 16.
52
53       -C n, --raw-chan=n
54              Sets raw mode input number of channels. Default is 2.
55
56       -R n, --raw-rate=n
57              Sets raw mode input samplerate. Default is 44100.
58
59       --raw-endianness n
60              Sets raw mode endianness to big endian (1) or little endian (0).
61              Default is little endian.
62
63       --utf8
64              Informs  oggenc  that the Vorbis Comments are already encoded as
65              UTF-8.  Useful in situations where the shell is using some other
66              encoding.
67
68       -k, --skeleton
69              Add  a  Skeleton  bitstream.   Important  if  the  output Ogg is
70              intended to carry multiplexed or chained streams.   Output  file
71              uses .oga as file extension.
72
73       --ignorelength
74              Support for Wave files over 4 GB and stdin data streams.
75
76       -Q, --quiet
77              Quiet mode.  No messages are displayed.
78
79       -b n, --bitrate=n
80              Sets  target bitrate to n (in kb/s). The encoder will attempt to
81              encode at approximately this bitrate. By default, this remains a
82              VBR  encoding.  See  the  --managed  option  to  force a managed
83              bitrate encoding at the selected bitrate.
84
85       -m n, --min-bitrate=n
86              Sets minimum bitrate to n (in kb/s). Enables bitrate  management
87              mode (see --managed).
88
89       -M n, --max-bitrate=n
90              Sets  maximum bitrate to n (in kb/s). Enables bitrate management
91              mode (see --managed).
92
93       --managed
94              Set bitrate management mode.  This  turns  off  the  normal  VBR
95              encoding,  but  allows  hard  or  soft bitrate constraints to be
96              enforced by the encoder. This mode is much slower, and may  also
97              be  lower quality. It is primarily useful for creating files for
98              streaming.
99
100       -q n, --quality=n
101              Sets encoding quality to n, between -1 (very low) and  10  (very
102              high).  This  is  the  default mode of operation, with a default
103              quality level of 3. Fractional quality levels such  as  2.5  are
104              permitted.  Using  this  option  allows the encoder to select an
105              appropriate bitrate based on your desired quality level.
106
107       --resample n
108              Resample input to the given sample rate (in Hz) before encoding.
109              Primarily useful for downsampling for lower-bitrate encoding.
110
111       --downmix
112              Downmix  input  from stereo to mono (has no effect on non-stereo
113              streams). Useful for lower-bitrate encoding.
114
115       --advanced-encode-option optionname=value
116              Sets an advanced option. See the Advanced  Options  section  for
117              details.
118
119       -s, --serial
120              Forces  a  specific  serial number in the output stream. This is
121              primarily useful for testing.
122
123       --discard-comments
124              Prevents comments in FLAC and Ogg FLAC files from  being  copied
125              to the output Ogg Vorbis file.
126
127       -o output_file, --output=output_file
128              Write the Ogg Vorbis stream to output_file (only valid if a sin‐
129              gle input file is specified).
130
131
132       -n pattern, --names=pattern
133              Produce filenames as this string, with %g, %a, %l,  %n,  %t,  %d
134              replaced by genre, artist, album, track number, title, and date,
135              respectively (see below for specifying these). Also, %% gives  a
136              literal %.
137
138       -X, --name-remove=s
139              Remove the specified characters from parameters to the -n format
140              string. This is useful to ensure legal filenames are generated.
141
142       -P, --name-replace=s
143              Replace characters removed by --name-remove with the  characters
144              specified.  If  this  string  is  shorter than the --name-remove
145              list, or  is  not  specified,  the  extra  characters  are  just
146              removed. The default settings for this option, and the -X option
147              above, are platform specific (and chosen to ensure  legal  file‐
148              names are generated for each platform).
149
150
151       -c comment, --comment comment
152              Add  the  string  comment as an extra comment.  This may be used
153              multiple times, and all instances will be added to each  of  the
154              input  files  specified.  The  argument  should  be  in the form
155              "tag=value".
156
157
158       -a artist, --artist artist
159              Set the artist comment field in the comments to artist.
160
161
162       -G genre, --genre genre
163              Set the genre comment field in the comments to genre.
164
165
166       -d date, --date date
167              Sets the date comment field to the given value. This  should  be
168              the date of recording.
169
170
171       -N n, --tracknum n
172              Sets the track number comment field to the given value.
173
174
175       -t title, --title title
176              Set the track title comment field to title.
177
178
179       -l album, --album album
180              Set the album comment field to album.
181
182
183       -L filename, --lyrics filename
184              Loads  lyrics  from filename and encodes them into a Kate stream
185              multiplexed with the Vorbis stream.  Lyrics may be in LRC or SRT
186              format,  and  should  be  encoded in UTF-8 or plain ASCII. Other
187              encodings may be converted using tools such as iconv or  recode.
188              Alternatively,  the same system as for comments will be used for
189              conversion between encodings.  So called  "enhanced  LRC"  files
190              are  supported,  and a simple karaoke style change will be saved
191              with the lyrics. For more  complex  karaoke  setups,  kateenc(1)
192              should be used instead.  When embedding lyrics, the default out‐
193              put file extension is ".oga".  Note  that  adding  lyrics  to  a
194              stream will automatically enable Skeleton (see the -k option for
195              more information about Skeleton).
196
197
198       -Y language-string, --lyrics-language language-string
199              Sets the language for the corresponding lyrics file to language-
200              string.   This  should be an ISO 639-1 language code (eg, "en"),
201              or a RFC 3066 language tag (eg, "en_US"), not a free  form  lan‐
202              guage  name.  Players will typically recognize this standard tag
203              and display the language name in your own language.   Note  that
204              the maximum length of this tag is 15 characters.
205
206       Note  that  the  -a,  -t, -l, -L, and -Y  options can be given multiple
207       times.  They will be applied, one to each file, in the order given.  If
208       there  are  fewer album, title, or artist comments given than there are
209       input files, oggenc will reuse the final one for the  remaining  files,
210       and issue a warning in the case of repeated titles.
211
212

ADVANCED ENCODER OPTIONS

214       Oggenc allows you to set a number of advanced encoder options using the
215       --advanced-encode-option option. These are intended for  very  advanced
216       users  only,  and  should be approached with caution. They may signifi‐
217       cantly degrade audio quality if misused. Not all these options are cur‐
218       rently documented.
219
220
221       lowpass_frequency=N
222              Set the lowpass frequency to N kHz.
223
224
225       impulse_noisetune=N
226              Set  a  noise  floor  bias N (range from -15. to 0.) for impulse
227              blocks.  A negative bias instructs the encoder  to  pay  special
228              attention  to  the crispness of transients in the encoded audio.
229              The tradeoff for better transient response is a higher bitrate.
230
231
232       bitrate_hard_max=N
233              Set the allowed bitrate maximum for the encoded file to N  kilo‐
234              bits  per  second.  This bitrate may be exceeded only when there
235              is spare bits in the bit reservoir;  if  the  bit  reservoir  is
236              exhausted,  frames  will be held under this value.  This setting
237              must be used with --managed to have any effect.
238
239
240       bitrate_hard_min=N
241              Set the allowed bitrate minimum for the encoded file to N  kilo‐
242              bits per second.  This bitrate may be underrun only when the bit
243              reservoir is not full; if the bit reservoir is full, frames will
244              be  held over this value; if it impossible to add bits construc‐
245              tively, the frame will be padded with zeroes.  This setting must
246              be used with --managed to have any effect.
247
248
249       bit_reservoir_bits=N
250              Set  the  total size of the bit reservoir to N bits; the default
251              size of the reservoir is equal to the  nominal  number  of  bits
252              coded  in one second (eg, a nominal 128kbps file will have a bit
253              reservoir of 128000 bits by default).  This option must be  used
254              with  --managed  to have any effect and affects only minimum and
255              maximum bitrate management.  Average bitrate  encoding  with  no
256              hard bitrate boundaries does not use a bit reservoir.
257
258
259       bit_reservoir_bias=N
260              Set  the  behavior  bias of the bit reservoir (range: 0. to 1.).
261              When set closer to 0, the bitrate manager attempts to hoard bits
262              for  future use in sudden bitrate increases (biasing toward bet‐
263              ter transient reproduction).  When set closer to 1, the  bitrate
264              manager  neglects  transients in favor using bits for homogenous
265              passages.  In the middle, the manager uses a balanced  approach.
266              The  default  setting  is .2, thus biasing slightly toward tran‐
267              sient reproduction.
268
269
270       bitrate_average=N
271              Set the average bitrate for the file to N kilobits  per  second.
272              When  used  without  hard minimum or maximum limits, this option
273              selects reservoirless  Average  Bit  Rate  encoding,  where  the
274              encoder  attempts  to  perfectly  track  a  desired bitrate, but
275              imposes no strict momentary fluctuation limits.  When used along
276              with  a minimum or maximum limit, the average bitrate still sets
277              the average overall bitrate of the file, but  will  work  within
278              the  bounds  set  by  the  bit reservoir.  When the min, max and
279              average bitrates are identical,  oggenc  produces  Constant  Bit
280              Rate Vorbis data.
281
282
283       bitrate_average_damping=N
284              Set  the reaction time for the average bitrate tracker to N sec‐
285              onds.  This number represents the fastest reaction  the  bitrate
286              tracker  is  allowed to make to hold the bitrate to the selected
287              average.  The faster the reaction time, the less momentary fluc‐
288              tuation  in  the  bitrate  but (generally) the lower quality the
289              audio output.  The slower the reaction time, the larger the  ABR
290              fluctuations,  but  (generally) the better the audio.  When used
291              along with min or  max  bitrate  limits,  this  option  directly
292              affects  how  deep and how quickly the encoder will dip into its
293              bit reservoir; the higher the number, the more demand on the bit
294              reservoir.
295
296              The  setting  must  be greater than zero and the useful range is
297              approximately .05 to 10.  The default is .75 seconds.
298
299
300       disable_coupling
301              Disable use of channel coupling for multichannel  encoding.   At
302              present,  the encoder will normally use channel coupling to fur‐
303              ther increase compression  with  stereo  and  5.1  inputs.  This
304              option  forces the encoder to encode each channel fully indepen‐
305              dently using neither lossy nor lossless coupling.
306
307

EXAMPLES

309       Simplest version. Produces output as somefile.ogg:
310              oggenc somefile.wav
311
312       Specifying an output filename:
313              oggenc somefile.wav -o out.ogg
314
315       Specifying a high-quality encoding averaging 256 kbps (but still VBR):
316              oggenc infile.wav -b 256 -o out.ogg
317
318       Specifying a maximum and average bitrate, and enforcing these:
319              oggenc infile.wav --managed -b 128 -M 160 -o out.ogg
320
321       Specifying quality rather than bitrate (to a very high quality mode):
322              oggenc infile.wav -q 6 -o out.ogg
323
324       Downsampling and downmixing to 11 kHz mono before encoding:
325              oggenc --resample 11025 --downmix infile.wav -q 1 -o out.ogg
326
327       Adding some info about the track:
328              oggenc somefile.wav -t "The track title"  -a  "artist  who  per‐
329              formed  this" -l "name of album" -c "OTHERFIELD=contents of some
330              other field not explicitly supported"
331
332       Adding embedded lyrics:
333              oggenc somefile.wav --lyrics lyrics.lrc --lyrics-language en  -o
334              out.oga
335
336       This  encodes the three files, each with the same artist/album tag, but
337       with different title tags on each one. The string given as an  argument
338       to  -n  is  used  to generate filenames, as shown in the section above.
339       This example gives filenames like "The Tea Party - Touch.ogg":
340              oggenc -b 192 -a  "The  Tea  Party"  -l  "Triptych"  -t  "Touch"
341              track01.wav  -t  "Underground"  track02.wav  -t  "Great Big Lie"
342              track03.wav -n "%a - %t.ogg"
343
344       Encoding from stdin, to stdout (you can also use  the  various  tagging
345       options, like -t, -a, -l, etc.):
346              oggenc -
347

AUTHORS

349       Program Author:
350              Michael Smith <msmith@xiph.org>
351
352
353       Manpage Author:
354              Stan Seibert <indigo@aztec.asu.edu>
355
356

BUGS

358       Reading  type  3  Wave  files (floating point samples) probably doesn't
359       work other than on Intel (or other 32 bit, little endian machines).
360
361

SEE ALSO

363       vorbiscomment(1),  ogg123(1),  oggdec(1),  flac(1),  speexenc(1),  ffm‐
364       peg2theora(1), kateenc(1)
365
366
367
368Xiph.Org Foundation             2008 October 05                      oggenc(1)
Impressum