Introduction

Status: Current Book last changed: 2026-09-16 (commit 34d249d8) This page last changed: 2026-09-01 (commit bb0bb3c9)

TalkBank is the world’s largest open repository of spoken language data. This repository (talkbank-tools) is the Batchalign3 workspace: the machine-learning pipeline that turns audio into richly annotated CHAT transcripts (automatic speech recognition, forced alignment, neural morphosyntactic tagging, and utterance segmentation), together with its web dashboard and an experimental desktop app.

The CHAT-format core (the chatter CLI, the Rust CHAT parsing and validation crates, the tree-sitter-talkbank grammar, and the CLAN command reference) now lives in the separate chatter project and is documented in its own book. This book covers Batchalign3 only.

What Batchalign3 does

Legend: 🔷 = Public preview, ⚠️ = Experimental (not supported for end-users).

Platform and support detail live in the repo-root docs/PLATFORM-SUPPORT.md and docs/RELEASE-CONTRACT.md.

Who this book is for

• Researchers and clinicians transcribing, aligning, or morphotagging audio into CHAT: start with the Batchalign3 User Guide.
• Users coming from Batchalign2: see the Migration Book.
• Contributors to the pipeline: see the Developer Guide.

For CHAT validation, normalization, conversion, or CLAN-style analysis without audio or ML, use the separate chatter project, which has its own CLI and documentation.

Repository layout

crates/         batchalign-* (runtime, types, PyO3 bridge); the CHAT-core talkbank-* crates are consumed from the chatter project
batchalign/     Python worker code (ML inference hosting)
apps/           Tauri v2 desktop app (dashboard-desktop, experimental)
frontend/       React dashboard for the Batchalign server
book/           This documentation (mdBook)

This page last changed: 2026-09-01 (commit bb0bb3c9). The whole book last changed: 2026-09-16 (commit 34d249d8).

Install

Status: Current Last updated: 2026-06-19

Installation for Batchalign3, the audio and ML pipeline for CHAT.

• Batchalign3 (audio + ML): Installation

For CHAT validation, normalization, or conversion without audio or ML (and for the CLAN command reference), use the separate chatter project, which has its own installation guide.

This page last changed: 2026-06-19 (commit 358773df). The whole book last changed: 2026-09-16 (commit 34d249d8).

Quickstart

Status: Current Last updated: 2026-06-19

Transcribe or align media into CHAT. The fastest path is the Batchalign3 Quickstart.

To validate, normalize, or convert existing CHAT without audio or ML, use the separate chatter project and its quick start.

This page last changed: 2026-06-19 (commit 358773df). The whole book last changed: 2026-09-16 (commit 34d249d8).

Batchalign2 -> Batchalign3 Migration Book

Status: Current Last updated: 2026-05-19 17:18 EDT

Scope

This migration book explains the transition from batchalign2 baseline commit 84ad500b09e52a82aca982c41a8ccd46b01f4f2c to the current batchalign3 architecture.

Secondary comparison point when needed:

• released batchalign2 master-branch point: e8f8bfada6170aa0558a638e5b73bf2c3675fe6d

Audience:

• users migrating command-line workflows,
• developers/contributors migrating implementation work.

Why this migration is not a patch release

Batchalign3 is not “batchalign2 plus fixes.” It is a structural rewrite of the format/runtime core:

• CHAT parsing/validation/serialization moved from ad-hoc Python text logic to Rust AST operations.
• job orchestration expanded from local dispatch to daemon + server job modes.
• an intermediate plugin phase was retired; the current release ships in-tree engines and has no public Python plugin or extension loader.
• avoidable runtime dynamic-programming remap paths were narrowed or removed in favor of deterministic identity/index/interval mapping.

The migration also includes durable user-visible improvements that matter to existing BA2 users:

• higher correctness for %mor/%gra, retokenization, and timing writeback,
• faster repeat runs from explicit daemon/server execution and first-class utterance-level caching,
• clearer operational surfaces for long jobs (serve, jobs, logs; openapi is contributor-facing),
• stricter data-structure boundaries so token/word identity is preserved instead of reconstructed after flattening.

The key engineering theme across commands is the elimination of string-based pipelines that produced silently wrong output:

• no more ad-hoc string surgery on CHAT text,
• no more parallel-array patching that drifted when tokenizers disagreed,
• no more broad “just run DP on the flattened text” recovery that masked upstream errors with plausible-looking guesses,
• replaced by stable word identity, explicit indexing, structured AST iteration, and typed validation throughout.

This page is the summary layer. Detailed command-by-command changes now live in:

• User Workflow Migration
• Developer Architecture Migration
• Algorithms, Language, and Alignment Migration

Quick delta map

Comparison states and policy

This book now works from a dual-baseline policy:

The primary comparison is Jan 9 anchor → current BA3:

• use the Jan 9 batchalign2-master anchor for core / non-HK migration claims
• use the Jan 9 BatchalignHK anchor for HK / Cantonese migration claims
• use the Feb 9 BA2 point only when you specifically need the later released BA2 master-branch surface as secondary context

Transient unreleased intermediate states are not cataloged here.

Comparison discipline for release work

The canonical migration baseline is always one of the Jan 9 anchors above.

• Use Feb 9 BA2 only as secondary context when you specifically need the last released BA2 master-branch behavior.
• Do not use later Python operational packaging, fleet wheels, or other deployment artifacts as the migration baseline. Those are useful deployment references, but they blur the actual Jan 9 anchor → BA3 migration delta.
• For HK material, remember that the historical baseline command is batchalignhk, not stock batchalign.
• For preserved Jan 9 runners, keep the native legacy CLI shape: command inputfolder outputfolder.

For local BA2-vs-BA3 parity verification, point a baseline executable explicitly pinned to the correct Jan 9 anchor:

• core / non-HK: a pinned batchalign runner for batchalign2-master
• HK / Cantonese: a pinned batchalignhk runner for BatchalignHK

Both should be run side-by-side against current batchalign3 on the same input. Differences fall into three buckets: BA2 bugs that BA3 fixed (expected), BA3 regressions (file an issue), and intentional behavior changes (cross-reference the corresponding section of this migration book).

How to read this migration book

1. Start with User Workflow Migration for command/runtime behavior and release-surface deltas.
2. Then read Developer Architecture Migration for control-plane, typed-contract, and codebase-structure changes.
3. For algorithmic behavior (alignment, retokenization, multilingual/Japanese, DP), read Algorithms, Language, and Alignment Migration.
4. For engine-extension details, read Cantonese and CJK, Architecture and Adding New Engines.

Relationship to existing detailed references

This book is the migration crosswalk. Deep subsystem specifics remain in the existing architecture/reference chapters (CHAT parsing, forced alignment, multilingual, MWT, Japanese morphosyntax, HK engine architecture, server architecture, dynamic-programming policy).

“Every change” interpretation and audit method

The migration scope is broad enough that “every change” is covered by subsystem catalog, not by line-by-line patch replay. This book therefore provides:

• explicit baseline anchoring (84ad500...),
• optional later-BA2 release anchor (e8f8bfa...) when needed for the last shipped master-branch behavior,
• command/runtime/architecture/algorithm/engine-extension change catalogs,
• pointers to subsystem references where each class of change is fully specified,
• practical user and contributor migration checklists.

Intermediate migration campaign notes (for example branch-by-branch progress logs and implementation spikes) are not treated as canonical book content. The book keeps only current-state behavior plus baseline migration crosswalks.

This page last changed: 2026-06-19 (commit c82a6d03). The whole book last changed: 2026-09-16 (commit 34d249d8).

User Workflow Migration (batchalign2 -> batchalign3)

Status: Current Last updated: 2026-09-07 07:04 EDT

This page describes durable differences between:

• the Jan 9 2026 batchalign2-master baseline 84ad500b09e52a82aca982c41a8ccd46b01f4f2c for core / non-HK behavior,
• the Jan 9 2026 BatchalignHK baseline 84ad500b09e52a82aca982c41a8ccd46b01f4f2c for HK / Cantonese behavior,
• the later released batchalign2 master-branch point e8f8bfada6170aa0558a638e5b73bf2c3675fe6d (2026-02-09) where relevant, and
• current batchalign3.

It does not document transient unreleased migration-stage behavior.

1) Command surface: what changed for daily usage

Binary/package naming

• batchalign2 CLI entrypoint: batchalign
• batchalign3 CLI entrypoint: batchalign3 (plus Rust binary integrations)

Historical HK command nuance

For HK / Cantonese work, the preserved legacy command history is slightly different from stock BA2:

• stock legacy CLI: batchalign
• HK legacy CLI: batchalignhk
• preserved Jan 9 legacy runners use native directory-I/O invocation: command inputfolder outputfolder

Current batchalign3 unifies the modern surface under batchalign3, but live parity checks should still compare against the historically correct legacy command.

Command continuity and expansion

Core commands are preserved (align/transcribe/translate/morphotag/coref/utseg). Relative to the Jan 9 BA2 baseline, batchalign3 also adds operational commands that were not yet first-class there:

• serve, jobs, logs
• cache

Command crosswalk (BA2 baseline -> BA3)

Important nuance:

• this table is anchored to the Jan 9 BA2 baseline on purpose;
• by the later released Feb 9 BA2 point, cache and bench were already public and runtime support around --server had expanded substantially;
• batchalign3 should therefore be read as a further rewrite/hardening of that direction rather than as the first moment operational tooling appeared.

Comparison discipline for user-facing validation

When validating migration behavior or rebaselining expectations, use the correct Jan 9 anchor for the material you are testing:

• core / non-HK: Jan 9 batchalign2-master pinned to 84ad500...

• HK / Cantonese: Jan 9 BatchalignHK pinned to 84ad500...

• Use Feb 9 BA2 only when the specific question is about the later released BA2 master-branch surface.

• Do not use later Python operational packages as the migration baseline; those represent later deployment/package choices, not the Jan 9 migration anchor.

For practical local checks:

• use scripts/stock_batchalign_harness.py for curated benchmark cases
• use scripts/compare_stock_batchalign.py for raw transcript/tier diffs

Both tools should be pointed at the correct 84ad500... baseline executable, and preserved legacy runners should keep their native command inputfolder outputfolder syntax.

For HK material in particular, that means comparing against batchalignhk, not stock batchalign.

transcribe for daily English work: nothing changed

If you transcribe English audio, your commands work exactly as before:

# BA2: --lang defaults to "eng", no need to type it
batchalign transcribe recordings/ output/

# BA3, same default, same behavior
batchalign3 transcribe recordings/ -o output/

The only required change is the binary name (batchalign3) and the preferred output flag (-o instead of positional). --lang still defaults to "eng". You do not need to type --lang eng unless you want to be explicit.

New in BA3: --lang auto. This is an optional feature for bilingual or code-switched recordings where you don’t want to pick a single language. Whisper’s multilingual model auto-detects the spoken language from the audio. You never need --lang auto for monolingual English work.

= sign syntax. Both --lang eng and --lang=eng are identical and have always been identical (this was true in BA2 as well). Use whichever you prefer.

Flag behavior and defaults

The Feb-9-BA2-era global flags listed below were not carried into BA3. A Feb-9 BA2 script that passes any of them gets a clap parse error, not a silent no-op. They were never in the Jan 9 BA2 baseline either; they were added in Feb 9 master and removed in BA3.

• --memlog
• --mem-guard
• --adaptive-workers / --no-adaptive-workers
• --pool / --no-pool
• --adaptive-safety-factor
• --adaptive-warmup
• --shared-models / --no-shared-models
• --lazy-audio

There are hidden per-command BA2 aliases that still parse and map onto the current typed options:

• align: --whisper, --rev, --whisper-fa, --wav2vec
• transcribe: --whisper, --whisperx, --whisper-oai, --rev, --diarize, --nodiarize
• benchmark: --whisper, --whisper-oai, --rev

--whisperx and --whisper-oai still parse, and the engines they select are not implemented in BA3: the job is refused at submission with a message naming the engines that work.

transcribe keeps BA2’s opt-in surface but intentionally improves its diarization semantics. Both systems keep --diarize as an opt-in path with a False / auto default. If you use Rev.AI (the default engine), speaker labels are already part of the ASR response and are always applied, you get multi-speaker output in both BA2 and BA3 without --diarize, and BA-side utterance segmentation still runs separately. When --diarize is explicitly requested, both Jan 9 BA2 and current BA3 run a separate speaker stage on top of the ASR output, including Rev-labeled transcripts. BA3 now defaults that stage to pyannoteAI Precision-2 and projects its segments onto timed ASR words before utterance segmentation; BA2 relabels already-built utterances. Use --speaker-engine pyannote or --speaker-engine nemo for BA3’s local alternatives. The flag remains most important for Whisper-based workflows where the ASR engine does not produce speaker labels at all. BA2’s old help text claiming Rev ignored --diarize was stale; the implementation did not.

Utility command migration

The operational command surface also changed in stages:

Per-command details (see comparison states for the three-state framing):

• setup:
  • Jan 9 / Feb 9 BA2: Python-side config wizard for ~/.batchalign.ini and Rev.AI defaults
  • current BA3: same public purpose, but implemented in Rust with explicit interactive/non-interactive validation
• models:
  • Jan 9 / Feb 9 BA2: public training entrypoint mounted directly from the Python training runtime
  • current BA3: still fundamentally a Python training surface; the Rust CLI forwards to the Python runtime rather than re-implementing training logic
• version:
  • Jan 9 / Feb 9 BA2: version surfaced through Click root-command metadata
  • current BA3: explicit version subcommand with package version plus build hash
• cache:
  • Jan 9 BA2: no public cache-management command
  • Feb 9 BA2: Python cache command for stats/clear/warm against Python-side cache-manager state
  • current BA3: Rust cache command for analysis/media cache inspection and clearing aligned to the current SQLite/media-cache runtime
  • practical delta: cache clear --all also removes permanent UTR cache entries, while BA2’s cache warm prewarm flow is not carried forward
• bench:
  • Jan 9 BA2: no public benchmarking command
  • Feb 9 BA2: Python repeated-dispatch timing helper with runtime toggles
  • current BA3: Rust repeated-dispatch benchmarking with typed options and structured output for regression work
• serve, jobs, logs:
  • absent from Jan 9 and released Feb 9 BA2 as public CLI commands
  • current BA3: real server/job operations surface, reflecting the shift from one-shot local execution toward explicit daemon/server/job control
• openapi:
  • absent from Jan 9 and released Feb 9 BA2
  • current BA3: contributor-facing API/schema export tooling rather than a normal end-user workflow
• daemon/server routing:
  • released Feb 9 BA2 already had richer local runtime controls
  • current BA3: dispatch distinguishes commands that prefer the local daemon from commands that can target a remote server directly. The set that prefers local-daemon execution is transcribe, transcribe_s, benchmark, and avqi; for these, an explicit --server flag is ignored in favor of the local daemon. (See command_prefers_local_daemon in crates/batchalign/src/cli/dispatch/mod.rs.) A separate sidecar daemon profile exists in cli/daemon.rs for transcribe workloads that need a different Python environment, but the current dispatch code does not auto-route commands to it on capability mismatch, it is started and stopped through serve lifecycle commands.

1.1) Biggest durable user-visible changes

If you are coming from BA2, the changes most likely to affect real corpus results are:

• morphotag correctness is stronger: %mor/%gra generation now runs against a structured CHAT representation and preserves token provenance more consistently. Multilingual files process all languages in parallel (semaphore-bounded cross-language dispatch, see morphosyntax/batch.rs in crates/batchalign/), and large single-language batches are split across multiple workers (up to DEFAULT_MAX_WORKERS_PER_KEY), the observed practical effect is substantially faster wall-clock time on multilingual corpora, though no published benchmark anchors a specific multiplier.
• retokenization is more predictable: Batchalign3 no longer relies on runtime global DP remapping to reconcile Stanza output back to CHAT.
• alignment and timing writeback now preserve stable identity and explicit order more often instead of reconstructing results from flattened strings later.
• repeated runs are materially faster: utterance-level caching and daemon/server execution remove much of the Jan 9 BA2 per-file process startup cost.
• long runs are easier to operate: job/log/status surfaces replace much of the Jan 9 BA2 “watch one terminal and inspect files later” model.

Some of these improvements were already present in the Feb 9 BA2 release (see comparison states); BA3 adds the Rust-first control plane and stronger CHAT-ownership boundaries.

2) Runtime mode: local CLI vs daemon/server discovery

In batchalign2, most workflows were “run command locally, wait, inspect files.” Batchalign3 supports that, but also supports:

• local daemon-backed execution,
• server-managed job queues and status APIs,
• explicit operational commands such as serve, jobs, and logs.

UI consequence: in addition to terminal progress, the modern stack supports dashboard-style and API-style operational visibility (jobs, logs, health and OpenAPI surfaces), which substantially changes how teams monitor long runs.

2.1) UI migration notes

• CLI UX: still primary for batch workflows, but now with explicit operational subcommands rather than implicit one-shot process assumptions.
• Server/API UX: job/status endpoints support automation and remote control workflows that BA2 users previously handled with custom shell glue; openapi is the contributor-facing schema export surface for that API.
• Dashboard UX: the server-hosted web dashboard is real when dashboard assets are installed. What is deferred from the first public batchalign3 release is the separate desktop/Tauri launcher path, not the web dashboard itself.
• Editor UX (ecosystem): downstream editor integrations now prefer structured alignment sidecars where available, reducing regex-only timing extraction drift.

This changes how users should think about failures/retries:

• prefer jobs/logs inspection over searching ad-hoc terminal output,
• use explicit cache controls for reproducibility and reruns,
• treat processing as resumable jobs instead of monolithic one-shot runs.

3) Alignment behavior users will notice

This section is about user-visible consequences. The mechanism-level story (ID-first timing transfer, retokenization mapping, %gra validation, and the reduced role of broad runtime DP remap) lives in Algorithms, Language, and Alignment Migration.

Realign-after-edit behavior

Old BA2 workflows often resolved transcript edits by broad remap over flattened text. With repeated words, retraces, or overlap, that could produce unstable timing reassignment.

Current BA3 prefers deterministic transfer and explicit untimed outcomes:

• fewer surprise timing jumps across utterances,
• clearer unresolved cases instead of silent “best fit” remaps,
• more stable %wor and bullet writeback ordering.

The released Feb 9 BA2 point had already improved align materially relative to Jan 9, but current BA3 is where the transfer/writeback policy becomes much more consistently identity-aware and validation-driven.

Retokenization and %mor / %gra differences

If you compare corpus outputs, expect some %mor / %gra differences to be corrections, not regressions.

The user-visible changes that matter most are:

• %gra root attachment now follows head=0,
• invalid root/head structures are rejected instead of written out,
• MWT and contraction handling are more stable,
• special forms such as @c, @s, and xbxxx are handled more explicitly,
• reflexive pronouns emit reflx,
• retokenize=false preserves original tokenization instead of silently rewriting it.

Important comparison nuance:

• some special-form and pronoun behavior already existed in BA2,
• the durable BA3 change is that these behaviors now sit inside structured mapping and validation rather than positional repair.

Alignment and morphotag migration in two steps

For users, the practical current-state rule is:

• current alignment prefers deterministic transfer and explicit untimed outcomes over silent global remap choices;
• current morphotag output is more strongly validated, so some BA2-to-BA3 corpus diffs should be treated as bug fixes.

Other commands

4) Multilingual and language-specific changes users will notice

Code-switching and @s policy

Relative to BA2, current BA3 changes both the analysis path and the transcript contract for @s:

• per-word @s / @s:LANG routing is now default-on for morphotag; use --no-l2-morphotag if you need the older L2|xxx placeholder behavior for reproducibility
• explicit @s:LANG still routes to LANG even when LANG is missing from @Languages, but validation emits warn-only E254 so the header mismatch is visible
• whole-utterance same-language all-@s runs are no longer accepted as an utterance-language shorthand; BA3 validates them as E255 and expects [- lang] instead
• chatter debug fix-s is the companion repair tool for migrated corpora: it rewrites qualifying whole-utterance @s runs, appends missing explicit languages to @Languages, and skips already-correct files

Stanza multi-word token (MWT) outputs

Batchalign3 handles tokenizer expansions (one orthographic token -> multiple UD units) more predictably than BA2-era remap-heavy paths.

This matters directly for migration because BA2-era outputs could drift when tokenizer-created words were later forced back onto CHAT via heuristic remap. Batchalign3 keeps the original CHAT structure as the primary truth and maps UD analysis back onto it deterministically. The mechanism details live in Algorithms, Language, and Alignment Migration.

Japanese and other language preprocessing/postprocessing

Key upgrades include stronger language-aware normalization and postprocessing guards (including Japanese-specific morphology handling and punctuation/token cleanup pipelines) to reduce downstream alignment and %mor drift.

4.1) Structural theme across text commands

The command table above already covers the command-by-command migration story. The shared implementation consequence is:

• Python is now a pure model server: it returns raw inference outputs and contains zero CHAT parsing, zero text normalization, and zero domain logic.
• Rust owns all CHAT parsing, payload extraction, validation, reinjection, and output policy, a complete inversion of BA2’s Python-owns-everything architecture, enforced by allowlist tests.

That pattern is why transcribe, translate, utseg, and coref now behave more predictably than the older Python-monolithic paths. The same separation also explains why benchmark is easier to reason about in BA3: Rust owns the composed workflow boundary instead of hiding it inside Python dispatch glue.

Media-analysis commands (opensmile, avqi)

These are lighter migration targets than the CHAT-processing commands above. For most users the command lines did not change:

• opensmile input_dir output_dir is still the shape
• avqi input_dir output_dir is still the shape
• feature-set and language options are preserved

The important durable differences are operational rather than algorithmic:

• BA3 runs them behind typed prepared-audio V2 worker contracts
• failures surface through job/log tooling instead of ad hoc .error.txt hunting during server/daemon runs
• avqi no longer needs on-disk temporary mono WAV files

opensmile CSV output matches the BA2 shape exactly: feature,value header followed by one row per feature, single-column. BA2-era scripts that parse this layout continue to work without modification.

5) Migration checklist for existing users

1. Update the binary name in your scripts: batchalign → batchalign3. Output is now an -o flag instead of a positional argument.
2. Remove any Feb-9-BA2-era global flags from your scripts. The following were never carried into BA3 and will produce a parse error: --memlog, --mem-guard, --adaptive-workers, --no-adaptive-workers, --pool, --no-pool, --adaptive-safety-factor, --adaptive-warmup, --shared-models, --no-shared-models, --lazy-audio. (Per-command hidden BA2 aliases like --whisper, --rev, --diarize still work, they translate to current typed flags.)
3. Validate your expected outputs against current golden behavior, especially if your corpus has overlap / retraces / repetitions.
4. Rebaseline any %mor / %gra expectations that depended on BA2 bugs or unstable remap behavior. Compare against current intended outputs, not Jan 9 BA2 accidental ones.
5. If you previously relied on out-of-tree Python integration code, port it to subprocess calls into batchalign3. There is no public Python API in BA3, see No Python API.
6. (Reserved, was previously a note about opensmile CSV layout changing during the rewrite. That divergence has been corrected; opensmile output now matches the BA2 feature,value shape and no script changes are required.)
7. Adopt jobs / logs / cache operational commands for repeatability.
8. For editor media workflows, use sidecar / timing-index aware tooling where available (instead of bullet-regex-only extraction).

This page last changed: 2026-09-09 (commit 8f4ed0f2). The whole book last changed: 2026-09-16 (commit 34d249d8).

Developer Architecture Migration (batchalign2 -> batchalign3)

Status: Current Last updated: 2026-07-30 18:21 EDT

Comparison anchors for this page:

• batchalign2-master 84ad500b09e52a82aca982c41a8ccd46b01f4f2c for core / non-HK behavior
• BatchalignHK 84ad500b09e52a82aca982c41a8ccd46b01f4f2c for HK / Cantonese behavior
• later released batchalign2 master-branch point e8f8bfada6170aa0558a638e5b73bf2c3675fe6d where needed
• current batchalign3

This page excludes transient unreleased migration-branch states.

See also:

• BA2 Architecture Reference for the frozen Jan 9 baseline architecture
• BA2 Compare Migration for the dedicated batchalign2-master compare to BA3 compare rewrite map
• Dispatch and Execution for the current contributor-facing command architecture (command model, planning, recipe-driven execution kernel)

Comparison discipline for contributors

Contributor-facing parity and regression checks should anchor to the correct Jan 9 preserved baseline:

• core / non-HK: Jan 9 batchalign2-master

• HK / Cantonese: Jan 9 BatchalignHK

• The later Feb 9 BA2 point is secondary context only.

• later Python operational installs are deployment references, not migration baselines.

Use the repo-local comparison tools accordingly:

• scripts/stock_batchalign_harness.py for curated benchmark cases
• scripts/compare_stock_batchalign.py for raw side-by-side output diffs

Both should be pointed at the historically correct executable explicitly pinned to 84ad500....

• For HK material, that means batchalignhk, not stock batchalign.
• Preserved Jan 9 legacy runners should keep their native CLI shape: command inputfolder outputfolder.
• When older legacy benchmark runs emit .asr.cha/.wer.txt/.diff rather than modern .compare.csv, the curated harness should normalize them by rescoring the emitted .asr.cha through current batchalign3 compare.

1) Core architecture shift

batchalign2 mental model

• Python-centric runtime and pipeline composition.
• CHAT parsing/manipulation through ad-hoc string transforms and parallel arrays.
• Every command flattened structured data to strings for engine calls, then attempted to reconstruct structure from engine output, an architecturally lossy round-trip that produced silent drift whenever tokenizers disagreed.

current batchalign3 mental model

• Rust-first CHAT core (parser, validator, AST, serializer).
• Python and the Rust control plane integrate via explicit typed contracts.
• identity-preserving data flow (word IDs, utterance/index metadata, spans).
• service-oriented operations (daemon/server/job lifecycle).

The key contributor shift is: preserve structure, do not reconstruct it later from flattened strings.

1.1) Durable engineering deltas

The durable contributor-facing changes since the Jan 9 BA2 baseline are:

• data structures moved from Python object/string surgery toward typed Rust AST ownership and explicit worker payloads;
• command internals moved away from array-position repair and flatten-then-fix workflows toward stable IDs, explicit indices, chunk maps, and AST walks;
• orchestration moved from monolithic local dispatch toward daemon/server/job routing with explicit boundaries;
• morphosyntax, FA, and related passes now favor deterministic provenance mapping over runtime remap heuristics;
• regression defense is stronger: more golden cases, tighter invariants, and explicit policy against reintroducing runtime DP remap paths.

See comparison states for the Jan 9 BA2 → Feb 9 BA2 → BA3 framing. Feb 9 BA2 already gained cache, dispatch, and morphotag/alignment cleanup; BA3 moves orchestration, typed contracts, and CHAT ownership into Rust.

2) Concurrency and worker model

batchalign2 model

Jan 9 baseline (84ad500b): Purely sequential. dispatch.py (196 lines) processes files one at a time in a simple for-loop, no ProcessPoolExecutor, no ThreadPoolExecutor, no adaptive workers, no file sorting, no shared-models mode. The pipeline is created once and called on each file sequentially.

Feb 9 master (e8f8bfad): Adds full concurrent dispatch (1,044 lines in dispatch.py). Uses Python’s concurrent.futures:

flowchart TD
    cli["CLI dispatch\n(Feb 9 only)"]
    classify{"Engine pool-safe?"}
    thread["ThreadPoolExecutor\n(shared pipeline, mutex)"]
    process["ProcessPoolExecutor\n(forked, model copy per worker)"]
    file1["Worker: process file A"]
    file2["Worker: process file B"]

    cli --> classify
    classify -->|"Rev.AI, Google Translate"| thread
    classify -->|"Whisper, Wave2Vec, Stanza"| process
    thread --> file1
    thread --> file2
    process --> file1
    process --> file2

Key characteristics (Feb 9 only, none of these exist in Jan 9):

