# Audiomix Presets

Audiomix presets define how Encore mixes audio channels when transcoding between different channel layouts. They control the downmixing and upmixing of audio, such as converting 5.1 surround sound to stereo, or mono to stereo.

## Overview

When encoding audio, you often need to convert between different channel configurations. For example, a source file might have 5.1 surround sound, but you need to create a stereo output for web delivery. Audiomix presets define the mathematical formulas that determine how each input channel contributes to the output channels.

Encore uses FFmpeg's `pan` audio filter under the hood, and audiomix presets provide a convenient way to configure these pan mappings without writing complex filter expressions in each encoding profile.

## How It Works

When Encore processes an audio encode, it:

1. Identifies the input channel layout (e.g., 5.1, stereo, mono)
2. Looks up the requested audiomix preset (defaults to "default")
3. Finds the appropriate pan mapping for the input-to-output conversion
4. If no specific mapping exists, uses the default pan for the output layout
5. If no default pan exists and `fallbackToAuto` is enabled, uses FFmpeg's automatic channel layout conversion

## Preset Structure

Each audiomix preset contains three configuration options:

**fallbackToAuto** (boolean, default: `true`): When set to `true`, Encore falls back to FFmpeg's automatic channel conversion if no explicit pan mapping is defined for the input/output combination. When `false`, the encode fails if no mapping exists.

**defaultPan** (map): Defines default pan expressions for output channel layouts. These are used when no specific mapping exists for an input/output combination, but the output has fewer or equal channels than the input.

**panMapping** (nested map): Defines specific pan expressions for exact input-to-output channel layout conversions. The outer key is the input layout, the inner key is the output layout.

## Configuration

Audiomix presets can be configured in two ways:

### Inline Configuration

Define presets directly in your application configuration:

```yaml
encore-settings:
  encoding:
    audio-mix-presets:
      default:
        fallback-to-auto: true
        default-pan:
          stereo: FL=FL+0.707107*FC+0.707107*BL+0.707107*SL|FR=FR+0.707107*FC+0.707107*BR+0.707107*SR
        pan-mapping:
          mono:
            stereo: FL=0.707*FC|FR=0.707*FC
```

### External File

Reference an external YAML or JSON file containing preset definitions:

```yaml
encore-settings:
  encoding:
    audio-mix-preset-location: file:///path/to/audio-mix-presets.yml
```
The file may be referenced using a http url.

The external file format:

```yaml
default:
  default-pan:
    stereo: FL=FL+0.707107*FC+0.707107*BL+0.707107*SL|FR=FR+0.707107*FC+0.707107*BR+0.707107*SR
  pan-mapping:
    mono:
      stereo: FL=0.707*FC|FR=0.707*FC

de:
  fallback-to-auto: false
  default-pan:
    stereo: FL<FL+1.5*FC+0.707107*BL+0.707107*SL|FR<FR+1.5*FC+0.707107*BR+0.707107*SR
  pan-mapping:
    "5.1":
      "5.1": c0=c0|c1=c1|c2<1.5*c2|c3=c3|c4=c4|c5=c5
    "5.1(side)":
      "5.1": c0=c0|c1=c1|c2<1.5*c2|c3=c3|c4=c4|c5=c5
```

## Using Presets in Profiles

Reference an audiomix preset in your encoding profile by setting the `audioMixPreset` property on an `AudioEncode`:

```yaml
encodes:
  - type: AudioEncode
    bitrate: 128k
    channelLayout: stereo
    audioMixPreset: default

  - type: AudioEncode
    bitrate: 128k
    channelLayout: stereo
    audioMixPreset: de
    dialogueEnhancement:
      enabled: true
```

If not specified, `audioMixPreset` defaults to `"default"`.

## Pan Expression Syntax

Pan expressions follow FFmpeg's [pan filter](https://ffmpeg.org/ffmpeg-filters.html#pan) syntax. The basic format is:

```
output_channel=gain*input_channel+gain*input_channel|output_channel=...
```

If the ‘=’ in a channel specification is replaced by ‘<’, then the gains for that specification will be renormalized so that the total is 1, thus avoiding clipping noise.

```
FL<FL+1.5*FC+0.707107*BL
```

### Channel Identifiers

Common channel identifiers:

- `FL` - Front Left
- `FR` - Front Right
- `FC` - Front Center
- `LFE` - Low Frequency Effects (subwoofer)
- `BL` - Back Left (rear left)
- `BR` - Back Right (rear right)
- `SL` - Side Left
- `SR` - Side Right

You can also use channel indices (`c0`, `c1`, etc.) for layouts where channel names are ambiguous.

