Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ErsatzTV/legacy/llms.txt

Use this file to discover all available pages before exploring further.

FFmpeg profiles define the full set of encoding parameters that ErsatzTV uses when transcoding media for a channel — including output resolution, video and audio codecs, bitrates, hardware acceleration, and normalization settings. The FFmpeg Profiles API gives you programmatic control over all profiles, and the Resolution API lets you look up a resolution record by its name string before creating or updating a profile.

​
GET /api/ffmpeg/profiles

Returns a list of all FFmpeg profiles with their complete configuration. Operation ID: GetFFmpegProfiles. 
curl http://localhost:8409/api/ffmpeg/profiles

​
Response Fields

​
id
integer
required
Internal database identifier for the profile.
​
name
string
required
Human-readable profile name.
​
threadCount
integer
required
Number of FFmpeg encoding threads. 0 means auto-detect.
​
hardwareAcceleration
string
required
Hardware acceleration mode. Enum values: None, Qsv, Nvenc, Vaapi, VideoToolbox, Amf, V4l2m2m, Rkmpp.
​
vaapiDisplay
string
required
VAAPI display string (relevant when hardwareAcceleration is Vaapi).
​
vaapiDriver
string
required
VAAPI driver selection. Enum values: Default, iHD, i965, RadeonSI, Nouveau.
​
vaapiDevice
string
required
Path to the VAAPI render device (e.g. /dev/dri/renderD128).
​
qsvExtraHardwareFrames
integer | null
required
Extra hardware frames for QSV; null when not applicable.
​
resolution
string
required
Output resolution as a name string (e.g. "1920x1080").
​
scalingBehavior
string
required
How source video is scaled to fit the output resolution. Enum values: ScaleAndPad, Stretch, Crop.
​
videoFormat
string
required
Output video codec. Enum values: None, H264, Hevc, Mpeg2Video, Av1, Copy.
​
videoProfile
string
required
Codec profile string (e.g. "high", "main").
​
videoPreset
string
required
Encoder preset string (e.g. "veryfast", "medium").
​
allowBFrames
boolean
required
Whether B-frames are permitted in the encoded output.
​
bitDepth
string
required
Output bit depth. Enum values: EightBit, TenBit.
​
videoBitrate
integer
required
Target video bitrate in kilobits per second.
​
videoBufferSize
integer
required
Video encoder buffer size in kilobits.
​
tonemapAlgorithm
string
required
HDR-to-SDR tone mapping algorithm. Enum values: Linear, Clip, Gamma, Reinhard, Mobius, Hable.
​
audioFormat
string
required
Output audio codec. Enum values: None, Aac, Ac3, AacLatm, Copy.
​
audioBitrate
integer
required
Target audio bitrate in kilobits per second.
​
audioBufferSize
integer
required
Audio encoder buffer size in kilobits.
​
normalizeLoudnessMode
string
required
Loudness normalization mode. Enum values: Off, LoudNorm.
​
audioChannels
integer
required
Number of output audio channels (e.g. 2 for stereo, 6 for 5.1).
​
audioSampleRate
integer
required
Output audio sample rate in Hz (e.g. 48000).
​
normalizeFramerate
boolean
required
When true, output framerate is normalized to a standard value.
​
deinterlaceVideo
boolean | null
required
When true, interlaced source video is deinterlaced. The value is null for profiles created before this field was introduced.

​
POST /api/ffmpeg/profiles/new

Creates a new FFmpeg profile. Operation ID: CreateFFmpegProfile.

​
Request Body

