C++ API Reference¶

Core C++ API for MediaX video streaming.

Stream Information¶

The StreamInformation structure defines stream parameters:

#include "rtp/rtp.h"

struct mediax::rtp::StreamInformation {
    std::string session_name;     // Stream name for SAP
    std::string hostname;         // Multicast address or IP
    uint16_t port;                // UDP port
    uint32_t width;               // Frame width in pixels
    uint32_t height;              // Frame height in pixels
    uint32_t framerate;           // Frames per second
    ColourspaceType encoding;     // Colorspace/codec type
};

Colorspace Types¶

enum class mediax::rtp::ColourspaceType {
    kColourspaceRgb24,      // 24-bit RGB
    kColourspaceYuv422,     // YCbCr 4:2:2 (UYVY)
    kColourspaceMono8,      // 8-bit grayscale
    kColourspaceMono16,     // 16-bit grayscale
    kColourspaceH264Part10, // H.264/AVC
    kColourspaceH265,       // H.265/HEVC
    kColourspaceAv1,        // AV1
    kColourspaceJpeg2000,   // JPEG 2000
};

Payloader Classes¶

Uncompressed Payloader¶

#include "uncompressed/rtp_uncompressed_payloader.h"

class mediax::rtp::uncompressed::RtpUncompressedPayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    bool Transmit(const uint8_t* data, bool blocking = true);
};

H.264 VAAPI Payloader¶

#include "h264/vaapi/rtp_h264_vaapi_payloader.h"

class mediax::rtp::h264::vaapi::RtpH264VaapiPayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    bool Transmit(const uint8_t* data, bool blocking = true);
};

H.265 VAAPI Payloader¶

#include "h265/vaapi/rtp_h265_vaapi_payloader.h"

class mediax::rtp::h265::vaapi::RtpH265VaapiPayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    bool Transmit(const uint8_t* data, bool blocking = true);
};

AV1 Payloader¶

#include "av1/vaapi/rtp_av1_vaapi_payloader.h"

class mediax::rtp::av1::vaapi::RtpAv1VaapiPayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    bool Transmit(const uint8_t* data, bool blocking = true);
};

Depayloader Classes¶

Uncompressed Depayloader¶

#include "uncompressed/rtp_uncompressed_depayloader.h"

class mediax::rtp::uncompressed::RtpUncompressedDepayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    void Start();
    void Stop();
    bool Receive(uint8_t* data, int timeout_ms = 0);
    void RegisterCallback(std::function<void(const RtpFrameData&)> callback);
};

H.264 VAAPI Depayloader¶

#include "h264/vaapi/rtp_h264_vaapi_depayloader.h"

class mediax::rtp::h264::vaapi::RtpH264VaapiDepayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    void Start();
    void Stop();
    bool Receive(uint8_t* data, int timeout_ms = 0);
    void RegisterCallback(std::function<void(const RtpFrameData&)> callback);
};

H.265 VAAPI Depayloader¶

#include "h265/vaapi/rtp_h265_vaapi_depayloader.h"

class mediax::rtp::h265::vaapi::RtpH265VaapiDepayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    void Start();
    void Stop();
    bool Receive(uint8_t* data, int timeout_ms = 0);
    void RegisterCallback(std::function<void(const RtpFrameData&)> callback);
};

AV1 Depayloader¶

#include "av1/vaapi/rtp_av1_vaapi_depayloader.h"

class mediax::rtp::av1::vaapi::RtpAv1VaapiDepayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    void Start();
    void Stop();
    bool Receive(uint8_t* data, int timeout_ms = 0);
    void RegisterCallback(std::function<void(const RtpFrameData&)> callback);
};

Frame Data Structure¶

struct mediax::rtp::RtpFrameData {
    uint8_t* cpu_buffer;          // Pointer to frame data
    struct {
        uint32_t width;
        uint32_t height;
    } resolution;
    ColourspaceType encoding;
    uint32_t timestamp;
};

SAP Classes¶

SAP Announcer¶

#include "sap/sap_announcer.h"

class mediax::sap::SapAnnouncer {
public:
    void AddSapAnnouncement(const rtp::StreamInformation& info);
    void DeleteSapAnnouncement(const std::string& session_name);
    void DeleteAllSapAnnouncements();
    void Start();
    void Stop();
};

SAP Listener¶

#include "sap/sap_listener.h"

class mediax::sap::SapListener {
public:
    void Start();
    void Stop();
    const std::map<std::string, rtp::StreamInformation>& GetSapAnnouncements();
    void RegisterCallback(std::function<void(const rtp::StreamInformation&)> callback);
};

Codec Query Interface¶

Discover which codecs are compiled into the library and available at runtime.

CodecInfo Structure¶

#include "rtp/codec_query.h"

struct mediax::rtp::CodecInfo {
    std::string name;               // e.g. "H.264 VAAPI"
    std::string backend;            // e.g. "vaapi", "openh264", "nvenc"
    ColourspaceType colourspace;    // Codec type enum
    CodecDirection direction;       // kEncoder, kDecoder, or kBidirectional
    AccelerationType acceleration;  // kSoftware or kHardware
    bool compiled;                  // Compiled into this build
    bool available;                 // Hardware available at runtime
    std::string description;        // Human-readable description
};

Enumerations¶

