Batchalign
Welcome to Batchalign. Batchalign is an audio and ML pipeline for producing and enriching CHAT transcripts. It supports transcription, forced alignment, morphotagging, utterance segmentation, translation, diarization, comparison, and the Batchalign desktop shell.
User Guides
User guides for getting started are available via the following links:
Installation
Batchalign is available in two variants: as an application or as a command-line tool. Downloads for both versions follow:
GUI Application

Press the blue rectangle corresponding to the operating system which you use to download the Batchalign application:
Finding the latest installers…
Terminal Interface (Advanced)

For the advanced terminal interface, the following scripts allows you to install Batchalign via uv.
On macOS or Linux:
curl -LsSf https://raw.githubusercontent.com/TalkBank/batchalign/main/bootstrap/bootstrap.sh | sh
On Windows, from PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-Expression ((Invoke-WebRequest -UseBasicParsing 'https://raw.githubusercontent.com/TalkBank/batchalign/main/bootstrap/bootstrap.ps1').Content)"
Batchalign documentation
Use Batchalign to transcribe recordings, align checked transcripts with audio, and add language analysis to CHAT files.
If you are new to Batchalign, begin with the Quick Start. It walks you through opening a command window and processing your first files.
| What you need | Start here |
|---|---|
| A guided first experience | Tutorials |
| Steps to complete a particular task | How-to guides |
| Exact commands, options, or data contracts | Reference |
| An understanding of how processing works | Explanation |
For common clinical and research workflows, the Batchalign guide helps you choose the next task. The sidebar also includes CHAT-format notation used by Batchalign. For Chatter, CLAN, and editors, see Related tools.
Batchalign documentation
Batchalign helps you turn conversation recordings into CHAT transcripts and add language analysis to transcripts you have checked.
Start here
If this is your first time using Batchalign, follow the Quick Start. It shows you how to open a command window, check your installation, and process a transcript. You do not need programming experience.
Choose what you need
| Your goal | Where to go |
|---|---|
| Learn by completing your first task | Tutorial: Quick Start |
| Install or update Batchalign | How to install Batchalign |
| Transcribe a recording | How to transcribe |
| Add grammatical analysis to a transcript | How to add morphology and grammar |
| Match a checked transcript to its recording | How to align |
| Solve a problem | Troubleshooting |
| Look up a command or option | CLI reference |
| Use Batchalign from Python | Python API reference |
| Understand processing speed and memory use | Performance explained |
| Understand what is reused on a repeat run | Caching explained |
| Understand the implementation | Pipeline architecture |
The documentation separates tutorials, how-to guides, reference, and explanation. Start with the kind of help you need; you do not need to read these pages in order.
Release notes
0.10.10
This release includes the latest desktop runtime fixes and aligns the application and Python package versions.
- Intel macOS runtime validation no longer mistakes Cryptography’s own library name for an external dependency. Runtime build errors retain their diagnostic output.
- macOS worker cleanup handles process groups that have already exited.
- Desktop validation covers Windows x86-64, macOS on Apple silicon and Intel, and Linux x86-64 and ARM64, including installed application checks.
The application installers are available from the homepage and GitHub releases. Update the Python package with:
pip install --upgrade batchalign
Included from 0.10.9
- Optional AVQI analysis with
pip install 'batchalign[avqi]', paired vowel and speech inputs, mirrored directory matching, and CSV output. - Pasketti engine options for word transcription and phonetic transcription.
- Plain CLI headers compatible with legacy Windows output encodings.
- Clean-install AVQI checks for all five wheel platforms.
Batchalign: tutorials
Learn by completing a guided task.
Quick Start
Status: Current Last updated: 2026-09-13
Install Batchalign with the command in the TalkBank/batchalign README.
1. Open a command window
- macOS: Open Terminal. Apple explains where to find it.
- Windows: Open the Start menu, type
PowerShell, and select PowerShell. Microsoft’s PowerShell guide includes startup help. - Linux: Open the Terminal application from your applications menu. On many systems, Ctrl-Alt-T opens it directly.
2. Check the installation
Paste this command and press Enter:
batchalign --help
If Batchalign prints a list of commands, it is ready.
3. Process a file or folder
This example adds %mor and %gra tiers to every CHAT file in a folder:
batchalign morphotag "/Users/me/Documents/My Corpus"
In PowerShell, a Windows path looks like this:
batchalign morphotag "C:\Users\me\Documents\My Corpus"
Batchalign accepts either one CHAT file or a folder. Use quotation marks around
paths containing spaces. Unless you specify an output folder, morphotag
updates the files in place.
Before you start
Model downloads: The first use of a backend may download its models. Download size and startup time depend on the backend and language. Later runs reuse model files from disk.
Caching: Batchalign saves text and audio backend results in a local LMDB cache. Repeat runs can reuse matching results, although startup and file processing still take time. See Caching for details.
Basic command shape
batchalign [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS] [PATHS...]
- Global options go before the command.
- Most processing commands use
-o/--outfor a destination directory. - Omitting
-o/--outmeans in-place processing when the command supports it.
Transcribe audio to CHAT
batchalign transcribe ~/recordings/ -o ~/transcripts/ --lang eng
To use the local OpenAI Whisper package instead of the default Rev.AI engine:
batchalign transcribe ~/recordings/ -o ~/transcripts/ \
--engine openai --lang eng
To use a local Whisper model:
batchalign transcribe ~/recordings/ -o ~/transcripts/ \
--engine whisper --lang eng
Align transcripts against audio
batchalign align ~/corpus/ -o ~/aligned/
Common useful flags:
batchalign align ~/corpus/ -o ~/aligned/ --engine whisper
batchalign align ~/corpus/ -o ~/aligned/ --utr-engine whisper
Add morphosyntactic analysis
batchalign morphotag ~/corpus/ -o ~/tagged/
Useful variants:
batchalign morphotag ~/corpus/ -o ~/tagged/ --retokenize
batchalign morphotag ~/corpus/ -o ~/tagged/ --keep-existing
Verbosity
batchalign align ~/corpus/ -o ~/aligned/
batchalign -v align ~/corpus/ -o ~/aligned/
batchalign -vv align ~/corpus/ -o ~/aligned/
batchalign -vvv align ~/corpus/ -o ~/aligned/
Next steps
- Batchalign Desktop (Experimental) — in-repo GUI shell status and scope
- CLI Reference
- Performance
- Rev.AI Integration
- Python API
Batchalign: how-to guides
Choose the task you want to complete.
- Install or update Batchalign
- Transcribe a recording
- Align a transcript
- Measure acoustic voice quality
- Add phonetic transcription
- Add morphology and grammar
- Segment utterances
- Add translation tiers
- Compare with a reference
- Configure Rev.AI
- Process Cantonese
- Prepare model downloads
- Manage the result cache
- Tune file concurrency
- Review generated output
- Troubleshoot a run
- Run the desktop from source
- Run the HTTP service
- Migrate a workflow
- Build from source
- Test a change
- Add a command
- Add a backend
- Add language support
- Handle a model-library defect
- Diagnose a pipeline failure
- Release the Python package
Install or update Batchalign
These instructions install the command-line application and its backend extras.
The installer also installs uv if needed and selects Python 3.11 for Batchalign.
macOS or Linux
Open Terminal, paste this command, and press Enter:
curl -LsSf https://raw.githubusercontent.com/TalkBank/batchalign/main/bootstrap/bootstrap.sh | sh
Windows
Open PowerShell, paste this command, and press Enter:
powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-Expression ((Invoke-WebRequest -UseBasicParsing 'https://raw.githubusercontent.com/TalkBank/batchalign/main/bootstrap/bootstrap.ps1').Content)"
Check the installation
Close and reopen your command window, then run:
batchalign --help
batchalign version
You should see a list of commands and version information. Continue to the Quick Start for your first processing task. If the command cannot be found, see Troubleshooting.
Update an existing installation
Run the same installer again. It upgrades the batchalign[all] tool installation
with prereleases allowed, matching the repository’s bootstrap scripts.
For an existing uv installation, the equivalent command is:
uv tool install --upgrade --python=3.11 --prerelease=allow 'batchalign[all]>=0.10'
The package on PyPI is named batchalign. It installs the batchalign command.
Model files may download separately when you first use a backend; see Model downloads.
Transcribe a recording
Use transcribe to produce a draft CHAT transcript from a recording. You will
need to listen to the recording and correct the draft afterward.
-
Place the recording in a folder you can find, such as
recordings. -
Run the following for English speech:
batchalign transcribe recordings/ -o transcripts/ --lang eng -
The default engine is Rev.AI. If you have not configured it, follow the credential prompt. Rev.AI processes uploaded audio through your account. See Configure Rev.AI.
-
Wait for the final summary. Open the
.chafile intranscriptsand review the words, speaker labels, and utterance boundaries against the recording. Generated transcripts include anUnchecked output of ASR modelcomment.
Use the appropriate three-letter language code, such as spa for Spanish or
cmn for Mandarin, instead of eng. --lang is required.
Without -o, the transcript is written beside the source recording.
Use a local speech model
To use the Hugging Face Whisper backend:
batchalign transcribe recordings/ -o transcripts/ --lang eng --engine whisper
The first run downloads the selected model. --engine openai selects the local
openai-whisper package; it does not mean the hosted OpenAI transcription API.
See CLI reference for the engine choices.
Pasketti for English child speech
Install batchalign[qwen3], then select the Pasketti word checkpoint:
batchalign transcribe recordings/ -o transcripts/ --lang eng --engine pasketti
This uses drivendata/pasketti-word through the local Qwen3 backend. The model
and its companion word aligner download on first use. This engine is English-only.
For IPA on an existing timed transcript, use phonetic.
Request separate speaker diarization
batchalign transcribe recordings/ -o transcripts/ --lang eng --diarize --num-speakers 2
This adds a separate speaker-assignment stage using the selected diarization backend. Provider speaker labels may already be present without this option.
Add word timings or refine alignment
Use --wor to retain word-level timing output from transcription. For forced
alignment of a corrected transcript, run align afterward. Transcription
does not automatically run forced alignment or morphosyntactic analysis.
Align a transcript to its recording
Use align after checking the transcript’s words. It adds word-level timing
information, including a %wor tier.
-
Put the CHAT transcript and its recording together. Check that
@Media:names the recording and@Languages:identifies the transcript language. -
Run:
batchalign align corpus/ -o aligned/ -
Wait for the final summary. Open the output transcript and check playback against the recording, especially long turns and overlapping speech.
The default forced-alignment engine is wav2vec. When utterance timings are
missing, the default timing-recovery engine is Rev.AI; configure its credentials
if prompted. Already-timed utterances can avoid that recovery step.
Use local timing recovery
batchalign align corpus/ -o aligned/ --utr-engine whisper
To use Whisper for forced alignment as well:
batchalign align corpus/ -o aligned/ --engine whisper --utr-engine whisper
Use --utr-engine none only when the transcript already has the timings required
for forced alignment. Keep different transcript languages in separate alignment
invocations: the CLI chooses a backend language from the selected CHAT inputs.
Without -o, source transcripts are updated in place. For model and device
options, see CLI reference.
Measure acoustic voice quality
Install the optional Praat bindings:
pip install 'batchalign[avqi]'
AVQI takes two recordings: a sustained vowel and continuous speech. Pass the vowel first:
batchalign avqi participant.sv.wav participant.cs.wav -o measurements/
For a collection, use two directories with mirrored relative paths:
vowels/participant1/session.sv.wav
speech/participant1/session.cs.wav
vowels/participant2/session.wav
speech/participant2/session.flac
batchalign --parallel 4 avqi vowels/ speech/ -o measurements/
The command searches both directory trees concurrently. Pairing uses the
relative path without its audio extension and removes a terminal .sv or
.cs marker for the corresponding input. Directory structure is preserved
in the pair identifier, so equal filenames in different participant folders
remain separate. Multiple files mapping to the same key are an error; files are
never paired by directory listing order. Two explicit files are paired directly,
regardless of their names. Mixing a file and a directory is not supported.
Output
The command writes measurements/avqi.csv, replacing it atomically after
processing. Without -o, it writes avqi.csv in the current directory.
Rows are sorted by pair identifier and include:
source_id,sv_file, andcs_file: pair identity and input paths.successanderror: processing status; failed measurements have empty numeric fields.avqi: the composite score.cpps,hnr,shimmer_local,shimmer_local_db,slope, andtilt: the six component measurements.voiced_cs_durationandsv_duration: seconds of retained speech and vowel used.implementation: extraction revision, Parselmouth version, and embedded Praat version.
Missing partners and per-pair processing failures remain visible as failed rows. Other valid pairs continue processing. Any failed pair gives a nonzero CLI exit status. No temporary audio files are written beside the originals.
Input and measurement procedure
Use recordings from the same speaker and assessment session. Inputs are decoded through Batchalign’s media layer and downmixed to mono. Both sample rates must be at least 20 kHz because the LTAS measurements use frequencies through 10 kHz. When the rates differ, Praat resamples to the higher rate. This does not restore bandwidth missing from the original recordings.
The sustained vowel must be at least three seconds long; its final three seconds are used. Remove unwanted trailing silence from the input beforehand. Silent, empty, non-finite, or unmeasurable recordings fail rather than receiving a fabricated score.
The backend follows the supplied energy-window extraction procedure:
- Apply a 0–34 Hz stop Hann filter to both recordings.
- Remove speech intervals classified as silence using Praat’s silence detector.
- Retain complete 30 ms speech windows whose power exceeds 30% of the concatenated sounding signal’s power and which contain a zero crossing.
- Concatenate the retained speech with the final three seconds of vowel.
- Measure CPPS, HNR, local shimmer (percent), local shimmer (dB), LTAS slope, and the slope of Praat’s computed LTAS trend line.
The combination uses the AVQI 03.01 coefficients:
(4.152 - 0.177*CPPS - 0.006*HNR - 0.037*shimmer_percent
+ 0.941*shimmer_dB + 0.010*slope + 0.093*tilt) * 2.8902
These coefficients are described in the AVQI validation literature. The energy-window selector here is a versioned Batchalign implementation, not a validated reproduction of the original AVQI script’s full speech-selection protocol. It does not enforce a language-specific speech task or balance voiced speech to exactly three seconds. Real-audio smoke tests establish execution, not clinical calibration or equivalence. Scores are not clamped or converted to diagnostic labels.
Praat operations are serialized to protect its shared object state. Pipeline workers can prepare independent pairs concurrently. Cache keys include both decoded recordings and the backend implementation/version identity.
Python pipeline
import batchalign as ba
pipeline = ba.recipes.avqi(avqi_backend=ba.AvqiBackend(), workers=4)
inputs = [
ba.AvqiMediaInput(
sustained_vowel="participant.sv.wav",
continuous_speech="participant.cs.wav",
source_id="participant",
)
]
for outcome in pipeline.run(inputs):
if outcome.is_failed:
print(outcome.source_id, outcome.error)
else:
print(outcome.metrics["rows"][0]["columns"])
Outcome.metrics exposes the structured metrics table without consuming the
outcome. The Rust runner prepares the audio pair; AvqiBackend implements the
AVQI backend marker and receives typed AvqiInput values.
Test a clean wheel installation
From the repository, build the native wheel, then pass its path to the installation smoke test:
just batchalign wheel
just batchalign avqi-install-test python/target/wheels/batchalign-<version>-<platform-tags>.whl
The test creates a disposable virtual environment, installs the wheel with its
avqi extra, runs pip check, verifies native and generated-type imports, and
processes two mirrored pairs of synthetic audio using the installed console
script outside the checkout. It requires network access for dependencies.
An optional final argument selects the Python interpreter, such as python3.12.
Add acoustic phonetic transcription
Use phonetic to add observed IPA to the %pho tier of a timed CHAT transcript.
Place matching audio beside the transcript, or pass a separate media directory
with --media. Utterances need timing bullets; existing phonetic tiers are
preserved.
batchalign phonetic transcripts/ -o phonetic/
The default engine is PhoneticXeus. Adjacent utterances share approximately
20-second inference windows. Reference pronunciations help assign the recognized
phones to transcript words; they do not replace observed speech with a canonical
pronunciation. Unresolved words receive ….
Pasketti for English speech
batchalign phonetic transcripts/ -o phonetic/ --engine pasketti
This selects
pasketti-phonetic, an
English child-speech WavLM CTC model. It processes utterances separately,
resamples audio to 16 kHz, and runs in full precision. Install
batchalign[phonetic] for local inference dependencies. Model weights download
on first use.
This is separate from transcribe --engine pasketti, which selects
pasketti-word to produce a
word transcript. Review both models’ output against the recording.
Pronunciation overrides and memory
batchalign phonetic transcripts/ -o phonetic/ --pronunciations words.csv --force-cpu --batch-size 1
The optional UTF-8 CSV has a word,ipa header, followed by overrides such as
wug,wʌɡ. Overrides affect the reference used for phone ownership, not the
recognized phones. The default model batch size is 1 on CPU and 2 on CUDA.
Reduce --batch-size if model batches exceed available memory.
See CLI reference for options.
Add morphology and grammar to a transcript
Use morphotag on checked CHAT transcripts to add %mor morphology and %gra
dependency tiers. Audio is not required.
-
Put the CHAT files you want to process in a folder. Check that each file’s
@Languages:header identifies its language. -
Choose a separate destination folder, then run:
batchalign morphotag "corpus" -o "tagged" -
Wait for the final summary. The first use of a language can download Stanza models before tagging begins.
-
Open a transcript in
taggedand inspect its%morand%gratiers under the speaker lines. Review the analysis before using it in your workflow.
Without -o, this command updates source files in place. Folder input is
recursive. You can also supply individual files or an
input list.
Retag existing analysis
By default, the CLI removes existing %mor and %gra tiers from staged inputs
before processing. Matching backend results may still come from the result cache.
To preserve existing analysis and let the engine skip already-tagged utterances:
batchalign morphotag corpus/ -o tagged/ --keep-existing
Allow retokenization
If you need the backend to retokenize text, request it explicitly:
batchalign morphotag corpus/ -o tagged/ --retokenize
Check the resulting main tiers as well as the analysis tiers.
For options, see CLI reference. For reuse and speed, see Caching and Performance.
Segment a transcript into utterances
Use utseg when a CHAT transcript needs utterance boundaries revised.
batchalign utseg corpus/ -o segmented/
Open the output and check the new boundaries against the conversation. Without
-o, the command updates source files in place.
The CLI uses the CHAT utterance-segmentation backend. The --language option
is passed to that backend and defaults to en. To enable its Stanza fallback:
batchalign utseg corpus/ -o segmented/ --stanza-fallback
See CLI reference for device options. Backend results use the result cache.
Add translation tiers
Use translate to add translation text to CHAT transcripts:
batchalign translate corpus/ -o translated/ --target eng
The default engine is Google. Open the output and review the %eng tiers. The
current output tier name remains %eng even when another target language is
selected. Without -o, the command updates source files in place.
To select the local NLLB backend:
batchalign translate corpus/ -o translated/ --target eng --engine nllb
The other CLI engine choices are tencent and aliyun. Provider setup and
language coverage depend on the selected backend. See
CLI reference for options.
Compare a transcript with a reference
Use compare when you have a transcript and a checked reference transcript.
-
Place
session.chaandsession.gold.chain the same folder. Alternatively, usetemplate.gold.chaas the reference for files in that folder; a per-file.gold.chatakes precedence. -
Run:
batchalign compare corpus/ -o comparisons/ -
Inspect the generated comparison metrics and the command’s summary. Gold files are references, not separate inputs to score. Files without a matching reference are skipped by input pairing.
See CLI reference for input selection.
Configure Rev.AI transcription
Rev.AI is the default speech-recognition backend for transcribe and the default
utterance-timing recovery backend for align.
Set up your key
Run an interactive transcription command:
batchalign transcribe recordings/ -o transcripts/ --lang eng --engine rev
When prompted, enter your Rev.AI API key. Interactive configuration stores the
key in ~/.batchalign.ini, under [asr] as engine.rev.key.
For automation, supply BATCHALIGN_REV_KEY through your environment or secret
manager. Quiet mode suppresses interactive credential prompts. The current CLI
has no setup subcommand.
Use the configured account
batchalign transcribe recordings/ -o transcripts/ --lang eng --engine rev
batchalign align corpus/ -o aligned/ --utr-engine rev
These operations can upload audio to Rev.AI. Use an account and recordings appropriate for your organization’s workflow. To select a local transcription backend, see Transcribe a recording.
The integration is implemented in the Python backends and configuration module, not a separate Rust server path.
Process Cantonese recordings and transcripts
For a local Cantonese ASR backend, select funaudio and the required language
code yue:
batchalign transcribe recordings/ -o transcripts/ --lang yue --engine funaudio
Cloud choices include tencent and aliyun; their credentials and model options
are owned by the corresponding Python backend. Use --engine, not the retired
JSON engine-override flag. Review the draft words before subsequent analysis.
For morphology, check that the CHAT header contains @Languages: yue, then run:
batchalign morphotag transcripts/ -o tagged/ --retokenize
Retokenization allows word boundaries to change, so inspect the main tiers and analysis tiers in the output. For alignment, follow Align a transcript; model coverage must match the recording and transcript language.
Prepare model downloads
Use this guide before processing on a new computer or before taking a machine offline.
- Install the backend dependencies using the standard installer.
- While connected to the internet, run a small representative input with the same command, language, engine, and model you intend to use later.
- Let the command complete. A successful installation alone does not prove that all required models have downloaded.
- Repeat for other languages or models you plan to use. A Stanza model for one language does not cover every language.
- If you need offline operation, test the exact command and input type after disconnecting. Cloud engines still require their external services.
Downloads and disk locations are managed by each backend’s model libraries. Download sizes vary; there is no fixed total size for a Batchalign installation. The current CLI has no model-download or cache-prewarm subcommand.
The Stanza morphosyntax backend refreshes an existing resource catalog once per process, retaining the cached catalog if refresh fails. It loads language pipelines lazily unless a language is pinned at construction. Missing model files can still require downloads. See Performance for the distinction between model files on disk, loaded models in memory, and cached task results.
Manage the result cache
Use these commands when you need to inspect stored results or force a fresh run. They operate on the default result cache, not downloaded models.
Inspect the cache
batchalign cache path
batchalign cache stats
path prints the directory. stats prints its apparent file size and latest
modification time, or reports that the cache is absent. It does not count entries.
Clear saved results
Finish or stop processing jobs that use the cache, then run:
batchalign cache clear
Confirm the displayed path when prompted. For an unattended script:
batchalign cache clear --yes
The next processing run recomputes the required backend results and can save them again. Your transcripts, recordings, and downloaded models remain in their own locations.
The current CLI has no per-run cache bypass flag. Python callers can use
CacheSpec.bypass() or CacheSpec.refresh().
Tune file concurrency
Use --parallel when you want to change how many files a processing command can
work on at once. Start with the default, 8. If memory use is too high, reduce it:
batchalign --parallel 2 morphotag corpus/ -o tagged/
The option goes before the command name. Its minimum is 1. Scripts using the
old global --workers option should use --parallel instead.
Compare settings
- Choose a representative set of files, including the longer transcripts or recordings you normally process.
- Run with
--parallel 1and a separate output folder. Record elapsed time and peak resident memory with your operating system’s monitoring tools. - Repeat with
--parallel 4, then 8 if memory permits. Keep the inputs and backend options unchanged. - Compare runs with the same cache state. A cached second run is not evidence that a higher concurrency setting improved inference. To compare uncached CLI runs, clear the result cache between trials after each job finishes.
- Keep the smallest setting that gives useful throughput on your workload.
For morphotag, active files share one Stanza batcher. Increasing --parallel
does not create additional Stanza replicas. The default utterance dispatch
window and backend batch maximum are both 128; there is no CLI batch-size flag.
Python callers can set StanzaBackend(batch_size=..., batch_window_ms=...), but
that does not change the Rust per-file dispatch window.
The Python Pipeline and recipe APIs still name file concurrency workers.
For the scheduling and memory model, see Performance.
Review generated transcripts and timings
- Keep the original transcript or recording and write processing output to a
separate folder with
-o. - Read the command’s final summary and inspect failed or skipped files before relying on the output set.
- For transcription, listen to the recording and correct words, speaker labels, and utterance boundaries. ASR output is marked as unchecked.
- For alignment, check playback at utterance and word boundaries, especially where speakers overlap or the recording is noisy.
- For morphology, inspect
%morand%graagainst the intended words and language. If retokenization was enabled, review main-tier changes too.
Older files may contain %xalign decision notes or %xrev review markers from
other processing versions. Their presence does not prove that the current run
created them, and their absence does not prove an output is correct. The current
CLI does not expose the old --review-level controls.
Use provenance comments to identify a producing build and task. A file modification timestamp alone cannot establish which utterances were edited or whether a previous review remains valid.
Troubleshoot a processing run
The command cannot be found
Close and reopen Terminal or PowerShell after installation, then try
batchalign --help. If it is still unavailable, repeat the
installation steps and check that the installer finished.
An option or command is unknown
Run batchalign --help and batchalign COMMAND --help using your installed
version. The current global concurrency flag is --parallel; engine selection
uses command-specific --engine options. The CLI does not expose the older
serve, setup, logs, doctor, or bench interfaces.
A processing command appears to be waiting
The first use of a backend can download models. An interactive cloud backend may
also be waiting for credentials. Keep the command window open and read its latest
message. Use batchalign -v COMMAND ... for more detail or --plain before the
command to avoid live terminal rendering. See Model downloads.
The transcript cannot be parsed
Read the error’s file location and CHAT diagnostic. Fix the indicated transcript
and rerun a single file before processing the folder again. For morphology, check
@Languages: and the CHAT header structure. Use the
CHAT format reference to interpret markup.
Alignment cannot find the recording
Check the transcript’s @Media: header, keep the referenced recording beside the
CHAT file, and confirm that the recording is readable. Use a small single-file
run to check the pairing. The current local CLI does not use the old server’s
remote media mappings.
The computer runs out of memory
Lower file concurrency, for example:
batchalign --parallel 1 morphotag corpus/ -o tagged/
For commands that expose it, --force-cpu selects CPU inference; it is not a
morphotag option. Long transcripts and model batch sizes still affect memory at
--parallel 1. See Performance.
A repeat run gives the same unexpected result
Check and correct the input first. If you need to rule out saved backend results, finish active processing and clear the result cache, then rerun. Removing model files is a separate operation and is not required to clear saved results.
Report a reproducible problem
Include the output of batchalign version, your operating system, the exact
command with credentials removed, and the final error text. Attach a small input
that reproduces the problem if you can share it. Say whether it also happens with
a fresh result cache. Report issues in the Batchalign repository.
Run the desktop application from source
The Batchalign desktop application lives in apps/batchalign/batchalign-gui/.
It uses React and Tauri, with a bundled Python HTTP-service sidecar.
From a development checkout with the repository build tools installed:
just batchalign gui dev
The Bazel dependency graph builds and stages the sidecar. To create a desktop
bundle, use just batchalign gui build.
In the application, drop an input folder onto the window or choose open folder, add a command, review its language and engine settings, choose the output location, and start the batch. Folders are searched recursively. The app displays one folder at a time. Use choose… to replace it or close beside the folder chooser to return to the drop-folder screen. The speaker command and Speaker recognition option identify speaker turns. The elapsed timer continues updating while a model is busy.
For transcription, enter a valid three-letter ISO 639-3 language code before
choosing an engine. Autocomplete searches codes and language names; Chinese uses
zho. No ASR engine is selected automatically. Recommendations appear in a gray
box, with the other engines listed below: CHAT-Whisper for English; Aliyun for adult Cantonese
and FunASR/SenseVoice for child Cantonese; Paraformer-zh for Mandarin. Google
GenAI, OpenAI Whisper, Qwen3, and Rev.AI are the general choices. Rev.AI is always
offered after a valid language is entered; other engines follow service availability.
Recommendations include cloud and local choices, with cloud engines first.
Rev.AI supplies the cloud recommendation when there is no language-specific one;
OpenAI Whisper or Qwen3 supplies a local fallback when available.
The Recognition engine defaults to pyannoteAI (cloud).
The GUI omits Malayalam Wav2Vec,
Qwen, Tencent Cloud ASR, and Hugging Face Whisper; their CLI/API availability
is unchanged.
For ordinary command-line use, start with the Quick Start. The CLI does not require the desktop service to be running.
Run the HTTP service
Use this guide for API development or a GUI integration. You do not need an HTTP service to process files with the CLI.
-
Install the
apiextra in your Batchalign environment. The standard bootstrap installation includes theallextra, which includes API dependencies. -
Start the service in your command window:
batchalign daemon --host 127.0.0.1 --port 8765 -
Open
http://127.0.0.1:8765/docsfor the API schema, or requesthttp://127.0.0.1:8765/capabilitiesto discover recipes and backends. -
Stop the foreground service with Ctrl-C when finished.
Keep the default one Uvicorn worker: the job registry is process-local. The
daemon --workers option concerns HTTP processes; it is unrelated to the CLI’s
global --parallel option. For supervised operation, run the foreground command
under your service manager.
For local path-based API inputs, the service requires
BATCHALIGN_API_ALLOW_PATHS=1. Enable it only for a trusted local integration:
those paths are interpreted on the machine running the service. The desktop
sidecar sets up its own local connection.
The service has no serve start/serve stop command group or server.yaml
configuration. See CLI reference for supported options.
Update commands and integrations
- Update the
batchalignpackage using the installer. Checkbatchalign versionbefore comparing behavior. - Replace the former global
--workers Nflag with--parallel N. It controls active files, not model-process replicas. - Use command-specific
--engineoptions for ASR and FA. Check the actual choices withbatchalign COMMAND --help; old engine names are not all interchangeable. - Use
-o/--outfor a destination. Processing commands accept multiple paths and-i/--input-list/--file-list. - Remove old automatic-server, fleet, benchmark, and cache-override flags.
Ordinary CLI processing now runs in process. The separate
daemonis an HTTP service for GUI/API integrations. - Update cache assumptions: text and audio backend results use LMDB. See Caching before comparing repeat-run performance.
- For Python integrations, use the current
Pipeline, recipe, input, and backend interfaces. The old BA2 document/pipeline classes are not drop-in equivalents.
Run a small copied input through the revised workflow before processing a corpus. The CLI reference lists the supported surface.
Build Batchalign from source
Use the repository’s just recipes from the checkout root. They invoke Bazel
and materialize the Rust extension, Python dependencies, and generated protocol
types required by each target.
just batchalign build debug
just batchalign test debug
just batchalign cli --help
just batchalign cli is the authoritative development CLI entrypoint. It restores
the invocation directory before running the Bazel Python binary, so relative
input paths behave as they do in an installed CLI.
Build release artifacts
just batchalign wheel
just batchalign sidecar
just batchalign gui build
wheel produces the host-platform Python wheel in python/target/wheels/.
sidecar builds the PyApp-bundled HTTP service. The GUI bundle embeds that sidecar.
Cross-platform wheel builds run in the GitHub Actions matrix.
Run checks
just batchalign test
just batchalign pytest
just batchalign lint
just batchalign gui test
just docs build
See Testing for scope. just batchalign versions shows the version
sources; just --list batchalign lists recipes. Use the repository wrappers
instead of a separate editable-install procedure for ordinary development.
Test a Batchalign change
Run commands from the repository root using just.
| Check | Command | Scope |
|---|---|---|
| Product tests | just batchalign test | Core Rust targets, explicitly named engine tests, Python pytest target |
| Python tests | just batchalign pytest | Python suite through Bazel; extra arguments are forwarded to pytest |
| Type/lint checks | just batchalign lint | Mypy, followed by Ruff when available |
| GUI integration | just batchalign gui test | Playwright against the Bazel-built PyApp service, with Tauri APIs stubbed |
| Book and links | just docs build | mdBook HTML and configured linkcheck renderer |
For a focused Python case:
just batchalign pytest -k cli_input_list
For an integration check, use the real development entrypoint:
just batchalign cli --parallel 2 morphotag /path/to/fixtures -o /tmp/tagged-check
Choose inputs that exercise the behavior being changed. For inference changes, compare semantic outputs as well as elapsed time and RSS; record cache state and model settings. Tests with fake backends check orchestration, not model accuracy.
The product recipe explicitly includes engine unit, cache-smoke, and pipeline-smoke targets that a broad wildcard can omit because of manual tags. The wheel CI matrix also checks native platform packaging and Python 3.10 imports.
GUI checks need a browser installed for the pinned Playwright version. On a cold machine, the bundled runtime may need first-launch setup before it can serve requests. Distinguish setup failures from frontend assertions when diagnosing results.
Add a processing command
- Identify the input/output types and task sequence. Reuse a recipe in
python/batchalign/recipes.pyor add one that constructsPipeline. - Implement a command module under
python/batchalign/cli/. Useresolve_inputsfor multiple paths and file lists, andcli_options(ctx)for global settings. - Pass
opts.parallelas the recipe’sworkersvalue. UseInterfacefor progress and the shared output helpers for outcomes where their contract fits. - Register the module in
_LAZY_SUBCOMMANDSincli/__init__.py. A file undercli/hidden/is not automatically a public command. - Test help, argument validation, output destinations, and failures. Exercise a
real invocation through
just batchalign cli. - Add a task-focused how-to page and update the CLI reference.
morphotag.py demonstrates staged CHAT preprocessing; convert.py demonstrates
output collision checks. Use the example that matches the new command’s behavior.
See Pipeline architecture for the runtime.
Add an inference backend
- Choose the task interface in
python/batchalign/backends/base.py. Implement the corresponding backend marker, a stablename, itsBatchPolicy, andcallbehavior. Start from an existing backend for the same task. - Return the typed output expected by the core
proto/definition. Preserve input/output correspondence and return one output per input in a batch. - Include output-affecting model/configuration changes in backend identity when they are not already in the typed input. The engine uses that name in cache keys.
- Export the backend through the package’s lazy import surface where appropriate,
add its dependencies to the relevant
python/pyproject.tomlextra, and supply it to a recipe. For a CLI engine choice, update that command’s enum and builder. - Test protocol shape and failure behavior with deterministic fixtures, then
perform a small real-backend smoke run through
just batchalign cli. - Update the command reference and any backend-specific instructions.
Batching and result caching are engine responsibilities. Do not add a worker process or a second cache solely to integrate an ordinary Python backend. A genuinely new task also needs core input/output types, a runner, and routing registration; inspect the existing task family before extending those contracts.
See Source map, Python API, and Testing.
Add or change language support
- Identify the command and backend you are extending. Language-code recognition, model availability, and useful analysis quality are separate checks.
- Check
python/batchalign/lang.pyand the backend’s vendor-code conversion. For Stanza, inspectbackends/morphosyntax/ud/lang.pyandstanza.py. - Test representative text or audio with the selected model. Include the language’s contractions, script, punctuation, and conversational forms.
- For ASR, check number expansion and cleanup in the Rust core
asr/modules. For morphology, check token reconciliation and typed tier alignment as well as the model’s raw output. - Add regression fixtures at the responsible layer and run the appropriate tests, followed by a small CLI integration run.
- Update language selection and the language-specific reference. Record measured quality with model versions and corpus scope instead of inferring support from a language list.
Handle a model-library defect
- Reduce the failure to a small reproducible input and record library/model versions and configuration.
- Determine whether the error originates in the model, a vendor adapter, token reconciliation, or CHAT result application.
- Add a regression at that boundary. Test a nearby valid case so a workaround does not merely suppress a class of outputs.
- Implement a narrowly scoped correction where the required information is available. Stanza token processing/rendering lives in the Python backend; typed CHAT injection lives in the Rust morphology runner.
- Re-run the affected command on representative inputs and compare semantic output. Record known limits rather than claiming a universal linguistic fix.
- If behavior affects cached outputs, update backend identity as appropriate; compiled build identity also participates in result-cache keys.
Historical model probes are useful evidence, but rerun a relevant case against the current pinned environment before treating an old mitigation table as active.
Diagnose a pipeline failure
- Reproduce with one small input through
just batchalign cli, using a separate output directory. Preserve the original failing input. - Add global
-vor-vvand capture the command’s error text. Use--plainwhen saving terminal output to a file. - Determine whether failure occurs during input parsing, backend construction, backend inference, result application, or output writing. Use the source map to find the owning layer.
- Compare cached and fresh behavior when relevant using the Python cache policy or the CLI cache-management command after active processing stops.
- Add a focused regression case at the layer that owns the defect. A fake backend can isolate scheduler and result-injection behavior from model behavior.
The current CLI does not expose the retired --debug-dir, server job logs, or
worker-protocol trace commands. Inspect Outcome.error, progress callbacks, and
the Python/Rust logging surfaces used by the current pipeline. Include version,
command, input shape, and cache state in a reproducible report.
Release the Python package
- Set the Python package version in
python/pyproject.toml. The repository wrapper refreshespython/uv.lock; check the resulting diff. Rust workspace and desktop versions have separate owners. - Run the relevant checks, inspect their results, and record any known baseline failures separately from regressions.
- Commit the intended release state and push it to the branch CI will build.
- Dispatch
.github/workflows/publish-pypi.ymlwithtagexactly matching the Python version. The workflow builds native macOS ARM/Intel, Linux ARM/x86-64, and Windows x86-64 wheels. - Verify that every artifact came from the intended commit, has the expected
version/platform tag, and passes
bazel/python/verify_wheel.pyandtwine check. - Publish through the configured channel. The workflow’s
publish=trueroute requires PyPI trusted publishing. If that is not configured, build withpublish=false, download all five wheel artifacts, and upload them using authenticated Twine. - Verify PyPI’s file list and hashes against the artifacts you uploaded.
Do not publish local development wheels in place of the matrix artifacts.
The exact workflow and package metadata are the release contract; historical
batchalign3 distribution and Rust-server release instructions do not apply.
Batchalign: reference
Look up syntax, contracts, and factual details.
- CLI options
- Python API
- Python CHAT documents
- Command inputs and outputs
- Filesystem locations
- Provenance comments
- CHAT handling
- CHAT processing options
- Language selection
- Language index
- Coreference interface
- Morphosyntax contract
- Dependency tiers
- Forced-alignment pipeline
- Media conversion
- TextGrid export
- English ASR corrections
- Retrace detection
- Wheel platforms
- Source map
- Python versions
- Release surfaces
- Historical studies and decisions
- Documentation audit
- Cantonese
- Mandarin
- Japanese
- Hebrew
- French
- Italian
- Portuguese
- Dutch
- Malayalam
CLI reference
The installed command is batchalign.
Options below are checked against python/batchalign/cli/ for version 0.10.1.
Run batchalign COMMAND --help for the help shipped with your installation.
batchalign [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS] [PATHS...]
Global options
| Option | Default | Meaning |
|---|---|---|
--parallel N | 8 | Maximum concurrent input files; minimum 1 |
-v, --verbose | Off | Increase verbosity; repeat for more detail |
-q, --quiet | Off | Suppress routine output and interactive credential prompts |
--plain | Automatic | Use the non-live renderer |
--ansi | Automatic | Force live rendering; --plain takes precedence if both are supplied |
--help | Show help |
Global options go before the command. Device, model, and engine options belong to their individual commands.
Input selection
Processing commands accept one or more paths, or -i/--input-list/--file-list FILE.
Directories are scanned recursively. CHAT commands accept .cha and .chat;
media discovery accepts .wav, .mp3, .m4a, .flac, .ogg, .mp4, .mov,
and .m4v. Actual decoding support depends on the media backend.
batchalign morphotag first.cha second.cha -o tagged/
batchalign transcribe -i recordings.txt -o transcripts/ --lang eng
A list is a UTF-8 text file containing one path per line. Blank lines and lines
whose first non-space character is # are ignored. List entries are resolved
relative to the list’s directory. Positional paths are relative to the command’s
working directory. Paths are deduplicated after resolving them; a repeated entry
is processed once. Whitespace around list entries is trimmed.
-o/--out DIR selects an output directory. Relative subdirectories are mirrored
from the common input root. Without it, CHAT transformation commands write beside
or over their input as described below. See Command I/O.
CHAT commands (align, phonetic, diarize, morphotag, translate, utseg,
ai, and compare) also accept -m/--media DIR for a separate media hierarchy:
batchalign align transcripts/ -m recordings/ -o aligned/
For transcripts/session/clip.cha, media is searched in recordings/session/,
using the @Media basename first, then clip, with a supported audio or video
extension. Missing matches report an error. A single transcript uses the media
folder directly; multiple paths or an input list use their common input root,
as output mirroring does. The explicit media folder takes precedence over media
beside transcripts. Transcript headers and output locations are preserved.
Commands
| Command | Purpose |
|---|---|
transcribe | Recording to CHAT transcript |
align | Forced alignment of CHAT against audio |
avqi | Measure paired sustained-vowel and continuous-speech audio; write avqi.csv |
phonetic | Add observed IPA to %pho using audio and phone-sequence DP |
morphotag | Add %mor and %gra |
utseg | Revise utterance segmentation |
translate | Add translation tiers |
compare | Compare CHAT against .gold.cha references |
convert | Convert media to WAV or MP3 |
diarize | Assign speakers to existing timed CHAT |
ai | Apply an AI editing instruction to CHAT |
cache | Inspect or clear the result cache |
version | Print version and build information |
daemon | Run the separate HTTP service |
transcribe
Accepts the shared input selection and -o/--out options above.
| Option or argument | Default | Details |
|---|---|---|
--engine | rev | Choices: rev, whisper, chatwhisper, openai, funaudio, tencent, qwen3, aliyun, malayalam, google, pasketti. Pasketti supports English only. |
--lang | Required | ISO-639-3 alpha_3 code: eng, cmn, yue, spa, … (Required.) |
--model | Unset | ASR model id (engine-specific default if omitted). |
--diarize/--no-diarize | False | Run speaker diarization with –diarize-engine after utterance segmentation. |
--diarize-engine | pyannote-ai | Choices: pyannote-ai, pyannote. Diarization engine: pyannote-ai (cloud, default) or pyannote (local). |
--num-speakers, -n | 2 | Expected speaker count (diarization hint). |
--force-cpu | False | Run local inference, including utterance segmentation, on CPU (BA2’s –force-cpu). |
--allow-mps | False | Explicitly allow local ASR and utterance-segmentation models to use Apple MPS. Off by default because sustained MPS inference can be unstable; CHATWhisper remains float32 when selected. |
--wor/--nowor | False | Include word-level timing (%wor and inline word bullets); omitted by default. |
align
Accepts the shared input selection and -o/--out options above.
| Option or argument | Default | Details |
|---|---|---|
--engine | wav2vec | Choices: wav2vec, whisper_fa, qwen. Forced-alignment engine: wav2vec | whisper_fa | qwen. |
--model | Unset | FA model id (engine-specific default if omitted; wav2vec picks per the file language). |
--force-cpu | False | Run the FA model on CPU (BA2’s –force-cpu). Needed for whisper_fa on Apple MPS, where Whisper’s bfloat16 attention kernel is unsupported. |
--allow-mps | False | Explicitly allow local alignment models to use Apple MPS. Off by default because sustained MPS inference can be unstable. |
--utr-engine | rev | Choices: off, whisper, rev. Utterance Timing Recovery backend: rev | whisper | off. When non-off, runs Task.Utr before FA to recover utterance bullets on fully-untimed CHATs. Automatically skipped when any utterance already carries a bullet — UTR is intended for fully-untimed transcripts only. |
--utr-model | Unset | UTR model id (only used when –utr-engine=whisper; default is openai/whisper-large-v3 to match BA2’s transcribe). |
morphotag
Accepts the shared input selection and -o/--out options above.
| Option or argument | Default | Details |
|---|---|---|
--retokenize/--no-retokenize | False | |
--clear-existing/--keep-existing | True | If true (default), drop any pre-existing %mor:/%gra: tiers from each input before tagging so re-runs regenerate. Use –keep-existing to preserve them and let the engine skip already-tagged utterances. |
utseg
Accepts the shared input selection and -o/--out options above.
| Option or argument | Default | Details |
|---|---|---|
--stanza-fallback/--no-stanza-fallback | False | |
--language | en | |
--force-cpu | False | Run utterance segmentation on CPU. |
--allow-mps | False | Use Apple MPS for utterance segmentation when available. |
translate
Accepts the shared input selection and -o/--out options above.
| Option or argument | Default | Details |
|---|---|---|
--target | eng | Target language code (ISO 639-3). |
--engine | Choices: google, nllb, tencent, aliyun. |
compare
Accepts the shared input selection and -o/--out options above.
| Option or argument | Default | Details |
|---|
convert
Accepts the shared input selection and -o/--out options above.
| Option or argument | Default | Details |
|---|---|---|
--format | Required | Choices: mp3, wav. Output format: mp3 or wav. |
diarize
Accepts the shared input selection and -o/--out options above.
| Option or argument | Default | Details |
|---|---|---|
--engine | pyannote-ai | Choices: pyannote-ai, pyannote. Diarization engine: pyannote-ai (cloud) or pyannote (local). |
--num-speakers, -n | 0 | Expected speaker count; zero auto-detects. |
avqi
batchalign [--parallel N] avqi SUSTAINED_VOWEL CONTINUOUS_SPEECH [-o DIRECTORY]
Both arguments must be files or both must be directories. Directory pairing uses
mirrored relative stems, optionally stripping terminal .sv / .cs markers.
The output is one avqi.csv in DIRECTORY (the current directory by default).
This command does not use CHAT inputs, --media, or --input-list.
Install batchalign[avqi]; inputs need at least 20 kHz audio and the vowel must
be at least three seconds. See AVQI for measurement details,
CSV columns, and failure behavior.
phonetic
Accepts timed CHAT and matching audio, using shared input selection and
-o/--out. Install the phonetic extra for PhoneticXeus, Pasketti, Piper Plus G2P, and Epitran.
Phonetic transcription requires Python 3.11 or newer.
The first inference downloads the pinned model revision;
building the CLI and displaying help do not download model weights.
just batchalign cli phonetic recording.cha --out phonetic-output --force-cpu
The command recognizes phones from audio and DP-aligns them against reference
IPA pronunciations to recover word boundaries. %pho retains the observed IPA,
including pronunciation differences. Existing %pho tiers are preserved.
The input must have utterance timing bullets. Prepare an aligned transcript
with align first if timing is missing.
Word-level forced alignment is not required.
The default PhoneticXeus engine groups consecutive utterances
into approximately 20-second audio windows, then projects phones back to their
original words and utterances. Gaps over two seconds and backwards timings start
a new window; an utterance longer than 20 seconds stays whole. Words receiving
no phones are marked … (uncoded) and reported with their utterance timing.
Pasketti processes each English utterance separately using a full-precision WavLM CTC model; it does not combine adjacent turns.
Windows of similar duration are batched using padding and real encoder lengths.
Normalization is performed independently per window, and padded output frames
are excluded from decoding. CPU defaults to one window at a time; CUDA defaults
to two. Increase --batch-size to try higher GPU throughput, or decrease it to
reduce memory use. Batched and single-window output can differ slightly because
the upstream encoder’s convolution branches remain sensitive to padding.
| Option | Default | Details |
|---|---|---|
--engine | phoneticxeus | phoneticxeus or pasketti (English child speech) |
--pronunciations | None | UTF-8 CSV with header word,ipa; one word or whole phonological unit and its IPA per row, overriding the generated pronunciation. |
--force-cpu | False | Use CPU instead of automatic CUDA selection. MPS is not selected. |
--batch-size | CPU 1, CUDA 2 | Maximum audio windows per model batch; must be positive. |
The task runner passes the primary @Languages code from CHAT. No separate
language option is needed. Piper Plus G2P
0.2.0 handles English, Japanese, Mandarin Chinese, Korean, Spanish, French,
Portuguese, and Swedish. Both cmn and zho select Mandarin; Cantonese (yue)
is a separate language and uses the fallback.
Other languages use Epitran, with their
default script resolved automatically (e.g. Russian rus-Cyrl, Hindi
hin-Deva). A failure in a supported Piper backend is reported rather than
silently switching providers. English does not require Flite’s lex_lookup
or eSpeak; Python language packages are included in the extra. Language
resources may download on first use.
The DP compares IPA directly, preserving distinctions such as nasalization,
vowel length, and tone. Piper’s language-specific phone/tone labels are
converted to IPA before comparison. References only determine grouping;
they never replace the observed phones. Alternate scripts and code-switched
words can use pronunciation overrides.
Pass --pronunciations pronunciations.csv to supply dialect forms or words
in unsupported languages. For example:
word,ipa
wug,wʌɡ
bonjour,bɔ̃ʒuʁ
the cat,ðəkæt
The header is required. Use standard CSV quoting for cells containing commas.
Words are matched without case; empty cells and duplicate words are errors.
An unknown pronunciation or invalid audio window fails the file without
overwriting it. A word without aligned phones receives …. Insertions between
word anchors attach to the preceding word;
review inferred boundaries, especially around reduced or atypical speech.
Python pipelines can compose recipes.phonetic(phonetic_backend=backend, utr_backend=...) with existing tasks. Custom backends implement the Phonetic
marker and typed PhoneticInput/PhoneticOutput contract; the Rust runner owns
CHAT extraction, result validation, and tier insertion.
ai
Accepts the shared input selection and -o/--out options above.
| Option or argument | Default | Details |
|---|---|---|
INSTRUCTION | Required | Instruction applied to every utterance. |
--engine | dspy | Choices: dspy. |
--model | zai-org/GLM-5.2 | DSPy LM model string. |
--max-tokens | 1024 | Maximum output tokens for the DSPy LM call. |
--timeout | 30 | Per-utterance DSPy LM timeout in seconds. |
daemon
| Option or argument | Default | Details |
|---|---|---|
--host | 127.0.0.1 | Bind address. Use 0.0.0.0 to accept off-host connections; default loopback-only so an unsecured daemon can’t be exposed accidentally. |
--port | 8765 | Bind port. |
--workers | 1 | Worker process count. Pinned to 1 by default — the in-memory job registry is per-process. Overriding requires a shared registry backend (not yet wired). |
--log-level | info | uvicorn log level: critical/error/warning/info/debug/trace. |
--access-log/--no-access-log | True | Emit HTTP access logs (one line per request). |
--proxy-headers/--no-proxy-headers | True | Trust X-Forwarded-* headers from the upstream reverse proxy. Combine with –forwarded-allow-ips when fronted by nginx/ALB. |
--forwarded-allow-ips | 127.0.0.1 | Comma-separated upstream IPs trusted for X-Forwarded-. Use ‘’ only when the daemon is behind a trusted proxy. |
--graceful-timeout | 30 | Seconds to wait for in-flight requests to drain on SIGTERM. |
--dev | False | Development mode: enable –reload, drop production defaults. Never use in production — disables clean shutdown handling. |
cache
batchalign cache path
batchalign cache stats
batchalign cache clear [--yes]
version
batchalign version
Removed or unregistered interfaces
The current command registry does not expose serve, jobs, logs, setup,
doctor, bench, benchmark, eval, or coref. A coreference recipe and backend interface
exist in the Python API, but the module under cli/hidden/ is not registered as
a public command. Old server and benchmark examples are not current CLI syntax.
Python API reference
The batchalign Python package exposes a Rust-backed Pipeline, task and input
types, backend classes, and recipe functions. The CLI uses this API too.
For parsing, constructing, and editing transcripts directly, see
Python CHAT documents. The CHATFile, Speaker,
Utterance, and Media types use the Rust CHAT model and derive participant
headers from utterance speaker choices.
Run a recipe
import batchalign as ba
from batchalign.inputs import chat_from_path
pipeline = ba.recipes.morphotag(
stanza_backend=ba.StanzaBackend(),
workers=4,
)
results = pipeline.run([chat_from_path("sample.cha")])
workers limits concurrent files. A recipe supplies a task sequence and backend
instances to Pipeline; backend constructors hold model-specific settings.
pipeline.run() returns outcomes. It does not perform the CLI’s output-file
writing step. See the outcome type and serialization methods in
crates/batchalign/batchalign-engine/src/py_outcome.rs when integrating output.
The ordinary return-value path prepares inputs and retains outcomes for the returned list. File concurrency alone therefore does not bound total memory for a large API call. The CLI uses the callback path to convert inputs within its dispatch window and write completed outcomes without retaining the full result set.
Paired acoustic measurements
ba.AvqiMediaInput(sustained_vowel=..., continuous_speech=..., source_id=...)
supplies the two recordings to ba.recipes.avqi(avqi_backend=ba.AvqiBackend()).
The backend requires the avqi installation extra.
Successful AVQI outcomes have kind == "Metrics". Read
outcome.metrics["rows"][0]["columns"] to access the measurements without
consuming the outcome. outcome.metrics is None for other kinds or after an
outcome has been consumed by write(). Check outcome.is_failed and
outcome.error before reading measurements.
See AVQI for its input and measurement contract.
Cache policy
Recipes forward pipeline options such as cache:
pipeline = ba.recipes.morphotag(
stanza_backend=ba.StanzaBackend(),
cache=ba.CacheSpec.bypass(),
workers=1,
)
| Policy | Reads saved results | Writes new results |
|---|---|---|
ba.CachePolicy.Use (default) | Yes | Yes |
ba.CachePolicy.Bypass / ba.CacheSpec.bypass() | No | No |
ba.CachePolicy.Refresh / ba.CacheSpec.refresh() | No | Yes |
To use a separate database:
cache = ba.CacheSpec(path="/path/to/cache.lmdb", policy=ba.CachePolicy.Use)
The CLI’s cache-management commands target the default path returned by
ba.default_cache_path(). They do not discover custom API cache paths.
API source
python/batchalign/__init__.py: exported types and lazy imports.python/batchalign/recipes.py: standard task compositions.python/batchalign/inputs.py: file-based input constructors.python/batchalign/backends/: backend constructors and interfaces.crates/batchalign/batchalign-engine/src/pipeline.rs: pipeline constructor and execution.
The old BA2 BatchalignPipeline and document model are not interchangeable with
this API. Use the current types when migrating integrations.
Python CHAT documents
batchalign.chat exposes four Rust-backed types: CHATFile, Speaker,
Utterance, and Media. Python imports these types from batchalign._core;
parsing, validation, storage, and edits happen in Rust using the TalkBank model.
CHATFile, Media, and Utterance are also available directly from batchalign.
Import the CHAT Speaker from batchalign.chat; batchalign.Speaker remains
the diarization backend base class.
Create a document
from batchalign.chat import CHATFile, Media, Speaker, Utterance
child = Speaker(
"CHI",
language="eng",
corpus="example",
role="Target_Child",
name="Sam",
)
chat = CHATFile.new()
chat.media = Media("recording", media_type="audio")
chat.utterances.append(
Utterance(child, "I want a cookie .", timing=(1000, 2500))
)
print(len(chat)) # 1: the number of utterances
print(chat.stringify())
Speaker(code, *, language, corpus, role="Participant", name=None) requires
explicit language and corpus information. language accepts a language-code
string or a list of codes for a multilingual speaker. Codes use CHAT’s ISO 639-3
form, such as eng, fra, and nld. Speaker values are immutable; replace an
utterance’s speaker to change its participant metadata.
Utterance(speaker, text, *, timing=None) takes a Speaker and CHAT main-tier
content, including its terminator. It does not take the *CHI: prefix. Timing
is either None or a pair of nonnegative integer milliseconds with start less
than end. Put timing in timing, rather than embedding a bullet in text.
An empty CHATFile.new() is an editable draft. Participant headers appear when
utterances are added. No placeholder speaker, corpus, or language is invented.
Read and write
with open("input.cha", encoding="utf-8") as fd:
chat = CHATFile.read(fd)
copy = CHATFile.parse(chat.stringify())
copy_from_lines = CHATFile.parse(chat.stringify().splitlines())
with open("output.cha", "w", encoding="utf-8") as fd:
chat.write(fd)
assert str(chat) == chat.stringify()
parse accepts a string or a list of strings. List entries may include their
line endings. read and write take open text streams and leave them open.
They operate from the stream’s current position. Binary streams and paths are
not accepted in place of text streams.
Serialization uses canonical CHAT formatting. Parsed dependent tiers, participant ID fields (including age, sex, group, education, and custom fields), and unrelated headers such as dates and comments are preserved. Comments retain their position relative to existing utterances.
Navigate and edit utterances
utterance = chat.utterances[0]
print(utterance.speaker.code)
print(utterance.words) # read-only tuple of word-timing units
print(utterance.timing) # (start_ms, end_ms), or None
print(utterance.tiers["pho"])
utterance.timing = (1200, 2700)
utterance.tiers["com"] = "reviewed by the transcriber"
utterance.text, .speaker, and .timing are editable. .words is a read-only
tuple obtained through the model’s word-timing traversal; it handles CHAT groups
and annotations rather than splitting text on spaces. Edit .text to change
the main tier.
.tiers is a live mapping from labels without % (for example pho, mor,
gra, and com) to CHAT tier content strings. Read, assign, delete, iterate,
and use len on it. Assigning an existing label replaces that tier in place.
Edits validate all dependent tiers together; for example, %gra requires
compatible %mor content. An invalid local edit raises before changing the
utterance. Editing text can fail if existing dependent tiers no longer align.
chat.utterances supports iteration, integer indexing, read slices, append,
insert, integer replacement and deletion, pop, and clear. Negative indices
follow Python conventions. Slices return lists; slice assignment is not supported.
The collection stores live utterance objects. Appending an object and then editing that object updates the document. Inserting or removing other utterances does not invalidate existing handles. A removed utterance remains usable but no longer contributes to that document. Appending the same object to multiple documents shares its edits. Iteration takes a snapshot of the collection’s references, while the referenced utterances remain live.
Derived participant metadata
print(chat.speakers) # tuple of Speaker values
print(chat.languages) # tuple of distinct language codes
print(chat.corpora) # tuple of distinct corpus names
print(chat.utterances[0].speaker.languages)
These document properties are derived from referenced speakers in first-use
order. Languages also include resolved utterance and word-level language choices.
If regenerating the language order changes the file default, serialization adds
an explicit language precode where needed to preserve an utterance’s meaning.
These properties and their contents are read-only: assignment or mutation raises.
@Participants, @ID, and @Languages are generated from those speakers.
Silent participants are omitted from this Python API and its serialized output.
Two utterances using the same speaker code must agree on participant metadata.
Collection insertion and replacement reject conflicting speaker definitions.
Media and validation
Media(filename, *, media_type="audio", status=None) represents @Media.
filename is a CHAT media basename without an extension. media_type accepts
audio, video, or missing; status accepts None, missing, unlinked,
or notrans. Media values are immutable.
chat.media = Media("recording", media_type="audio", status="unlinked")
print(chat.media.filename)
chat.media = None # remove @Media
There is no generic header type or editable header mapping. Participant headers are derived; media has its own typed property. Other parsed headers are retained.
Wrong input types raise TypeError. Invalid CHAT or metadata values raise
ValueError with model diagnostics; negative unsigned timestamps raise
OverflowError. Missing tier labels raise KeyError, and out-of-range utterance
indices raise IndexError.
Constructors and utterance edits validate local content and tier alignment.
stringify, str, and write also validate document-wide constraints, including
speaker consistency and media linkage. During editing, setting a media declaration
before adding timed utterances is allowed; serializing the resulting document
still requires valid CHAT. Timed transcripts require media; untimed transcripts
declaring media should use an appropriate status such as unlinked.
This API is separate from pipeline inputs. To run a file through a recipe, use the input constructors described in the Python API reference.
Command inputs and outputs
This table describes the current local CLI. -o/--out selects a destination
folder; relative subdirectories are mirrored from the selected inputs’ common
root. Discovery accepts individual paths, recursive directories, and file lists.
See Input selection.
| Command | Inputs | Output | Without -o |
|---|---|---|---|
transcribe | Media; required --lang | CHAT | Write .cha beside the recording |
align | CHAT with resolvable media | CHAT with word timings | Update source transcript |
morphotag | CHAT | CHAT with %mor/%gra | Update source transcript |
utseg | CHAT | CHAT with revised utterance boundaries | Update source transcript |
translate | CHAT | CHAT with %eng translation tiers | Update source transcript |
ai | CHAT and an instruction | Edited CHAT | Update source transcript |
compare | CHAT with a sibling gold reference | Comparison metrics | Write metrics beside inputs |
diarize | Timed CHAT with resolvable media | CHAT with revised speaker assignments | Update source transcript |
convert | Media and required --format wav or mp3 | Encoded media | Write beside input; same-format conversion uses .converted in the name |
morphotag strips existing %mor/%gra from staged inputs by default;
--keep-existing preserves them for the engine’s already-tagged check.
convert rejects pre-existing targets and collisions between selected inputs.
The CLI’s per-command collectors and write_outcome in
python/batchalign/cli/_common.py own these output decisions. Python API callers
receive Outcome objects and choose when and where to write them.
Filesystem locations
| Data | Location or resolution |
|---|---|
| Provider configuration | ~/.batchalign.ini (python/batchalign/config.py) |
| Default result cache | OS cache directory plus batchalign/cache.lmdb/; print with batchalign cache path |
| Input-list entries | Relative to the list file’s directory unless absolute |
| Positional input paths | Relative to the invocation directory unless absolute |
| CLI output | -o/--out, or command-specific output beside the input |
| Downloaded models | The selected model library’s own cache/resource directory |
There is no single Batchalign directory that owns all downloaded models. Stanza,
Hugging Face, and other backends use their own loaders. The old
BATCHALIGN_ANALYSIS_CACHE_DIR, BATCHALIGN_MEDIA_CACHE_DIR, and Rust
server.yaml examples do not configure the current result cache.
Python callers select a result-cache path with CacheSpec(path=...).
See Caching and Command I/O.
Processing provenance comments
Successful CHAT pipeline outputs contain a comment for each task in the pipeline’s task order. The current shape is:
@Comment: batchalign <compiled-git-sha> | <task>: <backend-name> | <UTC timestamp>
The placeholders above describe fields, not a literal header to add yourself.
The backend name can encode model/runtime versions and settings. A missing
backend name is recorded as <unknown>.
When a matching batchalign comment for the same task is present, stamping
replaces it in place. Legacy batchalign3 stamps for the same task are also
replaced with the current batchalign name. Comments for other tasks are
preserved. Failed pipeline outcomes are not stamped as successful output for
the whole task sequence.
This records the pipeline configuration, not proof that every backend request
ran freshly: cached results may have been reused.
ASR-generated transcripts also include @Comment: Unchecked output of ASR model.
This is separate from build/task provenance and signals that the transcript
needs review.
Implementation: engine pipeline.rs::stamp_run_provenance and core
utils.rs::stamp_provenance. The earlier bracketed [ba3 command | ...] examples
are not the format emitted by this implementation.
CHAT handling by the pipeline
The Rust core uses TalkBank’s CHAT model and parser. File input conversion enters
through Chat::parse; task runners operate on the resulting typed state, and
outcome writing serializes it. Python CLI code owns path selection and may stage
input text before the Rust parse.
For morphology, staging removes existing %mor/%gra by default, while
--keep-existing retains them. Translation emits %eng. Transcription creates
a new transcript from media. See Command I/O for the complete
input/output table and Morphosyntax for tier alignment checks.
For CHAT syntax, use the shared CHAT format reference. The old Rust-server parse-mode table does not describe this pipeline entrypoint.
CHAT options that affect processing
| Header option | Current runner behavior |
|---|---|
@Options: CA | Morphosyntax skips Conversation Analysis transcripts |
@Options: NoAlign | Forced alignment skips the transcript |
These are task-specific checks, not a universal skip directive for every command.
The CLI’s default morphology staging also removes the obsolete exact header
@Options:\tmulti along with old %mor/%gra tiers.
Source: core taskrunners/morphosyntax.rs, taskrunners/fa.rs, and
python/batchalign/cli/morphotag.py.
Language selection
Language selection is command-specific. A valid language identifier does not by itself establish that a selected model supports that language.
| Entry point | Language source |
|---|---|
transcribe | Required --lang, validated as ISO 639-3 |
morphotag | CHAT @Languages: and applicable utterance-level language markers |
align | Language inferred from selected CHAT input for backend construction |
utseg | Backend --language option, default en |
translate | --target selects output language, default eng |
For transcription, examples include eng (English), spa (Spanish), cmn
(Mandarin), and yue (Cantonese). python/batchalign/lang.py::LanguageCode
normalizes whitespace and case and resolves three-letter identifiers using
pycountry; backends choose the vendor-specific form they require.
Morphosyntax language routing
The Rust runner derives a language specification from CHAT. The Stanza backend resolves that specification to model language codes, groups requests by language configuration, and constructs a single-language or multilingual pipeline as needed. Its process-wide LRU retains at most two language/mode configurations. The CLI groups files by language headers to reduce model switching.
The current CLI does not expose the former --skipmultilang, --no-l2-morphotag,
or --no-pos-hints switches. Older language experiments that use those switches
must not be used as current operational instructions or accuracy guarantees.
For the implemented token and language workarounds, inspect
python/batchalign/backends/morphosyntax/ud/lang.py, its language submodules,
and the core morphology runner. For command syntax, see CLI reference.
Language reference index
Choose a language below for current routing notes and links to earlier studies. Model availability and language-code recognition are separate from analysis quality.
- Dutch —
nld - Portuguese —
por - French —
fra - Italian —
ita - Hebrew —
heb - Japanese —
jpn - Cantonese —
yue - Mandarin —
cmn - Malayalam —
mal
For the shared rules, see Language selection.
Coreference API
The Python API defines a Coref backend interface and a
ba.recipes.coref(coref_backend=...) recipe. This build does not bundle a concrete
coreference backend. The stub under cli/hidden/ is not registered as a public
command.
An integration must supply its own implementation of the interface in
python/batchalign/backends/base.py. See Add an inference backend
and Python API.
Morphosyntax processing contract
The morphotag pipeline adds typed %mor and %gra tiers. Its implementation
spans the Rust runner and Python Stanza backend; linguistic rendering is not
entirely Rust-owned.
Input and language
The Rust runner reads CHAT, skips Conversation Analysis files marked
@Options: CA, and collects utterances that need analysis. Language comes from
@Languages: with utterance-level overrides such as [- hin] where applicable.
The CLI has no morphotag --lang option.
By default, the CLI stages copies with existing %mor and %gra removed before
parsing. --keep-existing leaves them in place for the runner’s already-tagged
check. Clearing tiers does not bypass the backend result cache.
Backend processing
python/batchalign/backends/morphosyntax/stanza.py groups batch requests by
language configuration. It prepares text, runs Stanza, and uses the Python
ud/tokenize.py and ud/render.py modules for token handling and structured
morphological/dependency output. The ud/ language modules contain additional
language-specific behavior.
Preserve mode installs a tokenizer postprocessor to reconcile Stanza tokenization
with the input. --retokenize selects the other mode and permits changes to word
boundaries. The backend’s identity includes the mode and its rendering contract.
Do not treat a model’s raw token count as the CHAT main-tier word count.
A failed batched model call can fall back to individual sentence processing. Pipeline initialization failures propagate as backend failures; an unsupported or broken model is not treated as a successful empty analysis for the whole file.
Applying results
The Rust runner converts the structured backend output into TalkBank model
objects, aligns morphology and dependency tiers with try_align_mor_gra, and
checks the candidate against the main tier before committing it. An utterance
whose analysis cannot be aligned can be skipped with a warning; a completed file
is not a guarantee that every utterance received new analysis.
%gra unit indices, heads, and relations originate in the backend output. The
runner constructs typed relations and the CHAT writer serializes them. Avoid
attributing current dependency-tree behavior to the retired server’s
build_gra_and_validate path.
Scheduling and reuse
The per-file dispatch window is 128 utterances. Stanza’s default engine batch maximum is 128 with a 100 ms collection window. Result caching is enabled. See Performance and Caching.
Source locations
| Concern | Source |
|---|---|
| CLI staging and options | python/batchalign/cli/morphotag.py |
| Extraction, dispatch, typed injection | crates/batchalign/batchalign-core/src/taskrunners/morphosyntax.rs |
| Protocol and cache-key fields | Core proto/morphosyntax.rs |
| Stanza configuration and batching | python/batchalign/backends/morphosyntax/stanza.py |
| Token reconciliation and rendering | Python backend ud/tokenize.py, ud/render.py, language submodules |
For a processing walkthrough, see Add morphology and grammar.
Dependency tiers (%gra)
A %gra item has the form index|head|relation. It describes the grammatical
relation of one morphology unit to its head. Index 0 in the head position denotes
the root convention used by the current backend output.
The Stanza renderer supplies structured indices, heads, and relation labels.
The Rust morphology runner constructs typed grammatical relations and aligns
%mor and %gra using TalkBank model alignment helpers before committing tiers.
A rejected candidate can leave an utterance without new analysis and emit a warning.
The number of dependency units is not necessarily the number of whitespace- separated main-tier tokens: morphology can include clitic components. Consult the morphology contract and the shared dependent-tier reference.
Source: python/batchalign/backends/morphosyntax/ud/render.py and
crates/batchalign/batchalign-core/src/taskrunners/morphosyntax.rs.
Forced-alignment pipeline
The alignment recipe composes optional utterance timing recovery (Utr) and
forced alignment (Fa). The CLI supplies both backends by default, choosing
wav2vec for FA and rev for recovery. Setting --utr-engine none omits recovery.
Timing recovery uses an ASR-capable backend to establish missing utterance timing. The UTR runner can skip work when the input is already timed. FA uses transcript content and prepared audio to request word alignments and applies timing to CHAT. Results travel through the same bounded backend queues and LMDB cache as other tasks. It does not rely on a remote worker process or a separate SQLite audio cache.
Ownership
| Concern | Source |
|---|---|
| Engine/model options and language inference | python/batchalign/cli/align.py |
| Task order | python/batchalign/recipes.py::align |
| Timing recovery and overlap strategies | crates/batchalign/batchalign-core/src/taskrunners/utr/ |
| FA preparation and result application | Core taskrunners/fa.rs |
| Typed backend requests/results | Core proto/utr.rs, proto/fa.rs |
| Local model implementations | python/batchalign/backends/fa/ and ASR backends supporting UTR |
@Options: NoAlign causes the FA runner to skip alignment. For an operational
walkthrough, see Align a transcript. For
scheduling and RSS, see Performance.
Media conversion
batchalign convert accepts media paths and requires --format wav or mp3.
The default recipe selects the native Rust conversion backend and bypasses the
shared result cache. The output is an encoded media file, not a cached temporary
artifact managed by an old server media-cache directory.
batchalign convert recordings/ --format wav -o wav-recordings/
The CLI rejects existing output targets, source-overwriting targets, and two
inputs that would map to the same output. If a same-format conversion is written
beside the input, the name includes .converted to keep it distinct.
Input discovery recognizes common audio/video suffixes, but recognition alone does not establish that every codec/container can be decoded. Consult the conversion backend and test a representative file.
Source: python/batchalign/cli/convert.py, recipes.py::convert,
crates/batchalign/batchalign-core/src/taskrunners/convert.rs, and the core/engine
native conversion backend modules.
TextGrid export
TextGrid is Praat’s annotation format. The current Batchalign CLI does not expose
a TextGrid export command or the former batchalign_core Python export helper.
For CHAT-to-Praat conversion in the wider toolchain, see CLAN documentation for CHAT2PRAAT. Check that the input transcript has the timing required by the converter. Batchalign’s alignment workflow is described in Align a transcript.
English ASR text corrections
The Rust ASR cleanup code applies English-specific orthographic rules when the
language is eng:
| Rule | Example |
|---|---|
| Capitalize the pronoun and supported contractions | i → I, i'm → I'm |
| Strip periods from an allowlist of abbreviations | Dr. → Dr |
| Capitalize the first eligible word of an utterance | hello world . → Hello world . |
These modify spelling directly; they do not add a CHAT replacement annotation. The abbreviation rule runs before token splitting so a title’s period is not mistaken for an utterance boundary. It is an allowlist, not a general instruction to strip periods from arbitrary words or numbers.
The authoritative surfaces and exclusions are in
crates/batchalign/batchalign-core/src/asr/cleanup.rs, including
EN_I_CAP_REWRITES, EN_TITLE_PERIOD_SURFACES, and the pre/post-retokenization
English correction functions. Their invocation order is in asr/prepare.rs
and the ASR assembly path.
Automatic retrace detection
The ASR cleanup pass can mark earlier copies of an immediately repeated word sequence as retraces. Matching is case-insensitive; the word spelling is retained. It is a local repetition heuristic, not a detector of every conversational repair.
Fillers participate in sequence matching but are not themselves changed into
retrace words. Repeating a filler alone therefore does not create a retrace mark.
The minimum sequence length is two for the yue and zho language keys and one
for other keys in the current implementation.
The pass sets typed word kinds. The CHAT builder uses those kinds to construct retrace annotations rather than embedding bracket syntax in word text. Review these automatic decisions against the recording.
Source: crates/batchalign/batchalign-core/src/asr/cleanup.rs::apply_retrace_detection.
For CHAT notation, see Retraces and repetitions.
Wheel platform reference
The current Python wheel workflows build these native platforms:
| Platform | CI runner |
|---|---|
| macOS ARM64 | macos-14 |
| macOS x86-64 | macos-15-intel |
| Linux x86-64 | ubuntu-latest |
| Linux ARM64 | ubuntu-24.04-arm |
| Windows x86-64 | windows-latest |
The extension wheel uses cp310-abi3. Linux builds target manylinux 2.28 through
the wheel builder. The wheel smoke matrix installs and imports on Python 3.10.
Optional model libraries can have narrower platform support than the core wheel.
The bootstrap scripts select Python 3.11 and install batchalign[all]. Desktop
bundles are separate artifacts. See Install Batchalign
and Package and release surfaces.
Source: .github/workflows/publish-pypi.yml, bazel-wheels.yml, and
python/pyproject.toml.
Batchalign source map
| Location | Responsibility |
|---|---|
crates/batchalign/batchalign-core/ | Typed tasks, task runners, CHAT processing, ASR cleanup, protocol schemas |
crates/batchalign/batchalign-engine/ | PyO3 runtime, pipelines, backend routing, batching, LMDB, outcomes |
python/batchalign/cli/ | Typer CLI, input selection, terminal UI, output handling |
python/batchalign/backends/ | Model and service adapters, including Stanza token processing and rendering |
python/batchalign/recipes.py | Standard task compositions |
python/batchalign/api.py | FastAPI recipe endpoints and in-memory job lifecycle |
apps/batchalign/batchalign-gui/ | React/Tauri desktop application |
bazel/python/ | Wheel, PyApp, and protocol build integration |
just/batchalign.just | Product build, test, and CLI recipes |
The Python package imports the extension as batchalign._core. Typed protocol
schemas come from the Rust core; Bazel generates the Python wire types.
TalkBank parser, model, and transform crates supply the CHAT representation
used by the core. Their Git revision and version constraints are declared in
crates/batchalign/batchalign-core/Cargo.toml; the root manifest does not
centralize dependencies in a [workspace.dependencies] table.
For execution flow, see How a processing command runs.
Python versions and wheel tags
python/pyproject.toml declares Python >=3.10. The extension uses CPython’s
stable ABI, with release wheels tagged cp310-abi3 for each supported platform.
The wheel CI smoke test installs and imports the package on Python 3.10.
The user bootstrap scripts select Python 3.11 for batchalign[all]. This is
separate from the minimum version supported by the core wheel. Optional model
libraries can impose additional interpreter or platform constraints.
Use the bootstrap-selected interpreter for the documented end-user installation.
A stable-ABI tag is not a claim that every model extra works on every newer or
free-threaded Python build. See python/pyproject.toml, bootstrap/, and the
wheel workflows before changing interpreter support.
Package and release surfaces
| Surface | Source of truth |
|---|---|
| Python distribution name, version, dependencies, scripts | python/pyproject.toml (batchalign) |
| Rust workspace version | Root Cargo.toml |
| Rust dependencies and features | Each crate’s Cargo.toml |
| Native wheel matrix | .github/workflows/publish-pypi.yml |
| Installed wheel smoke checks | .github/workflows/bazel-wheels.yml |
| Desktop bundle | apps/batchalign/batchalign-gui/ and its Bazel targets |
| HTTP service | python/batchalign/api.py, cli/daemon.py |
The Python distribution provides the CLI, Python API, and compiled engine. A desktop bundle and a Python wheel are separate artifacts. Their versions and release procedures should not be inferred from obsolete server-era version tables.
For the release procedure, see Release the Python package.
Historical studies and decisions
These records describe earlier implementations, model probes, or proposals. They are useful for understanding why earlier choices were made, but are not current command instructions, support guarantees, or measurements of version 0.10.1. The links identify a fixed repository revision so the evidence does not drift.
For current behavior, use CLI reference, Morphosyntax, Language selection, and Pipeline architecture.
| Record | Scope |
|---|---|
| L2 Morphotag: Per-Word Code-Switching Analysis | Per-word code-switching design and its earlier evaluation |
| L2 Morphotag: Current Status | An earlier implementation-status and accuracy report |
| Literature Review: Code-Switching Morphosyntactic Analysis | Literature considered for the earlier code-switching design |
| Rev.AI Language Quality Strategy | A proposed Rev.AI quality-assessment strategy |
| Stanza Limitations — Observed Defects with Version Pinning | Version-specific model observations and former mitigation claims |
| Algorithms, Language, and Alignment Migration | A comparison of earlier BA2 and Rust-server algorithms |
| BA2 Architecture Reference | The BA2 implementation baseline |
| Batchalign2 CLI Reference (Baseline) | The BA2 command-line baseline |
| Why Replace Python CHAT Handling with Rust | The rationale for an earlier ownership migration |
| Arena Allocators (Evaluation — Not Used) | An earlier allocator evaluation |
| Models Training Runtime ADR | An earlier model-training/runtime decision |
| Lenient Parsing | An earlier parser-policy decision |
| Trait-Based Dispatch | An earlier algorithm-dispatch decision |
| Release Readiness State Machine | An earlier release-state proposal |
Documentation scope and maintenance
This book documents the products present in the Batchalign repository:
the Python CLI and backends, Rust core and engine, HTTP service, and desktop
application. The workspace membership in Cargo.toml, Python command registry,
just recipes, and release workflows are the implementation references.
Current organization
- Tutorials introduce a first Batchalign workflow.
- How-to guides cover user tasks and contributor workflows.
- Reference pages describe commands, data contracts, and CHAT notation.
- Explanations describe the current pipeline and runtime.
- Related tools identifies the separately maintained Chatter, CLAN, and editor documentation.
The old CLAN, Chatter, VS Code, parser-development, and combined-toolchain operations manuals have been removed. They described products or source paths that are no longer in this repository. Consolidated Batchalign pages are HTML redirects rather than duplicate chapters or a large previous-locations menu. Historical research is linked from Historical studies and decisions.
Maintaining the book
Edit book/src/SUMMARY.md when adding or reorganizing chapters. Update incoming
links when consolidating a page, and add an output.html.redirect entry in
book/book.toml for a retired published URL. Link to the owning project’s
documentation for external products instead of copying their install or release
instructions into this book.
Validate with just docs build and just docs linkcheck. The Bazel-backed recipes
provide the configured mdBook, Mermaid, and link-check tools. Compare examples
against just batchalign cli COMMAND --help; model accuracy claims require
separate measurements and must identify their fixtures and environment.
Cantonese processing reference
The transcription language code is yue. For morphology, use the appropriate
CHAT @Languages: header; there is no morphotag --lang option.
The current Stanza language mapping uses Traditional Chinese. This does not establish Cantonese model accuracy. See Process Cantonese for command examples.
Language resolution and processor selection are defined in
python/batchalign/backends/morphosyntax/ud/lang.py and stanza.py.
Backend availability and linguistic quality must be checked for the actual model
and input; a recognized language code alone is not a support guarantee.
See Language selection, Morphosyntax, and CLI reference.
The earlier Cantonese study contains model probes and implementation notes from a previous architecture. Its measurements and mitigation claims have not been revalidated by this documentation update.
Mandarin processing reference
The transcription language code is cmn. For morphology, use the appropriate
CHAT @Languages: header; there is no morphotag --lang option.
Use a Mandarin recording language code for transcription. Stanza mapping goes through ud/lang.py; the backend normalizes resolved zh to zh-hans. Do not assume every ISO alias has an alpha-2 mapping.
Language resolution and processor selection are defined in
python/batchalign/backends/morphosyntax/ud/lang.py and stanza.py.
Backend availability and linguistic quality must be checked for the actual model
and input; a recognized language code alone is not a support guarantee.
See Language selection, Morphosyntax, and CLI reference.
The earlier Mandarin study contains model probes and implementation notes from a previous architecture. Its measurements and mitigation claims have not been revalidated by this documentation update.
Japanese processing reference
The transcription language code is jpn. For morphology, use the appropriate
CHAT @Languages: header; there is no morphotag --lang option.
The current Stanza configuration selects the combined package for Japanese. Japanese rendering helpers are in ud/ja/. Check word boundaries in both preserve and retokenize modes.
Language resolution and processor selection are defined in
python/batchalign/backends/morphosyntax/ud/lang.py and stanza.py.
Backend availability and linguistic quality must be checked for the actual model
and input; a recognized language code alone is not a support guarantee.
See Language selection, Morphosyntax, and CLI reference.
The earlier Japanese study contains model probes and implementation notes from a previous architecture. Its measurements and mitigation claims have not been revalidated by this documentation update.
Hebrew processing reference
The transcription language code is heb. For morphology, use the appropriate
CHAT @Languages: header; there is no morphotag --lang option.
Review the rendered morphology and right-to-left text in an editor that supports the script. A model name from an older page is not an automatic current ASR selection.
Language resolution and processor selection are defined in
python/batchalign/backends/morphosyntax/ud/lang.py and stanza.py.
Backend availability and linguistic quality must be checked for the actual model
and input; a recognized language code alone is not a support guarantee.
See Language selection, Morphosyntax, and CLI reference.
The earlier Hebrew study contains model probes and implementation notes from a previous architecture. Its measurements and mitigation claims have not been revalidated by this documentation update.
French processing reference
The transcription language code is fra. For morphology, use the appropriate
CHAT @Languages: header; there is no morphotag --lang option.
French-specific rendering helpers are in python/batchalign/backends/morphosyntax/ud/fr/. Include contractions and clitic elisions in a review sample.
Language resolution and processor selection are defined in
python/batchalign/backends/morphosyntax/ud/lang.py and stanza.py.
Backend availability and linguistic quality must be checked for the actual model
and input; a recognized language code alone is not a support guarantee.
See Language selection, Morphosyntax, and CLI reference.
The earlier French study contains model probes and implementation notes from a previous architecture. Its measurements and mitigation claims have not been revalidated by this documentation update.
Italian processing reference
The transcription language code is ita. For morphology, use the appropriate
CHAT @Languages: header; there is no morphotag --lang option.
Italian handling spans ud/it/, the shared tokenizer, and renderer. The backend identity currently includes its native-MWT rendering contract; old Rust reconciler tables are not the current source map.
Language resolution and processor selection are defined in
python/batchalign/backends/morphosyntax/ud/lang.py and stanza.py.
Backend availability and linguistic quality must be checked for the actual model
and input; a recognized language code alone is not a support guarantee.
See Language selection, Morphosyntax, and CLI reference.
The earlier Italian study contains model probes and implementation notes from a previous architecture. Its measurements and mitigation claims have not been revalidated by this documentation update.
Portuguese processing reference
The transcription language code is por. For morphology, use the appropriate
CHAT @Languages: header; there is no morphotag --lang option.
Check preposition/article contractions and apostrophe forms in the rendered morphology.
Language resolution and processor selection are defined in
python/batchalign/backends/morphosyntax/ud/lang.py and stanza.py.
Backend availability and linguistic quality must be checked for the actual model
and input; a recognized language code alone is not a support guarantee.
See Language selection, Morphosyntax, and CLI reference.
The earlier Portuguese study contains model probes and implementation notes from a previous architecture. Its measurements and mitigation claims have not been revalidated by this documentation update.
Dutch processing reference
The transcription language code is nld. For morphology, use the appropriate
CHAT @Languages: header; there is no morphotag --lang option.
Contractions and apostrophes should be checked against the shared tokenizer and renderer.
Language resolution and processor selection are defined in
python/batchalign/backends/morphosyntax/ud/lang.py and stanza.py.
Backend availability and linguistic quality must be checked for the actual model
and input; a recognized language code alone is not a support guarantee.
See Language selection, Morphosyntax, and CLI reference.
The earlier Dutch study contains model probes and implementation notes from a previous architecture. Its measurements and mitigation claims have not been revalidated by this documentation update.
Malayalam processing reference
The transcription language code is mal. For morphology, use the appropriate
CHAT @Languages: header; there is no morphotag --lang option.
The CLI includes a malayalam ASR engine backed by Wav2Vec2 and a Malayalam segmentation implementation. That does not imply a usable Stanza morphology model. Verify the backend required by the task.
Language resolution and processor selection are defined in
python/batchalign/backends/morphosyntax/ud/lang.py and stanza.py.
Backend availability and linguistic quality must be checked for the actual model
and input; a recognized language code alone is not a support guarantee.
See Language selection, Morphosyntax, and CLI reference.
The earlier Malayalam study contains model probes and implementation notes from a previous architecture. Its measurements and mitigation claims have not been revalidated by this documentation update.
CHAT format: reference
Look up syntax, contracts, and factual details.
- Overview
- Headers
- Utterances
- Retraces and Repetitions
- Replacements
- Untranscribed Markers (xxx, yyy, www)
- Postcodes
- Dependent Tiers
- The %mor Tier
- Phon Tiers
- Word Syntax
- Symbols
CHAT Format Overview
Status: Reference Last updated: 2026-05-11 21:51 EDT
CHAT (Codes for the Human Analysis of Transcripts) is a standardized transcription format for spoken language data, developed by Brian MacWhinney as part of the CHILDES and TalkBank projects. It is the most widely used format in child language research and conversational analysis.
File Anatomy
Every CHAT file follows this structure:
@UTF8
@Begin
@Languages: eng
@Participants: CHI Target_Child, MOT Mother
@ID: eng|corpus|CHI|2;6.||||Target_Child|||
@ID: eng|corpus|MOT|||||Mother|||
*MOT: what do you want ?
%mor: ADV|what AUX|do PRON|you VERB|want ?
%gra: 1|4|LINK 2|4|AUX 3|4|SUBJ 4|0|ROOT 5|4|PUNCT
*CHI: I want cookie .
%mor: PRON|I VERB|want NOUN|cookie .
%gra: 1|2|SUBJ 2|0|ROOT 3|2|OBJ 4|2|PUNCT
@End
A CHAT file consists of:
@UTF8— required first line, declares UTF-8 encoding@Begin— marks the start of the transcript- Headers — lines starting with
@that provide metadata (participants, languages, IDs, etc.) - Utterances — blocks consisting of:
- A main tier (line starting with
*SPEAKER:) containing the transcribed speech - Zero or more dependent tiers (lines starting with
%tier:) containing annotations
- A main tier (line starting with
@End— marks the end of the transcript
Key Conventions
- Tab separation: a tab character separates the tier prefix from its content (e.g.,
*CHI:⟶content) - Terminators: every utterance ends with a terminator (
.,?,!, or special forms like+...) - Line continuation: long lines wrap with a tab at the start of continuation lines
- Speaker codes: short identifiers — the validator accepts up to seven characters from
A-Z,0-9,_,-,'; three uppercase letters is the convention (e.g.,CHI,MOT,FAT,INV) - Media linking: timestamps link transcripts to audio/video via bullet markers
CHAT vs Other Formats
| Feature | CHAT | Praat TextGrid | ELAN EAF |
|---|---|---|---|
| Morphological tiers | Built-in (%mor, %gra) | No | No |
| Dependency syntax | Built-in (%gra) | No | No |
| Standardized POS | UD-style via %mor | No | No |
| Word-level alignment | %wor tier | Interval-based | Interval-based |
| Error recovery | Tree-sitter GLR | N/A | N/A |
References
- CHAT Manual — the canonical reference
- TalkBank — the data repository
Headers
Status: Reference Last updated: 2026-05-11 20:30 EDT
Headers are lines beginning with @ that provide metadata about the transcript. They appear between @Begin and the first utterance (though some headers like @Comment can appear anywhere).
Required Headers
@UTF8
Must be the very first line of every CHAT file. Declares UTF-8 encoding.
@UTF8
@Begin / @End
Mark the start and end of the transcript body. Every CHAT file must have exactly one @Begin and one @End.
@Participants
Declares all speakers in the transcript. Format:
CODE [Name] Role, comma-separated. The role is required; the name
is optional, so each entry is either CODE Role or CODE Name Role.
@Participants: CHI Target_Child, MOT Mother, FAT Father
@Participants: CHI Alex Target_Child, MOT Mary Mother
In the first line, Target_Child, Mother, and Father are roles,
not names. In the second line, Alex and Mary are optional names
sitting between the speaker code and the role.
Speaker codes are short identifiers — the validator accepts up to
seven characters from A-Z, 0-9, _, -, and '. The convention
is three uppercase letters; the most common codes are:
CHI— target childMOT— motherFAT— fatherINV— investigatorOBS— observer
@ID
Provides detailed metadata for each participant. One @ID line per participant.
@ID: eng|corpus|CHI|2;6.||||Target_Child|||
Fields (pipe-separated): language, corpus, speaker code, age, sex, group, SES, participant role, education, custom field.
Age format: years;months.days (e.g., 2;6. = 2 years, 6 months).
SES field: ethnicity (White, Black, Asian, Latino, Pacific, Native, Multiple, Unknown), socioeconomic code (UC, MC, WC, LI), or combined with comma separator (e.g., White,MC).
Optional Headers
@Languages
Declares the language(s) used in the transcript.
@Languages: eng, fra
@Date
Recording date in DD-MON-YYYY format.
@Date: 15-JAN-2024
@Location
Where the recording took place.
@Location: Boston, MA, USA
@Situation
Description of the recording context.
@Situation: free play with toys in lab
@Activities
Activities during the recording.
@Activities: toyplay, reading
@Comment
Free-form comments. Can appear anywhere in the file (before, between, or after utterances).
@Comment: child was tired during this session
@Media
Links the transcript to an audio or video file.
@Media: session01, audio
@Transcriber / @Coder
Identifies who created or coded the transcript.
@Transcriber: JDS
@Coder: ABC
Header Ordering
Headers should follow this conventional order:
@UTF8(required, first line)@Begin(required)@Languages@Participants(required)@IDlines (one per participant)- Other metadata headers (
@Date,@Location, etc.) @Commentlines (can also appear later)
Validation
The parser validates header structure including:
@UTF8must be the first non-empty line@Beginand@Endare required and must appear exactly once@Participantsis required and must declare all speakers used in utterances@IDparticipant codes must match@Participantsdeclarations- Age format validation in
@IDlines
Utterances
Status: Reference Last updated: 2026-05-11 23:22 EDT
An utterance is the fundamental unit of a CHAT transcript. It consists of a main tier (the transcribed speech) followed by zero or more dependent tiers (annotations).
Main Tier
The main tier begins with *SPEAKER: followed by a tab and the utterance content, ending with a terminator.
*CHI: I want a cookie .
Speaker Codes
Speaker codes are short identifiers (up to seven characters from A-Z, 0-9, _, -, '; three uppercase letters is the convention) matching a code declared in @Participants:
@Participants: CHI Target_Child, MOT Mother
*MOT: what do you want ?
*CHI: cookie .
Terminators
Every utterance must end with a terminator:
| Terminator | Meaning |
|---|---|
. | Declarative (period) |
? | Question |
! | Exclamation |
+... | Trailing off |
+..? | Trailing-off question |
+/. | Interruption |
+//. | Self-interruption |
+/? | Interrupted question |
+!? | Broken question |
+"/. | Quotation follows on next line |
Line Continuation
Long utterances wrap to the next line with a leading tab:
*MOT: well I think that we should probably go to
the store and get some more cookies .
Content Items
The content between *SPEAKER: and the terminator consists of content items separated by whitespace:
- Words — regular words, potentially with annotations
- Groups — bracketed content like
<word word>for overlap, retrace, etc. - Special forms — pauses
(.), events&=laughs, fillers&-uh - Separators — commas
,and other punctuation
Words
Words are the primary content unit. See Word Syntax for full details.
Groups
Angle brackets < > group words for annotations:
*CHI: <I want> [/] I want cookie .
Common group annotations:
[/]— partial retrace (speaker repeats the same words)[//]— full retrace (speaker restarts with different words)[///]— multiple retracing (multiple false starts)[/-]— reformulation (speaker rephrases with different structure)[?]— uncertain transcription
Special Forms
*CHI: um (.) I want &-uh cookie .
(.)— short pause(..)— medium pause(...)— long pause(1.5)— timed pause in seconds&=laughs— paralinguistic event&-uh— filler
Media Linking
Utterances can include media timestamps (bullets) that link to audio/video:
*CHI: I want cookies . •1234_5678•
The numbers represent start and end times in milliseconds. The bullets
delimiting the pair render as • in most editors; on disk they are
the NAK control character (U+0015). See the CHAT manual for syntax.
Dependent Tiers
See Dependent Tiers for documentation on %mor, %gra, %pho, %wor, and other annotation tiers that follow the main tier.
Retraces and Repetitions
Status: Current Last updated: 2026-05-11 23:16 EDT
Retraces mark content that the speaker said but then corrected, repeated, or abandoned. They are one of the most consequential constructs in CHAT because they affect how every dependent tier aligns to the main tier.
CHAT Syntax
A retrace has two parts: the retraced content (what the speaker said first) and the correction (what follows). The retraced content is marked with a trailing bracket code:
| Marker | Name | Meaning |
|---|---|---|
[/] | Partial repetition | Speaker repeats the same words |
[//] | Full correction | Speaker restarts with different words |
[///] | Multiple correction | Multiple false starts |
[/-] | Reformulation | Speaker rephrases with different structure |
Single-Word Retraces
When only one word is retraced, no angle brackets are needed:
*CHI: I [/] I want that .
*CHI: ana [//] an .
*MOT: the book [/-] the magazine is here .
Group Retraces
When multiple words are retraced, angle brackets delimit the scope:
*MOT: <the dog> [//] the cat ran .
*CHI: <I want> [/] I need cookie .
*CHI: <I want the> [///] give me that .
Retraces with Replacements
A retraced word often has a replacement [: target] and/or error code
[* code]. This is common in aphasia and child language corpora where
the speaker produces an incorrect form:
*PAR: tika@u [: kitty] [* p:n] [//] kitty is nice .
%mor: noun|kitty aux|be-Fin-Ind-Pres-S3 adj|nice-S1 .
*PAR: lɛɾɪ@u [: later] [* p:n] [//] later in the day .
%mor: adv|late adp|in det|the-Def-Art noun|day .
*CHI: male [: female] [* s:r] [/] male [: female] [* s:r] .
%mor: adj|female-S1 .
In each case, the retraced word (before the [//] or [/]) is excluded
from %mor alignment. Only the correction (after the marker) is counted.
Alignment Behavior
Retraces interact differently with each dependent tier domain:
flowchart TD
RT["Retrace node\n(e.g. 'tika@u [: kitty] [* p:n] [//]')"]
RT -->|"Mor domain"| SKIP["SKIP\n(return 0)\nNot morphologically analyzed"]
RT -->|"Pho domain"| COUNT["COUNT\nPhonologically produced"]
RT -->|"Sin domain"| COUNT2["COUNT\nGesturally produced"]
RT -->|"Wor domain"| COUNT3["RECURSE\napply retrace-aware %wor leaf rule"]
style SKIP fill:#faa,stroke:#333
style COUNT fill:#afa,stroke:#333
style COUNT2 fill:#afa,stroke:#333
style COUNT3 fill:#afa,stroke:#333
Why %mor skips retraces: The %mor tier represents the morphological analysis of what the speaker meant to say. Retraced content is a false start or error — it was produced phonologically but is not part of the intended linguistic structure. The correction after the retrace marker carries the morphological analysis.
Why %pho/%sin/%wor include retraces: These tiers document what was actually produced — the sounds, gestures, and timing of the speech as it happened, including false starts. The retrace was physically spoken, so it appears in these tiers.
For %wor, retrace ancestry does not change leaf-level membership:
- spoken word tokens count both inside and outside retrace
- that includes fillers, fragments, nonwords, and untranscribed placeholders
- overlap annotations do not affect
%wormembership
Exact corpus-shaped contrast:
*CHI: <one &+ss> [/] one play ground .
%wor: one •321008_321148• ss •321148_321368• one •321809_321969• play •322049_322310• ground •322390_322890• .
*CHI: &+ih <the what> [/] what's letter &+th is this ?
%wor: ih •49063_49103• the •49103_49163• what •49183_50205• what's •50205_50405• letter •50405_50685• th •50886_50946• is •50946_51046• this •51086_51586• ?
Implementation and related guidance
Parser representation and validation belong to Chatter. For Batchalign’s treatment of ASR output, see Retrace detection.
Replacements
Status: Current Last updated: 2026-05-11 23:14 EDT
A replacement is a CHAT annotation [: ...] that pairs a single
spoken word on the main tier with one or more “intended” words. It
records both what the speaker actually said and what the analysis should
treat the utterance as containing.
*CHI: wanna [: want to] go .
*CHI: dis [: this] is fun .
*CHI: rocking+house [: rocking+horse] [*] ?
This page is the canonical reference for what replacements mean in TalkBank — both as a CHAT-manual construct and as a typed AST in this repo. The most important load-bearing fact, which the rest of the page expands on:
Replacements are word-level, not group-level. Each tier domain chooses one side of the pair:
%moranalyzes the replacement (right side);%wor,%pho,%sinalign to the original (left side).%grafollows%mor.
CHAT Syntax
Word-Level Scope
A replacement attaches to a single standalone_word on the main tier
and contains one or more replacement words inside the brackets:
*CHI: gonna [: going to] eat lunch .
*CHI: dis [: this] toy .
*CHI: rocking+house [: rocking+horse] [*] ?
Replacement words can be separated
by whitespace, so [: going to] is a single replacement of gonna
with two words.
There Is No Group-Level Replacement
<dat is> [: that is] is not valid CHAT. A replacement does not
attach to a group; it attaches to a single word. The grammar enforces
this by typing: ReplacedWord.word: Word, never Group. To replace
words inside a group, attach the replacement to the inner word:
*CHI: <dat [: that] is> [/] is broken .
This shape — replacement inside a group inside a retrace — is legal because each annotation operates at its own scope.
There Is No [::] Form
Some literature on CHILDES tooling references a [::] annotation; it
does not exist in this repo’s grammar, parser, or model, and is not
defined by the current CHAT manual. Only [:] exists. If you encounter
[::] in legacy data, treat it as a parse error to investigate, not a
construct to support.
The Per-Domain Alignment Rule
This is the rule contributors most often get wrong. Different tier domains align to different sides of a replacement pair:
| Tier | Side aligned to | Rationale |
|---|---|---|
%mor | replacement (right) | Morphosyntactic analysis annotates the target form, not the error |
%gra | replacement (right) | Grammatical relations align to %mor’s structure |
%wor | original (left) | Word-level timing is for what was actually spoken |
%pho | original (left) | Phonological transcription describes what was actually spoken |
%sin | original (left) | Spelling-in-actual describes the original surface form |
The mnemonic: the replacement encodes the intended form (what the
speaker meant or what a corrected transcript would read). Tiers
analyzing intent (%mor/%gra) use the replacement; tiers
documenting realization (%wor/%pho/%sin) use the original.
flowchart LR
spoken["Original word\n(left of [:)\n'dis'"]
target["Replacement words\n(inside [: ])\n'this'"]
spoken -->|"%wor (timing)"| wor["%wor: dis"]
spoken -->|"%pho (phonology)"| pho["%pho: dɪs"]
spoken -->|"%sin (spelling)"| sin["%sin: dis"]
target -->|"%mor (UD parse)"| mor["%mor: pron|this"]
target -->|"%gra (paired with %mor)"| gra["%gra: 1|0|ROOT"]
For multi-word replacements like gonna [: going to], the rule
generalizes consistently:
%wor/%pho/%sinproduce one entry — forgonna.%morproduces two entries — forgoingandto.%graproduces two entries — paired to the two%moritems.
The full table of per-domain rules is in
resources/spec/docs/ALIGNMENT_RULES.md.
Interactions with Other Annotations
Replacements and Retraces Are Orthogonal
A retrace ([/], [//], [///], [/-]) and a replacement
([:]) are distinct annotations operating at different structural
levels:
- Retraces wrap content (a single word or a group). They are first-
class
UtteranceContentvariants and represent post-hoc speaker correction. - Replacements attach inside a
Wordslot viaReplacedWord. They are editorial metadata about an individual spoken word.
Both can coexist:
*CHI: <dat [: that] is> [/] is broken . (replacement inside retrace)
A retrace cannot live inside a replacement (the grammar wraps
replacements around standalone_word, not arbitrary content).
Replacements and Error Coding
Error codes follow the replacement and operate on the replaced word as a unit:
*CHI: rocking+house [: rocking+horse] [*] ?
Here [*] marks rocking+house as containing a phonological/lexical
error; the [: rocking+horse] records the intended form. The two
annotations cooperate: the replacement encodes what was meant, the
error code classifies how it deviates. Implementation:
scoped_annotations field on ReplacedWord.
Common Misconceptions
These are bugs we have repeatedly written down then forgotten — recording them here so future contributors don’t reinvent them.
- “
[: ...]lets me put any text I want.” No. Each replacement word is validated.[: C-3PO]fails E220 in English just asC-3POwould. - “
[:]is the right mechanism for ASR sanitization.” Usually no. ASR-introduced normalization typically wants[% ...](free- form comment) or[= ...](free-form explanation), neither of which validates word grammar. Use[:]only when you have a concrete CHAT-legal intended form. - “
%moranalyzes the original.” No.%moranalyzes the replacement. This is the correction’s morphology, not the error’s. - “
%worcount must equal%morcount.” No. Forgonna [: going to],%worhas 1 entry and%morhas 2. They align to different sides. The validator’s per-domain rule respects this. - “
<a b> [: c d]is a group-level replacement.” No. Group-level replacements don’t exist. Either replace inside (<a [: c] b [: d]>) or rephrase the transcription.
See Also
- Retraces and Repetitions — the orthogonal post-hoc correction mechanism.
- The %mor Tier — UD-syntax morphosyntactic analysis that aligns to the replacement form.
- Word Syntax — the word grammar that replacement words must satisfy.
- Dependent Tiers — overview of
%mor,%wor, etc., with their alignment relationships.
Untranscribed Markers: xxx, yyy, www
Status: Reference Last updated: 2026-05-11 23:21 EDT
CHAT reserves three short word-level markers for material the human
transcriber cannot or chose not to render as words on the main tier.
Each one has a specific meaning. Tools that emit CHAT — including ASR
pipelines, format converters, and editor heuristics — must respect
those meanings, because every downstream consumer (researchers,
validators, and aggregate-statistics tools like CLAN’s freq,
kideval, mlu) reads them at face value.
| Marker | Meaning | Emitter |
|---|---|---|
xxx | Transcriber listened to the audio and could not make out what was said. The speech is unintelligible to the human ear at this point. | Human transcriber only. |
yyy | Transcriber heard a discrete utterance but could not write it as ordinary CHAT words. Used when the surface form resists orthography (mumbled, slurred, foreign with no equivalent). The phonetic content typically appears on the %pho tier. | Human transcriber only. |
www | Transcriber chose not to transcribe this stretch — usually for privacy, off-topic content, or because the segment is irrelevant to the corpus’s purpose. | Human transcriber only. |
The shared property: each marker is the human transcriber telling later readers something specific about their experience listening to the audio. None of them mean “tooling could not process this token”.
Why this matters
When a researcher loads a CHAT corpus and counts xxx occurrences, the
result is a measure of human listening difficulty: it tells them how
much of the audio resisted human transcription. That number feeds into
methodology decisions (“can we get reliable MLU from this corpus?”,
“what’s the noise floor on this child’s speech?”, “should we re-record
in a quieter environment next time?”). It is a load-bearing signal in
language-development research.
If an ASR pipeline emits xxx whenever it can’t sanitize a token —
for example, substituting xxx for any word that fails CHAT
validation under a strict language profile — every xxx count in the
corpus becomes a meaningless mixture of “human couldn’t tell” and
“pipeline gave up”. Researchers then reading those counts are silently
misled. The signal is destroyed for the entire history of that
corpus, because the corruption is indistinguishable from real
unintelligibility once committed.
The same reasoning applies to yyy and www. A converter or
post-processor that emits any of these three markers because the
tooling couldn’t handle a token is committing semantic vandalism
against the whole field.
Rules for tooling
- Never emit
xxx,yyy, orwwwfrom a tool to mean “could not process”. These markers are reserved for human transcriber judgment. - When a token cannot be validated as legal CHAT under the
declared language, prefer one of:
- Pass the token through verbatim and let the CHAT validator
(or CLAN’s
check) flag it for human review. The transcriber listens, decides, and corrects. - Fail loud — abort the file rather than emit corrupted output.
- Apply only purely orthographic, semantically null repairs
(e.g., stripping a stray boundary quote mark from
"My). These are safe because no information is lost.
- Pass the token through verbatim and let the CHAT validator
(or CLAN’s
- Never sanitize a token by replacing it with one of the three markers. That is exactly the corrupting behavior this document prohibits.
- Never delete a token to “fix” a validation failure. Deletion loses data without any flag.
Review ASR output
An ASR error is not evidence that the original speech was unintelligible.
Listen to the recording before introducing xxx, yyy, or www.
See Transcribe a recording
and ASR output processing
for Batchalign’s current workflow.
Postcodes ([+ ...])
Status: Reference Last updated: 2026-05-11 23:01 EDT
A postcode is a tagged annotation token that attaches to an
utterance as a whole and appears after the terminator. The
canonical CHAT syntax is [+ <text>]. Postcodes carry researcher /
analysis tags about the utterance — whether it should be excluded
from analysis, how it should be coded, what kind of speech act it
represents — without modifying the utterance’s word content.
Syntax and Scope
*CHI: I want cookie . [+ exc]
*MOT: what did you say ? [+ imp]
*CHI: no I don't want it ! [+ neg] [+ trn]
Three structural facts to internalize:
- Postcodes attach to the utterance, not to a word. They sit
after the terminator, on the main tier, alongside (but distinct
from) any utterance-level bullet. Unlike word-scoped annotations
(
[: ...]replacement,[% ...]comment,[= ...]explanation,[* ...]error code), a postcode does not modify the interpretation of any single word — it tags the whole utterance. - Multiple postcodes may follow a single terminator. They are ordered, but the order is not semantically privileged.
- The body is free-form text. The CHAT word grammar is not applied to postcode contents. Researchers can write arbitrary tags, codes, descriptions, comments, or analytic notes. The model stores the raw text and leaves interpretation to downstream tooling and conventions.
Common Postcodes — Empirical Survey
The postcode vocabulary is open-ended: the CHAT format imposes no
closed set, and an audit of every [+ ...] token across a
JSON-mirrored snapshot of the TalkBank corpora (~99k files, 23+
data-repo families) found 488 distinct values in active use.
The findings split into three tiers ranked by repo spread (in how many distinct corpus families the code appears) — the more useful ranking than raw count, because high-count codes can be concentrated in a single corpus.
Tier 1 — Cross-corpus codes (in 7+ repos)
These are the conventions every CHAT consumer should expect to encounter across collections:
| Postcode | Repo spread | Total occurrences | Meaning |
|---|---|---|---|
[+ gram] | 13 | ~3,100 | Grammatical — utterance is grammatically well-formed for purposes of the analysis. |
[+ exc] | 9 | ~26,900 | Exclude utterance from analysis. The utterance is preserved in the transcript but tagged so analytic tools (CLAN’s freq, mlu, etc.) skip it. |
[+ bch] | 9 | ~10,000 | Backchannel — listener-side acknowledgement (mhm, yeah) that should not be counted as a substantive turn. |
[+ trn] | 7 | ~3,800 | Translation utterance. |
Tier 2 — Multi-corpus protocol codes (in 4-6 repos)
Codes deployed across several CHILDES sub-collections, typically encoding picture-narration / story-reading / imitation experimental conditions. Substantial raw counts (often tens of thousands), but their meaning is set by the originating protocol — consult per-corpus documentation rather than assuming a global definition:
| Postcode | Repo spread | Total occurrences |
|---|---|---|
[+ SR] | 5 | ~31,000 |
[+ IN] | 5 | ~24,500 |
[+ PI] | 5 | ~22,700 |
[+ R] | 4 | ~16,200 |
[+ I] | 4 | ~10,500 |
[+ nv] | 4 | ~3,300 |
[+ imit] | 4 | ~3,200 |
Tier 3 — Single-corpus and long-tail codes
About 80% of the 488 distinct values appear in one repo only. The
single-corpus codes include high-volume protocol vocabularies (e.g.
[+ uncued] ~19,500 in one repo, [+ NAC] ~3,500 in one repo,
[+ diary] ~2,800 in a Romance/Germanic diary-study collection,
[+ noatt] ~2,300 in one repo, [+ inter-utter-switch] ~720
flagging code-switching turns).
The long tail also includes researcher-private notes, typos that
survived check, and per-study coding schemes. Tooling MUST treat
any unknown postcode value as opaque text — the corpus author may
know what it means, the format does not.
Caveats
- Numbers are from a snapshot audit and will drift as corpora are added or revised. Treat the broad shape (open vocabulary, ~4 truly cross-corpus codes, ~10 multi-corpus protocol codes, ~hundreds of single-corpus or long-tail codes) as the load-bearing finding, not the exact counts.
- “Repo spread” counts data-repo families, not individual files. Two corpora curated by the same group inside one data-repo count as one for spread; researchers using the same code in two different family-of-corpora packages count as two.
- The CHAT manual remains the source of truth for standard conventions. The empirical survey above shows what is actually deployed; when ingesting a new corpus, consult its own documentation for the postcodes in use.
What Postcodes Are NOT
Postcodes are easy to confuse with several other CHAT annotation forms because they all use square brackets. The differences are substantive and load-bearing.
| Form | Scope | Body validation | Purpose |
|---|---|---|---|
[+ ...] | Utterance-level (this doc) | None — free text | Researcher / analysis tag attached to the whole utterance |
[: ...] | Word-level | Replacement words ARE validated as CHAT words | Sanctioned-form correction of the preceding word (see replacements.md) |
[% ...] | Word-level | None — free text | Free-form comment about the preceding word or local span |
[= ...] | Word-level | None — free text | Explanation of unclear / non-standard speech (often paired with xxx / yyy placeholders) |
[* ...] | Word-level | None — error code text | Error coding for the preceding word, optionally with a structured code |
Two consequences worth pinning down explicitly:
- A postcode cannot carry per-word semantics. If you want to attach a comment, replacement, or error code to a single word, use the appropriate word-scoped form. Stretching a postcode to mean “this word is X” loses the per-word position downstream tools depend on.
- A word-scoped annotation cannot tag an utterance. If you want
to mark an entire utterance for exclusion or translation, use a
postcode. A
[% exclude this]after a word does not mean “exclude the utterance” to any consumer.
Not postcodes: quotation markers
Quotation terminators and linkers such as +" are separate from [+ ...]
postcodes. See Utterance terminators.
Do not use a word annotation or a quotation marker as an utterance-level tag.
Preserving postcodes
Keep utterance-level postcodes when editing a transcript. Downstream analysis tools interpret the code values according to their own protocols; a Batchalign processing run is not a CLAN analysis command.
For parsing and validation implementation details, see Chatter.
Dependent Tiers
Status: Reference Last updated: 2026-04-09 08:40 EDT
Dependent tiers appear on lines beginning with % immediately after an utterance. They provide annotations linked to the main tier content.
CHAT defines four structural categories of dependent tiers:
- Structured linguistic tiers — parsed into typed AST nodes with word-level alignment
- Phon phonological tiers — syllabification and segmental alignment from the Phon project
- Bullet-content tiers — free-form text with optional inline timing markers
- Text tiers — plain text with no structural alignment
Structured Linguistic Tiers
These tiers have rich, parsed representations in the data model. Each token aligns 1-to-1 with an alignable word on the main tier (excluding retraces, pauses, and events). Terminators (., ?, !) must match the main tier terminator.
%mor — Morphological Analysis
The %mor tier carries part-of-speech tags, lemmas, and morphological features for each word on the main tier. See The %mor Tier for full documentation covering the UD-style format, data model, divergences from Universal Dependencies, and migration from traditional CHAT MOR.
Format: POS|lemma[-Feature]*, with ~ separating post-clitics.
*CHI: she's eating cookies .
%mor: PRON|she~AUX|be-Pres-S3 VERB|eat-Prog NOUN|cookie-Plur .
%gra — Grammatical Relations
The %gra tier encodes dependency syntax using Universal Dependencies relation labels. Each entry has the format index|head|relation, where indices are 1-based and head 0 indicates ROOT.
*CHI: I want cookies .
%mor: PRON|I VERB|want NOUN|cookie-Plur .
%gra: 1|2|SUBJ 2|0|ROOT 3|2|OBJ 4|2|PUNCT
The %gra tier aligns with %mor chunks (clitics expand into multiple chunks). Validation checks sequential indices (E721), ROOT structure (E722 missing root, E723 multiple roots), and circular dependencies (E724).
%pho / %mod — Phonological Transcription
The %pho tier records actual pronunciation; %mod records target/model pronunciation. Both use the same format: space-separated phonetic tokens aligned 1-to-1 with main tier words.
*CHI: I want three cookies .
%pho: aɪ wɑnt fwi kʊkiz .
%mod: aɪ wɑnt θri kʊkiz .
Phonological tiers support IPA, UNIBET, X-SAMPA, or custom notation systems. They are used for child language, speech disorders, L2 learning, and dialectal variation studies.
Parsing strategy: We deliberately parse only the minimal word/group-level structure in
%phoand%modneeded for coarse alignment with the main tier. The full IPA phoneme content is stored as opaque strings — deep phonological analysis is handled by Phon, and we avoid duplicating that work. The Phon extension tiers (%modsyl,%phosyl,%phoaln) follow the same strategy.
%sin — Gesture and Sign Annotation
The %sin tier codes gestures and signs aligned with speech. Each token is either 0 (no gesture) or g:referent:type (e.g., g:ball:dpoint for a deictic point at a ball).
*CHI: that ball .
%sin: g:ball:dpoint 0 .
Multiple simultaneous gestures use bracket grouping: 〔g:toy:hold g:toy:shake〕.
%wor — Word Timing
The %wor tier carries word-level timing annotations for media synchronization.
Words may include inline bullets with millisecond timestamps. Word text is
display-only (“eye candy”) — timing data comes from the bullet fields.
%wor is not a flat “all tokens except punctuation” tier. It follows a
word-level alignment rule:
- Regular words count.
- Fillers (
&-um,&-uh,&-you_know) count — they are real spoken words with known phoneme sequences. - Fragments (
&+...) do NOT count — incomplete phoneme sequences; the FA engine cannot reliably anchor partial phonological material. - Nonwords (
&~...) do NOT count — interactional/gestural sounds without stable lexical phoneme content for alignment. - Untranscribed placeholders (
xxx,yyy,www) do NOT count — they have no known phoneme sequence; CTC forced alignment cannot produce timings for unknown material. - Replacements keep the original spoken word slot for
%wor; the replacement text matters for%mor, not%wor. If the original slot is untranscribed or a fragment/nonword, it is still excluded. - Retrace scope does not change
%wormembership. - Overlap markers do not change
%wormembership.
%wor is a timing-annotation tier. Its word count equals the number of Wor-domain
words and may differ from a naive main-tier word count. There is no downstream
positional indexing into %wor; the %wor count is not validated against the
main-tier word count.
*CHI: I want cookies .
%wor: I want cookies .
Exact corpus-shaped contrast:
*CHI: <one &+ss> [/] one play ground .
%wor: one •321809_321969• play •322049_322310• ground •322390_322890• .
# &+ss is a fragment — excluded from %wor regardless of retrace context.
*EXP: &+ih <the what> [/] what's letter &+th is this ?
%wor: the •49103_49163• what •49183_50205• what's •50205_50405• letter •50405_50685• is •50946_51046• this •51086_51586• ?
# Fragments &+ih and &+th excluded; regular words remain.
*EXP: what's is dis [: this] ?
%wor: what's •37050_37471• is •37491_37631• dis •37631_38131• ?
*CHI: xxx snack .
%wor: snack •884668_885168• .
# xxx has no phoneme sequence — excluded from %wor; only snack appears.
*CHI: &~um a boat .
%wor: a •1073779_1073799• boat •1076861_1077361• .
# &~um is a nonword — excluded from %wor.
*CHI: &-mm [<] bananas are good .
%wor: mm •1949506_1949566• bananas •1949566_1949766• are •1949846_1949987• good •1950067_1950567• .
# &-mm is a filler — included in %wor (real spoken word with alignable phoneme sequence).
flowchart TD
A["Main-tier word candidate"] --> B{"Timestamp token /\nomission / empty?"}
B -->|Yes| OUT["Excluded from %wor"]
B -->|No| C{"Untranscribed?\n(xxx/yyy/www)"}
C -->|Yes| OUT
C -->|No| D{"Fragment or nonword?\n(&+ or &~)"}
D -->|Yes| OUT
D -->|No| IN["Counts for %wor\n(word or filler &-)"]
style IN fill:#afa,stroke:#333
style OUT fill:#faa,stroke:#333
Phon Phonological Tiers
These tiers originate from the Phon
project and provide syllable-annotated phonological transcription and segmental
alignment. They were originally serialized as %x-prefixed user-defined tiers
(%xmodsyl, %xphosyl, %xphoaln) and are being promoted to official CHAT
tiers. Phon stores phonological data in its own XML format; the CHAT
representation is generated by PhonTalk.
%modsyl / %phosyl — Syllabified Phonology
%modsyl is a syllabified version of %mod (target pronunciation); %phosyl
is a syllabified version of %pho (actual pronunciation). Each phoneme is
annotated with a syllable position code (N=nucleus, O=onset, C=coda,
etc.). Words are space-separated and align 1-to-1 with the corresponding
%mod or %pho tier.
*CHI: the best .
%mod: ðə bɛst .
%modsyl: ð:Oə:N b:Oɛ:Ns:Ct:C .
%pho: ðə bɛs .
%phosyl: ð:Oə:N b:Oɛ:Ns:C .
Alignment: Content-based — stripping position codes (:N, :O, :C, etc.)
and stress markers (ˈ, ˌ) from %modsyl should yield the same phonemes
as %mod. Same for %phosyl → %pho.
%phoaln — Phone Alignment
%phoaln provides segmental alignment between target and actual IPA,
showing phoneme-by-phoneme correspondence. Each pair uses source↔target
notation; ∅ marks insertions or deletions.
*CHI: the best .
%phoaln: ð↔ð,ə↔ə b↔b,ɛ↔ɛ,s↔s,t↔∅
Alignment: Positional, word-by-word — word N in %phoaln aligns with
word N in both %mod and %pho.
Parsing strategy: Same as %pho/%mod — we parse just enough structure
for alignment (word boundaries for %modsyl/%phosyl, alignment pairs for
%phoaln). IPA phoneme content is treated as opaque strings.
Validation (E725–E728)
Because these are derived views, word counts must match between each syllabification tier and its parent IPA tier:
| Check | Error code |
|---|---|
%modsyl word count ≠ %mod word count | E725 |
%phosyl word count ≠ %pho word count | E726 |
%phoaln word count ≠ %mod word count | E727 |
%phoaln word count ≠ %pho word count | E728 |
These checks are gated on ParseHealth — if either tier in a pair has parse
errors, the alignment check is suppressed to avoid false positives.
Known PhonTalk Export Issue
The PhonTalk XML→CHAT converter writes %mod/%pho through a OneToOne
alignment path that maps IPA words to orthography words and silently drops
extras. The syllabification tiers (%modsyl, %phosyl, %phoaln) bypass
this path and include all IPA words. In child phonology data where children
produce more IPA words than orthographic targets (~4% of Phon corpus files),
this creates tier-to-tier word count mismatches. The mismatches originate in
the Phon XML source data (orthography↔IPA word count discrepancies) and are
inconsistently handled during CHAT export. This is being investigated in
collaboration with the Phon team.
Bullet-Content Tiers
These tiers contain free-form text with optional embedded timing markers (•START_END•) and picture references (•%pic:"file.jpg"•). They do not align word-by-word with the main tier.
| Tier | Purpose |
|---|---|
%act | Physical actions, gestures, non-verbal behaviors |
%cod | Research-specific coding (semantic roles, thematic coding, error classification) |
%com | Comments, annotations, and contextual notes |
%exp | Explanations or expansions of ambiguous/incomplete speech |
%add | Addressee identification in multi-party conversations |
%spa | Speech act coding (request, assertion, question, directive) |
%sit | Situational context or setting description |
%gpx | Extended gesture position coding |
%int | Intonational contours and prosodic patterns |
Example with timing:
*CHI: gimme that .
%act: reaches toward shelf
%com: child is pointing to picture
Text Tiers
These tiers contain plain text with no bullets, timing, or structural alignment:
| Tier | Purpose |
|---|---|
%alt | Alternative transcriptions |
%coh | Cohesion annotation |
%def | Definitions |
%eng | English translations (for non-English transcripts) |
%err | Error annotations |
%fac | Facial expressions |
%flo | Flow annotation |
%gls | Glosses |
%ort | Orthographic representations |
%par | Paralinguistic information |
%tim | Timing information |
User-Defined Tiers
Tiers prefixed with %x (e.g., %xcod, %xact) are user-defined dependent tiers. They are preserved during parsing and roundtrip but receive no structural validation beyond basic format checks.
The %mor Tier: Morphological Analysis
Status: Reference Last updated: 2026-05-11 20:35 EDT
The %mor (morphological) dependent tier provides word-by-word morphosyntactic annotation aligned with the main tier. Each main-tier word receives a morphological code specifying part of speech, lemma, and grammatical features.
Format Overview
*CHI: I want cookies .
%mor: pron|I-Prs-Nom-S1 verb|want-Fin-Ind-Pres-S1 noun|cookie-Plur .
Each %mor item has the structure POS|lemma[-Feature]*, where:
- POS — part-of-speech category (
noun,verb,pron,det,aux, etc.) |— pipe separator (always present)- Lemma — base form of the word (
cookie,be,I). May contain language-specific compound or derivational boundary markers (see Compound Lemma Boundaries below) - Features — zero or more morphological features, each preceded by
-(-Plur,-Fin-Ind-Pres-S3)
Items are space-separated and terminate with a punctuation marker (., ?, !, etc.).
The UD MOR Format
TalkBank’s %mor tier uses a format inspired by Universal Dependencies (UD) but adapted to CHAT conventions. We call this the UD MOR format to distinguish it from the older CLAN-era MOR format.
The UD MOR format was introduced via batchalign’s Stanza-based morphosyntax pipeline. Stanza produces standard UD analysis (UPOS, lemma, morphological features, dependency relations), and the Rust mapping layer converts this to CHAT %mor and %gra tiers. The new format has been adopted for all new corpus annotation.
Structure: Flat POS|lemma[-Feature]*
Every morphological word is flat — a single POS tag, a single lemma, and a linear chain of features:
POS|lemma[-Feature1][-Feature2][-Feature3]...
There are no compounds, prefixes, subcategories, or nested structures in the UD MOR format. The entire morphological analysis of a word is captured by the POS+lemma+features triple.
Examples:
| Word | %mor code | POS | Lemma | Features |
|---|---|---|---|---|
| dog | noun|dog | noun | dog | (none) |
| dogs | noun|dog-Plur | noun | dog | Plur |
| running | verb|run-Part-Pres-S | verb | run | Part, Pres, S |
| is | aux|be-Fin-Ind-Pres-S3 | aux | be | Fin, Ind, Pres, S3 |
| I | pron|I-Prs-Nom-S1 | pron | I | Prs, Nom, S1 |
| the | det|the-Def-Art | det | the | Def, Art |
Multi-Word Tokens (Clitics)
English contractions and similar multi-word tokens (MWTs) are represented using the tilde (~) separator for post-clitics:
*CHI: it's red .
%mor: pron|it~aux|be-Fin-Ind-Pres-S3 adj|red .
Here it's is a single main-tier word that expands to two morphological words: pron|it (main) and aux|be-Fin-Ind-Pres-S3 (post-clitic). The ~ indicates the two MOR words are fused into one orthographic token.
Each clitic counts as its own chunk for %gra alignment — pron|it~aux|be-Fin-Ind-Pres-S3 produces 2 chunks, each needing its own grammatical relation.
Terminator
The %mor tier ends with a terminator that matches the main tier’s utterance terminator:
*CHI: what is that ?
%mor: pron|what aux|be-Fin-Ind-Pres-S3 det|that ?
The terminator (., ?, !, +..., etc.) counts as one chunk for %gra alignment.
How It Diverges from UD
The UD MOR format is UD-inspired but not UD-compliant. Several deliberate adaptations make it fit CHAT conventions while preserving most UD information. This section catalogs every divergence.
1. POS Tags Are Lowercased UPOS
UD uses uppercase UPOS tags (NOUN, VERB, PRON). CHAT uses lowercase (noun, verb, pron). This is a lossless, trivially reversible surface change.
| UD UPOS | CHAT POS |
|---|---|
| NOUN | noun |
| VERB | verb |
| AUX | aux |
| PRON | pron |
| DET | det |
| ADJ | adj |
| ADV | adv |
| ADP | adp |
| PROPN | propn |
| INTJ | intj |
| CCONJ | cconj |
| SCONJ | sconj |
| NUM | num |
| PART | part |
| X | x |
2. Feature Values Are Flat, Not Key=Value (Currently)
UD represents morphological features as key=value pairs: Number=Plur, Tense=Past, Person=3. The current CHAT convention drops the keys and uses only the values: -Plur, -Past, -S3.
This is the most significant divergence from UD, because:
- Information loss:
Plurcould in principle beNumber=PlurorDegree=Plur(though in practice the UD feature value set has no real ambiguities). - Collapsed person/number: UD
Person=3|Number=Singbecomes-S3— a combined code that cannot be mechanically decomposed back to its UD components. - Feature ordering: Features appear in a conventional order determined by the generation pipeline, not in UD’s alphabetical order.
The data model now supports key=value features. The MorFeature type has an optional key field — when present, the feature serializes as Key=Value (e.g., -Number=Plur); when absent, it serializes as just the value (e.g., -Plur). This is forward-compatible: existing flat features parse and serialize identically, and if batchalign’s mapper begins emitting Key=Value features, they flow through the parser and model without any format changes.
3. Multi-Value Features: Commas Preserved
UD encodes multi-value features with commas: PronType=Int,Rel (the word is both interrogative and relative). In CHAT %mor, the comma is preserved within the feature value:
-Int,Rel
This is treated as a single feature value "Int,Rel". The grammar accepts commas within feature values, and the model stores them as-is. No decomposition occurs — the model faithfully records the string that appears in the %mor tier.
Historical note: Earlier documentation described a “comma-stripping” convention where
PronType=Int,Relbecame-IntRel(concatenated without separator). The current grammar and parser preserve the comma. Existing corpus data using the concatenated form (-IntRel) also parses correctly — it’s simply treated as the flat value"IntRel".
4. Dependency Relations Are Uppercase with Dash Subtypes
The %gra tier (not %mor, but closely related) uses uppercase relation names with dashes for subtypes, where UD uses lowercase with colons:
| UD | CHAT %gra |
|---|---|
nsubj | NSUBJ |
acl:relcl | ACL-RELCL |
obl:tmod | OBL-TMOD |
This is lossless — case and separator are trivially reversible.
5. ROOT Head Convention
In UD, the root word has head=0. In %gra, two conventions coexist:
- UD convention:
head=0(e.g.,3|0|ROOT) — the standard we now emit - Legacy TalkBank convention:
head=self(e.g.,3|3|ROOT) — found in older corpus data
The parser and validator accept both forms. New output uses head=0.
6. No XPOS, No DEPREL Subtypes in %mor
UD provides both UPOS (universal POS) and XPOS (language-specific POS). CHAT %mor uses only UPOS-equivalent tags — there is no XPOS field. Language-specific POS distinctions are not represented.
Similarly, UD’s fine-grained dependency relation subtypes (e.g., nsubj:pass) appear in %gra as NSUBJ-PASS, but the %mor tier itself contains no dependency information.
7. No Morpheme Segmentation
Traditional CHAT MOR formats (CLAN-era) supported morpheme-level segmentation with compound markers (+), prefix markers (#), and suffix chains (-SUFFIX&type). The UD MOR format does not use any of these — each word is analyzed as a flat POS+lemma+features triple.
The grammar still accepts some of these legacy markers for backward compatibility with older corpus data, but the canonical UD MOR format does not produce them.
Compound Lemma Boundaries
Several UD treebanks use special characters inside lemmas to mark morphological boundaries. These are meaningful linguistic annotations preserved in the CHAT %mor lemma field when possible.
Known Markers Across Languages
| Language | Marker | Meaning | Example Lemma | In %mor |
|---|---|---|---|---|
| Estonian | = | Compound boundary | maja=uks (house-door) | noun|maja=uks — preserved |
| Basque | ! | Derivational boundary | partxi!se (share + derivation) | noun|partxi!se-Ine — preserved |
| Finnish | # | Compound boundary | jää#kaappi (ice-cabinet) | noun|jää_kaappi — mangled (# → _) |
= and ! pass through the cleaning pipeline because they are not reserved CHAT %mor syntax characters. # is reserved in traditional CHAT MOR for prefix markers (e.g., v|#un#do), so the sanitizer replaces it with _.
Gotcha:
=ambiguity with legacy CLAN translation glosses. Legacy CLAN%mortiers use=for translation glosses (e.g.,n|perro=dog), a convention predating UD adoption. The parser treats=identically in both cases — it is preserved as part of the lemma string. This means legacyn|perro=dogparses successfully but the translation semantics are lost: the model storesperro=dogas a single lemma, indistinguishable from an Estonian compound likemaja=uks. Since we cannot reliably disambiguate the two uses without language-specific context, legacy translation glosses are silently absorbed into the lemma. Files with legacy=translationsyntax still parse and round-trip correctly, but the translation information is not semantically accessible. This affects corpora that predate our UD MOR adoption and lack Stanza coverage for their language.
Multi-Word Expression Lemmas (Stanza _ Convention)
Stanza uses underscores in lemmas to represent multi-word expressions across many languages: New_York, parce_que (French), pick_up (English), a_causa_di (Italian). The current cleaning pipeline strips underscores entirely (New_York → NewYork), which is a known data quality issue and should be treated as an open data-quality limitation of the current mapper.
Multi-Value Features (Commas in Feature Values)
UD encodes multi-value features with commas: PronType=Int,Rel means a word is both interrogative and relative. These commas appear in the CHAT %mor feature suffix and are preserved as-is:
pron|wat-Int,Rel
This is sometimes mistaken for a compound lemma marker, but commas in UD always appear in the feature column (CONLLU column 6), never in the lemma column (CONLLU column 3). In CHAT %mor, they appear after the - feature separator, not inside the lemma. The grammar, both parsers, and the data model all accept commas in feature values. See Section 3: Multi-Value Features above.
Future Direction
The current handling of compound lemma boundaries is inconsistent across languages. A possible future improvement is a unified Unicode separator character that would normalize all compound/derivational boundary markers (=, !, #, and potentially _) into a single convention. This has not been implemented as of 2026-03-02 and requires a design decision on which character to use and whether to preserve the original markers in a structured field.
Migration from Traditional CHAT MOR
What Changed
The traditional CHAT MOR format (CLAN-era) used a complex, hierarchically structured notation:
%mor: pro:sub|I v|want n|cookie-PL .
Key differences from the UD MOR format:
| Aspect | Traditional CHAT MOR | UD MOR |
|---|---|---|
| POS tags | CLAN categories (pro:sub, v, n, adj, adv) | Lowercased UPOS (pron, verb, noun, adj, adv) |
| POS subtypes | Colon-separated (pro:sub, det:art, v:aux) | Flat (subtypes dropped or encoded differently) |
| Features | CLAN suffix system (-PL, -PAST, -3S, -PRES) | UD feature values (-Plur, -Past, -S3, -Pres) |
| Compounds | + separator (`n | +n|black+n|bird`) |
| Prefixes | # separator (`v | #un#do`) |
| Morpheme segmentation | Full segmentation (v|eat&PAST) | Not used (features are abstract, not morphemic) |
| Translations | = separator (n|perro=dog) | Not present in base format (separate mechanism) |
Backward Compatibility
The grammar still accepts many traditional CHAT MOR constructs (colons in POS tags, etc.) because the reference corpus contains files in both formats. The parser produces the same flat MorWord regardless — legacy constructs are mapped to the simplified structure during parsing.
What Stays the Same
Despite the format changes, fundamental CHAT conventions remain:
- Pipe (
|) separates POS from lemma - Hyphen (
-) introduces features - Tilde (
~) marks post-clitics - Space separates items
- Terminator ends the tier
- 1-to-1 alignment with main tier words
Implementation
For Batchalign’s generation of morphology, see the Morphosyntax contract. The parser, data model, and validator are maintained by Chatter.
Phon Tiers (%xmodsyl, %xphosyl, %xphoaln)
Status: Reference Last updated: 2026-05-11 22:05 EDT
The Phon extension tiers provide syllable-level phonological annotation and segmental alignment between target and actual IPA transcription. They are produced by the Phon application and exported to CHAT via PhonTalk.
Note on the
xprefix: These tiers currently use the%xprefix (%xmodsyl,%xphosyl,%xphoaln) to indicate they are user-defined extension tiers, following the Phon project’s convention. When these tiers are officially adopted into the CHAT standard, thexprefix will be dropped.
Background
Phon is a software program for phonological analysis of child language, second language acquisition, and speech disorders. It stores phonological data in its own XML session format with structured IPA transcription, syllabification, and phone-level alignment. When Phon data is exported to CHAT, three extension tiers carry this phonological annotation:
- %xmodsyl — syllabified version of
%mod(target/model IPA) - %xphosyl — syllabified version of
%pho(actual IPA) - %xphoaln — phone-by-phone alignment between target and actual IPA
These tiers are derived views of the parent IPA tiers. The syllabification
tiers store the same phoneme sequence as %mod/%pho but with syllable
structure annotations applied. There is no independent alignment — the
syllabification is a reannotation of the same phone sequence.
Tier Format
%xmodsyl / %xphosyl — Syllabified Phonology
Each phoneme is annotated with a syllable constituent position code:
| Code | Meaning |
|---|---|
N | Nucleus (vowel center) |
O | Onset (syllable-initial consonant) |
C | Coda (syllable-final consonant) |
D | Left appendix |
E | Ambisyllabic / right appendix |
R | Rime / rhotic |
Format: phone:Position pairs concatenated within each syllable, with .
separating syllables within a word and spaces separating words.
*CHI: I want three cookies .
%mod: aɪ wɑnt θri kʊkiz .
%xmodsyl: a:Dɪ:D w:Oɑ:Nn:Ct:C θ:Oɹ:Oi:N k:Oʊ:Nk:Oɪ:Nz:C .
%pho: aɪ wɑn fwi kʊkiz .
%xphosyl: a:Dɪ:D w:Oɑ:Nn:C f:Ow:Oi:N k:Oʊ:Nk:Oɪ:Nz:C .
Pauses appear as (.) in the syllabification tiers, matching their
representation in %mod/%pho:
%pho: aɪ (.) wɑnt .
%xphosyl: a:Dɪ:D (.) w:Oɑ:Nn:Ct:C .
%xphoaln — Phone Alignment
Shows phoneme-by-phoneme correspondence between target (%mod) and actual
(%pho) IPA using target↔actual notation. Multiple pairs within a word
are comma-separated. ∅ marks deletions (target phone with no actual
counterpart) or insertions (actual phone with no target counterpart).
*CHI: the best .
%mod: ðə bɛst .
%pho: ðə bɛs .
%xphoaln: ð↔ð,ə↔ə b↔b,ɛ↔ɛ,s↔s,t↔∅ .
The %xphoaln tier aligns positionally with both %mod and %pho — word N
in %xphoaln corresponds to word N in both parent tiers.
Alignment Semantics
Because the syllabification tiers are derived views, word counts must match:
%xmodsylword count =%modword count%xphosylword count =%phoword count%xphoalnword count =%modword count =%phoword count
Mismatches are flagged as errors E725–E728. See Chatter alignment documentation for implementation details.
Implementation ownership
Phonological analysis belongs to Phon. CHAT parsing and tier-alignment validation belong to Chatter. Batchalign can add observed IPA with the phonetic command.
Phon XML Source Format
In Phon’s native XML format, phonological data is stored as structured elements:
<ipaTarget>
<pho>
<pw>
<ph scType="onset"><base>θ</base></ph>
<ph scType="nucleus"><base>ɹ</base></ph>
<ph scType="nucleus"><base>i</base></ph>
</pw>
</pho>
</ipaTarget>
Each <pw> (phonological word) element contains <ph> elements with
syllable constituent types (scType). Pauses appear as <pause> elements
at the same level as <pw> inside <pho>.
The <alignment> element provides phone-level mappings between target and
actual using index-based <pm> (phone map) entries.
Data Quality Notes
A small percentage of Phon corpus XML records have an orthography↔IPA
word-count mismatch — i.e. the number of <pw> (phonological word)
elements in <ipaTarget> / <ipaActual> differs from the number of <w>
elements in <orthography>. This is expected in child phonology data:
children may produce extra syllables, partial words, or over-productions
relative to the target.
For current counts on the data repos in ~/0tb/data/, run:
python3 scripts/analysis/scan_phon_mismatches.py ~/0tb/data
It reports total XML files scanned, files with at least one mismatched record, and total mismatched records across the corpus.
The PhonTalk CHAT export handles this discrepancy inconsistently:
%mod/%phoare written through aOneToOnealignment path that maps IPA words to orthography words — extras are silently dropped%xmodsyl/%xphosyl/%xphoalnare written directly from the rawIPATranscript— all IPA words are included
This produces CHAT files where %xmodsyl may have more words than %mod,
triggering E725–E728 validation errors.
This is being investigated in collaboration with the Phon team.
Word Syntax
Status: Reference Last updated: 2026-05-11 23:33 EDT
Words are the primary content unit on the main tier. CHAT defines several word types and annotation mechanisms.
Standalone Words
Most words are simple tokens separated by whitespace:
*CHI: I want a cookie .
Words can contain Unicode characters for any language:
*CHI: ich möchte Kekse .
Compounds
Compound words join multiple elements with +:
*CHI: I want ice+cream .
Special Word Forms
Shortened Forms
Parentheses mark omitted portions of a word:
*CHI: (be)cause I want it .
The full form is because; the child produced cause.
Replacements
Square brackets with colon mark what the speaker actually meant:
*CHI: I goed [: went] to the store .
The speaker said “goed” but the intended word was “went”.
Language Markers
The @s: suffix marks a word’s language in multilingual transcripts:
*CHI: I want a Keks@s:deu .
Other @ markers:
@l— letter@c— child-invented form@f— family-specific word@n— neologism@o— onomatopoeia@b— babbling@wp— word play@si— signed word
Annotations
Words and groups can carry post-positioned annotations in square brackets:
Error Marking
*CHI: he goed [*] to school .
[*] marks an error. More specific error codes can follow: [* m:+ed].
Explanations
*CHI: that one [= the red ball] .
[= text] provides an explanation or gloss.
Replacements
*CHI: I wanna [: want to] go .
[: text] marks the target/intended form.
Best Guess
*CHI: I want the birfer [?] .
[?] marks uncertain transcription.
Events and Actions
Paralinguistic Events
Events marked with &= describe non-speech sounds:
*CHI: &=laughs I want cookie .
*CHI: &=coughs .
Fillers
Fillers are marked with &-:
*CHI: &-um I want &-uh cookie .
Interposed Speech (Other Speaker)
Brief background speech from a different speaker is marked with the
&*SPK:text prefix — it captures the interjection without creating
a full turn line:
*CHI: I want &*MOT:careful a cookie .
This says CHI was speaking and MOT briefly said “careful” mid-turn.
If the intervention is substantial enough to constitute its own turn,
transcribe it as a separate *MOT: utterance instead.
[^ text] is a standalone researcher annotation on the main tier.
For notes about a single word, use [% text] or [= text] as appropriate.
Pauses
*CHI: I (.) want (..) a (...) cookie .
*CHI: I (1.5) want a cookie .
(.)— short pause(..)— medium pause(...)— long pause(N.N)— timed pause in seconds
Overlap
Overlapping speech between speakers uses angle brackets and overlap markers:
*MOT: do you want <a cookie> [>] ?
*CHI: <cookie> [<] !
[>]— follows the overlap (this speaker started first)[<]— overlaps the previous speaker
Retrace and Repetition
Groups followed by retrace markers indicate speech disfluencies:
*CHI: <I want> [/] I want a cookie .
*CHI: <I want> [//] I need a cookie .
*CHI: <I want a> [///] give me a cookie .
[/]— partial retrace (speaker repeats the same words)[//]— full retrace (speaker restarts with different words)[///]— multiple retracing (multiple false starts)[/-]— reformulation (speaker rephrases with different structure)
CHAT symbols
This reference summarizes notation used in transcripts. For the complete conventions, see the CHAT manual. Parser and symbol-registry development belong to Chatter.
Symbol Categories
Terminators
Punctuation that ends an utterance:
| Symbol | Name | Usage |
|---|---|---|
. | Period | Declarative |
? | Question | Interrogative |
! | Exclamation | Exclamatory |
+... | Trailing off | Incomplete utterance |
+..? | Trailing-off question | Question trails off |
+/. | Interruption | Speaker interrupted by another |
+//. | Self-interruption | Speaker interrupts self |
+/? | Interrupted question | Question interrupted |
+!? | Broken question | Exclamation-question |
+"/. | Quoted new line | Quotation continues on next line |
Conversation-analysis notation
Symbols used in conversation analysis notation:
| Symbol | Meaning |
|---|---|
↑ | Rising pitch |
↓ | Falling pitch |
→ | Level pitch |
↗ | Rise-fall |
↘ | Fall-rise |
≋ | Creaky voice |
∙ | Micropause |
These symbols do not all have the same word-boundary behavior. Pitch arrows
↑ and ↓ can attach to a word, as in book↑; separator symbols such as
→, ↗, and ↘ are separate content items. Do not strip or split all
conversation-analysis symbols using a single punctuation rule.
Language Codes
CHAT uses ISO 639-3 three-letter language codes in @Languages headers and @s: word markers:
@Languages: eng, fra
*CHI: I want a croissant@s:fra .
Common codes: eng (English), fra (French), deu (German), spa (Spanish), zho (Mandarin), jpn (Japanese).
Special Markers
@ Markers (Word-Level)
| Marker | Meaning |
|---|---|
@s:LANG | Second language word |
@l | Letter |
@c | Child-invented form |
@f | Family-specific word |
@n | Neologism |
@o | Onomatopoeia |
@b | Babbling |
@wp | Word play |
@si | Signed word |
& Markers (Events and Fillers)
| Prefix | Meaning |
|---|---|
&= | Paralinguistic event (e.g., &=laughs) |
&- | Filler (e.g., &-um) |
&+ | Phonological fragment (e.g., &+sh) |
&~ | Nonword (e.g., &~mama) |
&* | Other speaker’s speech event (e.g., &*MOT:word — speech attributed to another speaker) |
Scope Markers
| Marker | Meaning |
|---|---|
[/] | Partial retrace — speaker repeats the same words |
[//] | Full retrace — speaker restarts with different words |
[///] | Multiple retracing — multiple false starts |
[/-] | Reformulation — speaker rephrases with different structure |
[*] | Error |
[?] | Best guess |
[>] | Overlap follows |
[<] | Overlap precedes |
[= text] | Explanation |
[: text] | Replacement |
Batchalign: explanation
Understand the reasons and mechanisms behind the behavior.
- How a command runs
- Processing speed and memory
- How result caching works
- CLI and HTTP service roles
- HTTP pipeline execution
- Understanding progress
- From recognition output to CHAT
- Number expansion
- Multi-word tokens
How a processing command runs
The current CLI is a Python Typer application. It constructs backend objects and
a recipe, then runs a Rust Pipeline through the in-process PyO3 extension.
The pipeline owns file scheduling and task execution. There is no worker-process
protocol on this path.
flowchart LR
CLI[Python CLI] --> Inputs[Discover input paths]
Inputs --> Pipeline[Rust Pipeline]
Pipeline --> Runner[Typed task runner]
Runner --> Queue[Bounded backend queue]
Queue --> Cache{Result cached?}
Cache -->|yes| Result[Typed task output]
Cache -->|no| Backend[Python or native backend]
Backend --> Result
Result --> Apply[Rust result application]
Apply --> Outcome[File outcome]
Outcome --> Write[CLI writes output]
File and task scheduling
--parallel becomes Pipeline(workers=N), default 8. The callback-driven CLI path
admits a bounded window of files, converts inputs within that window, and writes
outcomes as files finish. Rust task runners prepare typed requests, dispatch
backend work, and apply the returned result to pipeline state.
A registered backend has one bounded queue and one batcher, even when it serves
several task kinds. The batcher checks LMDB, gathers misses according to
BatchPolicy, calls the backend on a blocking thread, and returns results to
waiting runners. Different backends can overlap. A single backend batcher awaits
its current call before calling it again.
Morphotag has an additional per-file window of 128 pending utterances. Its Stanza backend defaults to batches of at most 128 requests and a 100 ms collection window. Stanza partitions a received batch by language configuration before model inference. See Performance for memory implications.
Pipeline composition
Recipes in python/batchalign/recipes.py define task order. For example,
morphotag is one morphology task; align composes optional timing recovery and
forced alignment. Transcription composes ASR, an optional utterance segmenter,
and an optional speaker stage. The CLI chooses the backends supplied to recipes.
It does not automatically append alignment or morphology to transcription.
Ownership
| Concern | Implementation |
|---|---|
| CLI arguments, input discovery, output paths | python/batchalign/cli/ |
| Recipes and backend constructors | python/batchalign/recipes.py, backends/ |
| File admission, outcomes, cancellation | crates/batchalign/batchalign-engine/src/pipeline.rs |
| Routing and batching | Engine engine.rs, batcher.rs |
| Result cache | Engine cache.rs |
| Typed requests and task runners | crates/batchalign/batchalign-core/src/proto/, taskrunners/ |
| CHAT model, parsing, transformations | TalkBank Rust crates used by the core |
The GUI runs through the separate HTTP service, which constructs pipelines using the same recipe layer. It is not an implicit CLI daemon.
Understanding processing speed and memory use
Processing time depends on the input, backend, hardware, and cache state. A first run may download models; a later CLI invocation still has to start Python and initialize the backends it needs. Saved results can avoid inference, including for text tasks such as morphosyntax. See Caching.
How work overlaps
The CLI runs a Rust pipeline inside the Python process. It admits a limited
number of input files and sends their task requests to shared backend queues.
--parallel N controls file admission; the default is 8.
Each registered backend has one batcher. It checks the result cache, collects
misses up to the backend’s batch size or batching deadline, then calls that
backend. That batcher awaits the call before starting another call. Different
backends can overlap work; --parallel does not create N model processes.
For morphosyntax, the current defaults are:
| Control | Value | Meaning |
|---|---|---|
| Active files | 8 | CLI --parallel default |
| Pending utterances per active file | 128 | Rust morphotag dispatch window |
| Requests per Stanza backend batch | Up to 128 | Backend batch maximum |
| Batch collection window | Up to 100 ms after the first miss | Allows requests to accumulate |
| Resident Stanza pipeline configurations in the process-wide LRU | 2 | Keyed by language set and retokenization mode |
Stanza groups a received batch by language configuration. A mixed-language batch may produce several smaller model calls. The CLI orders morphotag files by language header, then by descending file size within a group, to improve locality. One sufficiently large file can fill a batch without additional file concurrency. A multilingual pipeline configuration can contain models for several languages; the two-entry LRU is not a limit of two individual model objects.
What the bounds do—and do not—mean
The engine bounds active file work and backend queue lengths, and morphotag bounds pending utterance futures. These limits prevent the scheduler from submitting the entire corpus for inference at once. They are not an RSS budget. The CLI still discovers input paths up front, and active files retain transcript state. Long utterances, decoded audio, model weights, inference tensors, and allocator retention can dominate memory.
Increasing file concurrency can improve overlap or batch filling, but can also increase RSS without speeding up inference. Increasing utterance batch size makes each model call larger. These are separate tuning decisions.
Device selection
Device behavior belongs to the selected backend. align, transcribe, and
utseg expose --force-cpu and an explicit --allow-mps option for applicable
local models. morphotag does not expose those flags; its Stanza configuration
uses the library’s device selection. There is no universal GPU speedup factor.
Measure your workload
Compare the same inputs, outputs, backend settings, package version, and cache policy. Record model-download time separately from ordinary startup, and report whether results were cached. Use utterances per second as well as files per second when transcript lengths vary. Measure peak RSS alongside elapsed time; a larger batch can trade substantial memory for a small throughput improvement.
For a practical file-concurrency comparison, see Tune file concurrency.
The current CLI has no bench command. The GUI’s HTTP service is a separate
entrypoint; ordinary CLI processing does not automatically connect to it or keep
a background model service alive between invocations.
How result caching works
Batchalign saves backend results so repeated processing can reuse completed computations. This includes text analysis: morphosyntax, utterance segmentation, and translation use the same result cache as audio inference.
Results and models are separate
The result cache stores individual task outputs in an LMDB database. Model files downloaded by Stanza, Hugging Face, or other libraries live in those libraries’ own download locations. Clearing result entries does not remove model files. Loaded models also occupy memory for the lifetime of their Python objects; a result-cache hit and a model already loaded in memory are different kinds of reuse.
The engine checks for a cached result before sending a request to a backend. A hit avoids that inference request. Input discovery, CHAT parsing, preprocessing, output assembly, and file writing still happen. Some backends initialize before cache lookup, so even a fully cached run can have startup costs.
What is reused
| Pipeline work | Default behavior |
|---|---|
Morphosyntax (morphotag) | Cache backend results per utterance |
Utterance segmentation (utseg) | Cache backend results |
Translation (translate) and AI editing (ai) | Cache backend results |
ASR (transcribe), timing recovery, forced alignment (align) | Cache backend results |
Speaker inference (diarize or transcription with diarization) | Cache backend results |
Media conversion (convert) | The default conversion recipe bypasses the result cache |
| CHAT parsing, tier assembly, output writing | Performed by the pipeline; not saved as finished output files in this cache |
The cache is shared across pipeline instances and processes at the same path. LMDB allows concurrent readers and serializes write transactions.
When a result stops matching
A cache key combines the compiled build identity, task, backend name, and the
input fields selected by that task’s CacheKey implementation. For example,
morphosyntax includes text, tokens, language, and retokenization mode. Routing
identifiers such as source file ID and utterance number do not participate, so
identical content in different files can share an entry.
Changing a key component causes a miss. The build identity normally comes from the compiled Git SHA, with the Rust package version as a fallback. A package upgrade can therefore leave older entries on disk while no longer reading them.
This does not fingerprint arbitrary downloaded model files or every remote provider update. If a provider or model changes without changing the backend identity or input, use a refresh policy in the Python API or clear the result cache before processing again.
Storage and limits
Run batchalign cache path to see the location for your installation. Defaults:
| Platform | Result-cache directory |
|---|---|
| macOS | ~/Library/Caches/batchalign/cache.lmdb/ |
| Linux | $XDG_CACHE_HOME/batchalign/cache.lmdb/, or ~/.cache/batchalign/cache.lmdb/ |
| Windows | %LOCALAPPDATA%\batchalign\cache.lmdb\ |
The directory contains data.mdb and lock.mdb. The current engine sets a
16 GiB maximum LMDB map size. This is a virtual address-space limit, not a
16 GiB resident-memory allocation or an automatic eviction policy. Cache writes
are best effort; a full database can prevent new results from being saved.
For commands to inspect or clear entries, see Manage the result cache. For custom paths and read/write policies, see Python API.
Implementation: crates/batchalign/batchalign-engine/src/cache.rs,
batcher.rs, the core proto/ input types, and python/batchalign/recipes.py.
The HTTP service and the CLI
Ordinary batchalign morphotag, align, and transcribe commands create and run
a pipeline in their own process. They do not start or discover an HTTP daemon,
and they do not accept a global --server option.
The desktop application uses a separate Python FastAPI service, packaged
as a PyApp sidecar. That service exposes recipes and job progress to the GUI.
It can also be started explicitly with batchalign daemon for API development
or integration. This is distinct from CLI file concurrency.
The service keeps its job registry in memory. It does not provide the retired
Rust server’s worker registry, server.yaml fleet configuration, Temporal job
persistence, or automatic CLI routing. Do not rely on jobs surviving a service
restart.
For instructions, see Run the HTTP service. For local CLI throughput, see Tune file concurrency.
How the HTTP service runs pipelines
The desktop GUI uses the FastAPI application in python/batchalign/api.py.
Recipe discovery exposes available task compositions and backend descriptors;
requests materialize typed inputs and create a pipeline through the recipe API.
Job status, events, results, and cancellation are exposed through /jobs/{job_id}
and its associated routes.
The default job registry is in memory. A service restart loses registry state, and separate Uvicorn processes do not share it. This is why the daemon defaults to one HTTP worker. The service is packaged with Python and the wheel in a PyApp sidecar for the Tauri application.
The desktop starts the sidecar on a loopback port and discovers the bound port
from its DAEMON_PORT announcement. The ordinary CLI invokes pipelines directly
and does not use this handshake or service lifecycle.
Backend batching and caching follow the same engine contracts as the local pipeline. The API’s job registry is not the LMDB result cache, and persistent result entries do not make jobs restartable.
For API integration, inspect the running service’s /docs and /capabilities.
See Run the HTTP service for startup instructions.
Read processing progress
The CLI tracks each selected file through task stages and prints a final summary
of completed, failed, and skipped work. Multiple active files can be at different
stages. The terminal renderer is selected automatically; use global --plain
for line-oriented output or --ansi to request live rendering.
batchalign --plain morphotag corpus/ -o tagged/
batchalign -v align corpus/ -o aligned/
Rust progress events reach Python callbacks and the terminal task model. Backend calls may report finer progress, but a batched call cannot always attribute a sub-step to each file. A quiet progress counter alone does not establish that inference is stuck. Startup can also include downloads and model initialization.
File completion and output writing happen as outcomes arrive on the CLI’s callback path. Text commands do not submit the entire corpus as one model call. See Performance for scheduling and Troubleshooting if a run is not advancing.
From recognition output to CHAT
The transcription runner sends prepared audio, a language hint, and task options to the selected ASR backend. The returned segments and words are converted to Rust ASR structures for cleanup and CHAT assembly.
The core asr/ modules handle compound merging, timed-word extraction, splitting
multiword recognizer tokens, numeric forms, orthographic cleanup, and construction
of CHAT utterances and headers. Some cleanup is language-specific. Backends also
normalize their own vendor outputs before returning the typed ASR result.
This means a backend token and a final CHAT word are not interchangeable. A single recognizer token can be split, a numeric token can expand into several words, and punctuation can be represented as a CHAT terminator rather than word text. Timing must remain attached to the transformed content through these steps.
The recipe can run an utterance-segmentation backend after ASR and a speaker backend afterward. It does not automatically append forced alignment or morphology. Generated CHAT includes the unchecked-ASR comment, and successful pipeline outputs receive task provenance.
Source: core taskrunners/asr.rs, asr/prepare.rs, asr/cleanup.rs,
asr/expand.rs, asr/chat/, and python/batchalign/recipes.py.
Number expansion in ASR output
The Rust ASR pipeline recognizes numeric expressions and expands them before
building CHAT. All ASR backends use this path. It does not invoke Python
num2words or depend on morphosyntactic analysis.
Recognition and rendering
| Source | Responsibility |
|---|---|
asr/data/number_rules.json | Ordered regular expressions, named captures, language selection, and punctuation protection |
asr/num2text/mod.rs | Compile rules once, recognize expressions, dispatch captures, and distinguish unsupported expressions from ordinary text |
asr/num2text/eng.rs | English ordinal and decade rendering |
asr/num2text/nld.rs | Dutch ordinal rendering |
asr/num2text/por.rs | Portuguese ordinal rendering with gender and plural agreement |
asr/num2text/table.rs and asr/data/num2lang.json | Existing cardinal lookup tables for 46 languages and integer decomposition |
asr/num2text/cjk.rs and asr/num2chinese.rs | Existing CJK conversion and script selection |
asr/num2text/common.rs | Shared cardinal, currency, numeric-group, and hyphenated-compound handlers; percentage vocabulary |
asr/prepare.rs and asr/expand.rs | Tokenization, protected abbreviation spans, and timing propagation |
Language rules are tried in their JSON array order, then common rules. The first
match selects the handler; unsupported rendering does not fall through to a
less specific interpretation. Patterns match entire tokens and provide named
captures such as value, gender, or symbol. Languages without a special
renderer use their cardinal table when available.
Rules marked protect_punctuation also participate in ASR tokenization. For
example, the Portuguese ordinal in 54.ª. consumes its abbreviation period,
but leaves the final period as a sentence terminator. Protection requires a
complete expression boundary; it does not match prefixes of longer words.
Supported forms and limits
- Cardinal tables retain their existing exact entries and decomposition behavior. This refactor does not add grammatical context to cardinal generation.
- English ordinals and decades retain the existing Rust implementation.
- Dutch ordinals accept
e,de,ste, and superscriptᵉafter digits for values 1–1000:29ebecomesnegenentwintigste,3debecomesderde, and117ebecomeshonderdzeventiende. The numeric value determines the written suffix. Larger values remain unsupported. - Portuguese ordinals accept digits followed by
ºorª, an optional abbreviation period, and optional plurals:54ª,54.ª,54ºs. Values 1–1000 are supported. For example,54ªbecomesquinquagésima quarta;54.ºbecomesquinquagésimo quarto. - Degree
°, plain lettersa/o, and arbitrary embedded digits are not interpreted as Portuguese ordinal markers. - Currency expansion retains the previous currency vocabulary, including English currency labels for non-English languages. Percentages retain their separate preparation-stage handling.
The Portuguese forms follow the ordinal composition described in Ciberdúvidas. Expansion reflects the recognizer’s written interpretation; it cannot establish which words the speaker actually said.
Dutch forms follow Taaladvies’s number spelling rules.
Results and timing
Recognition and rendering distinguish ordinary text, a successful expansion, and a recognized but unsupported expression. Unsupported expressions retain their source text and produce a debug diagnostic. The normal CHAT validation still applies and can reject remaining digits with E220.
An expansion can contain several words. The ASR pipeline retains the original token’s overall time span and apportions internal boundaries by character count; these are approximate boundaries for subsequent forced alignment to refine. It retains speaker information outside the language renderer.
The regression suite checks frozen outputs from the previous converter across all table languages and CJK/fallback paths, every applicable cardinal-table entry, and Dutch and Portuguese ordinal recognition, CHAT legality, punctuation, and timings. For surrounding stages, see ASR processing.
Why one word can have several morphology units
A written contraction can represent several grammatical units. Stanza may represent it as a multi-word token, while CHAT represents morphological components within the analysis of a main-tier word. These counts must not be confused.
The current backend reconciles token boundaries and renders structured units;
the Rust runner aligns the resulting %mor/%gra tiers to the CHAT main tier.
See Morphosyntax processing for ownership and failure handling.
Retokenization is a separate choice about main-tier word boundaries. Use
--retokenize only when you want that mode, and review its effect on the transcript.
Related tools and documentation
This repository ships Batchalign: the Python CLI and backends, Rust processing engine, HTTP service, and Batchalign desktop application. It does not ship CLAN, the Chatter CLI or desktop application, a CHAT language server, or a VS Code extension.
Chatter and CHAT-format tools
Chatter owns the CHAT parser, typed model, validation, transformations, CLI, language server, and Chatter desktop app. Use its documentation for installation, validation, parser development, and editor integration.
Batchalign consumes versioned Chatter crates. See the Batchalign source map for the dependency boundary. The CHAT-format reference in this book explains transcript notation used by Batchalign; the CHAT manual is the format reference.
CLAN
For CLAN analysis commands and their options, use the CLAN manual. The former Rust CLAN command manual described code that is no longer in this repository. Its commands are not Batchalign commands, and Batchalign releases do not provide a CLAN executable.
Editors
For editor support backed by Chatter’s language server, follow Chatter’s editor documentation. The former VS Code extension manual in this book described a separate application; Batchalign’s desktop is documented in Desktop application.
Older documentation
The former combined-toolchain manuals remain in repository history. They describe the source tree at that revision and should not be used as current installation or release instructions. Old published URLs redirect to current Batchalign pages or to this page.