LPreview Reference Manual & UI Preview Guide

The LPreview class is the cross-framework video rendering and audio monitoring widget of the now2sdk framework. It acts as a downstream receiver (sink) that can be bound to any stream source (such as LFile, LLive, LMixer, or LSwitcher) to render video feeds and play audio through the local sound card.

LPreview utilizes the Pimpl design pattern to decouple the API from the underlying graphics framework. This allows it to dynamically select and load either Qt (via OpenGL/QOpenGLWidget) or GTK (via GTK4/Cairo) rendering backends at runtime.

1. Unified Preview Architecture

graph TD
    A[Program Stream - LObject] -->|AVFrame*| B(LPreview Controller)
    B -->|ui_framework prop| C{Driver Selection}
    
    C -->|qt| D[Qt OpenGL Renderer - LVideoWidget]
    C -->|gtk| E[GTK4 Cairo Renderer - LVideoWidgetGTK]
    
    D --> F[1. OpenGL YUV-to-RGB Texturing]
    D --> G[2. Audio Playout - OpenAL/SDL2 Audio Device]
    D --> H[3. GLSL Canvas Overlays - VU Meter, Timecode, Status Label]
    
    E --> I[1. Cairo Surface Blitting]
    E --> J[2. Audio Playout - SDL2]
    E --> K[3. Cairo Overlays - Text/Borders]
    
    F --> L[GUI Window Canvas / QWidget]
    H --> L
    I --> M[GtkWidget Window Box]
    K --> M

Key Subsystems:

• OpenGL Hardware Acceleration (Qt Backend): Utilizes fragment shaders to convert planar YUV (YUV420p, UYVY, etc.) textures to RGB directly on the GPU, achieving ultra-low CPU overhead.
• Cairo Rasterizer (GTK Backend): Fallback GTK engine that handles blitting, text scaling, and overlay compositing using standard Cairo drawing routines.
• On-Screen Display (OSD) Layers: Built-in shaders/drawers render dynamic overlays including Real-Time VU Level Meters, SMPTE Timecodes, and customizable Name/Status banners directly on top of the live video.
• Direct Audio Playout: Extracts and synchronizes audio samples from the source stream, routing them directly to the local default audio output device.

2. API Reference & Public Methods

void previewEnable(void* parent, bool audio, bool video);

Binds the preview renderer to a parent GUI element.

• parent: Must be cast to QWidget* when using the Qt framework, or GtkWidget* when using GTK.
• audio/video: Configures whether audio monitoring and video rendering are enabled.

void previewObject(LObject* source);

Hooks up the preview widget as a downstream listener to source.

void setProps(const std::string& key, const std::string& value);

Updates layout variables, color properties, or toggles overlays. Parameter keys are detailed in Section 3.

void statusGet(int& status);

Returns the active visibility status of the widget (1 if visible/drawing, 0 if idle or hidden).

void setName(const std::string& name);
void setStatus(const std::string& status);

Sets OSD text labels for name tags (e.g. "CAM 1") or broadcast status tags (e.g. "PROGRAM", "PREVIEW", "ON AIR").

void setAudio(bool enable);
void mute(bool isMute);

Toggles or mutes audio playout monitoring.

void clear();

Flushes all frame and audio sample queues, clearing the canvas.

3. Properties & Configuration Options

All options listed below are configured at runtime via the setProps(const std::string& key, const std::string& value) interface:

4. Integration Code Examples

🟢 Qt Integration Example

This example demonstrates how to integrate LPreview inside a Qt main window parent, bind it to a media file playout source, and enable audio/timecode overlays.

mainwindow.cpp

#include "`mainwindow.h`"
#include "./ui_mainwindow.h"
#include "LFile.h"
#include "LPreview.h"

