🎙️ stts - Universal Voice Shell

📋 Menu

🚀 Szybki start
⚙️ Konfiguracja
✨ Funkcje
📊 Wymagania sprzętowe
💻 Użycie
🔧 Providery
🍓 Raspberry Pi
🐛 Troubleshooting
📁 Struktura
📚 Dokumentacja
🔗 Powiązane projekty

Repo zostało podzielone na dwa niezależne projekty:

python/ - wersja Python
nodejs/ - wersja Node.js (ESM)

Każdy folder ma własne:

README.md
Makefile
Dockerfile
testy Docker (bez mikrofonu)

Szybki start

użycie STT i TTS w komendzie shell:

#tylko STT
./stts git commit -m "{STT}"
# razem z TTS 
./stts git commit -m "{STT}" | ./stts --tts-stdin
# z TTS espeak angielski
./stts git commit -m "{STT}" | ./stts --tts-stdin --tts-provider espeak --tts-voice en
# z konfiguracją TTS lepszej jakosci
./stts git commit -m "{STT}" | ./stts --tts-provider piper --tts-voice en_US-amy-medium --tts-stdin
# z konfiguracją TTS polski lepszej jakosci
./stts git commit -m "{STT}" | ./stts --tts-provider piper --tts-voice pl_PL-gosia-medium --tts-stdin

Uruchamianie komend shell nawet z błędami fonetycznymi za pomocą nlp2cmd:

./stts nlp2cmd -r "{STT}" --auto-confirm | ./stts --tts-stdin

output

[13:14:01] 🎤 Mów (max 5s, VAD)... ✅ VAD stop (3.4s / 3.7s)
🔎 audio: 3.4s, rms=-37.4dBFS
[13:14:05] 🔄 Rozpoznawanie... ✅ "lista folderów" (5.5s)
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────── 🚀 Run Mode ────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ lista folderów                                                                                                                                                                                                                             │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Generating command...
Detected: shell/list

$ ls -la .
  total 108
  drwxrwxr-x 10 tom tom  4096 Jan 24 13:13 .
  drwxrwxr-x 31 tom tom  4096 Jan 24 09:33 ..
  -rw-r--r--  1 tom tom  1512 Jan 24 12:12 .env.example
  drwxrwxr-x  7 tom tom  4096 Jan 24 13:06 .git
  -rw-r--r--  1 tom tom  1664 Jan 24 10:34 .gitignore
  drwxrwxr-x  3 tom tom  4096 Jan 24 12:29 .idea
  -rw-rw-r--  1 tom tom 11357 Jan 24 09:33 LICENSE
  -rw-r--r--  1 tom tom  4658 Jan 24 12:21 Makefile
  -rw-rw-r--  1 tom tom 12421 Jan 24 13:13 README.md
  -rw-r--r--  1 tom tom     7 Jan 24 13:05 VERSION
  -rw-r--r--  1 tom tom  2291 Jan 24 12:20 bump_version.py
  drwxrwxr-x  2 tom tom  4096 Jan 24 13:05 dist
  drwxrwxr-x  5 tom tom  4096 Jan 24 10:38 nodejs
  -rw-r--r--  1 tom tom   300 Jan 24 13:05 package.json
  -rw-r--r--  1 tom tom   514 Jan 24 13:05 pyproject.toml
  drwxr-xr-x  7 tom tom  4096 Jan 24 10:43 python
  drwxr-xr-x  2 tom tom  4096 Jan 24 10:57 scripts
  -rwxr-xr-x  1 tom tom   573 Jan 24 10:11 stts
  drwxrwxr-x  2 tom tom  4096 Jan 24 13:05 stts.egg-info
  -rwxr-xr-x  1 tom tom   462 Jan 24 10:11 stts.mjs
  drwxrwxr-x  5 tom tom  4096 Jan 24 10:56 venv
✓ Command completed in 9.1ms
[stts] TTS: provider=piper voice=en_US-amy-medium

Uwaga: ./stts wykonuje komendę z buforowaniem – output pojawi się naraz po zakończeniu. Jeśli potrzebujesz strumieniowanie (np. git), użyj --dry-run | bash lub git commit -m "$(./stts --stt-once)".

./stts git commit -m "{STT}" | ./stts --tts-stdin
[12:23:19] 🎤 Mów (max 5s, VAD)... ✅ VAD stop (4.4s / 4.6s)
🔎 audio: 4.4s, rms=-44.5dBFS
[12:23:24] 🔄 Rozpoznawanie... ✅ "Aktualizuj dokumentację." (5.7s)
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

