Kaldi Alignment Methods

0.9.3 · active · verified Thu Apr 16

kaldialign is a Python package that provides wrappers for Kaldi's core alignment and edit distance computation functions. It directly incorporates Kaldi's C++ code via pybind11 to ensure identical Word Error Rate (WER) and alignment results as Kaldi, addressing inconsistencies found in other Levenshtein implementations. Currently at version 0.9.3, it receives regular updates focusing on performance enhancements and broader platform compatibility through pre-built wheels.

Common errors

```
CMake Error at CMakeLists.txt:...
```
cause This error typically occurs when attempting to install `kaldialign` from source without a properly configured C++ compiler and CMake build system. A specific bug related to `CMakeLists.txt` not being found was fixed in v0.4.0, but general build environment issues can still lead to this.

fix For most users, `pip install kaldialign` should download a pre-built wheel, avoiding compilation. If building from source is necessary, ensure you have CMake and a C++ compiler (like GCC or Clang) installed and accessible in your system's PATH.
```
ImportError: cannot import name 'align' from 'kaldialign'
```
cause This indicates that the `kaldialign` Python package, or its underlying C++ extensions, were not correctly installed or are not accessible in your current Python environment. This can happen due to partial installations, conflicting packages, or environment issues.

fix Try reinstalling the package in a clean virtual environment: `python -m venv .venv && source .venv/bin/activate && pip install --no-cache-dir kaldialign`. If errors persist, check the full installation log for compilation failures.

Warnings

gotcha When using `align()`, the `epsilon` parameter must be a 'null' symbol (e.g., `'*'`) that is guaranteed not to appear in any of the input sequence elements (words/characters). If `epsilon` is present in the sequences, it can lead to incorrect alignment results.
Fix: Choose an `epsilon` symbol (like `*` or `_`) that is unique and known not to exist in your reference or hypothesis sequences.
gotcha The `bootstrap_wer_ci` function, introduced in v0.8.0 and significantly optimized in v0.9.0, now performs its core computation in C++ for a 15x speed improvement. While this boosts performance, it means that the underlying logic for bootstrapping cannot be directly inspected or modified via Python.
Fix: Be aware that the implementation is now C++-based. Rely on the provided Python interface for its functionality.
gotcha For computing WER or alignments using `sclite` style weights (insertion/deletion cost 3, substitution cost 4), you must explicitly pass `sclite_mode=True` to the `align()` or `edit_distance()` functions. The default behavior aligns with standard Kaldi weights.
Fix: If `sclite`-style scoring is required, ensure your function call includes `sclite_mode=True`, e.g., `edit_distance(ref, hyp, sclite_mode=True)`.

Install

pip install kaldialign Install latest version

Imports

align
```
from kaldialign import align
```
edit_distance
```
from kaldialign import edit_distance
```
bootstrap_wer_ci
```
from kaldialign import bootstrap_wer_ci
```

Quickstart

This quickstart demonstrates the core `align` and `edit_distance` functions, as well as the `bootstrap_wer_ci` method for calculating Word Error Rate confidence intervals. The `epsilon_symbol` for `align` must be a character not present in either sequence to represent insertions/deletions.

from kaldialign import align, edit_distance, bootstrap_wer_ci

# Example 1: Basic Alignment
ref_seq = ['hello', 'world', 'this', 'is', 'a', 'test']
hyp_seq = ['hello', 'this', 'was', 'a', 'test']
epsilon_symbol = '*'

alignment = align(ref_seq, hyp_seq, epsilon_symbol)
print(f"Alignment: {alignment}")
# Expected: [('hello', 'hello'), ('world', '*'), ('*', 'this'), ('this', 'was'), ('is', '*'), ('a', 'a'), ('test', 'test')]

# Example 2: Edit Distance (Insertions, Deletions, Substitutions)
ed_results = edit_distance(ref_seq, hyp_seq)
print(f"Edit Distance: {ed_results}")
# Expected: {'ins': 1, 'del': 2, 'sub': 1, 'total': 4}

# Example 3: Bootstrapping WER Confidence Intervals (since v0.8.0)
# ref and hyp should be lists of lists of words (representing sentences)
# E.g., [['sentence', 'one'], ['sentence', 'two']] and [['sentece', 'one'], ['sentence', 'too']]
ref_utterances = [['the', 'quick', 'brown', 'fox'], ['jumps', 'over', 'the', 'lazy', 'dog']]
hyp_utterances = [['the', 'quik', 'brown', 'fox'], ['jump', 'over', 'the', 'lazi', 'dog']]

wer_ci = bootstrap_wer_ci(ref_utterances, hyp_utterances)
print(f"WER 95% Confidence Interval: {wer_ci}")

view raw JSON →