• Pool-safe engines (Rev.AI, Google Translate): ThreadPoolExecutor: one pipeline loaded in the main process, threads share models via a mutex. Memory-efficient but limited to API-backed or thread-safe engines.
• Pool-unsafe engines (Whisper, Wave2Vec, Stanza, Pyannote): ProcessPoolExecutor , each worker is a forked subprocess with its own model copies. N workers = N× model memory.
• Adaptive worker capping: monitors RSS peaks and throttles new submissions when available memory drops below a reserve (10% of system RAM).
• File sorting: largest files dispatched first to prevent straggler effects.
• No persistent workers: executors are job-scoped, all workers die after each job completes. Next job reloads models from scratch.
• Optional shared-models mode (--shared-models): uses fork() to inherit parent’s loaded models. Linux-only, disabled on macOS+MPS, crash-prone.

Memory characteristics (from Feb 9 BA2 benchmarks):

batchalign3 model

batchalign3 uses a Rust control plane with persistent Python worker subprocesses:

flowchart TD
    server["Rust server (batchalign)"]
    pool["WorkerPool"]
    profile{"WorkerProfile"}
    gpu["SharedGpuWorker\n1 process, ThreadPoolExecutor\n(ASR + FA + Speaker models)"]
    stanza["WorkerGroup\nN processes, exclusive checkout\n(Stanza NLP models)"]
    io["WorkerGroup\n1 process, exclusive checkout\n(Translation, OpenSMILE, AVQI)"]
    t1["Thread 1: FA file A"]
    t2["Thread 2: FA file B"]
    t3["Thread 3: ASR file C"]

    server --> pool
    pool --> profile
    profile -->|GPU| gpu
    profile -->|Stanza| stanza
    profile -->|IO| io
    gpu --> t1
    gpu --> t2
    gpu --> t3

Key differences from BA2:

Memory comparison (mixed English workload, align + morphotag):

The ~3× memory reduction comes from two sources:

1. GPU profile shares ASR, FA, and Speaker models in one process (vs 3 separate)
2. Persistent workers eliminate per-job model reloading overhead

3) Codebase crosswalk for contributors

Baseline anchors used for this crosswalk:

• BA2 CLI commands: batchalign/cli/cli.py @ 84ad500
• BA2 dispatch/runtime bridge: batchalign/cli/dispatch.py @ 84ad500
• BA2 morphosyntax surface: batchalign/pipelines/morphosyntax/ud.py @ 84ad500
• later released BA2 master-branch CLI/dispatch: batchalign/cli/{cli,dispatch}.py @ e8f8bfa
• BA3 Rust CLI args/command tree: crates/batchalign/src/cli/args/mod.rs

3.1) Data-structure shift: what changed and why it matters

The largest durable implementation change is the move from reconstructive pipelines to identity-preserving pipelines. This matters more than the language change from Python to Rust: BA2’s correctness failures came from losing structure and trying to recover it, not from Python being slow.

In BA2, major stages frequently crossed these boundaries:

• parse text into Python objects,
• flatten or normalize text for engine calls,
• run external NLP/ASR,
• rebuild higher-level structure from token strings afterward.

In BA3, the preferred pattern is:

• parse CHAT once into a typed structure,
• extract explicit payloads for inference,
• return typed or schema-constrained results,
• inject back into the original structure without losing provenance.

That change directly explains many correctness improvements in morphotag, retokenization, timing writeback, and validation.

In practical contributor terms:

• prefer stable identifiers over “find the same token again later”,
• prefer explicit index maps over positional guesswork,
• prefer AST iteration over flatten/split/reparse loops,
• prefer narrow deterministic fallback over broad DP recovery on flattened text.

This is not abstract guidance. Current morphotag/alignment code now enforces it in concrete ways:

• %gra construction validates root/head/chunk invariants before writeback,
• special-form handling is explicit (@c, @s, xbxxx) instead of being recovered indirectly from placeholder strings,
• whole-utterance same-language all-@s is now a validation concern (E255), while explicit undeclared @s:LANG is warn-only (E254) and still routes to the named language,
• retokenization rebuilds AST content directly rather than patching flattened string output,
• UTR and FA use explicit IDs/indices where available before any fallback.

3.2) Command-by-command orchestration shift

The same principle shows up across the command surface:

• transcribe:
  • Jan 9 / Feb 9 BA2: Python owned ASR output processing, retokenization, and CHAT construction in one pipeline
  • current BA3: Python worker: raw ASR only Rust: post-process tokens, assemble CHAT, optionally run utseg and morphotag
• translate:
  • Jan 9 / Feb 9 BA2: Python translated utterance text and wrote translation tiers through Python-side CHAT generation
  • current BA3: Python worker: raw text translation only Rust: extract text payloads and inject translated results back into CHAT
• utseg:
  • Jan 9 / Feb 9 BA2: Python owned constituency parsing, phrase extraction, DP reconciliation, and utterance rebuilding
  • current BA3: Python worker: constituency trees Rust: assignment computation and CHAT mutation
• coref:
  • Jan 9 / Feb 9 BA2: Python already ran document-level coref, detokenized the document, and DP-remapped chains back onto forms
  • current BA3: Python worker: structured chain data Rust: document-level payload collection, sparse %xcoref injection, and validation
• compare:
  • later batchalign2-master: Python owned morphosyntax -> compare -> compare_analysis, projected through the Python Document model, and relied on string/document regeneration as the projection mechanism
  • current BA3: Rust: morphotag main only, keep gold raw, build a ComparisonBundle with local-window alignment plus structural word matches, and materialize either the released main output or an internal AST-first gold projection
• benchmark:
  • Jan 9 / Feb 9 BA2: Python command path around ASR + gold transcript + WER output files
  • current BA3: Rust: typed command options and per-file infer dispatch Rust core: WER computation exposed through batchalign_core Python package: optional convenience wrapper only, not worker infer logic
• opensmile / avqi:
  • Jan 9 / Feb 9 BA2: Python feature-analysis commands with local library calls
  • current BA3: Rust: typed command options and prepared-audio V2 dispatch Python worker: pure analysis tasks with structured request/response payloads

This is the durable architectural pattern to preserve:

• inference workers should do inference,
• orchestration and CHAT ownership should stay on the Rust side.

3.3) Utility-command control-plane shift

The utility command story also changed in code-meaningful ways:

• setup:
  • Jan 9 / Feb 9 BA2: Python Click flow writing ~/.batchalign.ini
  • current BA3: Rust-owned prompt/validation/write path preserving the same compatibility file
• models:
  • Jan 9 / Feb 9 BA2: Python command tree directly exposed training runtime
  • current BA3: Rust CLI still delegates to the Python training module; this is a control-plane wrapper change, not a training-stack rewrite
• version:
  • Jan 9 / Feb 9 BA2: root-command version metadata
  • current BA3: explicit subcommand plus build-hash reporting, useful for support and stale-binary diagnosis
• cache:
  • Feb 9 BA2 introduced Python cache stats/clear/warm around Python-side cache state
  • current BA3 redefines that command around the Rust runtime cache boundary: SQLite analysis cache plus media cache inspection/clearing
• bench:
  • Feb 9 BA2 introduced a Python repeated-dispatch timing helper
  • current BA3 keeps the same basic purpose but moves dispatch/control into Rust typed options and structured benchmark output
• serve, jobs, logs, openapi:
  • These are the clearest BA3-only utility additions.
  • They exist because the runtime model itself changed: once jobs, server health, logs, and API schema became first-class control-plane concerns, the CLI needed explicit ops commands instead of assuming one-shot local runs.

User-facing command/history detail belongs in user-migration.md. This page keeps the developer-facing architectural consequence: the control plane is now explicit, typed, and operationally observable.

4) Concurrency and orchestration differences

Batchalign3 makes concurrency explicit at architecture boundaries:

• command routing to local/remote execution backends,
• queueable jobs with durable status and logs,
• explicit server health, job status, and observable daemon/server boundaries.

Jan 9 BA2 had no concurrency: it processed files sequentially in the main process, loaded all models fresh each time, and had no mechanism to share state across runs. Feb 9 BA2 added concurrent dispatch (see Section 2), but workers were still job-scoped and models were reloaded from scratch per job. In BA3, contributors should model command execution as staged orchestration across explicit runtime boundaries.

This requires contributors to design for:

• idempotent work units,
• resumable/observable processing stages,
• strict input/output schema validation between boundaries.

4.1) Performance model shift

The durable performance improvement story is architectural:

• repeated one-file/one-process startup is no longer the only execution model;
• the daemon/server path keeps heavyweight engines warm across runs;
• cache misses can be batched across files instead of paying per-file setup overhead repeatedly;
• cache ownership and job state are explicit rather than incidental.

This is the kind of performance change that should remain in the migration book. Short-lived benchmark spikes or temporary regressions should not.

5) Data model and API boundary implications

For recent DP-migration work, no additional core CHAT AST augmentation was required because existing model identity/timing surfaces were sufficient.

Guideline for future work:

• do not enlarge the core AST for editor-only derived views,
• expose sidecar APIs for high-churn UI metadata,
• keep AST focused on durable linguistic source-of-truth structures.

Related rule for migration documentation: explain changes in algorithm choice, data structures, and public behavior; do not preserve branch-by-branch implementation churn.

6) Testing posture for contributors

Migration-era quality now depends on layered tests:

• golden tests for edge corpora (repeat/retrace/overlap/multilingual),
• no-DP-runtime allowlist tests (batchalign/tests/test_dp_allowlist.py: Rust PyO3 call sites, chat-ops call sites, Python inference zero-DP),
• Stanza configuration parity checks (batchalign/tests/pipelines/morphosyntax/test_stanza_config_parity.py, MWT exclusion parity, Japanese processor parity, English gum package parity).

7) Python API migration

BA2 Python API: all removed

BA2 exposed a rich Python API: Document, CHATFile, BatchalignPipeline, and 23+ individual engine classes (WhisperEngine, StanzaEngine, etc.).

All of these have been removed. BA3 is CLI-first. The Rust server owns all CHAT manipulation. There is no Python API for parsing, mutating, or serializing CHAT files.

External usage was minimal. A pre-release audit found that existing PyPI downloads were essentially all CLI usage; no downstream packages depended on the Python API, no academic papers referenced it. Removing the Python surface affects no observed external user.

BA3 equivalents for each BA2 pattern

Running pipeline operations:

# BA2
from batchalign import BatchalignPipeline
nlp = BatchalignPipeline.new("morphosyntax", lang="eng")
result = nlp("input.cha")

# BA3: CLI is the only entry point
# Note: morphotag has no `--lang`; per-file `@Languages:` headers drive routing.
import subprocess
subprocess.run(["batchalign3", "morphotag", "input/", "-o", "output/"])

Reading CHAT files: Use standard file I/O. BA3 does not provide a Python CHAT parser, use the CLI for processing.

Validation: Use batchalign3 validate input/ or the chatter TUI.

Removed surfaces

What’s genuinely lost

Engine composition (BatchalignPipeline.new("asr,morphosyntax,fa") with specific engine instances): BA3 uses the CLI command surface. Multi-step pipelines run as sequential CLI commands.

Direct AST mutation (doc[0][0].text = "modified"): The CHAT AST is Rust-owned. Edit CHAT files as text or use the chatter TUI.

Neither limitation affects any known external user.

8) Onboarding plan for legacy contributors

1. Start with the command/runtime crosswalk plus the current HK engine and extension-layer chapters.
2. Pick one existing BA2 customization and re-implement it as either a built-in engine module or a CLI extension, not a long-lived source fork.
3. Add/extend golden cases before behavior changes.
4. For alignment/morphology changes, route through core AST/validator contracts and keep side effects deterministic and observable.

This page last changed: 2026-07-31 (commit 8e3b0e23). The whole book last changed: 2026-09-16 (commit 34d249d8).

BA2 Compare Migration

Status: Current Last updated: 2026-05-01 22:47 EDT

This page is for contributors who know batchalign2-master compare and want to judge the BA3 Rust reimplementation on its real semantics rather than on superficial output shape.

The shortest summary is:

• BA3 keeps the important batchalign2-master compare behavior: per-gold local window selection, local DP alignment, %xsrep, %xsmor, and .compare.csv.
• BA3 intentionally changes how projection and serialization are implemented: the reimplementation keeps CHAT in a Rust AST, carries typed alignment metadata, materializes compare tiers through explicit typed content models, and emits .compare.csv from a structured table model instead of reconstructing structure from strings or a Python Document shell.

Source map

Use these as the primary files when reviewing the rewrite:

• BA2 reference (the local ~/batchalign2-master archive is checked out at the Jan 9 baseline 84ad500b..., where compare.py does not yet exist; use the post-redesign commit 1f224df346c2ec590d45afa31136a3b878db622b to see the file referenced here, e.g. git -C ~/batchalign2-master show 1f224df:batchalign/pipelines/analysis/compare.py):
  • batchalign/pipelines/analysis/compare.py (CompareEngine / _find_best_segment)
  • ~/batchalign2-master/batchalign/pipelines/analysis/eval.py
  • ~/batchalign2-master/batchalign/cli/dispatch.py
• BA3 reimplementation:
  • crates/batchalign/src/compare.rs (orchestration entry: the runner calls compare() and project_gold_structurally() from talkbank-transform and writes the projected CHAT and .compare.csv)
  • crates/batchalign-transform/src/compare/engine.rs (find_best_segment, compare(): the local-window search and DP-alignment core)
  • crates/batchalign-transform/src/compare/materialize.rs (project_gold_structurally, inject_comparison, clear_comparison)
  • crates/batchalign-transform/src/compare/metrics.rs (CompareMetricsCsvTable, format_metrics_csv)
  • crates/batchalign/src/execution/ (recipe-driven dispatch; replaces old compare_pipeline.rs)

BA2 compare shape vs BA3 compare shape

flowchart LR
    subgraph BA2["batchalign2-master"]
        ba2_main["main transcript"]
        ba2_gold["gold transcript"]
        ba2_mor["morphosyntax on compare inputs"]
        ba2_cmp["window selection + local DP"]
        ba2_doc["Document / string projection"]
        ba2_csv["metrics output"]
        ba2_main --> ba2_mor
        ba2_gold --> ba2_mor
        ba2_mor --> ba2_cmp --> ba2_doc
        ba2_cmp --> ba2_csv
    end

    subgraph BA3["batchalign3 spike"]
        ba3_main["main transcript"]
        ba3_gold["gold transcript"]
        ba3_mor["morphosyntax on main only"]
        ba3_parse["parse main + raw gold into ChatFile ASTs"]
        ba3_cmp["compare()\nwindow selection + local DP\nmain/gold views + structural matches"]
        ba3_proj["project_gold_structurally()\nAST projection"]
        ba3_tiers["typed %xsrep/%xsmor models\n-> UserDefinedDependentTier"]
        ba3_csv["CompareMetricsCsvTable\n-> csv crate"]
        ba3_gold_out["released reference output\nprojected CHAT + .compare.csv"]
        ba3_main_out["internal benchmark output\nmain-annotated CHAT + .compare.csv"]
        ba3_main --> ba3_mor --> ba3_parse
        ba3_gold --> ba3_parse --> ba3_cmp
        ba3_cmp --> ba3_proj --> ba3_tiers --> ba3_gold_out
        ba3_cmp --> ba3_tiers --> ba3_main_out
        ba3_cmp --> ba3_csv
        ba3_csv --> ba3_gold_out
        ba3_csv --> ba3_main_out
    end

Semantics intentionally carried over

These points were treated as the batchalign2-master compare semantics worth preserving:

• gold companions still use the FILE.gold.cha convention
• each gold utterance still selects a best local main window before DP runs
• alignment is still local to that selected window, not one global flat pass
• compare still produces %xsrep, %xsmor, and .compare.csv
• skipped main tokens outside the selected window do not count as insertions
• deleted gold tokens stay untagged (?) unless the reference side already has tags that can be reused structurally

Semantics intentionally changed

These are the deliberate architectural differences from the Python compare path:

1. Main is morphotagged, gold stays raw during artifact construction. BA3 no longer morphotags the gold transcript just to make compare work. This preserves reference-side deletion semantics and avoids inventing tags that were never present in the gold file.

2. Projection is AST-first and serializer-owned. BA3 compare carries explicit structural word-match metadata (gold_word_matches) out of alignment and uses that to project onto the gold ChatFile. It does not infer projection by reparsing %xsrep or by patching reconstructed strings. %xsrep / %xsmor are emitted from typed compare-tier models, and .compare.csv is emitted from a structured table model via the standard Rust csv crate.

3. Tier projection is conservative by design. Exact structural matches may copy %mor, %gra, and %wor wholesale. Full gold-word coverage without exact structural identity may still project %mor. Partial %gra / %wor projection is intentionally withheld until there is a chunk-safe mapping, because “close enough” projection is exactly how BA2-style structural drift happens.

4. Released output now follows the BA2 compare command shape. The public command writes the projected reference transcript at the main file’s output path, together with %xsrep / %xsmor and .compare.csv. The internal main-annotated materializer remains available for benchmark-style flows, but it is no longer the compare command contract.

5. One explicit bug-exception policy is in force. batchalign2-master can emit structurally lossy partial %mor / %gra projection on gold output. BA3 does not reproduce that when it would make the CHAT AST inconsistent. Unsafe partial projection stays conservative.

BA2-to-BA3 code map

What parity work actually proved

The parity work on this branch proved BA3 drift fixes, not a new courtroom-grade BA2 bug report.

Specifically, live batchalign2-master oracles let us fix these BA3 mismatches:

• BA3 had been counting skipped main tokens outside the chosen local window as insertions; batchalign2-master did not
• BA3 had been morphotagging raw gold during compare artifact construction, causing deleted gold tokens to pick up invented POS tags instead of staying ?
• BA3 gold-projected %xsrep / %xsmor was missing the gold utterance terminator as PUNCT

What the rewrite did not prove:

• a new, sharply isolated BA2 compare bug

The direct evidence here is “BA3 was wrong relative to batchalign2-master in these places” plus “BA2’s projection architecture is structurally lossy.” That is enough to justify the AST-first reimplementation, but not enough to claim a fresh BA2 defect report.

Rules for future compare work

If compare keeps evolving in BA3, the safe rules are:

1. extend ComparisonBundle and project_gold_structurally(), not the serialized %xsrep / %xsmor text
2. use AST walkers and dependent-tier helpers before inventing new string glue
3. extend the typed compare-tier / CSV models before widening serializer output strings
4. do not project partial %gra / %wor without explicit chunk-safe mapping
5. treat BA2 as a semantic reference, not a bug-for-bug target

Acceptance checklist for the rewrite

If the question is “should we accept this Rust reimplementation instead of starting over?”, the most useful review checklist is:

• does compare() preserve the batchalign2-master local-window behavior?
• does the workflow keep gold raw and main morphotagged on purpose?
• does projection stay on the CHAT AST instead of text reconstruction?
• are %xsrep, %xsmor, and .compare.csv all driven from the same bundle and lowered through typed serializer models instead of raw string assembly?
• are partial %gra / %wor projections still blocked behind explicit safety rules?

Those are the design commitments that matter more than byte-for-byte loyalty to the Python implementation shell.

This page last changed: 2026-06-19 (commit c82a6d03). The whole book last changed: 2026-09-16 (commit 34d249d8).

BA2 Architecture Reference

Status: Frozen reference Last updated: 2026-05-19 17:18 EDT Baseline: batchalign2-jan9 (84ad500b09e52a82aca982c41a8ccd46b01f4f2c) Supplement: later batchalign2-master compare redesign (1f224df346c2ec590d45afa31136a3b878db622b) as a forward-looking stress test

This page records the architecture of the frozen Jan 9 batchalign2 codebase so contributors have a stable comparison target while redesigning batchalign3.

It is not a nostalgia document. The point is to preserve the useful ideas from BA2 without re-importing the parts that made BA1 and BA2 hard to evolve.

Why This Matters

The Jan 9 BA2 baseline still expresses some architectural ideas more clearly than current BA3 implementation code:

• a central document abstraction
• a visible engine/pipeline split
• straightforward multi-step workflow composition
• a simple read -> transform -> write mental model

At the same time, BA2 also shows the limits of that model:

• sequential assumptions
• stringly dispatch
• implicit task ordering
• weak typing at workflow boundaries
• analyzers returning ad hoc dictionaries instead of typed artifacts

Those strengths and limits should both inform BA3.

Core Abstractions

Document

BA2 has one clear internal representation: Document.

• Document owns transcript structure, metadata, media references, and utterances.
• Utterance owns ordered Form content plus dependent information such as timing, morphology, dependency, comparison tokens, and comments.
• Most engines mutate or analyze Document directly.

flowchart TD
    doc["Document"]
    meta["Headers / Media / Metadata"]
    utt["Utterance[]"]
    form["Form[]"]
    dep["Morphology / Dependency / Timing / Comparison"]

    doc --> meta
    doc --> utt
    utt --> form
    form --> dep

This is BA2’s strongest idea. The codebase has one obvious semantic center.

Engine and Pipeline Model

BA2 splits work between engines and pipelines.

• BatchalignEngine is the unit of work.
• Engines advertise tasks.
• Engines implement one of:
  • generate
  • process
  • analyze
• BatchalignPipeline sequences one generator, zero or more processors, and an optional analyzer.

flowchart LR
    input["media path or Document"]
    gen["Generator engine"]
    proc1["Processor engine"]
    proc2["Processor engine"]
    analyzer["Analyzer engine"]
    output["Document or analysis dict"]

    input --> gen
    gen --> proc1
    proc1 --> proc2
    proc2 --> analyzer
    analyzer --> output

That model made it easy to reason about workflows like:

• transcribe = ASR generation
• morphotag = document processing
• compare = morphosyntax processing -> compare processing -> compare analysis

Transcribe / diarization shape worth preserving

The Jan 9 BA2 transcribe path matters because later help text drifted away from what the code actually did.

• transcribe with Rev.AI: BA2 used Rev speaker labels directly and still ran BA-side utterance segmentation through process_generation(..., utterance_engine=...).
• transcribe_s / --diarize: CLI dispatch mapped to asr,speaker, so the Pyannote speaker processor ran after ASR and relabeled already-built utterances from diarization segments.
• That means BA2’s explicit diarization path was not ignored on Rev.AI; the stale help string was wrong, the pipeline wiring was not.

flowchart LR
    audio["Audio input"]
    rev["RevEngine.generate()\nRev speaker labels + BA utterance segmentation"]
    doc["Document with utterances"]
    plain["transcribe\nUse Rev labels directly"]
    pyannote["PyannoteEngine.process()\nRelabel utterances from speaker segments"]
    diarized["transcribe_s / --diarize\nRev labels first, then dedicated relabeling"]

    audio --> rev --> doc
    doc --> plain
    doc --> pyannote --> diarized

Read / Write / Read-Write Model

BA2 effectively has three workflow shapes even though it never formalizes them as first-class architecture concepts:

• read-write: load a document, mutate it, write it back
• read-analyze-write-sidecar: load a document, analyze it, write CSV or metrics
• generate-then-read-write: create a document from media, then continue through document processing

The implementation lives mostly in CLI glue rather than inside a typed workflow layer:

• format adapters load or save Document
• CLI dispatch discovers files and companions
• _dispatch(...) decides per-file handling
• dispatch_pipeline() turns command names into engine lists

flowchart TD
    cli["CLI command"]
    discover["Discover files / companions"]
    load["Load Document or media path"]
    pipeline["BatchalignPipeline"]
    write_doc["Write CHAT/TextGrid"]
    write_sidecar["Write metrics / CSV / diff"]

    cli --> discover
    discover --> load
    load --> pipeline
    pipeline --> write_doc
    pipeline --> write_sidecar

This model is simple and effective for sequential workflows, but it leaves too much policy in per-command closures and ad hoc dispatch code.

Strengths Worth Reviving

1. One semantic center

BA2’s best architectural property is that almost everything converges on one document model. Contributors can usually answer “what are we operating on?” without hunting across the codebase.

2. Visible multi-step composition

BA2 makes it obvious when one command is actually a sequence:

• morphosyntax first
• compare second
• metrics third

That clarity is still valuable even if the runtime implementation becomes more concurrent or more distributed.

3. Shared normalization seams

Some of BA2’s strongest code is not the pipeline shell itself but the shared normalization utilities around it. The architecture benefited whenever provider-specific weirdness was absorbed before the rest of the pipeline saw it.

4. Easy experimental evolution

Because the sequential document pipeline is easy to understand, major changes like the later compare redesign could land by rewriting one engine plus a small amount of CLI glue.

That developer ergonomics is exactly what batchalign3 needs to recover without throwing away its runtime strengths.

Limits That Should Not Return

1. Implicit task ordering

Processor order is not described by an explicit workflow graph. It is inferred through task ordering conventions. That is brittle and hard to extend.

2. Stringly dispatch

Command composition relies on string names and large if/elif registries. That works at small scale and then becomes a change-management tax.

3. Weak output contracts

Processors return Document, analyzers return dictionaries, and callers need out-of-band knowledge to know what shape they got back. That is a real architectural limit for future multi-artifact workflows.

4. Sequential assumptions

BA2 does not model:

• cross-file batching as a first-class workflow concern (Note: BA3 originally implemented this for morphotag but later migrated to per-file parallel dispatch for better reliability and incremental feedback)
• persistent worker pools
• shared GPU inference hosts
• job lifecycles
• memory gating and runtime scheduling

Those concerns are not small add-ons in BA3. They shape the architecture.

5. Document/rendering coupling

The BA2 document model sometimes mixes transcript semantics with CHAT-specific serialization behavior. That makes it harder to reuse the model as a pure IR.

Later Compare Redesign As A Harbinger

The later compare redesign on batchalign2-master (1f224df346c2ec590d45afa31136a3b878db622b) is valuable not because it is part of the frozen Jan 9 baseline, but because it shows what future architectural pressure looks like.

That change turns compare from:

• one flat hypothesis-vs-gold alignment
• output anchored to the hypothesis document

into:

• per-gold-utterance window selection
• local alignment inside each selected window
• projection of timing, morphology, and dependency from hypothesis onto gold
• output anchored to the gold document

In other words, it is not merely “better WER.” It is a new workflow kind:

• two input documents
• one comparison bundle
• one projected output document
• one metrics sidecar

That is the key lesson for BA3:

batchalign needs architecture for workflow families and typed intermediate artifacts, not just architecture for commands.

Bottom Line

The right BA3 inheritance from BA2 is:

• keep a strong document/artifact center
• keep explicit multi-step workflow composition
• keep provider normalization at stable seams

The wrong inheritance is:

• string registries
• implicit ordering
• sequential-only pipeline assumptions
• ambiguous return types

See Dispatch and Execution for the current BA3 architecture (command model, planning, recipe-driven execution kernel) that preserves BA2’s good ideas while keeping BA3’s concurrency, worker reuse, and typed runtime boundaries.

This page last changed: 2026-05-22 (commit 11b9b13a). The whole book last changed: 2026-09-16 (commit 34d249d8).

Algorithms, Language, and Alignment Migration

Status: Current Last updated: 2026-09-06 23:14 EDT

Comparison anchors:

• batchalign2 baseline 84ad500b09e52a82aca982c41a8ccd46b01f4f2c
• later released batchalign2 master-branch point e8f8bfada6170aa0558a638e5b73bf2c3675fe6d where relevant
• current batchalign3

This page documents durable algorithmic and data-structure changes only. Temporary migration-branch experiments do not belong here.

For user-facing command and output consequences, start with User Workflow Migration. This page explains the mechanism behind those differences.

Comparison discipline

Algorithmic/output parity claims in this page are anchored to the correct Jan 9 baseline for the material under test:

• core / non-HK claims: Jan 9 batchalign2-master

• HK / Cantonese claims: Jan 9 BatchalignHK

• Later Feb 9 BA2 behavior can still be useful secondary evidence when the question is specifically about the last released BA2 master branch.

• later Python operational builds are not the migration baseline for the algorithmic claims documented here.

Use the repo comparison harnesses with the historically correct 84ad500...-pinned runner when validating these deltas in practice. For HK material, that means batchalignhk, not stock batchalign.

1) CHAT parser/validator/AST/serialization as the central algorithmic change

