eric/seriatim

Fork 0

Files

Eric Rakestraw 385c62a5b4 Create canonical CLI and config docs and simplify README

2026-05-24 13:31:17 +00:00

4.4 KiB

Raw Blame History

Configuration Reference

Configuration surfaces

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

Runtime configuration comes from:

CLI flags
Environment variables (SERIATIM_*)
Optional YAML rule files referenced by CLI flags (--speakers, --autocorrect)

Output schema precedence

For merge and normalize:

--output-schema flag (when explicitly set)
SERIATIM_OUTPUT_SCHEMA
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:

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:

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.

CLI reference: cli.md
Public output schemas:
Remaining docs migration work (operations, troubleshooting, examples): roadmap/documentation.md

4.4 KiB Raw Blame History