​
name
string
required
Display name for the new profile.
​
threadCount
integer
required
Number of FFmpeg threads. Use 0 for automatic.
​
hardwareAcceleration
string
required
Hardware acceleration kind. One of: None, Qsv, Nvenc, Vaapi, VideoToolbox, Amf, V4l2m2m, Rkmpp.
​
vaapiDisplay
string
required
VAAPI display string. Pass an empty string when not using VAAPI.
​
vaapiDriver
string
required
VAAPI driver. One of: Default, iHD, i965, RadeonSI, Nouveau.
​
vaapiDevice
string
required
VAAPI device path (e.g. /dev/dri/renderD128). Pass an empty string when not using VAAPI.
​
qsvExtraHardwareFrames
integer | null
Extra QSV hardware frames. Pass null when not using QSV.
​
resolutionId
integer
required
ID of the resolution record to use. Retrieve the ID via GET /api/ffmpeg/resolution/by-name/{name}.
​
scalingBehavior
string
required
Scaling behavior. One of: ScaleAndPad, Stretch, Crop.
​
videoFormat
string
required
Output video codec. One of: None, H264, Hevc, Mpeg2Video, Av1, Copy.
​
videoProfile
string
required
Codec profile string (e.g. "high").
​
videoPreset
string
required
Encoder preset string (e.g. "veryfast").
​
allowBFrames
boolean
required
Whether to allow B-frames.
​
bitDepth
string
required
Bit depth. One of: EightBit, TenBit.
​
videoBitrate
integer
required
Video bitrate in kbps.
​
videoBufferSize
integer
required
Video buffer size in kbps.
​
tonemapAlgorithm
string
required
Tonemap algorithm. One of: Linear, Clip, Gamma, Reinhard, Mobius, Hable.
​
audioFormat
string
required
Output audio codec. One of: None, Aac, Ac3, AacLatm, Copy.
​
audioBitrate
integer
required
Audio bitrate in kbps.
​
audioBufferSize
integer
required
Audio buffer size in kbps.
​
normalizeLoudnessMode
string
required
Loudness normalization. One of: Off, LoudNorm.
​
audioChannels
integer
required
Number of output audio channels.
​
audioSampleRate
integer
required
Output sample rate in Hz.
​
normalizeFramerate
boolean
required
Whether to normalize the output framerate.
​
deinterlaceVideo
boolean
required
Whether to deinterlace interlaced source video.
curl -X POST http://localhost:8409/api/ffmpeg/profiles/new \
  -H "Content-Type: application/json" \
  -d '{
    "name": "1080p Software",
    "threadCount": 0,
    "hardwareAcceleration": "None",
    "vaapiDisplay": "",
    "vaapiDriver": "Default",
    "vaapiDevice": "",
    "qsvExtraHardwareFrames": null,
    "resolutionId": 6,
    "scalingBehavior": "ScaleAndPad",
    "videoFormat": "H264",
    "videoProfile": "high",
    "videoPreset": "veryfast",
    "allowBFrames": true,
    "bitDepth": "EightBit",
    "videoBitrate": 2000,
    "videoBufferSize": 4000,
    "tonemapAlgorithm": "Hable",
    "audioFormat": "Aac",
    "audioBitrate": 192,
    "audioBufferSize": 384,
    "normalizeLoudnessMode": "Off",
    "audioChannels": 2,
    "audioSampleRate": 48000,
    "normalizeFramerate": false,
    "deinterlaceVideo": false
  }'
Returns 200 OK with the created profile result on success, or an HTTP Problem response on failure.

​
PUT /api/ffmpeg/profiles/update

Updates an existing FFmpeg profile. Operation ID: UpdateFFmpegProfile. The request body is identical to CreateFFmpegProfile with the addition of the profile ID.
​
fFmpegProfileId
integer
required
The ID of the FFmpeg profile to update.
All other fields are identical to CreateFFmpegProfile. 
curl -X PUT http://localhost:8409/api/ffmpeg/profiles/update \
  -H "Content-Type: application/json" \
  -d '{
    "fFmpegProfileId": 1,
    "name": "Default Updated",
    "threadCount": 4,
    "hardwareAcceleration": "None",
    "vaapiDisplay": "",
    "vaapiDriver": "Default",
    "vaapiDevice": "",
    "qsvExtraHardwareFrames": null,
    "resolutionId": 6,
    "scalingBehavior": "ScaleAndPad",
    "videoFormat": "H264",
    "videoProfile": "high",
    "videoPreset": "fast",
    "allowBFrames": true,
    "bitDepth": "EightBit",
    "videoBitrate": 3000,
    "videoBufferSize": 6000,
    "tonemapAlgorithm": "Hable",
    "audioFormat": "Aac",
    "audioBitrate": 192,
    "audioBufferSize": 384,
    "normalizeLoudnessMode": "Off",
    "audioChannels": 2,
    "audioSampleRate": 48000,
    "normalizeFramerate": false,
    "deinterlaceVideo": false
  }'
Returns 200 OK with the update result on success, or a Problem response on failure.

​
DELETE /api/ffmpeg/delete/

Deletes an FFmpeg profile by its integer ID. Operation ID: DeleteFFmpegProfile.
​
id
integer
required
The ID of the FFmpeg profile to delete.

​
Responses

StatusDescription
200 OKProfile deleted successfully.
409 ConflictProfile could not be deleted (e.g. it is still assigned to a channel).
curl -X DELETE http://localhost:8409/api/ffmpeg/delete/3

​
GET /api/ffmpeg/resolution/by-name/

Looks up a resolution record by its name string. This is useful for obtaining the resolutionId integer required when creating or updating a profile. Operation ID: GetResolutionByName.
​
name
string
required
The resolution name to look up, formatted as {width}x{height} (e.g. 1920x1080).
curl http://localhost:8409/api/ffmpeg/resolution/by-name/1920x1080

​
Response Fields

​
id
integer
required
Database ID of the resolution record. Use this as resolutionId when creating or updating a profile.
​
name
string
required
Resolution name string (e.g. "1920x1080").
​
width
integer
required
Width in pixels.
​
height
integer
required
Height in pixels.
​
isCustom
boolean
required
Whether this is a user-defined custom resolution (true) or a built-in preset (false).

​
Responses

StatusDescription
200 OKResolution found; body contains ResolutionViewModel.
404 Not FoundNo resolution with that name exists.
Common resolution name strings include 1920x1080, 1280x720, 3840x2160, and 720x480. If you need a resolution that does not exist in the database, create it first through the ErsatzTV UI before using the API.

Build docs developers (and LLMs) love

Get started for freeTalk to us