MainWindow::MainWindow(QWidget *parent)
    : QMainWindow(parent),
      ui(new Ui::MainWindow),
      m_lFile(new LFile()),
      m_lPreview(new LPreview())
{
    ui->setupUi(this);

    // 1. Load media file path into playout engine
    m_lFile->fileNameSet("/home/alsaberk/Videos/commercial_break.mp4");
    m_lFile->setProps("loop", "true");

    // 2. Select Qt framework driver
    m_lPreview->setProps("ui_framework", "qt");
    
    // 3. Configure OSD overlays
    m_lPreview->setProps("audio_meter", "true");      // Enable VU meter
    m_lPreview->setProps("timecode.preview", "true"); // Enable Timecode display
    m_lPreview->setProps("border", "true");           // Draw border
    m_lPreview->setProps("border_color", "#ef4444");  // Red border
    m_lPreview->setProps("status", "ON AIR");         // Set status label
    m_lPreview->setProps("name", "PLAYOUT FEED");     // Set name tag

    // 4. Bind to parent QWidget layout structure
    // NOTE: This must be called BEFORE previewObject!
    m_lPreview->previewEnable(ui->previewWidget, true, true);

    // 5. Connect program source to preview widget
    m_lPreview->previewObject(m_lFile);

    // 6. Start playout
    m_lFile->play();
}

MainWindow::~MainWindow() {
    m_lFile->stop();
    delete m_lPreview;
    delete m_lFile;
    delete ui;
}

🟢 GTK4 Integration Example

This example demonstrates how to integrate LPreview inside a GTK4 layout container box.

#include <gtk/gtk.h>
#include "LFile.h"
#include "LPreview.h"

static void activateApp(GtkApplication* app, gpointer user_data) {
    // 1. Create main GTK window
    GtkWidget* window = gtk_application_window_new(app);
    gtk_window_set_title(GTK_WINDOW(window), "now2sdk GTK Ingest Monitor");
    gtk_window_set_default_size(GTK_WINDOW(window), 800, 600);

    // 2. Create GtkBox layout container
    GtkWidget* box = gtk_box_new(GTK_ORIENTATION_VERTICAL, 0);
    gtk_window_set_child(GTK_WINDOW(window), box);

    // 3. Initialize Playout player
    LFile* player = new LFile();
    player->fileNameSet("/home/alsaberk/Videos/stream_feed.ts");
    player->play();

    // 4. Setup GTK Preview
    LPreview* gtkPreview = new LPreview();
    gtkPreview->setProps("ui_framework", "gtk"); // Set GTK backend
    gtkPreview->setProps("timecode.preview", "true");
    gtkPreview->setProps("status", "PREVIEW");
    
    // Bind to GTK container box
    gtkPreview->previewEnable(box, true, true);
    
    // Connect stream source
    gtkPreview->previewObject(player);

    gtk_widget_show(window);
}

int main(int argc, char** argv) {
    GtkApplication* app = gtk_application_new("com.now2media.monitor", G_APPLICATION_DEFAULT_FLAGS);
    g_signal_connect(app, "activate", G_CALLBACK(activateApp), NULL);
    int status = g_application_run(G_APPLICATION(app), argc, argv);
    g_object_unref(app);
    return status;
}

5. Modular Plugin & Linkage Guide

To maintain a zero-dependency core kütüphane (libnow2sdk.so), the preview backends are split into separate runtime-loaded shared object plugins:

1. libnow2sdk_qt.so: Contains Qt-specific rendering (LVideoWidget).
2. libnow2sdk_gtk.so: Contains GTK-specific rendering (LVideoWidgetGTK).

📦 Deployment Requirements

For LPreview to load the graphics backends successfully:

• The plugin binaries (libnow2sdk_qt.so or libnow2sdk_gtk.so) must be present in the same directory as the executing binary (or accessible via standard system library paths like LD_LIBRARY_PATH).
• The loader dynamically calls dlopen on the required plugin file only when setProps("ui_framework", ...) is invoked.

🔗 Compilation Linkage

• If your application uses LPreview interface class exclusively, you only need to link your project against -lnow2sdk at compile-time. The graphic frameworks are resolved dynamically at runtime.
• If your C++ code directly instantiates UI components like LVideoWidget (Qt) or LVideoWidgetGTK (GTK) as local variables, you must link against the respective plugin library at compile-time:
  • Qt Projects: Link against -lnow2sdk -lnow2sdk_qt
  • GTK Projects: Link against -lnow2sdk -lnow2sdk_gtk