Metadata-Version: 2.4
Name: rsst
Version: 0.1.0
Summary: RSST - Real-time Streaming Speech Transcription
Author-email: Eric <ms626547127@163.com>
License: GPL-3.0
Project-URL: Homepage, https://github.com/bdoffr/rsst
Project-URL: Bug Tracker, https://github.com/bdoffr/rsst/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# RSST - 实时流式语音转写工具库

> **RSST** (Real-time Streaming Speech Transcription) — 一个用于处理 ASR 引擎流式文本输出的缓冲管理工具库。

## 简介

`RSST` 提供了 `StreamingTextBuffer` 类，专门用于管理来自语音识别引擎的流式文本输出。它实现了增量文本更新、中间结果纠错（回滚 + 追加）以及基于标点符号的句级分段，适用于需要实时展示语音转写结果的前端界面（如 QML、Web UI 等）。

## 核心功能

- **增量文本处理**：接收流式文本片段，自动计算与上一次的差异，返回需要回滚的字符数和需要追加的新文本。
- **中间结果纠错**：当 ASR 引擎返回修正后的中间结果时，自动对比前后差异，精确计算回滚位置，避免重复或遗漏显示。
- **句级分段**：基于预设标点符号（如 `。`、`！`、`？`、`.`、`!`、`?` 等）自动判断句子是否完结，将完整句子归入已提交段列表。
- **最终结果确认**：通过 `finalize()` 方法接收 ASR 的最终翻译结果，与当前流式显示内容比对后更新历史文本，并重置缓冲区。

## 安装

### 从源码安装

```bash
  pip install -e .
```

### 从 PyPI 安装（发布后）

```bash
  pip install rsst
```



## API 参考

### `class StreamingTextBuffer`

#### 参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `punctuations` | `tuple[str]` | `("、", "，", "。", "！", "？", ",", ".", "!", "?")` | 用于判断句子完结的标点符号元组 |

#### 属性

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `committed_segments` | `list[str]` | 已完成的句子列表，每个元素以标点符号结尾 |
| `current_buffer` | `str` | 当前正在累积的不完整句子 |
| `last_received` | `str` | 上次接收到的完整中间结果字符串 |
| `history_text` | `str` | 所有已确认句子的累积文本 |

#### 方法

##### `process_stream(incoming_text: str) -> tuple[int, str]`

处理流式文本，计算差异，执行回滚修正并尝试完结句子。

**参数：**
- `incoming_text` (str)：ASR 引擎返回的流式文本。

**返回值：**
- `tuple[int, str]`：`(rollback_count, new_text)`
  - `rollback_count`：需要回滚的字符数。
  - `new_text`：需要追加的新文本。

##### `finalize(final_text: str) -> tuple[int, str]`

使用 ASR 最终翻译结果确认当前文本，更新历史文本并重置缓冲区。

**参数：**
- `final_text` (str)：当前句的最终文本结果。

**返回值：**
- `tuple[int, str]`：`(rollback_count, new_text)`
  - `rollback_count`：需要回滚的字符数。
  - `new_text`：需要追加的新文本。

##### `reset()`

重置临时文本状态（清空已提交段、当前缓冲区和上次接收文本），保留已累积的 `history_text`。

##### `_is_finalized(text: str) -> bool`

检查给定文本是否以标点符号结尾（句子是否完结）。内部方法，通常不需要直接调用。

## 项目结构

```
rsst/
├── rsst/
│   ├── __init__.py
│   └── buffer.py
├── README.md
├── LICENSE
├── pyproject.toml
└── setup.py
```

## 许可证

本项目采用 [GNU General Public License v3 (GPLv3)](https://www.gnu.org/licenses/gpl-3.0.html) 许可证开源。

## 作者

Eric — ms626547127@163.com

## 链接

- 项目主页: https://github.com/bdoffr/rsst
- 问题反馈: https://github.com/bdoffr/rsst/issues
