seriatim/docs/config.md

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:

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.

Related docs

• CLI reference: cli.md
• Operations guide: operations.md
• Troubleshooting: troubleshooting.md
• YAML example files:
  • ../examples/speakers.yml
  • ../examples/autocorrect.yml
• Synthetic examples: ../examples/README.md
• Public output schemas:
  • ../schema/minimal-output.schema.json
  • ../schema/intermediate-output.schema.json
  • ../schema/full-output.schema.json
• Documentation roadmap: roadmap/documentation.md