Skip to content

Profile parametrization

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

Profile Parameterization with SpEL

Encore profiles support dynamic parameterization using Spring Expression Language (SpEL). This allows you to create flexible, reusable profiles that adapt based on job parameters.

For detailed information about SpEL syntax and capabilities, refer to the Spring Expression Language reference documentation.

What is SpEL?

SpEL (Spring Expression Language) is a powerful expression language that allows you to embed dynamic values in your profile configuration. Instead of hardcoding values, you can reference job properties or custom parameters that are provided when submitting a job.

SpEL Syntax

SpEL expressions in profiles are delimited by #{ and }:

height: #{profileParams['height']}
suffix: #{profileParams['suffix']}
enabled: #{profileParams['enableFeature']}

Available Context

SpEL expressions have access to the entire job object and its properties:

Job Properties:

  • baseName - Output filename base
  • outputFolder - Output directory path
  • profile - Profile name being used
  • externalId - External reference ID (if provided)
  • debugOverlay - Whether debug overlay is enabled
  • seekTo - Start time for encoding (seconds)
  • duration - Output duration limit (seconds)
  • thumbnailTime - Specific thumbnail timestamp
  • segmentLength - Segment length for parallel encoding
  • priority - Job priority (0-100)
  • inputs - List of input files

Custom Parameters:

  • profileParams - Map of custom parameters passed with the job

Using profileParams

The most common way to parameterize profiles is through the profileParams map. When submitting a job, you can pass custom parameters that the profile can reference.

For details on submitting jobs with profile parameters, see the API and Job Submission guide.

Job Submission (JSON):

{
  "profile": "archive",
  "baseName": "my_video",
  "outputFolder": "/output",
  "inputs": [...],
  "profileParams": {
    "height": 1080,
    "suffix": "_hd",
    "bitrate": "5000k"
  }
}

Profile (YAML):

name: archive
description: Parameterized archive profile
encodes:
  - type: VideoEncode
    codec: dnxhd
    height: #{profileParams['height']}
    suffix: #{profileParams['suffix']}
    params:
      b:v: #{profileParams['bitrate']}
    format: mxf
    twoPass: false

Default Values with Elvis Operator

Use the Elvis operator (?:) to provide default values when parameters aren't specified:

encodes:
  - type: X264Encode
    width: #{profileParams['width'] ?: 1920}
    height: #{profileParams['height'] ?: 1080}
    suffix: #{profileParams['suffix'] ?: '_default'}
    enabled: #{profileParams['enableOutput'] ?: true}

If width is not provided in profileParams, it defaults to 1920.

Conditional Encoding

Enable or disable specific outputs based on parameters:

encodes:
  - type: AudioEncode
    codec: ac3
    bitrate: 448k
    channelLayout: '5.1'
    suffix: _SURROUND
    enabled: #{profileParams['enableSurround'] ?: false}

  - type: ThumbnailEncode
    percentages: [25, 50, 75]
    optional: true
    enabled: #{profileParams['generateThumbnails'] ?: true}

Using Job Properties

Reference job properties directly in expressions:

encodes:
  - type: X264Encode
    width: 1920
    height: 1080
    # Include external ID in output filename
    suffix: _#{externalId}_1080p

  - type: ThumbnailEncode
    # Only generate thumbnails if debug mode is enabled
    enabled: #{debugOverlay}
    percentages: [50]

Complex Expressions

SpEL supports more complex logic:

encodes:
  - type: X264Encode
    # Use high bitrate if priority > 50, otherwise standard
    params:
      b:v: #{priority > 50 ? '8000k' : '5000k'}
      maxrate: #{priority > 50 ? '8500k' : '5350k'}

Real-World Example

Here's a complete example of a parameterized profile for H.264 CRF encoding:

name: x264-crf-parametrized
description: Flexible H.264 profile with CRF-based encoding
scaling: bicubic
encodes:
  - type: X264Encode
    # Dynamic suffix includes parameters for easy identification
    suffix: _x264_#{profileParams['preset']?:"medium"}_crf_#{profileParams['crf']?:23}
    twoPass: false
    height: #{profileParams['height']?:1080}
    params:
      crf: #{profileParams['crf']?:23}
      r: 25
      fps_mode: cfr
      pix_fmt: yuv420p
      force_key_frames: #{profileParams['keyframes']?:'expr:not(mod(n,96))'}
      preset: #{profileParams['preset']?:"medium"}
      movflags: faststart
    audioEncode:
      optional: true
      type: AudioEncode
      codec: aac
      bitrate: 128k
      suffix: STEREO

