Raptor CLI Configuration - themactep/thingino-firmware GitHub Wiki

Raptor is the default streamer on master-branch builds (see Streamer-Comparison for how the streamers differ). Everything it does can be controlled from the shell: raptorctl is the CLI tool that ships with the Raptor package, and it reaches every setting the Web UI exposes - plus plenty the UI does not. This page covers day-to-day configuration over SSH. This page does not apply to Prudynt (ciao/stable branch) builds.

The complete command reference lives upstream: raptorctl reference in the raptor-docs repository. The shipped /etc/raptor.conf is the fully commented reference config - every key is documented inline.

• SSH access to the camera (see SSH-Access-Keys; default credentials are root/root).
• raptorctl, installed at /usr/bin/raptorctl by the Raptor package. Check with raptorctl status.
• The init script for the whole streamer is /etc/init.d/S31raptor.

raptorctl sends JSON commands to each daemon over Unix domain sockets and prints the responses. Most commands take effect immediately, with no daemon restart.

Two calling conventions:

raptorctl <command> [args...]          # global command
raptorctl <daemon> <command> [args...] # command for one daemon

The daemons:

Global commands (no daemon prefix):

Configuration lives in one INI file, /etc/raptor.conf, shared by all daemons: [section] headers with key = value pairs. The config sections mirror the daemons ([image], [osd], [ircut], [recording], [rtsp], ...).

Read:

raptorctl config get image max_dgain   # one key
raptorctl config get image             # whole section
raptorctl rvd config                   # the daemon's resolved section

Write and persist:

raptorctl config set image max_dgain 32
raptorctl config save

Notes on saving:

• config set changes the running value immediately. config save writes what changed to /etc/raptor.conf - it is a dirty merge that only rewrites the keys each daemon actually modified, and leaves comments and untouched lines alone. A save with nothing dirty writes nothing at all.
• Verify a change with raptorctl config get <section> <key> rather than by eyeballing the file.
• Hand-editing /etc/raptor.conf is also fine; restart the affected daemon afterwards (see below). Hand-written comments survive every save.

Runtime commands like rvd set-brightness act on the live pipeline. Tunables that belong to a config section land in the running config as dirty keys, so a single raptorctl config save at the end of a tuning session persists everything. If you want a change to survive a reboot, end with config save; if you only want to experiment, don't - the next restart reverts to the file.

A useful pattern: tune live until the image looks right, dump what the daemons resolved (raptorctl rvd config, raptorctl ric get-thresholds), then apply the keepers with config set + config save.

All ISP commands take effect on the next frame.

raptorctl rvd set-brightness 140       # 0-255
raptorctl rvd set-contrast 128
raptorctl rvd set-saturation 128
raptorctl rvd set-sharpness 128
raptorctl rvd set-sinter 128           # spatial noise reduction, 0-255
raptorctl rvd set-temper 128           # temporal noise reduction, 0-255
raptorctl rvd set-hflip 1              # mirror
raptorctl rvd set-vflip 1              # flip
raptorctl rvd set-antiflicker 1        # 0 off / 1 50Hz / 2 60Hz
raptorctl rvd get-isp                  # dump all ISP settings as JSON

If night scenes look blotchy, cap the digital gain before touching the noise filters - high digital gain amplifies sensor noise, which the temporal filter then turns into smearing:

raptorctl rvd set-max-dgain 32         # lower = less digital gain
raptorctl rvd set-max-again 200000     # more analog headroom instead

The corresponding config keys (persist these with config save, or set them via config set image ...) are image.max_dgain and image.max_again.

Channel 0 is the main stream, 1 the sub stream.

raptorctl rvd set-rc-mode 0 vbr 4000000   # cbr | vbr | fixqp | capped
raptorctl rvd set-bitrate 0 2000000       # bits/sec
raptorctl rvd set-gop 0 50                # keyframe interval in frames
raptorctl rvd set-fps 0 25                # encoder frame rate
raptorctl rvd set-codec 0 h265            # restarts the stream
raptorctl rvd set-resolution 0 1920 1080  # restarts the stream
raptorctl rvd request-idr                 # force a keyframe now
raptorctl rvd get-bitrate 0               # target and measured bitrate
raptorctl rvd stream-restart 0            # stop + start one stream

set-sensor-fps is a transient override of the sensor rate (encoder rate control and GOP follow); 0 restores the boot rate, and nothing persists - handy for frame-drop experiments.

Practical bitrate numbers: see Bitrate.

The Web UI OSD page currently covers only the timestamp burn-in; the CLI reaches the rest.

raptorctl rod enable                       # / disable
raptorctl rod set-time-format "%H:%M:%S"   # strftime format
raptorctl rod set-font-size 24             # 10-72
raptorctl rod set-font-color 0xFFFFFFFF
raptorctl rod set-stroke-color 0xFF000000
raptorctl rod set-stroke-size 2            # 0-5
raptorctl rod add-element cam1 type=text template="Front door" position=top-left

raptorctl ric mode auto                # auto | day | night
raptorctl ric ircut night              # drive the IR-cut filter alone (transient)
raptorctl ric ir850 on                 # 850nm LED bank
raptorctl ric ir940 off                # 940nm LED bank
raptorctl ric get-thresholds           # every tunable + trigger source
raptorctl ric set-threshold night_luma 25
raptorctl ric set-threshold hysteresis_sec 3
raptorctl ric set-trigger luma         # luma | gain | adc | photo

Threshold keys take effect immediately and persist with config save; the whole day/night policy is runtime-tunable. Only the wiring (gpio_*, adc_channel) and enabled are boot-time.

