FFmpeg Profiles API — Create and Manage Profiles

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

[
  {
    "id": 1,
    "name": "Default",
    "threadCount": 0,
    "hardwareAcceleration": "None",
    "vaapiDisplay": "",
    "vaapiDriver": "Default",
    "vaapiDevice": "/dev/dri/renderD128",
    "qsvExtraHardwareFrames": null,
    "resolution": "1920x1080",
    "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
  }
]

Response Fields

integer

required

Internal database identifier for the profile.

string

required

Human-readable profile name.

integer

required

Number of FFmpeg encoding threads. 0 means auto-detect.

string

required

Hardware acceleration mode. Enum values: None, Qsv, Nvenc, Vaapi, VideoToolbox, Amf, V4l2m2m, Rkmpp.

string

required

VAAPI display string (relevant when hardwareAcceleration is Vaapi).

string

required

VAAPI driver selection. Enum values: Default, iHD, i965, RadeonSI, Nouveau.

string

required

Path to the VAAPI render device (e.g. /dev/dri/renderD128).

integer | null

required

Extra hardware frames for QSV; null when not applicable.

string

required

Output resolution as a name string (e.g. "1920x1080").

string

required

How source video is scaled to fit the output resolution. Enum values: ScaleAndPad, Stretch, Crop.

string

required

Output video codec. Enum values: None, H264, Hevc, Mpeg2Video, Av1, Copy.

string

required

Codec profile string (e.g. "high", "main").

string

required

Encoder preset string (e.g. "veryfast", "medium").

boolean

required

Whether B-frames are permitted in the encoded output.

string

required

Output bit depth. Enum values: EightBit, TenBit.

integer

required

Target video bitrate in kilobits per second.

integer

required

Video encoder buffer size in kilobits.

string

required

HDR-to-SDR tone mapping algorithm. Enum values: Linear, Clip, Gamma, Reinhard, Mobius, Hable.

string

required

Output audio codec. Enum values: None, Aac, Ac3, AacLatm, Copy.

integer

required

Target audio bitrate in kilobits per second.

integer

required

Audio encoder buffer size in kilobits.

string

required

Loudness normalization mode. Enum values: Off, LoudNorm.

integer

required

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

integer

required

Output audio sample rate in Hz (e.g. 48000).

boolean

required

When true, output framerate is normalized to a standard value.

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

string

required

Display name for the new profile.

integer

required

Number of FFmpeg threads. Use 0 for automatic.

string

required

Hardware acceleration kind. One of: None, Qsv, Nvenc, Vaapi, VideoToolbox, Amf, V4l2m2m, Rkmpp.

string

required

VAAPI display string. Pass an empty string when not using VAAPI.

string

required

VAAPI driver. One of: Default, iHD, i965, RadeonSI, Nouveau.

string

required

VAAPI device path (e.g. /dev/dri/renderD128). Pass an empty string when not using VAAPI.

integer | null

Extra QSV hardware frames. Pass null when not using QSV.

integer

required

ID of the resolution record to use. Retrieve the ID via GET /api/ffmpeg/resolution/by-name/{name}.

string

required

Scaling behavior. One of: ScaleAndPad, Stretch, Crop.

string

required

Output video codec. One of: None, H264, Hevc, Mpeg2Video, Av1, Copy.

string

required

Codec profile string (e.g. "high").

string

required

Encoder preset string (e.g. "veryfast").

boolean

required

Whether to allow B-frames.

string

required

Bit depth. One of: EightBit, TenBit.

integer

required

Video bitrate in kbps.

integer

required

Video buffer size in kbps.

string

required

Tonemap algorithm. One of: Linear, Clip, Gamma, Reinhard, Mobius, Hable.

string

required

Output audio codec. One of: None, Aac, Ac3, AacLatm, Copy.

integer

required

Audio bitrate in kbps.

integer

required

Audio buffer size in kbps.

string

required

Loudness normalization. One of: Off, LoudNorm.

integer

required

Number of output audio channels.

integer

required

Output sample rate in Hz.

boolean

required

Whether to normalize the output framerate.

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.

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.

integer

required

The ID of the FFmpeg profile to delete.

Responses

Status	Description
`200 OK`	Profile deleted successfully.
`409 Conflict`	Profile 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.

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

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

Response Fields

integer

required

Database ID of the resolution record. Use this as resolutionId when creating or updating a profile.

string

required

Resolution name string (e.g. "1920x1080").

integer

required

Width in pixels.

integer

required

Height in pixels.

boolean

required

Whether this is a user-defined custom resolution (true) or a built-in preset (false).

Responses

Status	Description
`200 OK`	Resolution found; body contains `ResolutionViewModel`.
`404 Not Found`	No 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.

Overview

Endpoints

FFmpeg Profiles API — Create and Manage Profiles

GET /api/ffmpeg/profiles

Response Fields

POST /api/ffmpeg/profiles/new

Request Body

PUT /api/ffmpeg/profiles/update

DELETE /api/ffmpeg/delete/

Responses

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

Response Fields

Responses

​GET /api/ffmpeg/profiles

​Response Fields

​POST /api/ffmpeg/profiles/new

​Request Body

​PUT /api/ffmpeg/profiles/update

​DELETE /api/ffmpeg/delete/

​Responses

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

​Response Fields

​Responses

GET /api/ffmpeg/profiles

Response Fields

POST /api/ffmpeg/profiles/new

Request Body

PUT /api/ffmpeg/profiles/update

DELETE /api/ffmpeg/delete/

Responses

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

Response Fields

Responses