enum class mediax::rtp::CodecDirection {
    kEncoder,       // Encode (payloader) only
    kDecoder,       // Decode (depayloader) only
    kBidirectional  // Both encode and decode
};

enum class mediax::rtp::AccelerationType {
    kSoftware,  // CPU / software-only codec
    kHardware   // Hardware-accelerated (GPU, ASIC, V4L2 M2M)
};

CodecQuery Class¶

#include "rtp/codec_query.h"

class mediax::rtp::CodecQuery {
public:
    // List all known backends (compiled and uncompiled)
    static std::vector<CodecInfo> GetCodecs();

    // Filter by direction
    static std::vector<CodecInfo> GetEncoders();
    static std::vector<CodecInfo> GetDecoders();

    // Filter by acceleration type
    static std::vector<CodecInfo> GetHardwareCodecs();
    static std::vector<CodecInfo> GetSoftwareCodecs();

    // Only compiled AND runtime-available backends
    static std::vector<CodecInfo> GetAvailableCodecs();

    // Filter by colourspace type
    static std::vector<CodecInfo> GetCodecsByColourspace(ColourspaceType type);

    // Quick check: is a named backend usable?
    static bool IsBackendAvailable(const std::string& backend);

    // Print formatted summary table
    static void PrintCodecSummary(std::ostream& os = std::cout);
};

Codec Query Examples¶

Print all available codecs:

#include "rtp/codec_query.h"

int main() {
    mediax::rtp::CodecQuery::PrintCodecSummary();
    return 0;
}

Output:

Codec                   Backend     Direction   Accel       Compiled  Available
--------------------------------------------------------------------------------
Uncompressed RGB24      uncompressed Both       Software    Yes       Yes
Uncompressed YUV422     uncompressed Both       Software    Yes       Yes
Uncompressed Mono8      uncompressed Both       Software    Yes       Yes
Uncompressed Mono16     uncompressed Both       Software    Yes       Yes
H.264 OpenH264          openh264    Both        Software    Yes       Yes
H.264 VAAPI             vaapi       Both        Hardware    Yes       Yes
H.265 VAAPI             vaapi       Both        Hardware    Yes       Yes
AV1 VAAPI               vaapi       Both        Hardware    Yes       Yes
H.264 NVENC Encoder     nvenc       Encoder     Hardware    No        No
H.264 NVDEC Decoder     nvenc       Decoder     Hardware    No        No

Choose a backend at runtime:

#include "rtp/codec_query.h"
#include <iostream>

void select_h264_encoder() {
    using namespace mediax::rtp;

    // Prefer hardware, fall back to software
    if (CodecQuery::IsBackendAvailable("vaapi")) {
        std::cout << "Using VAAPI hardware encoder\n";
        // Use RtpH264VaapiPayloader
    } else if (CodecQuery::IsBackendAvailable("nvenc")) {
        std::cout << "Using NVENC hardware encoder\n";
        // Use RtpH264NvencPayloader
    } else if (CodecQuery::IsBackendAvailable("openh264")) {
        std::cout << "Using OpenH264 software encoder\n";
        // Use RtpH264OpenH264Payloader
    } else {
        std::cerr << "No H.264 encoder available\n";
    }
}

List only hardware codecs:

auto hw = mediax::rtp::CodecQuery::GetHardwareCodecs();
for (const auto& c : hw) {
    std::cout << c.name << " - " << c.description
              << " [" << (c.available ? "ready" : "not available") << "]\n";
}

Find all H.264 backends:

auto h264 = mediax::rtp::CodecQuery::GetCodecsByColourspace(
    mediax::rtp::ColourspaceType::kColourspaceH264Part10);
for (const auto& c : h264) {
    std::cout << c.name << " (" << c.backend << ") "
              << (c.acceleration == mediax::rtp::AccelerationType::kHardware
                  ? "[HW]" : "[SW]")
              << "\n";
}

Complete Example¶

#include <iostream>
#include <vector>
#include "rtp/rtp.h"
#include "uncompressed/rtp_uncompressed_payloader.h"
#include "sap/sap_announcer.h"

int main() {
    // Configure stream
    mediax::rtp::StreamInformation stream_info;
    stream_info.session_name = "example-stream";
    stream_info.hostname = "239.192.1.1";
    stream_info.port = 5004;
    stream_info.width = 1920;
    stream_info.height = 1080;
    stream_info.framerate = 30;
    stream_info.encoding = mediax::rtp::ColourspaceType::kColourspaceRgb24;

    // Setup SAP announcer
    mediax::sap::SapAnnouncer announcer;
    announcer.AddSapAnnouncement(stream_info);
    announcer.Start();

    // Setup payloader
    mediax::rtp::uncompressed::RtpUncompressedPayloader payloader;
    payloader.SetStreamInfo(stream_info);
    payloader.Open();

    // Transmit frames
    std::vector<uint8_t> buffer(1920 * 1080 * 3);
    for (int i = 0; i < 100; ++i) {
        // Fill buffer with frame data...
        payloader.Transmit(buffer.data(), true);
    }

    // Cleanup
    payloader.Close();
    announcer.Stop();
    announcer.DeleteAllSapAnnouncements();

    return 0;
}

Linking¶

find_package(mediax REQUIRED)
target_link_libraries(your_app PRIVATE mediax::mediax)

Support¶

Website: https://astutesys.com/support
Email: [email protected]

Edit this page on GitHub