LFilter Reference Manual & FFmpeg Filter Recipes

The LFilter class is a dynamic filter graph wrapper of the now2sdk framework, derived from the base LObject class. It manages real-time audio or video filter configurations, enabling developers to build and modify standard FFmpeg filter chain strings dynamically at runtime.

When bound to a media playback engine (LFile) or a live video feed ingest (LLive), LFilter enables real-time adjustments (such as color corrections, audio delay alignments, and audio volume manipulation) without restarting the playout pipelines.

1. Architectural Concept & Core Mechanisms

LFilter acts as a container for individual filter components. Instead of managing fixed property fields, it stores an internal map of filter names and their parameter arguments:

graph LR
    A[setProps - key/value] --> B{Value empty or false?}
    B -->|Yes| C[Remove filter from map]
    B -->|No| D[Add / Update filter parameters]
    D --> E[Trigger m_onChanged callback]
    C --> E
    
    F[Parent Loop - LFile/LLive] --> G[getFilterString]
    G --> H{Map empty?}
    H -->|Yes| I[Return null/anull]
    H -->|No| J[Return combined filter string]
    J --> K[Rebuild AVFilterGraph if changed]

Key Subsystems:

• Dynamic Parameter Map: All filters are indexed in an internal map std::map<std::string, std::string>. When a filter is set, the key is converted to lowercase to match FFmpeg syntax standards.
• Dynamic Live Rebuilding: The playout engines (LFile and LLive) check the output of getFilterString() on each frame loop. If the resulting string differs from the active filter graph configuration, the underlying FFmpeg AVFilterGraph is destroyed and rebuilt on-the-fly, ensuring instant parameter changes without playout interruptions.
• Standard Null Fallbacks: If the filter map is empty, LFilter automatically returns anull (audio) or null (video) to ensure that downstream decoding loops run normally without building graph overheads.

2. API Reference & Key Methods

📌 Public API Signatures

enum Type {
    Audio,
    Video
};

Defines the stream processing type of the filter instance.

LFilter(Type type = Audio);

Constructs an LFilter instance. The default type is Audio.

virtual ~LFilter();

Destructs the LFilter instance.

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

Sets or removes filter parameters.

• key: The standard name of the FFmpeg filter (e.g. "volume", "eq", "adelay", "hflip"). It is automatically converted to lowercase.
• value: The parameters passed to the filter.
  • If the value is "true" or "1", the filter is output as a flag (e.g. hflip).
  • If the value is empty ("") or "false", the filter is removed from the active pipeline.
  • Otherwise, it is mapped to a key-value format (e.g. volume=2.0).

std::string getFilterString() const;

Assembles the internal filter map into a single comma-separated FFmpeg filter string (e.g. "eq=brightness=1.05:contrast=1.1,hflip"). If the filter map is empty, returns "anull" for audio filters and "null" for video filters.

Type getType() const;

Returns whether the filter instance is configured as Audio or Video.

void setNotifyCallback(std::function<void()> callback);

Binds an external callback function that is triggered whenever a property is added, updated, or removed via setProps().

3. Practical Video & Audio Filter Recipes

The table below lists standard, production-tested FFmpeg filters that can be directly passed to LFilter::setProps for real-time video and audio processing.

🎥 Video Filter Recipes (Type: Video)

🔊 Audio Filter Recipes (Type: Audio)

4. C++ Integration Code Example

This code snippet shows how to instantiate and link video and audio filters to an LFile player, and dynamically update parameters at runtime based on developer controls.

#include "now2sdk.h"
#include <iostream>
#include <thread>
#include <chrono>

void setupProcessingFilters() {
    // 1. Create a playout object
    LFile* player = new LFile();
    player->fileNameSet("/home/alsaberk/Videos/sports_feed.mp4");
    player->setProps("loop", "true");

    // 2. Create and configure a Video Color Correction Filter
    LFilter* videoFilter = new LFilter(LFilter::Video);
    
    // Set color equalizer: slight brightness boost, increased contrast, vivid saturation
    videoFilter->setProps("eq", "brightness=0.03:contrast=1.15:saturation=1.4");
    
    // Bind to the player pipeline
    player->setVideoFilter(videoFilter);

    // 3. Create and configure an Audio delay/volume filter
    LFilter* audioFilter = new LFilter(LFilter::Audio);
    
    // Boost volume by 50%
    audioFilter->setProps("volume", "1.5");
    
    // Delay left and right channels by 120ms to fix sync errors
    audioFilter->setProps("adelay", "delays=120ms|120ms");
    
    // Bind to the player pipeline
    player->setAudioFilter(audioFilter);

    // 4. Start playout
    player->play();
    std::cout << "Playout started with active filters." << std::endl;

    // Simulate real-time adjustment after 5 seconds of playout
    std::this_thread::sleep_for(std::chrono::seconds(5));
    std::cout << "Modifying color levels and muting audio filter dynamically..." << std::endl;

    // Dynamically increase saturation on-the-fly (Graph auto-rebuilds in background)
    videoFilter->setProps("eq", "brightness=0.03:contrast=1.15:saturation=1.8");

    // Turn off volume boost (Passing "false" or empty string removes the filter from map)
    audioFilter->setProps("volume", "false");

    // Keep running...
    std::this_thread::sleep_for(std::chrono::seconds(10));

    player->stop();
    delete videoFilter;
    delete audioFilter;
    delete player;
}