The current implementation supports the merge command. It reads one or more input JSON files, maps each input file to a canonical speaker using speakers.yml, sorts all segments by timestamp, assigns consecutive numeric id values, and writes a merged JSON artifact.

Usage

Run from source:

go run ./cmd/seriatim merge \
  --input-file samples/raw/2026-04-19-Eric_Rakestraw.json \
  --input-file samples/raw/2026-04-19-Mike_Brown.json \
  --speakers samples/speakers.yml \
  --output-file merged.json

Optional report output:

go run ./cmd/seriatim merge \
  --input-file eric.json \
  --input-file mike.json \
  --speakers speakers.yml \
  --output-file merged.json \
  --report-file report.json

CLI

seriatim merge [flags]

Required flags for the default pipeline:

--input-file: input transcript JSON file. Repeat once per speaker/input file.
--speakers: speaker map YAML file. Required because normalize-speakers is enabled by default.
--output-file: merged transcript JSON output path.

Optional flags:

--report-file: write a JSON report with pipeline events.
--input-reader: input reader module. Default: json-files.
--output-modules: comma-separated output modules. Default: json.
--preprocessing-modules: comma-separated preprocessing modules. Default: validate-raw,normalize-speakers,trim-text.
--postprocessing-modules: comma-separated postprocessing modules. Default: detect-overlaps,resolve-overlaps,assign-ids,validate-output.
--autocorrect: autocorrect rules file. Reserved for the autocorrect module; not part of the default pipeline.

Input JSON Format

Each input file must be valid JSON with a top-level segments array. The current parser accepts the WhisperX segment subset needed for merging:

{
  "segments": [
    {
      "start": 1.25,
      "end": 3.5,
      "text": "Hello there."
    }
  ]
}

Required segment fields:

start: number, must be >= 0.
end: number, must be >= start.
text: string.

Other WhisperX fields, including words and raw diarization speaker labels, are ignored for now.

Speaker Map Format

speakers.yml maps each input file basename to one canonical speaker name:

inputs:
  2026-04-19-Eric_Rakestraw.json:
    speaker: "Eric Rakestraw"

  2026-04-19-Mike_Brown.json:
    speaker: "Mike Brown"

Important details:

Keys are matched against the basename of each --input-file, not the full path.
Every input file must have exactly one matching entry.
speaker is required and must be non-empty.

Output JSON Format

The merged output uses the current seriatim envelope:

{
  "metadata": {
    "application": "seriatim",
    "version": "dev",
    "input_reader": "json-files",
    "input_files": ["eric.json", "mike.json"],
    "preprocessing_modules": ["validate-raw", "normalize-speakers", "trim-text"],
    "postprocessing_modules": ["detect-overlaps", "resolve-overlaps", "assign-ids", "validate-output"],
    "output_modules": ["json"]
  },
  "segments": [
    {
      "id": 1,
      "source": "eric.json",
      "source_segment_index": 0,
      "speaker": "Eric Rakestraw",
      "start": 1.25,
      "end": 3.5,
      "text": "Hello there."
    }
  ],
  "overlap_groups": []
}

Segments are sorted deterministically by:

(start, end, source, source_segment_index, speaker)

Final segment IDs are assigned after sorting and start at 1.

Current Limitations

Only JSON input is supported.
Word-level timing data is not preserved yet.
Overlap detection and overlap resolution are currently no-op modules.
Autocorrect, coalescing, and alternate output formats are not implemented yet.