.\" Process this file with
.\" groff -man -Tascii opusenc.1
.\"
.TH opusenc 1 2012-05-28 "Xiph.Org Foundation" "opus-tools"

.SH NAME
opusenc \- encode audio into the Opus format

.SH SYNOPSIS
.B opusenc
[
.B -v
] [
.B -h
] [
.B --speech
] [
.B --music
] [
.B --bitrate
.I kbit/sec
] [
.B --vbr
] [
.B --cvbr
] [
.B --hard-cbr
] [
.B --comp
.I complexity
] [
.B --framesize
.I 2.5, 5, 10, 20, 40, 60
] [
.B --expect-loss
.I pct
] [
.B --downmix-mono
] [
.B --downmix-stereo
] [
.B --max-delay
.I ms
] [
.B --save-range
.I file
] [
.B --set-ctl-int
.I ctl=value
] [
.B --uncoupled
] [
.B --comment
.I tag=value
] [
.B --artist
.I author
] [
.B --title
.I track title
] [
.B --raw
] [
.B --raw-bits
.I bits/sample
] [
.B --raw-rate
.I Hz
] [
.B --raw-chan
.I N
] [
.B --raw-endianness
.I flag
] [
.B --ignorelength
]
.I input.wav
.I output.opus

.SH DESCRIPTION
.B opusenc
reads audio data in either raw, Wave, or AIFF format and encodes it into an
Opus stream. If the input file is "-" audio data is read from stdin.
Likewise, if the output file is "-" opus data is written to stdout.

Unless quieted
.B opusenc
displays fancy statistics about the encoding progress.

.SH OPTIONS
.IP "-h, --help"
Show command help
.IP "-v, --version"
Show the version number
.IP "--speech"
Optimize for speech
.IP "--music"
Optimize for music
.IP "--bitrate N.nnn"
Encoding bitrate in kbit/sec (6-256 per channel)
.IP "--vbr"
Use variable bitrate encoding (default)
.IP "--cvbr"
Use constrained variable bitrate encoding
.IP "--hard-cbr"
Use hard constant bitrate encoding
.IP "--comp N"
Encoding computational complexity (0-10, default: 10)
.IP "--framesize N"
Maximum frame size in milliseconds (2.5, 5, 10, 20, 40, 60, default: 20)
.br
Smaller framesizes achieve lower latency but less quality at a given
bitrate.
.br
Sizes greater than 20ms are only interesting at fairly low
bitrates.
.IP "--expect-loss N"
Percentage packet loss to expect (default: 0)
.IP "--downmix-mono"
Downmix to mono
.IP "--downmix-stereo"
Downmix to stereo (if >2 channels input)
.IP "--max-delay N"
Maximum container delay in milliseconds (0-1000, default: 1000)
.IP "--save-range file"
Saves check values for every frame to a file
.IP "--set-ctl-int x=y"
Pass the encoder control x with value y (advanced)
Preface with s: to direct the ctl to multistream s
.br
This may be used multiple times
.IP "--uncoupled"
Use one mono stream per channel
.IP "--comment tag=value"
Add an extra comment.  This may be used multiple times, and all
instances will be added to each of the input files specified. The argument
should be in the form "tag=value".
See the vorbis-comment specification for well known tag names:
http://www.xiph.org/vorbis/doc/v-comment.html
.IP "--artist artist"
Set the artist comment field in the comments to
.I artist
.IP "--title title"
Set the track title comment field to
.I title
.IP "--raw"
Raw (headerless) PCM input
.IP "--raw-bits N"
Set bits/sample for raw input (default: 16)
.IP "--raw-rate N"
Set sampling rate for raw input (default: 48000)
.IP "--raw-chan N"
Set number of channels for raw input (default: 2)
.IP "--raw-endianness [0/1]"
Set the endianness for raw input: 1 for bigendian, 0 for little (defaults to 0)
.IP "--ignorelength"
Always ignore the datalength in Wave headers. Opusenc automatically ignores
the length when its implausible (very small or very large) but some STDIN
usage may still need this option to avoid truncation.

.SH EXAMPLES

Simplest usage. Take input as input.wav and produce output as output.opus:
.RS
opusenc input.wav output.opus
.RE
.PP

Produce a very high quality encode with a target rate of 160kbps:
.RS
opusenc --bitrate 160 input.wav output.opus
.RE
.PP

Record and send a live stream to an Icecast HTTP streaming server using oggfwd:
.RS
arecord -c 2 -r 48000 -twav - | opusenc --bitrate 96 -  - | oggfwd icecast.somewhere.org 8000 password /stream.opus
.RE
.PP

.SH NOTES

While it is possible to use opusenc for low latency streaming (e.g. with --max-delay set to 0
and netcat instead of Icecast) it's not really designed for this, and the Ogg container
and TCP transport aren't the best tools for that application. Shell
pipelines themselves will often have high buffering. The ability to set
framesizes as low as 2.5 ms in opusenc mostly exists to try out the quality
of the format with low latency settings, but not really for actual low
latency usage.
.br
Interactive usage should use UDP/RTP directly.

.SH AUTHORS
.br
Gregory Maxwell <greg@xiph.org>

.SH SEE ALSO
.BR opusdec (1),
.BR opusinfo (1),
.BR oggfwd (1)