Create canonical CLI and config docs and simplify README
This commit is contained in:
176
docs/cli.md
Normal file
176
docs/cli.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 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. |
|
||||
|
||||
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`.
|
||||
|
||||
## Common workflows
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Trim to a segment subset:
|
||||
|
||||
```sh
|
||||
go run ./cmd/seriatim trim \
|
||||
--input-file merged.json \
|
||||
--output-file trimmed.json \
|
||||
--keep "1-20,25"
|
||||
```
|
||||
|
||||
Normalize an external transcript JSON file:
|
||||
|
||||
```sh
|
||||
go run ./cmd/seriatim normalize \
|
||||
--input-file external.json \
|
||||
--output-file normalized.json
|
||||
```
|
||||
|
||||
## 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)
|
||||
- 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)
|
||||
- Remaining docs migration work (operations, troubleshooting, examples): [roadmap/documentation.md](roadmap/documentation.md)
|
||||
162
docs/config.md
Normal file
162
docs/config.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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](cli.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)
|
||||
- Remaining docs migration work (operations, troubleshooting, examples): [roadmap/documentation.md](roadmap/documentation.md)
|
||||
Reference in New Issue
Block a user