wyoming-tester/README.md

Wyoming Protocol Tester

A cross-platform tool to test Wyoming protocol TTS (Text-to-Speech) and STT (Speech-to-Text) endpoints.

Requirements

• Python 3.7 or higher
• No external dependencies (uses only Python standard library)

Installation

1. Download or clone this repository
2. No installation needed - the script is ready to use!

Usage

The tool has two modes: STT (Speech-to-Text) and TTS (Text-to-Speech).

Testing Speech-to-Text (STT)

Convert an audio file to text using a Wyoming STT endpoint:

# Linux/macOS
python3 wyoming_tester.py stt --audio test.wav --endpoint localhost:10300

# Windows
python wyoming_tester.py stt --audio test.wav --endpoint localhost:10300

Parameters:

• --audio, -a: Input audio file (must be 16kHz mono WAV format)
• --endpoint, -e: STT server endpoint in format host:port
• --save: Save the endpoint for future use (optional)

Example:

python wyoming_tester.py stt --audio my_voice.wav --endpoint 192.168.1.100:10300 --save

Testing Text-to-Speech (TTS)

Convert text to speech using a Wyoming TTS endpoint:

# Linux/macOS
python3 wyoming_tester.py tts --text "Hello world" --endpoint localhost:10200

# Windows
python wyoming_tester.py tts --text "Hello world" --endpoint localhost:10200

Parameters:

• --text, -t: Text to synthesize
• --endpoint, -e: TTS server endpoint in format host:port
• --output, -o: Output audio file (default: output.wav)
• --save: Save the endpoint for future use (optional)

Example:

python wyoming_tester.py tts --text "Testing Wyoming TTS" --endpoint 192.168.1.100:10200 --output result.wav --save

Using Saved Endpoints

After saving an endpoint with --save, you can omit the --endpoint parameter in future runs:

# STT with saved endpoint
python wyoming_tester.py stt --audio test.wav

# TTS with saved endpoint
python wyoming_tester.py tts --text "Hello again"

Endpoints are saved in ~/.wyoming_tester_config.json (or %USERPROFILE%\.wyoming_tester_config.json on Windows).

Preparing Audio Files for STT

The STT test requires audio files in a specific format:

• Format: WAV
• Sample Rate: 16kHz (16000 Hz)
• Channels: Mono (1 channel)
• Bit Depth: 16-bit (recommended)

Converting Audio Files

Using FFmpeg (Cross-platform)

Install FFmpeg from ffmpeg.org, then:

# Convert any audio file to the correct format
ffmpeg -i input.mp3 -ar 16000 -ac 1 -sample_fmt s16 output.wav

Using SoX (Linux)

# Install SoX
sudo apt-get install sox

# Convert audio
sox input.mp3 -r 16000 -c 1 -b 16 output.wav

Using Python (Cross-platform)

If you have pydub installed:

from pydub import AudioSegment

audio = AudioSegment.from_file("input.mp3")
audio = audio.set_frame_rate(16000).set_channels(1)
audio.export("output.wav", format="wav")

Creating a Test Audio File

You can record a test audio file:

Windows:

1. Use Voice Recorder app
2. Save the recording
3. Convert to 16kHz mono using FFmpeg

Linux:

# Record with arecord (5 seconds)
arecord -f S16_LE -r 16000 -c 1 -d 5 test.wav

macOS:

# Record with sox
rec -r 16000 -c 1 test.wav

Testing Against Wyoming Services

Common Wyoming Ports

• Faster-Whisper STT: Port 10300
• Piper TTS: Port 10200
• Custom services: Check your service configuration

Example with Docker

If you're running Wyoming services in Docker:

# Test local Docker service
python wyoming_tester.py stt --audio test.wav --endpoint localhost:10300

# Test remote service
python wyoming_tester.py tts --text "Hello" --endpoint 192.168.1.100:10200

Troubleshooting

"Connection refused" Error

• Verify the Wyoming service is running
• Check the host and port are correct
• Ensure firewall allows connections

"Audio file not found" Error

• Verify the file path is correct
• Use absolute paths if needed: C:\path\to\audio.wav or /path/to/audio.wav

"Expected 16kHz mono" Warning

• The audio file format doesn't match requirements
• Convert the audio using one of the methods above
• The test will still attempt to run but may fail

No Transcription Received

• Check the Wyoming STT service logs
• Verify the service supports the audio format
• Try a shorter audio clip for testing

No Audio Generated

• Check the Wyoming TTS service logs
• Verify the service is configured correctly
• Check if the text contains unsupported characters

Making the Script Executable

Linux/macOS

chmod +x wyoming_tester.py
./wyoming_tester.py stt --audio test.wav --endpoint localhost:10300

Windows

You can create a batch file test_stt.bat:

@echo off
python wyoming_tester.py stt --audio test.wav --endpoint localhost:10300

Or test_tts.bat:

@echo off
python wyoming_tester.py tts --text "Hello world" --endpoint localhost:10200

Configuration File

Saved endpoints are stored in JSON format:

{
  "stt_endpoint": "localhost:10300",
  "tts_endpoint": "localhost:10200"
}

Location:

• Linux/macOS: ~/.wyoming_tester_config.json
• Windows: %USERPROFILE%\.wyoming_tester_config.json

Wyoming Protocol

This tool implements the Wyoming protocol for voice services. For more information about the protocol, visit:

• Wyoming Protocol Documentation
• Home Assistant Wyoming Integration

License

This tool is provided as-is for testing Wyoming protocol endpoints.