uxtg 0.3.0

Production-oriented TextGrid, JSON, and MLF toolkit.

uxtg

uxtg 是一个面向生产集成的 Python 库，用于处理 Praat TextGrid、稳定 JSON 文档协议，以及 HTK MLF 转换流程。

Features

• 分层架构：domain、codecs、documents、mappers
• Pydantic v2 核心领域模型
• Praat TextGrid / TextTier / IntervalTier 读写
• 稳定的 TextGridJsonDocument 导出与反向映射
• MLF -> TextGrid 转换和 TextGrid 文件落盘
• 统一异常体系与库级 facade API

Installation

poetry add uxtg

Stable API

import uxtg

grid = uxtg.read_textgrid("sample.TextGrid", strict=True)
document = uxtg.textgrid_to_json_document(grid)
restored = uxtg.json_document_to_textgrid(document)
mlf = uxtg.read_mlf("labels.mlf")

Public Objects

• Point, Interval, PointTier, IntervalTier, TextGrid
• TextGridJsonDocument
• MLF

Public Functions

• parse_textgrid(text, *, round_digits=..., strict=True)
• read_textgrid(path, *, round_digits=..., strict=True, encoding=None)
• write_textgrid(textgrid, target, *, null="")
• read_mlf(path_or_text, *, samplerate=..., round_digits=...)
• textgrid_to_json_document(textgrid)
• json_document_to_textgrid(document)

Errors

• UXTGError
• ParseError
• SerializationError
• UnsupportedFormatError
• DomainValidationError

Supported Formats

Format	Read	Write	Notes
Praat TextGrid	Yes	Yes	TextGrid, TextTier, IntervalTier
JSON document	Yes	Yes	Stable protocol via TextGridJsonDocument
HTK MLF	Yes	Partial	Stable MLF -> TextGrid; write emits TextGrid files

Engineering

• pytest + coverage threshold
• ruff
• mypy
• benchmark fixtures
• GitHub Actions CI for Python 3.10 / 3.11 / 3.12

Versioning

0.3.0 是一次破坏性升级版本。后续版本按 semver 演进。