Frames¶

Frames encapsulate all data and signals that flow through a pipeline. The base class is Limef::frame::Frame; subclasses are identified by Limef::frame::FrameClass.

namespace frame¶

Frames encapsulate data and signals.

Enums

enum class BufferLocation¶

Location of frame buffer memory (authoritative — set explicitly, never inferred)

Every DecodedFrame carries a bufferlocation_ member that is the single source of truth for where pixel data lives. Whoever creates or transforms a frame is responsible for setting it via setBufferLocation(). updateFrom() sets it on the destination frame after completing the transfer.

Frames are always emitted as CPU or CUDA — DMA-buf fds are consumed internally by V4L2NVDecoder and ArgusCameraThread before any frame reaches downstream filters.

Values:

enumerator CPU¶: System RAM (AV_PIX_FMT_NV12 / YUV420P / etc.)

enumerator VAAPI¶: GPU via ffmpeg hw_frames_ctx / VAAPI device.

enumerator CUDA_FFMPEG¶: GPU via ffmpeg hw_frames_ctx / CUDA device (FFmpeg hw decoder output)

enumerator CUDA¶: GPU via plain cudaMalloc — no hw_frames_ctx, data[0]/[1] are device ptrs.

enumerator Vulkan¶: GPU via ffmpeg hw_frames_ctx / Vulkan device.

enum class FrameClass¶

Frame type identifier.

FrameClass identifies the type of frame. It is used by Frame and inherited classes to identify themselves and to do pointer casting to the correct subclass of Frame.

Values:

enumerator Null¶: identifies test frame class NullFrame

enumerator Packet¶: identifies class PacketFrame

enumerator Codec¶: identifies class CodecFrame

enumerator Decoded¶: identifies class DecodedFrame

enumerator Signal¶: identifies class SignalFrame

enumerator Raw¶: identifies class RawFrame

enumerator Info¶: identifies class InfoFrame

enumerator Stream¶: identifies class StreamFrame (raw/decoded stream info for encoders)

enumerator SDP¶: identifies class SDPFrame (SDP for RTSP)

enumerator RTP¶: identifies class RTPFrame (RTP/RTCP packets)

enumerator Tensor¶: identifies class TensorFrame (general N-plane tensor, CPU or GPU)

enum class DType¶

Element type for a TensorFrame plane.

Values:

enumerator UInt8¶

enumerator UInt16¶

enumerator Int16¶

enumerator Float16¶

enumerator Int32¶

enumerator Float32¶

enumerator Float64¶

Functions

inline const char *bufferLocationName(BufferLocation loc)¶

inline size_t alignSize(size_t size, size_t alignment = 32)¶

Align a size to the specified boundary. Used by some frame classes to de/serialize data.

Parameters:

size – Size to align
alignment – Alignment boundary (must be power of 2). Default: 32 bytes = ffmpeg’s default alignment

Returns:

size_t Aligned size

static void computeContiguousStrides(int ndim, const int64_t *shape, size_t elem_size, int64_t *strides)¶: Compute C-contiguous (row-major) strides for the given shape and element size.

static size_t contentBytes(int ndim, const int64_t *shape, DType dtype)¶: Total content bytes for a contiguous plane: shape[0] * strides[0].

inline size_t dtypeSize(DType dtype) noexcept¶: Bytes per element for a given DType.

inline const char *dtypeName(DType dtype) noexcept¶

Variables

static constexpr int TENSOR_MAX_PLANES = 4¶

static constexpr int TENSOR_MAX_DIMS = 4¶

class CodecFrame : public Limef::frame::Frame ¶

#include <codecframe.h>

A frame containing stream information for decoders.

Manages an internal AVFormatContext and AVStreams and contains minimal stream information required by decoders:

Codec parameters
Time base
Frame rates

Downstream decoders use this information to initialize their decoder contexts.

Subclassed by Limef::frame::StreamFrame

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

virtual void reset() override¶: Resets the state of the frame (if any)

virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

virtual void updateFrom(const Frame *other_) override¶: Updates the current frame (copy operation) using the input frame.

virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

void addStream(const AVStream *src)¶

