Skip to main content

Channel

A channel config sets where a channel's playout is, which ffmpeg it uses, and the format of its output. The lineup points to it from channels[].config, and can merge overlays over it from channels[].overlays.

  • A relative path is relative to the file that sets it (the channel config or an overlay).
  • version is the format version of the file. See Config Versions.
  • For validation and completion in an editor such as VS Code, set $schema to the JSON schema, https://ersatztv.org/schema/channel/0.1.2.json. ErsatzTV Next ignores $schema.
  • Since is the first channel config version with the property. A property marked unreleased is on main and not in a release yet.
{
  "version": "https://ersatztv.org/channel/version/0.1.2",
  "playout": { "folder": "./playout" },
  "ffmpeg": {},
  "normalization": {
    "audio": { "format": "aac", "bitrate_kbps": 192, "channels": 2 },
    "video": { "format": "h264", "width": 1920, "height": 1080, "bitrate_kbps": 4000 }
  }
}

Top level​

Settings for one channel: where its playout is, which ffmpeg to use, and the output format. A relative path in any of these settings is relative to the file that sets it.

fallback
FallbackSince 0.1.0

What plays when nothing is scheduled or an item fails.

Default value
{
  "show_error": false
}
ffmpegRequired
FFmpegSince 0.1.0

ffmpeg and ffprobe settings.

normalizationRequired
NormalizationSince 0.1.0

Output format for audio, video and subtitles.

playoutRequired
PlayoutSince 0.1.0

Where to find the channel's playout files.

version
stringSince 0.1.0

Schema version URI, e.g. "https://ersatztv.org/channel/version/0.1.0". Missing means 0.0.0.

Playout​

playout
folderRequired
stringSince 0.1.0

Folder of playout files, named {start}_{finish}.json.

virtual_start
stringDefault: nullSince 0.1.0

Play the playout as if the channel started at this time instead of now. RFC 3339, e.g. 2026-04-13T00:24:21.527-05:00. For testing.

FFmpeg​

ffmpeg
disabled_filters
array of stringDefault: []Since 0.1.0

ffmpeg video filters to never use, even when the ffmpeg build has them, e.g. ["scale_cuda"]. Pipelines that need one use another filter or software instead.

ffmpeg_path
stringDefault: nullSince 0.1.0

Path to the ffmpeg executable. Unset or empty uses ffmpeg from PATH.

ffprobe_path
stringDefault: nullSince 0.1.0

Path to the ffprobe executable. Unset or empty uses ffprobe from PATH.

preferred_filters
array of stringDefault: []Since 0.1.0

ffmpeg video filters in order of preference, used when more than one filter can do the same step, e.g. ["tonemap_vaapi", "tonemap_opencl"].

reports_folder
stringDefault: nullSince 0.1.0

Folder for troubleshooting reports. When set, each failed item or fallback writes a subfolder with the ffmpeg output, the channel config and media info. Unset writes none.

Fallback​

fallback

Controls the content that replaces scheduled content when there is nothing to play (a gap in the playout) or when the scheduled item fails

duration_secondsUnreleased
integerSince 0.1.2

Fallback length in seconds when the fallback has no end time, e.g. after a failed dynamic source. Default 60. Raised to the source's retry_budget_ms if shorter.

show_error
booleanDefault: falseSince 0.1.0

Burn the reason for the fallback into the fallback video; this is always burned, regardless of the normalization subtitle mode

Normalization​

normalization
audioRequired
Audio normalizationSince 0.1.0

Audio output settings.

subtitle
Subtitle normalizationSince 0.1.0

Subtitle output settings.

Default value
{
  "fonts_folder": null,
  "force_style": null,
  "mode": "burn"
}
videoRequired
Video normalizationSince 0.1.0

Video output settings.

Audio normalization​

normalization.audio
bitrate_kbps
integerSince 0.1.0

Bitrate in kbit/s. Unset leaves it to the encoder.

buffer_kbps
integerSince 0.1.0

Rate control buffer size (-bufsize) in kbit/s. Unset leaves it to the encoder.

channels
integerSince 0.1.0

Number of channels, e.g. 2 for stereo. Unset keeps the source channel count.

copy_formats
array of Audio copy formatSince 0.1.0

Source codecs to copy when mode is copy. Default: aac, ac3, eac3, mp3.

format
Audio formatDefault: "aac"Since 0.1.0

Codec for transcoded items. When mode is copy, used only for items that are not copied.

loudness
LoudnessSince 0.1.0

Targets for normalize_loudness.

mode
Stream modeDefault: "transcode"Since 0.1.0

Whether to transcode every item or copy items whose codec allows it.

normalize_loudness
booleanDefault: falseSince 0.1.0

Normalize loudness with the ffmpeg loudnorm filter to the loudness targets. Not allowed when mode is copy.

sample_rate_hz
integerSince 0.1.0

Sample rate in Hz, e.g. 48000. Unset keeps the source rate, or 48000 when normalize_loudness is on.

