Generate Russian Speech from Text

claude-skill-yandex-tts -- Claude Code Skill for text-to-speech via Yandex Station

A skill for Claude Code that enables voice output through Yandex Station using Alice's voice. When a user asks to speak something through the speaker or have an answer read aloud, Claude Code automatically sends the text to the station.

How it works

┌─────────────┐     ┌──────────────┐     ┌───────────────────┐     ┌────────────────┐
│ Claude Code  │────>│  /speak      │────>│  Yandex Quasar    │────>│ Yandex Station │
│  (CLI)       │     │  tts.py      │     │  API (Glagol)     │     │  (Alice)       │
└─────────────┘     └──────────────┘     └───────────────────┘     └────────────────┘
                     Pure Python 3          WebSocket (WSS)         Text-to-speech
                     Stdlib only            port 1961               with Alice voice

Glagol protocol is the local WebSocket API for Yandex Station. The script:

1. Obtains conversation_token via Yandex Quasar API (OAuth authorization)
2. Connects directly to the station over local network (WSS, port 1961)
3. Sends repeat_phrase command -- the station speaks the text in Alice's voice
4. Token is cached for 25 minutes, station IP is auto-discovered via mDNS

Requirements

• Python 3.10+ (uses type hints dict[str, str], str | None)
• macOS (mDNS discovery via dns-sd; on Linux you need to specify IP manually)
• Yandex account with a linked Yandex Station
• Computer and station must be on the same local network

No external dependencies -- the script uses only Python's standard library.

Installation

1. Clone the repository

git clone git@github.com:rasperepodvipodvert/claude-skill-yandex-tts.git ~/.claude/skills/speak

2. Create config

cp ~/.claude/skills/speak/.env.example ~/.claude/skills/speak/.env

3. Get tokens (see section below)

Fill in MUSIC_TOKEN in the .env file.

4. Find Device ID

~/.claude/skills/speak/scripts/tts.py --list-devices

Output will show all speakers on your account:

Fetching device list...
Scanning local network via mDNS...
  Station Mini  platform=yandexmini_2  id=XXXXXXXXXXXXXXX  IP: 192.168.1.100

Copy the id and platform to .env:

DEVICE_ID=XXXXXXXXXXXXXXX
DEVICE_PLATFORM=yandexmini_2

5. Test

~/.claude/skills/speak/scripts/tts.py "Hello, I'm Claude!"

If everything is configured correctly, the speaker will say the text.

6. Make script executable (if needed)

chmod +x ~/.claude/skills/speak/scripts/tts.py

Getting tokens

You need a MUSIC_TOKEN (Yandex OAuth token). The token retrieval procedure is based on the method from the AlexxIT/YandexStation project and uses public client_id/client_secret from the Yandex Music app.

Step 1: Get session_id via login

Log in to https://passport.yandex.ru and extract Session_id from cookies.

Or programmatically (requires password, 2FA, etc.) -- manual retrieval via browser is recommended.

Step 2: Get x_token

curl -s 'https://mobileproxy.passport.yandex.net/1/bundle/oauth/token_by_sessionid' \
  -H 'Ya-Client-Host: passport.yandex.ru' \
  -H 'Ya-Client-Cookie: Session_id=YOUR_SESSION_ID_HERE' \
  -d 'client_id=c0ebe342af7d48fbbbfcf2d2eedb8f9e&client_secret=ad0a908f0aa341a182a37ecd75bc319e'

Response contains x_token:

{"status": "ok", "x_token": "y0_AgAAAA..."}

Step 3: Get music_token (OAuth)

curl -s 'https://oauth.yandex.ru/token' \
  -d 'grant_type=x-token&client_id=23cabbbdc6cd418abb4b39c32c41195d&client_secret=53bc75238f0c4d08a118e51fe9203300&access_token=YOUR_X_TOKEN_HERE'

Response contains access_token -- this is your MUSIC_TOKEN:

{"access_token": "y0_AgAAAAAF...", "token_type": "bearer", ...}

Step 4: Write to .env

MUSIC_TOKEN=y0_AgAAAAAF...

Note: The client_id and client_secret in the commands above are public keys from Yandex apps (from the YandexStation project). They are not secrets.

MUSIC_TOKEN lifetime: The token is valid for approximately 1 year. After expiration, repeat the retrieval procedure (steps 1--3).

Usage

From command line

# Speak text
~/.claude/skills/speak/scripts/tts.py "Good morning! It will be sunny today."

# List all speakers on account (with mDNS IP discovery)
~/.claude/skills/speak/scripts/tts.py --list-devices

# Discover station IP via mDNS and save to .env
~/.claude/skills/speak/scripts/tts.py --discover

As a Claude Code skill

After installation in ~/.claude/skills/speak/, the skill is available automatically. Claude Code will use it when:

• User asks to read the answer aloud
• User asks to say something through the speaker
• It makes sense in the conversation to speak the answer

Example:

> /speak Tell me a joke through the speaker

Configuration (.env)

* If STATION_IP is not specified or the station doesn't respond, the script will attempt to find it via mDNS automatically.

Features

• Zero dependencies -- pure Python 3, stdlib only. WebSocket client implemented manually per RFC 6455.
• Auto IP discovery -- station is found via mDNS (_yandexio._tcp service). On macOS uses dns-sd.
• Token caching -- conversation_token is saved to .env and refreshed every 25 minutes.
• Text cleanup -- Markdown formatting, code blocks, special characters are automatically removed before playback.
• 500 character limit -- longer texts are truncated.

Speaker compatibility

The script works with any Yandex speaker that supports the Glagol protocol:

Platform ID may differ across revisions. Use --list-devices to get the exact value.

Troubleshooting