Output Handler¶

When adding a new exporting setting in the UI, CVEDIA-RT adds an output handler configuration in the instance JSON file.

You can inspect and edit this file with an external text editor, or using the Advance Mode available when you open the Edit Instance window.

output-config-json

Each export flow is managed by an Output Handler.

Example

This output handler is configured to export an MP4 video

"Output": {
    "handlers": {
        "Export1": {
            "uri": "mp4:///output.mp4",
            "sink": "output_buffer", // one of the keys used in writeOutputSink
            "config": {
                "fps": 30,
                "script": "assets/scripts/output_handler_script.lua"
            }
        }
    }
}

An output handler should at least have an uri and a sink value.

uri : The uri defines the scheme and the path of the data stream.

sink : The sink defines what data to export. These are names used in the Lua script to export data by using the instance:writeOutputSink function. For more information, please check the Developer Reference.

config: The output handlers have additional settings you can configure in the config JSON field. In the example above, we are settings the frames per second of the exported video.

config.script: All the output handlers have a script option that allows specifying a Lua script file. This script will pre-process the data before sending it out to the stream. You can use this feature to transform and reduce the data to export. Check here for more information.

Multiple output streams

The instance JSON file can have multiple Output handlers defined inside the Output JSON object array. This way, you can export data in differnt format, protocols, and destination, and also export different sinks at the same time.

Available Output Handlers¶

By default CVEDIA-RT already provides modules to deal with some common output types, but the platform allow extra output handlers to be included by adding modules that register themselves as Output Handlers.

WriteData Module¶

The included WriteData module allows processing the following uri's in the Output config:

json - Output json data¶

The following Output configuration, when defined in the instance JSON file, allows outputting metadata in JSON format to a text file.

Be careful with data size

When processing the data, be careful because usually the metadata object can contain image crops for all detections, etc. This can make the exported file very big. So its recommended to always use an output handler script to filter just the data you need to export.

Configurable properties:

encode_buffers : This boolean property allows controlling if the buffers present on the data are saved as base64 or not.

{
    "Output": {
        "handlers": {
            "Export1": {
                "uri": "json:///detector_outputs_{sys.count tag1}.json",
                "sink": "[sink key]", // one of the keys used in writeOutputSink
                "config": {
                    "encode_buffers": false
                }
            }
        }
    }
}

Dynamic path

This example uses a count Dynamic String to output a new filename number on every exported file. It was given a tag tag1 so that it increments only for this outputhandler call.

csv - Output CSV data¶

Exports data in comma delimited format, one entry per line.

Configurable properties:

encode_buffers : This boolean property allows controlling if the buffers present on the data are saved as base64 or not.

{
    "Output": {
        "handlers": {
            "Export1": {
                "uri": "csv:///detector_outputs.csv",
                "separator": ",",
                "minify": true,
                "sink": "[sink key]", // one of the keys used in writeOutputSink
            }
        }
    }
}

txt - Output TXT data¶

Exports data in plain text, one entry per line.

Configurable properties:

encode_buffers : This boolean property allows controlling if the buffers present on the data are saved as base64 or not.

{
    "Output": {
        "handlers": {
            "Export1": {
                "uri": "txt:///detector_outputs.txt",
                "sink": "[sink key]", // one of the keys used in writeOutputSink
            }
        }
    }
}

mp4, mpg, mpeg - Output video file¶

Export the sink data of type image to a video file.

Configurable properties:

width (Optional) : Set the output video width (Default: keep input size).
height (Optional) : Set the output video height.
fps (Optional) : Set the output video Frames per Second (Default: 30).

{
    "Output": {
        "handlers": {
            "Export1": {
                "uri": "mp4:///demo.mp4",
                "sink": "[sink key]", // one of the keys used in writeOutputSink
                "config": {
                    "width": 800,
                    "height": 600,
                    "fps": 30
                }
            }
        }
    }
}

jpg, png - Output image data¶

Export the sink data of type image to an image file.

{
    "Output": {
        "handlers": {
            "Export1": {
                "uri": "jpg:///frame_{sys.count tag1}.jpg",
                "sink": "[sink key]", // one of the keys used in writeOutputSink
            }
        }
    }
}

GStreamerWriter Module¶

The GStreamerWriter module allows defining a pipeline and using GStreamer to process the output data from CVEDIA-RT. This allows outputting data to files, RTMP servers, etc.:

gstreamer - Output GStreamer data¶

Export image and metadata to a GStreamer pipeline.

The pipeline must include the element appsrc name=cvedia-rt as source for this feature to work properly.

RTMP Example¶