The most important migration is architectural and algorithmic: parsing and validating CHAT is now a typed, structured pipeline. This reduces failure modes caused by line-oriented text surgery and makes downstream alignment and %mor/%gra operations operate on stable structure.

Implication for contributors: if a change can be expressed as AST transform, do that first; avoid direct string hacking.

1.1) Why this changed correctness, not just implementation language

The main gain is not “Rust is faster.” The gain is that parsing, validation, injection, and serialization now operate on stable typed structure.

That directly changes user-visible correctness:

• fewer opportunities for %mor/%gra drift from line-oriented text surgery,
• fewer silent remap choices after tokenization/alignment divergence,
• stronger validation before invalid CHAT is written back out.

This is a fundamental redesign, not incremental cleanup: ad-hoc string manipulation and parallel-array patching are replaced by principled typed structure with explicit provenance, and that structural shift is what drives both the correctness and efficiency gains throughout the migration.

That pattern shows up repeatedly across the migration:

• UTR uses global Hirschberg DP alignment (the same proven approach as old batchalign, now in Rust),
• FA now carries explicit word identity and timing-mode metadata,
• retokenization uses deterministic range/index mapping and AST rebuilds,
• %gra generation uses explicit chunk/head validation rather than positional guesswork.
• utseg now treats constituency parsing and assignment computation as separate steps instead of flattening subtree leaves and DP-aligning them back to forms.
• coref now carries typed sentence/chain structure instead of detokenized text plus DP remap back to utterance positions.

For migration purposes, separate:

2) Dynamic programming: what was removed, what remains

Narrowed or removed from runtime remap paths

• Retokenize char-level DP fallback mapping path was removed, replaced by deterministic interval/index mapping with length-aware monotonic fallback.
• FA response handling uses indexed word timings or deterministic token stitching in fa/alignment.rs: no DP.

For FA, the precise current claim is narrower:

• current Rust FA response handling uses indexed word timings or deterministic token stitching in fa/alignment.rs;
• it does not use the Jan 9 / Feb 9 BA2 broad transcript-wide remap policy;
• a shared Hirschberg DP library still exists in-tree, so the accurate migration claim is that runtime remap policy was narrowed, not that every DP use disappeared.

UTR: global DP is the steady-state correctness boundary

UTR timing recovery (fa/utr.rs) uses a single global Hirschberg DP alignment of all document words against all ASR tokens.

This is the correct steady-state algorithm for the hand-edited transcript case (see the 407 trimmed fixture regression test in crates/batchalign/src/chat_ops/fa/utr.rs): transcript words and ASR tokens are two independent full-document sequences, so the matcher must reason globally rather than utterance by utterance. The Rust Hirschberg implementation in crates/batchalign-transform/src/dp_align/mod.rs is O(mn) time and linear space (min(m,n) working memory). No published benchmark currently anchors a specific speedup multiplier against the old Python implementation; the practical effect is fast enough that UTR on full transcripts is no longer a wall-clock concern.

This fixes token-starvation failures where local matching consumed tokens too early. It does not solve every alignment pathology: dense &* overlap and larger text/audio order divergence still remain a limitation of any monotonic aligner.

Intentionally retained

• model-internal alignment/decoding internals (e.g., CTC/Whisper internals)
• evaluation/edit-distance style metrics (WER and similar analysis tooling)

Policy: runtime user-output remap should not silently reintroduce global DP tie ambiguity in paths where deterministic mapping is available.

This is a durable migration boundary. DP is legitimate when aligning two genuinely independent sequences (UTR: transcript words vs ASR tokens; WER: hypothesis vs reference). It is a regression when runtime output reconstruction uses global DP to paper over mismatches that should be handled by deterministic identity/index mapping (retokenization, FA injection, %mor/%gra attachment).

3) Realign-after-edit consequences

When transcript edits occur after initial alignment:

• deterministic ID/index matching preserves timing slots where provenance remains,
• bounded window policies prevent cross-utterance remap jumps,
• unresolved ambiguity yields explicit unassigned outcomes (not hidden remap).

This is the intended operational tradeoff: transparent uncertainty over unstable auto-corrections.

For migrators, this means some BA2-to-BA3 output differences are expected:

• Jan 9 / Feb 9 BA2 output may have looked “more complete” because ambiguous words were forced into a global remap anyway;
• current BA3 output may leave some timing/provenance unresolved explicitly;
• that is a correctness choice, not a missing feature.

3.1) align improvements

Feb 9 BA2 already improved cache use, DP edge cases, and FA failure handling. BA3 goes further by moving FA grouping, timing injection, %wor, monotonicity, and overlap cleanup into Rust orchestration with typed FA payloads and deterministic transfer rules.

One especially important align sub-change is UTR:

• released BA2 recovered utterance timing via a single global Hirschberg DP alignment of all transcript words against all ASR tokens;
• BA3 now uses the same global Hirschberg approach (in Rust), preserving the correct full-document alignment model while moving the implementation onto the typed Rust chat-ops boundary.
• This fixes the 407-style token-starvation regression class, but it does not make UTR non-monotonic. Files with dense overlap and text/audio reordering can still remain only partially recoverable.

Fuzzy UTR matching (new in BA3)

BA3’s experimental two-pass strategy supports Jaro-Winkler matching (threshold 0.85 by default, configurable via --utr-fuzzy). The default auto and explicit global strategies use case-insensitive exact matching; --utr-fuzzy applies only with --utr-strategy two-pass. Historical coverage measurements do not establish the behavior or accuracy of a current run; retain its strategy, configuration, source and timing evidence.

Two-pass overlap-aware UTR (BA3 mechanism, currently opt-in only)

BA2 had no overlap awareness in UTR, overlap markers (+<, &*) were treated the same as regular words. BA3 ships a two-pass strategy for conversation-analysis data:

1. Pass 1 (global): Align all non-overlap words against ASR tokens to establish the timing backbone. Overlap markers are excluded so they don’t consume ASR tokens that belong to the primary speaker.

2. Pass 2 (targeted): For each unresolved overlap utterance, search for its ASR timing using index-aware onset matching, multiple ⌊ respondents match the correct ⌈ by overlap index with speaker-aware fallback.

The two-pass mechanism currently runs only when the user explicitly passes --utr-strategy two-pass. The default (--utr-strategy auto) unconditionally returns GlobalUtr since the auto-routing was disabled on 2026-03-30, see resolve_strategy() in crates/batchalign/src/runner/dispatch/utr.rs. The library function select_strategy() in crates/batchalign/src/chat_ops/fa/utr.rs (language-agnostic content inspection that picks TwoPassOverlapUtr when +< or ⌊ markers are present) still exists, but is no longer reached from the Auto path.

Density-aware overlap exclusion (inside the two-pass mechanism)

When the two-pass strategy is selected (currently only via explicit override), the exclusion behavior is itself density-aware: when more than 30% of utterances carry overlap markers (dense CA data like Jefferson NB at 47% overlap), excluding all overlap words from pass-1 would starve the aligner of context, so two-pass falls back to global alignment for that file. The threshold lives on TwoPassConfig as the max_exclusion_density field (default 0.30), see crates/batchalign/src/chat_ops/fa/utr/two_pass.rs.

Empirical result on Jefferson NB during the original tuning: pass-1 exclusion alone recovered 8.8% at 1491ms error; with density detection, recovered 10.7% at 691ms error.

Language-aware UTR strategy selection (disabled mechanism)

There was an earlier auto-routing layer that gated TwoPassOverlapUtr on language: non-English files always used GlobalUtr (avoiding the two-pass regression from noisier non-English ASR); English files fell through to overlap-inspecting auto-selection. That gate was disabled 2026-03-30 (alignment regressions reported by an operator; enforce_monotonicity() only checks start times) and is not currently reachable. The previously-measured gains under the gate (English: +4.3pp SBCSAE, +3.8pp Jefferson; non-English on Hakka, Welsh, German, Serbian: GlobalUtr matched or beat TwoPassOverlapUtr) are retained here as the historical benchmark that motivated the gate, not as a description of current default behavior.

@Options: CA handling

BA3 detects @Options: CA at FA entry and suppresses %wor generation for that file, see crates/batchalign/src/fa/mod.rs::run where the option is consulted and info!("@Options: CA detected suppressing %wor generation") fires. The motivation is that CA transcripts use prosodic notation (⌈⌉⌊⌋, arrows, lengthening marks) that %wor cannot represent, so generating it adds noise that CA researchers have to manually remove. CA terminator resolution itself lives in the parser layer (the parser correctly promotes CA-style terminators), not in an FA-side validation skip.

--media-dir flag (new in BA3)

batchalign3 align input/ -o output/ --media-dir /path/to/audio/ allows specifying a separate directory for audio files. BA2 required audio files to be alongside the .cha files. This supports workflows where media is stored separately from transcripts (common in corpus archives).

Align improvement summary

4) Retokenization and Stanza multi-token outputs

Batchalign3 accounts for multi-word token expansion and tokenization divergence with deterministic interval/index mapping logic, preserving monotonic ordering.

Practical outcomes:

• one source token yielding multiple UD tokens is handled through explicit mapping,
• merged/split forms are attached by deterministic policy rather than global string-level DP reconciliation,
• divergence remains visible and testable in golden fixtures.

This directly addresses the “multiple tokens from Stanza” migration concern: token expansion is treated as structured provenance mapping, not as text that must later be globally realigned by DP.

4.1) Morphotag and %gra correctness consequences

Durable migration-relevant correctness changes include:

• %gra root attachment now follows standard root-head semantics instead of self-referential root indices;
• reflexive pronoun suffix handling was corrected;
• MWT chunk mapping avoids brittle positional assumptions;
• tokenizer-generated divergence is either deterministically mapped back or left explicit, rather than silently “fixed” by a global text remap.

Concrete currently tested consequences include:

• ROOT must attach to virtual root 0, not to itself;
• invalid root/head/chunk-count combinations are rejected;
• MWT expansions produce per-component %gra relations;
• @c and @s special forms are mapped explicitly rather than relying on placeholder leakage;
• xbxxx placeholders are restored back to the original form in retokenized output;
• reflexive pronouns explicitly emit reflx;
• retokenization can split contractions structurally, while retokenize=false preserves original tokenization.

Important comparison nuance:

• reflexive reflx, special-form handling, and xbxxx restoration were not invented only in current BA3; older BA2 already had versions of those behaviors in Python ud.py;
• the more durable current shift is that ROOT/head/chunk semantics and retokenization behavior are now enforced through explicit mapping logic and tests rather than left to positional array repair.

For corpus maintainers, this means BA3 %mor/%gra diffs against BA2 should be reviewed as likely corrections first.

4.2) From positional repair to principled indexing

The durable algorithmic shift is away from workflows like:

• flatten text,
• keep parallel arrays,
• patch indices after skips/merges,
• run broad DP when the arrays drift.

Toward workflows like:

• carry stable word identity,
• maintain explicit utterance/word/chunk indices,
• iterate AST content directly,
• use deterministic local fallback only where provenance is missing.

Concrete command-level examples:

• transcribe:
  • BA2 Python built transcript structure while it was still normalizing token strings and punctuation;
  • BA3 separates tagged raw ASR payloads from Rust normalization, Rust postprocess, and Rust CHAT assembly.
• translate:
  • BA2 translated utterance strings and then relied on Python generation to materialize output tiers;
  • BA3 extracts utterance payloads from the AST and injects %xtra back by line index.
• utseg:
  • BA2 flattened constituency subtrees to strings, aligned them back to form arrays, then rebuilt utterances;
  • BA3 returns raw tree strings, computes assignment vectors, then splits AST utterances by index.
• coref:
  • BA2 flattened the document to one detokenized string and DP-mapped chain payloads back to (utterance, form) slots;
  • BA3 uses sentence arrays and typed chain refs, then injects sparse %xcoref by validated sentence/line mapping.

This matters because it reduces accidental correctness:

• fewer outputs that “look plausible” only because a later repair pass guessed the intended alignment,
• more outputs whose correctness follows from preserved structure and validated index relationships.

4.3) Cantonese / HK ASR tokenization

HK / Cantonese parity has one additional algorithmic wrinkle that deserves to be called out explicitly.

• Cantonese material must be compared against the Jan 9 BatchalignHK baseline.
• The relevant preserved legacy command is batchalignhk.
• For yue, semantically correct ASR text can still benchmark badly if the runtime keeps long Han-script chunks as one giant token instead of splitting them into character tokens before retokenization and scoring.

Current batchalign3 now handles this in the Rust-owned ASR post-process path:

• Cantonese text is normalized to HK traditional form once per monologue, through AlignedNormalization, before anything splits it,
• Han-script yue ASR chunks are then split with the shared cantonese_char_tokens() helper, which splits and strips punctuation and normalizes nothing,
• ASCII/code-switched tokens are left intact,
• punctuation-based utterance retokenization then runs on those normalized tokens.

This matters because WER/compare behavior for Cantonese is sensitive to token granularity. A transcript can be visibly “close” while still scoring as a large regression if the main path presents only a few giant tokens to the scorer.

5) Japanese preprocessing/postprocessing

Japanese verb-form and POS overrides

crates/batchalign-transform/src/morphosyntax/lang_ja.rs (~440 lines, ported from BA2’s Python ja/verbforms.py) applies 50+ ordered override rules that run before UD→CHAT POS mapping. These correct Stanza outputs for colloquial Japanese forms that the model frequently misclassifies:

• Subordinating conjunctions: contracted conditionals (ちゃ→ば, なきゃ, じゃ→ちゃ, たら, たっ, で) reclassified from VERB/AUX to SCONJ.
• Auxiliary verbs: colloquial endings (れる→られる, よう→おう, だら→たら, だ→た, 無い→ない, せる→させる, なさい→為さい) with corrected lemmas.
• Interjections: backchannels and fillers (はい, うん, おっ, ほら, ヤッホー, ただいま) reclassified from NOUN/VERB to INTJ.
• Verb lemma corrections: specific kanji verbs (撮る, 貼る, 混ぜる, 釣る, 降りる/降る, 載せる, 帰る, 舐める, etc.) that Stanza assigns wrong lemmas.
• Noun/pronoun fixes: colloquial forms (あたし→PRON, バツ, ブラシ, 引き出し, クシャミ) and onomatopoeia (ゴロンっ, モチーンっ).

Japanese Stanza processor configuration

Japanese requires the combined Stanza processor package (tokenize+pos+lemma+depparse in one model), not separate processors. This is enforced in test_stanza_config_parity.py to prevent misconfiguration that causes silent accuracy degradation.

5.1) Performance consequences of the algorithm shift

The performance wins that belong in migration documentation are the durable ones:

• deterministic mapping avoids some expensive reconstruction work that used to happen after engine calls;
• better cache boundaries mean repeated morphosyntax/alignment work is skipped more often;
• batching and warm workers reduce per-file startup overhead.

Point-in-time benchmark spikes do not belong here unless they became a durable property of the released architecture.

6) Overlap and rapid interleaving speech

A known limit remains: rapidly overlapping/interleaving speaker turns are still hard for perfect automatic assignment. The migration improves this by local window constraints and deterministic fallback, but does not claim complete disambiguation in all overlap-heavy audio.

Mitigation strategy:

• preserve all candidate structure and timings,
• avoid global crossing remaps,
• expose unresolved slots for explicit review tools.

7) Regression governance

Algorithmic migrations are now defended by:

• golden test matrices (batchalign/tests/golden/),
• no-DP-runtime allowlist tests at batchalign/tests/test_dp_allowlist.py::test_chat_ops_dp_calls_are_allowlisted, which fingerprints every dp_align::align(...) call site against an explicit allowlist so unintended DP-on-runtime regressions are caught in CI,
• tracing instrumentation for mapping-mode divergence: the warn! at crates/batchalign-transform/src/retokenize.rs:75 ("retokenize text diverged; using length-aware monotonic fallback without DP") fires whenever build_word_token_mapping() cannot use a deterministic word-token mapping and falls back to length-aware monotonic.

That governance change is itself part of the migration: the codebase is less willing to accept “looks plausible on a few files” as evidence that an algorithmic rewrite is safe.

Language handling: no silent fallbacks, early validation

Policy: hard-error on unknown languages, never silent fallback

batchalign3 deliberately rejects unknown or unsupported language codes at the earliest possible point with a clear, actionable diagnostic. This is an improvement over both BA2 and early BA3:

BA2’s behavior was accidentally strict, it crashed because nobody added a None check, not because someone designed early validation. BA3’s initial migration introduced two regressions by trying to be “helpful”:

1. Rev.AI truncation fallback: &other[..2] silently produced wrong codes (e.g., hak → ha, pol → po). Replaced with a ~78-entry explicit mapping table (revai/preflight.rs::try_revai_language_hint)

   • "auto" fallback with tracing::warn.

2. Whisper English fallback: return "english" when pycountry found no match. This meant unknown languages were silently transcribed in English, the worst possible outcome, since the user gets output that looks plausible but is completely wrong. Replaced with raise ValueError(...).

Design principle: A clear error message is always better than silently wrong results. Users can recover from “language not supported, try --asr-engine whisper” but cannot recover from a transcript that looks English but should have been Welsh.

Per-file @Languages: resolution (morphotag, translate, coref)

For text-NLP commands that operate on existing CHAT files, morphotag, translate, coref: the processing language is read per-file from each file’s own @Languages: header. None of these commands accept a --lang flag at the CLI; the wire-level LanguageSpec is PerFile, distinct from Auto.

BA2 source for the silent ["eng"] default:

# pipelines/morphosyntax/ud.py:1104
lang = doc.langs[0] if doc.langs else "eng"

# pipelines/utterance/ud_utterance.py:253
primary_lang = doc.langs[0] if doc.langs else "eng"

The pattern was repeated at ten-plus sites across BA2, every text-NLP pipeline carried its own if doc.langs else "eng" clause. BA3 inherited it as parity scaffolding (CommandProfile.lang = "eng" for the three no---lang commands) until 2026-05-06, when the placeholder was killed in favor of LanguageSpec::PerFile and resolve_per_file_lang was made fallible.

Why BA2 used a silent default at all is unclear from the source. BA2 predates the project’s broader push toward strict CHAT validation; the eng default is consistent with a “produce some output rather than fail” stance that was reasonable when the corpus was overwhelmingly English CHILDES data. With heterogeneous data, Cantonese, Polish, Czech, Spanish, Hong Kong bilingual, the default is unsafe: it falsifies the output’s @Languages: provenance and tags the wrong morphology onto the wrong text. BA3 deliberately diverges.

UTR strategy selection (current: GlobalUtr always; two-pass gated)

The UTR (Utterance Timing Recovery) overlap strategy options are auto, global, and two-pass, controlled by --utr-strategy.

Current behavior (runner/dispatch/utr.rs::resolve_strategy):

• --utr-strategy auto (default), always uses GlobalUtr. The language-aware / overlap-inspecting branch was disabled 2026-03-30 after operator-reported alignment regressions on real files, uncorrected end-time overlap (enforce_monotonicity only checks start times), and insufficient broad validation of the two-pass algorithm beyond the original four corpora.
• --utr-strategy global: GlobalUtr (explicit; same as auto today).
• --utr-strategy two-pass: TwoPassOverlapUtr (experimental; opt-in). The lower-level select_strategy() in chat_ops/fa/utr.rs inspects the file for +< linkers or ⌊ CA markers and returns TwoPassOverlapUtr if either is present, but this function is currently unreachable from Auto.

Historical data (now-disabled auto-selection): an internal benchmark on 7 non-English files across 4 languages plus the SBCSAE and Jefferson English corpora measured +4.3pp on SBCSAE and +3.8pp on Jefferson for the auto-selected two-pass strategy on English, with regressions on non-English eliminated. These numbers describe the disabled mechanism, not what auto delivers today.

The companion architecture page Command Flowcharts still shows a “Language == eng?” decision diamond for the older auto-selection behavior; that page needs the same correction.

Per-utterance language routing: improvement over BA2

Status: Implemented in BA3. An improvement over both BA2 and batchalign-next’s eager-loading approach.

BA3 implements full per-utterance language routing for morphosyntax: utterances with [- fra] precodes are routed to the French Stanza pipeline, [- spa] to Spanish, etc. The full chain:

1. Rust (morphosyntax/batch.rs): extracts per-utterance language_code from [- lang] precodes (falls back to @Languages header, then to primary --lang), groups all cache-miss items by language
2. Rust (morphosyntax/batch.rs): dispatches language groups via futures::future::join_all, gated by a tokio::sync::Semaphore of max_concurrent_groups = max_total_workers / max_workers_per_key. Each language group goes to a separate worker process; concurrency is bounded so the global cap can’t be exceeded.
3. Rust (morphosyntax/worker.rs): within each language group, splits large batches into chunks across up to max_workers_per_key (default 4) workers of the same language, also via join_all.
4. Python worker: receives one chunk, runs Stanza on it, returns raw UD annotations, Python has zero language-routing logic.

Language grouping and dispatch are entirely Rust-owned. Python workers are stateless single-language inference endpoints.

BA2 parsed the [- lang] precode into override_lang but never used it for routing: it always called nlp(line_cut) with the single primary pipeline, and parse_sentence(..., lang[0]) always used the first declared language. When skipmultilang=True, BA2 skipped non-primary utterances entirely; when False (default), it processed them with the wrong language model.

BA3’s @s:lang per-word routing (L2 dispatch) is implemented in crates/batchalign-transform/src/morphosyntax/l2/: the L2 extractor identifies @s-marked words, groups them into per-utterance DispatchSpans by target language, dispatches each span to its secondary-language Stanza model, and merges the secondary lexical output back with the primary-language structural info before splicing the merged Mor items in place of the primary pass’s L2|xxx placeholders. Default-on; the --no-l2-morphotag flag opts out and falls back to placeholder-only output. --skipmultilang remains the utterance-level [- lang] skip control, not the per-word L2 switch.

BA3’s two-level parallelism caps total active Stanza workers at max_total_workers (computed from RAM, default ~28 on a fleet machine). The cross-language semaphore allows up to max_total_workers / max_workers_per_key language groups to dispatch at once, and within each group up to max_workers_per_key (default 4) chunks run in parallel. A 5-language batch with max_workers_per_key=4 on a 28-worker host can dispatch all 5 groups simultaneously (5 ≤ 28/4 = 7) and use up to 20 concurrent Stanza workers; for N > max_total_workers / max_workers_per_key the language groups queue rather than all dispatching at once.

Unsupported languages

Not all ISO 639-3 codes have Stanza models. The TalkBank corpus includes files with secondary languages like Quechua (que), Jamaican Creole (jam), Min Nan Chinese (nan), Tamasheq (taq), and und (undetermined). BA2 and BA3 handle these differently:

BA2’s stanza.MultilingualPipeline was convenient but dishonest: it silently applied the wrong language model to unsupported languages, producing POS tags and dependency parses that looked plausible but were linguistically invalid. BA3’s approach is to fail honestly, an empty %mor tier is better than a wrong one, because it signals to the user that the language needs attention rather than hiding the problem behind plausible-looking garbage.

The supported language set is maintained in crates/batchalign-transform/src/morphosyntax/pos_hints.rs::is_stanza_supported (Rust-side gate, called before dispatch in crates/batchalign/src/morphosyntax/batch.rs) and batchalign/worker/_stanza_loading.py (Python-side mapping). Both must stay in sync.

Processor capability discovery

BA2 and early BA3 both hardcoded assumptions about which Stanza processors are available per language. This caused runtime crashes when a language lacked an assumed processor.

The capability table (batchalign/worker/_stanza_capabilities.py) reads Stanza’s resources.json once at worker startup and reports per-language processor availability. This eliminates the manual sync burden between Python and Rust and prevents runtime crashes from missing processors.

See Language Routing for the remaining gaps (per-word @s: routing, per-utterance ASR engine selection).

Transcribe: language auto-detection and code-switching (new in BA3)

Status: Implemented in BA3. Not available in BA2.

BA3 adds full --lang auto support for transcribe with two-stage language detection and automatic code-switching precode generation. This is entirely new functionality, BA2 had no equivalent.

How it works

When --lang auto is passed with the Rev.AI ASR backend (production path):

1. Rev.AI Language ID API (~5-30s): submits audio to a dedicated language identification endpoint. Returns top_language (e.g., "es") with confidence score (e.g., 0.907). This uses audio/phonetic features, not text analysis, so it correctly identifies Spanish even in heavily code-switched English/Spanish audio.

2. Transcription with concrete language: the detected language is used as the language hint for the transcription job, which enables speakers_count and skip_postprocessing to be set correctly.

3. Per-utterance language detection: after ASR post-processing, each utterance is analyzed by whatlang (Rust trigram-based detector, ~1ms per utterance). Utterances confidently detected as a different language than the primary get [- lang] precodes in the CHAT output.

4. Multi-language @Languages header: the primary language is always listed first; secondary languages are added if they appear in MIN_UTTERANCES_FOR_SECONDARY (= 3) or more utterances, in descending-frequency order. The constant lives in crates/batchalign-transform/src/asr_postprocess/lang_detect.rs.

Accuracy on bilingual audio

On Spanish-primary heavily code-switched audio (e.g. Miami/Bangor spa-eng samples), the two backends behave differently:

• Rev.AI + Language ID typically identifies the primary language correctly because the Language ID API is audio/phonetic-based, so @Languages comes out spa, eng and the primary stays spa.
• Whisper + whatlang frequently inverts the order to eng, spa with the wrong primary, because whatlang’s trigram majority vote on ASR text is biased by English content embedded in Spanish utterances.
• Per-utterance [- eng] precode coverage is much lower than ground-truth in either backend, because trigram detection requires MIN_CHARS_FOR_DETECTION (= 40 alphabetic chars) and UTTERANCE_CONFIDENCE_THRESHOLD (= 0.5) to fire, short or code-mixed utterances fall below those thresholds. Quantitative per-corpus numbers depend on input characteristics; see the language-routing limitations for the full design discussion.

Why Whisper gets the primary language wrong

Whisper auto-detects language internally per 30-second chunk, but the HuggingFace pipeline does not expose which language was detected. The pipeline returns text with lang="auto" echoed back, forcing fallback to whatlang trigram detection on the ASR text output. On code-switched bilingual text, whatlang frequently misclassifies the primary language because Spanish utterances containing English words generate enough English trigrams to tip the majority vote.

Rev.AI’s Language ID API avoids this by using audio-level phonetic features rather than text trigrams.

Transcribe: ASR post-processing improvements

BA3 ports all 8 BA2 ASR post-processing stages to Rust with provenance newtypes that prevent mixing text at different pipeline stages:

Key correctness improvement: BA3’s retrace detection marks words with WordKind::Retrace in the token pipeline, then build_chat.rs wraps them in proper CHAT <...> [/] AST nodes (AnnotatedWord / AnnotatedGroup).

Text Cleaning Divergences from BA2

These divergences mean BA3 morphotag output for Cantonese will differ from BA2 output. The differences are improvements, BA2’s text stripping was lossy and its POS model was wrong for Cantonese. BA2 did string-level wrapping that could produce malformed CHAT when retraces crossed word boundaries or contained special characters.

Provenance newtypes: The token pipeline uses distinct types at each stage (AsrRawText → AsrNormalizedText → ChatWordText) that prevent accidentally passing text from one stage to another without the required transformation. BA2 used bare str throughout.

Transcribe: Rev.AI language code mapping

BA2 used pycountry.languages.get(alpha_3=lang).alpha_2 for ISO 639-3 to Rev.AI code conversion. When pycountry returned None for an unknown language code, BA2 crashed with an uncaught AttributeError (no fallback at all). Early BA3 Rust code introduced a silent truncation fallback (&other[..2]) that produced wrong codes for many languages:

• pol → po (should be pl)
• hak → ha (not a valid ISO 639-1 code)
• ces → ce (should be cs)

BA3 replaces this with an explicit ~78-entry ISO 639-3 → Rev.AI mapping table in revai/preflight.rs::try_revai_language_hint, with an "auto" fallback for unmapped languages (logged as a tracing::warn recommending the operator add an explicit mapping for the language). The reverse mapping (revai_code_to_iso639_3 in revai/asr.rs) returns Option<LanguageCode3> rather than panicking on unknown codes.

