input-processor — Config Reference

The authoritative field reference for the input-processor JSON pipeline config. See input-processor for worked examples and how it fits the pipeline.

Defines one or more media input→output pipelines for the phrame-builder input-processor.

Field	Type	Required	Default	Description
$schema	string	no	—	Optional JSON Schema URI for editor autocomplete.
version	"1"	no	"1"	Schema version. Always '1'.
log_level	log_level	no	"info"	Default log level for all pipelines. Per-output log_level overrides this.
inputs	array of input_config	yes	—	Input source definitions.
outputs	array of output_config	yes	—	Output plugin sink definitions.
pipelines	array of pipeline_binding	yes	—	Bindings connecting inputs to outputs. Executed sequentially by default, or in parallel threads when parallel is true.
parallel	boolean	no	false	Run all pipeline bindings concurrently as parallel threads instead of sequentially. Required when capturing multiple services from a single live source (e.g. multiple DVB services from one multiplex, or multiple simultaneous live streams). When true all pipelines start at the same time; the process exits when all threads complete (or when any non-looping pipeline fails).
rayon_threads	integer	no	—	Size of the rayon global thread pool used for parallel YUV pixel-format conversion in the VideoCompressor. Resolution order at startup: --rayon-threads CLI flag, then RAYON_NUM_THREADS env var, then this field, then a default of 4. Without an explicit value rayon spawns one worker per logical CPU, which over-subscribes large hosts (e.g. 128 threads on a 128-core server, fanning out per frame at 60 fps). Ignored in MQTT mode — the pool is fixed before any config is received.

Definitions

log_level

Logging verbosity level.

One of: error · warn · info · debug · trace

pixel_format

Pixel format for decoded video output.

One of: yuv420p · yuv422p · yuv444p · yuv422p16le · nv12 · nv21 · rgb24 · bgr24 · rgba · bgra · argb · abgr · yuyv422 · uyvy422 · gray8

stream_type

A stream type that can be sent to an output sink. 'av_compressed' is a single muxed stream containing re-encoded video and audio interleaved; requires compress.video and/or compress.audio to be configured.

One of: video · video_compressed · audio · audio_compressed · av_compressed · proxy · proxy_compressed · subtitle

proxy_config

Configuration for the proxy (scaled-down) video stream. Also defines the resolution used by proxy_compressed.

Field	Type	Required	Default	Description
width	integer	no	640	Proxy frame width in pixels.
height	integer	no	360	Proxy frame height in pixels.
pixel_format	pixel_format	no	"yuv422p"	Pixel format for the uncompressed proxy video stream. The compressed proxy always encodes to yuv420p regardless of this setting.

proxy_compressed_config

Configuration for the H.264-compressed proxy stream. Dimensions are taken from the proxy config (default 640x360). The stream is always encoded to yuv420p.

Field	Type	Required	Default	Description
codec	string	no	"libx264"	FFmpeg encoder name. Must be a valid libavcodec encoder identifier. Defaults to 'libx264'.
bitrate	integer	no	1000000	Target encoding bit rate in bits per second. Defaults to 1000000 (1 Mbit/s).

burn_in_stream_list

Which decoded output streams to burn this overlay into. Any subset of ["video", "proxy"]. Defaults to both.

burn_in_font

Font to use for burn-in rendering. 'NimbusMonoPS' is a Courier-compatible monospace font. The 'Technology' variants are a sans-serif display font.

One of: NimbusMonoPS · Technology · Technology-Bold · Technology-Italic · Technology-BoldItalic

burn_in_timecode

Timecode overlay burned into decoded video frames as HH:MM:SS:FF, derived from the TAI origination timestamp.

Field	Type	Required	Default	Description
x	integer	no	50	Pixel distance from the left edge of the frame to the start of the timecode text.
y	integer	no	50	Pixel distance from the top edge of the frame to the top of the timecode text.
font_size	integer	no	32	Character height in pixels.
font	burn_in_font	no	—
apply_to	burn_in_stream_list	no	—

burn_in_text

Static text overlay burned into decoded video frames.

