85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
# narratio
|
||
|
||
`narratio` is a Go-based orchestration application for processing D&D session audio into transcripts and downstream artifacts.
|
||
|
||
This repository currently contains a **working scaffold** with strict config loading, local workdir/manifest handling, resumable stage control, real WhisperX and Seriatim adapters, and real `prepare` + `transcribe` + `merge` stages.
|
||
|
||
## Expected Config Files
|
||
|
||
`narratio` expects two YAML files:
|
||
|
||
- `pipeline.yml`: pipeline/workspace settings (`workspace`, `storage`, `whisperx`, `seriatim`, `audita`, `analyzer`, `notification`)
|
||
- `session.yml`: per-session settings (`session_id`, `inputs`, optional metadata)
|
||
|
||
WhisperX config contract in `pipeline.yml`:
|
||
|
||
- required: `whisperx.transcribe_url`
|
||
- defaulted when omitted: `whisperx.language` (`en`), `whisperx.timeout` (`30m`), `whisperx.retries` (`3`), `whisperx.retry_delay` (`2s`), `whisperx.concurrency` (`2`)
|
||
|
||
Seriatim config contract in `pipeline.yml`:
|
||
|
||
- required: `seriatim.binary` (name or path; existence is checked at execution time, not config validation time)
|
||
- defaulted when omitted: `seriatim.timeout` (`10m`), `seriatim.output_schema` (`seriatim-intermediate`), `seriatim.coalesce_gap` (`3.0`), `seriatim.report` (`true`)
|
||
- allowed `seriatim.output_schema` values: `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`
|
||
- optional tuning: `seriatim.env.*` (`overlap_word_run_gap`, `overlap_word_run_reorder_window`, `backchannel_max_duration`, `filler_max_duration`) must be `> 0` when provided
|
||
|
||
`speakers.yml` note:
|
||
|
||
- use Seriatim’s documented `match:` format (not the legacy direct mapping style used by older scripts/scaffolds)
|
||
- see [`examples/speakers.yml`](examples/speakers.yml) for a concrete `match:` example.
|
||
|
||
Prepared inputs note:
|
||
|
||
- `prepare` copies session inputs into the session workdir (`work/<session_id>/inputs`), and downstream stages consume those prepared copies, not the original source files.
|
||
- If you edit `speakers.yml`, `autocorrect.yml`, `glossary.yml`, or session input paths after `prepare` has run, rerun `prepare` with `--force` before rerunning downstream stages.
|
||
|
||
Decoding is strict (`KnownFields(true)`), so unknown YAML fields fail fast.
|
||
|
||
Example minimal files are available under `examples/`:
|
||
|
||
- `examples/pipeline.minimal.yml`
|
||
- `examples/session.minimal.yml`
|
||
|
||
## Current Scaffold Status
|
||
|
||
Implemented now:
|
||
|
||
- strict config load + validation
|
||
- local artifact/workdir creation and locking
|
||
- manifest create/load/save and stage status tracking
|
||
- stage framework with real `prepare`, `transcribe`, and `merge` stages; placeholder downstream stages
|
||
- resumable run control (`run`, `resume`, `run-stage`, `plan` with run/skip decisions)
|
||
- real WhisperX HTTP adapter plus real Seriatim subprocess adapter (both with fake/no-op adapters for test/scaffold usage)
|
||
|
||
Not implemented yet:
|
||
|
||
- real Audita execution
|
||
- real analyzer integration
|
||
- real remote archive/storage backend
|
||
- real notification backend
|
||
|
||
## Run Tests
|
||
|
||
```bash
|
||
go test ./...
|
||
```
|
||
|
||
## Run Plan
|
||
|
||
```bash
|
||
go run ./cmd/narratio plan --config examples/pipeline.minimal.yml --session examples/session.minimal.yml
|
||
```
|
||
|
||
## Run Pipeline (Current State)
|
||
|
||
The current `run` command executes `prepare` + real `transcribe` + real `merge` + placeholder downstream stages and records progress in `manifest.json`.
|
||
|
||
Default CLI wiring builds and uses:
|
||
|
||
- real WhisperX HTTP adapter from `pipeline.whisperx`
|
||
- real Seriatim subprocess adapter from `pipeline.seriatim`
|
||
|
||
```bash
|
||
go run ./cmd/narratio run --config examples/pipeline.minimal.yml --session examples/session.minimal.yml
|
||
```
|