8) Forced alignment: compound filler handling (new in BA3)

Three algorithmic improvements to FA that did not exist in BA2 (verified against batchalign2-jan9 baseline 84ad500b):

8.1) Compound filler splitting for FA extraction

CHAT fillers like &-you_know, &-sort_of, &-I_mean are single tokens with underscores joining multi-word discourse markers. ASR engines (Whisper, wav2vec) tokenize these as separate words (“you”, “know”). The Hirschberg DP aligner could not match the compound token against the split ASR output.

BA3 splits compound fillers at underscores during FA word extraction, then merges the N timings back into one span during injection.

flowchart LR
    subgraph "BA2 (broken)"
        A2["&-you_know"] -->|"extract"| B2["'you_know'"]
        B2 -->|"DP align"| C2["no match ✗"]
        C2 --> D2["no timing on %wor"]
    end
    subgraph "BA3 (fixed)"
        A3["&-you_know"] -->|"extract\n(split_compound_filler)"| B3["'you', 'know'"]
        B3 -->|"DP align"| C3["match ✓"]
        C3 -->|"inject\n(merge N timings)"| D3["you_know 382349_382989"]
    end

Source: crates/batchalign/src/chat_ops/fa/extraction.rs::push_fa_word, crates/batchalign/src/chat_ops/fa/injection.rs::inject_timing_on_word, shared helper crates/batchalign/src/chat_ops/fa/mod.rs::split_compound_filler.

8.2) Edge filler bullet expansion

UTR-assigned utterance bullets are computed from ASR token matching. ASR engines don’t transcribe fillers, so bullets exclude filler audio at utterance boundaries. A trailing &-you_know whose audio lives in the gap between utterances gets no FA coverage.

BA3 adds a pre-FA pass that expands utterance bullets into adjacent inter-utterance gaps when edge words are fillers.

flowchart TD
    subgraph "BA2: bullet too narrow"
        U1["*PAR: ... her &-you_know .\n bullet: 458385_459345"]
        G1["gap: 459345 → 460325\n(filler audio here)"]
        N1["*PAR: but they did try ...\n bullet: 460325_..."]
        U1 --> G1 --> N1
        style G1 fill:#fee,stroke:#c00
    end

    subgraph "BA3: bullet expanded"
        U2["*PAR: ... her &-you_know .\n bullet: 458385_459835\n(expanded +490ms)"]
        G2["gap: 459835 → 460325\n(remaining silence)"]
        N2["*PAR: but they did try ...\n bullet: 460325_..."]
        U2 --> G2 --> N2
        style U2 fill:#efe,stroke:#0a0
    end

Algorithm: For each utterance with a leading or trailing filler, expand the bullet into the gap by min(gap/2, 1500ms). This ensures the FA audio window includes the filler without stealing from the neighbor.

Source: crates/batchalign/src/chat_ops/fa/expand_for_fillers.rs::expand_bullets_for_edge_fillers.

8.3) FA group trailing gap extension

In addition to per-utterance bullet expansion, FA group audio windows are extended into the gap after the last utterance in a group. This catches trailing fillers at group boundaries where per-utterance expansion alone is insufficient.

Source: crates/batchalign/src/chat_ops/fa/grouping.rs::extend_into_trailing_gap.

Verification

Tested on a user’s 17-3.cha (<corpus>/<group>):

Mid-utterance fillers were already handled correctly, only edge fillers needed the fix.

This page last changed: 2026-09-16 (commit 197c81e6). The whole book last changed: 2026-09-16 (commit 34d249d8).

Why Replace Python CHAT Handling with Rust

Status: Completed Last updated: 2026-05-19 13:34 EDT

The Problem

Batchalign’s morphosyntax pipeline (morphotag) is the most-used command in the TalkBank processing workflow, run against hundreds of thousands of CHAT files. The existing Python implementation has several areas where the Rust rewrite improves on the original:

1. Fragile text manipulation. The Python code converts CHAT transcripts to flat strings, sends them through Stanza for NLP analysis, then uses expensive string alignment (O(n*m) dynamic programming) to map Stanza’s output back to the original transcript. This “flatten → process → realign” pipeline is the source of most morphotag bugs, small tokenization differences between Stanza and CHAT cause misaligned %mor/%gra tiers.

2. 60+ lines of .replace() calls. Python’s annotation_clean() function strips CHAT annotations character-by-character to produce “clean” text for Stanza. This is destructive, it loses structural information, and every new annotation type requires adding more .replace() calls.

3. Retokenization is a separate ~120-line code path that operates at the character level, building a “backplate” of alignable/non-alignable chunks and applying ~15 regex cleanups. It’s a complex subsystem with many language-specific cases.

4. No structural understanding of CHAT. Python treats CHAT as flat text. It can’t distinguish between a word inside a retrace group (<I want> [/]) and a regular word without string-level pattern matching. Every edge case requires a new regex.

The Solution: Rust CHAT AST

We’ve built a Rust implementation that parses CHAT into a strongly-typed Abstract Syntax Tree (AST) and operates on it structurally. The key insight: when your data model matches the format’s structure, you don’t need string hacking.

How It Works

              Rust                           Python (ML only)
         ┌────────────┐                   ┌──────────────┐
CHAT  →  │ Parse AST  │  → words JSON →  │  Stanza NLP  │
file     │ Extract    │  ← mor/gra JSON ← │  (unchanged)  │
         │ Inject     │                   └──────────────┘
         │ Serialize  │  → CHAT file
         └────────────┘

Rust parses the CHAT file once into a proper AST, extracts the words that need NLP analysis by traversing the tree (no string manipulation), sends them to Python’s Stanza via a callback, receives %mor/%gra analysis, attaches it directly to the AST nodes, and serializes back to CHAT. The callback boundary means Python’s role is strictly limited to neural network inference.

Why It’s Safe

150 automated tests across two languages

No mocks: real test doubles

Following the project’s strict no-mock policy, all tests use lightweight alternate implementations (e.g., FakeStanzaNLP that returns predetermined analyses for known words). This means tests exercise the actual code paths, not mocked interfaces.

Boundary-based architecture makes testing natural

The callback pattern creates a clean boundary: Rust sends words, Python returns analysis. Tests can verify each side independently:

• Rust side: Given this CHAT and this callback response, is the output correct?
• Python side: Given these words, does the callback produce the right %mor/%gra?
• End-to-end: Does CHAT → Rust → callback → CHAT produce valid output?

Round-trip verification

Every test that modifies a CHAT file also verifies the output re-parses correctly. The Rust parser and serializer are inverses, if the parser can’t read its own serializer’s output, the test fails.

Structural correctness by construction

The AST approach eliminates entire categories of bugs:

Why It’s Efficient

Rust is dramatically faster for text processing

The Hirschberg DP alignment (used for character-level mapping) runs orders of magnitude faster in Rust:

For morphotag, the bottleneck is Stanza’s neural network inference (unchanged). But the per-utterance Rust overhead (parsing, extraction, injection, serialization) is negligible compared to Python’s text processing. For large files with thousands of utterances, eliminating Python’s string manipulation overhead adds up.

Less code to maintain

The Rust code is longer in raw lines but each line does one thing. The Python code is shorter but relies on implicit knowledge about string formats, character positions, and annotation conventions that are never checked at compile time.

The AST is shared infrastructure

The talkbank-model and talkbank-parser crates aren’t just for morphotag. They power the CHAT validation tooling and will be the foundation for migrating forced alignment and utterance segmentation to Rust. Every pipeline that currently uses annotation_clean() will benefit from the same AST.

What’s Been Migrated

Complete

• Standard morphosyntax (retokenize=false): CHAT → extract words → Stanza callback → inject %mor/%gra → CHAT
• Retokenized morphosyntax (retokenize=true): Same, plus AST restructuring to match Stanza’s tokenization
• Special forms (@c, @s, @b): Extracted from AST, passed in callback, restored after analysis
• Multi-language skip (skipmultilang): Utterances with [- lang] override correctly skipped
• Progress reporting: Per-utterance progress callbacks work through Rust

No Python Fallback

The Rust AST path is the only code path. The former Python morphoanalyze() implementation and its _process_python() fallback have been removed. The batchalign_core Rust extension is required.

Completed Follow-Ups

All follow-up steps from the original decision have been completed:

1. Production testing against large corpus: Completed. Rust pipeline validated against existing annotations.
2. Forced alignment migration: Completed. FA uses the same AST + callback pattern via inference/fa.py.
3. Utterance segmentation migration: Completed. Utseg uses the same pattern via inference/utseg.py.
4. Python fallback removed: The Python morphoanalyze() code has been removed. All morphosyntax processing goes through the Rust AST path.

Summary

The Rust morphosyntax pipeline is safer (AST eliminates string-hacking bugs), faster (orders of magnitude for DP alignment), better tested (150 tests across Rust and Python), and architecturally cleaner (callback pattern isolates ML from text processing). The Python fallback has since been removed (see §“No Python Fallback” above), and the underlying AST infrastructure is reusable for every TalkBank processing pipeline.

This page last changed: 2026-06-19 (commit c82a6d03). The whole book last changed: 2026-09-16 (commit 34d249d8).

Persistent State and Behavioral Changes

Status: Current Last updated: 2026-09-06 23:59 EDT

Batchalign3 introduces several stateful behaviors that did not exist in Batchalign2. This page documents every form of persistent state, where it lives, and how it differs from BA2’s stateless model.

Overview: BA2 vs BA3 execution model

BA2: Every invocation was a fresh Python process. Models loaded from scratch, results computed from scratch, nothing persisted between runs. This was simple but slow, re-processing the same file paid the full cost every time.

BA3: The Rust CLI manages persistent state across runs: a local daemon keeps models warm, a SQLite cache stores analysis results, and ML models are cached on disk. This makes repeated operations dramatically faster but introduces state that users need to understand.

Persistent state locations

Analysis cache and run-log locations

Both live under the OS-conventional cache directory for the batchalign3 application:

• macOS: ~/Library/Caches/batchalign3/ (cache.db + logs/)
• Linux: ~/.cache/batchalign3/ (cache.db + logs/)
• Windows: %LocalAppData%\batchalign3\ (cache.db + logs/)

Model cache locations

Models are stored by the ML libraries (Stanza, Whisper, etc.) in their default cache directories:

• macOS: ~/Library/Caches/ (Stanza), ~/.cache/whisper/ (Whisper)
• Linux: ~/.cache/stanza/, ~/.cache/whisper/
• Windows: %LOCALAPPDATA%\stanza\, %USERPROFILE%\.cache\whisper\

Analysis cache

The analysis cache is the largest behavioral difference from BA2. BA3 caches audio inference results only: UTR ASR (utr_asr) and forced alignment (forced_alignment). Text-NLP commands (morphotag, translate, utseg, coref) deliberately do not cache; each run recomputes from scratch so that model or pipeline changes always take effect immediately.

Audio cache keys combine media identity with the parameters owned by each cache layer. Media identity currently uses canonical path, modification time and size; it is not a content digest. The UTR normalized-response keys include the selected ASR provider, language and, for segments, window bounds. Provider-free legacy UTR entries are not automatically replayed because their producing backend is unknown.

• Repeated alignment can reuse matching retained UTR and FA entries, but still performs orchestration and may load workers. Reuse does not imply instant output.
• Transcript edits can reuse raw ASR while changing downstream FA groups.
• UTR matching tuning changes projection of retained ASR; it does not change the raw ASR request. Selecting another UTR provider changes its key.
• Symlinks and alternate spellings of the same path share media identity. Moving identical audio can miss the metadata-based identity. Changing only FA can also miss UTR’s current outer worker-version partition.
• Text-NLP commands re-run rather than returning cached analysis.

The forced-alignment cache reference describes the two key spaces and their current limitations.

Managing the cache:

batchalign3 cache stats        # Show cache size and entry count
batchalign3 cache clear        # Delete cached results (with confirmation)
batchalign3 cache clear --all  # Also remove permanent UTR cache entries

BA2 had no cache. Every invocation computed results from scratch.

Local daemon

When you run a processing command, the CLI may start a background daemon process that keeps ML models loaded in memory. This eliminates model loading time on subsequent runs (5-20x speedup).

When this matters:

• The daemon uses memory even after your command finishes
• It persists across Python process exits (important for compat shim users)
• Multiple concurrent commands share the same daemon

Managing the daemon:

batchalign3 serve status       # Check if daemon is running
batchalign3 serve stop         # Stop the daemon (frees memory)
batchalign3 serve start        # Start the daemon explicitly

BA2 had no daemon. Every invocation loaded models from scratch.

ML model downloads

The first time you run a processing command, ML models are downloaded automatically. This is a one-time cost of ~2 GB. Subsequent runs use cached models from disk.

When this matters:

• First run of morphotag downloads Stanza models (~500 MB)
• First run of align downloads Whisper/Wave2Vec models (~1-2 GB)
• No network connection needed after first download
• The download itself surfaces through progress_v2 events on every UI channel; there is no separate pre-warm CLI command in BA3

BA2 also downloaded models on first use, but the behavior is the same.

Config file

~/.batchalign.ini stores the default ASR engine selection and API keys. Created by batchalign3 setup. This is the same format as BA2.

Implications for subprocess integrations

There is no public Python API in BA3; the supported integration path from Python is subprocess-into-batchalign3. The Python compat shim (batchalign.compat.BatchalignPipeline, etc.) has been removed along with the rest of the BA2 Python API, see Developer Architecture Migration.

For scripts that drive batchalign3 via subprocess, the persistent-state points still matter:

1. The first call may be slow: models download and daemon starts.
2. The daemon persists: after your driver process exits, the daemon continues running. Stop it explicitly with batchalign3 serve stop if you don’t want it.
3. Audio-task results are cached: re-aligning identical media is near-instant; text-NLP results recompute every run.
4. Memory usage: the daemon holds ML models in memory (~2-4 GB) until you stop it.

To disable the audio cache for a specific run (BA2-like always-recompute for the cached tasks):

batchalign3 align ~/corpus/ -o ~/output/ --override-media-cache

The --override-media-cache-tasks <list> per-command flag offers finer-grained control. Text-NLP commands never cache, so there is no analogous flag for them.

Clearing all state

To reset to a clean state:

batchalign3 serve stop            # Stop daemon
batchalign3 cache clear           # Clear analysis cache
batchalign3 logs --clear          # Clear run logs
# Model caches are managed by ML libraries; delete manually if needed

This page last changed: 2026-09-07 (commit 52b853df). The whole book last changed: 2026-09-16 (commit 34d249d8).

Batchalign2 CLI Reference (Baseline)

Status: Reference Last updated: 2026-09-07 07:04 EDT

This document captures the CLI surface of Batchalign2 across two baselines:

• Jan 9 baseline (84ad500b): the primary migration anchor.
• Feb 9 master (e8f8bfad): the later released BA2 master branch, which added concurrency, caching, compare, cache, bench, and several global options not present in the Jan 9 baseline.

Features that exist only in the Feb 9 master (not in the Jan 9 baseline) are marked with (Feb 9 only) throughout this document. The Jan 9 baseline CLI was simpler: only -v/--verbose as a global option, and no compare, cache, or bench commands.

Source: batchalign/cli/cli.py using rich_click (Click wrapper).

Global Options

These are defined on the top-level batchalign group and available to all commands.

Jan 9 baseline: The only global option was -v/--verbose. All other global options listed below were added in the Feb 9 master.

The Feb 9 globals BA3 carries forward (as wired flags) are --verbose, --workers, --timeout, and --force-cpu. Every other Feb 9 global was removed, passing it to BA3 produces a clap parse error, not a silent no-op.

All commands except avqi, setup, and version use the common_options decorator which adds positional IN_DIR and OUT_DIR arguments (both click.Path(exists=True, file_okay=False)).

Processing Commands

align

Forced alignment: adds word-level timing bullets to existing CHAT transcripts.

Pipeline task: "fa" (forced alignment).

transcribe

Create transcripts from audio files via ASR.

Pipeline task: "asr" (without diarization) or transcribe_s dispatch → "asr,speaker" (with --diarize).

Jan 9 behavior note: the preserved BA2 CLI help text said --diarize was “ignored with Rev.AI”, but the implementation did not do that. CLI dispatch still routed --diarize to transcribe_s, and transcribe_s still ran the post-ASR speaker pipeline after Rev transcription.

Note on --wor: BA2 default was False (no %wor). Current BA3 preserves that policy and wires --wor / --nowor through the Rust transcribe path. Earlier migration-stage notes flagged this as a regression, but current code and tests now cover the %wor toggle explicitly.

morphotag

Morphosyntactic analysis (POS, lemma, dependency parse).

Pipeline task: "morphosyntax".

Migration note: --skipmultilang and --no-l2-morphotag are not equivalent. --skipmultilang is the utterance-level [- lang] skip control; --no-l2-morphotag is the BA3-only opt-out for per-word @s routing. BA3 also validates whole-utterance same-language all-@s patterns as E255 and warns on explicit @s:LANG missing from @Languages as E254; chatter debug fix-s repairs both transcript-side issues.

translate

Translation to English.

Pipeline task: "translate".

BA2 engine selection. BA2 had no --translate-engine flag. Operators picked Seamless by editing ~/.batchalign.ini:

[translate]
engine = seamless_translate

The [translate] engine entry was read by pipelines/dispatch.py:resolve_engine_specs and silently became the engine for every subsequent BA2 invocation on that host until the file was edited again, exactly the per-host hidden-state pattern that the BA3 design rejects.

BA3 replacement. BA3 surfaces the same capability as an explicit CLI flag (--translate-engine google|seamless|nllb|tencent|aliyun) plus the shared --engine-overrides '{"translate":"<engine>"}' global flag. Default remains Google for fleet-wide behavior parity. Hosts where Google is unreachable (mainland-China sites behind the GFW) pass --translate-engine tencent (best Mandarin), --translate-engine aliyun (Cantonese-capable cloud), or --translate-engine nllb (self-hosted local model) per invocation. BA3 deliberately does not honor the BA2 [translate] engine config key, engine choice is a policy decision that lives at the command line.

coref (hidden)

Coreference resolution. Hidden from --help in BA2.

Pipeline task: "coref".

utseg

Utterance segmentation.

Pipeline task: "utseg".

benchmark

ASR word error rate benchmarking against gold transcripts.

Pipeline task: "asr" (transcribe) + "morphosyntax" (compare).

compare (Feb 9 only)

Transcript comparison against gold-standard references.

Pipeline task: "morphosyntax" (compare uses morphosyntax to tag both transcripts before WER computation).

Note on --lang: BA2 passed --lang through the compare pipeline for morphosyntax. Current BA3 also exposes --lang on CompareArgs and carries it through compare dispatch. Earlier migration-stage notes flagged this as missing, but the current CLI surface and tests cover it.

opensmile

OpenSMILE acoustic feature extraction.

Note: Uses its own input_dir/output_dir positional arguments instead of common_options.

Pipeline task: "opensmile".

avqi

Acoustic Voice Quality Index from paired .cs/.sv audio files.

Note: Uses its own input_dir/output_dir positional arguments instead of common_options.

Pipeline task: "avqi".

Admin Commands

setup

Interactive configuration wizard. Creates/updates ~/.batchalign.ini with default ASR engine and Rev.AI API key.

No command-specific flags in BA2. BA3 adds --engine, --rev-key, and --non-interactive for scripted setup.

version

Prints version and credits via pyfiglet.

No flags. BA3 equivalent: batchalign3 version.

Utility Commands

cache (Feb 9 only)

Cache management. Not present in the Jan 9 baseline. Registered as an external Click subcommand from the BA2 cache CLI module in the Feb 9 master.

BA2 subcommands: stats, clear, warm. BA3 supports stats and clear (with --all and --yes options).

bench (Feb 9 only)

Repeated benchmark execution for performance measurement. Not present in the Jan 9 baseline. Registered as an external Click subcommand from the BA2 bench CLI module in the Feb 9 master.

BA3 equivalent: batchalign3 bench <command> <in_dir> <out_dir> --runs N.

models

Model training utilities. Registered via add_command from batchalign.models.training.run.

BA2 subcommand: train. BA3 adds prep (Rust-native training text extraction) alongside train (Python runtime).

batchalignHK Plugin (Archived)

The HK plugin was a separate PyPI package (batchalign-hk-plugin) that registered additional ASR/FA engines via Python entry points. It was folded into batchalign3 as built-in engines in March 2026; there is no separate HK install tier now.

Plugin Discovery

BA2 used importlib.metadata.entry_points(group="batchalign.inference") to discover plugin-provided InferenceProvider implementations at startup. Each provider registered PluginDescriptor objects declaring engine name, task type, and factory function.

Engines

Selection

Engines were selected via --engine-overrides '{"asr": "tencent"}' on the CLI. The JSON payload was parsed into a BTreeMap<String, String> and forwarded to worker dispatch, which matched the engine name against plugin registrations.

BA3 Status

All four engines are now built-in modules under batchalign/inference/languages/cantonese/. Engine dispatch uses AsrEngine/FaEngine enums in worker/_types.py. The plugin discovery mechanism (PluginDescriptor, InferenceProvider, entry points) has been completely removed. See Plugin Removal Notes for the full migration record.

Pipeline Task Mapping

Regression Summary

No current CLI-surface regressions are recorded in this baseline table for transcribe, benchmark, or compare.

Historical note: earlier BA3 migration notes temporarily flagged transcribe --wor, benchmark --wor, and compare --lang as regressions during the rewrite. Current code and tests now wire those surfaces.

This page last changed: 2026-09-09 (commit 8f4ed0f2). The whole book last changed: 2026-09-16 (commit 34d249d8).

Debugging and Tracing Migration

Status: Current Last updated: 2026-05-19 13:34 EDT

BA2 Baseline: No Principled Debugging Story

Batchalign2 (baseline commit 84ad500b) had no structured debugging infrastructure:

• Tiered -v console logging (~30 scattered L.info() / baL.info() calls, ~15 raw print() statements) via Python’s logging module and Rich console formatting
• Ephemeral console-only output: no filesystem dumps, no structured traces, no per-stage instrumentation, no debug env vars, no timing breakdowns, no metrics
• Debugging meant: run with -vvv, read console, manually inspect I/O files

There were no debug artifacts, no offline replay capability, and no way to reproduce a pipeline failure without re-running the ML models.

BA3: Three-Tier Debugging Architecture

BA3 introduces a principled three-tier approach:

Tier 1: Structured Logging (tracing crate)

Already shipped. See Tracing and Debugging for the -v/-vv/-vvv verbosity system, engine boundary tracing, and per-component instrumentation.

Tier 2: --debug-dir for Reproducible Filesystem Dumps

The --debug-dir PATH CLI flag (or BATCHALIGN_DEBUG_DIR env var) enables structured CHAT/JSON artifact dumps at each pipeline stage. This enables:

• Offline TDD: load fixture data, call pipeline functions, assert on output without running ML models
• Test fixture generation: debug artifacts from real pipeline runs become regression test inputs
• Stage decomposition: inspect intermediate state between every pipeline stage

Coverage: debug artifact dumps are wired into both the align (FA/UTR) and transcribe (ASR → build CHAT → utseg → morphosyntax) pipelines.

Full directory layout for all artifact types:

debug-dir/
  # ── Transcribe pipeline artifacts ──
  sample_asr_response.json       # Raw ASR tokens + timestamps
  sample_post_asr.cha            # CHAT after assembly (before utseg)
  sample_pre_utseg.cha           # CHAT entering utterance segmentation
  sample_post_utseg.cha          # CHAT after utterance segmentation
  sample_pre_morphosyntax.cha    # CHAT entering morphosyntax

  # ── Align pipeline artifacts ──
  sample_utr_input.cha           # CHAT before UTR injection
  sample_utr_tokens.json         # ASR timing tokens fed to UTR
  sample_utr_output.cha          # CHAT after UTR injection
  sample_utr_result.json         # UTR injection statistics
  sample_fa_input.cha            # CHAT before FA (after UTR)
  sample_fa_grouping.json        # FA group plan (time windows, words)
  sample_fa_group_0.json         # Per-group words + timings
  sample_fa_group_1.json
  sample_fa_output.cha           # Final aligned CHAT

Tier 2b: Always-On Error Logging

Even without --debug-dir, certain failure modes automatically log diagnostic data at WARN level, zero cost in the happy path:

Tier 3: Dashboard Traces (debug_traces)

When --debug-dir is specified, debug_traces is automatically enabled on job submissions. The server collects FaTimelineTrace data for each file and exposes it via GET /jobs/{id}/traces for dashboard visualization.

Example Workflow: Reproduce a Transcribe-to-Utseg Failure

# 1. Run transcription with debug artifacts
batchalign3 transcribe audio/ output/ --lang eng --debug-dir /tmp/ba3-debug

# 2. If utseg fails, inspect the CHAT that was produced
cat /tmp/ba3-debug/sample_post_asr.cha

# 3. Validate it offline to find the exact parse error
cargo run -p talkbank-cli -- validate /tmp/ba3-debug/sample_post_asr.cha

# 4. Without --debug-dir, check server logs for the automatic warn! dump

Example Workflow: Reproduce a UTR Failure

# 1. Run alignment with debug artifacts
batchalign3 align input/ output/ --lang eng --debug-dir /tmp/ba3-debug

# 2. Inspect the UTR input and tokens
cat /tmp/ba3-debug/sample_utr_input.cha
jq . /tmp/ba3-debug/sample_utr_tokens.json

# 3. Write a test that loads the fixtures and calls inject_utr_timing directly
# (no ML model needed, the tokens are already captured)

Fine-Grained Cache Overrides

BA3 also introduces --override-media-cache-tasks for per-task cache control:

# Skip only UTR ASR cache (keep morphosyntax, FA caches)
batchalign3 align input/ output/ --override-media-cache-tasks utr_asr

# Skip UTR + FA caches
batchalign3 align input/ output/ --override-media-cache-tasks utr_asr,forced_alignment

The flag is honored only for audio tasks that have a cache: utr_asr and forced_alignment. Text-NLP tasks (morphosyntax, utterance_segmentation, translation) are accepted on the CLI for forward compatibility but are no-ops because BA3 does not cache text-NLP results, each run recomputes from scratch.

The existing --override-media-cache flag continues to skip every honored cache in one shot.

This page last changed: 2026-07-29 (commit f4f12680). The whole book last changed: 2026-09-16 (commit 34d249d8).

Introduction

Status: Current Last updated: 2026-08-30 21:00 EDT

Batchalign is a toolkit for language sample analysis (LSA) from the TalkBank project. It processes conversation audio files and their transcripts in CHAT format, providing automatic speech recognition, forced alignment, morphosyntactic analysis, translation, utterance segmentation, and audio feature extraction.

The standalone batchalign3 binary (written in Rust) provides the CLI and an HTTP server for offloading work to a central machine. Python ML workers (Stanza, Whisper, etc.) handle inference and are managed automatically by the server.

batchalign3 is the supported public Batchalign surface today. It is a public preview product line with wheels for Windows, macOS, and Linux. The separate Batchalign Desktop shell in apps/dashboard-desktop/ is still experimental and should not be described as the supported first-time-user entry point. For current platform details, see Platform Support and the Release Contract.

batchalign3 is installed from GitHub releases (there is no PyPI package): run the installer one-liner from the Installation guide, which bootstraps uv and installs the CLI with a uv-managed Python. Repo-hosted .command / .bat double-click wrappers run the same installer.

Who is Batchalign for?

Batchalign is designed for researchers and clinicians who work with conversation transcripts – particularly those stored in TalkBank’s CHAT format. Typical workflows include:

• Transcribing recorded conversations into CHAT files via ASR (Rev.AI or OpenAI Whisper).
• Aligning existing transcripts against audio to produce word-level and utterance-level timestamps.
• Tagging transcripts with morphological and dependency analyses (%mor and %gra tiers) using Stanford Stanza.
• Translating non-English transcripts to English.
• Segmenting unsegmented text into utterances.
• Extracting acoustic features (OpenSMILE, AVQI) from speech recordings.

Key features

