theoraenc: GStreamer Base Plugins 1.0 Plugins Reference Manual

## theoraenc theoraenc |

## Properties

gint | bitrate | Read / Write
gboolean | cap-overflow | Read / Write
gboolean | cap-underflow | Read / Write
gboolean | drop-frames | Read / Write
gboolean | keyframe-auto | Read / Write
gint | keyframe-force | Read / Write
gint | keyframe-freq | Read / Write
gchar * | multipass-cache-file | Read / Write
GstTheoraEncMultipassMode | multipass-mode | Read / Write
gint | quality | Read / Write
gint | rate-buffer | Read / Write
gint | speed-level | Read / Write
gboolean | vp3-compatible | Read / Write

## Types and Values

struct | GstTheoraEnc
enum | GstTheoraEncMultipassMode

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstElement
                    ╰── GstVideoEncoder
                        ╰── GstTheoraEnc

## Implemented Interfaces

GstTheoraEnc implements GstPreset.

## Description

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

    1
    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.

## Synopsis

### Element Information

plugin | theora
author | Wim Taymans <wim@fluendo.com>
class | Codec/Encoder/Video

### Element Pads

name | sink
direction | sink
presence | always
details | video/x-raw, format=(string){ I420, Y42B, Y444 }, framerate=(fraction)[ 1/2147483647, 2147483647/1 ], width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ]

name | src
direction | source
presence | always
details | video/x-theora, framerate=(fraction)[ 1/2147483647, 2147483647/1 ], width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ]

## Functions

## Types and Values

### struct GstTheoraEnc

    struct GstTheoraEnc;

Opaque data structure.

### enum GstTheoraEncMultipassMode

#### Members

MULTIPASS_MODE_SINGLE_PASS | Single pass encoding |
MULTIPASS_MODE_FIRST_PASS | First pass of two pass encoding |
MULTIPASS_MODE_SECOND_PASS | Second pass of two pass encoding |

## Property Details

### The `“bitrate”` property

      “bitrate”                  gint

Compressed video bitrate (kbps).

Flags: Read / Write

Allowed values: [0,16777215]

Default value: 0

### The `“cap-overflow”` property

      “cap-overflow”             gboolean

Enable capping of bit reservoir overflows.

Flags: Read / Write

Default value: TRUE

### The `“cap-underflow”` property

      “cap-underflow”            gboolean

Enable capping of bit reservoir underflows.

Flags: Read / Write

Default value: FALSE

### The `“drop-frames”` property

      “drop-frames”              gboolean

Allow or disallow frame dropping.

Flags: Read / Write

Default value: TRUE

### The `“keyframe-auto”` property

      “keyframe-auto”            gboolean

Automatic keyframe detection.

Flags: Read / Write

Default value: TRUE

### The `“keyframe-force”` property

      “keyframe-force”           gint

Force keyframe every N frames.

Flags: Read / Write

Allowed values: [1,32768]

Default value: 64

### The `“keyframe-freq”` property

      “keyframe-freq”            gint

Keyframe frequency.

Flags: Read / Write

Allowed values: [1,32768]

Default value: 64

### The `“multipass-cache-file”` property

      “multipass-cache-file”     gchar *

Multipass cache file.

Flags: Read / Write

Default value: NULL

### The `“multipass-mode”` property

      “multipass-mode”           GstTheoraEncMultipassMode

Single pass or first/second pass.

Flags: Read / Write

Default value: Single pass

### The `“quality”` property

      “quality”                  gint

Video quality.

Flags: Read / Write

Allowed values: [0,63]

Default value: 48

### The `“rate-buffer”` property

      “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

Allowed values: [0,1000]

Default value: 0

### The `“speed-level”` property

      “speed-level”              gint

Controls the amount of motion vector searching done while encoding.

Flags: Read / Write

Allowed values: [0,3]

Default value: 1

### The `“vp3-compatible”` property

      “vp3-compatible”           gboolean

Disables non-VP3 compatible features.

Flags: Read / Write

Default value: FALSE

## See Also

theoradec, oggmux