wiki/archiv/README_AzureVoiceSetup.md

Azure Voice Services Integration

Übersicht

Diese Implementierung bietet Azure Speech Services Integration für zwei Hauptfunktionen:

1. Realtime Dolmetscher: Sprache → Text (übersetzt)
2. Konversation: Frage → Antwort in Voice

Architektur

Backend (Gateway)

• Route: gateway/modules/routes/routeVoiceAzure.py
• Connector: gateway/modules/connectors/connectorAzureSpeech.py
• Integration: In gateway/app.py eingebunden

Frontend (Frontend Agents)

• Module: frontend_agents/public/js/modules/voiceMain.js
• HTML: frontend_agents/public/htmlparts/part_voiceMain.html
• API: Erweitert in frontend_agents/public/js/shared/apiCalls.js
• Navigation: Integriert in frontend_agents/public/js/shared/globalState.js

API Endpunkte

Voice Services

• GET /api/voice/settings - Verfügbare Sprachen und Stimmen
• POST /api/voice/speech-to-text - Sprache zu Text
• POST /api/voice/text-to-speech - Text zu Sprache
• POST /api/voice/translate - Text übersetzen
• POST /api/voice/conversation - Konversation mit Voice-Antwort
• POST /api/voice/realtime-interpreter - Realtime Dolmetscher
• GET /api/voice/health - Verbindungsstatus

Streaming Services (Neu!)

• POST /api/voice/stream/speech-to-text - Streaming Sprache zu Text
• POST /api/voice/stream/text-to-speech - Streaming Text zu Sprache
• POST /api/voice/stream/realtime-interpreter - Streaming Realtime Dolmetscher

WebSocket Real-time Services (Neu!) ⭐

• WS /api/voice/ws/realtime-interpreter - Echte Real-time Übersetzung mit Live-Mikrofon
• WS /api/voice/ws/speech-to-text - Echte Real-time Speech-to-Text mit Live-Mikrofon
• WS /api/voice/ws/text-to-speech - Real-time Text-to-Speech Streaming
• GET /api/voice/ws/status - WebSocket Verbindungsstatus

Subscription Management (Neu!)

• GET /api/voice/connections - Microsoft Verbindungen mit Speech Key Status
• POST /api/voice/subscription - Azure Speech Services Subscription Key setzen
• GET /api/voice/subscription - Aktuelle Subscription Information abrufen

Authentifizierung

Die Voice Services nutzen Azure Speech Services Subscription Keys für die Authentifizierung:

Setup Prozess:

1. Microsoft Account verbinden: User muss zuerst eine Microsoft Connection erstellen
2. Azure Speech Services Subscription erstellen:
   • Azure Portal → Cognitive Services → Speech
   • Subscription Key und Region notieren
3. Subscription Key konfigurieren:
   • POST /api/voice/subscription mit Subscription Key und Region
   • System testet automatisch die Gültigkeit des Keys
4. Verwendung: Azure Speech Services werden mit dem konfigurierten Key aufgerufen

Fallback:

• Falls kein Subscription Key konfiguriert ist, wird der Microsoft Access Token als Fallback verwendet
• Dies funktioniert nur für Entwicklung/Testing, nicht für Produktion

Frontend Features

Realtime Dolmetscher Tab

• Mikrofon-Aufnahme Button
• Original Text Anzeige
• Übersetzter Text Anzeige
• Echtzeit-Verarbeitung

Konversation Tab

• Chat-Interface
• Voice-Input Button
• Voice-Output Wiedergabe
• Konversationshistorie

Einstellungen Tab

• Spracheinstellungen (STT/TTS)
• Stimmen-Auswahl
• Übersetzungsoptionen
• Verbindungstest

Verwendung

1. Microsoft Account verbinden: User muss zuerst eine Microsoft Connection erstellen
2. Voice Module öffnen: Über Navigation → Verwaltung → Voice Services
3. Einstellungen konfigurieren: Sprache, Stimme, Übersetzung
4. Services nutzen: Dolmetscher oder Konversation

Technische Details

Audio Format

• Input: WAV, 16kHz, Mono
• Output: MP3, 16kHz, 128kbps

Unterstützte Sprachen

• Deutsch (de-DE)
• English (en-US, en-GB)
• Französisch (fr-FR)
• Spanisch (es-ES)
• Weitere über Azure verfügbar

Stimmen

