# WhisperX-Like JSON Input

## Scope

This document covers the implemented JSON subset consumed by `seriatim merge`.
It does not describe full WhisperX output.
No explicit WhisperX version is encoded in the repository.

## Supported top-level shape

Merge expects a JSON object with top-level `segments` array:

```json
{
  "segments": [
    {
      "start": 0.0,
      "end": 1.2,
      "text": "hello"
    }
  ]
}
```

## Supported segment fields

Required per segment:

- `start` (number, `>= 0`)
- `end` (number, `>= start`)
- `text` (string)

Optional per segment:

- `words` (array)

## Supported word fields

Required when a word object is present:

- `word` (string)

Optional word timing fields:

- `start` (number)
- `end` (number)

Timing rules:

- if both `start` and `end` are present, they must be numeric and `end >= start`
- if either timing field is missing, the word is accepted but not used as a
  timing anchor for overlap resolution

Additional optional word fields:

- `score` (number)
- `speaker` (string)

## Validation and failure behavior

Merge fails for:

- malformed JSON
- missing top-level `segments`
- non-array `segments`
- missing required segment fields
- wrong field types
- negative segment/word start times
- segment/word end before start

Word timing missing from a word does not fail merge; it emits a warning event
in the optional report.

## Overlap-resolution impact

- overlap resolution uses timed words when available
- untimed words are kept in replacement text but do not provide timing anchors

## Related docs and examples

- CLI reference: [../cli.md](../cli.md)
- Configuration reference: [../config.md](../config.md)
- Minimal merge example inputs:
  - [../../examples/minimal-merge/input-alice.json](../../examples/minimal-merge/input-alice.json)
  - [../../examples/minimal-merge/input-bob.json](../../examples/minimal-merge/input-bob.json)