# Configuration Reference

## Configuration surfaces

seriatim has no central JSON/TOML/YAML application config file.

Runtime configuration comes from:

1. CLI flags
2. Environment variables (`SERIATIM_*`)
3. Optional YAML rule files referenced by CLI flags (`--speakers`, `--autocorrect`)

## Output schema precedence

For `merge` and `normalize`:

1. `--output-schema` flag (when explicitly set)
2. `SERIATIM_OUTPUT_SCHEMA`
3. default `seriatim-intermediate`

For `trim`:

- If `--output-schema` is omitted, output preserves the input artifact schema.
- If `--output-schema` is set, it must be one of `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`.

## Render format and defaults

`render` requires `--input-file`, `--output-file`, and `--format`.
Current supported format value is `markdown`.

Render defaults:

- `--title`: `Transcript`
- `--include-timestamps`: `true`
- `--include-segment-ids`: `false`
- `--include-metadata`: `false`

## Merge module defaults

Default merge module selections:

- `--input-reader`: `json-files`
- `--preprocessing-modules`: `validate-raw,normalize-speakers,trim-text`
- `--postprocessing-modules`: `detect-overlaps,resolve-overlaps,backchannel,filler,resolve-danglers,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output`
- `--output-modules`: `json`

Module-list notes:

- Lists are comma-separated.
- Empty module names are invalid.
- Unknown module names fail the command.
- Preprocessing order must satisfy state requirements.

## Environment variables

| Variable | Default | Used by | Rules |
| --- | --- | --- | --- |
| `SERIATIM_OUTPUT_SCHEMA` | `seriatim-intermediate` | `merge`, `normalize` | Must be `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`. Ignored when `--output-schema` is explicitly set. |
| `SERIATIM_OVERLAP_WORD_RUN_GAP` | `1.0` | `merge` | Positive float (`> 0`). |
| `SERIATIM_OVERLAP_WORD_RUN_REORDER_WINDOW` | `1.0` | `merge` | Positive float (`> 0`). |
| `SERIATIM_BACKCHANNEL_MAX_DURATION` | `2.0` | `merge` | Positive float (`> 0`). |
| `SERIATIM_FILLER_MAX_DURATION` | `1.25` | `merge` | Positive float (`> 0`). |

Additional merge threshold flag:

- `--coalesce-gap` defaults to `3.0` and must be a non-negative float (`>= 0`).

## `speakers.yml`

Purpose:

- Maps each merge input filename basename to a canonical speaker label.

Top-level key:

- `match` (array of ordered rules)

Rule fields:

- `speaker` (required, non-empty)
- `match` (required, non-empty array of non-empty strings)

Example:

```yaml
match:
  - speaker: "Alice"
    match:
      - "alice_track"
      - "alice"

  - speaker: "Bob"
    match:
      - "bob_track"
```

Behavior:

- Matching is case-insensitive.
- Matching is against basename only (not full path).
- First matching rule wins.
- Duplicate `speaker` values are invalid.
- If any input file has no match, merge fails.

## `autocorrect.yml`

Purpose:

- Applies ordered token-level text replacements during merge `autocorrect` postprocessing.

Top-level key:

- `autocorrect` (array of rules)

Rule fields:

- `target` (required, non-empty)
- `match` (required, non-empty array of non-empty strings)

Example:

```yaml
autocorrect:
  - target: "Godfrey"
    match:
      - "God-free"

  - target: "Mike Brown"
    match:
      - "Mike Pat"
```

Behavior:

- Match strings are case-sensitive.
- Replacements are whole-token only (no substring replacement inside larger tokens).
- Duplicate match strings within one rule are invalid.
- Duplicate match strings across different rules are invalid.
- If `--autocorrect` is not provided, the autocorrect module is skipped.

## Path and validation rules

All commands:

- `--input-file` paths must exist and must be files.
- Output/report parent directories must already exist.
- Paths are normalized before use.

`merge`:

- Requires at least one `--input-file`.
- Rejects duplicate `--input-file` paths.
- Sorts normalized input file paths for deterministic execution.
- `--speakers` and `--autocorrect` are optional, but when set they must point to existing files.

`trim`:

- Requires exactly one of `--keep` or `--remove`.
- `--keep` and `--remove` are mutually exclusive.
- Validates optional `--output-schema` when provided.

`normalize`:

- Validates `--output-schema` through the same schema set as `merge`.
- Currently accepts only `json` in `--output-modules`.

`render`:

- Requires `--input-file`, `--output-file`, and `--format`.
- Validates `--format` as `markdown`.

## Related docs

- CLI reference: [cli.md](cli.md)
- Operations guide: [operations.md](operations.md)
- Troubleshooting: [troubleshooting.md](troubleshooting.md)
- YAML example files:
  - [../examples/speakers.yml](../examples/speakers.yml)
  - [../examples/autocorrect.yml](../examples/autocorrect.yml)
- Synthetic examples: [../examples/README.md](../examples/README.md)
- Public output schemas:
  - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json)
  - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json)
  - [../schema/full-output.schema.json](../schema/full-output.schema.json)