99 lines
2.3 KiB
Markdown
99 lines
2.3 KiB
Markdown
# Transcript and Glossary File Integration
|
|
|
|
## Scope
|
|
|
|
This document defines the input file contracts for:
|
|
- transcript JSON;
|
|
- glossary YAML.
|
|
|
|
These files are loaded and validated before processing begins.
|
|
|
|
## Transcript JSON Contract
|
|
|
|
Audita accepts either top-level shape:
|
|
- JSON array of segments; or
|
|
- JSON object with a `segments` array.
|
|
|
|
Segment fields:
|
|
- `id` (optional integer in source form);
|
|
- `speaker` (required non-empty string);
|
|
- `start` (required finite non-negative number);
|
|
- `end` (required finite non-negative number, `>= start`);
|
|
- `text` (required non-empty string);
|
|
- `categories` (optional string array; entries must be non-empty).
|
|
|
|
Additional rules:
|
|
- transcript must contain at least one segment;
|
|
- duplicate segment IDs are rejected when IDs are present.
|
|
|
|
Example (`examples/tiny-transcript.json`):
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": 1,
|
|
"speaker": "A",
|
|
"start": 0.0,
|
|
"end": 1.2,
|
|
"text": "hello world"
|
|
}
|
|
]
|
|
```
|
|
|
|
## Glossary YAML Contract
|
|
|
|
Audita expects top-level `glossary` list entries.
|
|
|
|
Entry fields:
|
|
- `name` (required non-empty string);
|
|
- `category` (required non-empty string);
|
|
- `summary` (required non-empty string);
|
|
- `aliases` (optional list of strings; entries must be non-empty);
|
|
- `plural` (optional string).
|
|
|
|
Additional rules:
|
|
- glossary must contain at least one entry.
|
|
|
|
Example (`examples/tiny-glossary.yaml`):
|
|
|
|
```yaml
|
|
glossary:
|
|
- name: Audita
|
|
aliases:
|
|
- audita
|
|
category: product
|
|
summary: The Audita transcript correction CLI.
|
|
```
|
|
|
|
## Validation Failure Behavior
|
|
|
|
Representative transcript validation failures:
|
|
- invalid JSON;
|
|
- unsupported top-level shape;
|
|
- empty `speaker` or `text`;
|
|
- invalid times (`NaN`, `Inf`, negative, or `end < start`);
|
|
- duplicate IDs;
|
|
- empty transcript array.
|
|
|
|
Representative glossary validation failures:
|
|
- invalid YAML;
|
|
- empty or missing glossary entries;
|
|
- missing required entry fields;
|
|
- empty alias values.
|
|
|
|
These failures surface as schema errors and the process exits nonzero.
|
|
|
|
## CLI Usage
|
|
|
|
Minimal invocation:
|
|
|
|
```sh
|
|
audita process ./transcript.json --glossary ./glossary.yaml --output ./corrected.json
|
|
```
|
|
|
|
See also:
|
|
- [`docs/cli.md`](../cli.md)
|
|
- [`docs/config.md`](../config.md)
|
|
- [`examples/tiny-transcript.json`](../../examples/tiny-transcript.json)
|
|
- [`examples/tiny-glossary.yaml`](../../examples/tiny-glossary.yaml)
|