Add a stream to internal format context.

Copies essential stream information:

Codec parameters
Time base
Frame rates

Parameters:: src – Source stream to copy from
Throws:: std::runtime_error – on allocation or copy failure

void addStreamFromCodecParams(const AVCodecParameters *params, AVRational timebase, AVRational framerate, int stream_index = 0)¶

Add a stream from codec parameters (for encoder output)

Creates a synthetic stream from just AVCodecParameters. Used when an encoder produces codec info that downstream decoders need.

Parameters:

params – Codec parameters (from encoder’s getCodecParams())
timebase – Time base for the stream (e.g., {1, 1000000} for microseconds)
framerate – Frame rate (e.g., {30, 1} for 30fps)
stream_index – Index for this stream (default 0)

Throws:

std::runtime_error – on allocation or copy failure

bool updateExtradata(int stream_index, const uint8_t *extradata, size_t extradata_size)¶

Update extradata for a stream.

Updates just the extradata for an existing stream without rebuilding the entire CodecFrame. Useful when extradata is extracted from the bitstream after the initial CodecFrame was created.

Parameters:

stream_index – Index of the stream to update
extradata – Pointer to extradata bytes
extradata_size – Size of extradata in bytes

Returns:

true if update succeeded, false if stream not found

const AVStream *getVideoStream() const¶

Get the video stream if present.

Returns:: const AVStream* Pointer to video stream or nullptr if not found

inline std::chrono::microseconds getVideoFrameDuration() const¶

Get the video frame duration.

Returns the cached frame duration calculated from the video stream’s avg_frame_rate when addStream() was called. Returns 0 if no video stream.

Returns:: Frame duration in microseconds

inline const AVFormatContext *getFormatContext() const¶

Get the internal format context.

Returns:: const AVFormatContext* Pointer to format context

inline AVFormatContext *getFormatContextMutable()¶: Mutable version.

class DecodedFrame : public Limef::frame::Frame ¶

#include <decodedframe.h>

Frame containing either decoded video, audio data or both.

A unified frame class for handling both decoded video and audio frames. Contains two pre-allocated AVFrames that adapt to the maximum required size for their respective media types. Works with the FrameFifo pre-allocated stack system for efficient memory management.

Has both video and audio interal AVFrame’s of which either one is active.

Usage example:

DecodedFrame* frame = framefifo.getFrame();

// For video
if (frame->reserveVideo(1920, 1080, AV_PIX_FMT_YUV420P)) {
    // frame ready for video data
}

// For audio
if (frame->reserveAudio(44100, 2, AV_SAMPLE_FMT_S16, 1024)) {
    // frame ready for audio data
}

// Switch frame mode to video:
frame->setMediaType(MediaType::Video)

Public Types

enum class MediaType¶

Type of media contained in the frame.

Values:

enumerator Undef¶: Frame not initialized or reset.

enumerator Video¶: Frame contains video data.

enumerator Audio¶: Frame contains audio data.

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

virtual void reset() noexcept override¶

Reset frame for reuse from stack.

Keeps memory allocated but resets internal state. Both video and audio frames are kept but marked as unused.

virtual Frame *clone() const override¶

Create a new frame for stack allocation.

Returns:: Frame* New DecodedFrame instance

virtual void updateFrom(const Frame *other) override¶

Copy data from another frame.

Called when frame is pulled from stack. Reuses existing memory when possible, growing buffers if needed.

Parameters:: other – Source frame to copy from

virtual std::string dump() const override¶

Create string representation of frame state.

Returns:: std::string Frame information

inline MediaType getMediaType() const noexcept¶: Return current active MediaType of the frame.

inline void setMediaType(MediaType media_type_)¶: Set current active MediaType of the frame.

inline int getWidth() const noexcept¶: If current active type is video, return video width

inline int getHeight() const noexcept¶: If current active type is video, return video height

inline AVPixelFormat getVideoFormat() const noexcept¶: If current active type is video, return video format

inline bool isHWFrame() const noexcept¶: If current active type is video, return true if it is a hardware frame/format

inline BufferLocation getBufferLocation() const noexcept¶: Get the authoritative buffer location for this frame.

