LFormat Reference Manual & Format Standards

LFormat.h is the format normalization core of the now2sdk framework. It establishes a uniform, hardware-agnostic standard for video dimensions, frame rates, pixel configurations, and audio channels.

Every processing module in the SDK—including playout engines (LFile), ingest devices (LLive), composition mixers (LMixer), switchers (LSwitcher), transcoders (LConvert), and encoders (LRecorder)—uses these format structures to align and process audio and video data.

1. Core Format Structures

🎥 videoFormatProps

This structure is used by developers to configure the target layout specifications for video streams. When applied, the SDK automatically resizes, pads, or converts color spaces to match these properties.

struct videoFormatProps {
    vF_Type setVideoFormat = vF_Disabled; // Target video standard enum
    int width = 0;                        // Custom width (used only when setVideoFormat = vF_Custom)
    int height = 0;                       // Custom height (used only when setVideoFormat = vF_Custom)
    double fps = 0.0;                     // Custom frame rate (used only when setVideoFormat = vF_Custom)
    cS_Type colorSpace = fcc_Default;     // Target pixel format/color space
};

🔊 audioFormatProps

This structure defines target normalization standards for audio streams (e.g., bit depth, sampling rates, and channel layouts).

struct audioFormatProps {
    aF_Type setAudioFormat = aF_Custom;   // Target audio standard enum
    int bitsPerSample = 0;                // Depth (e.g. 16, 24, 32. Negative values indicate float types: -32)
    int sampleRate = 0;                   // Sampling frequency in Hz (e.g. 48000, 44100)
    int channels = 0;                     // Number of channels (e.g. 2 for Stereo, 6 for 5.1 Surround)
};

📌 Physical Information Structs

These read-only structures represent the concrete physical properties parsed from standard enums:

struct videoProps {
    int width;
    int height;
    double fps;
    bool interlaced;
};

struct audioProps {
    int bitsPerSample;
    int sampleRate;
    int channels;
};

📌 Inline Parse Helpers

The SDK provides helper functions to instantly extract the underlying physical properties of standard enums:

// Returns the resolution, framerate, and scan type for a video standard
videoProps getVideoProps(vF_Type format);

// Returns sample size, sample rate, and channels for an audio standard
audioProps getAudioProps(aF_Type format);

2. Standard Format Enums

🎥 Video Standard Enums (vF_Type)

These enums represent broadcast and cinematic video standards. They can be parsed using getVideoProps():

🎨 Color Space Standards (cS_Type)

Used to configure target pixel arrays and formats:

🔊 Audio Standard Enums (aF_Type)

These enums configure target bit depth, sampling rates, and channel layouts:

3. Practical Code Examples

The following Qt implementation illustrates how to utilize videoFormatProps and audioFormatProps inside a recording layout. It handles both Standard Preset Modes and Custom Format Overrides dynamically:

mainwindow.cpp

#include "now2sdk.h"
#include "LFormat.h"
#include <QString>
#include <QStringList>

// Configuration handler extracted from live recording controls
void MainWindow::applyRecorderSettings() {
    if (m_isRecording) return; // Do not alter properties during active recording

    videoFormatProps vProps;
    audioFormatProps aProps;

    if (ui->modeStandardRadio->isChecked()) {
        // ─── 1. STANDARD PRESET MODE ───
        // Reads raw enum values directly from UI combobox user data
        vF_Type selectedVideoEnum = static_cast<vF_Type>(ui->standardVideoFormatCombo->currentData().toInt());
        aF_Type selectedAudioEnum = static_cast<aF_Type>(ui->standardAudioFormatCombo->currentData().toInt());
        
        vProps.setVideoFormat = selectedVideoEnum;
        aProps.setAudioFormat = selectedAudioEnum;
        
        // Colorspace mapping
        vProps.colorSpace = cS::fcc_UYVY; // Force broadcast standard 4:2:2 output conversion
    } else {
        // ─── 2. CUSTOM OVERRIDE MODE ───
        // Configures video props manually by overriding standard presets
        vProps.setVideoFormat = vF::Custom;
        
        QString resStr = ui->customResCombo->currentData().toString(); // e.g. "1920x1080"
        QStringList parts = resStr.split('x');
        if (parts.size() == 2) {
            vProps.width = parts[0].toInt();
            vProps.height = parts[1].toInt();
        } else {
            vProps.width = 1920;
            vProps.height = 1080;
        }
        
        vProps.fps = ui->customFpsCombo->currentData().toDouble(); // e.g. 50.0
        vProps.colorSpace = cS::fcc_ARGB32;                        // Request Alpha support

        // Configures audio props manually
        aProps.setAudioFormat = aF::Custom;
        aProps.sampleRate = ui->customSampleRateCombo->currentData().toInt(); // e.g. 48000
        aProps.channels = ui->customChannelsCombo->currentData().toInt();     // e.g. 2
        aProps.bitsPerSample = 16;                                            // 16-bit PCM
    }

    // Apply properties to the recording target engine
    m_lRecorder->setVideoFormat(vProps);
    m_lRecorder->setAudioFormat(aProps);

    // Apply video & audio bitrates
    m_lRecorder->setVideoBitrate(ui->videoBitrateCombo->currentData().toInt()); // e.g. 10000 kbps
    m_lRecorder->setAudioBitrate(ui->audioBitrateCombo->currentData().toInt()); // e.g. 192 kbps

    // Configure encoders and path
    std::string container = ui->containerCombo->currentText().toLower().toStdString();
    m_lRecorder->setContainer(container);
    m_lRecorder->setVideoCodec(ui->videoCodecCombo->currentText().toStdString());
    m_lRecorder->setAudioCodec(ui->audioCodecCombo->currentText().toStdString());
    
    QString fullPath = m_outputDir + "/" + ui->fileNameEdit->text() + "." + QString::fromStdString(container);
    m_lRecorder->setFilePath(fullPath.toStdString());
    
    // Bind source object to recorder
    m_lRecorder->recordObject(m_lLive);
}