Configure FFmpeg Transcoding Profiles in ErsatzTV Legacy

An FFmpeg profile is a reusable collection of transcoding parameters that you assign to one or more channels. Every channel must reference a profile; when ErsatzTV prepares a stream for that channel it reads the profile to determine how to encode the video and audio, how to handle scaling, what hardware accelerator to use, and whether to normalise loudness or framerate. Separating profiles from channels makes it easy to apply the same quality preset to many channels simultaneously or to maintain separate profiles for 1080p, 720p, and mobile outputs without duplicating configuration.

Default Profile Values

When you create a new profile through the web UI, FFmpegProfile.New() populates the following defaults:

Field	Default value
`ThreadCount`	`0` (auto — FFmpeg selects thread count)
`VideoFormat`	`H264`
`VideoProfile`	`high`
`VideoPreset`	(unset)
`AllowBFrames`	`false`
`BitDepth`	`EightBit` (8-bit)
`VideoBitrate`	`2000` kbps
`VideoBufferSize`	`4000` kbps
`TonemapAlgorithm`	`Linear`
`AudioFormat`	`Aac`
`AudioBitrate`	`192` kbps
`AudioBufferSize`	`384` kbps
`AudioChannels`	`2`
`AudioSampleRate`	`48` kHz
`NormalizeLoudnessMode`	`Off`
`DeinterlaceVideo`	`true`
`NormalizeFramerate`	`false`
`HardwareAcceleration`	`None` (software / CPU)
`NormalizeAudio`	`true`
`NormalizeVideo`	`true`
`NormalizeColors`	`true`
`ScalingBehavior`	`ScaleAndPad`
`PadMode`	`Software`
`QsvExtraHardwareFrames`	`64`

Field Reference

General

Name

string

required

A human-readable label for the profile (e.g. 1080p H264 NVENC). Displayed in channel settings and API responses.

ThreadCount

int

Number of CPU threads FFmpeg may use for software encoding. Set to 0 to let FFmpeg choose automatically based on available cores. Ignored when a hardware accelerator is active.

Resolution and Scaling

ResolutionId / Resolution

int / Resolution

References a resolution record (e.g. 1920×1080). Resolutions are managed at Settings → Resolutions. A profile’s resolution is the output resolution; source content is scaled to fit.

ScalingBehavior

enum

Controls how source video is fitted to the target resolution when the aspect ratios differ.

Value	Behaviour
`ScaleAndPad`	Scale to fit, add black padding bars (letterbox / pillarbox)
`Stretch`	Stretch to fill the frame, ignoring source aspect ratio
`Crop`	Scale to fill, crop the overflow edges

PadMode

FilterMode enum

Selects whether the padding filter runs on the GPU or CPU.

Value	Description
`HardwareIfPossible`	Use the GPU filter graph when hardware acceleration is active
`Software`	Always run padding in software (safer, slightly higher CPU overhead)

Video Encoding

VideoFormat

enum

The output video codec.

Value	Codec	Notes
`None`	No video	Audio-only output
`H264`	H.264 / AVC	Broadest client compatibility
`Hevc`	H.265 / HEVC	Better compression; requires client support
`Mpeg2Video`	MPEG-2	Legacy — useful for some IPTV/HDHR clients
`Av1`	AV1	High efficiency; limited hardware encoder support
`Copy`	Stream copy	Passes through the original codec without re-encoding

VideoProfile

string

The H.264/HEVC encoder profile (e.g. main, high, main10). Defaults to high for H.264. Controls which decoding features the encoder may use.

VideoPreset

string

An encoder speed/quality preset. Available presets depend on the active hardware accelerator and video format:

Context	Available presets
Software H.264 / H.265	`veryfast`
NVENC H.264 (8-bit)	`llhp` (low-latency high performance), `llhq` (low-latency high quality)
NVENC HEVC	`llhp`, `llhq`
QSV H.264 / HEVC	`veryfast`
All others	(none)

Leave unset to use the encoder’s built-in default.

AllowBFrames