Loudness​

normalization.audio.loudness
integrated_target
numberSince 0.1.0

Integrated loudness target in LUFS (loudnorm I). Unset is -16.

range_target
numberSince 0.1.0

Loudness range target in LU (loudnorm LRA). Unset is 11.

true_peak
numberSince 0.1.0

Maximum true peak in dBTP (loudnorm TP). Unset is -1.5.

Video normalization​

normalization.video
accel
Hardware accelerationDefault: nullSince 0.1.0

Hardware acceleration for decoding, filtering and encoding. Steps the device can't do use software. If the device can't be probed, the whole channel uses software. Unset or empty uses software.

amf_device
integerSince 0.1.0

AMF adapter index. Windows only. Unset picks the discrete AMD adapter.

bit_depth
integerDefault: 8Since 0.1.0

Bit depth, 8 or 10. mpeg2video always uses 8.

bitrate_kbps
integerSince 0.1.0

Bitrate in kbit/s. Required for mpeg2video. Unset leaves it to the encoder.

buffer_kbps
integerSince 0.1.0

Rate control buffer size (-bufsize) in kbit/s. Unset leaves it to the encoder.

copy_formats
array of Video formatSince 0.1.0

Source codecs to copy when mode is copy. Default: h264, hevc.

deinterlace
booleanDefault: falseSince 0.1.0

Deinterlace interlaced sources. Progressive sources are not changed.

filters
Video filtersSince 0.1.0

Options for individual ffmpeg filters. Unset options use the filter's default.

Default value
{
  "bwdif": null,
  "bwdif_cuda": null,
  "deinterlace_qsv": null,
  "deinterlace_vaapi": null,
  "libplacebo": null,
  "scale": null,
  "tonemap": null,
  "tonemap_opencl": null,
  "w3fdif": null,
  "yadif": null,
  "yadif_cuda": null
}
format
Video formatDefault: "h264"Since 0.1.0

Codec for transcoded items. When mode is copy, this and all other video settings apply only to items that are not copied.

frame_rate
stringDefault: nullSince 0.1.1

Output frame rate, N or N/D (e.g. 25, 30000/1001). Frames are dropped or repeated to match it. In copy mode, only items at this rate are copied. Unset keeps the source rate.

height
integerSince 0.1.0

Height in pixels. Applies only when width is also set; otherwise the source size is kept. The fallback uses 1080 when unset.

mode
Stream modeDefault: "transcode"Since 0.1.0

Whether to transcode every item or copy items whose codec allows it. In copy mode, items with graphics, burned-in subtitles, still images, Dolby Vision profile 5 or AVI sources are always transcoded.

scaling_mode
Scaling modeDefault: "scale_and_pad"Since 0.1.0

How a source with a different aspect ratio fits width and height.

vaapi_device
stringSince 0.1.0

VAAPI render node. Unset uses /dev/dri/renderD128.

vaapi_driver
VAAPI driverSince 0.1.0

VAAPI driver. Unset lets libva select the driver for vaapi_device.

width
integerSince 0.1.0

Width in pixels. Applies only when height is also set; otherwise the source size is kept. The fallback uses 1920 when unset.

Video filters​

normalization.video.filters

Each filter has one option block. A value must contain only a-z, 0-9, _, ., + and -.

bwdif
bwdifDefault: nullSince 0.1.0

Options for the bwdif filter, used for software deinterlacing.

bwdif_cuda
bwdif_cudaDefault: nullSince 0.1.0

Options for the bwdif_cuda filter, used for CUDA deinterlacing.

deinterlace_qsv
deinterlace_qsvDefault: nullSince 0.1.0

Options for the deinterlace_qsv filter, used for QSV deinterlacing. Run ffmpeg -h filter=deinterlace_qsv for its options.

deinterlace_vaapi
deinterlace_vaapiDefault: nullSince 0.1.0

Options for the deinterlace_vaapi filter, used for VAAPI deinterlacing. Run ffmpeg -h filter=deinterlace_vaapi for its options.

libplacebo
libplaceboDefault: nullSince 0.1.0

Options for the libplacebo filter, used for CUDA and Vulkan tonemapping.

scaleUnreleased
scaleDefault: nullSince 0.1.2

Options for the scale filter, used for software scaling.

tonemap
tonemapDefault: nullSince 0.1.0

Options for the tonemap filter, used for software tonemapping.

tonemap_opencl
tonemap_openclDefault: nullSince 0.1.0

Options for the tonemap_opencl filter, used for VAAPI tonemapping.

w3fdif
w3fdifDefault: nullSince 0.1.0

Options for the w3fdif filter, used for software deinterlacing.

yadif
yadifDefault: nullSince 0.1.0

Options for the yadif filter, used for software deinterlacing.

yadif_cuda
yadif_cudaDefault: nullSince 0.1.0

Options for the yadif_cuda filter, used for CUDA deinterlacing.