{
    "Output": {
        "handlers": {
            "Export1": {
                "sink": "[sink key]", // one of the keys used in writeOutputSink
                "monotonic": false, // for rtmp you want to flush data as soon as possible, so we disable monotonic tics
                "uri": "gstreamer:///appsrc name=cvedia-rt ! videoconvert ! x264enc speed-preset=1 ! video/x-h264,profile=baseline ! flvmux latency=0 start-time-selection=1 streamable=true ! rtmpsink location='rtmp://127.0.0.1:1935/live/cam0 live=true'"
            }
        }
    }
}

RTMP Server

To test RTMP we suggest you use RED5 which allows you to do multicasting and requires no configuration.

MP4 file Example¶

{
    "Output": {
        "handlers": {
            "Export1": {
                "sink": "[sink key]", // one of the keys used in writeOutputSink
                "uri": "gstreamer:///appsrc name=cvedia-rt ! videoconvert ! x264enc ! queue ! filesink location=output/file.mp4"
            }
        }
    }
}

rtsp - Output RTSP data¶

{
    "Output": {
        "handlers": {
            "Export1": {
                "uri": "rtsp://0.0.0.0:8554/stream1",
                "sink": "[sink key]", // one of the keys used in writeOutputSink
                "config": {
                    "debug": "4",
                    "fps": 30,
                    "pipeline": "( appsrc name=cvedia-rt ! videoconvert ! videoscale ! x264enc speed-preset=1 ! video/x-h264,profile=baseline ! rtph264pay name=pay0 pt=96 )"
                }
            }
        }
    }
}

RTSP codecs

By default we're using h264, you can change to h265 or, on nvidia platforms, configure your own pipeline depending on the gstreamer plugins you have available.

MQTT Module¶

The MQTT module allows processing the following URIs:

mqtt - Output MQTT data¶

Export image and metadata to a MQTT broker. Images will be converted to jpeg/base64.

The following example contains several optional options:

certificate_path: Path of the certificate to authenticate to broker (server)
username: Username registered on broker
password: Password registered on broker

Change from RT 2023.5.1: Use config/schema_events instead of the sink key.

The events you can subscribe to are defined in the JSON schemas listed here: Events JSON schemas
The old sink data can still be used, but is not the suggested approach because the format of the data could change between different versions of CVEDIA-RT, making the integration with external tools at risk.
The schema_events field can be either a single string in the format exporter-schema:version or a list of those.

Minimal configuration

{
    "Output": {
        "handlers": {
            "MyMQTTExporter": {
                "config": {
                    "schema_events": "event-intrusion:1"
                },
                "enabled": true,
                "uri": "mqtt://127.0.0.1:8883/events"
            }
        }
    }
}

Configuration with optional parameters and events as list. Using localhost instead of 127.0.0.1

{
    "Output": {
        "handlers": {
            "AnotherMQTTExporter": {
                "config": {
                    "certificate_path": "/path/to/ca-root-cert.crt",
                    "username": "user",
                    "password": "SomeSecurePassword",
                    "schema_events": ["track:1", "event-intrusion:1"]
                },
                "enabled": true,
                "uri": "mqtt://localhost:8883/events"
            }
        }
    }
}

Legacy way - using sinks

Note: [sink key] is one of the keys used in writeOutputSink method in the Lua scripts of the solution.

{
    "Output": {
        "handlers": {
            "Export1": {
                "sink": "[sink key]",
                "uri": "mqtt://127.0.0.1:1883/outputtopic"
            }
        }
    }
}

MQTT Shared subscriptions

Starting with MQTT v5 (using mosquitto v1.6.x), a shared subscription feature is available. This feature enables the MQTT broker to distribute messages equally among subscribed clients.

From the publisher's perspective, no adjustments are required in terms of settings. For instance, when using a topic named output_topic, the CVEDIA-RT URI would appear as follows: mqtt://{hostname_or_ip}:{port}/output_topic. On the subscriber's side, however, modifications to the subscription topic are necessary. In this context, the topic format is $share/{groupname_of_clients}/output_topic. An example would be $share/rt_output_processors/output_topic.

This topic structure is generally applicable to any MQTT brokers that support MQTT v5 or higher.

Setting Output Handler in Lua¶

You can leave the JSON configuration empty for the output handlers and specify the output URI at runtime. For this, the following Lua interfaces can be used:

-- Usually executed in the function onInit() of index.lua

-- Standard output module loading
local output = api.factory.output.create(instance, "Output")

-- Set output source to the specified URI. When giving only one argument, the "Output" sink key will be used
output:setSource("mqtt://127.0.0.1:1883/output")

-- Set output source to the specified URI and specified sink key to attach to
output:setSource("mqtt://127.0.0.1:1883/output", "SinkName")

-- Set output source to the specified URI, specified sink key to attach to, and a configuration object
output:setSource("mp4:///demo.mp4", "SinkName", {"width": 800,"height": 600, "fps": 30})