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:

```bash
# 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:**
```bash
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:

```bash
# 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:**
```bash
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:

```bash
# 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](https://ffmpeg.org/download.html), then:

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

#### Using SoX (Linux)

```bash
# 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:

```python
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:**
```bash
# Record with arecord (5 seconds)
arecord -f S16_LE -r 16000 -c 1 -d 5 test.wav
```

**macOS:**
```bash
# 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:

```bash
# 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

```bash
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`:

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

Or `test_tts.bat`:

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

## Configuration File

Saved endpoints are stored in JSON format:

```json
{
  "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](https://github.com/rhasspy/wyoming)
- [Home Assistant Wyoming Integration](https://www.home-assistant.io/integrations/wyoming/)

## License

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