bwdif​
normalization.video.filters.bwdif
mode
stringDefault: nullSince 0.1.0

Value for the bwdif mode option. Allowed characters: a-z, 0-9, _, ., +, -.

bwdif_cuda​
normalization.video.filters.bwdif_cuda
mode
stringDefault: nullSince 0.1.0

Value for the bwdif_cuda mode option. Allowed characters: a-z, 0-9, _, ., +, -.

deinterlace_qsv​
normalization.video.filters.deinterlace_qsv
mode
stringDefault: nullSince 0.1.0

Value for the deinterlace_qsv mode option. Allowed characters: a-z, 0-9, _, ., +, -.

deinterlace_vaapi​
normalization.video.filters.deinterlace_vaapi
mode
stringDefault: nullSince 0.1.0

Value for the deinterlace_vaapi mode option. Allowed characters: a-z, 0-9, _, ., +, -.

libplacebo​
normalization.video.filters.libplacebo
tonemapping
stringDefault: nullSince 0.1.0

Value for the libplacebo tonemapping option. Allowed characters: a-z, 0-9, _, ., +, -.

scale​
normalization.video.filters.scale
flagsUnreleased
stringDefault: nullSince 0.1.2

Flags for the software scale filter, e.g. bicubic, lanczos, fast_bilinear. Default is bicubic. Also applies to graphics, image subtitles, and hardware accels that use the software scaler.

tonemap​
normalization.video.filters.tonemap
tonemap
stringDefault: nullSince 0.1.0

Value for the tonemap tonemap option. Allowed characters: a-z, 0-9, _, ., +, -.

tonemap_opencl​
normalization.video.filters.tonemap_opencl
tonemap
stringDefault: nullSince 0.1.0

Value for the tonemap_opencl tonemap option. Allowed characters: a-z, 0-9, _, ., +, -.

w3fdif​
normalization.video.filters.w3fdif
mode
stringDefault: nullSince 0.1.0

Value for the w3fdif mode option. Allowed characters: a-z, 0-9, _, ., +, -.

yadif​
normalization.video.filters.yadif
mode
stringDefault: nullSince 0.1.0

Value for the yadif mode option. Allowed characters: a-z, 0-9, _, ., +, -.

yadif_cuda​
normalization.video.filters.yadif_cuda
mode
stringDefault: nullSince 0.1.0

Value for the yadif_cuda mode option. Allowed characters: a-z, 0-9, _, ., +, -.

Subtitle normalization​

normalization.subtitle
fonts_folder
stringDefault: nullSince 0.1.0

Folder of fonts for burned-in text subtitles.

force_style
stringDefault: nullSince 0.1.0

ASS style overrides for burned-in text subtitles, e.g. FontName=Arial,FontSize=24 (the subtitles filter's force_style option).

mode
Subtitle modeDefault: "burn"Since 0.1.0

What to do with the selected text subtitle track. Image subtitles are always burned in.

Values​

The allowed values for properties that take a fixed set of strings.

Stream mode​

ValueSinceDescription
transcode0.1.0Transcode every item.
copy0.1.0Copy items with a source codec in copy_formats. Transcode all other items.

Audio format​

ValueSinceDescription
aac0.1.0AAC.
ac30.1.0Dolby Digital (AC-3).

Audio copy format​

Limited to codecs that mux correctly into HLS MPEG-TS.

ValueSinceDescription
aac0.1.0AAC.
ac30.1.0Dolby Digital (AC-3).
eac30.1.0Dolby Digital Plus (E-AC-3).
mp20.1.0MPEG-1 Audio Layer II.
mp30.1.0MPEG-1 Audio Layer III.

Video format​

ValueSinceDescription
h2640.1.0H.264 (AVC).
hevc0.1.0H.265 (HEVC).
mpeg2video0.1.0MPEG-2 video. Requires bitrate_kbps.

Scaling mode​

ValueSinceDescription
scale_and_pad0.1.0Scale to fit inside the frame and pad the rest with black.
stretch0.1.0Scale to fill the frame, ignoring the aspect ratio.
crop0.1.0Scale to cover the frame and crop the overflow.

Hardware acceleration​

ValueSinceDescription
amf0.1.0AMD AMF. Windows only.
cuda0.1.0NVIDIA NVENC/NVDEC.
qsv0.1.0Intel Quick Sync Video.
rkmpp0.1.0Rockchip MPP. Linux only.
vaapi0.1.0VA-API. Linux only.
videotoolbox0.1.0Apple VideoToolbox. macOS only.
vulkan0.1.0Vulkan Video.

VAAPI driver​

ValueSinceDescription
ihd0.1.0Intel media driver, for Broadwell and newer.
i9650.1.0Legacy Intel driver, for older Intel GPUs.
radeonsi0.1.0Mesa driver for AMD GPUs.

Subtitle mode​

ValueSinceDescription
burn0.1.0Burn subtitles into the video.
convert0.1.0Convert text subtitles to a WebVTT track in the HLS stream.