# 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:
```bash
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:
```bash
curl -X GET "https://your-api.com/api/voice/subscription" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 3. Verbindungen mit Speech Key Status anzeigen:
```bash
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:
```javascript
// 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:
```javascript
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