eric/seriatim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Add integration docs and synthetic command examples

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-24 13:43:47 +00:00
parent 88018c9e76
commit f8ab117bfc
15 changed files with 383 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@@ -27,6 +27,9 @@ go run ./cmd/seriatim merge \
- Configuration reference: [docs/config.md](docs/config.md)
- Operations guide: [docs/operations.md](docs/operations.md)
- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
- Integrations:
- [docs/integrations/whisperx-json.md](docs/integrations/whisperx-json.md)
- [docs/integrations/output-schemas.md](docs/integrations/output-schemas.md)
- Development architecture policy: [docs/policy/architecture.md](docs/policy/architecture.md)
- Contributor workflow: [docs/policy/development.md](docs/policy/development.md)
- Documentation policy: [docs/policy/documentation.md](docs/policy/documentation.md)
@@ -38,4 +41,5 @@ go run ./cmd/seriatim merge \
- [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)
- Synthetic examples: [examples/README.md](examples/README.md)
- Remaining documentation migration work: [docs/roadmap/documentation.md](docs/roadmap/documentation.md)

24
docs/cli.md
View File

@@ -136,28 +136,28 @@ Merge with a speaker map and report output:
```sh
go run ./cmd/seriatim merge \
--input-file speaker-a.json \
--input-file speaker-b.json \
--speakers speakers.yml \
--output-file merged.json \
--report-file merge-report.json
--input-file examples/minimal-merge/input-alice.json \
--input-file examples/minimal-merge/input-bob.json \
--speakers examples/minimal-merge/speakers.yml \
--output-file /tmp/seriatim-example-merge.json \
--report-file /tmp/seriatim-example-merge-report.json
```
Trim to a segment subset:
```sh
go run ./cmd/seriatim trim \
--input-file merged.json \
--output-file trimmed.json \
--keep "1-20,25"
--input-file examples/trim/input-full.json \
--output-file /tmp/seriatim-example-trim.json \
--keep "1-2"
```
Normalize an external transcript JSON file:
```sh
go run ./cmd/seriatim normalize \
--input-file external.json \
--output-file normalized.json
--input-file examples/normalize/object-with-segments.json \
--output-file /tmp/seriatim-example-normalize-object.json
```
## Exit and errors
@@ -171,6 +171,10 @@ go run ./cmd/seriatim normalize \
- Configuration reference: [config.md](config.md)
- Operations guide: [operations.md](operations.md)
- Troubleshooting: [troubleshooting.md](troubleshooting.md)
- Integration notes:
- [integrations/whisperx-json.md](integrations/whisperx-json.md)
- [integrations/output-schemas.md](integrations/output-schemas.md)
- 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)

4
docs/config.md
View File

@@ -157,6 +157,10 @@ All commands:
- 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)

68
docs/integrations/output-schemas.md Normal file
View File

@@ -0,0 +1,68 @@
# Output Schemas
## Scope
seriatim emits one of three public JSON output contracts:
- `seriatim-minimal`
- `seriatim-intermediate`
- `seriatim-full`
These are used by `merge`, `trim`, and `normalize`.
## Schema roles
`seriatim-minimal`:
- compact metadata plus ordered transcript segments
- no source/provenance fields
- no overlap groups
`seriatim-intermediate`:
- compact metadata plus ordered segments
- includes optional segment `categories`
- no source/provenance fields
- no overlap groups
`seriatim-full`:
- full metadata (`input_reader`, module lists, input files, output modules)
- source/provenance fields on segments
- overlap-group data
- version metadata populated from build info (`internal/buildinfo`)
## Semantic invariants
All schema outputs enforce:
- segment IDs are sequential starting at `1`
- segment timing uses `end >= start`
Full schema also enforces overlap-group timing (`end >= start`).
## Validation APIs
Go package: `gitea.maximumdirect.net/eric/seriatim/schema`
Key validators:
- `schema.ValidateMinimalTranscript`
- `schema.ValidateIntermediateTranscript`
- `schema.ValidateTranscript`
- `schema.ValidateMinimalJSON`
- `schema.ValidateIntermediateJSON`
- `schema.ValidateJSON`
## Machine-readable schema files
- [../../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)
## Related docs and examples
- CLI reference: [../cli.md](../cli.md)
- Artifact internals: [../internal/artifacts.md](../internal/artifacts.md)
- Trim example input artifact:
- [../../examples/trim/input-full.json](../../examples/trim/input-full.json)

85
docs/integrations/whisperx-json.md Normal file
View File

@@ -0,0 +1,85 @@
# 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)

4
docs/operations.md
View File

