# 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](https://docs.spring.io/spring-framework/reference/core/expressions.html).

## 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 `}`:

```yaml
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](API-and-job-submission.md) guide.

**Job Submission (JSON):**
```json
{
  "profile": "archive",
  "baseName": "my_video",
  "outputFolder": "/output",
  "inputs": [...],
  "profileParams": {
    "height": 1080,
    "suffix": "_hd",
    "bitrate": "5000k"
  }
}
```

**Profile (YAML):**
```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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:
```json
{
  "profile": "x264-crf-parametrized",
  "profileParams": {
    "preset": "slow",
    "crf": 18,
    "height": 1080
  }
}
```
Output: `video_x264_slow_crf_18.mp4`

Fast preview encode:
```json
{
  "profile": "x264-crf-parametrized",
  "profileParams": {
    "preset": "veryfast",
    "crf": 28,
    "height": 720
  }
}
```
Output: `video_x264_veryfast_crf_28.mp4`

Default encode (no parameters):
```json
{
  "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:

```yaml
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:**
```json
{
  "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:

```yaml
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:

```yaml
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:

```yaml
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'}
```