FFmpeg Profiles - ErsatzTV

Overview

FFmpeg profiles define transcoding settings for channel streams, including video/audio codecs, bitrates, resolution, hardware acceleration, and more. Each channel is assigned an FFmpeg profile that controls how media is processed for streaming.

Get All FFmpeg Profiles

Retrieve a list of all FFmpeg profiles.

GET /api/ffmpeg/profiles

Response

profiles

array

Array of FFmpeg profile objects

Show FFmpeg Profile Properties

integer

required

Unique profile identifier

name

string

required

Profile display name

threadCount

integer

required

Number of encoding threads (0 for auto)

hardwareAcceleration

string

required

Hardware acceleration type:

None - Software encoding
Qsv - Intel Quick Sync Video
Nvenc - NVIDIA NVENC
Vaapi - VA-API (Intel/AMD)
VideoToolbox - Apple VideoToolbox
Amf - AMD AMF
V4l2m2m - Video4Linux2
Rkmpp - Rockchip MPP

resolution

string

required

Target resolution name (e.g., “1920x1080”, “1280x720”)

scalingBehavior

string

required

How to handle aspect ratio:

ScaleAndPad - Scale and add letterboxing
Stretch - Stretch to fill
Crop - Crop to fill

videoFormat

string

required

Video codec:

None - No video
H264 - H.264/AVC
Hevc - H.265/HEVC
Mpeg2Video - MPEG-2
Av1 - AV1
Copy - Copy without transcoding

videoProfile

string

required

Codec profile (e.g., “main”, “high”)

videoPreset

string

required

Encoding preset (e.g., “medium”, “fast”, “slow”)

allowBFrames

boolean

required

Whether to allow B-frames in encoding

bitDepth

string

required

Color bit depth:

EightBit - 8-bit color
TenBit - 10-bit color

videoBitrate

integer

required

Target video bitrate in kbps

videoBufferSize

integer

required

Video buffer size in kbps

tonemapAlgorithm

string

required

HDR to SDR tone mapping:

Linear
Clip
Gamma
Reinhard
Mobius
Hable

audioFormat

string

required

Audio codec:

None - No audio
Aac - AAC
Ac3 - Dolby Digital (AC-3)
AacLatm - AAC LATM
Copy - Copy without transcoding

audioBitrate

integer

required

Target audio bitrate in kbps

audioBufferSize

integer

required

Audio buffer size in kbps

normalizeLoudnessMode

string

required

Audio loudness normalization:

Off - No normalization
LoudNorm - EBU R128 loudness normalization

audioChannels

integer

required

Number of audio channels (e.g., 2 for stereo, 6 for 5.1)

audioSampleRate

integer

required

Audio sample rate in Hz (e.g., 48000)

normalizeFramerate

boolean

required

Whether to normalize framerate to profile target

deinterlaceVideo

boolean

Whether to deinterlace interlaced video

vaapiDisplay

string

VA-API display (e.g., “/dev/dri/renderD128”)

vaapiDriver

string

VA-API driver:

Default
iHD - Intel iHD driver
i965 - Intel i965 driver
RadeonSI - AMD RadeonSI
Nouveau - NVIDIA Nouveau

vaapiDevice

string

VA-API device path

qsvExtraHardwareFrames

integer

Extra hardware frames for QSV

Example Request

curl http://localhost:8409/api/ffmpeg/profiles

Example Response

[
  {
    "id": 1,
    "name": "Default",
    "threadCount": 0,
    "hardwareAcceleration": "None",
    "vaapiDisplay": null,
    "vaapiDriver": "Default",
    "vaapiDevice": null,
    "qsvExtraHardwareFrames": null,
    "resolution": "1920x1080",
    "scalingBehavior": "ScaleAndPad",
    "videoFormat": "H264",
    "videoProfile": "high",
    "videoPreset": "medium",
    "allowBFrames": true,
    "bitDepth": "EightBit",
    "videoBitrate": 10000,
    "videoBufferSize": 20000,
    "tonemapAlgorithm": "Hable",
    "audioFormat": "Aac",
    "audioBitrate": 192,
    "audioBufferSize": 384,
    "normalizeLoudnessMode": "Off",
    "audioChannels": 2,
    "audioSampleRate": 48000,
    "normalizeFramerate": true,
    "deinterlaceVideo": true
  }
]

Create FFmpeg Profile

Create a new FFmpeg profile with transcoding settings.

POST /api/ffmpeg/profiles/new

Request Body

All fields from the FFmpeg profile object are required except hardware-specific fields.

