AppSrc Plugin

AppSrc is the C++ push-input interface for feeding raw or encoded frames into an RT instance. The release-pinned source supports raw BGR, NV12, and YV12 frames, plus H.264 and H.265 encoded frames.

This page is source-verified for RT 2026.2.1. An application must still exercise its own instance lifecycle, queueing, decoder, and error-handling paths on its target runtime.

Configuration

The source exposes these AppSrc configuration descriptors:

Parameter	Type	Default	Description
sampling_rate	integer	0 until set	Requested playback rate; accepted descriptor range is 1-300
appsrc_idle_timeout	integer	30	Seconds without frames before automatic stop; 0 disables the timeout
encoded_width	integer	0	Coded H.264/H.265 width for dimension-dependent decoders
encoded_height	integer	0	Coded H.264/H.265 height for dimension-dependent decoders
encoded_display_width	integer	0	Display width; 0 uses the coded width
encoded_display_height	integer	0	Display height; 0 uses the coded height

For an encoded source, an owning application can provide the geometry through setEncodedFrameParameters. Once it does, the push path does not read the encoded-dimension configuration values.

max_pixels and target-frame-rate controls are C++ methods, not AppSrc configuration-descriptor keys. queue_size and decode_threads are not AppSrc configuration-descriptor keys.

{
  "appsrc": {
    "sampling_rate": 25,
    "appsrc_idle_timeout": 0,
    "encoded_width": 1920,
    "encoded_height": 1080,
    "encoded_display_width": 1920,
    "encoded_display_height": 1080
  }
}

C++ API

iface::AppSrc declares these push and control operations:

virtual expected<void> pushRawFrame(cbuffer image, cmap const& metadata) = 0;
virtual expected<void> pushRawFrame(
    void const* buffer,
    int width,
    int height,
    iface::SolutionManager::RawFrameType type,
    std::chrono::milliseconds timestamp,
    cmap const& metadata
) = 0;
virtual expected<void> pushEncodedFrame(
    unsigned char const* data,
    size_t dataSize,
    iface::SolutionManager::EncodingType type,
    std::chrono::milliseconds timestamp
) = 0;
virtual expected<void> setEncodedFrameParameters(
    int /*width*/, int /*height*/, int /*displayWidth*/, int /*displayHeight*/
) { return {}; }
virtual int getQueueSize() = 0;
virtual void setTargetFps(int fps) = 0;
virtual void setMaxPixels(int pixels) = 0;

The raw-pointer overload requires metadata. setEncodedFrameParameters is optional in the base interface: its default implementation returns success. The AppSrc handler implements it to provide geometry for its own push path. The release source copies raw BGR, NV12, and YV12 data into RT buffers; do not rely on a zero-copy guarantee from this interface.

Examples

The caller obtains iface::AppSrc through its owning application. That lookup is application-specific and is deliberately not inferred here.

cmap metadata;
auto result = appsrc.pushRawFrame(
    bgr.data,
    bgr.cols,
    bgr.rows,
    iface::SolutionManager::RawFrameType::BGR,
    std::chrono::milliseconds(1000),
    metadata
);

Supply dimensions before the first encoded frame when the decoder cannot derive them from the bitstream.

RT_TRY(appsrc.setEncodedFrameParameters(1920, 1080, 1920, 1080));
RT_TRY(appsrc.pushEncodedFrame(
    nalData.data(),
    nalData.size(),
    iface::SolutionManager::EncodingType::H264,
    std::chrono::milliseconds(frameNumber * 40)
));

Lua

The pinned source has no AppSrc Lua binding. Push frames through C++; do not infer a Lua appsrc:// configuration contract from this page.

Validation

Test the complete owner path with representative raw and encoded input on the release-pinned runtime. Record queue-full, stopped-instance, decoder, and timing outcomes for the target deployment. See Plugin source and runtime validation for the coverage procedure.