| # Architecture |
|
|
| Speech-Text Data Aligners is a library-first forced-alignment framework. The core |
| contract accepts WAV audio plus a known, authoritative transcript and returns |
| backend-neutral timed words. The CLI is only a composition and presentation layer. |
|
|
| The mandatory design rules are defined in the |
| [modular architecture contract](MODULAR_ARCHITECTURE_CONTRACT.md) and the |
| [aligner engineering contract](ALIGNER_ENGINEERING_CONTRACT.md). |
|
|
| ## Layers and Dependency Direction |
|
|
| ```text |
| CLI --------------------> Application --------------------> Core |
| | ^ |
| +----------> Data -------------+ |
| +----------> Benchmarking -----+ |
| +----------> Runtime ----------+ |
| |
| CLI -- lazy composition --> Concrete Backends |
| | | |
| +------------> Core |
| +------------> Runtime |
| ``` |
|
|
| In compact form: |
|
|
| ```text |
| CLI -> Application -> Core |
| -> Data |
| -> Benchmarking |
| -> Runtime |
| |
| Concrete Backends -> Core / Runtime |
| ``` |
|
|
| The enforced consequences are: |
|
|
| - Core does not import application, data, benchmarking, CLI, or concrete backends. |
| - Data and benchmarking do not depend on concrete backends. |
| - Application services receive an `AlignmentBackend` protocol instance; they do not |
| branch on NeMo, MFA, or WhisperX names. |
| - Concrete backend packages do not import one another. |
| - The registry stores lazy dotted factories so unavailable optional runtimes do not |
| break backend-neutral imports or sibling backends. |
| - The CLI delegates annotation and benchmarking to reusable Python services. |
|
|
| ## Current Package Tree |
|
|
| ```text |
| src/speech_text_data_aligners/ |
| |-- __init__.py public backend-neutral facade |
| |-- application/ |
| | |-- annotate.py annotation orchestration and publication policy |
| | `-- benchmark.py identical-request benchmark orchestration |
| |-- backends/ |
| | |-- registry.py immutable lazy backend composition |
| | |-- nemo/ |
| | | |-- backend.py neutral adapter |
| | | |-- config.py typed configuration |
| | | |-- manifest.py reference JSONL and output-manifest parsing |
| | | |-- runner.py isolated NFA execution |
| | | `-- ctm.py word CTM parsing and mapping |
| | |-- mfa/ |
| | | |-- backend.py neutral adapter |
| | | |-- config.py typed configuration |
| | | |-- corpus.py temporary WAV/LAB corpus |
| | | |-- runner.py isolated MFA execution |
| | | `-- textgrid.py word-tier parsing and mapping |
| | `-- whisperx/ |
| | |-- backend.py neutral adapter |
| | |-- config.py typed configuration |
| | |-- segments.py full-WAV authoritative segments |
| | |-- provider.py isolated-worker transport |
| | |-- worker.py lazy heavyweight native runtime |
| | `-- parser.py native word-dictionary parsing and mapping |
| |-- benchmarking/ |
| | |-- metrics.py sparse-gold and pairwise metrics |
| | `-- reports.py JSON/CSV/Markdown report rendering |
| |-- cli/ |
| | |-- main.py command dispatch |
| | |-- annotate.py annotation argument adapter |
| | `-- benchmark.py benchmark argument adapter |
| |-- core/ |
| | |-- models.py immutable neutral values and provenance |
| | |-- protocols.py injected backend contracts |
| | |-- errors.py project exception taxonomy |
| | |-- normalization.py lexical plans and monotonic reconciliation |
| | |-- validation.py result and publication-path invariants |
| | `-- extraction.py six first/last output fields |
| |-- data/ |
| | |-- audio.py WAV resolution and lightweight probing |
| | `-- metadata.py preserving, atomic CSV I/O |
| `-- runtime/ |
| |-- process.py shell-free injected subprocess boundary |
| |-- artifacts.py temporary and retained artifact lifecycle |
| `-- receipts.py hashes and run provenance |
| ``` |
|
|
| Package-marker `__init__.py` files not shown above are deliberately empty. The root |
| `__init__.py` is the tested public facade. |
|
|
| ## Backend Isolation and Native Containment |
|
|
| ```text |
| PARENT PROCESS |
| |
| Python caller or CLI |
| | |
| v |
| backend-neutral application API |
| | |
| v |
| AlignmentBackend protocol |
| | |
| v |
| concrete adapter (NeMo | MFA | WhisperX) |
| | |
| | injected process/provider boundary |
| v |
| +------------------------------------------------------+ |
| | ISOLATED NATIVE RUNTIME | |
| | NeMo NFA process | MFA process | WhisperX worker | |
| | Heavy optional dependencies and model lifecycle | |
| +------------------------------------------------------+ |
| | |
| | native files / native dictionaries |
| v |
| adapter-local builder, parser, and reconciliation |
| | |
| | only neutral records cross this point |
| v |
| AlignmentResult | AlignmentFailure | diagnostics | provenance |
| ``` |
|
|
| NeMo manifests, output manifests, and CTM rows remain inside |
| `backends.nemo`. MFA corpus labels and TextGrid objects remain inside |
| `backends.mfa`. WhisperX segment payloads and native result dictionaries remain |
| inside `backends.whisperx`. NeMo CTM, MFA TextGrid, and WhisperX native dictionaries |
| never escape their adapters; callers receive only backend-neutral models. |
|
|
| The parent process does not import heavyweight NeMo, MFA, WhisperX, Torch, or |
| Torchaudio packages. NeMo and MFA run through the shared shell-free process boundary. |
| WhisperX runs in a dedicated worker that imports its heavy stack only after invocation. |
|
|
| ## Transcript-to-Result Data Flow |
|
|
| ```text |
| authoritative transcript |
| | |
| v |
| backend-specific reference representation |
| | |
| v |
| native timed words |
| | |
| v |
| shared monotonic reconciliation |
| | |
| v |
| shared validation |
| | |
| v |
| AlignmentResult |
| ``` |
|
|
| The authoritative `en_transcript` remains unchanged throughout. A backend may |
| normalize or expand text only through a reversible plan that retains ownership of |
| original lexical words. Shared reconciliation requires complete monotonic coverage, |
| and shared validation rejects non-finite, negative, reversed, overlapping, incomplete, |
| or out-of-audio timestamps. It never clamps, interpolates, or invents a timestamp. |
|
|
| ## Reuse and Composition |
|
|
| The root facade exposes reusable annotation and benchmark services. Applications may |
| inject any object satisfying `AlignmentBackend`, including a lightweight test or |
| custom backend. The default registry is a convenience for the CLI, not a dependency of |
| the application layer. |
|
|
| Benchmarking consumes the same neutral results as annotation. Native parsing, |
| transcript mapping, CSV I/O, metric calculation, report rendering, and process |
| execution each have one owning layer, so adding another adapter does not require |
| changes to established backend-neutral behavior. |
|
|
| Architecture is enforced by deterministic AST tests and Import Linter contracts. The |
| accepted audit and complete dependency evidence are recorded in the |
| [Stage 5 final acceptance report](STAGE_5_FINAL_ACCEPTANCE_REPORT.md). |
|
|
