FlexAligner Models

Official acoustic-model bundles for FlexAligner

GitHub · PyPI · English · 简体中文

This repository distributes the official acoustic-model assets for USTCPhonetics/FlexAligner, a wav2vec 2.0-based forced-alignment framework for speech and imperfect transcripts. The Python package, CLI, implementation status, and complete usage documentation are maintained in the GitHub repository.

English

Release status

Language	Bundle	Status in flexaligner==0.2.0a1
English	en/chunker + en/aligner	Release-tested for CPU single-file alignment; supported by the guarded CLI downloader
Mandarin	zh/chunker + zh/aligner	Weights are preserved; the package's complete Mandarin text-processing and alignment pipeline remains a reserved interface

The presence of Mandarin weights does not imply that the current Python package implements Mandarin tokenization, pronunciation generation, or end-to-end alignment.

Repository layout

.
├── README.md
├── model_manifest.json
├── en
│   ├── chunker
│   └── aligner
└── zh
    ├── chunker
    └── aligner

Each model directory contains model.safetensors plus its Transformers configuration, preprocessor, tokenizer, and vocabulary files. model_manifest.json fixes the English release file set, sizes, and SHA-256 digests used by the package downloader.

Recommended installation and download

Install the published preview:

python -m pip install "flexaligner[inference]==0.2.0a1"

Fetch and validate the pinned English bundle through the package CLI:

# Hugging Face official endpoint
flexaligner models fetch --yes --model-source official

# Explicit domestic mirror endpoint
flexaligner models fetch --yes --model-source mirror

When model paths are omitted during interactive alignment, the CLI first checks the default Hugging Face cache and asks for consent before downloading on a cache miss. Non-interactive use fails closed unless --yes explicitly authorizes the download. The downloader pins v0.2.0a1, requests only the English release files, and validates the manifest hash, file sizes, and SHA-256 digests before use.

For direct Hub access, pin an immutable revision:

from pathlib import Path

from huggingface_hub import snapshot_download

snapshot = Path(
    snapshot_download(
        repo_id="USTCPhonetics/FlexAligner",
        revision="v0.2.0a1",
        allow_patterns=[
            "model_manifest.json",
            "en/chunker/**",
            "en/aligner/**",
        ],
    )
)

chunker_dir = snapshot / "en" / "chunker"
aligner_dir = snapshot / "en" / "aligner"

Use a tag or full commit SHA for reproducible work instead of relying on the mutable main branch. The package release pins Hub commit f9ca09d445e5e8981e43eca6a2f5421526ddc59e.

Alignment example

A local pronunciation dictionary is required. Words absent from the dictionary can use the package's bundled offline English G2P fallback; every generated pronunciation is reported as a structured CLI warning.

flexaligner align \
  --audio recording.wav \
  --text-file transcript.txt \
  --lexicon english.dict \
  --output recording.TextGrid \
  --chunk-metadata recording.alignment.json \
  --num-threads 1

To bypass cache resolution and all network behavior, explicitly provide both --chunker-model and --aligner-model. See the GitHub README for the complete CLI and Python API documentation.

Verified release boundary

• English, CPU, single-file alignment.
• 16 kHz mono PCM16 WAV input.
• Frozen release inference stack: Torch 2.3.1 and Transformers 4.41.2.
• Real-model release E2E: Linux x86_64 with Python 3.10.8.
• Continuous Praat TextGrid words and phones tiers with explicit NULL intervals.
• The Stage 2 aligner uses a nominal 160-sample convolution stride at 16 kHz and a 10 ms frame grid.

No accuracy, demographic coverage, training-domain coverage, dynamic-hop, or sub-millisecond boundary claim is made by this model card.

简体中文

本仓库分发 USTCPhonetics/FlexAligner 的官方声学模型。Python 包、CLI、实现状态和完整用法以 GitHub 项目为准。

发布状态

语言	模型目录	flexaligner==0.2.0a1 状态
英语	en/chunker + en/aligner	已完成 CPU 单文件 release-E2E；包内受控下载器正式支持
普通话	zh/chunker + zh/aligner	权重继续保留；完整的普通话分词、发音生成和端到端对齐链路仍为预留接口

普通话权重存在不代表当前 Python 包已经实现完整的普通话处理链路。

安装当前公开预览版并下载英语模型：

python -m pip install "flexaligner[inference]==0.2.0a1"

# Hugging Face 官方端点
flexaligner models fetch --yes --model-source official

# 国内镜像端点
flexaligner models fetch --yes --model-source mirror

交互式对齐未指定模型路径时，CLI 会先检查默认 Hugging Face cache；缓存缺失时， 必须获得用户确认后才下载。非交互环境不会静默联网，必须由 --yes 明确授权。 下载器固定 v0.2.0a1，仅请求英语发布文件，并在使用前校验 manifest hash、文件大小 和 SHA-256。需要完全离线运行时，应同时显式传入 --chunker-model 和 --aligner-model。

本版本验证范围为英语、CPU、单文件、16 kHz 单声道 PCM16 WAV；真实模型 release-E2E 环境为 Linux x86_64 + Python 3.10.8。输出为连续覆盖时间轴的 Praat TextGrid，words 和 phones 层使用明确的 NULL 区间表示未覆盖时段。

发音词典仍为必需输入。词典缺失的规范化 ASCII 英语词可使用包内离线 G2P 兜底， 每个生成发音都会作为结构化 CLI warning 报告。完整命令、Python API 和能力边界请参阅 GitHub README。

License and provenance / 许可与来源

The model weights are made publicly available without an access gate by USTCPhonetics under the MIT license. FlexAligner source code is distributed in the GitHub repository under the same license.

本仓库模型权重由 USTCPhonetics 以 MIT 许可无条件公开，不设置访问门槛； FlexAligner 源代码在 GitHub 仓库中单独发布，并采用同一许可。

The English bundle in v0.2.0a1 is the exact bundle used by the public-alpha release E2E. The Mandarin bundle is preserved byte-for-byte from Hub revision e6b0be0b2717655165fd0899dc652455c85eabd6. Detailed training-corpus documentation is not included in this model-card revision; unsupported benchmark, population, or domain-coverage claims must not be inferred.

v0.2.0a1 的英语 bundle 是公开 alpha release-E2E 使用的精确模型；普通话 bundle 从 Hub revision e6b0be0b2717655165fd0899dc652455c85eabd6 逐字节保留。 本版模型卡尚未提供详细训练语料说明，不应据此推导未明确报告的准确率、人群或领域覆盖结论。