169 lines
4.7 KiB
Markdown
169 lines
4.7 KiB
Markdown
# 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`.
|
|
|
|
## 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`.
|
|
|
|
## 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)
|
|
- Documentation roadmap: [roadmap/documentation.md](roadmap/documentation.md)
|