221 lines
8.0 KiB
Markdown
221 lines
8.0 KiB
Markdown
# CLI Reference
|
||
|
||
## Shortest useful command
|
||
|
||
```sh
|
||
go run ./cmd/seriatim merge \
|
||
--input-file speaker-a.json \
|
||
--input-file speaker-b.json \
|
||
--output-file merged.json
|
||
```
|
||
|
||
## Command overview
|
||
|
||
| Command | Purpose |
|
||
| --- | --- |
|
||
| `merge` | Merge one or more raw transcript JSON inputs into one seriatim artifact. |
|
||
| `trim` | Keep or remove segment IDs from an existing seriatim artifact. |
|
||
| `normalize` | Canonicalize transcript-like JSON into a seriatim artifact. |
|
||
| `render` | Render an existing seriatim artifact as Markdown. |
|
||
|
||
Root usage:
|
||
|
||
```text
|
||
seriatim [command]
|
||
```
|
||
|
||
## Global flags
|
||
|
||
| Flag | Description |
|
||
| --- | --- |
|
||
| `-h, --help` | Show help. |
|
||
| `-v, --version` | Show build version. |
|
||
|
||
## `merge`
|
||
|
||
Usage:
|
||
|
||
```text
|
||
seriatim merge [flags]
|
||
```
|
||
|
||
Flags:
|
||
|
||
| Flag | Required | Default | Description |
|
||
| --- | --- | --- | --- |
|
||
| `--input-file stringArray` | Yes, repeat at least once | none | Input transcript JSON file(s). |
|
||
| `--output-file string` | Yes | none | Output transcript JSON file path. |
|
||
| `--report-file string` | No | none | Optional report JSON path. |
|
||
| `--speakers string` | No | none | Speaker-map YAML file. |
|
||
| `--autocorrect string` | No | none | Autocorrect YAML file. |
|
||
| `--input-reader string` | No | `json-files` | Input reader module name. |
|
||
| `--output-modules string` | No | `json` | Comma-separated output module names. |
|
||
| `--output-schema string` | No | `seriatim-intermediate` | Output schema name: `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`. |
|
||
| `--preprocessing-modules string` | No | `validate-raw,normalize-speakers,trim-text` | Comma-separated preprocessing module names, run in order. |
|
||
| `--postprocessing-modules string` | No | `detect-overlaps,resolve-overlaps,backchannel,filler,resolve-danglers,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output` | Comma-separated postprocessing module names, run in order. |
|
||
| `--coalesce-gap string` | No | `3.0` | Non-negative seconds for coalescing and overlap-resolution context. |
|
||
|
||
`merge` behavior and validation:
|
||
|
||
- Unknown input reader, preprocessing module, postprocessing module, or output module fails the command.
|
||
- Preprocessing order must satisfy module state requirements (`raw` -> `canonical`); invalid order fails.
|
||
- Input files are validated, deduplicated, normalized, then sorted for deterministic processing.
|
||
- Optional report output is written only when `--report-file` is set.
|
||
- When `--output-schema` is omitted, schema resolution is: `SERIATIM_OUTPUT_SCHEMA` -> default `seriatim-intermediate`.
|
||
|
||
## `trim`
|
||
|
||
Usage:
|
||
|
||
```text
|
||
seriatim trim [flags]
|
||
```
|
||
|
||
Flags:
|
||
|
||
| Flag | Required | Default | Description |
|
||
| --- | --- | --- | --- |
|
||
| `--input-file string` | Yes | none | Input seriatim artifact JSON file. |
|
||
| `--output-file string` | Yes | none | Output transcript JSON file path. |
|
||
| `--keep string` | Exactly one of `--keep` / `--remove` | none | Segment ID selector to keep. |
|
||
| `--remove string` | Exactly one of `--keep` / `--remove` | none | Segment ID selector to remove. |
|
||
| `--output-schema string` | No | preserve input artifact schema | Output schema override: `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`. |
|
||
| `--report-file string` | No | none | Optional report JSON path. |
|
||
| `--allow-empty` | No | `false` | Allow output with zero segments. |
|
||
|
||
Selector rules:
|
||
|
||
- IDs must be positive integers.
|
||
- Single IDs and inclusive ranges are supported: `1`, `1-10`.
|
||
- Comma-separated selectors are supported: `1-10,15,20-25`.
|
||
- Whitespace around commas and hyphens is allowed.
|
||
- Descending ranges (example `10-1`) are invalid.
|
||
- Duplicates and overlapping ranges are normalized as a union.
|
||
|
||
`trim` behavior:
|
||
|
||
- Input must already be a valid seriatim artifact (not raw merge input JSON).
|
||
- Output keeps transcript order from input and renumbers retained segment IDs sequentially.
|
||
- If `--output-schema` is omitted, the input artifact schema is preserved.
|
||
- `trim` never runs merge preprocessing/postprocessing modules.
|
||
|
||
## `normalize`
|
||
|
||
Usage:
|
||
|
||
```text
|
||
seriatim normalize [flags]
|
||
```
|
||
|
||
Flags:
|
||
|
||
| Flag | Required | Default | Description |
|
||
| --- | --- | --- | --- |
|
||
| `--input-file string` | Yes | none | Input transcript JSON file. |
|
||
| `--output-file string` | Yes | none | Output transcript JSON file path. |
|
||
| `--output-schema string` | No | `seriatim-intermediate` | Output schema name: `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`. |
|
||
| `--output-modules string` | No | `json` | Comma-separated output module names (`json` only). |
|
||
| `--report-file string` | No | none | Optional report JSON path. |
|
||
|
||
`normalize` input shapes:
|
||
|
||
- Object with top-level `segments` array.
|
||
- Bare top-level segment array.
|
||
|
||
`normalize` behavior:
|
||
|
||
- Sorts deterministically and reassigns output IDs sequentially from `1`.
|
||
- Fills missing/blank speakers with `Unknown_Speaker`.
|
||
- Repairs/sanitizes timing fields deterministically; rejects invalid repaired timing.
|
||
- Drops segments with missing or blank text.
|
||
- Does not run merge modules.
|
||
- When `--output-schema` is omitted, schema resolution is: `SERIATIM_OUTPUT_SCHEMA` -> default `seriatim-intermediate`.
|
||
|
||
## `render`
|
||
|
||
Usage:
|
||
|
||
```text
|
||
seriatim render [flags]
|
||
```
|
||
|
||
Flags:
|
||
|
||
| Flag | Required | Default | Description |
|
||
| --- | --- | --- | --- |
|
||
| `--input-file string` | Yes | none | Input seriatim artifact JSON file. |
|
||
| `--output-file string` | Yes | none | Rendered output file path. |
|
||
| `--format string` | Yes | none | Output format. Current supported value: `markdown`. |
|
||
| `--title string` | No | `Transcript` | Markdown document title. |
|
||
| `--include-timestamps` | No | `true` | Include `[HH:MM:SS–HH:MM:SS]` per segment. |
|
||
| `--include-segment-ids` | No | `false` | Include `[#id]` marker per segment. |
|
||
| `--include-metadata` | No | `false` | Include artifact metadata block near the top. |
|
||
|
||
`render` behavior:
|
||
|
||
- Input must be a valid existing seriatim output artifact (`seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`).
|
||
- Raw WhisperX-style JSON is rejected.
|
||
- `render` does not execute merge/trim/normalize transformations.
|
||
- `render` has no `--report-file` output in the current implementation.
|
||
- Markdown output is deterministic for the same input artifact and render flags.
|
||
- Category names are not printed directly; `background`, `backchannel`, and `filler` only influence italics.
|
||
|
||
## Common workflows
|
||
|
||
Merge with a speaker map and report output:
|
||
|
||
```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 \
|
||
--report-file /tmp/seriatim-example-merge-report.json
|
||
```
|
||
|
||
Trim to a segment subset:
|
||
|
||
```sh
|
||
go run ./cmd/seriatim trim \
|
||
--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 examples/normalize/object-with-segments.json \
|
||
--output-file /tmp/seriatim-example-normalize-object.json
|
||
```
|
||
|
||
Render an existing artifact as Markdown:
|
||
|
||
```sh
|
||
go run ./cmd/seriatim render \
|
||
--input-file examples/render/input-intermediate.json \
|
||
--output-file /tmp/seriatim-example-render.md \
|
||
--format markdown
|
||
```
|
||
|
||
## Exit and errors
|
||
|
||
- Commands return exit code `0` on success.
|
||
- On error, the CLI prints one error line to stderr and exits with status `1`.
|
||
- Cobra usage text is silenced on runtime errors; use `--help` for command usage.
|
||
|
||
## Related docs
|
||
|
||
- 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)
|
||
- [../schema/full-output.schema.json](../schema/full-output.schema.json)
|