[stts] TTS: provider=piper voice=pl_PL-gosia-medium

Konfiguracja

# Python
cd python
cp .env.example .env
./stts --setup
./stts

# Node.js
cd nodejs
cp .env.example .env
./stts.mjs --setup
./stts.mjs

Szybki setup (bez interakcji, Python):

./stts --init whisper_cpp:tiny

.env (ustawienia / linki / domyślne wartości)

W repo jest /.env.example (oraz osobne python/.env.example, nodejs/.env.example). Skrypty automatycznie wczytują .env.

Najważniejsze zmienne:

STTS_CONFIG_DIR - katalog na modele/cache (również dla Docker volume)
STTS_TIMEOUT - czas nagrywania STT (sekundy), domyślnie 5
STTS_NLP2CMD_ENABLED=1 - włącza NL → komenda przez nlp2cmd
STTS_NLP2CMD_ARGS=-r - tryb jak w przykładach: nlp2cmd -r "Pokaż użytkowników"
STTS_NLP2CMD_CONFIRM=1 - pytaj o potwierdzenie przed wykonaniem
STTS_PIPER_AUTO_INSTALL=1 - auto-instalacja piper binarki (Python)
STTS_PIPER_AUTO_DOWNLOAD=1 - auto-download modelu głosu piper (Python)
STTS_PIPER_RELEASE_TAG=2023.11.14-2 - wersja piper do pobrania
STTS_PIPER_VOICE_VERSION=v1.0.0 - wersja głosów piper do pobrania

NLP2CMD (Natural Language → komendy)

W wersji Python i Node możesz:

wpisać: nlp Pokaż użytkowników
albo użyć STT: ENTER → powiedz tekst → skrypt odpali nlp2cmd i zapyta o potwierdzenie

Instalacja nlp2cmd:

cd python && make pip-nlp2cmd

TTS: szybki setup + autodiagnostyka (Python)

Jeśli "TTS nie działa" (cisza), najczęstsze przyczyny:

brak binarki providera (espeak / piper)
dla piper: brak modelu *.onnx i *.onnx.json
brak odtwarzacza audio (paplay / aplay / play) dla piper

Test TTS (bez STT)

./stts --tts-test "Test syntezatora mowy"

Setup: espeak (Linux)

make tts-setup-espeak

Setup: piper (Linux, auto-download)

make tts-setup-piper

Piper: automatyczny install + auto-download w runtime

Wersja Python potrafi automatycznie:

pobrać binarkę piper do ~/.config/stts-python/bin/
pobrać model i config głosu do ~/.config/stts-python/models/piper/

Ręcznie (CLI):

./stts --install-piper
./stts --download-piper-voice pl_PL-gosia-medium
./stts --tts-provider piper --tts-voice pl_PL-gosia-medium
./stts --tts-test "Cześć, to działa."

Testy w Docker (bez dostępu do audio)

Testy działają przez symulację wypowiedzi usera:

Generujemy próbki audio do plików samples/*.wav
Do każdej próbki zapisujemy transkrypt w samples/*.wav.txt
W testach ustawiamy STTS_MOCK_STT=1 i uruchamiamy --stt-file ...

# wszystkie platformy
make test-docker

# albo osobno
make docker-test-python
make docker-test-nodejs

Testy Docker montują cache/config jako volume (żeby nie pobierać modeli za każdym razem). Domyślne katalogi cache:

CACHE_DIR_PYTHON=~/.config/stts-python
CACHE_DIR_NODEJS=~/.config/stts-nodejs

Możesz je nadpisać:

make test-docker CACHE_DIR_PYTHON=/tmp/stts-python-cache CACHE_DIR_NODEJS=/tmp/stts-nodejs-cache

Alternatywnie (wrapper shell):

bash scripts/test_docker_all.sh --cache-python /tmp/stts-python-cache --cache-nodejs /tmp/stts-nodejs-cache

✨ Funkcje

Auto-detekcja sprzętu - sprawdza RAM, GPU, CPU i rekomenduje odpowiedni model
Wybór STT - whisper.cpp, faster-whisper, vosk, Google Speech
Wybór TTS - espeak, piper (neural), system TTS
Auto-pobieranie - modele pobierane automatycznie
Cross-platform - Linux, macOS, Windows, Raspberry Pi
Zero konfiguracji - interaktywny setup przy pierwszym uruchomieniu

🚀 Instalacja

# 1. Pobierz
git clone https://github.com/wronai/stts
cd stts

# 2. Uruchom (wybierz wersję)
./stts           # Python 3.8+
./stts.mjs       # Node.js 18+

# 3. Opcjonalnie: zainstaluj globalnie
sudo ln -s $(pwd)/stts /usr/local/bin/stts
sudo ln -s $(pwd)/stts.mjs /usr/local/bin/stts-node

🔄 Python vs Node.js

Cecha	Python (`python/stts`)	Node.js (`nodejs/stts.mjs`)
Wymagania	Python 3.8+	Node.js 18+
Windows	✅ Pełne	⚠️ Częściowe
Linux/macOS	✅	✅
Zależności	0 (stdlib)	0 (stdlib)

Zależności systemowe

# Linux (Ubuntu/Debian)
sudo apt install espeak alsa-utils sox

# macOS
brew install espeak sox

# Windows
# Python + espeak (lub użyj system TTS)

📊 Wymagania sprzętowe

STT (Speech-to-Text)

Provider	Min RAM	GPU	Offline	Jakość	Szybkość
whisper.cpp	1 GB	❌	✅	⭐⭐⭐⭐	⭐⭐⭐
faster-whisper	2 GB	✅ (opt)	✅	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
vosk	0.5 GB	❌	✅	⭐⭐⭐	⭐⭐⭐⭐⭐
google	0.5 GB	❌	❌	⭐⭐⭐⭐	⭐⭐⭐

Modele Whisper

Model	RAM	VRAM	Rozmiar	Jakość
tiny	1 GB	-	75 MB	⭐⭐
base	1 GB	-	150 MB	⭐⭐⭐
small	2 GB	-	500 MB	⭐⭐⭐⭐
medium	4 GB	2 GB	1.5 GB	⭐⭐⭐⭐⭐
large	8 GB	4 GB	3 GB	⭐⭐⭐⭐⭐

TTS (Text-to-Speech)

Provider	Min RAM	Jakość	Offline
espeak	0.1 GB	⭐⭐	✅
piper	0.5 GB	⭐⭐⭐⭐⭐	✅
system	-	⭐⭐⭐	✅

💻 Użycie

Voice Shell (interaktywny)

./stts

🔊 stts> make build       # wpisz komendę
🔊 stts>                  # ENTER = nagrywanie głosu
🔊 stts> exit             # wyjście

Command Wrapper

# Uruchom komendę z głosowym output
./stts make build
./stts python script.py
./stts kubectl get pods
./stts git status

# Ostatnia linijka output zostanie przeczytana na głos

STT placeholder (Python)

W trybie wrapper możesz użyć {STT} jako placeholdera, który zostanie zastąpiony transkryptem z mikrofonu:

STTS_NLP2CMD_ENABLED=1 ./stts nlp2cmd -r "{STT}"

Pipeline (jednorazowe STT → stdout, Python)

Tryb --stt-once wypisuje sam transkrypt na stdout (a logi na stderr), więc nadaje się do pipe:

./stts --stt-once | xargs -I{} nlp2cmd -r "{}"

Strumieniowanie komend z git: Jeśli chcesz zobaczyć output git na bieżąco (bez bufora), użyj:

# Opcja 1: --dry-run + bash
./stts --dry-run git commit -m "{STT}" | bash

# Opcja 2: podstawienie argumentu (brak bufora)
git commit -m "$(./stts --stt-once)"

Pipeline (TTS na końcu, Python)

Jeśli chcesz, żeby dowolny pipeline kończył się TTS (np. przeczytanie ostatniej niepustej linii), użyj:

... | ./stts --tts-stdin

Uwaga: {TTS} nie jest wbudowaną komendą – jeśli chcesz mieć skrót, ustaw alias w swoim shellu (np. alias TTS='stts --tts-stdin').

Uwaga: aliasy (np. TTS) działają w Twoim shellu (bash/zsh), ale nie działają wewnątrz promptu stts>.

Przykład: zbuduj komendę i przeczytaj ją na głos (bez wykonania):

./stts --dry-run git commit -m "{STT}" | ./stts --tts-stdin

Jeśli koniecznie chcesz użyć aliasu, uruchom w normalnym shellu (nie w stts>), ewentualnie przez:

bash -lc './stts --dry-run git commit -m "{STT}" | TTS'

Makefile Integration

# Dodaj do Makefile
%_voice:
	./stts make $*

# Użycie:
# make build_voice
# make test_voice

⚙️ Konfiguracja

# Interaktywny setup
./stts --setup

# Jednolinijkowy setup (Python)
./stts --init whisper_cpp:tiny

# TTS w jednej linijce (Python)
./stts --tts-provider espeak --tts-voice pl

# Konfiguracja zapisywana w:
~/.config/stts-python/config.json

Przykładowa konfiguracja

{
  "stt_provider": "whisper_cpp",
  "stt_model": "small",
  "tts_provider": "piper",
  "tts_voice": "pl",
  "language": "pl",
  "timeout": 5,
  "auto_tts": true
}

🔧 Providery

STT: whisper.cpp (rekomendowany)

# Auto-instalacja przy setup
# Lub ręcznie:
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp && make

STT: faster-whisper (GPU)

pip install faster-whisper

STT: vosk (lekki, RPi)

pip install vosk

TTS: piper (neural, rekomendowany)

# Przykład (Python):
./stts --tts-provider piper --tts-voice pl_PL-gosia-medium

# albo podaj ścieżkę do modelu .onnx:
./stts --tts-provider piper --tts-voice ~/.config/stts-python/models/piper/pl_PL-gosia-medium.onnx

# Modele trzymane są w:
~/.config/stts-python/models/piper/

Wymagania:

piper w PATH (binarka)
model *.onnx w ~/.config/stts-python/models/piper/
odtwarzacz audio: paplay lub aplay lub play

Szybki check:

command -v piper
ls ~/.config/stts-python/models/piper/*.onnx
command -v paplay || command -v aplay || command -v play

Automatyzacja (Python):

# Auto-install piper + auto-download głosu
./stts --install-piper
./stts --download-piper-voice pl_PL-gosia-medium

# Lub przez Makefile
make tts-setup-piper

TTS: espeak (fallback)

sudo apt install espeak

🍓 Raspberry Pi

Dla RPi rekomendowane:

STT: vosk (small-pl) lub whisper.cpp (tiny)
TTS: espeak lub piper

# RPi setup
sudo apt install espeak alsa-utils
./stts --setup
# Wybierz: vosk + espeak

🐛 Troubleshooting

Brak mikrofonu

# Sprawdź
arecord -l

# Zainstaluj
sudo apt install alsa-utils

Brak dźwięku TTS

# Diagnostyka (Python)
./stts --tts-test "Test TTS"

# Jeśli brak espeak/piper/player:
make tts-setup-espeak   # lub make tts-setup-piper

Model nie pobiera się

# Ręczne pobranie whisper
wget https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin
mv ggml-small.bin ~/.config/stts/models/whisper.cpp/

📁 Struktura

stts/
├── python/
│   ├── stts
│   ├── README.md
│   ├── Makefile
│   ├── Dockerfile
│   ├── samples/
│   ├── scripts/
│   └── tests/
└── nodejs/
    ├── stts.mjs
    ├── README.md
    ├── Makefile
    ├── Dockerfile
    ├── samples/
    ├── scripts/
    └── tests/

~/.config/
├── stts-python/   # config + models dla Python
└── stts-nodejs/   # config + models dla Node.js

📚 Dokumentacja

Python: python/README.md – szczegóły TTS, piper, VAD, audio, CLI
Node.js: nodejs/README.md – szczegóły ESM, Docker, CLI
.env: .env.example (root) + python/.env.example + nodejs/.env.example
Makefile: python/Makefile – targety tts-setup-espeak, tts-setup-piper

🔗 Powiązane projekty

STT/TTS Engines

whisper.cpp - High-performance inference of OpenAI's Whisper model
faster-whisper - Faster Whisper transcription with CTranslate2
vosk - Offline speech recognition API
piper - Fast, local neural text-to-speech system
espeak - Compact open source speech synthesizer

CLI Tools

nlp2cmd - Natural Language to Command converter
whisper-cli - Command-line interface for Whisper

Audio Libraries

pyaudio - Python bindings for PortAudio
sox - Sound eXchange - universal sound processing utility

📜 Licencja

Apache 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
nodejs		nodejs
python		python
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
VERSION		VERSION
bump_version.py		bump_version.py
package.json		package.json
pyproject.toml		pyproject.toml
stts		stts
stts.mjs		stts.mjs

License

wronai/stts

Folders and files

Latest commit

History

Repository files navigation