bool

Permits the encoder to use B-frames (bidirectional predicted frames), which improve compression but can cause issues with some hardware decoders. Disabled by default.

BitDepth

enum

Colour bit depth of the encoded output.

Value	Description
`EightBit`	8-bit per channel — standard for most SDR content
`TenBit`	10-bit per channel — required for HDR10; wider colour gradients

VideoBitrate

int (kbps)

Target video bitrate in kilobits per second. The default 2000 kbps is appropriate for 720p H.264. Increase to 4000–8000 kbps for 1080p, and 15000+ for 4K HEVC.

VideoBufferSize

int (kbps)

The VBV (Video Buffering Verifier) buffer size in kbps. Controls how much bitrate can burst above the target. The default is 4000 kbps (2× the video bitrate). A typical rule of thumb is 1.5–2× VideoBitrate.

TonemapAlgorithm

enum

Algorithm used to map HDR (wide gamut / high dynamic range) content to SDR output colour space during transcoding. Has no effect on SDR source material.

Value	Description
`Linear`	Simple linear scale — default; preserves relative brightness
`Clip`	Hard clip — fastest, may lose highlight detail
`Gamma`	Gamma-curve mapping
`Reinhard`	Reinhard global operator — soft highlights, good general use
`Mobius`	Mobius transform — smooth transition
`Hable`	Filmic / Hable curve — strong highlight roll-off

DeinterlaceVideo

bool?

When true, applies a deinterlace filter to interlaced source content. Set to null to inherit the channel-level default. Recommended true for broadcast-sourced content.

Audio Encoding

AudioFormat

enum

The output audio codec.

Value	Codec	Notes
`None`	No audio	Video-only
`Aac`	AAC-LC	Default; universal client support
`Ac3`	Dolby AC-3	5.1 surround support; good for Kodi/Plex
`AacLatm`	AAC-LATM	Low-overhead AAC framing
`Copy`	Stream copy	Passes the original audio track without re-encoding

AudioBitrate

int (kbps)

Target audio bitrate in kbps. Default 192 kbps for stereo AAC. Use 384–448 kbps for AC-3 5.1.

AudioBufferSize

int (kbps)

Audio encoder buffer size in kbps. Default 384 kbps (2× audio bitrate).

AudioChannels

int

Number of output audio channels: 1 (mono), 2 (stereo), 6 (5.1), 8 (7.1). Default 2.

AudioSampleRate

int (kHz)

Output audio sample rate in kHz. Default 48 (standard for broadcast). Common values: 44 (CD), 48 (broadcast/streaming).

Normalisation

NormalizeAudio

bool

When true, ErsatzTV ensures all source audio tracks are re-encoded to the target format rather than being copied. Prevents format mismatches when inserting filler or concatenating items.

NormalizeVideo

bool

When true, ErsatzTV re-encodes video to the target format. Disabling this may cause playback artefacts if source clips use different codecs or parameters.

NormalizeColors

bool

When true, applies colour space normalisation (converts to BT.709 / SDR) so that content from different sources appears visually consistent.

NormalizeFramerate

bool

When true, converts all content to a consistent output framerate (as defined by the resolution record). Useful when mixing 24fps film and 30fps TV content on the same channel.

NormalizeLoudnessMode

enum

Controls integrated loudness normalisation of audio.

Value	Description
`Off`	No loudness processing — default
`LoudNorm`	Apply the FFmpeg `loudnorm` filter (EBU R128 two-pass normalisation)

TargetLoudness

double? (LUFS)

The integrated loudness target in LUFS (Loudness Units Full Scale) used when NormalizeLoudnessMode is LoudNorm. Typical values: -23.0 LUFS (EBU R128 broadcast), -16.0 LUFS (streaming).

Hardware Acceleration

HardwareAcceleration

HardwareAccelerationKind enum

Selects the GPU acceleration backend. See Hardware Acceleration for setup instructions per platform.

VaapiDisplay

string

DRM display path for VAAPI (e.g. /dev/dri/card0). Only used when HardwareAcceleration is Vaapi.