Hardware acceleration fields (vaapiDisplay, vaapiDriver, vaapiDevice, qsvExtraHardwareFrames) are only required when using the corresponding hardwareAcceleration type.

Example Request

curl -X POST http://localhost:8409/api/ffmpeg/profiles/new \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HD Quality",
    "threadCount": 4,
    "hardwareAcceleration": "None",
    "vaapiDisplay": null,
    "vaapiDriver": "Default",
    "vaapiDevice": null,
    "qsvExtraHardwareFrames": null,
    "resolutionId": 2,
    "scalingBehavior": "ScaleAndPad",
    "videoFormat": "H264",
    "videoProfile": "high",
    "videoPreset": "medium",
    "allowBFrames": true,
    "bitDepth": "EightBit",
    "videoBitrate": 5000,
    "videoBufferSize": 10000,
    "tonemapAlgorithm": "Hable",
    "audioFormat": "Aac",
    "audioBitrate": 192,
    "audioBufferSize": 384,
    "normalizeLoudnessMode": "Off",
    "audioChannels": 2,
    "audioSampleRate": 48000,
    "normalizeFramerate": true,
    "deinterlaceVideo": true
  }'

Example Response

{
  "id": 5
}

Update FFmpeg Profile

Update an existing FFmpeg profile.

PUT /api/ffmpeg/profiles/update

Request Body

Same as create, but must include the profile fFmpegProfileId:

fFmpegProfileId

integer

required

ID of the profile to update

Example Request

curl -X PUT http://localhost:8409/api/ffmpeg/profiles/update \
  -H "Content-Type: application/json" \
  -d '{
    "fFmpegProfileId": 5,
    "name": "HD Quality Updated",
    "threadCount": 6,
    "videoBitrate": 6000,
    ...
  }'

Delete FFmpeg Profile

Delete an FFmpeg profile.

DELETE /api/ffmpeg/delete/{id}

Path Parameters

integer

required

ID of the profile to delete

Response

status

integer

200 OK - Profile deleted successfully
409 Conflict - Profile is in use by a channel

Example Request

curl -X DELETE http://localhost:8409/api/ffmpeg/delete/5

Profiles assigned to channels cannot be deleted. Assign channels to a different profile first.

Get Resolution by Name

Retrieve resolution details by name for use in profile creation.

GET /api/ffmpeg/resolution/by-name/{name}

Path Parameters

name

string

required

Resolution name (e.g., “1920x1080”, “1280x720”)

Response

integer

Resolution ID for use in profile creation

name

string

Resolution name

width

integer

Horizontal resolution in pixels

height

integer

Vertical resolution in pixels

isCustom

boolean

Whether this is a custom resolution

Example Request

curl http://localhost:8409/api/ffmpeg/resolution/by-name/1920x1080

Example Response

{
  "id": 2,
  "name": "1920x1080",
  "width": 1920,
  "height": 1080,
  "isCustom": false
}

Hardware Acceleration

ErsatzTV supports multiple hardware acceleration platforms:

Intel QSV

Quick Sync Video for Intel CPUs with integrated graphics

NVIDIA NVENC

Hardware encoding on NVIDIA GPUs

VA-API

Video Acceleration API for Intel and AMD GPUs

Apple VideoToolbox

Hardware acceleration on macOS and iOS

AMD AMF

Advanced Media Framework for AMD GPUs

Video4Linux2

Hardware encoding on embedded Linux devices

Hardware Acceleration Setup

Hardware acceleration requires proper drivers and device access. See Hardware Acceleration Guide for setup instructions.

VA-API Configuration

For VA-API acceleration:

Display: /dev/dri/renderD128 (or your device path)
Driver: Select based on your GPU
- iHD - Modern Intel GPUs
- i965 - Older Intel GPUs
- RadeonSI - AMD GPUs
Device: Usually same as display

QSV Configuration

Set qsvExtraHardwareFrames to 64 or higher for complex content
Requires Intel CPU with integrated graphics
Best performance with recent Intel generations

Video Codecs

H.264 (AVC)

Most compatible codec
Wide device support
Profiles: baseline, main, high
Recommended for general use

H.265 (HEVC)

Better compression than H.264
Lower bitrate for same quality
Requires newer devices/players
Profiles: main, main10

MPEG-2

Legacy codec for compatibility
Larger file sizes
Universal support
Use for older devices

AV1

Next-generation codec
Best compression efficiency
Limited hardware support
CPU-intensive encoding

Copy Mode

No transcoding
Source stream copied directly
Fastest, lowest CPU usage
Requires compatible source