@@ -130,3 +130,7 @@ Transcript artifacts and reports are local files and may contain sensitive conve
- CLI reference: [cli.md](cli.md)
- Configuration reference: [config.md](config.md)
- Troubleshooting: [troubleshooting.md](troubleshooting.md)
- Integration notes:
- [integrations/whisperx-json.md](integrations/whisperx-json.md)
- [integrations/output-schemas.md](integrations/output-schemas.md)
- Synthetic examples: [../examples/README.md](../examples/README.md)

61
examples/README.md Normal file
View File

@@ -0,0 +1,61 @@
# Examples
These are small synthetic, copyable example assets for the implemented CLI
commands.
This directory is the canonical examples home for documentation.
## Merge example
Inputs:
- `minimal-merge/input-alice.json`
- `minimal-merge/input-bob.json`
- `minimal-merge/speakers.yml`
Run:
```sh
go run ./cmd/seriatim merge \
--input-file examples/minimal-merge/input-alice.json \
--input-file examples/minimal-merge/input-bob.json \
--speakers examples/minimal-merge/speakers.yml \
--output-file /tmp/seriatim-example-merge.json
```
## Normalize examples
Object-with-segments input:
```sh
go run ./cmd/seriatim normalize \
--input-file examples/normalize/object-with-segments.json \
--output-file /tmp/seriatim-example-normalize-object.json
```
Bare-array input:
```sh
go run ./cmd/seriatim normalize \
--input-file examples/normalize/bare-segments-array.json \
--output-file /tmp/seriatim-example-normalize-array.json
```
## Trim example
Input artifact:
- `trim/input-full.json`
Run:
```sh
go run ./cmd/seriatim trim \
--input-file examples/trim/input-full.json \
--output-file /tmp/seriatim-example-trim.json \
--keep "1-2"
```
## YAML rule examples
- `speakers.yml`
- `autocorrect.yml`

8
examples/autocorrect.yml Normal file
View File

@@ -0,0 +1,8 @@
autocorrect:
- target: "General Kenobi"
match:
- "General Kenobi."
- target: "Okay"
match:
- "Okay."

14
examples/minimal-merge/input-alice.json Normal file
View File

@@ -0,0 +1,14 @@
{
"segments": [
{
"start": 0.0,
"end": 1.2,
"text": " Hello there. "
},
{
"start": 2.6,
"end": 3.1,
"text": "Okay."
}
]
}

9
examples/minimal-merge/input-bob.json Normal file
View File

@@ -0,0 +1,9 @@
{
"segments": [
{
"start": 1.3,
"end": 2.4,
"text": "General Kenobi."
}
]
}

8
examples/minimal-merge/speakers.yml Normal file
View File

@@ -0,0 +1,8 @@
match:
- speaker: "Alice Example"
match:
- "alice"
- speaker: "Bob Example"
match:
- "bob"

13
examples/normalize/bare-segments-array.json Normal file
View File

@@ -0,0 +1,13 @@
[
{
"start": 2.5,
"end": 3.0,
"speaker": "Bob",
"text": "later"
},
{
"end": 2.0,
"speaker": "",
"text": "no start uses end"
}
]

19
examples/normalize/object-with-segments.json Normal file
View File

@@ -0,0 +1,19 @@
{
"segments": [
{
"id": 7,
"start": 2.0,
"end": 2.5,
"speaker": "Bob",
"text": "second"
},
{
"id": 1,
"start": 1.0,
"end": 1.3,
"speaker": "Alice",
"text": "first",
"categories": ["backchannel"]
}
]
}

8
examples/speakers.yml Normal file
View File

@@ -0,0 +1,8 @@
match:
- speaker: "Alice Example"
match:
- "alice"
- speaker: "Bob Example"
match:
- "bob"

64
examples/trim/input-full.json Normal file
View File

@@ -0,0 +1,64 @@
{
"metadata": {
"application": "seriatim",
"version": "dev",
"input_reader": "json-files",
"input_files": [
"examples/minimal-merge/input-alice.json",
"examples/minimal-merge/input-bob.json"
],
"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"
]
},
"segments": [
{
"id": 1,
"source": "examples/minimal-merge/input-alice.json",
"source_segment_index": 0,
"speaker": "Alice Example",
"start": 0,
"end": 1.2,
"text": "Hello there."
},
{
"id": 2,
"source": "examples/minimal-merge/input-bob.json",
"source_segment_index": 0,
"speaker": "Bob Example",
"start": 1.3,
"end": 2.4,
"text": "General Kenobi."
},
{
"id": 3,
"source": "examples/minimal-merge/input-alice.json",
"source_segment_index": 1,
"speaker": "Alice Example",
"start": 2.6,
"end": 3.1,
"text": "Okay.",
"categories": [
"backchannel"
]
}
],
"overlap_groups": []
}