Encoder API Reference (obs_encoder_t)

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

type obs_encoder_t

A reference-counted encoder object.

type obs_weak_encoder_t

A weak reference to an encoder object.

#include <obs.h>

Encoder Definition Structure (obs_encoder_info)

struct obs_encoder_info

Encoder definition structure.

const char *obs_encoder_info.id

Unique string identifier for the encoder (required).

enum obs_encoder_type obs_encoder_info.type

Type of encoder.

• OBS_ENCODER_VIDEO - Video encoder

• OBS_ENCODER_AUDIO - Audio encoder

const char *obs_encoder_info.codec

The codec, in string form. For example, “h264” for an H.264 encoder.

const char *(*obs_encoder_info.get_name)(void *type_data)

Get the translated name of the encoder type.

Param type_data:

The type_data variable of this structure

Return:

The translated name of the encoder type

void *(*obs_encoder_info.create)(obs_data_t *settings, obs_encoder_t *encoder)

Creates the implementation data for the encoder.

Param settings:

Settings to initialize the encoder with

Param encoder:

Encoder that this data is associated with

Return:

The implementation data associated with this encoder

void (*obs_encoder_info.destroy)(void *data)

Destroys the implementation data for the encoder.

bool (*encode)(void *data, struct encoder_frame *frame, struct encoder_packet *packet, bool *received_packet)

Called to encode video or audio and outputs packets as they become available.

Param frame:

Raw audio/video data to encode

Param packet:

Encoder packet output, if any

Param received_packet:

Set to true if a packet was received, false otherwise

Return:

true if successful, false on critical failure

size_t (*get_frame_size)(void *data)

Return:

An audio encoder’s frame size. For example, for AAC this number would be 1024

void (*obs_encoder_info.get_defaults)(obs_data_t *settings)

void (*obs_encoder_info.get_defaults2)(obs_data_t *settings, void *type_data)

Sets the default settings for this encoder.

Param settings:

Default settings. Call obs_data_set_default* functions on this object to set default setting values

obs_properties_t *(*obs_encoder_info.get_properties)(void *data)

obs_properties_t *(*obs_encoder_info.get_properties2)(void *data, void *type_data)

Gets the property information of this encoder.

Param data:

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)

Return:

The properties of the encoder

void (*obs_encoder_info.update)(void *data, obs_data_t *settings)

Updates the settings for this encoder.

(Optional)

Param settings:

New settings for this encoder

bool (*obs_encoder_info.get_extra_data)(void *data, uint8_t **extra_data, size_t *size)

Returns extra data associated with this encoder (usually header).

(Optional)

Param extra_data:

Pointer to receive the extra data

Param size:

Pointer to receive the size of the extra data

Return:

true if extra data available, false otherwise

bool (*obs_encoder_info.get_sei_data)(void *data, uint8_t **sei_data, size_t *size)

Gets the SEI data of a video encoder that has SEI data.

(Optional)

Param sei_data:

Pointer to receive the SEI data

Param size:

Pointer to receive the SEI data size

Return:

true if SEI data available, false otherwise

void (*obs_encoder_info.get_audio_info)(void *data, struct audio_convert_info *info)

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)

Param info:

Audio format information

void (*obs_encoder_info.get_video_info)(void *data, struct video_scale_info *info)

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.

Param info:

Video format information

void *obs_encoder_info.type_data

void (*obs_encoder_info.free_type_data)(void *type_data)

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.

uint32_t obs_encoder_info.caps

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

• OBS_ENCODER_CAP_SCALING - Encoder implements its own scaling logic,

  desiring to receive unscaled frames

Encoder Packet Structure (encoder_packet)

struct encoder_packet

Encoder packet structure.

uint8_t *encoder_packet.data

Packet data.

size_t encoder_packet.size

Packet size.

int64_t encoder_packet.pts

int64_t encoder_packet.dts

Packet presentation and decode timestamps.

int32_t encoder_packet.timebase_num

int32_t encoder_packet.timebase_den

Packet time base.

enum obs_encoder_type encoder_packet.type

