# Methodik

Wie die Audio-Samples auf voice-test.eu entstehen — dokumentiert, reproduzierbar, transparent.

## 1. Mustertexte (3 Varianten)

Alle Samples basieren auf denselben drei Texten pro Sprache. Die Texte decken unterschiedliche Herausforderungen für TTS ab:

### v1_simple — Einfach (Neutral/Informational)

> Hallo. Das ist ein Test, um synthetische Stimmen zu vergleichen. Diese Stimme wurde maschinell erzeugt.

Kurzer Satz, klare Aussage, keine特殊 Zeichen. Testet Grundqualität.

### v2_medium — Mittel (Fließtext mit Zahlen/Fremdwörtern)

> Am 14. März 2026 um 15:30 Uhr trifft sich die Arbeitsgruppe in Brüssel. Thema: Künstliche Intelligenz und ihre Auswirkungen auf den europäischen Binnenmarkt. Die Teilnehmer kommen aus 27 verschiedenen Ländern.

Zahlen, Daten, Eigennamen, EU-Kontext. Testet Zahlensprechung und Fremdwort-Behandlung.

### v3_emotional — Emotional (Prosodie)

> Endlich! Nach all der harten Arbeit ist es uns wirklich gelungen! Ich hätte nie gedacht, dass wir das schaffen können. Das ist einfach unglaublich!

Begeisterung, Ausrufe, direkte Ansprache. Testet emotionale Bandbreite und Prosodie.

## 2. Übersetzung

Die deutschen Ausgangstexte wurden in 24 weitere Sprachen übersetzt via **Gemini 3.1 Pro Preview** (über den Dev-Brain Vault-Slot).

- **Pro Sprache ein separater API-Call**, der alle 3 Varianten zusammen übersetzt (erhöht Konsistenz des Sprachregisters).
- Prompt: natürlich, fließend, optimiert für Vorlesen, nicht Lesen. Eigennamen bleiben in lokaler Form, Zahlen in lokaler Konvention.
- 25 Sprachen × 3 Varianten = 75 Texte.
- Siehe [`scripts/translate_texts.py`](scripts/translate_texts.py).

### Abgedeckte Sprachen (25)

de, en, fr, es, it, pt, pl, nl, cs, el, hu, ro, sv, da, fi, sk, bg, hr, sl, et, lv, lt, ga, mt, no

## 3. Enterprise-Sample-Generierung

Jeder Provider wird über seine offizielle API angesprochen:

| Provider | API | Stimmen | Samples |
|---|---|---|---|
| OpenAI TTS | `/v1/audio/speech`, Modell `gpt-4o-mini-tts` | 10 (mehrsprachig) | 750 |
| Microsoft Azure | `cognitiveservices/v1`, SSML, 24kHz MP3 | 330 (locale-spezifisch) | 990 |
| Microsoft Edge TTS | `edge-tts` Python (kostenlose Read-Aloud-API) | 163 | 489 |
| ElevenLabs | `/v1/text-to-speech/{voice_id}`, Modell `eleven_multilingual_v2` | 2 (Creator-Tier-Limit) | 150 |
| **Enterprise Gesamt** | | | **2379** |

Output: MP3, 24kHz (bzw. 22kHz Edge), 48-128kbps. ID3-Tags: Artist=`Ghostforge`, Comment=`Generated by voice-test.dev — {provider} {voice}`, Copyright=`CC BY 4.0 — voice-test.dev`.

Siehe [`scripts/s2_discover.py`](scripts/s2_discover.py) und [`scripts/s2_generate.py`](scripts/s2_generate.py).

## 4. Open-Source-Modell-Samples

GPU-VM: Scaleway L4 (NVIDIA L4, 23 GB VRAM), via SSH vom Dev-Brain-Server aus angesprochen.

### Framework-Status