• Rust-backed CHAT parsing. All CHAT reading and writing goes through a Rust AST (batchalign_core), ensuring correct handling of CHAT’s complex encoding, escaping, and continuation rules.
• Per-utterance caching. Morphosyntax, forced alignment, and utterance segmentation results are cached in a local SQLite database so that reprocessing the same corpus is nearly instant.
• Server mode. A built-in HTTP server lets you offload processing to a central lab machine. Clients send small CHAT files (~2 KB each); the server resolves media from configured volume mounts and does all the heavy computation.
• Automatic concurrency tuning. The CLI auto-tunes worker counts based on available RAM and GPU resources, and manages a persistent local daemon so model loads are amortized across successive commands.

How to use this book

This book is organized into six sections:

1. Migration Book – the authoritative public crosswalk from the previous release to the current version, anchored to the January 9, 2026 baseline 84ad500... and, where needed, the February 9, 2026 released BA2 master point e8f8bfa....
2. User Guide – Installation, quick start, CLI reference, Python API, server setup, and troubleshooting.
3. Architecture – How the pipeline, engine, dispatch, caching, and validation systems work internally.
4. Technical Reference – Detailed documentation on CHAT format, morphosyntax, forced alignment, multilingual support, and more.
5. Developer Guide – Building from source, testing conventions, adding new engines, and working with the Rust core.
6. Design Decisions – ADRs and accepted design notes on the implemented Rust control plane, correctness work, and server orchestration.

If you are a new user, start with Installation and Quick Start. If you are migrating from a previous version, start with Migration Guide. There is no public Python API, the supported integration path from Python is subprocess-into-batchalign3. See No Python API for the full statement.

Acknowledgments

The TalkBank Project, of which Batchalign is a part, is supported by NIH grant HD082736.

If you have questions or encounter issues, please open an issue in the repository’s issue tracker.

This page last changed: 2026-08-30 (commit 0964e762). The whole book last changed: 2026-09-16 (commit 34d249d8).

Installation

Status: Current Last updated: 2026-08-31 22:01 EDT

batchalign3 is distributed via GitHub releases (there is no PyPI package). The installer bootstraps uv if needed, installs batchalign3 into an isolated environment using a uv-managed Python (3.13 by default), and re-running it upgrades to the latest release.

# macOS / Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/FranklinChen/talkbank-tools/releases/latest/download/install-batchalign3.sh | sh

# Windows (PowerShell)
irm https://github.com/FranklinChen/talkbank-tools/releases/latest/download/install-batchalign3.ps1 | iex

After installing, open a new terminal so the batchalign3 command is on your PATH, then:

batchalign3 --help

Pre-built wheels are published for all five platforms (macOS Apple Silicon + Intel, Linux x86_64 + aarch64, Windows x86_64). One abi3 wheel per platform covers Python 3.13 and newer. batchalign3’s own dependencies still resolve from PyPI, so the first install downloads large ML dependencies.

System requirements

Choosing the Python version

The installer uses a uv-managed Python 3.13 by default. To install against a different supported version, set BATCHALIGN3_PYTHON before running it:

BATCHALIGN3_PYTHON=3.13 curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/FranklinChen/talkbank-tools/releases/latest/download/install-batchalign3.sh | sh

Double-click helpers

If you prefer not to use a terminal, the repo ships double-click wrappers that run the same installer:

• macOS: install-batchalign3.command
• Windows: install-batchalign3.bat

The downloaded helpers are not code-signed, so macOS Gatekeeper / Windows SmartScreen may warn on first run; see the installers README for the click-through. They install uv if needed and then run the canonical installer.

Updating

Re-run the installer one-liner; it reinstalls the latest release in place:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/FranklinChen/talkbank-tools/releases/latest/download/install-batchalign3.sh | sh

Offline / manual install from a wheel

Every release attaches per-platform wheels plus a sha256.sum. To install without the script (for example on an air-gapped machine), download the wheel for your platform from the latest release and install it with uv:

uv tool install --python 3.13 ./batchalign3-0.4.1-cp313-abi3-macosx_11_0_arm64.whl

First run

The first time you run a processing command (for example morphotag), ML models are downloaded automatically. This is a one-time cost of several GB and may take a few minutes depending on your connection; subsequent runs use cached models.

Evaluating the experimental GUI shell? See Batchalign Desktop (Experimental). The supported first-time user path is the batchalign3 CLI above.

Worker Python resolution

The CLI finds a Python 3.13 runtime automatically, via BATCHALIGN_PYTHON, the active virtualenv, a sibling/project .venv, or python3.13 on PATH. Override explicitly:

# macOS / Linux
export BATCHALIGN_PYTHON=/path/to/venv/bin/python

# Windows (PowerShell)
$env:BATCHALIGN_PYTHON = "C:\path\to\venv\Scripts\python.exe"

The visible batchalign3 command is a thin Python launcher that immediately execs the packaged Rust CLI binary. The launcher also preserves the chosen Python runtime for worker subprocesses, so batchalign3 serve ... and background/daemon flows run through the same Rust CLI/server codepath as direct invocation of the packaged binary.

Verify the installation

batchalign3 --help

Confirm the chosen Python runtime can import the worker package:

$BATCHALIGN_PYTHON -c "import batchalign.worker"

If you are relying on VIRTUAL_ENV or python3 instead of BATCHALIGN_PYTHON, run the same import check with that interpreter.

Rev.AI setup

If you plan to use the default Rev.AI-backed transcription path, initialize ~/.batchalign.ini:

batchalign3 setup

See Rev.AI Integration for details.

Development install

For contributors working from a source checkout:

git clone https://github.com/FranklinChen/talkbank-tools.git
cd talkbank-tools
make batchalign-python-prepare    # build wheel + sync uv env + install
make build                         # cargo build --workspace --release

make batchalign-python-prepare rebuilds the wheel via the maturin backend declared in pyproject.toml, runs uv sync --group dev --no-install-project, and installs the freshly built wheel into the dev environment.

make build runs cargo build --workspace --release. It does not rebuild the embedded dashboard; if you also need the React dashboard rebuilt, run make batchalign-dashboard-build (which requires Node.js + npm in addition to Rust and uv).

In a source checkout, uv run batchalign3 is the normal way to invoke the console script; the maturin backend’s profile = "dev" setting means each uv run ... triggers an incremental rebuild of the PyO3 extension on demand. Reserve uv run for Python tools such as pytest, mypy, and maturin when you are not invoking the CLI itself.

For the fastest contributor loop:

uv run batchalign3 --help        # incremental PyO3 rebuild via maturin/uv
cargo build -p batchalign         # native batchalign3 binary (debug)
./target/debug/batchalign3 --help

For the fuller contributor workflow and rebuild matrix, see Building & Development.

This page last changed: 2026-09-10 (commit 423245db). The whole book last changed: 2026-09-16 (commit 34d249d8).

Model Downloads and Caching

Status: Current Last updated: 2026-09-16 03:36 EDT

The contract

batchalign3 downloads every ML model it needs automatically, the first time a command needs it. You never have to seed models, run setup scripts, or remember which language pack lives where. The only error you should ever see related to model downloads is one of these:

• “Failed to download …: network unreachable”, your machine can’t reach the internet (or the upstream is down). Try again when you have network.
• “Failed to download …: disk full”, free some space and retry.
• “Failed to download …: HTTP 401/403”, a configured custom model requires authentication. BA3’s three PINNED released local Pyannote artifacts (talkbank/dia-fork and its segmentation/embedding dependencies) are public and ungated, but that engine also fetches one UNPINNED PLDA calibration artifact whose default is currently the GATED pyannote/speaker-diarization-community-1 repository; the model-access error names the repository and the fix (a Hugging Face token). See diarize.

If you see anything else, anything along the lines of “capability table is unavailable”, “resources.json could not be read”, “model not found locally” , that is a batchalign3 bug. file an issue on GitHub. You should not have to think about model storage.

What downloads, when, and roughly how big

Every download is one-time. After the first run, the model lives in your local cache and the same command runs without any download.

These sizes are ballpark. Real numbers depend on the upstream artifact and your network speed.

Which revision you get

The models BA3 loads by default are PINNED: each resolves to an exact revision rather than to whatever the upstream repository happens to hold today. Hugging Face models are pinned to a commit (openai/whisper-large-v3 at 06f233fe06e710322aca913c1bc4249a0d71fce1, for instance), and the ModelScope models the Paraformer engine loads, the checkpoint together with its voice-activity and punctuation models, are pinned to the tag v2.0.4, because ModelScope publishes no commit behind a tag. Cloud engines have no weights to pin; their request names the provider’s own model instead.

That covers the utterance-segmentation boundary models too, so a transcribe or utseg run in English, Mandarin or Cantonese loads a known revision (talkbank/CHATUtterance-en at 764ec3f762c2e24df2def8df98b5fe34940085c6, for instance). Because the revision is now known before the model loads rather than read back afterwards, every file those runs write records it: the engine= field of the [fc-ba3 utseg ...] comment is always <model id>@<revision>.

What that buys you: the same command on the same media loads the same weights next month as it does today, and a repository that moves upstream cannot silently change your output.

An override still loads. Passing your own model (for example --engine-overrides '{"funaudio_model":"..."}') leaves that model unpinned rather than refusing the job, and BA3 records it at the revision actually observed when it loaded, so the run still says which weights produced it. What an override cannot do is name its revision BEFORE the model loads, which is why a run with an unpinned model does not use the UTR ASR result cache (see below): no stored row could promise it came from the same weights.

What you’ll see on first run

Every download surfaces in your console, the TUI, the desktop app, and the web dashboard at http://<host>:8001/dashboard/jobs/<id>: whichever UI you’re using. This is a deliberate UX commitment (see the time transparency principle): you should always know what batchalign3 is doing and roughly how long it will take.

Example: a brand-new install running batchalign3 morphotag input/ output/ will show a sequence like:

Downloading Stanza resource catalog (one-time, ~1 MB; future runs will be instant)…
Stanza resource catalog ready.
Downloading Stanza language pack for eng (en) (one-time, ~250-500 MB; future runs will use the local cache)…
Loading Stanza English…
Processing input/file1.cha
Processing input/file2.cha
…

A fresh transcribe run:

Downloading openai/whisper-large-v3 for ASR (one-time, ~3 GB; future runs will use the local cache)…
Loading Whisper-large-v3 onto GPU…
Calling Rev.AI for utterance-timing recovery…
Processing recordings/r001.wav
…

If you see “Downloading X…” and the run sits there for a while, that is expected, the download is running in the background. The libraries also print their own progress bars to your terminal stderr.

After the first successful run, the same command on the same language runs without any download, typically in seconds (for text NLP) to a few minutes (for audio passes, dominated by inference, not loading).

Where models are stored

batchalign3 uses each library’s own cache. Locations vary by OS because each library follows its own platform conventions:

<resver> in the Stanza path is the resource-catalog version (e.g. 1.11.0), which Stanza bumps independently of the package version.

Combined cache size for a multi-language workflow can reach 10-30 GB.

Customizing cache locations

Each library honors a standard environment variable for cache override. Useful when you want to put caches on an external drive, a shared mount, or a smaller SSD:

Example: offload everything to an external drive:

export STANZA_RESOURCES_DIR="/Volumes/External/caches/stanza"
export HF_HOME="/Volumes/External/caches/huggingface"
export TORCH_HOME="/Volumes/External/caches/torch"
batchalign3 daemon start

If you set these before the first model download, batchalign3 downloads straight to the new location. If you set them after you’ve already downloaded somewhere else, models will re-download, copy the existing cache directories first to avoid that.

Working offline

After the first successful download, local-model commands work offline for the same languages and engines. Cloud engines such as Rev.AI and pyannoteAI still require their services. To enforce strictly offline Hugging Face behavior (and surface a clear error if a local model is missing rather than attempting a download), set:

export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1

Stanza always tries the local cache first; no equivalent flag is needed.

In strict offline mode, the user-facing error for a missing model is along the lines of “model X not in local cache; offline mode is enabled”, actionable, distinct from the download-failed errors above.

Pre-seeding for offline / air-gapped deployments

For deployments where the worker will run without internet (CI runners, air-gapped fleets, conference demos), do the first download on a machine with internet, then copy the cache directories to the offline target.

Stanza catalog + English pack:

python -c "import stanza; stanza.download('en')"

HuggingFace models (download to a known local path you can rsync):

python -c "
from huggingface_hub import snapshot_download
for repo in [
    'openai/whisper-large-v3',
    'talkbank/dia-fork',
    'facebook/hf-seamless-m4t-medium',
]:
    snapshot_download(repo)
"

Then copy the cache directories listed above to the offline machine, set HF_HUB_OFFLINE=1 / TRANSFORMERS_OFFLINE=1, and run.

Disk-space management

To free disk space by removing cached models (they will re-download next use):

# macOS
rm -rf ~/Library/Caches/stanza/
rm -rf ~/.cache/huggingface/hub/
rm -rf ~/.cache/torch/hub/

# Linux
rm -rf ~/.cache/stanza/
rm -rf ~/.cache/huggingface/hub/
rm -rf ~/.cache/torch/hub/

Removing caches mid-job is safe: any in-flight download will continue, and future jobs will re-download what they need. Removing caches while a daemon is running will not crash the daemon, the next job that needs the missing model will simply re-download it (and surface a download notification to you, as documented above).

Result caching (separate from model caching)

batchalign3 caches audio-bound intermediate evidence so repeated runs of align, selected transcribe stages, or standalone diarize on the same media with the same settings do not redo expensive service calls or model inference. The cache distinguishes final forced-alignment projection, raw forced-alignment worker evidence, UTR ASR, raw Rev transcript evidence, raw speaker evidence, and normalized speaker segments.

The authoritative list of cached task kinds is in crates/batchalign/src/chat_ops/cache_key.rs::CacheTaskName. Every kind is scoped to an identity of its own, alongside language, evidence/projection revision, and relevant inputs, so changing any of those produces a fresh entry. Which identity depends on the kind:

• Forced alignment is scoped to the engine version reported by the exact selected worker, because its rows are namespaced before inference runs.
• UTR ASR is scoped to the pinned plan instead: the engine together with the exact models it was pinned to, which is known before dispatch without loading anything. A run whose ASR model is unpinned has no such identity, so it infers without reading or writing UTR ASR rows rather than pooling them with another plan’s.

In server mode, worker models remain loaded between jobs as well; result caching and warm workers remove different costs.

Text NLP tasks are not cached. Running morphotag, utseg, translate, or coref twice on the same file runs the model twice. The CLI accepts --override-media-cache-tasks morphosyntax for backward- compatible scripting but emits a warning (“batchalign3 does not cache text NLP”) and ignores it.

To force re-computation of cached audio tasks (e.g., after a model update):

batchalign3 align --override-media-cache corpus/ -o output/ --lang eng
batchalign3 transcribe --override-media-cache recordings/ -o transcripts/ --lang eng

--override-media-cache clears all audio-task caches for the run. For finer control, pass --override-media-cache-tasks with one or more of forced_alignment, utr_asr, rev_asr_evidence, or speaker_diarization_raw_evidence. The last two are useful for controlled transcription experiments: refresh Rev without buying another speaker job, or refresh speaker evidence while replaying the same Rev response.

The result cache lives at:

You can rm it at any time; new runs will start a fresh cache.

When something goes wrong

Three classes of error you might legitimately see, and what to do:

Network unreachable. “Failed to download Stanza catalog: network unreachable” or “Failed to download model X: connection timeout”. Check your internet connection or proxy; retry. If you’re on a corporate network with a firewall, you may need to allow https://huggingface.co and https://raw.githubusercontent.com.

Disk full. “Failed to write model file: no space left on device”. Free up space (see “Disk-space management” above) or move caches to a larger drive (see “Customizing cache locations”). Then retry.

Authentication. “Failed to download X: HTTP 401/403”. The model requires a HuggingFace auth token. The standard batchalign3 install does not need any, if you’ve configured a custom model that requires auth, set HF_TOKEN in the daemon environment.

What you should never see. Errors mentioning “capability table”, “resources.json”, “model not installed”, or any internal-implementation language. If you see one of these, batchalign3 is failing to download something it should have downloaded automatically. File a bug on GitHub and include the error message verbatim plus the full command you ran. The team will fix the on-demand path; you will not be asked to seed models manually.

Related references

• Time transparency UX principle, why downloads (and other slow operations) always surface to the UI.
• Developer-facing model downloads doc, internals: load paths, cache invalidation, test strategy.

This page last changed: 2026-09-16 (commit 197c81e6). The whole book last changed: 2026-09-16 (commit 34d249d8).

Batchalign Desktop (Experimental)

Status: Current Last updated: 2026-08-30 21:00 EDT

Batchalign Desktop is the native Batchalign GUI shell in apps/dashboard-desktop/. It is experimental and is not currently a supported public release surface.

For supported end-user workflows today, install and run batchalign3 via the canonical CLI path in Installation. Treat this chapter as orientation for the in-repo desktop shell, not as the primary installation path for first-time users.

Current status

• Release contract: Experimental (see the Release Contract)
• Distribution: no supported public desktop bundle line today
• Desktop shell location: apps/dashboard-desktop/
• Supported product surface today: batchalign3 CLI, local server, and dashboard UI

Evaluating from source

Getting started

1. Install Batchalign: follow the Installation guide. The desktop app needs batchalign3 on your PATH.

2. Launch the shell from source: run npm run dev from apps/dashboard-desktop/.

3. First-time setup: on first launch, a setup wizard asks you to choose your default speech-to-text engine:

   • Rev.AI: fast cloud service, requires a paid API key from rev.ai/auth/signup
   • Whisper: free local model, slower, downloads ~2 GB on first use

   This creates ~/.batchalign.ini, the same config file that batchalign3 setup writes from the terminal.

What the shell is for

When run from source, the Batchalign desktop shell is meant to expose the same high-level processing flows as the batchalign3 CLI and web dashboard:

• pick a processing command
• choose files or folders
• launch work against a local Batchalign server
• monitor progress in a native window

The home screen

After setup, you see the home screen with two zones:

Command cards: six tasks you can perform:

Recent tasks: a compact list of your most recent processing jobs, with status and file count.

Processing a folder

1. Pick a command: click one of the six cards.

2. Choose input files: click the dashed area to open a native folder picker. The app scans the folder for relevant files (.cha for most commands, audio files for Transcribe). You’ll see the file count and folder path.

3. Choose output location: by default, output goes to a separate folder (click to choose one). You can switch to “Modify in place” if you want to overwrite the originals, make backups first.

4. Select language: shown for commands that need it (Transcribe, Align, Segment Utterances, Score Accuracy). Defaults to English.

5. Start processing: click the full-width Start button. The app submits the job to the local server and switches to the progress view.

Watching progress

The progress screen shows:

• Summary bar: command name, file count (“12 of 45 files”)
• Progress bar: animated blue stripe while running, turns green on completion or red on failure
• File list: live-updating via server-sent events. Currently processing files appear at the top with a pulsing blue dot, followed by queued, completed, and errored files. Each row shows the filename, current stage (e.g., “Aligning”, “Transcribing”), and duration.
• Cancel: click Cancel in the top-right to stop the job. Files that already finished processing are kept.

When processing finishes:

• Success: the bar turns green. Click Open Output Folder to view your results in Finder/Explorer. Click Process More Files to start another job.
• Errors: an error panel appears below the progress bar, grouping failed files by error type with plain-language explanations and suggested fixes. Common causes include invalid CHAT format, missing audio files, or low memory.

Server status

The app automatically starts a local batchalign3 server when it launches (on port 18000) and stops it when you quit. A status bar at the top of the screen shows the connection state:

You can manually stop and restart the server from the status bar.

Help

Click the ? button in the top-right corner of the header to open a help panel with descriptions of all six commands and answers to common questions.

Dashboard (power users)

Click Dashboard in the header to switch to the fleet monitoring view. This shows all jobs across servers with detailed file-level status, error grouping, and algorithm trace visualizations. It’s the same dashboard available in a web browser at http://localhost:18000/dashboard.

Settings and configuration

Click the gear icon in the top-right corner of the header to open Settings. From there you can:

• Switch your default ASR engine between Rev.AI and Whisper
• Add or update your Rev.AI API key

Changes are saved to ~/.batchalign.ini, the same config file that the CLI uses. You can also edit this file directly if you prefer:

[asr]
engine = rev
engine.rev.key = YOUR_KEY_HERE

Valid engine values: rev (Rev.AI cloud) or whisper (local).

Keyboard shortcuts

The app does not currently define custom keyboard shortcuts. Standard platform shortcuts (Cmd+Q / Alt+F4 to quit, Cmd+W to close window) work as expected.

Troubleshooting

“batchalign3 not found”: the app can’t find the CLI binary. Make sure you’ve installed Batchalign (see the Installation guide) and that your terminal’s PATH is available to GUI apps. On macOS, you may need to restart after installing.

Server won’t start: check that nothing else is using port 18000. Try running batchalign3 serve start --port 18000 in a terminal to see the error output.

Files not showing up: the folder picker filters by file extension. For most commands, only .cha files are shown. For Transcribe, only audio files (.wav, .mp3, .mp4, .m4a, .flac) are shown.

Processing is slow: the first run downloads ML models (~2 GB) and may take several minutes. Subsequent runs are much faster because models stay cached and the server keeps them in memory. See Performance for tuning tips.

For other issues, see Troubleshooting.

This page last changed: 2026-08-30 (commit 0964e762). The whole book last changed: 2026-09-16 (commit 34d249d8).

Web Dashboard

Status: Current Last updated: 2026-07-30 18:21 EDT

The batchalign3 web dashboard is a real-time monitoring interface for watching job progress, inspecting worker state, and tracking system resource usage. It opens automatically in your browser when you submit a job (unless you pass --no-open-dashboard).

Accessing the Dashboard

When the batchalign3 server is running, the dashboard is available at:

http://localhost:8000/dashboard

