# 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

```bash
poetry add uxtg
```

## Stable API

```python
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 演进。