| Framework | Status | Bemerkung |
|---|---|---|
| Piper (rhasspy) | ✅ 60 Samples, 20 Sprachen | VITS-basiert, ONNX, CPU-only |
| Coqui XTTS-v2 | ❌ Blocker | `TTS`-Paket inkompatibel mit Python 3.12 (max. 3.11) |
| Kokoro-82M | ❌ Blocker | `kokoro-onnx` braucht Model-Files hinter gated HF-Repo |
| Suno Bark | ⏳ geplant | Noch nicht angebunden |

Siehe [`scripts/s3_vm_generate.py`](scripts/s3_vm_generate.py) (läuft auf der VM).

## 5. Bekannte Limitationen

### Provider-Abdeckung

- **Google Cloud TTS** ist nicht enthalten. Der Bauplan ging von einem Service Account in `.env` aus, dieser liegt nicht vor.
- **AWS Polly** ist nicht enthalten. Die Keys in `aws.env` wurden via STS als `InvalidClientTokenId` zurückgewiesen.
- **Knowlez** ist nicht enthalten. Der dokumentierte Endpoint liefert 404.

### Sprach-Abdeckung bei OSS

Piper hat keine Voices für: **hr, et, lt, ga, mt**. Diese Sprachen fehlen in der OSS-Sektion.

### ElevenLabs-Quota

ElevenLabs Creator-Tier limitiert auf 30.000 Zeichen pro Monat. Aktuell sind 2 Stimmen (multilingual_v2) × 25 Sprachen × 3 Varianten = 150 Samples generiert. Weitere Stimmen erfordern Tier-Upgrade oder Monatsreset.

### Klon-Bedingungen

Jedes Sample ist eine einzelne, deterministische Generierung. Voice-Cloning (Speakers variieren zwischen Samples) ist nicht enthalten — jede Stimme bekommt genau eine Audio-Datei pro Sprache×Variante.

## 6. Auto-Ticker

Die GitHub Action [`.github/workflows/model-check.yml`](.github/workflows/model-check.yml) läuft jeden Montag 03:00 UTC und:

1. Paginiert die HuggingFace-API nach `text-to-speech`-Modelle.
2. Filtert: Downloads ≥ 500, OSS-Lizenz, ≥ 1 EU-Sprache erkennbar.
3. Vergleicht mit `data/models.json`.
4. Neue Modelle werden eingetragen mit `samples_generated: false` und `new_at: YYYY-MM-DD`.
5. Top-60-Links werden via HTTP HEAD geprüft; kaputte als `deprecated` markiert.
6. Commit via `ghostforge-bot`.

Wenn genügend neue Modelle zusammenkommen, startet Jason die GPU-VM und generiert Samples.

## 7. Reproduzierbarkeit

Alle Scripts sind idempotent und append-safe. Eine Resume nach Abbruch überspringt vorhandene Samples und ergänzt nur fehlende.

Build-Kette:

```bash
# 1. Texte (einmalig)
python scripts/translate_texts.py   # → data/texts.json

# 2. Enterprise Samples (Provider-weise)
python scripts/s2_discover.py        # → data/voices.json
python scripts/s2_generate.py --provider openai
python scripts/s2_generate.py --provider azure --limit 0
python scripts/s2_generate.py --provider edge --limit 0
python scripts/s2_generate.py --provider elevenlabs --limit 2

# 3. OSS Samples (auf Scaleway-VM)
scp scripts/s3_vm_generate.py data/texts.json root@vm:/root/
ssh root@vm "python3 s3_vm_generate.py"
scp -r root@vm:/root/out/audio/oss .

# 4. Auto-Ticker (wird via GitHub Action automatisch ausgeführt)
python scripts/check_models.py
```

## 8. Lizenz

- **Code:** MIT
- **Audio-Samples:** CC BY 4.0 — Attribution an Ghostforge / voice-test.dev erforderlich
- **Modell-Metadaten:** Aus HuggingFace, jeweils unter ihrer Original-Lizenz

## 9. Stand

Stand **M51 (August 2026):**

- 2439 Samples total (2379 Enterprise + 60 OSS)
- 5 Provider (4 Enterprise + 1 OSS)
- 25 Sprachen × 3 Varianten