Can be one of the following values:

• OBS_ENCODER_VIDEO - Video data

• OBS_ENCODER_AUDIO - Audio data

bool encoder_packet.keyframe

Packet is a keyframe.

int64_t encoder_packet.dts_usec

The DTS in microseconds.

(This should not be set by the encoder implementation)

int64_t encoder_packet.sys_dts_usec

The system time of this packet in microseconds.

(This should not be set by the encoder implementation)

int encoder_packet.priority

Packet priority. This is no longer used.

(This should not be set by the encoder implementation)

int encoder_packet.drop_priority

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)

size_t encoder_packet.track_idx

Audio track index.

(This should not be set by the encoder implementation)

obs_encoder_t *encoder_packet.encoder

Encoder object associated with this packet.

(This should not be set by the encoder implementation)

Raw Frame Data Structure (encoder_frame)

struct encoder_frame

Raw frame data structure.

uint8_t *encoder_frame.data[MAX_AV_PLANES]

Raw video/audio data.

uint32_t encoder_frame.linesize[MAX_AV_PLANES]

Line size of each plane.

uint32_t encoder_frame.frames

Number of audio frames (if audio).

int64_t encoder_frame.pts

Presentation timestamp.

Encoder Region of Interest Structure (obs_encoder_roi)

struct obs_encoder_roi

Encoder region of interest structure.

Added in version 30.1.

uint32_t top

uint32_t bottom

uint32_t left

uint32_t right

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

float priority

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.

General Encoder Functions

void obs_register_encoder(struct obs_encoder_info *info)

Registers an encoder type. Typically used in obs_module_load() or in the program’s initialization phase.

---

const char *obs_encoder_get_display_name(const char *id)

Calls the obs_encoder_info.get_name callback to get the translated display name of an encoder type.

Parameters:

• id – The encoder type string identifier

Returns:

The translated display name of an encoder type

---

obs_encoder_t *obs_video_encoder_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data)

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.

Parameters:

• 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

Returns:

A reference to the newly created encoder, or NULL if failed

---

obs_encoder_t *obs_audio_encoder_create(const char *id, const char *name, obs_data_t *settings, size_t mixer_idx, obs_data_t *hotkey_data)

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.

Parameters:

• 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

Returns:

A reference to the newly created encoder, or NULL if failed

---

obs_encoder_t *obs_encoder_get_ref(obs_encoder_t *encoder)

Returns an incremented reference if still valid, otherwise returns NULL. Release with obs_encoder_release().

---

void obs_encoder_release(obs_encoder_t *encoder)

Releases a reference to an encoder. When the last reference is released, the encoder is destroyed.

---

obs_weak_encoder_t *obs_encoder_get_weak_encoder(obs_encoder_t *encoder)

obs_encoder_t *obs_weak_encoder_get_encoder(obs_weak_encoder_t *weak)

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.

---

void obs_weak_encoder_addref(obs_weak_encoder_t *weak)

void obs_weak_encoder_release(obs_weak_encoder_t *weak)

Adds/releases a weak reference to an encoder.

---

void obs_encoder_set_name(obs_encoder_t *encoder, const char *name)

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.

---

const char *obs_encoder_get_name(const obs_encoder_t *encoder)

Returns:

The name of the encoder

---

const char *obs_encoder_get_codec(const obs_encoder_t *encoder)

const char *obs_get_encoder_codec(const char *id)

Returns:

The codec identifier of the encoder

---

enum obs_encoder_type obs_encoder_get_type(const obs_encoder_t *encoder)

enum obs_encoder_type obs_get_encoder_type(const char *id)

Returns:

The encoder type: OBS_ENCODER_VIDEO or OBS_ENCODER_AUDIO

---

void obs_encoder_set_scaled_size(obs_encoder_t *encoder, uint32_t width, uint32_t height)

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.

---

bool obs_encoder_scaling_enabled(const obs_encoder_t *encoder)

Returns:

true if pre-encode (CPU) scaling enabled, false otherwise.

---

