LConvert Reference Manual & Batch Transcoding Guide

The LConvert class is a high-performance offline media transcode and file conversion engine based on the FFmpeg architecture. It reads one or multiple input media files (MP4, MKV, MOV, etc.), decodes them, applies scaling/resampling format conversions, and encodes them into a single merged output file with precise video/audio codec, bitrate, and container parameters.

It is particularly useful for exporting/merging playlist files, offline proxy generation, and rendering finished video packages.

1. API Reference & Key Methods

📌 Transcode Target Settings

• void setContainer(const std::string& container)
  Sets the destination container format (e.g. "mp4", "mkv", "mov").
• void setVideoCodec(const std::string& codec)
  Selects the target video encoder (e.g. "libx264", "h264_nvenc", "mjpeg").
• void setAudioCodec(const std::string& codec)
  Selects the target audio encoder (e.g. "aac", "mp3").
• void setVideoBitrate(int bitrateKbps)
  Sets the target video encoding bitrate in kilobits per second (e.g. 5000 for 5 Mbps).
• void setAudioBitrate(int bitrateKbps)
  Sets the target audio encoding bitrate in kilobits per second (e.g. 128 for 128 kbps).
• void setVideoFormat(const videoFormatProps& props)
  Configures output frame size, frame rate (FPS), and color space normalization parameters.
• void setAudioFormat(const audioFormatProps& props)
  Configures output audio sample rate, depth, and channels normalization.
• void setFilePath(const std::string& filePath)
  Sets the final absolute output file path.
• void setProps(const std::string& key, const std::string& value)
  Dynamic key-value parameters configuration block (used for fine-tuning encoder features).

📌 Input File Queue Management

• void addInputFile(const std::string& filePath)
  Appends an absolute media file path to the transcode source queue. Multiple files will be concatenated in order of addition.
• void removeInputFile(const std::string& filePath)
  Removes a specific file path from the input queue.
• void clearInputFiles()
  Empties the transcode input queue.

📌 Process Control & Monitoring

• bool Start()
  Launches the background transcoding worker thread. Returns true if initialization succeeds.
• void Stop()
  Requests thread termination to cancel the active transcode.
• void statusGet(int& status)
  Queries the current transcode state:
  • 0: Idle or successfully finished.
  • 1: Transcoding in progress.
  • -1: Failed due to an encoding error.
• double getProgress()
  Returns the current conversion progress factor (0.0 to 1.0 representing 0% to 100%).

📌 Dynamic Queries (Static Methods)

• static std::vector<std::string> getAvailableContainers()
  Returns a list of write-supported file format containers.
• static std::vector<std::string> getAvailableVideoCodecs(const std::string& container)
  Queries a list of supported video encoders for the specified container.
• static std::vector<std::string> getAvailableAudioCodecs(const std::string& container)
  Queries a list of supported audio encoders for the specified container.

2. Standard Supported Containers & Codecs

While LConvert dynamically queries the host system's FFmpeg library at runtime (via the static getAvailable... methods), the following table lists the industry-standard containers and codecs fully supported, validated, and optimized by the now2sdk framework:

📦 Supported Containers

🎥 Supported Video Codecs

🔊 Supported Audio Codecs

3. Encoder Configuration Properties (setProps)

The setProps(key, value) method is used to pass advanced configurations directly to FFmpeg codecs:

4. Qt Integration Example (settings.cpp & mainwindow.cpp integration)

The following implementation shows how LConvert dynamically populates UI selector combo-boxes, triggers an asynchronous export operation from selected playlist clips, and monitors progress using a timer and a QProgressDialog.

📄 settings.cpp (Dynamic Codec Query)

#include "settings.h"
#include "LConvert.h"
#include <QComboBox>

void SettingsWindow::populateForm() {
    // 1. Fetch available containers
    std::vector<std::string> containers = LConvert::getAvailableContainers();
    ui->containerCombo->clear();
    for (const auto& fmt : containers) {
        ui->containerCombo->addItem(QString::fromStdString(fmt));
    }
}