Audio Codecs

AAC

Standard for modern streaming
Good quality at low bitrates
Wide device support
Recommended: 192 kbps for stereo

AC-3 (Dolby Digital)

Supports multichannel audio
Compatible with most devices
Higher bitrates than AAC
Recommended: 384 kbps for 5.1

AAC LATM

AAC variant for MPEG-TS streams
Use for IPTV/broadcast applications

Copy Mode

No audio transcoding
Preserves original audio
Requires compatible source and client

Bitrate Guidelines

Video Bitrates

Resolution	H.264	H.265	Use Case
1920x1080	8-12 Mbps	6-9 Mbps	Full HD
1280x720	4-6 Mbps	3-5 Mbps	HD
854x480	2-3 Mbps	1.5-2.5 Mbps	SD
640x480	1-2 Mbps	0.8-1.5 Mbps	Low quality

Audio Bitrates

Configuration	Bitrate	Use Case
Stereo (2.0)	128-192 kbps	Standard quality
Stereo (2.0)	256 kbps	High quality
5.1 Surround	384-448 kbps	Home theater
Mono	64-96 kbps	Voice/podcast

Buffer size should typically be 2x the target bitrate for smooth streaming.

Best Practices

Test Profiles

Test new profiles with sample content before production use

Match Source

Target resolution and bitrate appropriate for your source content

Hardware First

Use hardware acceleration when available for better performance

Profile Per Use

Create different profiles for different quality tiers or device types

Troubleshooting

Transcoding Errors

If streams fail to start:

Check FFmpeg logs for errors
Verify hardware acceleration is properly configured
Test with software encoding (hardwareAcceleration: "None")
Ensure FFmpeg has required codecs

Poor Quality

If stream quality is poor:

Increase videoBitrate and videoBufferSize
Use a slower videoPreset (e.g., “slow” instead of “fast”)
Consider higher resolution
Check source quality

High CPU Usage

If CPU usage is too high:

Enable hardware acceleration
Reduce resolution or bitrate
Use faster videoPreset
Increase threadCount
Consider using H.264 instead of H.265/AV1

Channels API - Assign profiles to channels
Sessions API - Monitor active transcoding sessions

Next Steps

Hardware Acceleration

Configure GPU-accelerated transcoding

Transcoding Guide

Learn about transcoding concepts and optimization

Overview

Endpoints

IPTV & Streaming

​Overview

​Get All FFmpeg Profiles

​Response

​Example Request

​Example Response

​Create FFmpeg Profile

​Request Body

​Example Request

​Example Response

​Update FFmpeg Profile

​Request Body

​Example Request

​Delete FFmpeg Profile

​Path Parameters

​Response

​Example Request

​Get Resolution by Name

​Path Parameters

​Response

​Example Request

​Example Response

​Hardware Acceleration

Intel QSV

NVIDIA NVENC

VA-API

Apple VideoToolbox

AMD AMF

Video4Linux2

​Hardware Acceleration Setup

​VA-API Configuration

​QSV Configuration

​Video Codecs

​H.264 (AVC)

​H.265 (HEVC)

​MPEG-2

​AV1

​Copy Mode

​Audio Codecs

​AAC

​AC-3 (Dolby Digital)

​AAC LATM

​Copy Mode

​Bitrate Guidelines

​Video Bitrates

​Audio Bitrates

​Best Practices

Test Profiles

Match Source

Hardware First

Profile Per Use

​Troubleshooting

​Transcoding Errors

​Poor Quality

​High CPU Usage

​Related Endpoints

​Next Steps

Hardware Acceleration

Transcoding Guide

Build docs developers (and LLMs) love

Overview

Get All FFmpeg Profiles

Response

Example Request

Example Response

Create FFmpeg Profile

Request Body

Example Request

Example Response

Update FFmpeg Profile

Request Body

Example Request

Delete FFmpeg Profile

Path Parameters

Response

Example Request

Get Resolution by Name

Path Parameters

Response

Example Request

Example Response

Hardware Acceleration

Hardware Acceleration Setup

VA-API Configuration

QSV Configuration

Video Codecs

H.264 (AVC)

H.265 (HEVC)

MPEG-2

AV1

Copy Mode

Audio Codecs

AAC

AC-3 (Dolby Digital)

AAC LATM

Copy Mode

Bitrate Guidelines

Video Bitrates

Audio Bitrates

Best Practices

Troubleshooting

Transcoding Errors

Poor Quality

High CPU Usage

Related Endpoints

Next Steps