inline void setBufferLocation(BufferLocation loc) noexcept¶: Set the buffer location — caller must ensure AVFrame state is consistent.

inline bool isOnCPU() const noexcept¶: Check if frame data is in CPU-accessible memory.

inline bool isOnGPU() const noexcept¶: Check if frame data is on GPU (not CPU-accessible without a transfer)

void setupNVDECCPUView(int width, int height, uint8_t *y_ptr, uint8_t *uv_ptr, size_t y_sz)¶

Set up frame as a non-owning CPU NV12 view into pre-mapped NVMM memory.

Used by V4L2NVDecoder’s EXPBUF-at-setup path: CAPTURE slot CPU pointers are established once in setupCapture() and outlive individual frames. The V4L2NVDecoder owns the memory — this frame holds a no-op AVBufferRef so that AVFrame reference-counting does not free the mapping on unref.

Pointers remain valid until V4L2NVDecoder re-queues the slot via the next status() call (hold/release contract validated in playground/jetson/2/).

Parameters:

width – Frame width
height – Frame height
y_ptr – Pre-mapped Y-plane CPU pointer (owned by V4L2NVDecoder)
uv_ptr – Pre-mapped UV-plane CPU pointer (owned by V4L2NVDecoder)
y_sz – Y-plane size in bytes

void setupArgusCPUView(int width, int height, uint8_t *y_ptr, uint8_t *uv_ptr, int y_pitch, int uv_pitch)¶

Non-owning CPU NV12 view into a pre-mapped pitch-linear NvBufSurface.

Used by ArgusCameraThread after copyToNvBuffer + NvBufSurfaceSyncForCpu. ArgusCameraThread owns the NvBufSurface mapping for the stream lifetime. Pitch comes from planeParams.pitch[] (may differ from width due to alignment).

Parameters:

width – Frame width in pixels
height – Frame height in pixels
y_ptr – Pre-mapped Y-plane CPU pointer
uv_ptr – Pre-mapped UV-plane CPU pointer
y_pitch – Y-plane row stride in bytes
uv_pitch – UV-plane row stride in bytes

bool setupCPUNvBufVideo(int width, int height, int dma_fd, size_t nv12_size)¶

Set up frame as CPU NV12 from a NvBuf dma-buf fd (mmap, zero-copy).

mmaps the fd into userspace, sets data[0]/[1] directly into the mmap’d region, and attaches a custom AVBufferRef destructor that calls munmap + close. No pixel copy — the mmap IS the AVFrame buffer.

Caller must NOT close dma_fd after this call.

Parameters:

width – Frame width
height – Frame height
dma_fd – DMA-buf fd (ownership transferred)
nv12_size – Total NV12 size in bytes (width * height * 3 / 2)

Returns:

true on success

const uint8_t *getCPUData(int plane = 0) const¶

Get CPU-accessible data for a plane.

For CPU frames, returns the data directly. For GPU frames, triggers a copy to CPU cache on first call, then returns cached data.

Parameters:: plane – Plane index (0 for Y, 1 for U, 2 for V in YUV)
Returns:: Pointer to plane data, or nullptr if unavailable

AVPixelFormat getCPUFormat() const¶

Get the pixel format of the CPU-accessible data.

For CPU frames returns the frame’s own format (e.g. AV_PIX_FMT_YUV420P). For GPU frames (VAAPI, CUDA) returns the format of the downloaded CPU cache (e.g. AV_PIX_FMT_NV12 for VAAPI, AV_PIX_FMT_NV12 for NVDEC). Returns AV_PIX_FMT_NONE if the frame is unavailable or the download fails.

Always call materializeToCPU() or getCPUData() first for GPU frames.

int getCPULinesize(int plane = 0) const¶

Get the row stride for a CPU-accessible plane.

Mirrors getCPUData(): for CPU frames returns the AVFrame linesize directly; for GPU frames triggers a download and returns the cache’s linesize. Returns 0 if the plane is unavailable or the download fails.

Parameters:: plane – Plane index (0=Y, 1=U, 2=V for YUV)

bool materializeToCPU()¶

Explicitly copy frame data from GPU to CPU.