Usage examples:

High quality encode:

{
  "profile": "x264-crf-parametrized",
  "profileParams": {
    "preset": "slow",
    "crf": 18,
    "height": 1080
  }
}

Output: video_x264_slow_crf_18.mp4

Fast preview encode:

{
  "profile": "x264-crf-parametrized",
  "profileParams": {
    "preset": "veryfast",
    "crf": 28,
    "height": 720
  }
}

Output: video_x264_veryfast_crf_28.mp4

Default encode (no parameters):

{
  "profile": "x264-crf-parametrized",
  "profileParams": {}
}

Output: video_x264_medium_crf_23.mp4

Common Use Cases

1. Quality Tiers

Create a single profile that supports multiple quality levels:

name: adaptive-quality
description: Quality tier based on parameters
encodes:
  - type: X264Encode
    width: #{profileParams['width'] ?: 1920}
    height: #{profileParams['height'] ?: 1080}
    twoPass: true
    suffix: _#{profileParams['quality'] ?: 'standard'}
    params:
      b:v: #{profileParams['bitrate'] ?: '5000k'}
      maxrate: #{profileParams['maxrate'] ?: '5350k'}
      bufsize: #{profileParams['bufsize'] ?: '10000k'}
    x264-params:
      preset: #{profileParams['preset'] ?: 'medium'}
      crf: #{profileParams['crf'] ?: '23'}

Usage:

{
  "profile": "adaptive-quality",
  "profileParams": {
    "quality": "high",
    "width": 1920,
    "height": 1080,
    "bitrate": "8000k",
    "maxrate": "8500k",
    "bufsize": "16000k",
    "preset": "slow",
    "crf": "20"
  }
}

2. Optional Audio Tracks

Control which audio tracks are generated:

name: flexible-audio
description: Configurable audio outputs
encodes:
  - type: X264Encode
    width: 1920
    height: 1080
    audioEncodes:
      - type: AudioEncode
        channelLayout: stereo
        bitrate: 128k
        # Stereo always enabled

      - type: AudioEncode
        channelLayout: '5.1'
        bitrate: 384k
        enabled: #{profileParams['include51'] ?: false}

      - type: AudioEncode
        channelLayout: '7.1'
        bitrate: 512k
        enabled: #{profileParams['include71'] ?: false}

3. Archive Format Selection

Dynamically choose codec and container:

name: archive
description: Flexible archive format
encodes:
  - type: VideoEncode
    codec: #{profileParams['codec'] ?: 'dnxhd'}
    format: #{profileParams['format'] ?: 'mxf'}
    height: #{profileParams['height'] ?: 1080}
    params:
      b:v: #{profileParams['bitrate'] ?: '185M'}
      pix_fmt: #{profileParams['pixfmt'] ?: 'yuv422p10le'}
    suffix: _#{profileParams['codec']}_#{profileParams['height']}
    twoPass: false

4. Resolution Ladder

Generate different resolutions from parameters:

name: abr-ladder
description: Adaptive bitrate ladder
encodes:
  - type: X264Encode
    width: 1920
    height: 1080
    twoPass: true
    suffix: _1080p
    enabled: #{profileParams['enable1080p'] ?: true}
    params:
      b:v: #{profileParams['bitrate1080p'] ?: '5000k'}

  - type: X264Encode
    width: 1280
    height: 720
    twoPass: true
    suffix: _720p
    enabled: #{profileParams['enable720p'] ?: true}
    params:
      b:v: #{profileParams['bitrate720p'] ?: '2800k'}

  - type: X264Encode
    width: 854
    height: 480
    twoPass: true
    suffix: _480p
    enabled: #{profileParams['enable480p'] ?: false}
    params:
      b:v: #{profileParams['bitrate480p'] ?: '1400k'}

Clone this wiki locally