theoraenc
This element encodes raw video into a Theora stream. Theora is a royalty-free video codec maintained by the Xiph.org Foundation, based on the VP3 codec.
The theora codec internally only supports encoding of images that are a multiple of 16 pixels in both X and Y direction. It is however perfectly possible to encode images with other dimensions because an arbitrary rectangular cropping region can be set up. This element will automatically set up a correct cropping region if the dimensions are not multiples of 16 pixels.
To control the quality of the encoding, the bitrate and quality properties can be used. These two properties are mutualy exclusive. Setting the bitrate property will produce a constant bitrate (CBR) stream while setting the quality property will produce a variable bitrate (VBR) stream.
A videorate element is often required in front of theoraenc, especially when transcoding and when putting Theora into the Ogg container.
Example pipeline
gst-launch-1.0 -v videotestsrc num-buffers=500 ! video/x-raw,width=1280,height=720 ! queue ! progressreport ! theoraenc ! oggmux ! filesink location=videotestsrc.ogg
This example pipeline will encode a test video source to theora muxed in an ogg container. Refer to the theoradec documentation to decode the create stream.
Hierarchy
GObject ╰──GInitiallyUnowned ╰──GstObject ╰──GstElement ╰──GstVideoEncoder ╰──theoraenc
Implemented interfaces
Factory details
Authors: – Wim Taymans
Classification: – Codec/Encoder/Video
Rank – primary
Plugin – theora
Package – GStreamer Base Plug-ins
Pad Templates
sink
video/x-raw:
format: { I420, Y42B, Y444 }
framerate: [ 1/2147483647, 2147483647/1 ]
width: [ 1, 2147483647 ]
height: [ 1, 2147483647 ]
src
video/x-theora:
framerate: [ 1/2147483647, 2147483647/1 ]
width: [ 1, 2147483647 ]
height: [ 1, 2147483647 ]
Properties
cap-overflow
“cap-overflow” gboolean
Enable capping of bit reservoir overflows
Flags : Read / Write
Default value : true
cap-underflow
“cap-underflow” gboolean
Enable capping of bit reservoir underflows
Flags : Read / Write
Default value : false
drop-frames
“drop-frames” gboolean
Allow or disallow frame dropping
Flags : Read / Write
Default value : true
keyframe-auto
“keyframe-auto” gboolean
Automatic keyframe detection
Flags : Read / Write
Default value : true
keyframe-force
“keyframe-force” gint
Force keyframe every N frames
Flags : Read / Write
Default value : 64
multipass-cache-file
“multipass-cache-file” gchararray
Multipass cache file
Flags : Read / Write
Default value : NULL
multipass-mode
“multipass-mode” Theora-enc-multipass-mode *
Single pass or first/second pass
Flags : Read / Write
Default value : single-pass (0)
rate-buffer
“rate-buffer” gint
Sets the size of the rate control buffer, in units of frames. The default value of 0 instructs the encoder to automatically select an appropriate value
Flags : Read / Write
Default value : 0
speed-level
“speed-level” gint
Controls the amount of motion vector searching done while encoding
Flags : Read / Write
Default value : 1
vp3-compatible
“vp3-compatible” gboolean
Disables non-VP3 compatible features
Flags : Read / Write
Default value : false
Named constants
Theora-enc-multipass-mode
Members
single-pass (0) – Single pass
first-pass (1) – First pass
second-pass (2) – Second pass
The results of the search are