After this call, getCPUData() will return valid CPU pointers.

Returns:: true if materialization succeeded or frame already on CPU

inline int getSampleRate() const noexcept¶: If current active type is audio, return sample rate

inline const AVChannelLayout *getChannelLayout() const noexcept¶: If current active type is audio, return channel layout

inline AVSampleFormat getAudioFormat() const noexcept¶: If current active type is audio, return sample fmt

inline void setTimeBase(const AVRational &tb) noexcept¶: Set the timebase of this frame’s timestamps

inline AVRational getTimeBase() const noexcept¶: Get the timebase of this frame’s timestamps

inline bool hasPTS() const noexcept¶: Returns true if the frame has a valid PTS (i.e. pts != AV_NOPTS_VALUE and timebase is set).

std::chrono::microseconds getTimestamp() const noexcept¶: Returns the active frame’s PTS in microseconds (rescaled via time_base)

void setTimestamp(std::chrono::microseconds ts) noexcept¶: Sets the active frame’s PTS from microseconds (rescaled via time_base)

inline const AVFrame *getFrame() const noexcept¶

Get currently active frame.

Returns:: const AVFrame* Either video or audio frame based on media_type

bool reserveVideo(int width, int height, AVPixelFormat format, AVBufferRef *hw_ctx = nullptr)¶

Reserve space for video frame.

Allocates or reuses memory for video frame. Sets media type to Video on success.

Parameters:

width – Frame width
height – Frame height
format – Pixel format
hw_ctx – Hardware context (nullptr for SW frames)

Returns:

true if allocation successful

bool reserveAudio(int sample_rate, const AVChannelLayout &ch_layout, AVSampleFormat format, int nb_samples)¶

Reserve space for audio frame.

Parameters:

sample_rate – Audio sample rate
ch_layout – Channel layout
format – Sample format
nb_samples – Number of samples per channel

Returns:

true if allocation successful

virtual size_t serialize(uint8_t *buffer, size_t buffer_size) override¶

Serialize frame to a byte buffer with memory alignment.

Produces a buffer with aligned data suitable for memory mapping

Writes all data it can - the return value indicates the number of bytes that would have been required to write all data

Parameters:

buffer – Output buffer to hold serialized data
buffer_size – Size of the provided output buffer

virtual bool deserialize(const uint8_t *buffer, size_t buffer_size) override¶

Deserialize frame from a byte buffer.

Parameters:

buffer – Input buffer containing serialized data
buffer_size – Size of the provided input

inline bool hasOverflow() const noexcept¶

Check if overflow was detected during the last deserialization.

This flag is set during deserialization if the buffer didn’t contain enough data for the complete frame.

Returns:: true If overflow was detected
Returns:: false If no overflow was detected

class Frame¶

#include <frame.h>

Frame base class.

Frame class uses intentionally raw pointers, not unique or shared pointers. The object lifetime is managed by the FrameFifo class. Frame subclasses are used to encapsulate almost anything:

Payload packets
Decoded frames (bitmap and raw audio)
FFMpeg’s AVFormatContext to inform downstream threads and framefilters about the stream
Signals to inform downstream framefilters and threads about their tasks
etc.

