# 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](API-and-job-submission.md) guide. For details on configuring inputs, see the [Input Configuration](Input-configuration.md) 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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](Audiomix-presets.md#supported-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](Audiomix-presets.md). #### SimpleAudioEncode - Basic Audio Encoding Simple audio encoder that preserves the input's channel layout without any remapping or processing. ```json { "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. ```json { "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): ```json { "percentages": [10, 25, 50, 75, 90] } ``` Generates thumbnails at 10%, 25%, 50%, 75%, and 90% of video duration. 2. **Interval-based**: ```json { "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. ```json { "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](Hardware-acceleration.md). ```json { "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: ```json { "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:** ```json { "cropTo": "16:9" } ``` Crops the input to 16:9 before scaling. Useful for removing pillarboxing or letterboxing from source. **Pad to aspect ratio:** ```json { "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:** ```json { "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: ```json { "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: ```json { "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 ```json { "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 ```json { "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 ```json { "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. ```yaml 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: ```json { "params": { "hwaccel": "cuda", "hwaccel_output_format": "cuda" } } ``` ### Video Stream Copy Copy the video stream without re-encoding, useful for remuxing: ```yaml 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](Profile-parametrization.md) for detailed information on using SpEL expressions in profiles.