Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quick Start

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

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

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

For the full command surface, see the CLI Reference.

Before you start

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

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

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

Basic command shape

batchalign3 [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS] [PATHS...]
  • Global options go before the command.
  • Most processing commands use -o/--output for a destination directory.
  • Omitting -o/--output means in-place processing when the command supports it.

Transcribe audio to CHAT

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

To use a local Whisper model:

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

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

Align transcripts against audio

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

Common useful flags:

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

Add morphosyntactic analysis

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

Useful variants:

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

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

Verbosity

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

Run logs

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

Remote server mode

For commands that support explicit remote dispatch:

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

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

Next steps

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