telegram-voice-to-voice-macos

适用于 macOS Apple Silicon 的 Telegram 语音转语音：使用 yap (Speech.framework) 转录入站 .ogg 语音笔记，并通过 say+ffmpeg 使用 Telegram 语音笔记进行回复。与 Linux/Windows 不兼容。

# Telegram voice-to-voice (macOS Apple Silicon only)

This is an **OpenClaw skill**.

## Requirements

- macOS on Apple Silicon.
- `yap` CLI available in `PATH` (Speech.framework transcription).
  - Project: https://github.com/finnvoor/yap (by finnvoor)
- `ffmpeg` available in `PATH`.

## Compatibility note (important)

This skill is **macOS-only** (uses `say` + Speech.framework). The skill registry cannot enforce OS restrictions, so installing/running it on Linux/Windows will result in runtime failures.

## Persistent reply mode (voice vs text)

Store a small per-user preference file in the workspace:

- State file: `voice_state/telegram.json`
- Key: Telegram sender user id (string)
- Values:
  - `"voice"` (default): reply with a Telegram voice note
  - `"text"`: reply with a single text message

If the file does not exist or the sender id is missing: assume `"voice"`.

### Toggle commands

If an inbound **text** message is exactly:

- `/audio off` → set state to `"text"` and confirm with a short text reply.
- `/audio on` → set state to `"voice"` and confirm with a short text reply.

## Getting the inbound audio (.ogg)

Telegram voice notes often show up as `<media:audio>` in message text.
OpenClaw saves the attachment to disk (typically `.ogg`) under:

- `~/.openclaw/media/inbound/`

Recommended approach:

1) If the inbound message context includes an attachment path, use it.
2) Otherwise, take the most recent `*.ogg` from `~/.openclaw/media/inbound/`.

## Transcription

Default locale: **macOS system locale**.

Optional env:

- `YAP_LOCALE` — override the transcription locale (e.g. `it-IT`, `en-US`).

Preferred:

- `yap transcribe --locale "${YAP_LOCALE:-<system>}" <path.ogg>`
  - If `YAP_LOCALE` is not set, the helper script will use the macOS system locale (from `defaults read -g AppleLocale`).

If transcription fails or is empty: ask the user to repeat or send text.

Helper script:

- `scripts/transcribe_telegram_ogg.sh [path.ogg]`

## Reply behavior

### Mode: voice (default)

Voice default: **SYSTEM** (uses the current macOS system voice). You can override by passing a specific voice name to the helper script.

1) Generate the reply text.
2) Convert reply text to an OGG/Opus voice note using:

- `scripts/tts_telegram_voice.sh "<reply text>" [SYSTEM|VoiceName]`

The script prints the generated `.ogg` path to stdout.

3) Send the `.ogg` back to Telegram as a **voice note** (not a generic audio file):

- use the `message` tool with `asVoice: true` and `media: <path.ogg>`
- optionally set `replyTo` to thread the response

Notes:

- Use `SYSTEM` to rely on the current macOS system voice (recommended).

### Mode: text

Reply with a single text message:

- `Transcription: <...>`
- `Reply: <...>`

---

## 中文说明

# Telegram 语音转语音（仅限 macOS Apple Silicon）

这是一个 **OpenClaw 技能**。

## 要求

- 运行于 Apple Silicon 的 macOS。
- `PATH` 中可用的 `yap` CLI（Speech.framework 转录）。
  - 项目地址：https://github.com/finnvoor/yap （作者 finnvoor）
- `PATH` 中可用的 `ffmpeg`。

## 兼容性说明（重要）

本技能**仅限 macOS**（使用 `say` + Speech.framework）。技能注册表无法强制 OS 限制，因此在 Linux/Windows 上安装/运行将导致运行时失败。

## 持久化回复模式（语音 vs 文本）

在工作区中为每个用户存储一个小的偏好设置文件：

- 状态文件：`voice_state/telegram.json`
- 键：Telegram 发送者用户 id（字符串）
- 值：
  - `"voice"`（默认）：以 Telegram 语音笔记回复
  - `"text"`：以单条文本消息回复

如果文件不存在或缺少发送者 id：假定为 `"voice"`。

### 切换命令

如果入站的**文本**消息恰好为：

- `/audio off` → 将状态设为 `"text"` 并以简短文本回复确认。
- `/audio on` → 将状态设为 `"voice"` 并以简短文本回复确认。

## 获取入站音频（.ogg）

Telegram 语音笔记常以 `<media:audio>` 形式出现在消息文本中。
OpenClaw 将附件保存到磁盘（通常为 `.ogg`），位于：

- `~/.openclaw/media/inbound/`

推荐做法：

1) 如果入站消息上下文包含附件路径，则使用它。
2) 否则，取 `~/.openclaw/media/inbound/` 中最新的 `*.ogg`。

## 转录

默认区域设置：**macOS 系统区域设置**。

可选环境变量：

- `YAP_LOCALE` — 覆盖转录区域设置（例如 `it-IT`、`en-US`）。

首选方式：

- `yap transcribe --locale "${YAP_LOCALE:-<system>}" <path.ogg>`
  - 如果未设置 `YAP_LOCALE`，辅助脚本将使用 macOS 系统区域设置（来自 `defaults read -g AppleLocale`）。

如果转录失败或为空：请用户重复一次或发送文本。

辅助脚本：

- `scripts/transcribe_telegram_ogg.sh [path.ogg]`

## 回复行为

### 模式：voice（默认）

语音默认：**SYSTEM**（使用当前 macOS 系统语音）。你可以通过向辅助脚本传入特定语音名称来覆盖。

1) 生成回复文本。
2) 使用以下命令将回复文本转换为 OGG/Opus 语音笔记：

- `scripts/tts_telegram_voice.sh "<reply text>" [SYSTEM|VoiceName]`

该脚本会将生成的 `.ogg` 路径打印到 stdout。

3) 将 `.ogg` 作为**语音笔记**（而非普通音频文件）发回 Telegram：

- 使用 `message` 工具，并设置 `asVoice: true` 和 `media: <path.ogg>`
- 可选地设置 `replyTo` 以将回复串入对应会话线程

注意：

- 使用 `SYSTEM` 以依赖当前 macOS 系统语音（推荐）。

### 模式：text

以单条文本消息回复：

- `Transcription: <...>`
- `Reply: <...>`