commit 04dacedb264352b3e70a4b470e5a13be7c53b589 Author: Daniel Gradman-Svendsen Date: Thu Jan 15 22:57:34 2026 +0100 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..8eeb72f --- /dev/null +++ b/README.md @@ -0,0 +1,234 @@ +# 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.