salute-speech

使用 Sber Salute Speech 异步 API 转录音频文件。 俄罗斯首个 STT，支持 ru-RU、en-US、kk-KZ、ky-KG、uz-UZ。

# Audio Transcription with Sber Salute Speech

Transcribe audio/video files to text with timestamps via Salute Speech async REST API.

## Requirements

- **API Key**: Environment variable `SALUTE_AUTH_DATA` must be set (Base64-encoded `client_id:client_secret` or raw authorization key from https://developers.sber.ru/studio/).
- **SSL note**: The script disables SSL verification by default (`verify_ssl=False`) because Sber's certificate chain is non-standard. This is expected.

## Supported formats & encodings

| Audio encoding | Content-Type | Typical extensions |
|---------------|-------------|--------------------|
| `MP3` | `audio/mpeg` | `.mp3` |
| `PCM_S16LE` | `audio/wav` | `.wav` |
| `OPUS` | `audio/ogg` | `.ogg`, `.opus` |
| `FLAC` | `audio/flac` | `.flac` |
| `ALAW` | `audio/alaw` | `.alaw` |
| `MULAW` | `audio/mulaw` | `.mulaw` |

## Supported languages

`ru-RU`, `en-US`, `kk-KZ` (Kazakh), `ky-KG` (Kyrgyz), `uz-UZ` (Uzbek).

## Workflow

1. **Identify input files** — from user request.
2. **Read API key** from host environment.
3. **Run transcription** — execute `salute_transcribe.py` with `uv` and appropriate arguments.
4. **Deliver results** — present to user human-readable transcript with timestamps to the user and give a direct link to files.

## Usage

```bash
uv run --with requests {baseDir}/salute_transcribe.py \
  --file /path/to/audio.mp3 \
  --output_dir ~/.openclaw/workspace/transcriptions \
  --lang ru-RU
```

### Arguments

| Argument | Required | Default | Description |
|----------|----------|---------|-------------|
| `--file` | **Yes** | — | Path to audio/video file |
| `--output_dir` | No | `~/.openclaw/workspace/transcribations` | Output directory for results |
| `--lang` | No | `ru-RU` | Language code: `ru-RU`, `en-US`, `kk-KZ`, `ky-KG`, `uz-UZ` |
| `--audio-encoding` | No | `MP3` | Codec: `MP3`, `PCM_S16LE`, `OPUS`, `FLAC`, `ALAW`, `MULAW` |
| `--model` | No | `general` | Recognition model: `general` or `callcenter` |
| `--hyp-count` | No | `1` | Number of alternative hypotheses: `1` or `2` |
| `--max-wait-time` | No | `300` | Max seconds to wait for async result |
| `--print` | No | off | Also print transcription to stdout |

### Content-Type mapping

When the file extension doesn't match `audio/mpeg`, adjust `content_type` in the script or add logic. Current default is `audio/mpeg` (MP3). For `.wav` files use `audio/wav`, etc.

## Output files

For input file `meetingABC.mp3` the script produces:

| File | Description |
|------|-------------|
| `meetingABC_recognition_orig.json` | Raw API response (full JSON with all hypotheses, timing, confidence) |
| `meetingABC_pretty.txt` | Formatted human-readable transcript with timestamps |

### Output text format

```
[00:01 - 00:20]:
Ну, даже если сосредоточиться на идее узкой щели.

[00:20 - 00:45]:
Следующий фрагмент текста здесь.
```

## Notes

- Token is valid for ~30 minutes; the script fetches a new one each run.
- Large files (>1 hour) may need `--max-wait-time` increased beyond 300s.
- The `callcenter` model is optimized for telephony audio (8kHz, mono).
- Profanity filter is disabled by default (`enable_profanity_filter=False`).
- The script uses **normalized text** by default (numbers as digits, abbreviations expanded). Raw text is also available in the JSON output.

---

## 中文说明

# 使用 Sber Salute Speech 进行音频转录

通过 Salute Speech 异步 REST API 将音频/视频文件转录为带时间戳的文本。

## 要求

- **API 密钥**：必须设置环境变量 `SALUTE_AUTH_DATA`（Base64 编码的 `client_id:client_secret`，或来自 https://developers.sber.ru/studio/ 的原始授权密钥）。
- **SSL 说明**：由于 Sber 的证书链不标准，脚本默认禁用 SSL 验证（`verify_ssl=False`）。这是预期行为。

## 支持的格式与编码

| Audio encoding | Content-Type | Typical extensions |
|---------------|-------------|--------------------|
| `MP3` | `audio/mpeg` | `.mp3` |
| `PCM_S16LE` | `audio/wav` | `.wav` |
| `OPUS` | `audio/ogg` | `.ogg`, `.opus` |
| `FLAC` | `audio/flac` | `.flac` |
| `ALAW` | `audio/alaw` | `.alaw` |
| `MULAW` | `audio/mulaw` | `.mulaw` |

## 支持的语言

`ru-RU`、`en-US`、`kk-KZ`（哈萨克语）、`ky-KG`（吉尔吉斯语）、`uz-UZ`（乌兹别克语）。

## 工作流

1. **识别输入文件** — 来自用户请求。
2. **读取 API 密钥** — 来自主机环境。
3. **运行转录** — 使用 `uv` 并配以适当参数执行 `salute_transcribe.py`。
4. **交付结果** — 向用户呈现带时间戳的人类可读转录文本，并提供文件的直接链接。

## 用法

```bash
uv run --with requests {baseDir}/salute_transcribe.py \
  --file /path/to/audio.mp3 \
  --output_dir ~/.openclaw/workspace/transcriptions \
  --lang ru-RU
```

### 参数

| Argument | Required | Default | Description |
|----------|----------|---------|-------------|
| `--file` | **Yes** | — | 音频/视频文件的路径 |
| `--output_dir` | No | `~/.openclaw/workspace/transcribations` | 结果输出目录 |
| `--lang` | No | `ru-RU` | 语言代码：`ru-RU`、`en-US`、`kk-KZ`、`ky-KG`、`uz-UZ` |
| `--audio-encoding` | No | `MP3` | 编解码器：`MP3`、`PCM_S16LE`、`OPUS`、`FLAC`、`ALAW`、`MULAW` |
| `--model` | No | `general` | 识别模型：`general` 或 `callcenter` |
| `--hyp-count` | No | `1` | 备选假设数量：`1` 或 `2` |
| `--max-wait-time` | No | `300` | 等待异步结果的最大秒数 |
| `--print` | No | off | 同时将转录结果打印到 stdout |

### Content-Type 映射

当文件扩展名与 `audio/mpeg` 不匹配时，请调整脚本中的 `content_type` 或添加逻辑。当前默认为 `audio/mpeg`（MP3）。对于 `.wav` 文件请使用 `audio/wav`，依此类推。

## 输出文件

对于输入文件 `meetingABC.mp3`，脚本会生成：

| File | Description |
|------|-------------|
| `meetingABC_recognition_orig.json` | 原始 API 响应（包含所有假设、时间和置信度的完整 JSON） |
| `meetingABC_pretty.txt` | 格式化的人类可读转录文本，带时间戳 |

### 输出文本格式

```
[00:01 - 00:20]:
Ну, даже если сосредоточиться на идее узкой щели.

[00:20 - 00:45]:
Следующий фрагмент текста здесь.
```

## 注意事项

- 令牌有效期约为 30 分钟；脚本每次运行都会获取一个新令牌。
- 大文件（>1 小时）可能需要将 `--max-wait-time` 增加到 300 秒以上。
- `callcenter` 模型针对电话音频（8kHz，单声道）进行了优化。
- 脏话过滤器默认禁用（`enable_profanity_filter=False`）。
- 脚本默认使用 **规范化文本**（数字以阿拉伯数字呈现，缩写展开）。原始文本也可在 JSON 输出中获取。