• Neural Voices (hohe Qualität)
• Männlich/Weiblich verfügbar
• Sprachenspezifisch

Production Implementation

Die Azure Voice Services sind jetzt vollständig implementiert mit:

✅ Implementierte Features

1. Echte Azure Speech Services API Integration

   • Speech-to-Text (STT) mit Azure Cognitive Services
   • Text-to-Speech (TTS) mit Azure Neural Voices
   • Translation Services mit Azure Translator

2. Audio Format Handling

   • Unterstützung für WAV, MP3, OGG Formate
   • Automatische Format-Validierung
   • Audio-Konvertierung für optimale Qualität

3. Robuste Error Handling

   • Spezifische Fehlermeldungen für verschiedene HTTP-Status-Codes
   • Retry-Logik mit exponentieller Backoff
   • Timeout-Handling für langsame Verbindungen

4. Rate Limiting

   • 20 Requests pro Minute pro Service
   • Automatische Reset-Funktionalität
   • Benutzerfreundliche Fehlermeldungen

5. AI Integration

   • Intelligente Konversationsantworten
   • Mehrsprachige Unterstützung (Deutsch/Englisch)
   • Erweiterbare Response-Logik

6. Umfassendes Logging

   • Detaillierte Fehlerprotokollierung
   • Performance-Monitoring
   • Debug-Informationen für Audio-Formate

7. Audio Streaming Support ⭐ NEU!

   • Real-time Audio-Verarbeitung in Chunks
   • Server-Sent Events (SSE) für Live-Updates
   • Streaming Text-to-Speech für bessere Performance
   • Chunked Audio-Upload für große Dateien
   • Reduzierte Latenz bei Voice-Interaktionen

8. WebSocket Real-time Services ⭐ NEU!

   • Echte Live-Mikrofon-Integration
   • Bidirektionale Echtzeit-Kommunikation
   • Real-time Audio-Streaming ohne Datei-Upload
   • Live-Übersetzung während des Sprechens
   • WebSocket-basierte Verbindungsverwaltung
   • Automatische Wiederverbindung bei Verbindungsabbruch

🔧 Konfiguration

Azure Speech Services Setup:

1. Azure Speech Services Resource erstellen
2. Subscription Key in der Datenbank speichern
3. Region konfigurieren (Standard: westeurope)

Unterstützte Audio-Formate:

• STT Input: WAV (16kHz), MP3, OGG
• TTS Output: MP3 (verschiedene Qualitäten), PCM

Rate Limits:

• Speech-to-Text: 20 requests/minute
• Text-to-Speech: 20 requests/minute
• Translation: 20 requests/minute

Subscription Key Setup Beispiel

1. Subscription Key setzen:

curl -X POST "https://your-api.com/api/voice/subscription" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_key": "your-azure-speech-subscription-key",
    "region": "westeurope"
  }'

2. Subscription Status prüfen:

curl -X GET "https://your-api.com/api/voice/subscription" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

3. Verbindungen mit Speech Key Status anzeigen:

curl -X GET "https://your-api.com/api/voice/connections" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

WebSocket Real-time Usage Beispiel

1. JavaScript WebSocket Client:

// Real-time Interpreter
const client = new VoiceWebSocketClient();
await client.connectRealtimeInterpreter('user123', 'de-DE', 'en-US');

// Callbacks setzen
client.onTranslationResult = (result) => {
    console.log('Original:', result.original_text);
    console.log('Translated:', result.translated_text);
};

// Recording starten
await client.startRecording();

2. WebSocket Verbindung:

const ws = new WebSocket('ws://localhost:8000/api/voice/ws/realtime-interpreter?user_id=user123&from_language=de-DE&to_language=en-US');

ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    if (message.type === 'translation_result') {
        // Live-Übersetzung anzeigen
        displayTranslation(message.original_text, message.translated_text);
    }
};

🚀 Nächste Schritte

1. Azure OpenAI Integration für erweiterte Konversation
2. ✅ Audio Streaming für bessere Performance - IMPLEMENTIERT!
3. ✅ Subscription Key Management - IMPLEMENTIERT!
4. ✅ WebSocket Real-time Services - IMPLEMENTIERT!
5. Voice Cloning mit Custom Neural Voices
6. Advanced Audio Processing mit Noise Reduction
7. Audio Quality Enhancement mit Noise Reduction und Echo Cancellation
8. Multi-user WebSocket Rooms für Gruppen-Übersetzung