Install & Compatibility
Where this runs
tested against v2.18.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.258s · 89.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.268s · 86MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load_ark
✓ from kaldiio import load_ark
load_scp
✓ from kaldiio import load_scp
save_ark
✓ from kaldiio import save_ark
✗ import kaldiio.save_ark
save_ark is a function directly exposed in the top-level package for convenience, not typically accessed as a submodule.
ReadHelper
✓ from kaldiio import ReadHelper
WriteHelper
✓ from kaldiio import WriteHelper
open_like_kaldi
✓ from kaldiio import open_like_kaldi
This quickstart demonstrates how to write a dictionary of NumPy arrays to a Kaldi .ark file and generate a corresponding .scp file using `save_ark`. It then shows two common methods for reading data: `ReadHelper` for sequential iteration (supporting Kaldi-style specifiers and pipes) and `load_scp` for random access to features by utterance ID.
import numpy as np
from kaldiio import load_scp, ReadHelper, WriteHelper, save_ark
# Example: Create dummy data for writing
utt_ids = ['utt1', 'utt2', 'utt3']
features = {
'utt1': np.random.rand(100, 40).astype(np.float32),
'utt2': np.random.rand(120, 40).astype(np.float32),
'utt3': np.random.rand(90, 40).astype(np.float32)
}
# Write features to an ARK file and generate an SCP file
output_ark_path = 'output.ark'
output_scp_path = 'output.scp'
save_ark(output_ark_path, features, scp=output_scp_path)
print(f"Written to {output_ark_path} and {output_scp_path}")
# Read SCP file using ReadHelper (sequential access, supports pipes)
print("\nReading via ReadHelper (scp:)...")
with ReadHelper(f'scp:{output_scp_path}') as reader:
for key, matrix in reader:
print(f"Key: {key}, Matrix shape: {matrix.shape}")
# Read SCP file using load_scp (random access, returns dict-like object)
print("\nReading via load_scp (random access)...")
loaded_features = load_scp(output_scp_path)
print(f"Loaded 'utt2' shape: {loaded_features['utt2'].shape}")
# Cleanup (optional)
import os
os.remove(output_ark_path)
os.remove(output_scp_path)
Debug
Known issues
gotchaUsers often confuse `kaldiio` with older or related libraries like `kaldi_io` (from Karel Vesely) or `torchaudio.kaldi_io`. The `torchaudio.kaldi_io` module, in particular, is deprecated since version 2.8 and will be removed in 2.9, potentially leading to breaking changes if not using `kaldiio` directly.fixEnsure you are importing directly from `kaldiio` (`from kaldiio import ...`) and that it is the installed package, not an indirect dependency or a different library.
affects: All versions
breakingThe `wav` option, previously available in `ReadHelper` for WAV file processing, was removed in version 2.11.0. Code relying on this option will break.fixFor WAV file I/O, use the dedicated `kaldiio.wavio` functions directly or leverage `kaldiio`'s support for reading WAV/FLAC files via extended ark formats if applicable. Review the `ReadHelper` documentation for current functionality.
affects: >=2.11.0
breakingVersion 2.16.0 introduced support for an 'extended ark format'. Older versions of `kaldiio` (prior to 2.16.0) might not be able to correctly read or fully utilize `.ark` files created with these extended formats by newer `kaldiio` versions or other Kaldi tools.fixUpgrade `kaldiio` to the latest version to ensure compatibility with all supported `.ark` formats, especially if you are working with recently generated Kaldi data.
affects: <2.16.0 (reading newer formats)
gotchaKaldi's I/O often involves complex `rspecifiers` and `wspecifiers` which can include UNIX pipes (e.g., `ark:gunzip -c file.ark.gz |`). Incorrect formatting or environment issues with pipe commands are common pitfalls. `kaldiio` explicitly supports 'pipe fashion' for functions like `load_scp` (since v2.15.0) and `ReadHelper`.fixCarefully construct your specifiers. For debugging pipe issues, try running the pipe command directly in the shell to isolate the problem. `kaldiio`'s `open_like_kaldi` and `ReadHelper` are designed to abstract away some of this complexity, but understanding Kaldi's I/O conventions is beneficial.
affects: All versions
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'raw_mfcc_dev_clean.1.ark:17\r\n'
This error often occurs when .scp files, created on Windows, contain Windows-style line endings (CRLF), which are then interpreted as part of the filename on Unix-like systems, leading to an incorrect file path.
fixConvert the .scp file to use Unix-style line endings (LF). This can be done using tools like `dos2unix` or by opening and saving the file with a text editor configured for Unix line endings.
UnicodeDecodeError: 'ascii' codec can't decode byte 0xfc in position ...
This error typically arises when `kaldiio` attempts to read an .scp or .ark file that contains characters not compatible with the default system encoding (often ASCII), or if file paths contain non-ASCII characters.
fixEnsure that the .scp and .ark files and any associated paths use a consistent, compatible encoding, preferably UTF-8, and avoid special characters in file paths.
TypeError: scp file can be created only if the output ark file is a file or a seekable file descriptor.
`kaldiio` raises this error when a user attempts to write both an .ark and an .scp file simultaneously, but the specified .ark output is a non-seekable stream (like a pipe), preventing the library from recording byte offsets for the .scp file.
fixWhen writing both .ark and .scp files, ensure the .ark output is a direct file path, not a pipe, allowing `kaldiio` to manage offsets properly.
ModuleNotFoundError: No module named 'kaldiio'
The `kaldiio` library is not installed in the Python environment being used, or the environment's `PYTHONPATH` does not include the directory where `kaldiio` is located.
fixInstall the `kaldiio` library using pip: `pip install kaldiio`.
Upgrade
Version history
2.18.1latest on PyPI · released Mar 6, 2025
Audit
Dependencies
numpyrequiredFundamental for handling matrix and vector data read from/written to Kaldi archives. While not a direct PyPI dependency, it's implicitly required for almost all practical usage.