How to Stream Video with RTSP on VOXL

Table of contents

1. Overview
2. General Use as a Service
3. Configuration File
4. Two Primary Modes
5. Running Multiple Instances
6. Command Line Reference
7. Troubleshooting

Overview

voxl-streamer is a background service that subscribes to MPA image streams, compresses them if necessary, and makes them available as an RTSP stream at:

rtsp://<VOXL_IP>:8900/live

The port is configurable (default 8900); the /live mount point is fixed. This is enabled by default on most systems to enable automatic streaming of video to QGroundControl by voxl-mavcam-manager — FPV SKUs are the exception, where video ships through voxl-vtx instead.

This video shows setting up a 720p encoded video stream with a VOXL 2 and IMX412: YouTube

General Use as a Service

voxl-streamer runs in the background via its systemd service (visible in voxl-inspect-services), started with no arguments — all behavior comes from the config file. Manage it with:

voxl-configure-streamer factory_enable   # reset config to defaults and enable
voxl-configure-streamer enable           # enable (starts on next reboot)
voxl-configure-streamer disable          # disable and stop

Multiple RTSP clients can watch the same stream simultaneously — the encoded media is shared. When no clients are connected, voxl-streamer disconnects from the MPA pipe entirely to save power and CPU, reconnecting when the next client shows up.

Configuration File

/etc/modalai/voxl-streamer.conf (JSON, created with defaults on first run):

Two Primary Modes

Pre-encoded input (default). voxl-streamer can subscribe to pre-encoded H264 or H265 MPA pipes such as the default hires_small_encoded. This is most efficient: frames pass straight through to RTSP with no re-encode. In this mode the bitrate, rotation, and decimator fields are ignored — set bitrate and GOP in voxl-camera-server.conf instead.

Raw input. When pointed at an uncompressed pipe (RAW8, NV12, YUV, RGB — e.g. tracking or qvio_overlay), voxl-streamer builds a GStreamer pipeline that can rotate, decimate, and compress the video to the configured bitrate using the platform’s hardware encoder. This works well but is less efficient than pre-encoded input.

The original VOXL (apq8096) supports H264 onboard encoding only — encoder: h265 errors out there. VOXL 2 supports both.

Running Multiple Instances

Each voxl-streamer process serves one stream. To stream a second camera alongside the background service, launch another instance with --standalone (so it doesn’t kill the service’s process) and a unique --port:

voxl-streamer --standalone --port 8901 -i tracking

That second stream is then at rtsp://<VOXL_IP>:8901/live.

Running voxl-streamer by hand without --standalone kills the running background service instance — that’s by design, so a manual run can take over cleanly.

Command Line Reference

-b --bitrate    <#>     | Override bitrate specified in the config file
-c --config             | Load config file only and quit (used for scripted setup)
-d --decimator  <#>     | Override the decimator specified in the config file
-h --help               | Print this help message
-i --input-pipe <name>  | Override the input pipe specified in the config file
-e --encoder <type>     | Choose video encoder h264 or h265 (if video is not already encoded)
-p --port       <#>     | Override the RTSP port number specified in the config file
-s --standalone         | Use this to launch a new instance alongside the default service
-v --verbosity  <#>     | Log verbosity level (Default 2)

CLI flags override the config file. Tab completion is installed — -i completes live camera pipes.

Troubleshooting

For general service debugging — logs, restarts, running in the foreground — see Debugging Services.

• Stream won’t open: confirm the service is running (voxl-inspect-services) and the configured input-pipe exists (voxl-list-pipes). The startup log prints the stream URL.
• Choppy or stalling video: voxl-streamer drops frames rather than buffering under load; if the source pipe backs up it is flushed. Reduce resolution/bitrate at the source, or lower the framerate with decimator (raw input).
• Frame size mismatch ... Shutting down: the pipe’s advertised frame size doesn’t match reality — usually a camera configuration change; re-check voxl-configure-cameras.
• Rotation/bitrate/decimator “not working”: those only apply to raw input — with a pre-encoded pipe, adjust voxl-camera-server.conf.
• If the camera server restarts, voxl-streamer automatically reconnects and re-serves the stream.

For a deeper latency-focused setup, see Low Latency Video Streaming.