raptorctl rad mute                     # / unmute
raptorctl rad set-volume 80
raptorctl rad set-aec 1                # echo cancellation
raptorctl rad set-ns 1 2               # noise suppression + level 0-3
raptorctl rad ao-set-volume 90         # speaker output

raptorctl rmr enable                   # / disable (closes active segments)
raptorctl test-motion 10               # trigger a test clip
raptorctl rmr timelapse-enable
raptorctl rmr timelapse-set interval 30
raptorctl rmr timelapse-snap           # one sample immediately
raptorctl rmr timelapse-status

raptorctl rsd clients                  # connected RTSP clients + RTCP stats
raptorctl rhd clients                  # HTTP clients
raptorctl rwd clients                  # WebRTC clients
raptorctl rvd status                   # per-stream state + frame-drop ledger
raptorctl rvd get-exposure             # live exposure, gain, luma, WB gains
raptorctl rvd set-log-level debug      # per-daemon, runtime; info to go back

rvd status reports a loss ledger per stream (drop_source, drop_publish, src_seq_resets) - all three at zero on a healthy pipeline.

raptorctl rsp start                    # / stop
raptorctl rsp set-url rtmp://live.example.com/app/key

set-url reconnects live within the same scheme; switching between RTMP and raw UDP needs a daemon restart.

rwd serves the live stream to browsers over WebRTC (sub-second latency) and, when built with WebTorrent support, to viewers outside your network with no port forwarding.

First check the build has it: raptorctl status should list rwd. The daemon is included when the firmware was built with BR2_PACKAGE_THINGINO_RAPTOR_WEBRTC (default on for Raptor full builds; it requires the TLS option, since WebRTC needs DTLS-SRTP). WebTorrent sharing needs BR2_PACKAGE_THINGINO_RAPTOR_WEBTORRENT (default on wherever WebRTC is). If rwd is missing, the image needs recompiling with those options.

Enable local WebRTC viewing:

raptorctl config set webrtc enabled true
raptorctl config set webrtc cert /etc/ssl/certs/uhttpd.crt
raptorctl config set webrtc key /etc/ssl/private/uhttpd.key
raptorctl config set webrtc username admin      # both lines enable HTTP auth
raptorctl config set webrtc password secret
raptorctl config save
/etc/init.d/S31raptor restart

Defaults worth knowing: WHIP signaling on port 8554 (https = true by default, which also enables the Talk button for two-way audio), media over UDP 8443, max_clients = 2 (raise with config set webrtc max_clients 4), local_ip auto-detected.

Open the built-in viewer at https://<camera-ip>:8554/webrtc in Chrome, Edge or Safari. Firefox needs mbedTLS 3.6.6 or newer in the firmware (DTLS ClientHello fragmentation fix); on older builds Firefox cannot connect.

go2rtc can consume the stream as WHEP:

streams:
  cam:
    - webrtc:http://CAMERA_IP:8554/whip

Enable WebTorrent sharing (view from anywhere, no port forwarding):

raptorctl config set webtorrent enabled true
raptorctl config save
/etc/init.d/S31raptor restart
raptorctl rwd share             # print the share URL
raptorctl rwd share-rotate      # new random key, invalidates the old link

The camera connects outbound to a WebTorrent tracker and a STUN server (defaults wss://tracker.openwebtorrent.com and stun.l.google.com:19302) and announces a share room keyed by webtorrent.share_key (auto-generated if omitted). Anyone holding the URL opens the viewer page and gets a direct P2P WebRTC connection to the camera. NAT notes: full-cone and port-restricted NATs work; symmetric NAT may not - viewers behind one should route through a VPN or a go2rtc proxy instead.

Only two outbound connections ever leave your network (tracker + STUN); inbound, the camera only serves LAN clients on ports 8554/8443. Design details: RWD WebRTC design.

raptorctl rvd save jpeg /tmp/snap.jpg        # one JPEG from the jpeg ring
raptorctl rvd save raw /tmp/frame.nv12       # one NV12 frame
raptorctl rvd save bayer /tmp/raw.bayer      # pre-ISP sensor RAW (16-bit LE)

Bayer frames are 12-bit (some sensors 10-bit) MSB-aligned in 16-bit little-endian words; demosaic with ffmpeg's bayer_bggr16le-class pixfmt, matching the pattern reported in /proc/jz/isp/isp-m0.

raptorctl rvd restart                  # one daemon
/etc/init.d/S31raptor restart          # the whole streamer

The ONVIF discovery script derives its profile URLs from /etc/raptor.conf, so endpoint changes made there stay consistent with ONVIF clients after the next discovery cycle.

Raptor images ship a few convenience wrappers that sit on top of raptorctl and the GPIO layer - handy interactively and in scripts:

Builds using the opt-in V4L2 capture backend ([system] video_backend = v4l2, currently a T41 main-stream path) deliberately answer only status, config-show, request-idr and the read-only getters on rvd; every other verb returns an explicit "not supported by the V4L2 backend" instead of touching uninitialized SDK state. The bulk of the CLI applies to the default IMP backend.

For scripts, raptorctl -j speaks raw JSON and can batch commands:

raptorctl -j '{"daemon":"rvd","cmd":"get-isp"}'
raptorctl -j '[
  {"daemon":"rvd","cmd":"set-brightness","value":128},
  {"daemon":"rvd","cmd":"set-contrast","value":140}
]'

• raptorctl command reference - the full upstream reference
• gtxaspec/raptor - the streamer source, including the fully commented config/raptor.conf
• Streamer-Comparison - which streamer your build runs
• Media-Streaming-Endpoints - RTSP/HTTP/WebRTC URLs
• Configuration:-Night-Mode - day/night behavior