void SettingsWindow::onContainerChanged(const QString& container) {
    // 2. Query valid video codecs for container
    std::vector<std::string> vCodecs = LConvert::getAvailableVideoCodecs(container.toStdString());
    ui->videoCodecCombo->clear();
    for (const auto& codec : vCodecs) {
        ui->videoCodecCombo->addItem(QString::fromStdString(codec));
    }

    // 3. Query valid audio codecs for container
    std::vector<std::string> aCodecs = LConvert::getAvailableAudioCodecs(container.toStdString());
    ui->audioCodecCombo->clear();
    for (const auto& codec : aCodecs) {
        ui->audioCodecCombo->addItem(QString::fromStdString(codec));
    }
}

📄 mainwindow.cpp (Asynchronous Transcode Progress Monitoring)

#include "mainwindow.h"
#include "LConvert.h"
#include <QFileDialog>
#include <QProgressDialog>
#include <QTimer>
#include <QMessageBox>

void MainWindow::exportSelectedClips() {
    // Save target file selection
    QString savePath = QFileDialog::getSaveFileName(this, "Export Merged File", "/home/user/export.mp4", "Video Files (*.mp4 *.mov)");
    if (savePath.isEmpty()) return;

    // 1. Initialize & Configure LConvert
    m_LConvert = new LConvert();
    m_LConvert->setContainer("mp4");
    m_LConvert->setVideoCodec("libx264");
    m_LConvert->setAudioCodec("aac");
    m_LConvert->setVideoBitrate(8000); // 8 Mbps
    m_LConvert->setAudioBitrate(128);
    m_LConvert->setFilePath(savePath.toStdString());

    // Normalize format to system standard (1080p50)
    videoFormatProps vFormat;
    vFormat.setVideoFormat = vF::HD1080_50p;
    m_LConvert->setVideoFormat(vFormat);

    // Apply custom preset tuning
    m_LConvert->setProps("preset", "fast");
    m_LConvert->setProps("tune", "zerolatency");

    // 2. Add files to the input queue in order
    m_LConvert->clearInputFiles();
    m_LConvert->addInputFile("/recordings/clip1.bin");
    m_LConvert->addInputFile("/recordings/clip2.bin");

    // 3. Start transcode
    if (!m_LConvert->Start()) {
        QMessageBox::critical(this, "Export Failure", "Failed to start transcode engine.");
        return;
    }

    // 4. Initialize progress bar modal
    QProgressDialog* progressDlg = new QProgressDialog("Merging & Encoding Clips...", "Cancel", 0, 100, this);
    progressDlg->setWindowModality(Qt::WindowModal);
    progressDlg->setValue(0);
    progressDlg->show();

    // 5. Connect timer to monitor progress at 100ms intervals
    QTimer* progressTimer = new QTimer(this);
    connect(progressTimer, &QTimer::timeout, this, [this, progressTimer, progressDlg]() {
        int status = 0;
        m_LConvert->statusGet(status);
        double progressVal = m_LConvert->getProgress();
        
        // Progress is 0.0 to 1.0; QProgressDialog takes 0 to 100
        progressDlg->setValue(static_cast<int>(progressVal * 100.0));

        // User clicked cancel
        if (progressDlg->wasCanceled()) {
            m_LConvert->Stop();
            progressTimer->stop();
            progressTimer->deleteLater();
            progressDlg->deleteLater();
            delete m_LConvert;
            QMessageBox::information(this, "Export", "Transcode cancelled by user.");
            return;
        }

        if (status == 0) { // Finished successfully
            progressTimer->stop();
            progressTimer->deleteLater();
            progressDlg->setValue(100);
            progressDlg->deleteLater();
            delete m_LConvert;
            QMessageBox::information(this, "Export", "File exported successfully.");
        } else if (status < 0) { // Conversion error
            progressTimer->stop();
            progressTimer->deleteLater();
            progressDlg->deleteLater();
            delete m_LConvert;
            QMessageBox::critical(this, "Export Error", "Offline transcode failed.");
        }
    });

    progressTimer->start(100);
}