Field	Type	Required	Default	Description
content	string	yes	—	The text string to render. Supports ${variable} placeholders: ${width} (hi-res frame width), ${height} (hi-res frame height), ${frame_rate} (rate reported by stream, e.g. '25' or '29.97'), ${measured_frame_rate} (actual measured rate from a rolling window, updated per-frame), ${codec} (e.g. 'h264'). Unknown placeholders are left as-is.
x	integer	no	50	Pixel distance from the left edge of the frame to the start of the text.
y	integer	no	50	Pixel distance from the top edge of the frame to the top of the text.
font_size	integer	no	32	Character height in pixels.
font	burn_in_font	no	—
apply_to	burn_in_stream_list	no	—

burn_in_config

Burn-in overlays rendered into uncompressed video before sending to the output plugin. Both timecode and text are optional and independent.

Field	Type	Required	Default	Description
timecode	burn_in_timecode	no	—	Timecode overlay (HH:MM:SS:FF). Omit to disable.
text	burn_in_text	no	—	Static text overlay. Omit to disable.

input_config

Describes one media input source.

Field	Type	Required	Default	Description
id	string	yes	—	Unique identifier referenced by pipelines[].input_id.
plugin	enum: network · mxl · ndi	yes	—	Input plugin. 'network' reads any file/device/URL via FFmpeg. 'mxl' reads a live MXL stream. 'ndi' reads a live NDI source via the phramendi plugin (libphramendi.so).
source	string	yes	—	For 'network': a file path, device path (/dev/video0), or network URL (rtsp://, rtmp://, …). For 'mxl': the MXL stream name (stream_id). For 'ndi': the NDI source URL (e.g. 'ndi://192.168.1.10:5961/HOST (Source Name)').
format	string / null	no	null	FFmpeg input format hint, e.g. 'v4l2', 'rtsp', 'lavfi', 'mpegts'. Omit to let FFmpeg auto-detect.
options	object	no	{}	Arbitrary FFmpeg AVOption key/value pairs applied to the input.
video	video_input_config	no	—
audio	audio_input_config	no	—
realtime	boolean	no	false	Pace output to the source's native timestamps (real-time playback). Useful for live sources replayed from file.
loop	boolean	no	false	Restart from the beginning when EOF is reached.
frame_limit	integer	no	0	Stop after this many decoded video frames. 0 means unlimited.
label	string	no	—	Human-readable label for this input. Passed to output plugins as the 'label' field in their open configuration. When absent, the pipeline derives a label from 'source' (file basename for file inputs, stream name for MXL inputs).
flow_id	string	no	—	MXL flow UUID. Required when plugin is 'mxl'.
domain	string	no	—	MXL domain string. Required when plugin is 'mxl'.
media_type	enum: video · audio	no	"video"	NDI sub-stream selector. Each NDI reader instance is bound to a single media type — open two inputs if both are required. Only meaningful when plugin is 'ndi'.
log_level	log_level	no	—	Per-input log level override. Falls back to the top-level log_level when absent.
dvb	dvb_config	no	—

dvb_config

DVB-T/T2 tuning parameters for a network input backed by a DVB USB receiver (e.g. RTL2832U). When present the pipeline tunes the front-end, opens the demux, and reads the MPEG-TS stream from /dev/dvb/adapterN/dvr0. The source field is ignored — set it to the adapter path as a human-readable label.

Field	Type	Required	Default	Description
adapter	integer	no	0	DVB adapter index (0-based). Selects /dev/dvb/adapterN/frontend0, demux0, and dvr0.
frequency_hz	integer / null	no	—	Channel centre frequency in Hz (e.g. 578000000 for 578 MHz). Omit or set null to skip tuning (device must be pre-tuned externally). The demux filter is still configured.
bandwidth_hz	integer	no	8000000	Channel bandwidth in Hz. Default 8000000 (8 MHz) — standard for UK/EU DVB-T. Use 7000000 or 6000000 for other regions.
dvb_t2	boolean	no	false	Use the DVB-T2 delivery system instead of DVB-T. Enable for UK Freeview HD and other DVB-T2 multiplexes.
service_id	integer	no	0	MPEG-TS program/service number to decode. Passed to FFmpeg as program_num. 0 means auto-select the first available program.

video_input_config

Video stream decode settings.

Field	Type	Required	Default	Description
enabled	boolean	no	true	Whether to decode and forward the video stream.
pixel_format	pixel_format	no	"yuv422p"	Decoded video pixel format.
width	integer	no	—	Required output width for the hi-res video stream in pixels. Must be set together with height. When the source differs and scale_to_fit is false, a warning is logged; when scale_to_fit is true the frame is scaled to this resolution.
height	integer	no	—	Required output height for the hi-res video stream in pixels. Must be set together with width.
scale_to_fit	boolean	no	false	When true and width/height are set, scale input frames to the desired resolution. When false (default), only log a warning if the source resolution differs.
frame_rate	object	no	—	Explicit frame rate override (numerator / denominator). When set, replaces whatever frame rate the source reports. Example: { "numerator": 25, "denominator": 1 } forces 25 fps.
convert_frame_rate	object	no	—	Convert the video frame rate by dropping or duplicating decoded frames to achieve the target rate. Use frame_rate to correct wrong metadata without changing delivery rate; use convert_frame_rate to actually change the frame delivery rate.
min_width	integer	no	—	HLS/multi-bitrate variant selection: reject video streams narrower than this (pixels). Among streams that pass all constraints the highest-bitrate one is used.
max_width	integer	no	—	HLS/multi-bitrate variant selection: reject video streams wider than this (pixels).
min_height	integer	no	—	HLS/multi-bitrate variant selection: reject video streams shorter than this (pixels).
max_height	integer	no	—	HLS/multi-bitrate variant selection: reject video streams taller than this (pixels).
min_bitrate	integer	no	—	HLS/multi-bitrate variant selection: reject video streams with a bitrate below this value (bits/s).
max_bitrate	integer	no	—	HLS/multi-bitrate variant selection: reject video streams with a bitrate above this value (bits/s).

audio_input_config

Audio stream decode settings.

Field	Type	Required	Default	Description
enabled	boolean	no	true	Whether to decode and forward the audio stream.
sample_rate	integer	no	48000	Target sample rate in Hz for decoded audio. If the source rate differs the pipeline resamples via libswresample. Default: 48000.

output_config

Describes one plugin output sink.

Field	Type	Required	Default	Description
id	string	yes	—	Unique identifier referenced by pipelines[].output_id.
plugin	enum: vdi · mxl · null	yes	—	Output plugin backend. 'null' logs every frame and discards it — useful for validation.
stream_id	string	yes	—	Stream identifier passed to plugin_open (the VDI/MXL stream name).
streams	array of stream_type	no	["video","video_compressed","audio","audio_compressed"]	Which stream types to create. Defaults to all four when omitted.
log_level	log_level	no	—	Per-output log level override. Falls back to the top-level log_level when absent.
flow_id	string	no	—	MXL flow UUID. Required when plugin is 'mxl'.
domain	string	no	—	MXL domain string. Required when plugin is 'mxl'.
proxy	proxy_config	no	—	Proxy video stream settings. Used when 'proxy' or 'proxy_compressed' is listed in streams. Defines the scaled-down resolution; defaults to 640×360 yuv422p when omitted.
proxy_compressed	proxy_compressed_config	no	—	Compressed proxy stream settings. Active when 'proxy_compressed' is listed in streams. Defaults to libx264 at 1 Mbit/s when omitted.
compress	object	no	—	Re-encode decoded frames for the video_compressed and/or audio_compressed VDI streams. When absent the existing passthrough behaviour applies (compressed packets from the input are forwarded unchanged).
burn	burn_in_config	no	—	Burn-in overlays (timecode and/or text) rendered into uncompressed video frames. Omit to disable all overlays.
yuv_dump_file	string	no	—	Path to a raw YUV dump file. When set, every uncompressed decoded video frame (after burn-in) is written as planar YUV with no stride padding before being sent to the output plugin. Works with any output plugin. Playback: ffplay -f rawvideo -pixel_format yuv422p -video_size WxH -framerate N file.yuv
mqtt_broker	string	no	—	MQTT broker URL for stats publishing (null plugin only). E.g. 'tcp://localhost:1883'.
mqtt_topic_prefix	string	no	"stats"	MQTT topic prefix for stats (null plugin only). Defaults to 'stats'.
mqtt_client_id	string	no	—	MQTT client ID for stats publishing (null plugin only). Defaults to the stream_id.
frame_rate	number	no	—	Nominal frame rate used to compute the speed ratio in stats (null plugin only). 0 disables ratio.

pipeline_binding

Connects one input source to one output sink.

Field	Type	Required	Default	Description
input_id	string	yes	—	Must match an inputs[].id value.
output_id	string	yes	—	Must match an outputs[].id value.