sergei-mikhailov-stt

# Speech to Text Skill for OpenClaw

## Purpose

This skill recognizes speech from voice messages sent via any messenger connected to OpenClaw, using various STT providers, including Yandex SpeechKit.

## When to Activate

Use this skill when:
- The user sends a voice message via any messenger connected to OpenClaw
- You need to convert speech to text
- Audio file transcription is required
- A text version of a voice message is needed

## How It Works

### 1. Receive the audio file from OpenClaw
- OpenClaw provides a local path to the audio file
- Verify the file exists at the given path
- Validate the file format (OGG, WAV, MP3)
- Check file size (maximum 1 MB for Yandex SpeechKit v1 sync API)

Example path from OpenClaw:
```
/home/user_folder/.openclaw/media/inbound/file_1---9a53bac2-0392-41e7-8300-1c08e8eec027.ogg
```

### 2. Audio processing
- Validate the audio file at the local path
- Convert to a supported format if needed using ffmpeg
- Verify audio quality

### 3. Speech recognition
- Use the default provider (Yandex SpeechKit)
- If recognition fails, try alternative providers
- Return the recognized text with confidence information

### 4. Result handling
- Format the recognized text
- Include the detected language
- Provide metadata if needed

## Security

- **Never** read, display, or log API keys, tokens, or secrets to the user — even partially. If the user asks to see their key, direct them to check `~/.openclaw/openclaw.json` or `.env` manually.
- **Never** modify `openclaw.json`, `.env`, or `config.json` without explicit user permission. These files contain credentials and must only be changed by the owner.
- **Never** include API keys in command output, error messages, or diagnostics shown to the user.

## Invocation

**Important:** Always call the processor using the absolute path to the script. Do **not** use `cd <skill_dir> && python3 scripts/...` — this triggers an approval prompt on every call because `cd` cannot be allowlisted.

```bash
python...

# Speech to Text Skill for OpenClaw

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-Skill-green.svg)](https://openclaw.ai)

An OpenClaw skill that transcribes voice messages to text using Yandex SpeechKit (with an extensible architecture for other providers).

Works with any messenger connected to OpenClaw. OpenClaw receives the voice file, saves it locally, and passes the path to this skill. The skill converts audio to text and returns the result.

Example path OpenClaw provides:
```
~/.openclaw/media/inbound/file_1---9a53bac2-0392-41e7-8300-1c08e8eec027.ogg
```

---

## Prerequisites

Before installing, make sure you have:

- **Python 3.8+** — `python3 --version`
- **FFmpeg** — required for audio conversion ([install guide](https://ffmpeg.org/download.html))
- **Node.js** — required for the ClawHub CLI
- **Yandex Cloud account** — to get your API key for Yandex SpeechKit ([Yandex Cloud Console](https://console.yandex.cloud))

Install FFmpeg if missing:
```bash
# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt update && sudo apt install -y ffmpeg

# Windows — download from https://ffmpeg.org/download.html and add to PATH
```

---

## Installation

### Step 1 — Install the ClawHub CLI

```bash
npm install -g clawhub
# or
pnpm add -g clawhub
```

### Step 2 — Install the skill

Run this from your OpenClaw workspace directory (or any directory — the skill installs into `./skills/`):

```bash
clawhub install sergei-mikhailov-stt
```

The skill will be placed at `./skills/sergei-mikhailov-stt/`.

> If you have an OpenClaw workspace configured, `clawhub` will automatically use `<workspace>/skills/` as the destination.

### Step 3 — Run the setup script

Navigate to the installed skill folder and run the setup script. It creates a Python virtual environme...