## theoraenc theoraenc — encode raw YUV video to a theora stream |

## Synopsis

    struct              GstTheoraEnc;
    enum                GstTheoraEncBorderMode;

## Object Hierarchy

      GObject
       +----GstObject
             +----GstElement
                   +----GstTheoraEnc

## Implemented Interfaces

GstTheoraEnc implements GstPreset.

## Properties

      "bitrate"                  gint                  : Read / Write
      "border"                   GstTheoraEncBorderMode  : Read / Write
      "center"                   gboolean              : Read / Write
      "keyframe-auto"            gboolean              : Read / Write
      "keyframe-force"           gint                  : Read / Write
      "keyframe-freq"            gint                  : Read / Write
      "keyframe-mindistance"     gint                  : Read / Write
      "keyframe-threshold"       gint                  : Read / Write
      "noise-sensitivity"        gint                  : Read / Write
      "quality"                  gint                  : Read / Write
      "quick"                    gboolean              : Read / Write
      "sharpness"                gint                  : Read / Write
      "speed-level"              gint                  : Read / Write / Construct
      "cap-overflow"             gboolean              : Read / Write
      "cap-underflow"            gboolean              : Read / Write
      "drop-frames"              gboolean              : Read / Write
      "rate-buffer"              gint                  : Read / Write
      "vp3-compatible"           gboolean              : Read / Write
      "multipass-cache-file"     gchar*                : Read / Write
      "multipass-mode"           GstTheoraEncMultipassMode  : Read / Write

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

### Example pipeline

    1
    gst-launch -v videotestsrc num-buffers=1000 ! 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.

Last reviewed on 2006-03-01 (0.10.4)

## 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-yuv, format=(fourcc){ 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

## Details

### struct GstTheoraEnc

    struct GstTheoraEnc;

Opaque data structure.

### enum GstTheoraEncBorderMode

    typedef enum
    {
      BORDER_NONE,
      BORDER_BLACK,
      BORDER_MIRROR
    }
    GstTheoraEncBorderMode;

Border color to add when sizes not multiple of 16.

`BORDER_NONE` | no border
`BORDER_BLACK` | black border
`BORDER_MIRROR` | Mirror image in border

## Property Details

### The `"bitrate"` property

      "bitrate"                  gint                  : Read / Write

Compressed video bitrate (kbps).

Allowed values: [0,16777215]

Default value: 0

### The `"border"` property

      "border"                   GstTheoraEncBorderMode  : Read / Write

ignored and kept for API compat only.

Default value: Black Border

### The `"center"` property

      "center"                   gboolean              : Read / Write

ignored and kept for API compat only.

Default value: TRUE

### The `"keyframe-auto"` property

      "keyframe-auto"            gboolean              : Read / Write

Automatic keyframe detection.

Default value: TRUE

### The `"keyframe-force"` property

      "keyframe-force"           gint                  : Read / Write

Force keyframe every N frames.

Allowed values: [1,32768]

Default value: 64

### The `"keyframe-freq"` property

      "keyframe-freq"            gint                  : Read / Write

Keyframe frequency.

Allowed values: [1,32768]

Default value: 64

### The `"keyframe-mindistance"` property

      "keyframe-mindistance"     gint                  : Read / Write

ignored and kept for API compat only.

Allowed values: [1,32768]

Default value: 8

### The `"keyframe-threshold"` property

      "keyframe-threshold"       gint                  : Read / Write

ignored and kept for API compat only.

Allowed values: [0,32768]

Default value: 80

### The `"noise-sensitivity"` property

      "noise-sensitivity"        gint                  : Read / Write

ignored and kept for API compat only.

Allowed values: [0,32768]

Default value: 1

### The `"quality"` property

      "quality"                  gint                  : Read / Write

Video quality.

Allowed values: [0,63]

Default value: 48

### The `"quick"` property

      "quick"                    gboolean              : Read / Write

ignored and kept for API compat only.

Default value: TRUE

### The `"sharpness"` property

      "sharpness"                gint                  : Read / Write

ignored and kept for API compat only.

Allowed values: [0,2]

Default value: 0

### The `"speed-level"` property

      "speed-level"              gint                  : Read / Write / Construct

Controls the amount of analysis performed when encoding. Higher values trade compression quality for speed. This property requires libtheora version >= 1.0, and the maximum value may vary based on encoder version.

Allowed values: [0,2]

Default value: 1

### The `"cap-overflow"` property

      "cap-overflow"             gboolean              : Read / Write

Enable capping of bit reservoir overflows.

Default value: TRUE

### The `"cap-underflow"` property

      "cap-underflow"            gboolean              : Read / Write

Enable capping of bit reservoir underflows.

Default value: FALSE

### The `"drop-frames"` property

      "drop-frames"              gboolean              : Read / Write

Allow or disallow frame dropping.

Default value: TRUE

### The `"rate-buffer"` property

      "rate-buffer"              gint                  : Read / Write

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.

Allowed values: [0,1000]

Default value: 0

### The `"vp3-compatible"` property

      "vp3-compatible"           gboolean              : Read / Write

Disables non-VP3 compatible features.

Default value: FALSE

### The `"multipass-cache-file"` property

      "multipass-cache-file"     gchar*                : Read / Write

Multipass cache file.

Default value: NULL

### The `"multipass-mode"` property

      "multipass-mode"           GstTheoraEncMultipassMode  : Read / Write

Single pass or first/second pass.

Default value: Single pass

## See Also

theoradec, oggmux