# StreamPA 使用说明

这是冻结的 Ours-M / `M_stress_scalar_gate_capacity64`，默认 seed 1337。
它不是旧版 v6 的 47 维 Streaming GOPT。发布的是可下载运行的多组件系统，
不是 HF 网页在线推理服务，也不提供虚构的 Transformers `AutoModel` 接口。

原 checkpoint SHA256：
`870df8dbe3c787487f094e0c4d4ade6bed8fcc5d86b578c4edc57581e81023b4`。
`model_manifest.json` 记录发布 tensor、配置、源文件和各组件身份。
scorer 的全部原 tensor 保留为 safetensors，没有训练、微调、量化或修改值。

## 安装

实际验证环境是本机 Windows 的 Ubuntu WSL2，Python 3.10，CPU FP32。
没有将服务器 Linux 测试写成 Windows 原生测试。Windows 原生和 CUDA 尚未验证。
首次需要联网安装依赖和下载官方固定版本的 Charsiu、词典与 NLTK 资源。

```bash
python3.10 -m venv .venv-streampa
source .venv-streampa/bin/activate
python -m pip install huggingface_hub==0.36.0
python -c "from huggingface_hub import snapshot_download; snapshot_download('faeea/StreamPA', revision='streampa-v1.0.0', local_dir='./StreamPA')"
cd StreamPA
python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements-lock.txt
python -m pip install --no-deps --no-build-isolation .
python scripts/setup_assets.py
python scripts/verify_bundle.py
```

Charsiu 权重未在本仓库重新分发，由 setup 从官方固定 revision 下载并验 hash。
微调 Whisper Base 则已在包内，不能替换为通用预训练 Whisper。各组件并非同一
许可证，详见 `THIRD_PARTY_NOTICES.md`。初始安装若需要网络代理，由用户环境设置，
包内不包含作者 token、代理密码或服务器路径。

## 最短完整推理

输入自己的英文、单声道、16 kHz WAV，不输入参考文本、音素数、GT 边界、分数或 teacher。
输出文件必须不存在，以免覆盖旧结果。

```bash
python -m streampa.infer --audio /path/to/demo.wav --bundle-dir . --device cpu --output scores.json
python -m streampa.stream --audio /path/to/demo.wav --bundle-dir . --device cpu --output prefixes.jsonl
```

单音频命令返回全部 prefix 和 EOF 分数；流式命令逐块读取音频，经过相同的调度和计算。
最大原始音频长度为 30 秒，最大当前 PCN 槽位数为 72。超限明确拒绝，不静默截断。
实际运行路径：收到的 prefix 音频 -> 微调 Whisper N-best -> G2P、Charsiu、PCN、prosody
-> StreamPA。没有用预计算预测代替模型运行。

## 会话 API

```python
from streampa import StreamPAPipeline
pipeline = StreamPAPipeline('./StreamPA', device='cpu', threads=2)
session = pipeline.create_session()
# block 是实际已收到的、16 kHz 单声道 float32 波形数组
for result in session.append(block):
    print(result)
print(session.current())
print(session.finish())  # 调用方 EOF，处理最后不足一个 chunk 的音频
session.reset()          # 新录音前必须重置，清空音频、提交历史和 GRU state
```

完整可执行逐块示例：`python examples/session.py --bundle-dir . --audio demo.wav`。
不同 session 的 state 独立；当前包不提供多线程服务调度，建议顺序调用。

## 如何读输出

- `commit_time` 每 0.64 秒推进，普通 prefix 等收到额外 0.16 秒 lookahead 才处理。
  `audio_end` 是每个前端实际得到的波形末端；`received_audio_end` 可能因整块到达而更晚，
  但前端不能读取更晚部分。EOF 由调用方决定，不从参考标注推导。
- `slots` 保留原始独立 phone head 与 word head 输出、当前 ASR 词归属、时间、mask。
  epsilon/gap 槽位保留；`valid_phone=false` 时不能作为有效局部音素评分。
- `words` 按当前 ASR word ID，平均该词可见槽位的 **word head** 输出用于显示。
  不是平均 phone accuracy，不等同论文按 reference word ID 的共同单元评价。
- GRU 只消费 `new_commit_mask` 对应的新词。没有任何新词时 persistent state 不变，
  但 visible 表示仍进入句级 head，所以句级分数仍可能变化。已提交词不代表其评分永远不变。
- 保留冻结的 legacy commitment，包括复杂 mixed merge 下的已知限制。
  不声称“每一个完成词均有形式化 exactly-once 保证”，没有偷偷换成 corrected 规则。
- 原训练把源标签除以 5；词和句源尺度为 0--10、音素源尺度为 0--2。
  显示成 0--5 时，词/句网络输出乘 2.5，音素网络输出乘 12.5。不裁剪超界估计。
  原始网络输出同时保留。completeness 未参与训练，只在 raw 审计字段保留，不显示为可靠评分。
- 非 `ok` 状态给 `scores=null`，包括空音频、静音、无可用假设、对齐失败、超限等。
  不用零分代替失败，不静默删掉失败 prefix。ASR confidence 也不等于“读对的概率”。

## 离线和性能

```bash
python scripts/setup_assets.py --offline
HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 python -m streampa.infer --audio demo.wav --bundle-dir . --device cpu --output offline_scores.json
python -m pytest tests -q
```

离线复制时保留整个已准备好的 bundle，包括 setup 产生的 `charsiu/` 与
`assets/nltk_data/`。依赖缺失先补 setup，不要用别的权重替换。
`stages` 分开记录前端与 scorer 的计算时间；不把文件读取测试声称为包含真实采集等待的
端到端实时实验。CUDA 分支保留原 Whisper FP16 行为，Charsiu/scorer FP32，但尚未验证。

## 论文与部署边界

发布 seed 1337 不等于论文四 seed 均值。接口测试音频不证明论文 PCC。
训练使用人工监督和 teacher；历史评测样本经过预处理筛选，主要来自朗读数据。
部署移除了历史参考音素长度比例筛选，并使用 audio/EOF 调度；这一差异已明确记录，
不声称任意 WAV 会复现历史样本集合和指标。词典只是通用词到音素的静态资源，
不按当前录音读取其标准文本。未验证自发开放回答泛化，不宣称 GRU/稳定性 loss 的
直接稳定性机制已获得证明。

旧 v6 历史版本保留在 `faeea/StreamPA` 的 `legacy-v6-before-streampa` revision；
其权重、结构和调用方法不能与本包混用。实际已通过和未测试项目见 `validation_summary.json`。