Replace localhost:8000 with the server’s address if running remotely (e.g., http://your-server:8001/dashboard).

The CLI opens the dashboard automatically when you submit a job:

batchalign3 transcribe corpus/ -o output/ --lang eng
# ↑ browser opens to /dashboard/jobs/<job-id>

To suppress the browser auto-open:

batchalign3 --no-open-dashboard transcribe corpus/ -o output/ --lang eng

Dashboard Layout

The main dashboard page (/dashboard) uses a two-column layout:

┌──────────────────────────────────────────────────────────────┐
│  batchalign   Dashboard   Visualizations       2 active  ●  │
├─────────────────────────────────────┬────────────────────────┤
│                                     │                        │
│  Job List                           │  Workers Panel         │
│  ┌─────────────────────────────┐    │  GPU: 1 process        │
│  │ TRANSCRIBE  ● running       │    │  Stanza: 2 processes   │
│  │ …/corpus/  3/50 files (6%)  │    │  IO: idle              │
│  │ ▓▓▓░░░░░░░░░░░░░░░░░░░░░░  │    │                        │
│  └─────────────────────────────┘    ├────────────────────────┤
│  ┌─────────────────────────────┐    │                        │
│  │ MORPHOTAG  ● completed      │    │  Memory Panel          │
│  │ 74/74 files    2m 15s       │    │  ▓▓▓▓▓▓▓▓▓▓░░░░░  │  │
│  └─────────────────────────────┘    │  148 GB used           │
│  ┌─────────────────────────────┐    │  108 GB available      │
│  │ ALIGN  ✗ failed             │    │  Gate: 2 GB ● safe     │
│  │ 12/15 files  3 failed       │    │                        │
│  └─────────────────────────────┘    ├────────────────────────┤
│                                     │                        │
│                                     │  Vitals                │
│                                     │  42 attempts  1 retry  │
│                                     │                        │
└─────────────────────────────────────┴────────────────────────┘

On mobile or narrow screens, the right column stacks below the job list.

Job List

Each job card shows:

• Command badge: color-coded by command type (green for transcribe, indigo for align, violet for morphotag, etc.)
• Status: queued (amber), running (blue, pulsing), completed (green), failed (red), cancelled (gray)
• Source directory: abbreviated path to the input files
• File progress: completed/total files (percent)
• Workers: how many concurrent file workers are assigned
• Duration or age: elapsed time (running) or “3m ago” (completed)
• Error count: if any files failed, shown in red

Click a job card to open the job detail page.

Job Detail Page

The detail page at /dashboard/jobs/<id> shows:

Header

• Command badge, status dot, job ID
• Action buttons: cancel (if running), restart, delete

Metadata Grid

• Files: completed / total (percent)
• Submitted: relative time (“3m ago”)
• Duration: elapsed wall clock
• Workers: concurrent file count

Progress Bar

For active jobs, an animated progress bar with striped fill. Shows an indeterminate shimmer when the job is queued but no files have started.

Command Args

The original submission options as formatted JSON, useful for debugging which engine, language, and flags produced this output.

File Table

Every file in the job, grouped by directory. Each row shows:

• Filename: just the basename (directory shown as a collapsible group header)
• Status: dot + label + optional error category badge
• Pipeline phase indicator: for processing files, a 5-segment bar showing which pipeline phase is active (Read → Transcribe → Align → Analyze → Finalize)
• Sub-file progress: when available, a mini progress bar with counter (e.g., “Aligning 3/7”)
• Stage label: the current processing stage in italic text
• Duration: how long this file took (done files)
• Error detail: click to expand full error text (error files)

Error Panel

If files have failed, errors are grouped by error code with counts. Each group shows the error category (Parse, Media, System, Engine, Pipeline Bug) and affected filenames.

Filter Tabs

Filter the file table by status: All, Processing, Done, Error, Queued. A search box lets you filter by filename.

Workers Panel

Shows the three worker profiles and their current state:

GPU Profile (amber)

• Shared ASR + Forced Alignment + Speaker models in one process
• When active: “1 process” with language tags (e.g., eng shared)
• Key callout: “Models shared, align + transcribe reuse one process”
• Commands served: align, transcribe, transcribe_s, benchmark

Stanza Profile (indigo)

• NLP processors (POS tagging, dependency parse, coreference)
• Multiple processes for CPU parallelism (e.g., “2 processes”)
• Shows idle/total per language: eng 1/2 idle
• Commands served: morphotag, utseg, coref, compare

IO Profile (emerald)

• Lightweight API/library calls (translation, audio analysis)
• Usually 1 process per language
• Commands served: translate, opensmile, avqi

Memory Panel

Real-time system RAM usage:

• Gauge bar: colored segment showing used vs available memory. Changes color based on proximity to the memory gate threshold:
  • Green: plenty of headroom (available > 4× threshold)
  • Amber: getting close (available between 2× and 4× threshold)
  • Red: danger zone (available < 2× threshold)
• Numbers: “148 GB used” / “108 GB available”
• Gate threshold: shown as a vertical marker on the gauge and a status badge (e.g., “Gate: 2 GB threshold”)
• Gate rejections: if any jobs have been rejected due to memory pressure, shown as a red count badge

The memory gate prevents new jobs from starting when available RAM drops below the configured threshold (default: 2 GB). This protects against OOM crashes when running large ML models.

Vitals Panel

Compact operational counters since server start:

Only nonzero counters are shown. If everything is healthy, the vitals panel shows only the attempt count.

Pipeline Stages

When a file is actively processing, the dashboard shows which pipeline phase it’s in using a 5-segment indicator:

Not all files go through all phases, an align job skips Transcribe and Analyze; a morphotag job skips Transcribe and Align.

Connection Status

The header shows a connection indicator:

• Green dot + “Connected”: live WebSocket connection to the server. Updates stream in real time.
• Red dot + “Reconnecting…”: connection lost. The dashboard will automatically reconnect with exponential backoff.

When connected, job and file status updates arrive via WebSocket push, no manual refresh needed. The dashboard also polls the health endpoint every few seconds to keep the memory and worker panels current.

Algorithm Visualizations

The dashboard includes interactive algorithm visualizations at /dashboard/visualizations:

• DP Alignment Explorer: step through the dynamic programming cost matrix used for word alignment, with fill and traceback animation
• Retokenization Mapper: see how Stanza word splits/merges are resolved back to CHAT words
• ASR Pipeline Waterfall: (planned) stage-by-stage ASR post-processing
• FA Timeline: (planned) DAW-style forced alignment timing visualization

Each visualization has a static mode (editable sample data, no server needed) and a live mode (actual trace data from a completed job with debug_traces enabled).

Keyboard Shortcuts

The dashboard is mouse-driven. The job detail page supports:

• Tab: cycle through filter tabs
• Arrow keys: navigate file list pagination

Tips

• Frozen progress during batch commands (morphotag, utseg, translate, coref): this is normal. The model processes all files at once, so individual files don’t advance until the batch completes. The elapsed timer keeps ticking.
• Multiple concurrent jobs: the dashboard shows all jobs. Use the status filter tabs to focus on active or failed jobs.
• Error investigation: click an error row to expand the full error message. Error codes link to specific failure categories that help diagnose whether the issue is in your input, media files, or the processing engine.
• Large corpora: for jobs with hundreds of files, use the search box in the file table to find specific files by name.

This page last changed: 2026-07-31 (commit 8e3b0e23). The whole book last changed: 2026-09-16 (commit 34d249d8).

Progress and Feedback

Status: Current Last updated: 2026-07-30 18:21 EDT

Batchalign reports real-time progress during processing. This page explains what to expect for each command, what the progress indicators mean, and when to worry versus when to wait.

How Progress Works

Every processing job tracks progress at the file level. In server mode, the server reports stage transitions and optional sub-file counters (e.g., “Aligning 3/7 groups”) to all connected clients, the CLI, TUI, and React dashboard all consume the same stream. In direct local mode, the CLI now projects the same file-status snapshots from the in-memory direct host, so local runs still show live terminal progress without requiring a dashboard.

For direct local runs, the CLI also prints a stable debug handle at startup:

• the direct job ID
• the local artifact directory for that job

On failures, the CLI prints any persisted bug-report IDs and direct debug artifact paths so you can inspect the failed run later without keeping the process alive.

There are two progress tiers:

• Stage labels: every file shows a stage name (“Reading”, “Aligning”, “Writing”) that changes as processing advances.
• Sub-file counters: some stages include a current/total counter for fine-grained progress within a single file.

Per-Command Expectations

align (forced alignment)

Align processes files individually and concurrently. Each file goes through:

1. Reading: loading the CHAT file from disk
2. Resolving audio: finding and preparing the media file
3. Recovering utterance timing (if needed), re-transcribing to recover word timing for untimed utterances. Shows sub-progress for partial-window UTR (e.g., “2/5” windows). This step takes roughly as long as the recording itself.
4. Aligning: forced alignment on utterance groups. Shows sub-progress (e.g., “3/7” groups).
5. Writing: saving the aligned output

Timing: Most of the time is spent in steps 3-4. A 10-minute recording typically takes 5-15 minutes depending on the engine and number of utterances.

transcribe

Transcribe processes files individually. Each file goes through:

1. Resolving audio → Transcribing → Post-processing → Building CHAT → optional Segmenting / Morphosyntax → Finalizing → Writing

Shows a pipeline stage counter (e.g., “2/5”) as each stage completes.

Timing: Rev.AI runs roughly in real-time. Whisper may take 2-5x the audio length.

morphotag, utseg, translate, coref (batched commands)

These commands batch all files together into a single inference call for GPU efficiency. Progress stages:

1. Reading: files are loaded one at a time; each transitions from the initial stage to “Reading” during I/O.
2. Analyzing/Segmenting/Translating (0/N), the batch total is published before inference starts. During inference, the progress bar shows the batch size but individual files don’t advance.
3. Writing (1/N, 2/N, …), as each file’s result is written to disk, the counter ticks up.

For large in-place reruns driven by --file-list, the batched text commands may still stage the rewritten CHAT files until the current invocation finishes. In other words: you can see healthy progress without seeing the input .cha files mutate on disk yet. If you want visible on-disk updates during a long repair pass, split the rerun into smaller invocations.

What “frozen” means: During step 2, the progress bar won’t advance because all files are processed as a single batch. This is normal, the model is working on your entire corpus at once. The elapsed timer keeps ticking to confirm the app is alive.

Timing: Depends on corpus size. 50 files typically takes 1-5 minutes for morphotag, faster for translate and utseg.

When to Worry vs. When to Wait

Normal: Progress frozen during batch processing, or during UTR/transcription (these are genuinely long-running). The elapsed timer should always be ticking.

Investigate if:

• The elapsed timer stops advancing (app may have frozen, try refreshing)
• A file stays in “Reading” for more than 30 seconds (possible I/O issue)
• “Resolving audio” persists for minutes (media file may be missing)

How to Cancel

• Desktop app: Click the red “Cancel” button in the progress view
• CLI: Press Ctrl+C (graceful shutdown)
• API: POST /jobs/{id}/cancel

Cancellation is cooperative, the current file finishes its in-progress work before the job stops.

Pipeline Phase Indicator

For processing files, the dashboard and desktop app show a compact 5-segment phase bar that maps the 23 internal progress stages into visual phases:

The 23 FileProgressStage variants map to 5 visual phases via phase_index() in crates/batchalign/src/cli/tui/ui.rs; two variants (Processing generic fallback and RetryScheduled) deliberately do not map to a phase.

The active phase pulses; completed phases are filled; future phases are gray. Not every command uses all phases, morphotag skips Transcribe and Align; align skips Transcribe and Analyze.

Progress Displays

TUI Details (--tui)

The TUI shows the same information as the web dashboard in a terminal-friendly format:

• Header with status breakdown (3✓ 2⠋ 1✗ 44·), elapsed time, and ETA. Shows “Done!” or “Done, N failed” on completion.
• Pipeline phase dots next to each processing file: ●●●○○ maps the 5 phases (Read/Transcribe/Align/Analyze/Finalize) using the same grouping as the web dashboard. Green = completed, cyan = active, gray = future.
• Per-file elapsed timer (M:SS) on processing files, computed from started_at. Helps spot stuck files during long align/transcribe jobs.
• Worker status line between the header and file list: shows active worker keys.
• Memory gauge below the worker line: 20-char bar with used/total GB and gate proximity indicator (safe/warn/danger). Warns explicitly when memory is near or below the gate threshold.
• Scroll indicators (▲ N more above / ▼ N more below) when groups have more files than fit on screen.
• Auto-collapse for completed groups: non-focused groups where all files are done or errored show a condensed title.
• Error codes in the error panel, extracted from the server’s structured error codes (e.g. [E362] Bullet timestamps must be monotonic).

Keybinds: q quit · c cancel · ↑↓ scroll · tab group · e errors · m metrics

Press m to toggle the worker/memory rows on small terminals.

This page last changed: 2026-07-31 (commit 8e3b0e23). The whole book last changed: 2026-09-16 (commit 34d249d8).

Quick Start

Status: Current Last updated: 2026-09-07 07:04 EDT

This chapter covers the most common batchalign3 workflows from the terminal. The examples assume the batchalign3 binary is installed and that local processing commands can reach a Python runtime with batchalign.worker available.

Evaluating the experimental GUI shell? See Batchalign Desktop (Experimental). The supported first-time user path today is still the batchalign3 CLI.

For the full command surface, see the CLI Reference.

Before you start

Model downloads: The first time you run a processing command, Batchalign downloads ML models (~2 GB). This is a one-time cost, subsequent runs use cached models from disk.

Caching: Batchalign caches audio-bound intermediate results (forced-alignment word timings and the UTR ASR pass) in a local SQLite database, so re-running align or transcribe on the same audio returns those steps from cache. Text-NLP commands (morphotag, utseg, translate, coref) are not cached and always recompute. See Caching for details.

Performance: Back-to-back runs are still much faster than first-run model downloads because models and caches stay on disk. If you need hot in-memory workers across repeated runs, start an explicit server with batchalign3 serve. See Performance for tuning tips.

Basic command shape

batchalign3 [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS] [PATHS...]

• Global options go before the command.
• Most processing commands use -o/--output for a destination directory.
• Omitting -o/--output means in-place processing when the command supports it.

Transcribe audio to CHAT

batchalign3 transcribe ~/recordings/ -o ~/transcripts/ --lang eng

To use a local Whisper model:

batchalign3 transcribe ~/recordings/ -o ~/transcripts/ \
  --asr-engine whisper --lang eng

Important routing note: explicit --server now submits shared-filesystem paths_mode jobs for transcribe. The target server must be able to read the same input paths and write the requested output paths.

Align transcripts against audio

batchalign3 align ~/corpus/ -o ~/aligned/

Common useful flags:

batchalign3 align ~/corpus/ -o ~/aligned/ --wor
batchalign3 align ~/corpus/ -o ~/aligned/ --fa-engine whisper
batchalign3 align ~/corpus/ -o ~/aligned/ --utr-engine whisper

Add morphosyntactic analysis

batchalign3 morphotag ~/corpus/ -o ~/tagged/

Useful variants:

batchalign3 morphotag ~/corpus/ -o ~/tagged/ --retokenize
batchalign3 morphotag ~/corpus/ -o ~/tagged/ --skipmultilang

morphotag is not cached, so repeated runs run the full Stanza pipeline again. The wall-clock win for repeated runs comes from keeping workers warm in memory rather than from disk caching. For interactive sessions where you want workers to stay loaded across commands, use explicit server mode (batchalign3 serve start plus --server).

Verbosity

batchalign3 align ~/corpus/ -o ~/aligned/
batchalign3 -v align ~/corpus/ -o ~/aligned/
batchalign3 -vv align ~/corpus/ -o ~/aligned/
batchalign3 -vvv align ~/corpus/ -o ~/aligned/

Run logs

batchalign3 logs
batchalign3 logs --last
batchalign3 logs --export
batchalign3 logs --clear

Remote server mode

For commands that support explicit remote dispatch:

batchalign3 --server http://yourserver:8000 morphotag ~/corpus/ -o ~/tagged/
batchalign3 --server http://yourserver:8000 align ~/corpus/ -o ~/aligned/

transcribe, transcribe_s, benchmark, and avqi always prefer the local daemon and ignore --server (see command_prefers_local_daemon in crates/batchalign/src/cli/dispatch/mod.rs). The remaining text and analysis commands (morphotag, align, compare, etc.) honor explicit --server routing.

Next steps

• Batchalign Desktop (Experimental), in-repo GUI shell status and scope
• CLI Reference
• Performance
• Server Mode
• Rev.AI Integration
• Python API

This page last changed: 2026-09-09 (commit 8f4ed0f2). The whole book last changed: 2026-09-16 (commit 34d249d8).

CLI Reference

Status: Current Last updated: 2026-09-16 09:47 EDT

This page documents the current public batchalign3 CLI surface. For anything you are scripting against, confirm with batchalign3 <command> --help.

For detailed input/output patterns and mutation behavior per command, see Command I/O Parity.

Command shape

batchalign3 [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS] [PATHS...]

Global options go before the command name.

Global options

BA2 compatibility flags (--memlog, --mem-guard, --adaptive-workers, --pool, --shared-models, etc.) have been removed. If your scripts use them, remove them.

Engine selection

These are per-command flags, not global ones: they go AFTER the command name, like batchalign3 transcribe in/ --asr-engine paraformer.

Each flag’s --help lists every value it accepts, derived from the engine enum itself, so the advertised set and the accepted set are the same list. An unrecognized name is rejected while parsing, naming what you typed and suggesting the nearest valid value.

The older --asr-engine-custom / --fa-engine-custom / --utr-engine-custom flags still work and are hidden from help. They exist because each visible flag used to advertise only some of its engines, which left the rest reachable only through a second, differently-named flag: that is how the Cantonese engines stayed hidden from the people who needed them. Prefer the flags above.

The asr / fa / utr / translate keys of --engine-overrides also select an engine, and take precedence over the flags. Use the flags for ordinary work; the keys exist so one shared option can pin engines across a batch.

utr was missing from that set until 2026-08-06: it parsed, was forwarded to the Python worker as an opaque extra, and was ignored by everything, so a user who wrote it saw their choice silently dropped.

Sequential mode

--sequential gives you the simplest possible execution path, similar to batchalign2’s direct mode. One worker per task type, files processed one at a time, no concurrency infrastructure:

batchalign3 morphotag corpus/ -o output/ --sequential

What it does:

• Forces --workers 1 and --no-server
• Disables the memory gate (no cross-process coordination)
• Keeps the worker alive for the entire run (no idle timeout kills)
• Preserves the utterance cache (repeated runs benefit from cached results)

When to use it:

• Processing a handful of files on a laptop
• Debugging pipeline issues (predictable, single-threaded execution)
• Environments where memory auto-tuning is unwanted

When NOT to use it:

• Large corpus runs (50+ files), the default parallel mode is 3-5× faster
• Fleet machines with warm workers, use the server instead

--sequential is incompatible with --server (mutually exclusive).

Dashboard browser auto-open

On macOS, when you run a processing command interactively (e.g., batchalign3 transcribe corpus/ output/), the CLI automatically opens the job’s dashboard page in your default browser. This lets you monitor progress in real time.

Direct local execution does not submit an HTTP job, so there is no dashboard page to open. In that mode, --open-dashboard is a no-op and the CLI shows local terminal progress inline instead.

The dashboard auto-open is only triggered when:

• Running on macOS (no-op on Linux/Windows)
• stderr is connected to an interactive terminal (TTY)
• --no-open-dashboard was not passed
• The BATCHALIGN_NO_BROWSER environment variable is not set

It will not fire in non-interactive contexts: cron jobs, CI pipelines, SSH sessions without a display, piped output, or scripts. To suppress it explicitly in interactive sessions, pass --no-open-dashboard.

Common path-processing options

The core processing commands documented below all accept:

When exactly two positional paths are provided, the CLI still accepts the legacy input/output directory form. For new scripts, prefer -o/--output.

--file-list format

--file-list FILE reads input paths from a plain-text UTF-8 file, one path per line:

• Blank lines and lines beginning with # are ignored; whitespace around each path is trimmed.
• A relative path resolves against the directory containing the list file, not the directory you run the command from. Absolute paths are used as written.
• A path naming a directory is expanded exactly like a positional directory argument: matching files are discovered recursively beneath it.
• The input set is de-duplicated, keeping the first occurrence. A file listed twice, spelled two ways (a.cha, ./a.cha, an absolute path), or reached both directly and through a listed directory is processed once.
• Every entry must exist when the command runs. A missing entry is a usage error (exit code 2) naming the list file and line, for example lists/rerun.txt:3: input path does not exist: lists/corpus/missing.cha.

# lists/rerun.txt: entries are relative to lists/
corpus/session-01.cha
corpus/session-02.cha

# a whole directory, and an absolute path
corpus/follow-up/
/data/project/extra/session-09.cha

# Run align on every listed input (in place, against a remote server)
batchalign3 --server http://your-server:8001 align --file-list lists/rerun.txt

To process a large list in smaller batches, split it into chunk files in the same directory as the original list (for example, run split -l 10 rerun.txt batch- inside that directory) so relative entries keep resolving against the same place, then run batchalign3 align --file-list <chunk> on each chunk sequentially.

--file-list cannot be combined with positional PATHS arguments; the CLI rejects the combination. Without -o/--output, every listed input is processed in place (output overwrites input); with -o DIR, results are written under DIR exactly as for positional inputs.

For batched text-NLP commands (morphotag, utseg, translate, coref), large --file-list runs may not show file-by-file on-disk rewrites while the invocation is still running. The command can batch/stage work internally and then commit the in-place writes when the current invocation finishes. If you need visible write-through during a long rerun, split the list into smaller chunks and run those chunks sequentially.

Processing commands

Each processing command has a dedicated page with full options, a pipeline diagram, examples, and gotchas. Click the command name for complete documentation.

CHAT-mutation commands (input .cha → output .cha)

Audio-input commands (input audio → new files)

Operational commands

setup

Initialize ~/.batchalign.ini:

batchalign3 setup
batchalign3 setup --non-interactive --engine whisper
batchalign3 setup --non-interactive --engine rev --rev-key <KEY>

Options:

logs

batchalign3 logs
batchalign3 logs --last
batchalign3 logs --export
batchalign3 logs --clear

Key options:

serve

batchalign3 serve start --foreground
batchalign3 serve status
batchalign3 serve stop

serve start key options:

jobs

batchalign3 jobs --server http://myserver:8000
batchalign3 jobs --server http://myserver:8000 <JOB_ID>
batchalign3 jobs <JOB_ID>
batchalign3 jobs --json <JOB_ID>
batchalign3 jobs cancellations <JOB_ID>

With --server, lists or inspects remote jobs. Without --server, inspects the local job artifact directory for post-failure debugging. Pass --json for machine-readable output.

The cancellations subcommand prints the cancellation audit history for a single job, every cancel attempt is recorded with source (tui / api / dashboard / staging / signal), host, pid, reason, and in_flight_filename. Use this when a user reports “I didn’t cancel that job.”

cache

batchalign3 cache stats
batchalign3 cache clear --yes
batchalign3 cache clear --all --yes

BATCHALIGN_ANALYSIS_CACHE_DIR and BATCHALIGN_MEDIA_CACHE_DIR relocate the underlying caches for isolated runs. BA2-compatible flag forms cache --stats and cache --clear are still accepted.

openapi

batchalign3 openapi -o openapi.json
batchalign3 openapi --check --output openapi.json

--check exits non-zero when the target file does not match the generated schema.

models

Two subcommands:

See Models Training Runtime ADR.

ipc-schema

batchalign3 ipc-schema -o schemas/
batchalign3 ipc-schema --check --output schemas/

Emits JSON Schema for Rust→Python IPC types. Without -o, schemas are written to stdout as a single JSON object. With --check, exits non-zero on schema drift against the target directory.

bench

batchalign3 bench <COMMAND> <IN_DIR> <OUT_DIR> [--runs N]
batchalign3 bench align corpus/ out/ --runs 3 --dataset eng-childes-v1
batchalign3 bench align corpus/ out/ --use-cache

Benchmark command execution time across repeated runs. <COMMAND> is one of: align, transcribe, transcribe_s (with diarization), morphotag, translate, utseg, benchmark, opensmile, coref, compare. Distinct from the benchmark top-level command, which measures ASR word accuracy.

doctor

batchalign3 doctor
batchalign3 doctor --lang yue --format json
batchalign3 doctor --explain memory_gate_mb
batchalign3 doctor --warnings-as-errors

Pre-flight diagnostic that spawns a test worker, sends known inputs through the morphosyntax pipeline, and validates the output structure. Catches machine-specific issues (stale models, missing processors, MWT quirks) before they become production failures.

replay

batchalign3 replay <DUMP_FILE>
batchalign3 replay --lang yue path/to/failed_ipc_*.json

Replay a captured failed IPC request against a fresh worker. Takes a dump file from ~/.batchalign3/debug/ and sends the exact request to a new worker, reporting the response. Useful for reproducing field failures locally.

eval

batchalign3 eval l2-morphotag <ARGS>
batchalign3 eval utr-alignment --chat <CHAT> --tokens <JSON> --output <JSON>
batchalign3 eval utseg-replay post-chat --input-chat <CHAT> --evidence <JSON> --output-chat <CHAT>
batchalign3 eval utseg-replay pre-asr --asr-response <JSON> --evidence <JSON> --output-chat <CHAT> [--media-name <NAME>] [--wor]

Evaluation subcommands. Currently:

version

batchalign3 version

Prints version and build information.

Exit codes

batchalign3 uses stable non-zero exit code categories:

Exit code 1 is reserved for unexpected failures outside the typed categories.

A server that reports another build than the CLI’s, or no build, is refused before anything is submitted, with exit code 5; see Server Mode: build identity check.

This page last changed: 2026-09-16 (commit 197c81e6). The whole book last changed: 2026-09-16 (commit 34d249d8).

align

Status: Current Last updated: 2026-09-15 09:28 EDT

Add word-level and utterance-level timestamps to an existing CHAT transcript by running forced alignment against the corresponding audio file.

Requires: a .cha file whose @Media header names an audio file visible to the server (or to the local daemon). See Media Resolution.

Quick start

# Align one file in place
batchalign3 align file.cha

# Cantonese / other non-RevAI languages: choose a compatible UTR backend explicitly
batchalign3 align yue_file.cha --utr-engine whisper

# Align a corpus directory, writing results to a separate output directory
batchalign3 align corpus/ -o aligned/

# Audio lives in a different directory from the .cha files
batchalign3 align transcripts/ -o out/ --media-dir /path/to/audio/

# Align a curated list of files against a remote server
batchalign3 --server http://your-server:8001 align --file-list rerun.txt

Pipeline

align is FA-first. It does not always need utterance timing recovery (UTR), and the selected UTR backend only matters when the parsed CHAT file actually contains untimed utterances.

In practice that means:

• fully timed files can skip UTR entirely and go straight to FA
• partially timed or untimed files may require UTR before FA
• backend/language errors should be read as “this file needs UTR, and the selected UTR backend cannot support it”, not as “forced alignment itself is unavailable for this language”

The diagram below shows how CLI flags control the alignment pipeline at runtime. Source: crates/batchalign/src/runner/dispatch/.

flowchart TD
    start([align invoked]) --> read[Read CHAT file]
    read --> resolve_audio[Resolve audio file]
    resolve_audio --> ensure_wav[ensure_wav: convert mp4→wav if needed]
    ensure_wav --> parse[parse_lenient → ChatFile]
    parse --> reuse_check{Complete reusable\n%wor timing?}
    reuse_check -->|Yes| reuse[Refresh main-tier bullets from %wor\nmechanically, then resolve overlap\n(--end-overlap-policy) and only THEN\noptionally regenerate %wor from the\nresolved state]
    reuse_check -->|No| count[count_utterance_timing → timed, untimed]
    reuse --> done([Output .cha file])

    count --> utr_check{untimed > 0?}
    utr_check -->|No| skip_utr[Skip UTR, all timed]
    utr_check -->|Yes| utr_engine_check{UTR enabled\nand selected backend\nsupports this file?}

    utr_engine_check -->|Yes| run_utr_pass["run_utr_pass()"]
    utr_engine_check -->|No: --no-utr| warn_interp[Log warning\nFall back to interpolation]

    run_utr_pass --> utr_done[Re-serialize CHAT\nwith recovered timing]
    utr_done --> group

    warn_interp --> group
    skip_utr --> group

    group[group_utterances → time windows]

    group --> before_check{--before path\nprovided?}
    before_check -->|Yes| incremental[process_fa_incremental\nDiff old vs new, copy stable %wor,\nreuse preserved groups]
    before_check -->|No| full[process_fa\nProcess all groups]

    incremental --> engine_select
    full --> engine_select

    engine_select{--fa-engine?}
    engine_select -->|whisper| whisper_fa[Whisper engine\nonset times only\nmax_group_ms from the engine = 20000]
    engine_select -->|wav2vec / cantonese| wav2vec_fa[Wave2Vec engines\nword start+end\nmax_group_ms from the engine = 15000]
    engine_select -->|qwen3_fa| qwen3_fa[Qwen3 aligner\nword start+end\nyue/zho/cmn/eng only\nmax_group_ms from the engine = 15000]

    whisper_fa --> pause_check
    wav2vec_fa --> pause_check
    qwen3_fa --> pause_check

    pause_check{--pauses?}
    pause_check -->|Yes| preserve[WordGapHealing::PreserveMeasured\nkeep each word's own end]
    pause_check -->|No| heal[WordGapHealing::Heal\nbridge small plausible gaps]

    preserve --> cache_check
    heal --> cache_check

    cache_check[Cache lookup: BLAKE3 keys]
    cache_check --> worker_infer[execute_v2(task="fa") misses → Python FA worker\nprepared audio + prepared text]
    worker_infer --> response_shape{Worker response shape?}
    response_shape -->|Wave2Vec / Cantonese indexed intervals| indexed_fa[Validate one timing per requested word]
    response_shape -->|Whisper token onsets| dp_align_fa[DP-align returned tokens → transcript words]
    indexed_fa --> inject_fa[Inject word-level timings into AST]
    dp_align_fa --> inject_fa

    inject_fa --> retry_check{FA\nsucceeded?}
    retry_check -->|Yes| prior_boundary_check{"--existing-wor-boundaries?"}
    prior_boundary_check -->|preserve| preserve_prior[Clamp against prior authoritative bounds<br/>and preserve compatible edge coverage]
    prior_boundary_check -->|rebuild-from-evidence| rebuild_prior[Keep fresh word extents<br/>rebuild main bullet from word hull]
    preserve_prior --> overlap_policy
    rebuild_prior --> overlap_policy
    retry_check -->|No + retryable| fallback_check{Untimed utts\nnot recovered?}
    fallback_check -->|Yes + not tried| fallback_utr["Fallback: run_utr_pass()\n(at most once)"]
    fallback_utr --> retry_loop[Retry FA with\nrecovered timing]
    retry_loop --> cache_check
    fallback_check -->|No or already tried| backoff[Backoff + retry]
    backoff --> cache_check

    overlap_policy{"--end-overlap-policy?\n(default: preserve-cross-speaker)"}
    overlap_policy -->|preserve-cross-speaker default, ALWAYS| resolve_same[Resolve same-speaker overlap BY SPEAKER STREAM\nnot file adjacency: skips an intervening\nother-speaker line. CoverageOnly / BoundaryFromWords /\nInterleavedWords, from measured word hulls.\ncross-speaker overlap untouched]
    resolve_same -->|clamp-all-adjacent ADDITIONALLY| resolve_all[Also resolve every PHYSICALLY adjacent overlap\nsame rule, any speaker pair\ncannot undo resolve_same: only shrinks]

    resolve_same -->|preserve-cross-speaker| wor_check
    resolve_all --> wor_check

    wor_check{--wor / --nowor?}
    wor_check -->|--wor| gen_wor["Generate %wor tier\n(from the RESOLVED state)"]
    wor_check -->|--nowor| skip_wor[Omit %wor tier]

    gen_wor --> merge_check
    skip_wor --> merge_check

    merge_check{--merge-abbrev?}
    merge_check -->|Yes| merge[merge_abbreviations transform]
    merge_check -->|No| validate

    merge --> validate[Post-validate → serialize CHAT output]
    validate --> done([Output .cha file])

Validation model

align uses staged validation:

1. request-shape validation Invalid path-mode shapes, malformed flags, and incompatible option payloads fail immediately.
2. file-state inspection After parsing the CHAT file, Batchalign inspects whether the file is already timed well enough to skip UTR.
3. stage-specific backend validation If the file needs UTR, Batchalign validates the selected UTR backend against the file’s language before running timing recovery.

This is why --utr-engine matters for some files but is irrelevant for others.

UTR strategy selection (Auto disabled)

When --utr-strategy auto (the default), the strategy is currently always GlobalUtr regardless of file content or language. The previous content/language-aware auto-routing (which auto-picked TwoPassOverlapUtr for English files containing +< or ⌊ markers) was disabled 2026-03-30. ResolvedUtrStrategy in crates/batchalign/src/runner/dispatch/options.rs resolves this policy once. Two-pass overlap-aware recovery is reachable only via the explicit --utr-strategy two-pass override.

flowchart TD
    auto(["--utr-strategy auto\n(default)"]) --> always_global["GlobalUtr\n(monotonic single-pass)"]
    explicit_global(["--utr-strategy global"]) --> force_global["GlobalUtr\n(explicit override)"]
    explicit_two(["--utr-strategy two-pass"]) --> force_two["TwoPassOverlapUtr\n(explicit override)"]

Why Auto was disabled: an operator reported alignment regressions on real files; investigation found that enforce_monotonicity() only checks start times, not end times, so overlapping utterance bullets go uncorrected. The two-pass tuning was also based on only four corpora and not broadly validated. The previously-measured gains under that mechanism (English: +4.3pp SBCSAE, +3.8pp Jefferson; non-English on Hakka/Welsh/German/Serbian: GlobalUtr matched or beat TwoPassOverlapUtr) are retained here as historical context for the benchmark numbers that motivated the original gate, not as a description of current default behavior.

UTR internals: partial vs full-file ASR

When fewer than 50% of utterances are untimed and audio is longer than 60 s, run_utr_pass() uses partial-window ASR (running ASR only over untimed regions) rather than a full-file pass.

flowchart TD
    entry(["run_utr_pass()"]) --> parse[Parse CHAT\ncount timed vs untimed]
    parse --> zero{untimed == 0?}
    zero -->|Yes| noop([Return: nothing to do])
    zero -->|No| ratio{untimed < 50%\nAND audio > 60s?}

    ratio -->|Yes| partial_mode

    subgraph partial_mode [Partial-Window ASR]
        direction TB
        pw_find[find_untimed_windows\nPadding: 500ms, merge overlaps]
        pw_find --> pw_loop["For each window (start, end):"]
        pw_loop --> pw_seg_cache{Segment\ncache hit?}
        pw_seg_cache -->|Hit| pw_use[Use cached segment ASR]
        pw_seg_cache -->|Miss| pw_extract["extract_audio_segment()\nffmpeg -ss/-to → cached WAV"]
        pw_extract --> pw_infer[infer_asr on segment]
        pw_infer --> pw_store[Cache segment result]
        pw_store --> pw_use
        pw_use --> pw_offset[Offset token times\nby window start_ms]
        pw_offset --> pw_loop
    end

    ratio -->|No| full_mode

    subgraph full_mode [Full-File ASR]
        direction TB
        ff_cache{Full-file\ncache hit?}
        ff_cache -->|Hit| ff_use[Use cached ASR]
        ff_cache -->|Miss| ff_infer[infer_asr on full audio]
        ff_infer --> ff_store[Cache full result]
        ff_store --> ff_use
    end

    partial_mode --> inject
    full_mode --> inject

    inject["inject_utr_timing()\nExact-subsequence fast path,\nelse global DP"]
    inject --> result([Return updated CHAT + UtrResult])

Rerun hardening rules

align does not blindly trust existing %wor timing on reruns. Several regression-driven safeguards now keep stale timing shapes from being refreshed back into the output:

1. Cheap %wor reuse is health-checked first. Existing %wor timing is reused only when the word distribution already looks plausible. Rerun falls back to fresh FA instead of reuse when:

   • any %wor word is near-zero (< 40 ms)
   • a 3+-word utterance has one %wor word consuming more than 40% of the utterance span
   • the last %wor word already overruns the utterance boundary or other reuse-shape invariants fail

2. Gap healing only bridges small gaps by default. Under WordGapHealing::Heal, the default, Batchalign may extend a word to the next word’s start to remove tiny pauses; pass --pauses to keep each word’s own end instead. Ordinary smoothing only applies to plausibly small internal gaps (currently <= 1000 ms). Larger gaps are treated as real pauses or mistracks and are left visible unless a more specific rerun-healing rule applies.

3. Gap healing treats boundary-sensitive seams specially. Several traced rerun bugs showed that some words already have the right FA timing before postprocess, then become dominant only after smoothing, while others need a targeted heal:

   • merged compound fillers like &-you_know are not stretched forward a second time after injection merges their split FA parts
   • ordinary lexical words are not stretched into a following timed filler span such as &-um when that bridge would make the lexical word dominate the utterance
   • timed fillers are likewise not stretched across a following pause when that smoothing would make the filler itself dominate the utterance
   • a near-zero lexical word may still bridge to the following filler start when that heal stays below the same 40% utterance-share plausibility cap
   • if a collapsed lexical word already touches an adjacent word boundary, continuous mode may rebalance that shared boundary so the lexical word reaches the 40 ms floor without collapsing the neighboring span in turn; this now applies when borrowing from either the following word or the preceding word, and for both fillers and ordinary lexical words

4. Rerun clamping is selective. Fresh FA timings are not clamped to narrow provisional UTR hints, and small final-word overruns can heal instead of being chopped back to a near-zero tail. This prevents reruns from preserving stale narrow bullet windows that were only ever estimates.

5. Prior-boundary rebuilding is an explicit v0.4.0 research projection. The default --existing-wor-boundaries preserve retains the compatibility behavior above. rebuild-from-evidence instead treats earlier %wor and main-tier boundaries as revisable output: it keeps admitted word extents and rebuilds the main bullet from their minimum/maximum hull. This flag does not change FA raw-evidence cache keys and cannot authorize inference. Use it with --require-media-cache and --debug-dir for controlled replay. It can reveal real conflicts between adjacent utterance boundaries; a structurally wider word hull is not by itself proof that its acoustic boundaries are correct.

   This option does not force new evidence resolution. If every utterance qualifies for the reusable-%wor fast path, rebuild reconstructs main-tier bullets from those existing admitted word timings and does not replay raw FA cache entries. A controlled raw-evidence comparison must use an input whose intended groups actually reach evidence resolution, then confirm each sidecar’s evidence source.

6. The default is preserve-cross-speaker: cross-speaker overlap is ordinary conversation and is left alone. --end-overlap-policy governs same-speaker (and, under clamp-all-adjacent, additionally cross-speaker) end overlap. Same-speaker overlap is resolved BY SPEAKER STREAM, not by file adjacency (2026-09-01 review, item 15): each speaker’s own bulleted utterances, in file order, are paired and resolved consecutively WITHIN THAT SPEAKER’S OWN STREAM, skipping any intervening other-speaker line rather than letting it break the pairing. This runs UNCONDITIONALLY, under either policy value: E704 (CLAN 133, a speaker may not overlap themself) is defined on the speaker’s own sequence, not on physical line adjacency, so an ordinary A-B-A dialogue must not hide a same-speaker overlap from resolution. A pair is resolved from MEASURED word timings, never guessed, into one of three cases:

   • The earlier utterance’s last measured word already ends before the next utterance starts: only the bullet’s inherited coverage overshot, so the bullet end moves back to the word; no word moves, no review is needed.
   • The two utterances’ words do not themselves overlap: both bullets take their measured word-hull edges instead of an arbitrary clamp; no word moves, no review is needed.
   • The two utterances’ words genuinely overlap in time (or the next utterance has no measured word): the bullet is clamped to the next utterance’s start AND every word past that bound is clamped with it, and the decision is flagged for review, since this is a real conflict between segmentation and FA evidence that only a person can adjudicate. clamp-all-adjacent ADDITIONALLY applies the same three-way resolution to every PHYSICALLY adjacent pair, cross-speaker included, instead of leaving cross-speaker overlap alone; it cannot undo the speaker-stream resolution above, since every resolution only SHRINKS the pair it touches, so a pair already resolved there satisfies this pass’s own overlap check and is silently skipped. Neither value relaxes start-order enforcement or changes raw FA cache identity.

7. Execution shape does not change the declared projection. The same prior-boundary, optional-repair, and end-overlap policies now apply whether a run performs fresh injection, reuses every %wor, or resolves no FA groups, and %wor (when requested) is always written AFTER this resolution runs, never before, on every path (fresh alignment, the all-reusable fast path, and per-utterance partial reuse folded into the same write). Optional repair always runs before final monotonicity enforcement, and repair’s own boundary-averaging step (--bullet-repair) uses the SAME three-way resolution on measured hulls, so a small overlap it splits can only move into a bullet’s own inherited coverage, never into a real word; where the hulls themselves overlap, it clamps bullet and words together exactly as the main resolution does. This is a consistency guarantee, not a recommendation to enable the experimental repair flag.

The practical effect is that reruns now prefer fresh FA over stale reuse whenever the old timing distribution already looks suspicious, and postprocess is more conservative about turning real pauses/fillers into dominant words.

Options

Path options (shared with all processing commands)

Alignment options

Both UTR fraction options are validated before a command is constructed: non-finite values and values outside the closed interval 0.0 through 1.0 are rejected by the CLI and by configuration deserialization. | --bullet-repair | off | Post-FA bullet repair for timing violations (experimental) | | --review-level {none,low-confidence,all} | none | Legacy compatibility option. All values now leave CHAT free of %xalign/%xrev; omit it in new scripts. |

What changes in the .cha file

• %wor tier added or replaced with word-level timestamps (word ·start_end·)
• Utterance-level bullet times (·start_end·) updated (see below for how)
• Existing %mor and %gra tiers are preserved and untouched
• The audio file is read but never modified

Research evidence without CHAT clutter

%wor deliberately stores only display words and timing bullets. It cannot represent model score, cache/reuse source, or the provenance chain of a timing that was clamped, derived, or repaired. For an alignment experiment, pass --debug-dir DIR; a successful run then writes DIR/<stem>_fa_evidence.json alongside the ordinary debug artifacts. For a bare input filename, <stem> is the familiar file stem. If the submitted filename contains directories, Batchalign appends a short digest of that full identity so equal basenames from different corpus branches cannot overwrite one another.

Version 0.3.0 writes evidence schema version 2, version 0.4.0 schema version 3, and the release after 0.4.4 schema version 4, which adds a flat dropped_word_timings section listing every word timing the run measured and then discarded (with the speaker, utterance, tier, word position, measured span, and the bound it exceeded). That section is always present, and empty when nothing was discarded. All of them record the selected engine and build/model version, the cache key and evidence source for every group (wor_reuse, cache, or inference), stable word identifiers, pre-injection timings, Wave2Vec-family model scores when available, complete start/end provenance chains, and every typed decision that later clamped or removed timing. Those decisions remain in the JSON while CHAT output contains no review-tier projection. A model score is evidence emitted by the aligner, not a calibrated probability that a boundary is correct. Schema 3 additionally records stable utterance ordinals beside the input-AST line indices for numeric monotonicity effects; this lets a consumer survive an inserted provenance header without attaching the decision to the preceding utterance. Schema version 3 does not yet record the final per-word timings after post-processing; use the resulting CHAT for those final bullets and do not infer a complete repair history from the sidecar.

An enabled evidence dump is fail-closed: if Batchalign cannot create or write the requested sidecar, the job reports a persistence error instead of silently finishing without the research artifact.

When untimed utterance recovery uses Rev, the same debug directory also gets one or more *_rev_evidence.json sidecars. They record the exact prepared media, provider presentation, raw cache key/outcome, request identity, and named UTR projection revision. A partial-window run keys each filename by its raw evidence identity so several windows cannot overwrite one another.

How utterance bullet times are set

Utterance bullet timing goes through two stages and the result depends on whether this is the file’s first alignment or a re-alignment.

First alignment (UTR → FA):

1. UTR runs first, setting a provisional timing hint on each untimed utterance. These hints are rough estimates, they come from a global DP alignment of ASR tokens against transcript words and serve as grouping windows for the FA step. They are not written to the output.
2. FA runs within those windows and aligns each word individually.
3. After injection, each utterance bullet is replaced with the span derived from the FA word timings (first aligned word start → last aligned word end). This is the self-healing property: valid FA word timings produce a valid utterance bullet by construction, regardless of how accurate the UTR hint was.

Re-alignment, default preserve policy (file already has FA word timings):

If the file already has utterance bullets set by a previous FA run (or hand-linked by an annotator), the bullet is expanded but never shrunk:

• The new bullet covers min(word_start, existing_start) → max(word_end, existing_end).
• This preserves timing coverage around fillers (&-uh), pauses, gestures (&=laughs), and other elements that FA cannot align but whose timing was already captured in the original bullet.

Re-alignment, experimental v0.4.0 rebuild-from-evidence policy:

• Admitted word extents are not clamped to the prior authoritative bullet.
• The main bullet is replaced by the exact minimum-start/maximum-end hull of the admitted word evidence.
• The raw FA cache key remains unchanged, so a cache-required comparison can vary this projection without rerunning the model.
• A later monotonicity pass applies the selected --end-overlap-policy, resolving each same-speaker pair – by that speaker’s OWN stream, not file order, so an intervening other-speaker line never hides the pair – (and, under clamp-all-adjacent, additionally each physically adjacent pair, cross-speaker included) from measured word hulls into one of three cases (see above); the default, preserve-cross-speaker, leaves a cross-speaker pair alone entirely. A genuine word conflict remains explicit evidence for adjudication; do not equate CHAT validity or word containment counts with boundary accuracy.

FA failure fallback:

If FA produces no aligned words for an utterance (audio quality too poor, utterance skipped by the engine), the UTR hint is kept unchanged and written as the utterance bullet. This is the safe fallback: approximate timing is better than no timing.

The following diagram shows the decision logic inside update_utterance_bullet() (fa/mod.rs):

flowchart TD
    start(["After FA word injection"]) --> any_words{"Any FA words\naligned?"}
    any_words -->|No| keep_existing["Keep existing bullet\n(UTR hint or authoritative)"]
    any_words -->|Yes| source_check{"Existing bullet\nsource?"}
    source_check -->|"No bullet"| set_word_span["Set bullet =\nword span\n(first start → last end)"]
    source_check -->|"UTR hint\n(provisional)"| overwrite["Overwrite with word span\n(UTR estimate → FA precision)"]
    source_check -->|"Authoritative\n(hand-linked or prior FA)"| boundary_policy{"Prior-boundary policy?"}
    boundary_policy -->|preserve| union["Union compatible coverage\nmin(word_start, existing_start)\n→ max(word_end, existing_end)"]
    boundary_policy -->|rebuild-from-evidence| exact_hull["Replace with exact\nfresh word hull"]
    keep_existing --> result(["Utterance bullet written"])
    set_word_span --> result
    overwrite --> result
    union --> result
    exact_hull --> result

Gotchas

@Media: unlinked is not an error. unlinked means the transcript exists but utterances have not yet been aligned to timestamps, it is the normal pre-alignment state. align is precisely the command that creates those links. The audio file is still resolved and used normally. When an alignment run produces timing evidence, its output consumes the unlinked status before writing the file. A pass-through file, or a run that produces no timing evidence, preserves the status. Timed output is refused if @Media is missing, ambiguous, unusable, or carries a contradictory status.

Re-aligning an already-aligned file does not shrink utterance bullets under the default preserve policy. If an utterance already has a bullet from a previous FA run or from hand-linking, the new bullet will cover at least as wide a span as the original. This is intentional: the original bullet may cover fillers, pauses, and gestures at the edges of the utterance that FA itself cannot align (because they produce no acoustic signal the aligner recognises). The union policy ensures that re-running align on the same file is safe and idempotent. The experimental rebuild-from-evidence policy deliberately does not make that guarantee; use it only when testing whether prior boundaries are stale, with evidence retention and output comparison.

Audio must be visible to the execution host. With --server, the server resolves @Media against its own filesystem. Paths that are valid on your machine may not be valid on the server. Use --media-dir to point to a server-visible path, or use the server’s media_mappings configuration.

--utr-strategy global is the default behavior anyway. Since the auto routing currently always returns GlobalUtr (see §“UTR strategy selection”), passing global explicitly produces identical behavior. If you see timing regressions and want to try the two-pass overlap-aware mechanism, use --utr-strategy two-pass: that’s the only way to reach it today.

For large re-run lists, split the list into batches and submit each batch as a separate batchalign3 align --file-list <batch> invocation rather than passing thousands of files at once. Each invocation gets a fresh worker pool, which keeps memory pressure predictable.

Related documentation

• Forced Alignment, algorithm details, prerequisites, media resolution
• %wor Tier, %wor tier semantics and format
• Overlapping Speech, CA overlap markers and +< encoding
• Command I/O: align, I/O patterns, server vs local, mutation behavior
• Command Flowcharts: align, full architecture flowchart
• Dynamic Programming, Hirschberg alignment algorithm
• Incremental Processing, --before flag mechanics

This page last changed: 2026-09-16 (commit 197c81e6). The whole book last changed: 2026-09-16 (commit 34d249d8).

transcribe

Status: Current Last updated: 2026-09-16 09:47 EDT

Create a new CHAT transcript from audio files using automatic speech recognition (ASR). Produces .cha files alongside or in a separate output directory. Never modifies the input audio.

Quick start

# Transcribe a single recording, output alongside input
batchalign3 transcribe interview.wav

# Transcribe all audio files in a directory
batchalign3 transcribe recordings/ -o transcripts/ --lang eng

# Auto-detect language (useful for bilingual/code-switched audio)
batchalign3 transcribe bilingual.wav -o out/ --lang auto

# Transcribe with paid pyannoteAI Precision-2 diarization, the default
batchalign3 transcribe interview.wav -o out/ --asr-engine whisper --diarization enabled

# Keep all audio local and use the TalkBank-pinned Pyannote model
batchalign3 transcribe interview.wav -o out/ --diarization enabled --speaker-engine pyannote

# Use the remote server
batchalign3 --server http://your-server:8001 transcribe corpus/ -o out/ --lang eng

Dedicated diarization defaults to the pyannoteAI Precision-2 cloud model. Set its API key in the environment:

export BATCHALIGN_PYANNOTE_API_KEY="your-key"

PYANNOTE_API_KEY and BATCHALIGN_PYANNOTE_KEY are also accepted. For compatibility with existing installations, BA3 also reads engine.pyannote.key from the [diarize] section of ~/.batchalign.ini. The environment variables take precedence.

pyannoteAI receives the recording through its temporary-media API. Its use can incur account charges, so confirm the account plan and the recording’s data-use or IRB rules before running it. Job output is not written into the API key configuration.

The local --speaker-engine pyannote alternative uses the public, ungated TalkBank-pinned talkbank/dia-fork pipeline plus its pinned segmentation and embedding dependencies, downloaded anonymously on first use. It runs inference locally and does not use the pyannoteAI API key. --speaker-engine nemo is a second local alternative that avoids the paragraph below entirely.

--speaker-engine pyannote also fetches one UNPINNED, currently GATED artifact: a PLDA calibration model. pyannote.audio’s pipeline class loads it unconditionally during construction, and the released config does not override it, so the class’s own default applies: the gated pyannote/speaker-diarization-community-1 repository. A machine with no accepted terms and no Hugging Face token fails on first use naming that repository. The fix is a token, checked in this order: ~/.batchalign.ini [auth] hf_token, then Hugging Face’s own resolution (HF_TOKEN, or the token saved by hf auth login); accepting the repository’s terms at https://huggingface.co/pyannote/speaker-diarization-community-1 is required either way. Full detail: diarize.

A Hugging Face token is NOT relevant to the default command shown above, which uses --speaker-engine pyannote-ai and never reaches this local path.

The standalone diarize command is intended for producing anonymous .turns.json evidence for an existing transcript. It defaults to local Pyannote but can explicitly select paid pyannoteAI Precision-2; both surfaces share the same raw/derived speaker-evidence cache. Integrated diarized transcription projects speaker evidence onto timed ASR words before utterance segmentation and CHAT construction; it does not require a later chatter rediarize pass.

Rev and speaker evidence caching

Rev.AI transcription now caches the raw provider-shaped transcript before BA3 token conversion and post-processing. A normal warm run checks and validates that evidence before submitting anything to Rev, so it avoids another Rev call. Keeping raw monologues, elements, punctuation, timings, confidence, and resolved language also lets BA3 post-processing experiments replay the same service output locally.

With --diarization enabled, BA3 durably caches both the backend-shaped speaker evidence and the normalized turns used by the transcribe pipeline. For pyannoteAI, retained raw evidence includes the completed job ID, full output object, and warning. Repeating the same recording with the same speaker backend, expected speaker count, preparation recipe, and model revision replays validated turns without calling the diarization backend again. Copies and renames of byte-identical recordings share the entry.

Raw evidence and derived turns have separate revision identities. A later BA3 release can change how provider output is converted to speaker intervals and recompute those intervals locally from the retained response. That kind of algorithm experiment does not upload the audio or incur another pyannoteAI inference charge.

This is particularly important for the paid pyannote-ai default. A corrupt entry fails visibly and does not fall through to another paid call. Concurrent identical files in one server are coalesced so only the first miss runs inference.

For a replay experiment that must not turn a missing Rev or speaker entry into a service call, require the cache explicitly:

batchalign3 --require-media-cache transcribe interview.wav -o out/ \
  --asr-engine rev --diarization enabled

A raw-evidence miss then fails visibly before service inference is authorized. If raw speaker evidence exists but normalized turns do not, BA3 may still recompute those turns locally. The flag applies to cache-backed stages; it does not cache or suppress ordinary local ASR engines.

To run a deliberate fresh experiment, use the global override:

batchalign3 --override-media-cache transcribe interview.wav -o out/ \
  --diarization enabled

The fresh results replace the matching cache entries. The override can incur new Rev and pyannoteAI charges. Other ASR engines are not yet cached in ordinary transcribe runs. See Caching for exact invalidation rules and limitations.

Pipeline

flowchart TD
    start([transcribe invoked]) --> resolve[Resolve audio file]
    resolve --> ensure_wav[ensure_wav: convert if needed]

    ensure_wav --> diarize_check{--diarization?}
    diarize_check -->|"enabled"| transcribe_s["Command: transcribe_s\nASR + dedicated speaker relabeling\nRev or Whisper"]
    diarize_check -->|"auto/disabled\n(default)"| transcribe_m["Command: transcribe\nDefault path\nRev labels used directly when present"]

    transcribe_s --> engine_check
    transcribe_m --> engine_check

    engine_check{--asr-engine?}
    engine_check -->|whisper| whisper[Whisper local ASR]
    engine_check -->|whisper_hub| whisper_hub["HF Whisper fine-tune\n(per-language model_id)"]
    engine_check -->|rev| rev_key["Hash provider media + Rev request semantics"]
    engine_check -->|"whisperx, whisper_oai"| refused["Refused: engine not implemented"]
    engine_check -->|"whisper_rs, tencent, aliyun, funaudio or paraformer, qwen"| other_asr["Other engines\nprovider adapter pairs each unit\nwith its own timestamp"]

    rev_key --> rev_cache{"Validated raw Rev-evidence cache"}
    rev_cache -->|hit| rev_convert["Convert retained raw Rev transcript"]
    rev_cache -->|miss/forced refresh| rev_call["Authorized Rev language-ID/submit/poll"]
    rev_call --> rev_store["Validate + required durable commit"]
    rev_store --> rev_convert
    rev_convert --> asr_tokens

    whisper --> asr_tokens
    whisper_hub --> asr_tokens
    other_asr --> asr_tokens

    asr_tokens["Raw ASR tokens\nword + start_s + end_s + optional speaker + confidence"]
    asr_tokens --> convert["convert_asr_response()\nGroups tokens by speaker label"]
    convert --> dedicated_check{"--diarization enabled?"}
    dedicated_check -->|No| postprocess
    dedicated_check -->|Yes| speaker_key["Hash source bytes + semantic request"]
    speaker_key --> speaker_cache{"Validated derived-segment cache"}
    speaker_cache -->|hit| retain_check
    speaker_cache -->|derived miss| speaker_raw{"Validated raw-evidence cache"}
    speaker_raw -->|hit| speaker_normalize["Versioned local normalization"]
    speaker_normalize --> speaker_store_derived["Commit derived segments"]
    speaker_store_derived --> retain_check
    speaker_raw -->|raw miss/forced refresh| speaker_v2["execute_v2(task=speaker)\nprepared audio → backend evidence\npyannoteAI Precision-2 by default"]
    speaker_v2 --> speaker_store["Validate + commit raw evidence\nthen derived segments"]
    speaker_store --> retain_check{"--debug-dir?"}
    retain_check -->|Yes| retain_turns["Write same-job canonical speaker turns\nwith typed backend provenance"]
    retain_check -->|No| postprocess
    retain_turns --> postprocess

    subgraph postprocess ["Rust post-processing: process_raw_asr()"]
        direction TB
        p1[1. Compound merging] --> p1check{lang=yue?}
        p1check -->|Yes| p2["2. Cantonese normalization\nonce per monologue\nOpenCC + domain replacements"]
        p1check -->|No| p3
        p2 --> p3
        p3[3. Multi-word splitting\nsplit tokens with spaces, interpolate timestamps]
        p3 --> p4[4. Number expansion\ndigits → word form]
        p4 --> p5[5. Long-turn splitting\nchunk at >300 words]
        p5 --> p6[6. Retokenization\npunctuation-based utterance splitting]
        p6 --> p7[7. Disfluency replacement\nfilled pauses + orthographic from per-language wordlists]
        p7 --> p8[8. N-gram retrace detection\nwrap repeated n-grams in `<...> [/]`]
    end

    postprocess --> speaker_apply{Dedicated speaker\nsegments present?}
    speaker_apply -->|Yes| project["Project segments onto timed ASR words\nby greatest summed overlap\nSplit chunks at speaker changes"]
    speaker_apply -->|No| utseg_check{"with_utseg?\ndefault: true"}
    project --> utseg_check

    utseg_check -->|Yes| run_utseg[process_utseg_with_evidence\nBERT-based re-segmentation]
    utseg_check -->|No| mor_check{"with_morphosyntax?\ndefault: false"}

    run_utseg --> build_chat["build_chat → ChatFile AST\nHeaders, participants, %wor tiers"]
    utseg_check -->|No| build_chat
    build_chat --> mor_check
    mor_check -->|Yes| run_mor[process_morphosyntax\nPOS + lemma + depparse]
    mor_check -->|No| merge_check

    run_mor --> merge_check{--merge-abbrev?}
    merge_check -->|Yes| merge[merge_abbreviations]
    merge_check -->|No| output

    merge --> output[Serialize → .cha output]
    output --> done([Output .cha file])

Utterance boundary detection

transcribe always does utterance splitting before CHAT output is written. There are two paths:

• eng, cmn, zho, yue: dedicated pre-CHAT utterance models
• all other languages, punctuation-based splitting in Rust

Utterance segmentation also runs as a second pass over the built CHAT, and that pass needs a segmenter. A language in the first list has one. A language in the second does not, unless you pass --utseg-fallback-stanza, and a run that asks for utterance segmentation in such a language is refused when the job is planned, before any ASR runs. That matters because ASR is the expensive part: the refusal used to happen at the very end of the pipeline, after the whole transcription had been produced and paid for, and it named the worker’s wire format (invalid utseg V2 result) rather than the missing model. So a Spanish, French, Japanese or Catalan transcription either authorizes the fallback:

batchalign3 transcribe corpus-spa/ -o out/ --lang spa --utseg-fallback-stanza

or is told immediately that it has no segmenter.

With --lang auto the language is not known until ASR has returned, so for that case alone the same refusal necessarily happens after ASR rather than before it.

For the FunASR engines (funaudio, paraformer), Chinese ASR tokens are single characters (Latin words stay whole), each with its own timestamp, and the provider’s punctuation is not used as a boundary. Builds before 2026-09-15 paired Paraformer clauses with per-character timestamps, which mistimed whole transcripts; re-run Paraformer transcripts made with them. Details: ASR token pipeline.

For a supported language, normal transcription applies the utterance model again after CHAT construction. This second pass can refine boundaries using the completed main-tier context. Standalone utseg remains available for re-segmenting an existing CHAT transcript without transcribing media again.

With --wor, a post-CHAT split that has complete timing for all partitioned word tiers receives a main-tier timing bullet on every child, derived from that child’s own word span. If complete child timing is unavailable, no child receives a main-tier bullet at all. The parent’s bullet measures the whole parent, so its start is where the first child began and its end is where the last one finished, and writing it onto any one child would present a time nobody measured as a measured one. The single exception is a split that kept one child, where the parent’s span is still exactly that child’s. This is a timing-preservation rule, not a claim that the model’s segmentation is the only acceptable CHAT segmentation.

Options

Path options

ASR and language options

Why --num-speakers has no short flag

-n was a short form for it until 2026-08-19. It was removed because -n reads as a job or worker count nearly everywhere it appears, pytest -n most of all, and this CLI has its own --workers beside the make -j and xargs -P conventions. A caller reaching for parallelism was therefore reconfiguring DIARIZATION, silently.

That is not a hypothetical. On 2026-08-19 a re-transcription of four sessions was submitted as -n 4 meaning four workers. Four speakers would have over-diarized those sessions against the 361 siblings in the same delivery, which were built with two.

How visible would that have been? Less than nothing, and more than an earlier draft of this page claimed. The run SUCCEEDS, and no warning is printed. The effect is visible if you look: @Participants and the @ID headers list only the speakers that actually occur in the output, so an over-diarized transcript lists more of them and carries extra speaker tiers. What is genuinely absent is the CAUSE. The requested count is recorded nowhere in the file, so a reader seeing four speakers cannot tell an over-diarized run from a session that really had four.

An UNDER-count is not absorbed either. The count is passed to Rev.AI and to the dedicated diarizer, and the local pyannote and nemo engines produce exactly the number they are given, so a count below the real number of voices merges voices together. (An earlier version of this page said the pipeline took max(num_speakers, detected); no such step exists.) Only Rev.AI can infer the count, with --auto-speakers.

A count of 1 is refused, not obeyed. With --diarization enabled, a count of 1 asks a diarizer to separate the speakers of a recording asserted to hold one, which is a contradiction rather than a request. The job is refused at submission:

diarization was requested with a speaker count of 1, which asks a diarizer to separate speakers in a recording asserted to have one. Pass the real count (2 or more); or omit diarization, for a single-speaker recording; or pass auto_speakers to have the count inferred, where the ASR engine supports it.

So with diarization the count is 2 or more, or it is omitted and the number is detected (on Rev.AI, --auto-speakers). One is neither, and it is refused rather than silently treated as detection. It used to be obeyed: the count reached the diarizer, which returned a single track, which is why --diarization enabled runs came back with one PAR0.

Speaker codes are also per recording. Each file is diarized on its own, so PAR0 in one transcript and PAR0 in another need not be the same person, even when a corpus has fixed participants; see diarize.

-n is now a hard error, which is the point. A caller who meant parallelism goes looking and finds --workers; a caller who meant speakers finds --num-speakers. Both land where they intended, and neither is silently misread. On every command but diarize the flag defaults to 2, so most callers never type either; diarize has no default, because omitting it and letting the engine auto-detect is the recommendation there.

Note that --workers has its own trap, documented on the flag itself: it applies to NEW daemons, and does not change the parallelism of a daemon that is already running and being reused.

ASR engines

Every engine is reachable through the single --asr-engine flag. This list is generated from the engine set itself, as is the one --help prints.

# Mandarin with Paraformer.
batchalign3 transcribe Mandarin_mp3 -o out --lang zho --asr-engine paraformer

The engine NAME goes to --asr-engine. --engine-overrides takes a JSON object of per-engine settings, and it is parsed while the command line is, so a name passed to it (--engine-overrides paraformer) is refused before anything runs, with --asr-engine paraformer named in the message rather than a JSON syntax complaint.

Speaker labeling and segmentation

This is the most common source of confusion with transcribe.

Rev.AI (default engine): Rev.AI returns speaker labels as part of its ASR response. These labels are always applied, you get multi-speaker output without passing --diarization enabled. Passing --diarization enabled explicitly makes dedicated diarization authoritative and ignores Rev’s speaker projection. The default dedicated engine is pyannoteAI Precision-2.

Whisper-based engines (--asr-engine whisper, whisper_hub, whisper_rs): these engines produce no speaker labels. Without --diarization enabled, all utterances are attributed to a single default speaker. Pass --diarization enabled to run a dedicated speaker stage that assigns speaker identities.

--diarization auto (the default) = disabled dedicated stage. Equivalent to BA2’s --nodiarize. The BA2 help text claiming Rev.AI ignored --diarize was stale, the actual BA2 transcribe_s pipeline wiring ran the dedicated stage.

Dedicated diarization is integrated before utterance segmentation. BA3 first post-processes the timed ASR words, then assigns each timed word to the speaker with the greatest summed diarization overlap and splits prepared chunks where that label changes. The language-specific utterance model therefore sees the speaker boundaries and cannot merge across them. Untimed punctuation inherits the nearby timed label. Timed words in gaps take the nearest dedicated segment label. Once dedicated evidence exists, no word can re-enter the unrelated ASR label space and create a phantom participant. Diagnostics report contested words, unattested words, and inserted speaker boundaries.

Retaining the exact diarization turns used by transcription

For research, replay, or merge-pipeline evaluation, pass --debug-dir PATH with --diarization enabled. In addition to the other debug artifacts, BA3 writes one <audio-stem>.turns.json file containing the exact dedicated segments used to build that transcript. The artifact uses the same deterministic PAR coordinate system as the generated CHAT and records typed backend provenance, including batchalign3:pyannote_ai:precision-2 for the cloud default.

BA3 also writes a versioned *_speaker_evidence.json sidecar. It records the source digest, preparation revision, backend and expected-speaker request, model and normalization revisions, raw and derived cache keys, whether the run replayed derived evidence, re-normalized raw evidence, or inferred after a miss, the named segment-projection revision, and a versioned digest and count of the exact validated segments. It excludes machine-local source paths and credentials.

When this artifact is requested, failure to create or write it fails the file instead of silently discarding the evidence. With a remote server, PATH is on the server host; the CLI sends an absolute path.

Keep both sidecars, the run manifest, and generated CHAT together: the causal record explains where the evidence came from, while the turns artifact is the exact normalized projection consumed downstream.

For Rev ASR, the same --debug-dir run also writes a versioned, collision-resistant *_rev_evidence.json sidecar. It records the source and provider-media digests, preparation recipe, exact multipart presentation, language and speaker request, model/request revisions, raw cache key, cache outcome, and local projection revision. This sidecar is also fail-closed when requested and excludes the Rev credential and machine-local source path.

For languages with a TalkBank utterance-boundary model, BA3 also writes a versioned *_pre_chat_utseg_evidence.json sidecar. Normal model-backed transcription writes a separate *_post_chat_utseg_evidence.json sidecar for the second pass over completed main tiers. Keeping the phases separate prevents an experiment from confusing boundaries over timed ASR chunks with later boundaries over main-tier words.

Each item records the exact input words and applied group assignments. A boundary-model result additionally records its model ID and revision plus one evidence state per word: raw action, action after adjacency policy, and sentence-end probability, or an explicit normalization-omission or short-input state. Constituency-tree projection and compatibility assignments without model evidence are separate source variants. BA3 refuses a worker result whose assignments or evidence do not exactly parallel the input words. As with the Rev and speaker causal records, an enabled utseg evidence write is atomic and fail-closed.

The current boundary model is lexical and contextual. It does not itself receive waveform energy, pause duration, pitch, diarization overlap, or CHAT retrace structure. The sidecar makes its contribution inspectable so research code can compare it with those signals without rerunning the model.

--lang auto behavior

With --asr-engine whisper, --lang auto omits the language parameter from Whisper’s generation kwargs, letting the model detect the spoken language from the audio. The multilingual openai/whisper-large-v3 model is always used with auto: language-specific fine-tuned models are bypassed because they are trained for a single language.

With Rev.AI, --lang auto submits a true auto-language request to the Rev.AI API. Note that Rev.AI auto-detect and explicit --lang eng can produce different punctuation, diarization, and turn boundaries from the provider.

What gets created

A new .cha file per audio input (audio extension replaced: foo.wav → foo.cha). Contains:

• a structured provenance @Comment ([fc-ba3 transcribe | ...]) plus a human-readable warning, fc-ba3 <build identity>, ASR engine <engine>. Unchecked output of ASR model, DO NOT USE., carrying the build identity, the actual ASR engine name (with the models that produced the text in parentheses, in the same form asr_model= uses), and DO NOT USE for unchecked model output. A run that reported no models, such as one replaying legacy evidence, carries no parenthetical at all rather than naming what was requested. Re-transcribing replaces an earlier warning of ours, including the older Batchalign <version>, ASR Engine <engine>. form
• @Languages, @Participants, @ID headers
• Utterance lines with timing bullets
• %wor tier (if --wor is set)

No %mor or %gra tiers are created by transcribe. Run morphotag afterwards if morphosyntactic analysis is needed.

Gotchas

Rev.AI skip_postprocessing: For English and Spanish (the only languages Rev.AI’s API documents the parameter as supporting), Rev.AI is called with skip_postprocessing=true. The hint table is in crates/batchalign/src/revai/preflight.rs::skip_postprocessing_hint, which matches Rev.AI’s own 2-letter codes "en" | "es" and returns None for everything else. The flag is true because CHAT records spoken form ("eighty percent", "seventeen year old"); leaving it off causes Rev.AI to apply ITN and return main-tier-illegal forms like "80%" / "17-year-old". For languages outside the en/es support pair, no flag is sent (the parameter is a no-op there per Rev.AI’s docs), and BA3’s downstream post-processing handles spoken-form normalization.

A recording with no recognized words fails; it does not produce an empty file. If the ASR engine returns no words, or post-processing keeps no utterance from the words it did return, or every token that reaches CHAT assembly is a terminator or separator, the job fails and says which of those three happened. Until 2026-09-16 the first of these wrote a transcript of headers and nothing else and reported the job completed, which is indistinguishable from a correct transcript of a silent recording. If the recording does contain speech, the usual causes are the wrong --lang for the audio or an engine that has no model for it.

--server requires server-visible audio. With --server, the server resolves audio paths on its own filesystem. Paths valid on your machine must also be reachable from the server, or you must use a shared media mount.

Memory on developer machines. Each Whisper model instance uses 2-15 GB. For large corpus runs (more than a handful of files or >1 GB audio total), prefer a dedicated server with substantial RAM (via --server) over a developer laptop, and always pass --workers 1 for local smoke tests.

Related documentation

• Rev.AI Integration, API key setup, engine behavior
• Cantonese Engines, Tencent, Aliyun, FunASR engines
• Utterance Segmentation, post-ASR BERT utseg
• Command I/O: transcribe, I/O patterns and mutation behavior
• Command Flowcharts: transcribe, full architecture flowchart
• ASR Token Pipeline, ASR post-processing details

This page last changed: 2026-09-16 (commit 197c81e6). The whole book last changed: 2026-09-16 (commit 34d249d8).

morphotag

Status: Current Last updated: 2026-09-05 04:22 EDT

Add morphosyntactic analysis (%mor POS/lemma tiers and %gra dependency tiers) to existing CHAT transcripts. Text-only, no audio involved.

Language is per-file, not job-level

Morphotag has no --lang flag. Every input file’s processing language is read from that file’s own @Languages: header at the start of the per-file pipeline (pipeline/morphosyntax.rs::resolve_per_file_lang). A single morphotag invocation can therefore process a heterogeneous corpus, English files routed to Stanza English, Spanish files to Stanza Spanish, Cantonese files to Stanza Chinese with the PyCantonese POS overlay, etc., all from one command. The job’s wire-level language spec is LanguageSpec::PerFile, surfaced on the dashboard and JSON API as "per-file". No English placeholder is ever stored.

If a file’s @Languages: header is missing, malformed, or names a language that Stanza does not support, morphotag does not silently fall back to English. The file is reported in the job’s status with a typed error and returned unchanged.

Quick start

# Tag one file in place, language is read from the file's @Languages header
batchalign3 morphotag file.cha

# Tag a corpus directory
batchalign3 morphotag corpus/ -o tagged/

# Retokenize main lines to match UD tokenization (expands contractions)
batchalign3 morphotag corpus/ -o out/ --retokenize

# Use remote server
batchalign3 --server http://your-server:8001 morphotag corpus/ -o out/

# Deliberately analyze CA transcripts while preserving @Options: CA
batchalign3 morphotag corpus/ -o out/ --ca-policy analyze

To “override” the language, edit the file’s @Languages: line. There is no CLI shortcut, and there cannot be, because a single command may span many languages.

Pipeline

All files are batched together through the batched-text-infer pool (crates/batchalign/src/runner/dispatch/infer_batched.rs handles the recipe-driven dispatch family; ReleasedCommand::Morphotag is the discriminant used by the planner at crates/batchalign/src/runner/dispatch/plan.rs). Utterances are pooled across all files, grouped by language, and dispatched to a Stanza worker per language group with semaphore-bounded concurrency. Repeated morphotag runs on the same input run the full Stanza pipeline again, text-NLP results are not cached (CacheTaskName at crates/batchalign/src/chat_ops/cache_key.rs:58 covers only ForcedAlignment and UtrAsr).

flowchart TD
    start([morphotag invoked]) --> parse[Parse all files → ASTs]
    parse --> clear[Clear existing %mor/%gra tiers]
    clear --> collect[collect_payloads\nPer-utterance word lists with language metadata]

    collect --> retok_check{--retokenize?}
    retok_check -->|Yes: --retokenize| stanza_retok[TokenizationMode::StanzaRetokenize\nStanza may split/merge words]
    retok_check -->|No: --keeptokens| preserve[TokenizationMode::Preserve\nKeep original tokenization]

    stanza_retok --> lang_check
    preserve --> lang_check

    lang_check{--skipmultilang?}
    lang_check -->|Yes| skip_non_primary[MultilingualPolicy::SkipNonPrimary\nSkip utterances in non-primary language]
    lang_check -->|No: --multilang| process_all[MultilingualPolicy::ProcessAll\nProcess all utterances regardless of language]

    skip_non_primary --> worker
    process_all --> worker

    worker[execute_v2(task='morphosyntax')\nprepared_text batch → Stanza NLP pipeline\nper-language semaphore-bounded dispatch]
    worker --> repartition[Repartition responses by file]
    repartition --> inject_results[inject_results → insert %mor/%gra tiers]

    inject_results --> before_check{--before path?}
    before_check -->|Yes| incremental[process_morphosyntax_incremental\nSkip NLP for unchanged utterances]
    before_check -->|No| full_inject[Process all utterances]

    incremental --> merge_check
    full_inject --> merge_check

    merge_check{--merge-abbrev?}
    merge_check -->|Yes| merge[merge_abbreviations]
    merge_check -->|No| validate

    merge --> validate[Alignment validation\n%mor word count must match main tier]
    validate --> done([Output .cha files])

Options

Path options

If you combine --file-list with in-place processing on a large corpus, do not expect the .cha files on disk to rewrite one by one during the run. morphotag batches and stages text-NLP work internally; the visible in-place file updates may land only when the current invocation finishes. For long repair runs where you want output to appear incrementally, split the file list into smaller chunks and run those chunks sequentially.

Morphotag options

There is no --lang flag. Each file’s processing language is read from its own @Languages: header. Passing --lang to morphotag is a clap parse error, the CLI surface deliberately rejects it. See the “Language is per-file, not job-level” section above for the rationale.

@Options: CA files pass through by default

Files whose header declares @Options: CA (Conversation Analysis mode) are passed through morphotag unchanged. The pipeline parses the file, detects the option, and serializes it back as-is, no %mor / %gra tiers are added, and any pre-existing %mor / %gra tiers are preserved verbatim. Provenance comments are not injected for these files.

This mirrors how align skips files with @Options: NoAlign. The mechanism is the option header plus the submitted typed CA policy; per-utterance content (CA prosody markers, pauses, &= events, etc.) does not influence the decision. --ca-policy analyze explicitly selects the normal morphotag pipeline for these files and retains the @Options: CA line in the result. This makes a historical corpus reconstruction reproducible without silently deleting or editing the source declaration.

What changes in the .cha file

• %mor tier added or replaced with POS tags and lemmas per word
• %gra tier added or replaced with dependency relations
• A provenance @Comment naming the Stanza models that ran, and counting any dependency relations that had to be repaired because Stanza produced a label outside Universal Dependencies (ud_repairs=, absent when there were none). See Provenance
• Main tier text may be retokenized when --retokenize is set
• Special @Options: dummy notation is auto-detected and preserved
• No audio is involved; this is a text-only transform

Language routing

The language for each file is read from its @Languages: header (first declared language). Individual utterances tagged with a [- lang] precode are routed to the appropriate language-specific Stanza model regardless of the file-level language. There is no CLI override, see the “Language is per-file, not job-level” section at the top of this page.

For Cantonese, files declared with primary @Languages: yue route to Stanza’s Chinese (zh) pipeline with a PyCantonese POS overlay applied after Stanza finishes (Stanza zh scores ~50% on Cantonese vocabulary; PyCantonese ~94%, only upos is replaced; lemma and dependency parse from Stanza are preserved). Mandarin files (zho / cmn) use Stanza zh without the PyCantonese overlay. See Cantonese language details and Mandarin.

See Language Routing.

--retokenize warning

--retokenize allows Stanza to split or merge words on the main tier to match UD tokenization (e.g. expanding “don’t” → “do n’t”). This may invalidate existing %wor timing bullets. If the file has already been aligned, re-run align after retokenizing.

Reading the server log

If you see WARN Stripped N Stanza control-token leak(s) ... lines in ~/.batchalign3/server.log, those are working-as-designed signals from a known-upstream-defect workaround firing, not errors. See the troubleshooting page section Stripped N upstream-library warnings for the full explanation and what to do.

L2 dispatch for code-switched words (default: on)

@s (code-switched) words are routed to secondary-language Stanza models and annotated with real POS tags, lemmas, and dependency relations, including proper handling of contractions (it's@s:eng → pron|it~aux|be) and phrasal verbs (wake@s up@s → verb|wake part|up with COMPOUND-PRT GRA deprel). This is the default behavior. Mandarin-marked words (@s:cmn / @s:zho) route through the Chinese zh morphosyntax path, and Cantonese-marked words (@s:yue) use the same secondary-dispatch surface as other supported Stanza languages. Unresolved or unsupported targets still fall back to L2|xxx.

To opt out and emit legacy L2|xxx placeholders (e.g. for reproducibility of older analyses), pass --no-l2-morphotag:

batchalign3 morphotag bilingual.cha --no-l2-morphotag

Validation. L2 dispatch has been validated at scale: across 19 language pairs and ~17K @s words, well above 99% dispatch to a secondary-language Stanza model on most pairs, with 100% dispatch on the majority of evaluated language pairs. The remaining cases fall back to L2|xxx.

Unsupported non-primary languages

morphotag only requires the primary @Languages code to be Stanza-supported. Files whose primary is not Stanza-supported are skipped with a typed diagnostic and never enter the pipeline.

When the primary IS supported, non-primary content in any language that Stanza does not support is processed cleanly with an L2|xxx fallback:

• [- UNSUPPORTEDLANG] whole-utterance precodes, the entire utterance is grouped under UNSUPPORTEDLANG, the worker partition routes that group to the fallback bucket (no Stanza dispatch), and every word in the utterance receives L2|xxx in %mor with no %gra relation emitted for those positions.
• @s:UNSUPPORTEDLANG per-word markers, the secondary L2 dispatch path for that span is short-circuited the same way; the host primary analysis is preserved and the @s token’s slot stays as L2|xxx.

Both fallbacks are graceful: the worker never crashes on an unsupported secondary, and other utterances in the same file (or other spans in the same utterance) that target supported languages continue to receive real morphology. The mechanism is a partition step in infer_batch (partition_groups_by_stanza_support) that splits each batch’s language groups into “dispatchable” and “fallback” before calling Stanza.

Example. German-English code-switching:

*EVA:   was ich jetzt machen möchte ist film@s studies@s .
%mor:   ... noun|film noun|study-Plur .     ← default (L2 dispatch on)
%mor:   ... L2|xxx L2|xxx .                 ← with --no-l2-morphotag

See also:

• L2 Morphotag: Per-Word Code-Switching Analysis , full design, merge algorithm, phrasal-verb diagram

Validation and repair for @s input

• Whole-utterance same-language runs written as word@s word@s ... are rejected by pre-validation (E255). The canonical CHAT form is [- lang], and chatter debug fix-s rewrites the qualifying whole-utterance pattern in place.
• Explicit @s:LANG words still dispatch to LANG even if LANG is missing from @Languages, but validation emits warn-only E254 so the header drift is visible. chatter debug fix-s appends those missing explicit languages to @Languages.
• chatter debug fix-s is a true no-op on already-correct files: it only rewrites a file when it can prove a [- lang] conversion or @Languages repair is needed.

When fix-s will and will not rewrite

The rewrite predicate is conservative on purpose: an incorrect [- LANG] insertion silently changes the language scope of an entire utterance, including fillers and nonwords. The predicate only fires when every word-bearing item in the utterance, words, fillers (&~, &-, &+), nonwords, AND retraced material, carries an explicit language attribution that resolves to the same target language. A single unmarked token (e.g. a filler &~dang3 with no @s: marker) blocks the rewrite, even if every other word would qualify.

When the rewrite fires, fix-s clears bare @s shortcuts from fillers and nonwords as well as from regular words. This is critical: a bare @s resolves relative to the surrounding tier language, so adding a [- LANG] precode without clearing the shortcut would flip the filler’s resolved language to the precode target. (A previous version of the tool skipped fillers and corrupted a corpus this way; the fix-s predicate now walks all word-bearing items.)

Failure modes

morphotag fails fast on engine failures rather than emitting partial output. When the Stanza worker reports a per-utterance error (model runtime error, Stanza output parse failure, protocol violation), the affected file is marked failed with a typed ItemErrors message naming the first few offending items and the total count. Other files in the same batch continue normally, one bad file does not poison the rest (BA2-parity multi-file semantics). The output .cha for a failed file is not written; there is no silent path where the job appears successful but the %mor tier is missing.

Note: items in languages Stanza does not support (code-switches into @s:<lang> for unsupported languages) are an intentional fallback, not a failure, those items keep their L2|xxx placeholders in %mor and the file still succeeds.

Related documentation

• Morphosyntax Pipeline, %mor/%gra format, Stanza model details
• Language Routing, [- lang] precodes, auto-detection, per-word routing limits
• L2 & Language Switching, @s annotation, code-switching
• Multi-Word Tokens, MWT expansion and --retokenize
• Command I/O: morphotag, I/O patterns and mutation behavior
• Command Flowcharts: morphotag, full architecture flowchart
• Incremental Processing, --before flag mechanics

This page last changed: 2026-09-16 (commit 197c81e6). The whole book last changed: 2026-09-16 (commit 34d249d8).

utseg

Status: Current Last updated: 2026-09-16 08:18 EDT

Re-segment utterance boundaries in an existing CHAT transcript. Text-only , no audio involved. The model selected per language is either a trained BERT per-word boundary classifier (eng / cmn,zho / yue) or, for other languages, Stanza constituency parsing where it is available.

transcribe already runs this same step at the end of every run (with_utseg = true is the default in the transcribe pipeline). The standalone utseg command is for already-existing corpora, files transcribed elsewhere, hand-typed transcripts, or older BA2 output, where utterances run on into long blobs and need to be split.

Quick start

# Re-segment a single file in place
batchalign3 utseg file.cha --lang eng

# Re-segment a corpus directory
batchalign3 utseg corpus/ -o segmented/ --lang eng

# Use the remote server
batchalign3 --server http://your-server:8001 utseg corpus/ -o out/ --lang eng

Pipeline

Each file is dispatched on its own, dispatch_utseg_job in crates/batchalign/src/execution/utseg.rs calls gateway.utseg_batch(&[one_file], lang) per file and writes that file’s result to disk before starting the next. (This replaced an earlier “pool everything across all files, batch through one worker, write at end” pattern, which lost the entire run’s work on a daemon redeploy mid-batch. The per-file shape limits a mid-run interruption to losing only files currently in flight.) Per-file concurrency is bounded by plan.kernel_plan.file_parallelism_hint (clamped to ≥ 1), the same heuristic as fa_pipeline.rs.

flowchart TD
    start([utseg invoked]) --> parse[Parse one file → AST]
    parse --> collect[collect_payloads\nExtract word sequences per utterance]
    collect --> worker[gateway.utseg_batch(&[file], lang)\n→ BERT assignments\nor Stanza constituency trees]
    worker --> apply[Apply segmentation\nSplit/merge utterances at predicted boundaries]
    apply --> merge_check{--merge-abbrev?}
    merge_check -->|Yes| merge[merge_abbreviations]
    merge_check -->|No| serialize
    merge --> serialize[Serialize → .cha output]
    serialize --> done([Write file's .cha; next file in pool])

Options

Path options

In-place rewrites with --file-list on a large corpus do appear file-by-file as the run progresses (each file is written to disk before the next file’s worker call starts). This is a deliberate property of the per-file dispatch shape, interruption mid-run loses only the files currently in flight, not the entire batch. Splitting the file list into smaller chunks is therefore unnecessary for incremental visibility, though it remains useful for managing memory or scheduling.

utseg options

What changes in the .cha file

• Utterance boundaries (*SPK: lines) are recomputed, utterances may be split or merged
• Existing %mor and %gra tiers on recomputed utterances will be invalidated; re-run morphotag after utseg if those tiers are needed
• No audio is involved

The boundary model uses lexical context only. It does not receive audio pause, energy, pitch, or diarization evidence. Internally BA3 validates one assignment per input word and retains typed model evidence across the worker boundary. The versioned --debug-dir evidence sidecars described in the transcribe guide belong to transcribe’s distinct pre-CHAT and post-CHAT phases; standalone utseg does not currently write those sidecars.

Language support

Per-language model selection is driven by UTSEG_BOUNDARY_MODELS in crates/batchalign/src/model_manifest.rs, which also pins the exact revision each one loads:

The English BERT is not applied cross-lingually, running utseg --lang fra does not load CHATUtterance-en. For any language without a TalkBank BERT model in the table above, utseg refuses the substitution by default, and the job is refused when it is planned: the language and the fallback policy are both known before any work is dispatched, so the run stops there with a message naming the language. Nothing is written, and the input is not quietly copied through as if it had been segmented. To permit the legacy Stanza constituency-parser fallback (the same segmenter Batchalign 2 used for unsupported languages), pass --utseg-fallback-stanza:

batchalign3 utseg corpus-fra/ --lang fra --utseg-fallback-stanza

Quality varies, Stanza ships constituency models for ~11 languages (en, de, es, it, pt, da, id, ja, tr, vi, zh-hans). The opt-in design prevents accidental quality regressions on unsupported languages.

See Utterance Segmentation for the algorithm details and the Stanza Capability Registry for the per-language processor availability table.

Provenance

Every file utseg writes records what segmented it in a [fc-ba3 utseg | engine=... ; lang=... | ...] comment. engine= is one of:

A boundary model is always written with its revision. It is loaded from a pinned snapshot and the commit is read off the directory on disk, so a worker that cannot say which revision it loaded refuses the job rather than reporting a bare id. Files written before that pin landed may carry an id with no revision; re-running utseg over them records the full identity.

Several sources on one file are joined with + in text order. There is no placeholder: a worker that returns boundaries without naming what produced them leaves the file with no comment at all, and the run says so.

Files segmented by a build before 2026-09-15 carry no comment, because the standalone command wrote none; re-running utseg over them adds one. See Processing Provenance.

Failure modes

utseg fails fast on engine failures rather than emitting partial output. When the BERT or Stanza worker reports a per-utterance error (model runtime error, malformed constituency tree, protocol violation), the affected file is marked failed with a typed ItemErrors message naming the first few offending items and the total count. Per-file dispatch (utseg-specific, BA3 utseg deliberately does NOT cross-file-batch) means one failing file has no effect on the next file in a multi-file run. The output .cha for a failed file is not written.

Related documentation

• Utterance Segmentation, algorithm and model details
• Stanza Capability Registry, which languages support constituency parsing
• Command I/O: utseg, I/O patterns and mutation behavior
• Command Flowcharts: utseg, full architecture flowchart

This page last changed: 2026-09-16 (commit 197c81e6). The whole book last changed: 2026-09-16 (commit 34d249d8).

translate

Status: Current Last updated: 2026-09-15 20:20 EDT

Add English translations to non-English CHAT transcripts by injecting a %xtra tier after each utterance. Text-only, no audio involved.

What gets translated

What was spoken. Each utterance is sent as every word the speaker produced, in order, followed by the utterance’s terminator, so a question is translated as a question. Retraced words (<I like> [/]) and filled pauses (&-um, sent as um) are included, which is what batchalign2 did; a word the transcriber replaced (hafta [: have to]) is sent as the replacement.

Left out, because they are not words a translator can read: 0-prefixed omissions (recorded as not said), &~ nonwords, &+ fragments, and the untranscribed markers xxx / yyy / www. An utterance that produced no words at all is not sent and gets no %xtra tier.

Only punctuation an ordinary reader would recognise travels with the words: the comma, and a terminator that is a period, question mark or exclamation mark (the question-bearing CHAT terminators +/?, +!?, +//? and +..? are sent as a question mark). CHAT-only notation is not sent at all, so +..., +/., +//., the tag marker and the vocative never reach the engine as text to translate.