For a complete list of channel identifiers see [Channel layout](https://ffmpeg.org/ffmpeg-utils.html#toc-Channel-Layout) section in the ffmpeg documentation.

### Example Expressions

**5.1 to stereo downmix:**
```
FL=FL+0.707107*FC+0.707107*BL+0.707107*SL|FR=FR+0.707107*FC+0.707107*BR+0.707107*SR
```
This mixes the center channel and rear channels into the front left and right, using standard downmix coefficients (0.707 = -3dB).

**Mono to stereo:**
```
FL=0.707*FC|FR=0.707*FC
```
This sends the mono center channel equally to both stereo channels at -3dB.

**5.1 with boosted center (dialogue enhancement):**
```
c0=c0|c1=c1|c2<1.5*c2|c3=c3|c4=c4|c5=c5
```
This keeps all channels the same but boosts the center channel (dialogue) by 1.5x.

## Supported Channel Layouts

- `mono` - 1 channel (FC)
- `stereo` - 2 channels (FL, FR)
- `2.1` - 3 channels (FL, FR, LFE)
- `3.0` - 3 channels (FL, FR, FC)
- `3.0(back)` - 3 channels (FL, FR, BC)
- `3.1` - 4 channels (FL, FR, FC, LFE)
- `4.0` - 4 channels (FL, FR, FC, BC)
- `quad` - 4 channels (FL, FR, BL, BR)
- `quad(side)` - 4 channels (FL, FR, SL, SR)
- `4.1` - 5 channels (FL, FR, FC, LFE, BC)
- `5.0` - 5 channels (FL, FR, FC, BL, BR)
- `5.0(side)` - 5 channels (FL, FR, FC, SL, SR)
- `3.1.2` - 6 channels (FL, FR, FC, LFE, TFL, TFR)
- `5.1` - 6 channels (FL, FR, FC, LFE, BL, BR)
- `5.1(side)` - 6 channels (FL, FR, FC, LFE, SL, SR)
- `6.0` - 6 channels (FL, FR, FC, BC, SL, SR)
- `6.0(front)` - 6 channels (FL, FR, FLC, FRC, SL, SR)
- `hexagonal` - 6 channels (FL, FR, FC, BL, BR, BC)
- `6.1` - 7 channels (FL, FR, FC, LFE, BC, SL, SR)
- `6.1(back)` - 7 channels (FL, FR, FC, LFE, BL, BR, BC)
- `6.1(front)` - 7 channels (FL, FR, LFE, FLC, FRC, SL, SR)
- `7.0` - 7 channels (FL, FR, FC, BL, BR, SL, SR)
- `7.0(front)` - 7 channels (FL, FR, FC, FLC, FRC, SL, SR)
- `5.1.2` - 8 channels (FL, FR, FC, LFE, BL, BR, TFL, TFR)
- `7.1` - 8 channels (FL, FR, FC, LFE, BL, BR, SL, SR)
- `7.1(wide)` - 8 channels (FL, FR, FC, LFE, BL, BR, FLC, FRC)
- `7.1(wide-side)` - 8 channels (FL, FR, FC, LFE, FLC, FRC, SL, SR)
- `octagonal` - 8 channels (FL, FR, FC, BL, BR, BC, SL, SR)
- `cube` - 8 channels (FL, FR, BL, BR, TFL, TFR, TBL, TBR)
- `5.1.4` - 10 channels (FL, FR, FC, LFE, BL, BR, TFL, TFR, TBL, TBR)
- `7.1.2` - 10 channels (FL, FR, FC, LFE, BL, BR, SL, SR, TFL, TFR)
- `7.1.4` - 12 channels (FL, FR, FC, LFE, BL, BR, SL, SR, TFL, TFR, TBL, TBR)
- `7.2.3` - 12 channels (FL, FR, FC, LFE, BL, BR, SL, SR, TFL, TFR, TBC, LFE2)
- `9.1.4` - 14 channels (FL, FR, FC, LFE, BL, BR, FLC, FRC, SL, SR, TFL, TFR, TBL, TBR)
- `hexadecagonal` - 16 channels (FL, FR, FC, BL, BR, BC, SL, SR, TFL, TFC, TFR, TBL, TBC, TBR, WL, WR)
- `downmix` - 2 channels (DL, DR)
- `22.2` - 24 channels (FL, FR, FC, LFE, BL, BR, FLC, FRC, BC, SL, SR, TC, TFL, TFC, TFR, TBL, TBC, TBR, LFE2, TSL, TSR, BFC, BFL, BFR)

(See also the
[Channel layout](https://ffmpeg.org/ffmpeg-utils.html#toc-Channel-Layout) section in the ffmpeg documentation.)

__*Note that encore does not support specifying channel layouts using the number of channels with a 'c' or 'C' prefix*__

## Troubleshooting

**Error: "Audio mix preset 'name' not found!"**
The preset referenced in your profile doesn't exist in the configuration. Check that the preset name matches exactly and is properly configured.

**Error: "No audio mix preset for 'name': layout1 -> layout2!"**
No pan mapping exists for this specific channel conversion, and either `fallbackToAuto` is `false` or the output has more channels than the input. Add a specific pan mapping or enable `fallbackToAuto`.