# 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 GstTheoraEnc:bitrate and GstTheoraEnc: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

    GstPreset

## 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 ]

Presence – always

Direction – sink

Object type – GstPad

### `src`

    video/x-theora:
          framerate: [ 1/2147483647, 2147483647/1 ]
              width: [ 1, 2147483647 ]
             height: [ 1, 2147483647 ]

Presence – always

Direction – src

Object type – GstPad

## Properties

### bitrate

    “bitrate” gint

Compressed video bitrate (kbps)

Flags : Read / Write

Default value : 0

### 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

### keyframe-freq

    “keyframe-freq” gint

Keyframe frequency

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)

### quality

    “quality” gint

Video quality

Flags : Read / Write

Default value : 48

### 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