Skip to content

Encoding profiles

Jump to bottom
Gustav Grusell edited this page Dec 12, 2025 · 2 revisions

Encore Profile Configuration Guide

What Are Profiles?

Profiles are configuration templates that tell Encore how to transcode your media files. Each profile defines one or more output files to generate from your input video, including different video qualities, audio formats, and thumbnails.

Profiles are typically stored in YAML or JSON format and loaded when needed.

For information on how to submit jobs that use these profiles, see the API and Job Submission guide. For details on configuring inputs, see the Input Configuration guide.

Profile Structure

A profile consists of:

  • name: Unique identifier for the profile
  • description: Human-readable description of what this profile does
  • encodes: List of encoders that produce outputs (video, audio, thumbnails)
  • scaling: Scaling algorithm (default: "bicubic")
  • deinterlaceFilter: Deinterlacing filter (default: "yadif")
  • filterSettings: Advanced FFmpeg `filter configuration
  • joinSegmentParams: Optional parameters for joining segments when using segmented encoding

Encoder Types

Video Encoders

Video encoders transform your input video into output files with specific codecs, resolutions, and quality settings. All video encoders support:

  • Scaling: Resize to specific dimensions
  • Aspect Ratio Control: Crop or pad to target aspect ratios
  • Custom FFmpeg Filters: Apply additional video processing
  • Audio Muxing: Include one or more audio tracks
  • Debug Overlays: Overlay encoder name for testing

Common Video Properties

Property Description Example Values
width Target width in pixels (omit for auto) 1920, 1280, null
height Target height in pixels (omit for auto) 1080, 720, null
twoPass Enable two-pass encoding true, false
params FFmpeg parameters {"b:v": "5000k"}
filters Custom FFmpeg video filters ["hqdn3d", "unsharp"]
audioEncode Single audio track (deprecated) See AudioEncode
audioEncodes List of audio tracks to include See AudioEncode
suffix Output filename suffix "_1080p", "_4k"
format Container format "mp4", "mkv", "webm"
codec Video codec "libx264", "libx265"
inputLabel Which input to encode (default: "main") "main"
optional Skip instead of fail if input missing true, false
enabled Enable/disable this encoder true, false
cropTo Crop to aspect ratio before scaling "16:9", "4:3"
padTo Add letterboxing/pillarboxing to achieve aspect ratio "16:9", "21:9"

Common Video Encoding Parameters

These FFmpeg parameters go in the params section and are commonly used across all video encoders:

Parameter Description Example Values
b:v Video bitrate "5000k", "15000k"
maxrate Maximum bitrate for VBV "5350k"
bufsize VBV buffer size "10000k"
crf Constant rate factor (quality) "23", "28"
r Output frame rate 25, 30, "24000/1001"
fps_mode Frame rate mode "cfr" (constant)
pix_fmt Pixel format "yuv420p", "yuv420p10le"
force_key_frames Keyframe placement expression "expr:not(mod(n,96))"
profile:v Codec profile "high", "main10"
level Codec level "4.0", "4.1"
preset Encoding speed/quality tradeoff "medium", "slow"
tag:v Video stream tag "hvc1" (for HEVC compatibility)
movflags MOV/MP4 container flags "faststart"
g GOP size (keyframe interval) "96", "240"

X264Encode - H.264/AVC Video

Use X264Encode for encoding H.264/AVC video with the libx264 encoder.

{
  "type": "X264Encode",
  "width": 1920,
  "height": 1080,
  "twoPass": true,
  "suffix": "_1080p",
  "format": "mp4",
  "params": {
    "b:v": "5000k",
    "maxrate": "5350k",
    "bufsize": "10000k",
    "r": 25,
    "fps_mode": "cfr",
    "pix_fmt": "yuv420p",
    "force_key_frames": "expr:not(mod(n,96))",
    "profile:v": "high",
    "level": "4.1"
  },
  "x264-params": {
    "deblock": "0,0",
    "aq-mode": "1",
    "bframes": "6",
    "ref": "4",
    "rc-lookahead": "60"
  }
}

Parameter Sections:

  • params: Standard FFmpeg parameters including bitrate, frame rate, profile, level, preset, and pixel format
  • x264-params: libx264-specific encoder options that get passed as colon-separated key=value pairs

Common x264-params Options:

Parameter Description Example Values
deblock Deblocking filter strength "0,0", "-1,-1"
aq-mode Adaptive quantization mode "1", "2"
aq-strength AQ strength "1.0"
bframes Max consecutive B-frames "6", "3"
b-adapt B-frame decision method "2"
ref Reference frames "4", "6"
rc-lookahead Lookahead buffer size "60", "40"
keyint Maximum GOP size "192"
keyint_min Minimum GOP size "96"
scenecut Scene change detection threshold "40"
me Motion estimation method "hex", "umh"
subme Subpixel motion estimation quality "9", "7"
cabac Enable CABAC entropy coding "1"
trellis Trellis quantization "2"
partitions Partitions to analyze "all"
direct Direct MV prediction mode "auto"

X265Encode - H.265/HEVC Video

Use X265Encode for H.265/HEVC video encoded with the libx265 encoder.

{
  "type": "X265Encode",
  "width": 3840,
  "height": 2160,
  "twoPass": true,
  "suffix": "_4k",
  "format": "mp4",
  "params": {
    "b:v": "15000k",
    "maxrate": "22500k",
    "bufsize": "30000k",
    "r": 25,
    "pix_fmt": "yuv420p10le",
    "profile:v": "main10",
    "tag:v": "hvc1",
    "force_key_frames": "expr:not(mod(n,96))"
  },
  "x265-params": {
    "min-keyint": "96",
    "keyint": "96",
    "level-idc": "4.1",
    "bframes": "6",
    "ref": "4",
    "aq-mode": "2",
    "rd": "4"
  }
}

Parameter Sections:

  • params: Standard FFmpeg parameters including bitrate, profile, pixel format, and tag
  • x265-params: libx265-specific encoder options

Common x265-params Options:

Parameter Description Example Values
keyint Maximum GOP size "96"
min-keyint Minimum GOP size "96"
level-idc HEVC level "4.1", "5.1"
bframes Max consecutive B-frames "6", "4"
b-adapt B-frame decision method "2"
ref Reference frames "4"
rc-lookahead Lookahead buffer size "25", "60"
aq-mode Adaptive quantization mode "2"
rd RD level for mode decision "4"
me Motion estimation method "star", "hex"
subme Subpixel motion estimation "3"
ctu Max CTU size "64"
pmode Parallel mode decision "1"
sao Sample adaptive offset "1"
weightp Weighted prediction "1"
cutree CU tree optimization "1"

VideoEncode - Generic Video Encoder

Use VideoEncode for any FFmpeg-supported codec not covered by X264 or X265.

{
  "type": "VideoEncode",
  "width": 1280,
  "height": 720,
  "twoPass": false,
  "codec": "libvpx-vp9",
  "suffix": "_720p_vp9",
  "format": "webm",
  "params": {
    "b:v": "2500k",
    "crf": "31",
    "g": "240"
  }
}

Supported Codecs: Any codec supported by the FFmpeg executable used

Video Filter Processing Order

When encoding video, filters are applied in this order:

  1. Crop (if cropTo is set) - Crops to target aspect ratio
  2. Scale (if width/height are set) - Resizes video
  3. Set SAR - Sets sample aspect ratio to 1:1
  4. Pad (if padTo is set) - Adds letterboxing/pillarboxing
  5. Custom filters (from filters property)
  6. Debug overlay (if enabled in job)

Audio Encoders

AudioEncode - Advanced Audio with Channel Remapping

Full-featured audio encoder with channel layout conversion, audio mixing presets, and dialogue enhancement.

{
  "type": "AudioEncode",
  "codec": "aac",
  "bitrate": "192k",
  "samplerate": 48000,
  "channelLayout": "5.1",
  "suffix": "_aac_51",
  "audioMixPreset": "default",
  "dialogueEnhancement": {
    "enabled": false
  }
}

Properties:

Property Default Description
codec "aac" Audio codec to use
bitrate (auto) Audio bitrate (e.g., "192k", "128k")
samplerate 48000 Sample rate in Hz
channelLayout "stereo" Target channel layout
suffix Auto-generated Output filename suffix
params (empty) Additional FFmpeg parameters
filters (empty) Custom audio filters
audioMixPreset "default" Audio mix preset to use
dialogueEnhancement (disabled) Dialogue enhancement settings
optional false Skip if input missing
format "mp4" Container format
inputLabel "audio" Which input to encode
enabled true Enable/disable encoder

Audio Codec Notes:

The aac codec uses FFmpeg's native AAC encoder, which is available in standard FFmpeg builds. The libfdk_aac codec offers slightly better quality but requires a custom FFmpeg build with non-free libraries enabled (using --enable-libfdk-aac --enable-nonfree configure flags). For most use cases, the native aac encoder produces excellent results.

Supported Channel Layouts: See Channel layouts

Audio Mix Presets:

Audio mix presets define how to downmix or upmix between channel layouts. The preset name references a configuration that maps input layouts to output layouts with specific pan/mixing rules. For more info see Audiomix presets.

SimpleAudioEncode - Basic Audio Encoding

Simple audio encoder that preserves the input's channel layout without any remapping or processing.

{
  "type": "SimpleAudioEncode",
  "codec": "aac",
  "bitrate": "128k",
  "samplerate": 48000,
  "suffix": "_aac",
  "format": "mp4"
}

Properties:

Property Default Description
codec "aac" Audio codec
bitrate (auto) Audio bitrate
samplerate (input rate) Sample rate in Hz
suffix Auto-generated Output filename suffix
params (empty) Additional FFmpeg parameters
optional false Skip if input missing
format "mp4" Container format
inputLabel "audio" Which input to encode
enabled true Enable/disable encoder

When to Use:

  • You want to re-encode audio without changing channel layout
  • No need for downmixing or upmixing
  • Faster processing than AudioEncode
  • Creating lossless audio outputs (e.g., FLAC)

Thumbnail Generators

ThumbnailEncode - Individual Thumbnail Images

Generates individual JPEG thumbnail images at specified points in the video.

{
  "type": "ThumbnailEncode",
  "percentages": [25, 50, 75],
  "thumbnailWidth": -2,
  "thumbnailHeight": 1080,
  "quality": 5,
  "suffix": "_thumb",
  "suffixZeroPad": 2,
  "decodeOutput": 0
}

Properties:

Property Default Description
percentages [25, 50, 75] Percentage points for thumbnail extraction
thumbnailWidth -2 Width in pixels (-2 = auto maintain aspect)
thumbnailHeight 1080 Height in pixels
quality 5 JPEG quality (1-31, lower = better quality)
suffix "_thumb" Output filename suffix
suffixZeroPad 2 Zero padding for numbering (e.g., 01, 02)
inputLabel "video" Which input to use
optional false Skip if input missing
enabled true Enable/disable encoder
intervalSeconds (none) Generate at fixed intervals instead of percentages
decodeOutput (none) Index of decode output stream to use

Thumbnail Selection Modes:

  1. Percentage-based (default):

    {
  "percentages": [10, 25, 50, 75, 90]
}

    Generates thumbnails at 10%, 25%, 50%, 75%, and 90% of video duration.

  2. Interval-based:

    {
  "intervalSeconds": 10.0
}

    Generates a thumbnail every 10 seconds.

  3. Single frame: Set via job parameter thumbnailTime for a specific timestamp.

The decodeOutput Parameter:

When a job produces multiple decoded video streams (such as when using segmented encoding or multiple inputs), the decodeOutput parameter specifies which stream index to use for thumbnail generation. A value of 0 selects the first decoded stream. This is useful when you want thumbnails from a specific quality level or input source.

Output Files:

  • Named as: {baseName}{suffix}{number}.jpg
  • Example: myvideo_thumb01.jpg, myvideo_thumb02.jpg, myvideo_thumb03.jpg

Limitations:

  • Not supported when using segmented encoding

ThumbnailMapEncode - Sprite Sheet / Tile Map

Generates a single sprite sheet image containing multiple thumbnail tiles, ideal for video player scrubbing/preview interfaces.

{
  "type": "ThumbnailMapEncode",
  "tileWidth": 160,
  "tileHeight": 90,
  "cols": 12,
  "rows": 20,
  "quality": 5,
  "suffix": "_thumbnail_map",
  "format": "jpg",
  "decodeOutput": 0
}

Properties:

Property Default Description
tileWidth 160 Width of each tile in pixels
tileHeight 90 Height of each tile in pixels
cols 12 Number of columns in the grid
rows 20 Number of rows in the grid
quality 5 JPEG quality (1-31, lower = better quality)
optional true Skip if input missing
enabled true Enable/disable encoder
suffix Auto-generated Output filename suffix
format "jpg" Output format
inputLabel "video" Which input to use
decodeOutput (none) Index of decode output stream to use

How It Works:

  1. Calculates interval: video_duration / (cols x rows)
  2. Extracts frames at each interval point
  3. Scales and pads each frame to tile dimensions
  4. Arranges all tiles into a single grid image

Output:

  • Single image file: {baseName}{suffix}.{format}
  • Total thumbnails: cols x rows (e.g., 12x20 = 240 thumbnails)
  • Final image dimensions: tileWidth x cols by tileHeight x rows

Common Use Case:

Video players can load one sprite sheet and display hover previews by calculating tile position:

col = floor(currentTime / interval) % cols
row = floor(currentTime / interval / cols)

Then display the region at (col * tileWidth, row * tileHeight) with size (tileWidth, tileHeight).

Limitations:

  • Not supported when using segmented encoding

Filter Settings

Advanced users can customize FFmpeg filters inserted by encore, mainly useful for using hardware accelerated filters when doing hardware encoding. See also Hardware accelration guide.

{
  "filterSettings": {
    "splitFilter": "split",
    "scaleFilter": "scale_cuda",
    "scaleFilterParams": {
      "force_original_aspect_ratio": "decrease",
      "force_divisible_by": "2"
    },
    "cropFilter": "crop",
    "padFilter": "pad_cuda"
  }
}

Complete Profile Example

Here's a comprehensive profile that generates multiple outputs:

{
  "name": "multiformat-hd",
  "description": "Multi-format HD transcoding with audio variants and thumbnails",
  "scaling": "lanczos",
  "deinterlaceFilter": "yadif",
  "encodes": [
    {
      "type": "X264Encode",
      "width": 1920,
      "height": 1080,
      "twoPass": true,
      "suffix": "_1080p",
      "format": "mp4",
      "params": {
        "b:v": "5000k",
        "maxrate": "5350k",
        "bufsize": "10000k",
        "r": 25,
        "fps_mode": "cfr",
        "pix_fmt": "yuv420p",
        "force_key_frames": "expr:not(mod(n,96))",
        "profile:v": "high",
        "level": "4.1"
      },
      "x264-params": {
        "deblock": "0,0",
        "aq-mode": "1",
        "bframes": "6",
        "ref": "4"
      },
      "audioEncodes": [
        {
          "type": "AudioEncode",
          "codec": "aac",
          "bitrate": "192k",
          "channelLayout": "5.1",
          "suffix": "_aac_51"
        },
        {
          "type": "AudioEncode",
          "codec": "aac",
          "bitrate": "128k",
          "channelLayout": "stereo",
          "suffix": "_aac_stereo"
        }
      ]
    },
    {
      "type": "X264Encode",
      "width": 1280,
      "height": 720,
      "twoPass": true,
      "suffix": "_720p",
      "format": "mp4",
      "params": {
        "b:v": "2800k",
        "r": 25,
        "fps_mode": "cfr",
        "pix_fmt": "yuv420p",
        "profile:v": "main",
        "level": "3.1",
        "crf": "23"
      },
      "audioEncode": {
        "type": "AudioEncode",
        "codec": "aac",
        "bitrate": "128k",
        "channelLayout": "stereo"
      }
    },
    {
      "type": "SimpleAudioEncode",
      "codec": "flac",
      "suffix": "_audio_lossless",
      "format": "flac"
    },
    {
      "type": "ThumbnailEncode",
      "percentages": [10, 25, 50, 75, 90],
      "thumbnailHeight": 720,
      "quality": 3,
      "decodeOutput": 0
    },
    {
      "type": "ThumbnailMapEncode",
      "tileWidth": 160,
      "tileHeight": 90,
      "cols": 10,
      "rows": 10,
      "decodeOutput": 0
    }
  ]
}

This profile generates:

  • 1080p H.264 video with both 5.1 surround and stereo audio tracks
  • 720p H.264 video with stereo audio
  • FLAC lossless audio file (preserves original channels)
  • 5 thumbnail images at 10%, 25%, 50%, 75%, and 90%
  • Thumbnail sprite sheet with 100 tiles (10x10 grid)

Advanced Configuration

Portrait Video Handling

Encore can automatically handle portrait videos by swapping width/height dimensions. When enabled in the encoding configuration, portrait videos (aspect ratio < 1.0) will have their width and height swapped to match the profile's landscape dimensions.

This respects video rotation metadata and ensures portrait videos are properly scaled.

Aspect Ratio Control

Control output aspect ratio with crop and pad operations:

Crop to aspect ratio:

{
  "cropTo": "16:9"
}

Crops the input to 16:9 before scaling. Useful for removing pillarboxing or letterboxing from source.

Pad to aspect ratio:

{
  "padTo": "16:9"
}

Adds letterboxing or pillarboxing after scaling to achieve exactly 16:9. Useful for ensuring consistent aspect ratios.

Processing order: Input -> Crop -> Scale -> Pad -> Output

Example - Converting 4:3 to 16:9:

{
  "width": 1920,
  "height": 1080,
  "padTo": "16:9"
}

Scales the 4:3 video and adds pillarboxing to create 16:9 output.

Optional Outputs

Mark outputs as optional to prevent job failure when inputs are missing:

{
  "type": "ThumbnailEncode",
  "optional": true,
  "percentages": [25, 50, 75]
}

If the video input is missing, Encore will skip this encoder and continue with other outputs rather than failing the entire job.

Conditional Outputs

Enable or disable outputs at runtime:

{
  "type": "X265Encode",
  "enabled": false,
  "width": 3840,
  "height": 2160
}

Useful for:

  • A/B testing encoding settings
  • Environment-specific outputs (production vs testing)
  • Temporarily disabling expensive encodes
  • Configuration-based output selection

Example Profiles for Common Use Cases

Streaming ABR Ladder

{
  "name": "streaming-abr",
  "description": "Adaptive bitrate ladder for HLS/DASH streaming",
  "encodes": [
    {
      "type": "X264Encode",
      "width": 1920,
      "height": 1080,
      "twoPass": true,
      "suffix": "_1080p",
      "format": "mp4",
      "params": {
        "b:v": "5000k",
        "maxrate": "5350k",
        "bufsize": "10000k",
        "r": 25,
        "fps_mode": "cfr",
        "pix_fmt": "yuv420p",
        "profile:v": "high",
        "level": "4.1"
      }
    },
    {
      "type": "X264Encode",
      "width": 1280,
      "height": 720,
      "twoPass": true,
      "suffix": "_720p",
      "format": "mp4",
      "params": {
        "b:v": "2800k",
        "maxrate": "3000k",
        "bufsize": "5600k",
        "profile:v": "main",
        "level": "3.1"
      }
    },
    {
      "type": "X264Encode",
      "width": 854,
      "height": 480,
      "twoPass": true,
      "suffix": "_480p",
      "format": "mp4",
      "params": {
        "b:v": "1400k",
        "maxrate": "1500k",
        "bufsize": "2800k",
        "profile:v": "main",
        "level": "3.1"
      }
    }
  ]
}

Archive/Mezzanine

{
  "name": "archive-mezzanine",
  "description": "High-quality archival format",
  "encodes": [
    {
      "type": "VideoEncode",
      "codec": "prores_ks",
      "format": "mov",
      "suffix": "_prores",
      "params": {
        "profile:v": "3",
        "vendor": "apl0"
      },
      "audioEncode": {
        "type": "SimpleAudioEncode",
        "codec": "pcm_s24le"
      }
    }
  ]
}

Social Media

{
  "name": "social-media",
  "description": "Optimized for social media platforms",
  "encodes": [
    {
      "type": "X264Encode",
      "width": 1280,
      "height": 720,
      "twoPass": false,
      "suffix": "_social",
      "format": "mp4",
      "padTo": "16:9",
      "params": {
        "crf": "23",
        "preset": "fast",
        "movflags": "faststart"
      },
      "audioEncode": {
        "type": "AudioEncode",
        "codec": "aac",
        "bitrate": "128k",
        "channelLayout": "stereo"
      }
    }
  ]
}

Hardware Encoding (NVENC)

This example uses NVIDIA GPU acceleration for HEVC encoding. It requires CUDA hardware decoding to be specified on the input.

name: nvenc-hevc
description: HEVC NVENC encoding with hardware scaling
scaling: bicubic
filterSettings:
  scaleFilter: scale_cuda
  scaleFilterParams:
    format: p010le
encodes:
  - type: VideoEncode
    codec: hevc_nvenc
    format: mp4
    suffix: _hevc_1080p
    twoPass: false
    height: 1080
    params:
      b:v: 4500k
      maxrate: 6750k
      bufsize: 9000k
      r: 25
      profile:v: main10
      tag:v: hvc1
      force_key_frames: expr:not(mod(n,96))
    audioEncode:
      type: AudioEncode
      codec: aac
      bitrate: 192k
      suffix: _STEREO

To use this profile, configure the input with hardware decoding:

{
  "params": {
    "hwaccel": "cuda",
    "hwaccel_output_format": "cuda"
  }
}

Video Stream Copy

Copy the video stream without re-encoding, useful for remuxing:

name: video-copy
description: Copy video stream without re-encoding
scaling: bicubic
encodes:
  - type: VideoEncode
    suffix: _copy
    codec: copy
    format: mxf
    params: {}

Advanced: Profile Parameterization

For advanced users, Encore supports dynamic profile parameterization using Spring Expression Language (SpEL). This allows you to create flexible, reusable profiles that can be customized with parameters passed at job submission time.

See Profile Parameterization Guide for detailed information on using SpEL expressions in profiles.

Clone this wiki locally