uint32_t obs_encoder_get_width(const obs_encoder_t *encoder)

uint32_t obs_encoder_get_height(const obs_encoder_t *encoder)

Returns:

The width/height of a video encoder’s encoded image

---

uint32_t obs_encoder_get_sample_rate(const obs_encoder_t *encoder)

Returns:

The sample rate of an audio encoder’s audio data

---

size_t obs_encoder_get_frame_size(const obs_encoder_t *encoder)

Returns:

The frame size of the audio packet

---

size_t obs_encoder_get_mixer_index(const obs_encoder_t *encoder)

Returns:

The mixer index for the audio track which is encoded by the encoder

---

void obs_encoder_set_preferred_video_format(obs_encoder_t *encoder, enum video_format format)

enum video_format obs_encoder_get_preferred_video_format(const obs_encoder_t *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.

---

obs_data_t *obs_encoder_defaults(const char *id)

obs_data_t *obs_encoder_get_defaults(const obs_encoder_t *encoder)

Returns:

An incremented reference to the encoder’s default settings. Release with obs_data_release().

---

obs_properties_t *obs_encoder_properties(const obs_encoder_t *encoder)

obs_properties_t *obs_get_encoder_properties(const char *id)

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.

Returns:

The properties list for a specific existing encoder. Free with obs_properties_destroy()

---

void obs_encoder_update(obs_encoder_t *encoder, obs_data_t *settings)

Updates the settings for this encoder context.

---

obs_data_t *obs_encoder_get_settings(const obs_encoder_t *encoder)

Returns:

An incremented reference to the encoder’s settings. Release with obs_data_release().

---

signal_handler_t *obs_encoder_get_signal_handler(const obs_encoder_t *encoder)

Returns:

The signal handler of the encoder. Should not be manually freed, as its lifecycle is managed by libobs.

---

proc_handler_t *obs_encoder_get_proc_handler(const obs_encoder_t *encoder)

Returns:

The procedure handler of the encoder. Should not be manually freed, as its lifecycle is managed by libobs.

---

bool obs_encoder_get_extra_data(const obs_encoder_t *encoder, uint8_t **extra_data, size_t *size)

Gets extra data (headers) associated with this encoder.

Returns:

true if successful, false if no extra data associated with this encoder

---

void obs_encoder_set_video(obs_encoder_t *encoder, video_t *video)

void obs_encoder_set_audio(obs_encoder_t *encoder, audio_t *audio)

Sets the video/audio handler to use with this video/audio encoder. This is used to capture the raw video/audio data.

---

video_t *obs_encoder_video(const obs_encoder_t *encoder)

video_t *obs_encoder_parent_video(const obs_encoder_t *encoder)

audio_t *obs_encoder_audio(const obs_encoder_t *encoder)

Returns:

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.

---

bool obs_encoder_active(const obs_encoder_t *encoder)

Returns:

true if the encoder is active, false otherwise

---

bool obs_encoder_add_roi(obs_encoder_t *encoder, const struct obs_encoder_roi *roi)

Adds a new region of interest to the encoder if ROI feature is supported.

Returns:

true if adding succeeded, false otherwise.

Added in version 30.1.

---

bool obs_encoder_has_roi(obs_encoder_t *encoder)

Returns:

true if encoder has ROI regions set, false otherwise.

Added in version 30.1.

---

void obs_encoder_clear_roi(obs_encoder_t *encoder)

Clear region of interest list, if any.

Added in version 30.1.

---

void obs_encoder_enum_roi(obs_encoder_t *encoder, void (*enum_proc)(void*, struct obs_encoder_roi*), void *param)

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.

---

uint32_t obs_encoder_get_roi_increment(const obs_encoder_t *encoder)

Encoders shall refresh their ROI configuration if the increment value changes.

Returns:

Increment/revision of ROI list

Added in version 30.1.

---

Functions used by encoders

void obs_encoder_packet_ref(struct encoder_packet *dst, struct encoder_packet *src)

void obs_encoder_packet_release(struct encoder_packet *packet)

Adds or releases a reference to an encoder packet.