Batchalign3

Turn audio recordings into fully annotated CHAT transcripts — or enrich existing transcripts — from the command line.

• Transcribe — speech-to-text from audio (Whisper, Rev.AI)
• Morphotag — morphosyntactic analysis (%mor and %gra tiers)
• Align — forced alignment of words to audio timestamps
• Translate — add translation tiers (%xtra)
• Segment — utterance boundary detection
• Benchmark — WER scoring against gold transcripts

Part of the TalkBank project. Runs on macOS, Windows, and Linux.

Get Started

Easiest: Download and double-click

No terminal required. Download the installer for your platform, double-click it, and follow the on-screen prompts:

• macOS: Download install-batchalign3.command — if macOS blocks it, right-click > Open > Open in the dialog
• Windows: Download install-batchalign3.bat — if SmartScreen blocks it, click More info > Run anyway

See installers/README.md for details.

From the terminal

Install the uv package manager, then install Batchalign:

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Close and reopen your terminal, then:

uv tool install batchalign3

Optional extras

uv tool install "batchalign3[asr]"       # Whisper ASR engine
uv tool install "batchalign3[hk]"        # HK/Cantonese engines
uv tool install "batchalign3[all]"       # ASR + diarization + audio features
uv tool install "batchalign3[all,hk]"   # Everything including HK/Cantonese

System requirements

• Python: 3.12 (installed automatically by uv)
• Disk: ~2 GB for ML models (downloaded on first use)
• RAM: 8 GB minimum, 16 GB recommended
• FFmpeg: only needed for MP4 media files
• Platforms: macOS (ARM + Intel), Windows (x86), Linux (x86 + ARM)

See Installation guide for offline install, worker Python resolution, and development setup.

First run

After installing, restart your terminal so the batchalign3 command is on your PATH. Then configure your default ASR engine:

batchalign3 setup

This creates ~/.batchalign.ini. You can also configure non-interactively:

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

The first time you run a processing command (e.g. morphotag), ML models will be downloaded automatically — this is a one-time cost of ~2 GB and may take a few minutes depending on your connection.

See Quick start for a full first-run walkthrough.

Updating

Upgrade to the latest version:

uv tool upgrade batchalign3

If you installed via the one-click installer, re-running the same installer script will upgrade an existing installation.

The CLI will print a notice when a newer version is available on PyPI.

Usage

The safest way to run any command is with a separate output directory, so your originals are never touched:

# Morphosyntactic analysis (%mor and %gra tiers)
batchalign3 morphotag ~/corpus/ -o ~/output/

# Forced alignment (word-level timestamps)
batchalign3 align ~/corpus/ -o ~/output/

# ASR transcription
batchalign3 transcribe ~/recordings/ -o ~/transcripts/ --lang eng

# Translation (%xtra tier)
batchalign3 translate ~/corpus/ -o ~/output/

# Utterance segmentation
batchalign3 utseg ~/corpus/ -o ~/output/

# WER benchmarking
batchalign3 benchmark ~/corpus/

The -o flag is optional — two positional arguments are treated as input/ output/:

batchalign3 morphotag ~/corpus/ ~/output/    # same as -o ~/output/

See CLI reference for the full command list and all flags.

In-place processing

If your corpus is tracked in Git (or you have another backup), you can skip the output directory and write results directly back into the source files. A single argument with no -o is treated as in-place:

batchalign3 morphotag ~/corpus/
batchalign3 align ~/corpus/
batchalign3 translate ~/corpus/

The --in-place flag makes this explicit, and is required when passing multiple input paths:

batchalign3 morphotag --in-place ~/corpus1/ ~/corpus2/

Each .cha file is overwritten with the annotated version. You can then review the changes with git diff and commit when satisfied.

Warning: In-place processing has no undo. If your files are not under version control, copy the folder first or use -o to write to a separate directory.

Verbosity and logs

batchalign3 -v morphotag ~/corpus/ -o ~/output/    # verbose
batchalign3 -vv morphotag ~/corpus/ -o ~/output/   # debug
batchalign3 logs --last                             # most recent run

Server mode

By default, a local server starts automatically and stays running so ML models only load once. If you have a more powerful machine (e.g. one with a GPU), you can run the server there and connect to it from your desktop or laptop:

# On the server (e.g. a GPU workstation called myserver):
batchalign3 serve start --port 9000      # default port is 8000

# From any other machine on the network (use the same port):
batchalign3 --server http://myserver:9000 morphotag ~/corpus/ -o ~/output/

See Server mode for setup details and the remote/local tradeoffs.

Learn more

For users

• Installation guide — system requirements, offline install, updating
• Quick start — first run walkthrough
• CLI reference — all commands and flags
• Server mode — remote dispatch, daemon management
• Performance tips — large corpus processing
• Migrating from Batchalign2 — upgrade path
• TalkBank CHAT manual — CHAT format reference

For developers

• Python API — programmatic access to parsing, validation, and pipelines
• Building & Development — Rust toolchain, dev rebuilds, test matrix
• Batchalign2 compatibility shim — drop-in for CHATFile, Document, BatchalignPipeline

Development

Requires a Rust toolchain, uv, and a talkbank-tools sibling clone.

make sync && make build
./target/debug/batchalign3 --help

Support

• Bug reports and feature requests: https://github.com/TalkBank/batchalign3/issues
• General TalkBank questions: https://talkbank.org/

---

Supported by NIH grant HD082736.