VaapiDriver

VaapiDriver enum

The VAAPI backend driver to request.

Value	Driver	Use case
`Default`	System default	Automatic selection
`iHD`	Intel Media Driver	Intel 6th gen+ (Skylake and newer)
`i965`	Intel VA-API Driver	Intel Haswell and older
`RadeonSI`	Mesa RadeonSI	AMD GPUs on Linux
`Nouveau`	Mesa Nouveau	NVIDIA on open-source driver

VaapiDevice

string

The DRM render device node for VAAPI (e.g. /dev/dri/renderD128). Must be accessible inside the Docker container.

QsvExtraHardwareFrames

int?

Extra surface frames allocated for Intel QSV. Increase this value (e.g. to 128) if you see errors like not enough surfaces during complex filter graphs. Default 64.

Managing Profiles

Open FFmpeg Profiles

Navigate to Settings → FFmpeg Profiles in the ErsatzTV web UI.

Create a Profile

Click Add FFmpeg Profile, fill in the fields described above, and click Save. The new profile is immediately available for assignment to channels.

Assign to a Channel

Open Channels, edit the desired channel, and select your profile from the FFmpeg Profile dropdown.

Edit or Delete

Profiles can be edited at any time. Changes take effect on the next scheduled segment or stream reconnect. A profile cannot be deleted while it is assigned to a channel.

REST API

Profiles are also manageable via the REST API:

Method	Endpoint	Description
`GET`	`/api/ffmpeg/profiles`	List all profiles (full detail)
`POST`	`/api/ffmpeg/profiles/new`	Create a new profile
`PUT`	`/api/ffmpeg/profiles/update`	Update an existing profile
`DELETE`	`/api/ffmpeg/delete/{id}`	Delete a profile by ID

Example — create a profile:

POST /api/ffmpeg/profiles/new
{
  "Name": "1080p H264 NVENC",
  "ThreadCount": 0,
  "HardwareAcceleration": "Nvenc",
  "ResolutionId": 5,
  "ScalingBehavior": "ScaleAndPad",
  "PadMode": "HardwareIfPossible",
  "VideoFormat": "H264",
  "VideoProfile": "high",
  "VideoPreset": "llhq",
  "AllowBFrames": false,
  "BitDepth": "EightBit",
  "VideoBitrate": 4000,
  "VideoBufferSize": 8000,
  "TonemapAlgorithm": "Reinhard",
  "AudioFormat": "Aac",
  "AudioBitrate": 192,
  "AudioBufferSize": 384,
  "NormalizeLoudnessMode": "Off",
  "AudioChannels": 2,
  "AudioSampleRate": 48,
  "NormalizeAudio": true,
  "NormalizeVideo": true,
  "NormalizeColors": true,
  "NormalizeFramerate": false,
  "DeinterlaceVideo": true
}

Hardware Acceleration

Set up NVENC, QSV, VAAPI, and other GPU accelerators.

Streaming Modes

Understand TS, HLS Segmenter, and HLS Direct output modes.

Get Started

Core Concepts

Configuration

Scheduling

Media Server Integration

Streaming & Clients

Operations

Configure FFmpeg Transcoding Profiles in ErsatzTV Legacy

Default Profile Values

Field Reference

General

Resolution and Scaling

Video Encoding

Audio Encoding

Normalisation

Hardware Acceleration

Managing Profiles

REST API

Hardware Acceleration

Streaming Modes

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Scheduling

Media Server Integration

Streaming & Clients

Operations

Documentation Index

​Default Profile Values

​Field Reference

​General

​Resolution and Scaling

​Video Encoding

​Audio Encoding

​Normalisation

​Hardware Acceleration

​Managing Profiles

​REST API

Hardware Acceleration

Streaming Modes

Build docs developers (and LLMs) love

Default Profile Values

Field Reference

General

Resolution and Scaling

Video Encoding

Audio Encoding

Normalisation

Hardware Acceleration

Managing Profiles

REST API