FrameFifo subclasses typically make copies of frames for downstream using the (1) Frame::updateFrom method or with the (2) Frame::clone` method.

(1) copies data between existing frames, always trying to minimize memory (re)allocations. Think if it as a “delta” copying: apply just a delta to modify the target frame.

(2) uses the copy constructor to create a new frame and reserves memory from scratch.

The = operator (3) is a copy-operator like (1), but is more carefree: i.e. just copies from source to target without caring much about the efficiency / if there are mem reallocs.

On many occacions, (1) may just internally use (3).

For each subclass, you also need to define a static method called staticFrameClass() that is used in Frame::as to identify the frame:

static FrameClass staticFrameClass() { return FrameClass::Null; }

Subclassed by Limef::frame::CodecFrame, Limef::frame::DecodedFrame, Limef::frame::InfoFrame, Limef::frame::NullFrame, Limef::frame::PacketFrame, Limef::frame::RTPFrame, Limef::frame::RawFrame, Limef::frame::SDPFrame, Limef::frame::SignalFrame, Limef::frame::TensorFrame

Public Functions

virtual FrameClass getFrameClass() const noexcept = 0¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

virtual void reset() = 0¶: Resets the state of the frame (if any)

virtual Frame *clone() const = 0¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

inline Slot getSlot() const noexcept¶: Get slot value.

inline void setSlot(const Slot slot_) noexcept¶: Set slot value.

virtual std::string dump() const = 0¶: Returns a one-liner string representation of the frame.

inline virtual bool deserialize(const uint8_t *buffer, size_t buffer_size)¶: Serialize frame into bytes.

template<typename T> inline T *as()¶

Deserialize frame from bytes.

Test and typecast to correct frame type

Tests if this frame is the frame class as suggested by the template parameter, i.e:

const CodecFrame* codec_frame = frame->as<CodecFrame>()

inline virtual void updateFrom(const Frame *other)¶: Updates the current frame (copy operation) using the input frame.

Public Static Functions

static inline void setLogger(std::shared_ptr<spdlog::logger> logger_instance)¶

Set the logger for all Frame classes.

Parameters:: logger_instance – Logger to use

static inline void setLogLevel(spdlog::level::level_enum level)¶

Set the log level for the Frame logger.

Parameters:: level – Log level to set

static inline std::shared_ptr<spdlog::logger> getLogger()¶

Get the current logger instance.

Returns:: std::shared_ptr<spdlog::logger> Current logger

class InfoFrame : public Limef::frame::Frame ¶

#include <infoframe.h>

Frame for carrying diagnostic/status messages.

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

inline virtual void reset() noexcept override¶: Resets the state of the frame (if any)

inline virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

virtual void updateFrom(const Frame *other_) override¶: Updates the current frame (copy operation) using the input frame.

virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

class NullFrame : public Limef::frame::Frame ¶

#include <frame.h>

A dummy / placeholder frame class.

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

inline virtual void reset() noexcept override¶: Resets the state of the frame (if any)

inline virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

inline virtual void updateFrom(const Frame *other) override¶: Updates the current frame (copy operation) using the input frame.

inline virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

class PacketFrame : public Limef::frame::Frame ¶

#include <packetframe.h>

A Frame object encapsulating an FFmpeg AVPacket.

PacketFrame represents a demuxed video stream and encapsulates an AVPacket structure.

AVPacket encapsulates the payload and various metadata resulting from the demuxing process.

Copy ctor and operator take care of the proper copying of the underlying AVPacket. So does PacketFrame::updateFrom.

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

virtual void reset() noexcept override¶: Resets the state of the frame (if any)

virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

virtual void updateFrom(const Frame *other) override¶: Updates the current frame (copy operation) using the input frame.

std::chrono::microseconds getTimestamp() const noexcept¶: Returns internal AVPacket PTS timestamp in microseconds.

std::chrono::microseconds getDTSTimestamp() const noexcept¶: Returns internal AVPacket DTS timestamp in microseconds.

void setTimestamp(std::chrono::microseconds ts) noexcept¶: Sets internal AVPacket timestamp in microseconds.

virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

inline const AVPacket *getPacket() const noexcept¶: Returns the internal AVPacket.

inline AVPacket *getPacketMutable() const noexcept¶: Returns the internal AVPacket.

void setPacket(const AVPacket *src)¶: Sets the internal AVPacket.

void setData(const uint8_t *data, int size, bool shrink = false)¶: Set AVPacket’s payload data.

std::string dumpFirstNBytes(size_t n) const¶: Returns a string that peeks into AVPacket’s payload data.

std::string dumpPacketInfo(size_t bytesToDump = 16) const¶: Returns a string that dymps first n bytes of AVPacket’s payload.

inline bool isKey() const noexcept¶: This works for both AVCC and Annex-B type streams: it marks the start of a sequence If this is true and the stream is Annex-B, then it contains sps+pps+iframe Otherwise just iframe

int annexBOffset() const noexcept¶: Returns the Annex B start-code length (3 or 4) if the packet begins with a start code, or 0 if the packet is in AVCC (length-prefixed) format or empty.

inline bool isAnnexB() const noexcept¶: Returns true if the packet is in Annex B byte-stream format.

bool isSPS() const noexcept¶: Returns true if any NAL unit in this packet is a Sequence Parameter Set (H.264 type 7 / H.265 type 33). Works for both Annex B and AVCC formats.

bool isPPS() const noexcept¶: Returns true if any NAL unit in this packet is a Picture Parameter Set (H.264 type 8 / H.265 type 34). Works for both Annex B and AVCC formats.

bool isVPS() const noexcept¶: Returns true if any NAL unit in this packet is a Video Parameter Set (H.265 type 32 only). Always false for non-H.265 codecs.

inline bool hasPTS() const noexcept¶: Returns true if the packet has a valid PTS (i.e. pts != AV_NOPTS_VALUE and timebase is set).

inline void setMediaType(AVMediaType type) noexcept¶: Set the media type of this packet

inline void setTimeBase(const AVRational &tb) noexcept¶: Set the timebase of this packet’s timestamps

inline AVRational getTimeBase() const noexcept¶: Get the timebase of this packet’s timestamps

inline AVMediaType getMediaType() const noexcept¶: Get the media type of this packet

inline bool isVideo() const noexcept¶: Convenience method: check if the packet is video

inline bool isAudio() const noexcept¶: Convenience method: check if the packet is audio

struct Plane¶

#include <tensorframe.h>

One plane of a TensorFrame.

Either CPU-only (data_ set, d_data_ nullptr) or GPU-only (d_data_ set, data_ nullptr). Mixed CPU+GPU in the same plane is not supported.

Fields are intentionally public — consumers read them directly without getters, just as with AVFrame::data[] / linesize[].

Public Functions

inline size_t contentBytes() const noexcept¶

Total content bytes: shape[0] * strides[0].

For contiguous planes this equals elementSize * product(shape). Returns 0 if the plane is empty (ndim == 0).

Public Members

uint8_t *data_ = nullptr¶: CPU pointer (nullptr if GPU-only)

uint8_t *d_data_ = nullptr¶: GPU device pointer (nullptr if CPU-only)

int64_t shape[TENSOR_MAX_DIMS] = {}¶: Logical dimensions (active: shape[0..ndim-1])

int64_t strides[TENSOR_MAX_DIMS] = {}¶: Byte strides per dimension (C-contiguous by default)

int ndim = 0¶: Number of active dimensions.

DType dtype = DType::UInt8 ¶: Element type.

size_t nbytes = 0¶: Allocated bytes (grow-only — never shrinks)

int device_id = 0¶: CUDA device id (ignored for CPU planes)

class RawFrame : public Limef::frame::Frame ¶

#include <rawframe.h>

Frame containing raw muxed stream data.

Encapsulates raw bytes from a muxed media stream. This can be used for both pre-muxed input streams and muxer outputs. The frame simply holds a buffer of bytes without interpreting them - the actual interpretation is done by muxers/demuxers.

Example usage:

RawFrame frame;
frame.setData(buffer, size);  // Copy data from buffer

// Get pointer to internal data
const uint8_t* data = frame.getData();
size_t size = frame.getSize();

Public Types

enum class DataFormat¶

Data format types for raw frame content.

Used to identify the type of data contained in the frame for proper interpretation by receivers.

Values:

enumerator UNKNOWN¶

enumerator H264¶

enumerator H265¶

enumerator AAC¶

enumerator JPEG¶

enumerator MP4¶

enumerator MPEGTS¶

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

virtual void reset() noexcept override¶: Resets the state of the frame (if any)

virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

virtual void updateFrom(const Frame *other) override¶: Updates the current frame (copy operation) using the input frame.

virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

void setData(const uint8_t *data, size_t size, bool shrink = false)¶

Set frame data content.

Copies data into internal buffer. If current capacity is insufficient, buffer will be reallocated unless shrink is false.

Parameters:

data – Source data pointer
size – Size of data in bytes
shrink – If true, buffer will be shrunk if significantly larger than needed

inline const uint8_t *getData() const noexcept¶: Get pointer to internal data buffer.

inline size_t getSize() const noexcept¶: Get current data size in bytes.

inline size_t getCapacity() const noexcept¶: Get allocated buffer capacity.

std::string peekBytes(size_t n) const¶

Peek at first N bytes of data.

Useful for debugging and logging.

Parameters:: n – Number of bytes to peek at
Returns:: std::string Hexadecimal representation of bytes

DataFormat getDataFormat() const noexcept¶

Get the data format.

Returns:: DataFormat Format of the contained data

void setDataFormat(DataFormat format)¶

Set the data format.

Parameters:: format – Format of the contained data

virtual size_t serialize(uint8_t *buffer, size_t buffer_size) override¶

Serialize frame to a byte buffer with memory alignment.

Produces a buffer with aligned data suitable for memory mapping

Writes all data it can - the return value indicates the number of bytes that would have been required to write all data

Parameters:

buffer – Output buffer to hold serialized data
buffer_size – Size of the provided output buffer

virtual bool deserialize(const uint8_t *buffer, size_t buffer_size) override¶

Deserialize frame from a byte buffer.

Parameters:

buffer – Input buffer containing serialized data
buffer_size – Size of the provided input

inline bool hasOverflow() const noexcept¶

Check if overflow was detected during the last deserialization.

This flag is set during deserialization if the buffer didn’t contain enough data for the complete frame.

Returns:: true If overflow was detected
Returns:: false If no overflow was detected

class RTPFrame : public Limef::frame::Frame ¶

#include <rtpframe.h>

Frame containing RTP or RTCP packet data.

Used to carry individual RTP/RTCP packets from RTPMuxerFrameFilter to RTSPServerThread / WebRTCServerThread for transmission to clients.

This is very similar to RawFrame: just raw muxed bytes, but it carries some metadata set by the RTPMuxerFrameFilter.

One RTP packet is typically a small fragment of, say, sps+pps+iframe (if annex b) blob, or b-frame, or whatever. RTP receivers don’t mind if the first byte blob they get is a part of a b-frame, i.e. midstream/frame.

However, it’s better if the stream is self-contained, i.e. Annex-B = sps and pps come self-contained in the stream always together with the iframe.

Example usage:

RTPFrame rtp;
rtp.setData(packet_bytes, packet_size);
rtp.setTrackIndex(0);  // video track
rtp.setPacketType(RTPFrame::PacketType::RTP);
pass(&rtp);

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

virtual void reset() noexcept override¶: Resets the state of the frame (if any)

inline virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

virtual void updateFrom(const Frame *other) override¶: Updates the current frame (copy operation) using the input frame.

virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

void setData(const uint8_t *data, size_t size, bool shrink = false)¶

Set packet data.

Copies data into internal buffer. Buffer grows as needed but doesn’t shrink unless explicitly requested.

inline const uint8_t *getData() const noexcept¶: Get pointer to internal data buffer.

inline size_t getSize() const noexcept¶: Get current data size in bytes.

inline size_t getCapacity() const noexcept¶: Get allocated buffer capacity.

inline PacketType getPacketType() const noexcept¶: Get packet type (RTP or RTCP)

inline void setPacketType(PacketType t) noexcept¶: Set packet type.

inline int getTrackIndex() const noexcept¶: Get track index (0=video, 1=audio, etc.)

inline void setTrackIndex(int idx) noexcept¶: Set track index.

inline bool isSeqStart() const noexcept¶

True if this is the first RTP packet of a new access unit.

Set on the first writeCallback per av_write_frame() call. Use this to gate new-client delivery: wait until isSeqStart() before sending to a late-joining peer, avoiding mid-frame delivery. Not set for RTCP packets.

inline void setSeqStart(bool s) noexcept¶: Set sequence-start flag.

std::string peekBytes(size_t n) const¶: Peek at first N bytes of data (for debugging)

class SDPFrame : public Limef::frame::Frame ¶

#include <sdpframe.h>

Frame containing SDP (Session Description Protocol) data.

Used to pass SDP information downstream, typically from RTPMuxerFrameFilter to RTSPServerThread for DESCRIBE responses.

Example usage:

SDPFrame sdp;
sdp.setSDP("v=0\r\no=- ...\r\n");
sdp.setSlot(1);
pass(&sdp);

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

inline virtual void reset() noexcept override¶: Resets the state of the frame (if any)

inline virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

virtual void updateFrom(const Frame *other) override¶: Updates the current frame (copy operation) using the input frame.

virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

inline const std::string &getSDP() const noexcept¶: Get the SDP string.

inline void setSDP(const std::string &sdp)¶: Set the SDP string.

class SignalFrame : public Limef::frame::Frame ¶

#include <signalframe.h>

Encapsulates Signal objects.

Encapsulates signals that can be passed to Thread’s and FrameFilters.

Public Functions

inline explicit SignalFrame(const Limef::signal::Signal &signal)¶

Default ctor.

Parameters:: signal – a Signal carried by this frame

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

inline virtual void reset() noexcept override¶: Resets the state of the frame (if any)

inline virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

virtual void updateFrom(const Frame *other) override¶: Updates the current frame (copy operation) using the input frame.

virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

inline const Limef::signal::Signal &getSignal() const¶: Get the signal carried by this frame.

template<typename T> inline const T *asSignal() const¶

Returns and casts to correct signal type.

Returns the signal carried by this frame, casted to the type implied by the template type:

const auto* basicSignal = signalFrame->template asSignal<BasicSignal>()

If the signal is not of the desired type, returns nullptr.

class StreamFrame : public Limef::frame::CodecFrame ¶

#include <streamframe.h>

A frame containing stream information for raw/decoded sources.

StreamFrame is a subclass of CodecFrame, used to carry stream metadata from raw or decoded sources to downstream encoders.

While CodecFrame carries encoded stream info (codec parameters, extradata) for decoders, StreamFrame carries raw stream info (dimensions, format, timing) for encoders.

The distinction allows the pipeline to detect misrouted frames:

DecodingFrameFilter expects CodecFrame (encoded stream)
EncodingFrameFilter expects StreamFrame (raw/decoded stream)

Internally uses the same AVFormatContext/AVStream mechanism as CodecFrame, but the codec_id will typically be AV_CODEC_ID_RAWVIDEO or AV_CODEC_ID_PCM_*.

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

inline virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

inline virtual void updateFrom(const Frame *other_) override¶: Updates the current frame (copy operation) using the input frame.

virtual bool deserialize(const uint8_t *buffer, size_t buffer_size) override¶: Serialize frame into bytes.

inline virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

class TensorFrame : public Limef::frame::Frame ¶

#include <tensorframe.h>

General-purpose multi-plane tensor frame, decoupled from FFmpeg.

Planes are reserved explicitly with reserveCPUPlane() / reserveGPUPlane(). Memory is grow-only — buffers are reused across frames of the same or smaller size, reallocated only when a larger frame arrives.

Public Functions

inline virtual FrameClass getFrameClass() const noexcept override¶

Return Frame’s type.

Return’s Frame’s Limef::FrameClass that can be used to identify the subclass of the Frame. You can use it like this:

frame->getFrameClass() == FrameClass::Packet

virtual void reset() noexcept override¶: Resets the state of the frame (if any)

virtual Frame *clone() const override¶: Returns a cloned frame. Implement carefully! Is used extensively by Limef::FrameFifo.

virtual void updateFrom(const Frame *other) override¶: Updates the current frame (copy operation) using the input frame.

virtual std::string dump() const override¶: Returns a one-liner string representation of the frame.

bool reserveCPUPlane(int plane_idx, int ndim, const int64_t *shape, DType dtype)¶

Allocate or reuse a CPU plane.

Allocates a contiguous (C-order) buffer large enough for the given shape and dtype. Grow-only: if the existing buffer is already large enough, it is reused and only the metadata is updated.

Parameters:

plane_idx – Index of plane to allocate (0 .. TENSOR_MAX_PLANES-1)
ndim – Number of dimensions
shape – Array of ndim dimension sizes
dtype – Element type

Returns:

true on success

Public Members

Plane planes[TENSOR_MAX_PLANES]¶: Plane array — read/write access.