Encoders are OBS-specific implementations of video/audio encoders, which are used with outputs that use encoders. x264, NVENC, Quicksync are examples of encoder implementations. The libobs/obs-encoder.h file is the dedicated header for implementing encoders
A reference-counted encoder object.
A weak reference to an encoder object.
#include <obs.h>
Encoder definition structure.
Unique string identifier for the encoder (required).
Type of encoder.
OBS_ENCODER_VIDEO - Video encoder
OBS_ENCODER_AUDIO - Audio encoder
The codec, in string form. For example, “h264” for an H.264 encoder.
Get the translated name of the encoder type.
The type_data variable of this structure
The translated name of the encoder type
Creates the implementation data for the encoder.
Settings to initialize the encoder with
Encoder that this data is associated with
The implementation data associated with this encoder
Destroys the implementation data for the encoder.
Called to encode video or audio and outputs packets as they become available.
Raw audio/video data to encode
Encoder packet output, if any
Set to true if a packet was received, false otherwise
true if successful, false on critical failure
An audio encoder’s frame size. For example, for AAC this number would be 1024
Sets the default settings for this encoder.
Default settings. Call obs_data_set_default* functions on this object to set default setting values
Gets the property information of this encoder.
The implementation data associated with this encoder.
This value can be null (e.g., when
obs_get_encoder_properties() is called on the
encoder type), make sure to handle this gracefully.
(Optional)
The properties of the encoder
Updates the settings for this encoder.
(Optional)
New settings for this encoder
Returns extra data associated with this encoder (usually header).
(Optional)
Pointer to receive the extra data
Pointer to receive the size of the extra data
true if extra data available, false otherwise
Gets the SEI data of a video encoder that has SEI data.
(Optional)
Pointer to receive the SEI data
Pointer to receive the SEI data size
true if SEI data available, false otherwise
Returns desired audio format and sample information. This callback can be used to tell the back-end that the audio data needs to be automatically converted to a different sample rate or audio format before being sent to the encoder.
(Optional)
Audio format information
Returns desired video format information. This callback can be used to tell the back-end that the video data needs to be automatically converted to a different video format or specific size before being sent to the encoder.
Video format information
Private data associated with this entry. Note that this is not the same as the implementation data; this is used to differentiate between two different types if the same callbacks are used for more than one different type.
Can be 0 or a bitwise OR combination of one or more of the following values:
OBS_ENCODER_CAP_DEPRECATED - Encoder is deprecated
OBS_ENCODER_CAP_ROI - Encoder supports region of interest feature
desiring to receive unscaled frames
Returns the number of priming samples that must be skipped for correct playback for audio produced by this encoder. Only required for lossy codecs such as AAC or Opus.
Number of samples
Encoder packet structure.
Packet data.
Packet size.
Packet presentation and decode timestamps.
Packet time base.
Can be one of the following values:
OBS_ENCODER_VIDEO - Video data
OBS_ENCODER_AUDIO - Audio data
Packet is a keyframe.
The DTS in microseconds.
(This should not be set by the encoder implementation)
The system time of this packet in microseconds.
(This should not be set by the encoder implementation)
Packet priority. This is no longer used.
(This should not be set by the encoder implementation)
Packet drop priority.
If this packet needs to be dropped, the next packet must be of this priority or higher to continue transmission.
(This should not be set by the encoder implementation)
Audio track index.
(This should not be set by the encoder implementation)
Encoder object associated with this packet.
(This should not be set by the encoder implementation)
Raw frame data structure.
Raw video/audio data.
Line size of each plane.
Number of audio frames (if audio).
Presentation timestamp.
Encoder region of interest structure.
Added in version 30.1.
The rectangle edges of the region are specified as number of pixels from the input video’s top and left edges (i.e. row/column 0).
Priority is specified as a float value between -1.0f and 1. These are converted to encoder-specific values by the encoder. Values above 0 tell the encoder to increase quality for that region, values below tell it to worsen it. Not all encoders support negative values and they may be ignored.
Registers an encoder type. Typically used in
obs_module_load() or in the program’s initialization phase.
Calls the obs_encoder_info.get_name callback to get the
translated display name of an encoder type.
id – The encoder type string identifier
The translated display name of an encoder type
Creates a video encoder with the specified settings.
The “encoder” context is used for encoding video/audio data. Use obs_encoder_release to release it.
id – The encoder type string identifier
name – The desired name of the encoder. If this is not unique, it will be made to be unique
settings – The settings for the encoder, or NULL if none
hotkey_data – Saved hotkey data for the encoder, or NULL if none
A reference to the newly created encoder, or NULL if failed
Creates an audio encoder with the specified settings.
The “encoder” context is used for encoding video/audio data. Use
obs_encoder_release() to release it.
id – The encoder type string identifier
name – The desired name of the encoder. If this is not unique, it will be made to be unique
settings – The settings for the encoder, or NULL if none
mixer_idx – The audio mixer index this audio encoder will capture audio from
hotkey_data – Saved hotkey data for the encoder, or NULL if none
A reference to the newly created encoder, or NULL if failed
Returns an incremented reference if still valid, otherwise returns
NULL. Release with obs_encoder_release().
Releases a reference to an encoder. When the last reference is released, the encoder is destroyed.
These functions are used to get a weak reference from a strong encoder reference, or a strong encoder reference from a weak reference. If the encoder is destroyed, obs_weak_encoder_get_encoder will return NULL.
Adds/releases a weak reference to an encoder.
Sets the name of an encoder. If the encoder is not private and the name is not unique, it will automatically be given a unique name.
The name of the encoder
The codec identifier of the encoder
The encoder type: OBS_ENCODER_VIDEO or OBS_ENCODER_AUDIO
Sets the scaled resolution for a video encoder. Set width and height to 0 to disable scaling. If the encoder is active, this function will trigger a warning, and do nothing.
true if pre-encode (CPU) scaling enabled, false otherwise.
The width/height of a video encoder’s encoded image
The sample rate of an audio encoder’s audio data
The frame size of the audio packet
The mixer index for the audio track which is encoded by the encoder
Sets the preferred video format for a video encoder. If the encoder can use the format specified, it will force a conversion to that format if the obs output format does not match the preferred format.
If the format is set to VIDEO_FORMAT_NONE, will revert to the default functionality of converting only when absolutely necessary.
An incremented reference to the encoder’s default settings.
Release with obs_data_release().
Use these functions to get the properties of an encoder or encoder type. Properties are optionally used (if desired) to automatically generate user interface widgets to allow users to update settings.
The properties list for a specific existing encoder. Free
with obs_properties_destroy()
Updates the settings for this encoder context.
An incremented reference to the encoder’s settings. Release with
obs_data_release().
The signal handler of the encoder. Should not be manually freed, as its lifecycle is managed by libobs.
The procedure handler of the encoder. Should not be manually freed, as its lifecycle is managed by libobs.
Gets extra data (headers) associated with this encoder.
true if successful, false if no extra data associated with this encoder
Sets the video/audio handler to use with this video/audio encoder. This is used to capture the raw video/audio data.
The video/audio handler associated with this encoder, or NULL if none or not a matching encoder type. parent_video returns the “original” video handler associated with this encoder, regardless of whether an FPS divisor is set.
true if the encoder is active, false otherwise
Adds a new region of interest to the encoder if ROI feature is supported.
true if adding succeeded, false otherwise.
Added in version 30.1.
true if encoder has ROI regions set, false otherwise.
Added in version 30.1.
Clear region of interest list, if any.
Added in version 30.1.
Enumerate currently configured ROIs by invoking callback for each entry, in reverse order of addition (i.e. most recent to oldest).
Note: If the encoder has scaling enabled the struct passed to the callback will be scaled accordingly.
Added in version 30.1.
Encoders shall refresh their ROI configuration if the increment value changes.
Increment/revision of ROI list
Added in version 30.1.
Gets the number of samples that shall be skipped when playing back the encoded audio. Commonly referred to as “encoder delay” or “priming samples” in AAC/Opus.
Number of priming samples
Added in version 32.1.
Adds or releases a reference to an encoder packet.