Upload 20 files

Dockerfile

@@ -1,36 +1,34 @@
-FROM python:3.11-slim
-
-WORKDIR /app
-
-ENV PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1 \
-    PORT=8000
-
-# Install dependencies
-RUN apt-get update && apt-get install -y gcc curl git && rm -rf /var/lib/apt/lists/*
-
-# Copy source code first
-COPY ttsfm/ ./ttsfm/
-COPY ttsfm-web/ ./ttsfm-web/
-COPY pyproject.toml ./
-COPY requirements.txt ./
-COPY .git/ ./.git/
-
-# Install the TTSFM package with web dependencies
-RUN pip install --no-cache-dir -e .[web]
-
-# Install additional web dependencies
-RUN pip install --no-cache-dir python-dotenv>=1.0.0 flask-socketio>=5.3.0 python-socketio>=5.10.0 eventlet>=0.33.3
-
-# Create non-root user
-RUN useradd --create-home ttsfm && chown -R ttsfm:ttsfm /app
-USER ttsfm
-
-EXPOSE 8000
-
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD curl -f http://localhost:8000/api/health || exit 1
-
-WORKDIR /app/ttsfm-web
-# Use run.py for proper eventlet initialization
-CMD ["python", "app.py"]
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Create necessary directories
+RUN mkdir -p static data
+
+# Copy application files
+COPY app.py .
+COPY translations/ translations/
+COPY i18n.py .
+COPY websocket_handler.py .
+COPY static/ static/
+COPY data/ data/
+
+# Create a non-root user
+RUN useradd -m -u 1000 user && chown -R user:user /app
+USER user
+
+# Expose port for Hugging Face Spaces
+EXPOSE 7860
+
+# Run the application
+CMD ["python", "app.py"]

app.py

@@ -0,0 +1,988 @@
+"""
+TTSFM Web Application
+
+A Flask web application that provides a user-friendly interface
+for the TTSFM text-to-speech package.
+"""
+
+import os
+import json
+import logging
+import tempfile
+import io
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+from functools import wraps
+from urllib.parse import urlparse, urljoin
+
+from flask import Flask, request, jsonify, send_file, Response, render_template, redirect, url_for
+from flask_cors import CORS
+from flask_socketio import SocketIO
+from dotenv import load_dotenv
+
+# Import i18n support
+from i18n import init_i18n, get_locale, set_locale, _
+
+# Import the TTSFM package
+try:
+    from ttsfm import TTSClient, Voice, AudioFormat, TTSException
+    from ttsfm.exceptions import APIException, NetworkException, ValidationException
+    from ttsfm.utils import validate_text_length, split_text_by_length
+except ImportError:
+    # Fallback for development when package is not installed
+    import sys
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+    from ttsfm import TTSClient, Voice, AudioFormat, TTSException
+    from ttsfm.exceptions import APIException, NetworkException, ValidationException
+    from ttsfm.utils import validate_text_length, split_text_by_length
+
+# Load environment variables
+load_dotenv()
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Create Flask app
+app = Flask(__name__, static_folder='static', static_url_path='/static')
+app.secret_key = os.getenv("SECRET_KEY", "ttsfm-secret-key-change-in-production")
+CORS(app)
+
+# Configuration (moved up for socketio initialization)
+HOST = os.getenv("HOST", "localhost")
+PORT = int(os.getenv("PORT", "7860"))
+DEBUG = os.getenv("DEBUG", "true").lower() == "true"
+
+# Initialize SocketIO with proper async mode
+# Using eventlet for production, threading for development
+async_mode = 'eventlet' if not DEBUG else 'threading'
+socketio = SocketIO(app, cors_allowed_origins="*", async_mode=async_mode)
+
+# Initialize i18n support
+init_i18n(app)
+
+# API Key configuration
+API_KEY = os.getenv("TTSFM_API_KEY")  # Set this environment variable for API protection
+REQUIRE_API_KEY = os.getenv("REQUIRE_API_KEY", "false").lower() == "true"
+
+# Create TTS client - now uses openai.fm directly, no configuration needed
+tts_client = TTSClient()
+
+# Initialize WebSocket handler
+from websocket_handler import WebSocketTTSHandler
+websocket_handler = WebSocketTTSHandler(socketio, tts_client)
+
+logger.info("Initialized web app with TTSFM using openai.fm free service")
+logger.info(f"WebSocket support enabled with {async_mode} async mode")
+
+# API Key validation decorator
+def require_api_key(f):
+    """Decorator to require API key for protected endpoints."""
+    @wraps(f)
+    def decorated_function(*args, **kwargs):
+        # Skip API key check if not required
+        if not REQUIRE_API_KEY:
+            return f(*args, **kwargs)
+
+        # Check if API key is configured
+        if not API_KEY:
+            logger.warning("API key protection is enabled but TTSFM_API_KEY is not set")
+            return jsonify({
+                "error": "API key protection is enabled but not configured properly"
+            }), 500
+
+        # Get API key from request headers - prioritize Authorization header (OpenAI compatible)
+        provided_key = None
+
+        # 1. Check Authorization header first (OpenAI standard)
+        auth_header = request.headers.get('Authorization')
+        if auth_header and auth_header.startswith('Bearer '):
+            provided_key = auth_header[7:]  # Remove 'Bearer ' prefix
+
+        # 2. Check X-API-Key header as fallback
+        if not provided_key:
+            provided_key = request.headers.get('X-API-Key')
+
+        # 3. Check API key from query parameters as fallback
+        if not provided_key:
+            provided_key = request.args.get('api_key')
+
+        # 4. Check API key from JSON body as fallback
+        if not provided_key and request.is_json:
+            data = request.get_json(silent=True)
+            if data:
+                provided_key = data.get('api_key')
+
+        # Validate API key
+        if not provided_key or provided_key != API_KEY:
+            logger.warning(f"Invalid API key attempt from {request.remote_addr}")
+            return jsonify({
+                "error": {
+                    "message": "Invalid API key provided",
+                    "type": "invalid_request_error",
+                    "code": "invalid_api_key"
+                }
+            }), 401
+
+        return f(*args, **kwargs)
+    return decorated_function
+
+def combine_audio_chunks(audio_chunks: List[bytes], format_type: str = "mp3") -> bytes:
+    """
+    Combine multiple audio chunks into a single audio file.
+
+    Args:
+        audio_chunks: List of audio data as bytes
+        format_type: Audio format (mp3, wav, etc.)
+
+    Returns:
+        bytes: Combined audio data
+    """
+    try:
+        # Try to use pydub for audio processing if available
+        try:
+            from pydub import AudioSegment
+
+            # Convert each chunk to AudioSegment
+            audio_segments = []
+            for chunk in audio_chunks:
+                if format_type.lower() == "mp3":
+                    segment = AudioSegment.from_mp3(io.BytesIO(chunk))
+                elif format_type.lower() == "wav":
+                    segment = AudioSegment.from_wav(io.BytesIO(chunk))
+                elif format_type.lower() == "opus":
+                    # For OPUS, we'll treat it as WAV since openai.fm returns WAV for OPUS requests
+                    segment = AudioSegment.from_wav(io.BytesIO(chunk))
+                else:
+                    # For other formats, try to auto-detect or default to WAV
+                    try:
+                        segment = AudioSegment.from_file(io.BytesIO(chunk))
+                    except:
+                        segment = AudioSegment.from_wav(io.BytesIO(chunk))
+
+                audio_segments.append(segment)
+
+            # Combine all segments
+            combined = audio_segments[0]
+            for segment in audio_segments[1:]:
+                combined += segment
+
+            # Export to bytes
+            output_buffer = io.BytesIO()
+            if format_type.lower() == "mp3":
+                combined.export(output_buffer, format="mp3")
+            elif format_type.lower() == "wav":
+                combined.export(output_buffer, format="wav")
+            else:
+                # Default to the original format or WAV
+                try:
+                    combined.export(output_buffer, format=format_type.lower())
+                except:
+                    combined.export(output_buffer, format="wav")
+
+            return output_buffer.getvalue()
+
+        except ImportError:
+            # Fallback: Simple concatenation for WAV files
+            logger.warning("pydub not available, using simple concatenation for WAV files")
+
+            if format_type.lower() == "wav":
+                return _simple_wav_concatenation(audio_chunks)
+            else:
+                # For non-WAV formats without pydub, just concatenate raw bytes
+                # This won't produce valid audio but is better than failing
+                logger.warning(f"Cannot properly combine {format_type} files without pydub, using raw concatenation")
+                return b''.join(audio_chunks)
+
+    except Exception as e:
+        logger.error(f"Error combining audio chunks: {e}")
+        # Fallback to simple concatenation
+        return b''.join(audio_chunks)
+
+def _simple_wav_concatenation(wav_chunks: List[bytes]) -> bytes:
+    """
+    Simple WAV file concatenation without external dependencies.
+    This is a basic implementation that works for simple WAV files.
+    """
+    if not wav_chunks:
+        return b''
+
+    if len(wav_chunks) == 1:
+        return wav_chunks[0]
+
+    try:
+        # For WAV files, we can do a simple concatenation by:
+        # 1. Taking the header from the first file
+        # 2. Concatenating all the audio data
+        # 3. Updating the file size in the header
+
+        first_wav = wav_chunks[0]
+        if len(first_wav) < 44:  # WAV header is at least 44 bytes
+            return b''.join(wav_chunks)
+
+        # Extract header from first file (first 44 bytes)
+        header = bytearray(first_wav[:44])
+
+        # Collect all audio data (skip headers for subsequent files)
+        audio_data = first_wav[44:]  # Audio data from first file
+
+        for wav_chunk in wav_chunks[1:]:
+            if len(wav_chunk) > 44:
+                audio_data += wav_chunk[44:]  # Skip header, append audio data
+
+        # Update file size in header (bytes 4-7)
+        total_size = len(header) + len(audio_data) - 8
+        header[4:8] = total_size.to_bytes(4, byteorder='little')
+
+        # Update data chunk size in header (bytes 40-43)
+        data_size = len(audio_data)
+        header[40:44] = data_size.to_bytes(4, byteorder='little')
+
+        return bytes(header) + audio_data
+
+    except Exception as e:
+        logger.error(f"Error in simple WAV concatenation: {e}")
+        # Ultimate fallback
+        return b''.join(wav_chunks)
+
+def _is_safe_url(target: Optional[str]) -> bool:
+    """Validate that a target URL is safe for redirection.
+
+    Allows only relative URLs or absolute URLs that match this server's host
+    and http/https schemes. Prevents open redirects to external domains.
+    """
+    if not target:
+        return False
+
+    parsed = urlparse(target)
+    if parsed.scheme or parsed.netloc or target.startswith('//'):
+        return False
+    if not parsed.path.startswith('/'):
+        return False
+    joined = urljoin(request.host_url, target)
+    host = urlparse(request.host_url)
+    j = urlparse(joined)
+    return j.scheme in ("http", "https") and j.netloc == host.netloc
+
+@app.route('/set-language/<lang_code>')
+def set_language(lang_code):
+    """Set the user's language preference."""
+    if set_locale(lang_code):
+        # Redirect back only if the referrer is safe; otherwise go home
+        target = request.referrer
+        if _is_safe_url(target):
+            return redirect(target)
+        return redirect(url_for('index'))
+    else:
+        # Invalid language code, redirect to home
+        return redirect(url_for('index'))
+
+@app.route('/')
+def index():
+    """Serve the main web interface."""
+    return render_template('index.html')
+
+@app.route('/playground')
+def playground():
+    """Serve the interactive playground."""
+    return render_template('playground.html')
+
+@app.route('/docs')
+def docs():
+    """Serve the API documentation."""
+    return render_template('docs.html')
+
+@app.route('/websocket-demo')
+def websocket_demo():
+    """Serve the WebSocket streaming demo page."""
+    return render_template('websocket_demo.html')
+
+@app.route('/api/voices', methods=['GET'])
+def get_voices():
+    """Get list of available voices."""
+    try:
+        voices = [
+            {
+                "id": voice.value,
+                "name": voice.value.title(),
+                "description": f"{voice.value.title()} voice"
+            }
+            for voice in Voice
+        ]
+        
+        return jsonify({
+            "voices": voices,
+            "count": len(voices)
+        })
+        
+    except Exception as e:
+        logger.error(f"Error getting voices: {e}")
+        return jsonify({"error": "Failed to get voices"}), 500
+
+@app.route('/api/formats', methods=['GET'])
+def get_formats():
+    """Get list of supported audio formats."""
+    try:
+        formats = [
+            {
+                "id": "mp3",
+                "name": "MP3",
+                "mime_type": "audio/mpeg",
+                "description": "MP3 audio format - good quality, small file size",
+                "quality": "Good",
+                "file_size": "Small",
+                "use_case": "Web, mobile apps, general use"
+            },
+            {
+                "id": "opus",
+                "name": "OPUS",
+                "mime_type": "audio/opus",
+                "description": "OPUS audio format - excellent quality, small file size",
+                "quality": "Excellent",
+                "file_size": "Small",
+                "use_case": "Web streaming, VoIP"
+            },
+            {
+                "id": "aac",
+                "name": "AAC",
+                "mime_type": "audio/aac",
+                "description": "AAC audio format - good quality, medium file size",
+                "quality": "Good",
+                "file_size": "Medium",
+                "use_case": "Apple devices, streaming"
+            },
+            {
+                "id": "flac",
+                "name": "FLAC",
+                "mime_type": "audio/flac",
+                "description": "FLAC audio format - lossless quality, large file size",
+                "quality": "Lossless",
+                "file_size": "Large",
+                "use_case": "High-quality archival"
+            },
+            {
+                "id": "wav",
+                "name": "WAV",
+                "mime_type": "audio/wav",
+                "description": "WAV audio format - lossless quality, large file size",
+                "quality": "Lossless",
+                "file_size": "Large",
+                "use_case": "Professional audio"
+            },
+            {
+                "id": "pcm",
+                "name": "PCM",
+                "mime_type": "audio/pcm",
+                "description": "PCM audio format - raw audio data, large file size",
+                "quality": "Raw",
+                "file_size": "Large",
+                "use_case": "Audio processing"
+            }
+        ]
+
+        return jsonify({
+            "formats": formats,
+            "count": len(formats)
+        })
+
+    except Exception as e:
+        logger.error(f"Error getting formats: {e}")
+        return jsonify({"error": "Failed to get formats"}), 500
+
+@app.route('/api/validate-text', methods=['POST'])
+def validate_text():
+    """Validate text length and provide splitting suggestions."""
+    try:
+        data = request.get_json()
+        if not data:
+            return jsonify({"error": "No JSON data provided"}), 400
+
+        text = data.get('text', '').strip()
+        max_length = data.get('max_length', 4096)
+
+        if not text:
+            return jsonify({"error": "Text is required"}), 400
+
+        text_length = len(text)
+        is_valid = text_length <= max_length
+
+        result = {
+            "text_length": text_length,
+            "max_length": max_length,
+            "is_valid": is_valid,
+            "needs_splitting": not is_valid
+        }
+
+        if not is_valid:
+            # Provide splitting suggestions
+            chunks = split_text_by_length(text, max_length, preserve_words=True)
+            result.update({
+                "suggested_chunks": len(chunks),
+                "chunk_preview": [chunk[:100] + "..." if len(chunk) > 100 else chunk for chunk in chunks[:3]]
+            })
+
+        return jsonify(result)
+
+    except Exception as e:
+        logger.error(f"Text validation error: {e}")
+        return jsonify({"error": "Text validation failed"}), 500
+
+@app.route('/api/generate', methods=['POST'])
+@require_api_key
+def generate_speech():
+    """Generate speech from text using the TTSFM package."""
+    try:
+        # Parse request data
+        data = request.get_json()
+        if not data:
+            return jsonify({"error": "No JSON data provided"}), 400
+
+        # Extract parameters
+        text = data.get('text', '').strip()
+        voice = data.get('voice', Voice.ALLOY.value)
+        response_format = data.get('format', AudioFormat.MP3.value)
+        instructions = data.get('instructions', '').strip() or None
+        max_length = data.get('max_length', 4096)
+        validate_length = data.get('validate_length', True)
+        
+        # Validate required fields
+        if not text:
+            return jsonify({"error": "Text is required"}), 400
+        
+        # Validate voice
+        try:
+            voice_enum = Voice(voice.lower())
+        except ValueError:
+            return jsonify({
+                "error": f"Invalid voice: {voice}. Must be one of: {[v.value for v in Voice]}"
+            }), 400
+        
+        # Validate format
+        try:
+            format_enum = AudioFormat(response_format.lower())
+        except ValueError:
+            return jsonify({
+                "error": f"Invalid format: {response_format}. Must be one of: {[f.value for f in AudioFormat]}"
+            }), 400
+        
+        logger.info(f"Generating speech: text='{text[:50]}...', voice={voice}, format={response_format}")
+        
+        # Generate speech using the TTSFM package with validation
+        response = tts_client.generate_speech(
+            text=text,
+            voice=voice_enum,
+            response_format=format_enum,
+            instructions=instructions,
+            max_length=max_length,
+            validate_length=validate_length
+        )
+        
+        # Return audio data
+        return Response(
+            response.audio_data,
+            mimetype=response.content_type,
+            headers={
+                'Content-Disposition': f'attachment; filename="speech.{response.format.value}"',
+                'Content-Length': str(response.size),
+                'X-Audio-Format': response.format.value,
+                'X-Audio-Size': str(response.size)
+            }
+        )
+        
+    except ValidationException as e:
+        logger.warning(f"Validation error: {e}")
+        return jsonify({"error": "Invalid input parameters"}), 400
+
+    except APIException as e:
+        logger.error(f"API error: {e}")
+        return jsonify({
+            "error": "TTS service error",
+            "status_code": getattr(e, 'status_code', 500)
+        }), getattr(e, 'status_code', 500)
+
+    except NetworkException as e:
+        logger.error(f"Network error: {e}")
+        return jsonify({
+            "error": "TTS service is currently unavailable"
+        }), 503
+
+    except TTSException as e:
+        logger.error(f"TTS error: {e}")
+        return jsonify({"error": "Text-to-speech generation failed"}), 500
+        
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
+        return jsonify({"error": "Internal server error"}), 500
+
+
+
+@app.route('/api/generate-combined', methods=['POST'])
+@require_api_key
+def generate_speech_combined():
+    """Generate speech from long text and return a single combined audio file."""
+    try:
+        data = request.get_json()
+        if not data:
+            return jsonify({"error": "No JSON data provided"}), 400
+
+        text = data.get('text', '').strip()
+        voice = data.get('voice', Voice.ALLOY.value)
+        response_format = data.get('format', AudioFormat.MP3.value)
+        instructions = data.get('instructions', '').strip() or None
+        max_length = data.get('max_length', 4096)
+        preserve_words = data.get('preserve_words', True)
+
+        if not text:
+            return jsonify({"error": "Text is required"}), 400
+
+        # Check if text needs splitting
+        if len(text) <= max_length:
+            # Text is short enough, use regular generation
+            try:
+                voice_enum = Voice(voice.lower())
+                format_enum = AudioFormat(response_format.lower())
+            except ValueError as e:
+                logger.warning(f"Invalid voice or format: {e}")
+                return jsonify({"error": "Invalid voice or format specified"}), 400
+
+            response = tts_client.generate_speech(
+                text=text,
+                voice=voice_enum,
+                response_format=format_enum,
+                instructions=instructions,
+                max_length=max_length,
+                validate_length=True
+            )
+
+            return Response(
+                response.audio_data,
+                mimetype=response.content_type,
+                headers={
+                    'Content-Disposition': f'attachment; filename="combined_speech.{response.format.value}"',
+                    'Content-Length': str(response.size),
+                    'X-Audio-Format': response.format.value,
+                    'X-Audio-Size': str(response.size),
+                    'X-Chunks-Combined': '1'
+                }
+            )
+
+        # Text is long, split and combine
+        try:
+            voice_enum = Voice(voice.lower())
+            format_enum = AudioFormat(response_format.lower())
+        except ValueError as e:
+            logger.warning(f"Invalid voice or format: {e}")
+            return jsonify({"error": "Invalid voice or format specified"}), 400
+
+        logger.info(f"Generating combined speech for long text: {len(text)} characters, splitting into chunks")
+
+        # Generate speech chunks
+        try:
+            responses = tts_client.generate_speech_long_text(
+                text=text,
+                voice=voice_enum,
+                response_format=format_enum,
+                instructions=instructions,
+                max_length=max_length,
+                preserve_words=preserve_words
+            )
+        except Exception as e:
+            logger.error(f"Long text generation failed: {e}")
+            return jsonify({"error": "Long text generation failed"}), 500
+
+        if not responses:
+            return jsonify({"error": "No valid text chunks found"}), 400
+
+        logger.info(f"Generated {len(responses)} chunks, combining into single audio file")
+
+        # Extract audio data from responses
+        audio_chunks = [response.audio_data for response in responses]
+
+        # Combine audio chunks
+        try:
+            combined_audio = combine_audio_chunks(audio_chunks, format_enum.value)
+        except Exception as e:
+            logger.error(f"Failed to combine audio chunks: {e}")
+            return jsonify({"error": "Failed to combine audio chunks"}), 500
+
+        if not combined_audio:
+            return jsonify({"error": "Failed to generate combined audio"}), 500
+
+        # Determine content type
+        content_type = responses[0].content_type  # Use content type from first chunk
+
+        logger.info(f"Successfully combined {len(responses)} chunks into single audio file ({len(combined_audio)} bytes)")
+
+        return Response(
+            combined_audio,
+            mimetype=content_type,
+            headers={
+                'Content-Disposition': f'attachment; filename="combined_speech.{format_enum.value}"',
+                'Content-Length': str(len(combined_audio)),
+                'X-Audio-Format': format_enum.value,
+                'X-Audio-Size': str(len(combined_audio)),
+                'X-Chunks-Combined': str(len(responses)),
+                'X-Original-Text-Length': str(len(text))
+            }
+        )
+
+    except ValidationException as e:
+        logger.warning(f"Validation error: {e}")
+        return jsonify({"error": "Invalid input parameters"}), 400
+
+    except APIException as e:
+        logger.error(f"API error: {e}")
+        return jsonify({
+            "error": "TTS service error",
+            "status_code": getattr(e, 'status_code', 500)
+        }), getattr(e, 'status_code', 500)
+
+    except NetworkException as e:
+        logger.error(f"Network error: {e}")
+        return jsonify({
+            "error": "TTS service is currently unavailable"
+        }), 503
+
+    except TTSException as e:
+        logger.error(f"TTS error: {e}")
+        return jsonify({"error": "Text-to-speech generation failed"}), 500
+
+    except Exception as e:
+        logger.error(f"Combined generation error: {e}")
+        return jsonify({"error": "Combined audio generation failed"}), 500
+
+@app.route('/api/status', methods=['GET'])
+def get_status():
+    """Get service status."""
+    try:
+        # Try to make a simple request to check if the TTS service is available
+        test_response = tts_client.generate_speech(
+            text="test",
+            voice=Voice.ALLOY,
+            response_format=AudioFormat.MP3
+        )
+        
+        return jsonify({
+            "status": "online",
+            "tts_service": "openai.fm (free)",
+            "package_version": "3.2.3",
+            "timestamp": datetime.now().isoformat()
+        })
+        
+    except Exception as e:
+        logger.error(f"Status check failed: {e}")
+        return jsonify({
+            "status": "error",
+            "tts_service": "openai.fm (free)",
+            "error": "Service status check failed",
+            "timestamp": datetime.now().isoformat()
+        }), 503
+
+@app.route('/api/health', methods=['GET'])
+def health_check():
+    """Simple health check endpoint."""
+    return jsonify({
+        "status": "healthy",
+        "package_version": "3.2.3",
+        "timestamp": datetime.now().isoformat()
+    })
+
+@app.route('/api/websocket/status', methods=['GET'])
+def websocket_status():
+    """Get WebSocket server status and active connections."""
+    return jsonify({
+        "websocket_enabled": True,
+        "async_mode": async_mode,
+        "active_sessions": websocket_handler.get_active_sessions_count(),
+        "transport_options": ["websocket", "polling"],
+        "endpoint": f"ws{'s' if request.is_secure else ''}://{request.host}/socket.io/",
+        "timestamp": datetime.now().isoformat()
+    })
+
+@app.route('/api/auth-status', methods=['GET'])
+def auth_status():
+    """Get authentication status and requirements."""
+    return jsonify({
+        "api_key_required": REQUIRE_API_KEY,
+        "api_key_configured": bool(API_KEY) if REQUIRE_API_KEY else None,
+        "timestamp": datetime.now().isoformat()
+    })
+
+@app.route('/api/translations/<lang_code>', methods=['GET'])
+def get_translations(lang_code):
+    """Get translations for a specific language."""
+    try:
+        if hasattr(app, 'language_manager'):
+            translations = app.language_manager.translations.get(lang_code, {})
+            return jsonify(translations)
+        else:
+            return jsonify({}), 404
+    except Exception as e:
+        logger.error(f"Error getting translations for {lang_code}: {e}")
+        return jsonify({"error": "Failed to get translations"}), 500
+
+# OpenAI-compatible API endpoints
+@app.route('/v1/audio/speech', methods=['POST'])
+@require_api_key
+def openai_speech():
+    """OpenAI-compatible speech generation endpoint with auto-combine feature."""
+    try:
+        # Parse request data
+        data = request.get_json()
+        if not data:
+            return jsonify({
+                "error": {
+                    "message": "No JSON data provided",
+                    "type": "invalid_request_error",
+                    "code": "missing_data"
+                }
+            }), 400
+
+        # Extract OpenAI-compatible parameters
+        model = data.get('model', 'gpt-4o-mini-tts')  # Accept but ignore model
+        input_text = data.get('input', '').strip()
+        voice = data.get('voice', 'alloy')
+        response_format = data.get('response_format', 'mp3')
+        instructions = data.get('instructions', '').strip() or None
+        speed = data.get('speed', 1.0)  # Accept but ignore speed
+
+        # TTSFM-specific parameters
+        auto_combine = data.get('auto_combine', True)  # New parameter: auto-combine long text (default: True)
+        max_length = data.get('max_length', 4096)  # Custom parameter for chunk size
+
+        # Validate required fields
+        if not input_text:
+            return jsonify({
+                "error": {
+                    "message": "Input text is required",
+                    "type": "invalid_request_error",
+                    "code": "missing_input"
+                }
+            }), 400
+
+        # Validate voice
+        try:
+            voice_enum = Voice(voice.lower())
+        except ValueError:
+            return jsonify({
+                "error": {
+                    "message": f"Invalid voice: {voice}. Must be one of: {[v.value for v in Voice]}",
+                    "type": "invalid_request_error",
+                    "code": "invalid_voice"
+                }
+            }), 400
+
+        # Validate format
+        try:
+            format_enum = AudioFormat(response_format.lower())
+        except ValueError:
+            return jsonify({
+                "error": {
+                    "message": f"Invalid response_format: {response_format}. Must be one of: {[f.value for f in AudioFormat]}",
+                    "type": "invalid_request_error",
+                    "code": "invalid_format"
+                }
+            }), 400
+
+        logger.info(f"OpenAI API: Generating speech: text='{input_text[:50]}...', voice={voice}, format={response_format}, auto_combine={auto_combine}")
+
+        # Check if text exceeds limit and auto_combine is enabled
+        if len(input_text) > max_length and auto_combine:
+            # Long text with auto-combine enabled: split and combine
+            logger.info(f"Long text detected ({len(input_text)} chars), auto-combining enabled")
+
+            # Generate speech chunks
+            responses = tts_client.generate_speech_long_text(
+                text=input_text,
+                voice=voice_enum,
+                response_format=format_enum,
+                instructions=instructions,
+                max_length=max_length,
+                preserve_words=True
+            )
+
+            if not responses:
+                return jsonify({
+                    "error": {
+                        "message": "No valid text chunks found",
+                        "type": "processing_error",
+                        "code": "no_chunks"
+                    }
+                }), 400
+
+            # Extract audio data and combine
+            audio_chunks = [response.audio_data for response in responses]
+            combined_audio = combine_audio_chunks(audio_chunks, format_enum.value)
+
+            if not combined_audio:
+                return jsonify({
+                    "error": {
+                        "message": "Failed to combine audio chunks",
+                        "type": "processing_error",
+                        "code": "combine_failed"
+                    }
+                }), 500
+
+            content_type = responses[0].content_type
+
+            logger.info(f"Successfully combined {len(responses)} chunks into single audio file")
+
+            return Response(
+                combined_audio,
+                mimetype=content_type,
+                headers={
+                    'Content-Type': content_type,
+                    'Content-Length': str(len(combined_audio)),
+                    'X-Audio-Format': format_enum.value,
+                    'X-Audio-Size': str(len(combined_audio)),
+                    'X-Chunks-Combined': str(len(responses)),
+                    'X-Original-Text-Length': str(len(input_text)),
+                    'X-Auto-Combine': 'true',
+                    'X-Powered-By': 'TTSFM-OpenAI-Compatible'
+                }
+            )
+
+        else:
+            # Short text or auto_combine disabled: use regular generation
+            if len(input_text) > max_length and not auto_combine:
+                # Text is too long but auto_combine is disabled - return error
+                return jsonify({
+                    "error": {
+                        "message": f"Input text is too long ({len(input_text)} characters). Maximum allowed length is {max_length} characters. Enable auto_combine parameter to automatically split and combine long text.",
+                        "type": "invalid_request_error",
+                        "code": "text_too_long"
+                    }
+                }), 400
+
+            # Generate speech using the TTSFM package
+            response = tts_client.generate_speech(
+                text=input_text,
+                voice=voice_enum,
+                response_format=format_enum,
+                instructions=instructions,
+                max_length=max_length,
+                validate_length=True
+            )
+
+            # Return audio data in OpenAI format
+            return Response(
+                response.audio_data,
+                mimetype=response.content_type,
+                headers={
+                    'Content-Type': response.content_type,
+                    'Content-Length': str(response.size),
+                    'X-Audio-Format': response.format.value,
+                    'X-Audio-Size': str(response.size),
+                    'X-Chunks-Combined': '1',
+                    'X-Auto-Combine': str(auto_combine).lower(),
+                    'X-Powered-By': 'TTSFM-OpenAI-Compatible'
+                }
+            )
+
+    except ValidationException as e:
+        logger.warning(f"OpenAI API validation error: {e}")
+        return jsonify({
+            "error": {
+                "message": "Invalid request parameters",
+                "type": "invalid_request_error",
+                "code": "validation_error"
+            }
+        }), 400
+
+    except APIException as e:
+        logger.error(f"OpenAI API error: {e}")
+        return jsonify({
+            "error": {
+                "message": "Text-to-speech generation failed",
+                "type": "api_error",
+                "code": "tts_error"
+            }
+        }), getattr(e, 'status_code', 500)
+
+    except NetworkException as e:
+        logger.error(f"OpenAI API network error: {e}")
+        return jsonify({
+            "error": {
+                "message": "TTS service is currently unavailable",
+                "type": "service_unavailable_error",
+                "code": "service_unavailable"
+            }
+        }), 503
+
+    except Exception as e:
+        logger.error(f"OpenAI API unexpected error: {e}")
+        return jsonify({
+            "error": {
+                "message": "An unexpected error occurred",
+                "type": "internal_error",
+                "code": "internal_error"
+            }
+        }), 500
+
+
+
+@app.route('/v1/models', methods=['GET'])
+def openai_models():
+    """OpenAI-compatible models endpoint."""
+    return jsonify({
+        "object": "list",
+        "data": [
+            {
+                "id": "gpt-4o-mini-tts",
+                "object": "model",
+                "created": 1699564800,
+                "owned_by": "ttsfm",
+                "permission": [],
+                "root": "gpt-4o-mini-tts",
+                "parent": None
+            }
+        ]
+    })
+
+@app.errorhandler(404)
+def not_found(error):
+    """Handle 404 errors."""
+    return jsonify({"error": "Endpoint not found"}), 404
+
+@app.errorhandler(405)
+def method_not_allowed(error):
+    """Handle 405 errors."""
+    return jsonify({"error": "Method not allowed"}), 405
+
+@app.errorhandler(500)
+def internal_error(error):
+    """Handle 500 errors."""
+    logger.error(f"Internal server error: {error}")
+    return jsonify({"error": "Internal server error"}), 500
+
+if __name__ == '__main__':
+    logger.info(f"Starting TTSFM web application on {HOST}:{PORT}")
+    logger.info("Using openai.fm free TTS service")
+    logger.info(f"Debug mode: {DEBUG}")
+
+    # Log API key protection status
+    if REQUIRE_API_KEY:
+        if API_KEY:
+            logger.info("🔒 API key protection is ENABLED")
+            logger.info("All TTS generation requests require a valid API key")
+        else:
+            logger.warning("⚠️  API key protection is enabled but TTSFM_API_KEY is not set!")
+            logger.warning("Please set the TTSFM_API_KEY environment variable")
+    else:
+        logger.info("🔓 API key protection is DISABLED - all requests are allowed")
+        logger.info("Set REQUIRE_API_KEY=true to enable API key protection")
+
+    try:
+        logger.info(f"Starting with {async_mode} async mode")
+        socketio.run(app, host=HOST, port=PORT, debug=DEBUG)
+    except KeyboardInterrupt:
+        logger.info("Application stopped by user")
+    except Exception as e:
+        logger.error(f"Failed to start application: {e}")
+    finally:
+        # Clean up TTS client
+        tts_client.close()

i18n.py

@@ -0,0 +1,238 @@
+"""
+Internationalization (i18n) support for TTSFM Web Application
+
+This module provides multi-language support for the Flask web application,
+including language detection, translation management, and template functions.
+"""
+
+import json
+import os
+from typing import Dict, Any, Optional
+from flask import request, session, current_app
+
+
+class LanguageManager:
+    """Manages language detection, translation loading, and text translation."""
+    
+    def __init__(self, app=None, translations_dir: str = "translations"):
+        """
+        Initialize the LanguageManager.
+        
+        Args:
+            app: Flask application instance
+            translations_dir: Directory containing translation files
+        """
+        self.translations_dir = translations_dir
+        self.translations: Dict[str, Dict[str, Any]] = {}
+        self.supported_languages = ['en', 'zh']
+        self.default_language = 'en'
+        
+        if app is not None:
+            self.init_app(app)
+    
+    def init_app(self, app):
+        """Initialize the Flask application with i18n support."""
+        app.config.setdefault('LANGUAGES', self.supported_languages)
+        app.config.setdefault('DEFAULT_LANGUAGE', self.default_language)
+        
+        # Load translations
+        self.load_translations()
+        
+        # Register template functions
+        app.jinja_env.globals['_'] = self.translate
+        app.jinja_env.globals['get_locale'] = self.get_locale
+        app.jinja_env.globals['get_supported_languages'] = self.get_supported_languages
+        
+        # Store reference to this instance
+        app.language_manager = self
+    
+    def load_translations(self):
+        """Load all translation files from the translations directory."""
+        translations_path = os.path.join(
+            os.path.dirname(__file__), 
+            self.translations_dir
+        )
+        
+        if not os.path.exists(translations_path):
+            print(f"Warning: Translations directory not found: {translations_path}")
+            return
+        
+        for lang_code in self.supported_languages:
+            file_path = os.path.join(translations_path, f"{lang_code}.json")
+            
+            if os.path.exists(file_path):
+                try:
+                    with open(file_path, 'r', encoding='utf-8') as f:
+                        self.translations[lang_code] = json.load(f)
+                    print(f"Info: Loaded translations for language: {lang_code}")
+                except Exception as e:
+                    print(f"Error: Failed to load translations for {lang_code}: {e}")
+            else:
+                print(f"Warning: Translation file not found: {file_path}")
+    
+    def get_locale(self) -> str:
+        """
+        Get the current locale based on user preference, session, or browser settings.
+        
+        Returns:
+            Language code (e.g., 'en', 'zh')
+        """
+        # 1. Check URL parameter (for language switching)
+        if 'lang' in request.args:
+            lang = request.args.get('lang')
+            if lang in self.supported_languages:
+                session['language'] = lang
+                return lang
+        
+        # 2. Check session (user's previous choice)
+        if 'language' in session:
+            lang = session['language']
+            if lang in self.supported_languages:
+                return lang
+        
+        # 3. Check browser's Accept-Language header
+        if request.headers.get('Accept-Language'):
+            browser_langs = request.headers.get('Accept-Language').split(',')
+            for browser_lang in browser_langs:
+                # Extract language code (e.g., 'zh-CN' -> 'zh')
+                lang_code = browser_lang.split(';')[0].split('-')[0].strip().lower()
+                if lang_code in self.supported_languages:
+                    session['language'] = lang_code
+                    return lang_code
+        
+        # 4. Fall back to default language
+        return self.default_language
+    
+    def set_locale(self, lang_code: str) -> bool:
+        """
+        Set the current locale.
+        
+        Args:
+            lang_code: Language code to set
+            
+        Returns:
+            True if successful, False if language not supported
+        """
+        if lang_code in self.supported_languages:
+            session['language'] = lang_code
+            return True
+        return False
+    
+    def translate(self, key: str, **kwargs) -> str:
+        """
+        Translate a text key to the current locale.
+        
+        Args:
+            key: Translation key in dot notation (e.g., 'nav.home')
+            **kwargs: Variables for string formatting
+            
+        Returns:
+            Translated text or the key if translation not found
+        """
+        locale = self.get_locale()
+        
+        # Get translation for current locale
+        translation = self._get_nested_value(
+            self.translations.get(locale, {}), 
+            key
+        )
+        
+        # Fall back to default language if not found
+        if translation is None and locale != self.default_language:
+            translation = self._get_nested_value(
+                self.translations.get(self.default_language, {}), 
+                key
+            )
+        
+        # Fall back to key if still not found
+        if translation is None:
+            translation = key
+        
+        # Format with variables if provided
+        if kwargs and isinstance(translation, str):
+            try:
+                translation = translation.format(**kwargs)
+            except (KeyError, ValueError):
+                pass  # Ignore formatting errors
+        
+        return translation
+    
+    def _get_nested_value(self, data: Dict[str, Any], key: str) -> Optional[str]:
+        """
+        Get a nested value from a dictionary using dot notation.
+        
+        Args:
+            data: Dictionary to search in
+            key: Dot-separated key (e.g., 'nav.home')
+            
+        Returns:
+            Value if found, None otherwise
+        """
+        keys = key.split('.')
+        current = data
+        
+        for k in keys:
+            if isinstance(current, dict) and k in current:
+                current = current[k]
+            else:
+                return None
+        
+        return current if isinstance(current, str) else None
+    
+    def get_supported_languages(self) -> Dict[str, str]:
+        """
+        Get a dictionary of supported languages with their display names.
+        
+        Returns:
+            Dictionary mapping language codes to display names
+        """
+        return {
+            'en': 'English',
+            'zh': '中文'
+        }
+    
+    def get_language_info(self, lang_code: str) -> Dict[str, str]:
+        """
+        Get information about a specific language.
+        
+        Args:
+            lang_code: Language code
+            
+        Returns:
+            Dictionary with language information
+        """
+        language_names = {
+            'en': {'name': 'English', 'native': 'English'},
+            'zh': {'name': 'Chinese', 'native': '中文'}
+        }
+        
+        return language_names.get(lang_code, {
+            'name': lang_code.upper(),
+            'native': lang_code.upper()
+        })
+
+
+# Global instance
+language_manager = LanguageManager()
+
+
+def init_i18n(app):
+    """Initialize i18n support for the Flask application."""
+    language_manager.init_app(app)
+    return language_manager
+
+
+# Template helper functions
+def _(key: str, **kwargs) -> str:
+    """Shorthand translation function for use in templates and code."""
+    return language_manager.translate(key, **kwargs)
+
+
+def get_locale() -> str:
+    """Get the current locale."""
+    return language_manager.get_locale()
+
+
+def set_locale(lang_code: str) -> bool:
+    """Set the current locale."""
+    return language_manager.set_locale(lang_code)

requirements.txt

@@ -1,4 +1,20 @@
+# Web application dependencies
+flask>=2.0.0
+flask-cors>=3.0.10
+flask-socketio>=5.3.0
+python-socketio>=5.10.0
+eventlet>=0.33.3
 # Core dependencies for the TTSFM package
 requests>=2.25.0
 aiohttp>=3.8.0
-fake-useragent>=1.4.0
+fake-useragent>=1.4.0
+waitress>=3.0.0
+python-dotenv>=1.0.0
+
+# Audio processing (optional, for combining audio files)
+# If not installed, will fall back to simple concatenation for WAV files
+pydub>=0.25.0
+
+# TTSFM package (install from local directory or PyPI)
+# For local development: pip install -e ../
+# For Docker/production: installed via pyproject.toml[web] dependencies

run.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python
+"""
+Run script for TTSFM web application with proper eventlet initialization
+"""
+
+# MUST be the first imports for eventlet to work properly
+import eventlet
+eventlet.monkey_patch()
+
+# Now import the app
+from app import app, socketio, HOST, PORT, DEBUG
+
+if __name__ == '__main__':
+    print(f"Starting TTSFM with WebSocket support on {HOST}:{PORT}")
+    socketio.run(app, host=HOST, port=PORT, debug=DEBUG, allow_unsafe_werkzeug=True)

static/css/style.css

@@ -0,0 +1,1399 @@
+/* TTSFM Web Application Custom Styles */
+
+:root {
+    /* Clean Color Palette */
+    --primary-color: #4f46e5;
+    --primary-dark: #3730a3;
+    --primary-light: #6366f1;
+    --secondary-color: #6b7280;
+    --secondary-dark: #4b5563;
+    --accent-color: #059669;
+    --accent-dark: #047857;
+
+    /* Status Colors */
+    --success-color: #059669;
+    --warning-color: #d97706;
+    --danger-color: #dc2626;
+    --info-color: #2563eb;
+
+    /* Clean Neutral Colors */
+    --light-color: #ffffff;
+    --light-gray: #f9fafb;
+    --medium-gray: #6b7280;
+    --dark-color: #111827;
+    --text-color: #374151;
+    --text-muted: #6b7280;
+
+    /* Design System */
+    --border-radius: 0.75rem;
+    --border-radius-sm: 0.5rem;
+    --border-radius-lg: 1rem;
+    --box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+    --box-shadow-lg: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
+    --box-shadow-xl: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+    --transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    --transition-fast: all 0.15s cubic-bezier(0.4, 0, 0.2, 1);
+
+    /* Gradients */
+    --gradient-primary: linear-gradient(135deg, var(--primary-color) 0%, var(--primary-light) 100%);
+    --gradient-secondary: linear-gradient(135deg, var(--secondary-color) 0%, var(--secondary-dark) 100%);
+    --gradient-accent: linear-gradient(135deg, var(--accent-color) 0%, var(--accent-dark) 100%);
+    --gradient-hero: linear-gradient(135deg, var(--primary-color) 0%, var(--secondary-color) 50%, var(--accent-color) 100%);
+}
+
+/* Global Styles */
+body {
+    font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    line-height: 1.6;
+    color: var(--text-color);
+    background-color: #ffffff;
+    font-weight: 400;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+}
+
+/* Enhanced Typography */
+h1, h2, h3, h4, h5, h6 {
+    font-weight: 700;
+    line-height: 1.3;
+    color: var(--dark-color);
+    letter-spacing: -0.025em;
+}
+
+.display-1, .display-2, .display-3, .display-4 {
+    font-weight: 800;
+    letter-spacing: -0.05em;
+}
+
+.lead {
+    font-size: 1.125rem;
+    font-weight: 400;
+    color: var(--text-muted);
+    line-height: 1.8;
+}
+
+/* Simplified Button Styles */
+.btn {
+    font-weight: 600;
+    border-radius: 12px;
+    transition: all 0.3s ease;
+    letter-spacing: 0.025em;
+    border: none;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+
+.btn-primary {
+    background: linear-gradient(135deg, var(--primary-color) 0%, var(--primary-light) 100%);
+    color: white;
+}
+
+.btn-primary:hover {
+    background: linear-gradient(135deg, var(--primary-dark) 0%, var(--primary-color) 100%);
+    color: white;
+    transform: translateY(-1px);
+    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15);
+}
+
+.btn-outline-primary {
+    border: 2px solid var(--primary-color);
+    color: var(--primary-color);
+    background: transparent;
+    box-shadow: none;
+}
+
+.btn-outline-primary:hover {
+    background: var(--primary-color);
+    border-color: var(--primary-color);
+    color: white;
+    transform: translateY(-1px);
+    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15);
+}
+
+.btn-lg {
+    padding: 0.875rem 2rem;
+    font-size: 1.125rem;
+    border-radius: var(--border-radius);
+}
+
+.btn-sm {
+    padding: 0.5rem 1rem;
+    font-size: 0.875rem;
+    border-radius: var(--border-radius-sm);
+}
+
+/* Clean Card Styles */
+.card {
+    border: 1px solid #e5e7eb;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+    transition: all 0.3s ease;
+    border-radius: 16px;
+    background: white;
+}
+
+.card:hover {
+    box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
+    border-color: var(--primary-light);
+    transform: translateY(-2px);
+}
+
+.card-body {
+    padding: 2rem;
+}
+
+/* Clean Hero Section */
+.hero-section {
+    background: linear-gradient(135deg, #f9fafb 0%, #ffffff 100%);
+    color: var(--text-color);
+    padding: 5rem 0;
+    min-height: 75vh;
+    display: flex;
+    align-items: center;
+    border-bottom: 1px solid #e5e7eb;
+}
+
+.min-vh-75 {
+    min-height: 75vh;
+}
+
+/* Status Indicators */
+.status-indicator {
+    display: inline-block;
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background-color: #6c757d;
+}
+
+.status-online {
+    background-color: #28a745;
+}
+
+.status-offline {
+    background-color: #dc3545;
+}
+
+/* Footer */
+.footer {
+    margin-top: auto;
+}
+
+/* Clean Code Blocks */
+pre {
+    background-color: #f8fafc !important;
+    border: 1px solid #e5e7eb;
+    border-radius: 8px;
+    font-size: 0.875rem;
+}
+
+code {
+    color: #374151;
+    font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
+}
+
+/* Enhanced Form Styles */
+.form-control, .form-select {
+    border-radius: 12px;
+    border: 2px solid #e5e7eb;
+    transition: var(--transition);
+    padding: 1rem 1.25rem;
+    font-size: 1rem;
+    background-color: #ffffff;
+    color: var(--text-color);
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.form-control:focus, .form-select:focus {
+    border-color: var(--primary-color);
+    box-shadow: 0 0 0 4px rgba(79, 70, 229, 0.1);
+    outline: none;
+    background-color: #ffffff;
+    transform: translateY(-1px);
+}
+
+.form-control:hover, .form-select:hover {
+    border-color: var(--primary-light);
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+
+.form-label {
+    font-weight: 600;
+    color: var(--dark-color);
+    margin-bottom: 0.75rem;
+    font-size: 0.95rem;
+}
+
+.form-text {
+    color: var(--text-muted);
+    font-size: 0.875rem;
+    margin-top: 0.5rem;
+}
+
+.form-check-input {
+    border-radius: var(--border-radius-sm);
+    border: 2px solid #e2e8f0;
+    width: 1.25rem;
+    height: 1.25rem;
+}
+
+.form-check-input:checked {
+    background-color: var(--primary-color);
+    border-color: var(--primary-color);
+}
+
+.form-check-input:focus {
+    box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.1);
+}
+
+.form-check-label {
+    color: var(--text-color);
+    font-weight: 500;
+    margin-left: 0.5rem;
+}
+
+/* Enhanced Status Indicators */
+.status-indicator {
+    display: inline-block;
+    width: 12px;
+    height: 12px;
+    border-radius: 50%;
+    margin-right: 8px;
+    position: relative;
+    animation: statusPulse 2s infinite;
+}
+
+.status-indicator::before {
+    content: '';
+    position: absolute;
+    top: -2px;
+    left: -2px;
+    right: -2px;
+    bottom: -2px;
+    border-radius: 50%;
+    opacity: 0.3;
+    animation: statusRing 2s infinite;
+}
+
+.status-online {
+    background-color: var(--success-color);
+    box-shadow: 0 0 8px rgba(16, 185, 129, 0.4);
+}
+
+.status-online::before {
+    background-color: var(--success-color);
+}
+
+.status-offline {
+    background-color: var(--danger-color);
+    box-shadow: 0 0 8px rgba(239, 68, 68, 0.4);
+}
+
+.status-offline::before {
+    background-color: var(--danger-color);
+}
+
+@keyframes statusPulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.7; }
+}
+
+@keyframes statusRing {
+    0% { transform: scale(0.8); opacity: 0.8; }
+    100% { transform: scale(1.4); opacity: 0; }
+}
+
+/* Enhanced Audio Player */
+.audio-player {
+    width: 100%;
+    margin-top: 1rem;
+    border-radius: var(--border-radius);
+    box-shadow: var(--box-shadow);
+    background: var(--light-color);
+    padding: 0.5rem;
+}
+
+.audio-player::-webkit-media-controls-panel {
+    background-color: var(--light-color);
+    border-radius: var(--border-radius-sm);
+}
+
+/* Enhanced Sections */
+.features-section {
+    padding: 6rem 0;
+    background: linear-gradient(180deg, #ffffff 0%, var(--light-color) 100%);
+}
+
+.stats-section {
+    padding: 4rem 0;
+    background: var(--gradient-primary);
+    color: white;
+    position: relative;
+    overflow: hidden;
+}
+
+.stats-section::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><defs><pattern id="stats-pattern" width="40" height="40" patternUnits="userSpaceOnUse"><circle cx="20" cy="20" r="1" fill="white" opacity="0.1"/></pattern></defs><rect width="100" height="100" fill="url(%23stats-pattern)"/></svg>');
+}
+
+.stat-card {
+    text-align: center;
+    padding: 2rem 1rem;
+    background: rgba(255, 255, 255, 0.1);
+    border-radius: var(--border-radius);
+    backdrop-filter: blur(10px);
+    border: 1px solid rgba(255, 255, 255, 0.2);
+    transition: var(--transition);
+}
+
+.stat-card:hover {
+    transform: translateY(-5px);
+    background: rgba(255, 255, 255, 0.15);
+}
+
+.stat-icon {
+    font-size: 2.5rem;
+    margin-bottom: 1rem;
+    color: rgba(255, 255, 255, 0.9);
+}
+
+.stat-number {
+    font-size: 3rem;
+    font-weight: 800;
+    color: white;
+    margin-bottom: 0.5rem;
+    display: block;
+}
+
+.stat-label {
+    color: rgba(255, 255, 255, 0.9);
+    font-weight: 500;
+    font-size: 0.95rem;
+}
+
+.quick-start-section {
+    padding: 6rem 0;
+}
+
+.use-cases-section {
+    padding: 6rem 0;
+    background: var(--light-color);
+}
+
+.tech-specs-section {
+    padding: 6rem 0;
+}
+
+.faq-section {
+    padding: 6rem 0;
+    background: var(--light-color);
+}
+
+.final-cta-section {
+    padding: 6rem 0;
+    background: var(--gradient-hero);
+    color: white;
+    position: relative;
+    overflow: hidden;
+}
+
+.cta-background-animation {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background: linear-gradient(45deg, transparent 30%, rgba(255,255,255,0.05) 50%, transparent 70%);
+    animation: shimmer 4s ease-in-out infinite;
+}
+
+.section-badge {
+    display: inline-block;
+    background: var(--gradient-primary);
+    color: white;
+    padding: 0.5rem 1.5rem;
+    border-radius: 2rem;
+    font-size: 0.875rem;
+    font-weight: 600;
+    margin-bottom: 1.5rem;
+    box-shadow: 0 4px 14px 0 rgba(99, 102, 241, 0.3);
+}
+
+/* Enhanced Loading States */
+.loading-spinner {
+    display: none;
+}
+
+.loading .loading-spinner {
+    display: inline-block;
+}
+
+.loading .btn-text {
+    display: none;
+}
+
+.loading {
+    position: relative;
+    overflow: hidden;
+}
+
+.loading::after {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: -100%;
+    width: 100%;
+    height: 100%;
+    background: linear-gradient(90deg, transparent, rgba(255,255,255,0.3), transparent);
+    animation: loading-shimmer 1.5s infinite;
+}
+
+@keyframes loading-shimmer {
+    0% { left: -100%; }
+    100% { left: 100%; }
+}
+
+/* Enhanced Code Blocks */
+.code-card {
+    background: white;
+    border-radius: var(--border-radius);
+    box-shadow: var(--box-shadow);
+    overflow: hidden;
+    border: 1px solid #e2e8f0;
+    transition: var(--transition);
+}
+
+.code-card:hover {
+    transform: translateY(-2px);
+    box-shadow: var(--box-shadow-lg);
+}
+
+.code-header {
+    background: var(--light-gray);
+    padding: 1rem 1.5rem;
+    border-bottom: 1px solid #e2e8f0;
+    display: flex;
+    justify-content: between;
+    align-items: center;
+}
+
+.code-header h4 {
+    margin: 0;
+    font-size: 1.1rem;
+    color: var(--dark-color);
+}
+
+.code-content {
+    padding: 1.5rem;
+    background: #f8fafc;
+    margin: 0;
+    overflow-x: auto;
+}
+
+.code-content code {
+    font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+    font-size: 0.9rem;
+    line-height: 1.6;
+    color: var(--text-color);
+}
+
+.code-footer {
+    padding: 1rem 1.5rem;
+    background: white;
+    border-top: 1px solid #e2e8f0;
+}
+
+.copy-btn {
+    font-size: 0.8rem;
+    padding: 0.25rem 0.75rem;
+}
+
+/* Enhanced Use Case Cards */
+.use-case-card {
+    background: white;
+    border-radius: var(--border-radius);
+    padding: 2rem;
+    box-shadow: var(--box-shadow);
+    transition: var(--transition);
+    border: 1px solid #e2e8f0;
+    height: 100%;
+    text-align: center;
+}
+
+.use-case-card:hover {
+    transform: translateY(-4px);
+    box-shadow: var(--box-shadow-lg);
+    border-color: rgba(99, 102, 241, 0.2);
+}
+
+.use-case-icon {
+    width: 4rem;
+    height: 4rem;
+    background: var(--gradient-primary);
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 1.5rem;
+    color: white;
+    margin: 0 auto 1.5rem;
+    box-shadow: 0 4px 14px 0 rgba(99, 102, 241, 0.3);
+}
+
+.use-case-title {
+    font-size: 1.25rem;
+    font-weight: 700;
+    color: var(--dark-color);
+    margin-bottom: 1rem;
+}
+
+.use-case-description {
+    color: var(--text-muted);
+    margin-bottom: 1.5rem;
+    line-height: 1.7;
+}
+
+.use-case-examples {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    justify-content: center;
+}
+
+.use-case-examples .badge {
+    font-size: 0.75rem;
+    padding: 0.4rem 0.8rem;
+    border-radius: 1rem;
+    background: var(--light-gray);
+    color: var(--text-color);
+    border: 1px solid #e2e8f0;
+}
+
+/* Enhanced Tech Spec Cards */
+.tech-spec-card {
+    background: white;
+    border-radius: var(--border-radius);
+    padding: 2rem;
+    box-shadow: var(--box-shadow);
+    transition: var(--transition);
+    border: 1px solid #e2e8f0;
+    height: 100%;
+}
+
+.tech-spec-card:hover {
+    transform: translateY(-2px);
+    box-shadow: var(--box-shadow-lg);
+}
+
+.tech-spec-icon {
+    width: 3rem;
+    height: 3rem;
+    background: var(--gradient-accent);
+    border-radius: var(--border-radius-sm);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 1.25rem;
+    color: white;
+    margin: 0 auto 1rem;
+}
+
+.tech-spec-card h4, .tech-spec-card h5 {
+    color: var(--dark-color);
+    margin-bottom: 1.5rem;
+}
+
+.tech-spec-card ul {
+    list-style: none;
+    padding: 0;
+}
+
+.tech-spec-card li {
+    padding: 0.5rem 0;
+    color: var(--text-color);
+    border-bottom: 1px solid #f1f5f9;
+}
+
+.tech-spec-card li:last-child {
+    border-bottom: none;
+}
+
+/* Enhanced Validation Styles */
+.badge {
+    font-size: 0.75em;
+    padding: 0.4em 0.8em;
+    border-radius: 1rem;
+    font-weight: 600;
+    letter-spacing: 0.025em;
+}
+
+.validation-result {
+    animation: slideDown 0.3s ease;
+}
+
+@keyframes slideDown {
+    from {
+        opacity: 0;
+        transform: translateY(-10px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+/* Enhanced Alert Styles */
+.alert {
+    border-radius: var(--border-radius);
+    border: none;
+    box-shadow: var(--box-shadow);
+    padding: 1rem 1.5rem;
+}
+
+.alert-success {
+    background: linear-gradient(135deg, rgba(16, 185, 129, 0.1) 0%, rgba(16, 185, 129, 0.05) 100%);
+    color: #065f46;
+    border-left: 4px solid var(--success-color);
+}
+
+.alert-warning {
+    background: linear-gradient(135deg, rgba(245, 158, 11, 0.1) 0%, rgba(245, 158, 11, 0.05) 100%);
+    color: #92400e;
+    border-left: 4px solid var(--warning-color);
+}
+
+.alert-danger {
+    background: linear-gradient(135deg, rgba(239, 68, 68, 0.1) 0%, rgba(239, 68, 68, 0.05) 100%);
+    color: #991b1b;
+    border-left: 4px solid var(--danger-color);
+}
+
+.alert-info {
+    background: linear-gradient(135deg, rgba(59, 130, 246, 0.1) 0%, rgba(59, 130, 246, 0.05) 100%);
+    color: #1e40af;
+    border-left: 4px solid var(--info-color);
+}
+
+/* Enhanced Accordion */
+.accordion-item {
+    border: none;
+    margin-bottom: 1rem;
+    border-radius: var(--border-radius) !important;
+    box-shadow: var(--box-shadow);
+    overflow: hidden;
+}
+
+.accordion-button {
+    background: white;
+    border: none;
+    padding: 1.5rem;
+    font-weight: 600;
+    color: var(--dark-color);
+    border-radius: var(--border-radius) !important;
+}
+
+.accordion-button:not(.collapsed) {
+    background: var(--light-gray);
+    color: var(--primary-color);
+    box-shadow: none;
+}
+
+.accordion-button:focus {
+    box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.1);
+    border-color: transparent;
+}
+
+.accordion-body {
+    padding: 1.5rem;
+    background: white;
+    color: var(--text-color);
+    line-height: 1.7;
+}
+
+/* Enhanced CTA Buttons */
+.cta-btn-primary, .cta-btn-secondary {
+    position: relative;
+    overflow: hidden;
+    backdrop-filter: blur(10px);
+    border-radius: var(--border-radius);
+}
+
+.cta-btn-primary small, .cta-btn-secondary small {
+    font-size: 0.75rem;
+    opacity: 0.9;
+    font-weight: 400;
+}
+
+.cta-content {
+    position: relative;
+    z-index: 2;
+}
+
+.cta-buttons {
+    margin: 2rem 0;
+}
+
+.cta-stats {
+    margin-top: 3rem;
+}
+
+.cta-stat h4 {
+    font-size: 2rem;
+    font-weight: 800;
+    margin-bottom: 0.25rem;
+}
+
+.cta-stat small {
+    font-size: 0.9rem;
+    opacity: 0.9;
+}
+
+/* Enhanced Quick Start */
+.quick-start-cta {
+    background: white;
+    border-radius: var(--border-radius-lg);
+    padding: 3rem;
+    box-shadow: var(--box-shadow-lg);
+    text-align: center;
+    border: 1px solid #e2e8f0;
+}
+
+.quick-start-cta h4 {
+    color: var(--dark-color);
+    margin-bottom: 1.5rem;
+}
+
+/* Enhanced Batch Processing */
+.batch-chunk-card {
+    transition: var(--transition);
+    border: 1px solid #e2e8f0;
+    border-radius: var(--border-radius);
+    overflow: hidden;
+}
+
+.batch-chunk-card:hover {
+    transform: translateY(-2px);
+    box-shadow: var(--box-shadow-lg);
+    border-color: rgba(99, 102, 241, 0.2);
+}
+
+.batch-chunk-card .card-body {
+    padding: 1.5rem;
+}
+
+.batch-chunk-card .card-title {
+    font-size: 1rem;
+    font-weight: 600;
+    color: var(--dark-color);
+}
+
+.batch-chunk-card .card-text {
+    color: var(--text-muted);
+    line-height: 1.6;
+}
+
+.download-chunk {
+    transition: var(--transition-fast);
+}
+
+.download-chunk:hover {
+    transform: scale(1.1);
+}
+
+/* Enhanced Navigation */
+.navbar {
+    backdrop-filter: blur(10px);
+    background: rgba(255, 255, 255, 0.95) !important;
+    border-bottom: 1px solid rgba(226, 232, 240, 0.8);
+    box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
+}
+
+.navbar-brand {
+    font-weight: 800;
+    font-size: 1.5rem;
+    color: var(--primary-color) !important;
+    transition: var(--transition);
+}
+
+.navbar-brand:hover {
+    transform: scale(1.05);
+}
+
+.navbar-nav .nav-link {
+    font-weight: 500;
+    transition: var(--transition);
+    color: var(--text-color) !important;
+    position: relative;
+    padding: 0.75rem 1rem !important;
+}
+
+.navbar-nav .nav-link::after {
+    content: '';
+    position: absolute;
+    bottom: 0;
+    left: 50%;
+    width: 0;
+    height: 2px;
+    background: var(--gradient-primary);
+    transition: var(--transition);
+    transform: translateX(-50%);
+}
+
+.navbar-nav .nav-link:hover::after {
+    width: 80%;
+}
+
+.navbar-nav .nav-link:hover {
+    color: var(--primary-color) !important;
+}
+
+.navbar-text {
+    color: var(--text-muted) !important;
+    font-weight: 500;
+}
+
+/* Enhanced Footer */
+.footer {
+    background: linear-gradient(135deg, var(--dark-color) 0%, #2d3748 100%);
+    color: white;
+    padding: 3rem 0 2rem;
+    margin-top: 6rem;
+    position: relative;
+    overflow: hidden;
+}
+
+.footer::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><defs><pattern id="footer-pattern" width="20" height="20" patternUnits="userSpaceOnUse"><circle cx="10" cy="10" r="0.5" fill="white" opacity="0.1"/></pattern></defs><rect width="100" height="100" fill="url(%23footer-pattern)"/></svg>');
+}
+
+.footer h5 {
+    color: white;
+    font-weight: 700;
+    margin-bottom: 1rem;
+}
+
+.footer p, .footer a {
+    color: rgba(255, 255, 255, 0.8);
+    transition: var(--transition);
+}
+
+.footer a:hover {
+    color: white;
+    text-decoration: none;
+}
+
+/* Enhanced Responsive Design */
+@media (max-width: 1200px) {
+    .hero-section {
+        padding: 4rem 0;
+    }
+
+    .floating-icon-container {
+        width: 250px;
+        height: 250px;
+    }
+
+    .floating-icon {
+        width: 50px;
+        height: 50px;
+        font-size: 1.25rem;
+    }
+
+    .hero-main-icon {
+        width: 100px;
+        height: 100px;
+        font-size: 2.5rem;
+    }
+}
+
+@media (max-width: 992px) {
+    .hero-section {
+        padding: 3rem 0;
+        min-height: auto;
+    }
+
+    .display-3 {
+        font-size: 2.5rem;
+    }
+
+    .features-section, .stats-section, .quick-start-section,
+    .use-cases-section, .tech-specs-section, .faq-section,
+    .final-cta-section {
+        padding: 4rem 0;
+    }
+
+    .floating-icon-container {
+        display: none;
+    }
+
+    .hero-visual {
+        margin-top: 2rem;
+    }
+}
+
+@media (max-width: 768px) {
+    .hero-section {
+        padding: 2rem 0;
+        text-align: center;
+    }
+
+    .display-3 {
+        font-size: 2rem;
+    }
+
+    .lead {
+        font-size: 1rem;
+    }
+
+    .btn-lg {
+        padding: 0.75rem 1.5rem;
+        font-size: 1rem;
+        width: 100%;
+        margin-bottom: 1rem;
+    }
+
+    .hero-stats .col-4 {
+        margin-bottom: 1rem;
+    }
+
+    .stat-item h3 {
+        font-size: 2rem;
+    }
+
+    .features-section, .stats-section, .quick-start-section,
+    .use-cases-section, .tech-specs-section, .faq-section,
+    .final-cta-section {
+        padding: 3rem 0;
+    }
+
+    .feature-card-enhanced, .use-case-card, .tech-spec-card {
+        margin-bottom: 2rem;
+    }
+
+    .code-card {
+        margin-bottom: 1.5rem;
+    }
+
+    .code-header {
+        flex-direction: column;
+        gap: 1rem;
+        text-align: center;
+    }
+
+    .quick-start-cta {
+        padding: 2rem 1rem;
+    }
+
+    .cta-buttons .btn {
+        width: 100%;
+        margin-bottom: 1rem;
+    }
+
+    .navbar-nav {
+        text-align: center;
+        padding: 1rem 0;
+    }
+
+    .toc {
+        position: static;
+        margin-bottom: 2rem;
+        max-height: none;
+    }
+}
+
+@media (max-width: 576px) {
+    .container {
+        padding-left: 1rem;
+        padding-right: 1rem;
+    }
+
+    .hero-section {
+        padding: 1.5rem 0;
+    }
+
+    .display-3 {
+        font-size: 1.75rem;
+    }
+
+    .card-body {
+        padding: 1.5rem;
+    }
+
+    .feature-card-enhanced, .use-case-card, .tech-spec-card {
+        padding: 1.5rem;
+    }
+
+    .stat-number {
+        font-size: 2.5rem;
+    }
+
+    .hero-main-icon {
+        width: 80px;
+        height: 80px;
+        font-size: 2rem;
+    }
+
+    .pulse-ring {
+        width: 100px;
+        height: 100px;
+    }
+}
+
+/* Enhanced Accessibility */
+.btn:focus,
+.form-control:focus,
+.form-select:focus,
+.form-check-input:focus {
+    outline: 3px solid rgba(99, 102, 241, 0.3);
+    outline-offset: 2px;
+}
+
+.btn:focus-visible,
+.form-control:focus-visible,
+.form-select:focus-visible {
+    outline: 3px solid var(--primary-color);
+    outline-offset: 2px;
+}
+
+/* Skip to content link for screen readers */
+.skip-link {
+    position: absolute;
+    top: -40px;
+    left: 6px;
+    background: var(--primary-color);
+    color: white;
+    padding: 8px;
+    text-decoration: none;
+    border-radius: 4px;
+    z-index: 1000;
+}
+
+.skip-link:focus {
+    top: 6px;
+}
+
+/* Enhanced Animation Classes */
+.fade-in {
+    animation: fadeIn 0.6s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@keyframes fadeIn {
+    from {
+        opacity: 0;
+        transform: translateY(10px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+.slide-up {
+    animation: slideUp 0.6s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@keyframes slideUp {
+    from {
+        opacity: 0;
+        transform: translateY(30px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+.scale-in {
+    animation: scaleIn 0.5s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@keyframes scaleIn {
+    from {
+        opacity: 0;
+        transform: scale(0.9);
+    }
+    to {
+        opacity: 1;
+        transform: scale(1);
+    }
+}
+
+/* Enhanced Utility Classes */
+.text-gradient {
+    background: var(--gradient-primary);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+
+.text-gradient-secondary {
+    background: var(--gradient-secondary);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+
+.shadow-custom {
+    box-shadow: var(--box-shadow);
+}
+
+.shadow-lg-custom {
+    box-shadow: var(--box-shadow-lg);
+}
+
+.shadow-xl-custom {
+    box-shadow: var(--box-shadow-xl);
+}
+
+.border-radius-custom {
+    border-radius: var(--border-radius);
+}
+
+.bg-gradient-primary {
+    background: var(--gradient-primary);
+}
+
+.bg-gradient-secondary {
+    background: var(--gradient-secondary);
+}
+
+.bg-gradient-accent {
+    background: var(--gradient-accent);
+}
+
+/* Enhanced Progress Indicators */
+.progress-custom {
+    height: 10px;
+    border-radius: var(--border-radius-sm);
+    background-color: #e2e8f0;
+    overflow: hidden;
+    box-shadow: inset 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.progress-bar-custom {
+    height: 100%;
+    background: var(--gradient-primary);
+    transition: width 0.6s cubic-bezier(0.4, 0, 0.2, 1);
+    position: relative;
+    overflow: hidden;
+}
+
+.progress-bar-custom::after {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background: linear-gradient(90deg, transparent, rgba(255,255,255,0.3), transparent);
+    animation: progress-shimmer 2s infinite;
+}
+
+@keyframes progress-shimmer {
+    0% { transform: translateX(-100%); }
+    100% { transform: translateX(100%); }
+}
+
+/* Enhanced Tooltip */
+.tooltip-inner {
+    background-color: var(--dark-color);
+    border-radius: var(--border-radius-sm);
+    font-size: 0.875rem;
+    padding: 0.5rem 0.75rem;
+    box-shadow: var(--box-shadow);
+}
+
+/* Enhanced Custom Scrollbar */
+::-webkit-scrollbar {
+    width: 10px;
+    height: 10px;
+}
+
+::-webkit-scrollbar-track {
+    background: var(--light-gray);
+    border-radius: var(--border-radius-sm);
+}
+
+::-webkit-scrollbar-thumb {
+    background: var(--gradient-primary);
+    border-radius: var(--border-radius-sm);
+    border: 2px solid var(--light-gray);
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: var(--gradient-secondary);
+}
+
+::-webkit-scrollbar-corner {
+    background: var(--light-gray);
+}
+
+/* Print Styles */
+@media print {
+    .navbar, .footer, .hero-scroll-indicator, .floating-icon-container {
+        display: none !important;
+    }
+
+    .hero-section {
+        background: white !important;
+        color: black !important;
+        padding: 1rem 0 !important;
+    }
+
+    .card {
+        box-shadow: none !important;
+        border: 1px solid #ddd !important;
+    }
+
+    .btn {
+        border: 1px solid #ddd !important;
+        background: white !important;
+        color: black !important;
+    }
+}
+
+/* Playground-Specific Styles */
+.playground-visual {
+    position: relative;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    height: 200px;
+}
+
+.playground-icon {
+    width: 100px;
+    height: 100px;
+    background: rgba(255, 255, 255, 0.15);
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 2.5rem;
+    color: white;
+    backdrop-filter: blur(20px);
+    border: 2px solid rgba(255, 255, 255, 0.3);
+    position: relative;
+}
+
+.audio-player-container {
+    border: 2px solid #e2e8f0;
+    transition: var(--transition);
+}
+
+.audio-player-container:hover {
+    border-color: var(--primary-color);
+    box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.1);
+}
+
+.stat-item {
+    padding: 1rem;
+    text-align: center;
+}
+
+.stat-item i {
+    font-size: 1.5rem;
+    margin-bottom: 0.5rem;
+    display: block;
+}
+
+.stat-value {
+    font-size: 1.25rem;
+    font-weight: 700;
+    color: var(--dark-color);
+    margin-bottom: 0.25rem;
+}
+
+.stat-label {
+    font-size: 0.875rem;
+    color: var(--text-muted);
+    font-weight: 500;
+}
+
+.card-header {
+    border-bottom: none;
+    border-radius: var(--border-radius) var(--border-radius) 0 0 !important;
+}
+
+/* Enhanced Form Controls for Playground */
+.playground .form-control,
+.playground .form-select {
+    border: 2px solid #e2e8f0;
+    border-radius: var(--border-radius-sm);
+    padding: 1rem;
+    font-size: 1rem;
+    transition: var(--transition);
+}
+
+.playground .form-control:focus,
+.playground .form-select:focus {
+    border-color: var(--primary-color);
+    box-shadow: 0 0 0 4px rgba(99, 102, 241, 0.1);
+    transform: translateY(-1px);
+}
+
+.playground .btn-group .btn {
+    border-radius: var(--border-radius-sm);
+}
+
+.playground .btn-group .btn:first-child {
+    border-top-right-radius: 0;
+    border-bottom-right-radius: 0;
+}
+
+.playground .btn-group .btn:last-child {
+    border-top-left-radius: 0;
+    border-bottom-left-radius: 0;
+}
+
+/* Audio Player Enhancements */
+audio::-webkit-media-controls-panel {
+    background-color: var(--light-gray);
+    border-radius: var(--border-radius-sm);
+}
+
+audio::-webkit-media-controls-play-button,
+audio::-webkit-media-controls-pause-button {
+    background-color: var(--primary-color);
+    border-radius: 50%;
+}
+
+audio::-webkit-media-controls-timeline {
+    background-color: var(--light-gray);
+    border-radius: var(--border-radius-sm);
+}
+
+audio::-webkit-media-controls-current-time-display,
+audio::-webkit-media-controls-time-remaining-display {
+    color: var(--text-color);
+    font-weight: 500;
+}
+
+/* Reduced Motion Support */
+@media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+    }
+
+    .hero-background-animation,
+    .floating-icon,
+    .pulse-ring,
+    .hero-scroll-indicator,
+    .playground-icon {
+        animation: none !important;
+    }
+}

static/js/i18n.js

@@ -0,0 +1,221 @@
+// JavaScript Internationalization Support for TTSFM
+
+// Translation data - this will be populated by the server
+window.i18nData = window.i18nData || {};
+
+// Current locale
+window.currentLocale = document.documentElement.lang || 'en';
+
+// Translation function
+function _(key, params = {}) {
+    const keys = key.split('.');
+    let value = window.i18nData;
+    
+    // Navigate through the nested object
+    for (const k of keys) {
+        if (value && typeof value === 'object' && k in value) {
+            value = value[k];
+        } else {
+            // Fallback to key if translation not found
+            return key;
+        }
+    }
+    
+    // If we found a string, apply parameters
+    if (typeof value === 'string') {
+        return formatString(value, params);
+    }
+    
+    // Fallback to key
+    return key;
+}
+
+// Format string with parameters
+function formatString(str, params) {
+    return str.replace(/\{(\w+)\}/g, (match, key) => {
+        return params.hasOwnProperty(key) ? params[key] : match;
+    });
+}
+
+// Load translations from server
+async function loadTranslations() {
+    try {
+        const response = await fetch(`/api/translations/${window.currentLocale}`);
+        if (response.ok) {
+            window.i18nData = await response.json();
+        }
+    } catch (error) {
+        console.warn('Failed to load translations:', error);
+    }
+}
+
+// Sample texts for different languages
+const sampleTexts = {
+    en: {
+        welcome: "Welcome to TTSFM! This is a free text-to-speech service that converts your text into high-quality audio using advanced AI technology.",
+        story: "Once upon a time, in a digital world far away, there lived a small Python package that could transform any text into beautiful speech. This package was called TTSFM, and it brought joy to developers everywhere.",
+        technical: "TTSFM is a Python client for text-to-speech APIs that provides both synchronous and asynchronous interfaces. It supports multiple voices and audio formats, making it perfect for various applications.",
+        multilingual: "TTSFM supports multiple languages and voices, allowing you to create diverse audio content for global audiences. The service is completely free and requires no API keys.",
+        long: "This is a longer text sample designed to test the auto-combine feature of TTSFM. When text exceeds the maximum length limit, TTSFM automatically splits it into smaller chunks, generates audio for each chunk, and then seamlessly combines them into a single audio file. This process is completely transparent to the user and ensures that you can convert text of any length without worrying about technical limitations. The resulting audio maintains consistent quality and natural flow throughout the entire content."
+    },
+    zh: {
+        welcome: "欢迎使用TTSFM！这是一个免费的文本转语音服务，使用先进的AI技术将您的文本转换为高质量音频。",
+        story: "很久很久以前，在一个遥远的数字世界里，住着一个小小的Python包，它能够将任何文本转换成美妙的语音。这个包叫做TTSFM，它为世界各地的开发者带来了快乐。",
+        technical: "TTSFM是一个用于文本转语音API的Python客户端，提供同步和异步接口。它支持多种声音和音频格式，非常适合各种应用。",
+        multilingual: "TTSFM支持多种语言和声音，让您能够为全球受众创建多样化的音频内容。该服务完全免费，无需API密钥。",
+        long: "这是一个较长的文本示例，用于测试TTSFM的自动合并功能。当文本超过最大长度限制时，TTSFM会自动将其分割成较小的片段，为每个片段生成音频，然后无缝地将它们合并成一个音频文件。这个过程对用户完全透明，确保您可以转换任何长度的文本，而无需担心技术限制。生成的音频在整个内容中保持一致的质量和自然的流畅性。"
+    }
+};
+
+// Get sample text for current locale
+function getSampleText(type) {
+    const locale = window.currentLocale;
+    const texts = sampleTexts[locale] || sampleTexts.en;
+    return texts[type] || texts.welcome;
+}
+
+// Error messages
+const errorMessages = {
+    en: {
+        empty_text: "Please enter some text to convert.",
+        generation_failed: "Failed to generate speech. Please try again.",
+        network_error: "Network error. Please check your connection and try again.",
+        invalid_format: "Invalid audio format selected.",
+        invalid_voice: "Invalid voice selected.",
+        text_too_long: "Text is too long. Please reduce the length or enable auto-combine.",
+        server_error: "Server error. Please try again later."
+    },
+    zh: {
+        empty_text: "请输入要转换的文本。",
+        generation_failed: "语音生成失败。请重试。",
+        network_error: "网络错误。请检查您的连接并重��。",
+        invalid_format: "选择的音频格式无效。",
+        invalid_voice: "选择的声音无效。",
+        text_too_long: "文本太长。请减少长度或启用自动合并。",
+        server_error: "服务器错误。请稍后重试。"
+    }
+};
+
+// Success messages
+const successMessages = {
+    en: {
+        generation_complete: "Speech generated successfully!",
+        text_copied: "Text copied to clipboard!",
+        download_started: "Download started!"
+    },
+    zh: {
+        generation_complete: "语音生成成功！",
+        text_copied: "文本已复制到剪贴板！",
+        download_started: "下载已开始！"
+    }
+};
+
+// Get error message
+function getErrorMessage(key) {
+    const locale = window.currentLocale;
+    const messages = errorMessages[locale] || errorMessages.en;
+    return messages[key] || key;
+}
+
+// Get success message
+function getSuccessMessage(key) {
+    const locale = window.currentLocale;
+    const messages = successMessages[locale] || successMessages.en;
+    return messages[key] || key;
+}
+
+// Format file size
+function formatFileSize(bytes) {
+    if (bytes === 0) return '0 Bytes';
+    
+    const k = 1024;
+    const sizes = window.currentLocale === 'zh' 
+        ? ['字节', 'KB', 'MB', 'GB'] 
+        : ['Bytes', 'KB', 'MB', 'GB'];
+    
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+
+// Format duration
+function formatDuration(seconds) {
+    if (isNaN(seconds) || seconds < 0) {
+        return window.currentLocale === 'zh' ? '未知' : 'Unknown';
+    }
+    
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = Math.floor(seconds % 60);
+    
+    if (minutes > 0) {
+        return window.currentLocale === 'zh' 
+            ? `${minutes}分${remainingSeconds}秒`
+            : `${minutes}m ${remainingSeconds}s`;
+    } else {
+        return window.currentLocale === 'zh' 
+            ? `${remainingSeconds}秒`
+            : `${remainingSeconds}s`;
+    }
+}
+
+// Update UI text based on current locale
+function updateUIText() {
+    // Update button texts
+    const generateBtn = document.getElementById('generate-btn');
+    if (generateBtn && !generateBtn.disabled) {
+        generateBtn.innerHTML = window.currentLocale === 'zh' 
+            ? '<i class="fas fa-magic me-2"></i>生成语音'
+            : '<i class="fas fa-magic me-2"></i>Generate Speech';
+    }
+    
+    // Update other dynamic text elements
+    const charCountElement = document.querySelector('#char-count');
+    if (charCountElement) {
+        const count = charCountElement.textContent;
+        const parent = charCountElement.parentElement;
+        if (parent) {
+            // Escape HTML characters to prevent XSS
+            const escapedCount = count.replace(/&/g, '&amp;')
+                                     .replace(/</g, '&lt;')
+                                     .replace(/>/g, '&gt;')
+                                     .replace(/"/g, '&quot;')
+                                     .replace(/'/g, '&#x27;');
+            
+            parent.innerHTML = window.currentLocale === 'zh'
+                ? `<i class="fas fa-keyboard me-1"></i><span id="char-count">${escapedCount}</span> 字符`
+                : `<i class="fas fa-keyboard me-1"></i><span id="char-count">${escapedCount}</span> characters`;
+        }
+    }
+}
+
+// Initialize i18n
+function initI18n() {
+    // Load translations if needed
+    loadTranslations();
+    
+    // Update UI text
+    updateUIText();
+    
+    // Listen for language changes
+    document.addEventListener('languageChanged', function(event) {
+        window.currentLocale = event.detail.locale;
+        loadTranslations().then(() => {
+            updateUIText();
+        });
+    });
+}
+
+// Export functions for global use
+window._ = _;
+window.getSampleText = getSampleText;
+window.getErrorMessage = getErrorMessage;
+window.getSuccessMessage = getSuccessMessage;
+window.formatFileSize = formatFileSize;
+window.formatDuration = formatDuration;
+window.initI18n = initI18n;
+
+// Auto-initialize when DOM is ready
+if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initI18n);
+} else {
+    initI18n();
+}

static/js/playground-enhanced-fixed.js

@@ -0,0 +1,712 @@
+// TTSFM Enhanced Playground with WebSocket Streaming Support - Fixed Version
+
+// Global variables
+let currentAudioBlob = null;
+let currentFormat = 'mp3';
+let batchResults = [];
+let wsClient = null;
+let streamingMode = false;
+let currentStreamRequest = null;
+
+// Initialize playground
+document.addEventListener('DOMContentLoaded', function() {
+    initializePlayground();
+    initializeWebSocket();
+});
+
+// Initialize WebSocket client
+function initializeWebSocket() {
+    // Check if Socket.IO is available
+    if (typeof io === 'undefined') {
+        console.warn('Socket.IO not loaded. WebSocket streaming will be disabled.');
+        return;
+    }
+    
+    // Initialize WebSocket client
+    wsClient = new WebSocketTTSClient({
+        socketUrl: window.location.origin,
+        debug: true,
+        onConnect: () => {
+            console.log('WebSocket connected');
+            updateStreamingStatus('connected');
+        },
+        onDisconnect: () => {
+            console.log('WebSocket disconnected');
+            updateStreamingStatus('disconnected');
+        },
+        onError: (error) => {
+            console.error('WebSocket error:', error);
+            updateStreamingStatus('error');
+        }
+    });
+}
+
+// Update streaming status indicator
+function updateStreamingStatus(status) {
+    const indicator = document.getElementById('streaming-indicator');
+    if (!indicator) return;
+    
+    indicator.className = 'streaming-status';
+    switch(status) {
+        case 'connected':
+            indicator.classList.add('connected');
+            indicator.innerHTML = '<i class="fas fa-bolt"></i> Streaming Ready';
+            enableStreamingMode(true);
+            break;
+        case 'disconnected':
+            indicator.classList.add('disconnected');
+            indicator.innerHTML = '<i class="fas fa-plug"></i> Streaming Offline';
+            enableStreamingMode(false);
+            break;
+        case 'error':
+            indicator.classList.add('error');
+            indicator.innerHTML = '<i class="fas fa-exclamation-triangle"></i> Connection Error';
+            enableStreamingMode(false);
+            break;
+        case 'streaming':
+            indicator.classList.add('streaming');
+            indicator.innerHTML = '<i class="fas fa-stream"></i> Streaming...';
+            break;
+    }
+}
+
+// Enable/disable streaming mode
+function enableStreamingMode(enabled) {
+    const streamToggle = document.getElementById('stream-mode-toggle');
+    if (streamToggle) {
+        streamToggle.disabled = !enabled;
+        if (!enabled && streamingMode) {
+            streamingMode = false;
+            streamToggle.checked = false;
+        }
+    }
+}
+
+// Check authentication status
+async function checkAuthStatus() {
+    try {
+        const response = await fetch('/api/auth-status');
+        const data = await response.json();
+
+        const apiKeySection = document.getElementById('api-key-section');
+        if (apiKeySection) {
+            if (data.api_key_required) {
+                apiKeySection.style.display = 'block';
+                const apiKeyInput = document.getElementById('api-key-input');
+                if (apiKeyInput) {
+                    apiKeyInput.required = true;
+                }
+            } else {
+                apiKeySection.style.display = 'none';
+            }
+        }
+    } catch (error) {
+        console.warn('Could not check auth status:', error);
+    }
+}
+
+function initializePlayground() {
+    console.log('Initializing enhanced playground...');
+    checkAuthStatus();
+    loadVoices();
+    loadFormats();
+    updateCharCount();
+    setupEventListeners();
+    setupStreamingControls();
+    console.log('Enhanced playground initialization complete');
+}
+
+function setupStreamingControls() {
+    // Add streaming mode toggle
+    const generateButton = document.getElementById('generate-btn');
+    if (generateButton && generateButton.parentElement) {
+        const streamingControls = document.createElement('div');
+        streamingControls.className = 'streaming-controls mt-3';
+        streamingControls.innerHTML = `
+            <div class="form-check form-switch">
+                <input class="form-check-input" type="checkbox" id="stream-mode-toggle" disabled>
+                <label class="form-check-label" for="stream-mode-toggle">
+                    <i class="fas fa-bolt me-1"></i>
+                    Enable WebSocket Streaming
+                    <small class="text-muted">(Real-time audio chunks)</small>
+                </label>
+            </div>
+            <div id="streaming-indicator" class="streaming-status mt-2"></div>
+        `;
+        generateButton.parentElement.appendChild(streamingControls);
+        
+        // Add toggle event listener
+        const toggle = document.getElementById('stream-mode-toggle');
+        if (toggle) {
+            toggle.addEventListener('change', (e) => {
+                streamingMode = e.target.checked;
+                console.log('Streaming mode:', streamingMode ? 'ON' : 'OFF');
+                
+                // Update button text
+                const btnText = generateButton.querySelector('.btn-text');
+                if (btnText) {
+                    if (streamingMode) {
+                        btnText.innerHTML = '<i class="fas fa-bolt me-2"></i>Stream Speech';
+                    } else {
+                        btnText.innerHTML = '<i class="fas fa-magic me-2"></i>' + 
+                            (window.currentLocale === 'zh' ? '生成语音' : 'Generate Speech');
+                    }
+                }
+            });
+        }
+    }
+    
+    // Add streaming progress section and error message div
+    const audioResult = document.getElementById('audio-result');
+    if (audioResult && audioResult.parentElement) {
+        // Add error message div
+        const errorDiv = document.createElement('div');
+        errorDiv.id = 'error-message';
+        errorDiv.className = 'alert alert-danger';
+        errorDiv.style.display = 'none';
+        audioResult.parentElement.insertBefore(errorDiv, audioResult);
+        
+        // Add loading section
+        const loadingDiv = document.createElement('div');
+        loadingDiv.id = 'loading-section';
+        loadingDiv.className = 'text-center';
+        loadingDiv.style.display = 'none';
+        loadingDiv.innerHTML = `
+            <div class="spinner-border text-primary" role="status">
+                <span class="visually-hidden">Loading...</span>
+            </div>
+            <p class="mt-2">Generating speech...</p>
+        `;
+        audioResult.parentElement.insertBefore(loadingDiv, audioResult);
+        
+        // Add progress section
+        const progressSection = document.createElement('div');
+        progressSection.id = 'streaming-progress';
+        progressSection.className = 'streaming-progress-section';
+        progressSection.style.display = 'none';
+        progressSection.innerHTML = `
+            <div class="card border-primary">
+                <div class="card-body">
+                    <h5 class="card-title">
+                        <i class="fas fa-stream me-2"></i>Streaming Progress
+                    </h5>
+                    <div class="progress mb-3" style="height: 25px;">
+                        <div class="progress-bar progress-bar-striped progress-bar-animated" 
+                             id="stream-progress-bar" 
+                             role="progressbar" 
+                             style="width: 0%">
+                            <span id="stream-progress-text">0%</span>
+                        </div>
+                    </div>
+                    <div class="row text-center">
+                        <div class="col-md-4">
+                            <h6>Chunks</h6>
+                            <p class="h5"><span id="chunks-count">0</span> / <span id="total-chunks">0</span></p>
+                        </div>
+                        <div class="col-md-4">
+                            <h6>Data</h6>
+                            <p class="h5" id="data-transferred">0 KB</p>
+                        </div>
+                        <div class="col-md-4">
+                            <h6>Time</h6>
+                            <p class="h5" id="stream-time">0.0s</p>
+                        </div>
+                    </div>
+                    <div id="chunks-visualization" class="chunks-visual mt-3"></div>
+                </div>
+            </div>
+        `;
+        audioResult.parentElement.insertBefore(progressSection, audioResult);
+    }
+}
+
+function setupEventListeners() {
+    console.log('Setting up event listeners...');
+
+    // Form and input events
+    const textInput = document.getElementById('text-input');
+    if (textInput) {
+        textInput.addEventListener('input', updateCharCount);
+    }
+
+    // Form submit
+    const form = document.getElementById('tts-form');
+    if (form) {
+        form.addEventListener('submit', function(event) {
+            event.preventDefault();
+            event.stopPropagation();
+            
+            if (streamingMode && wsClient && wsClient.isConnected()) {
+                generateSpeechStreaming(event);
+            } else {
+                generateSpeech(event);
+            }
+            
+            return false;
+        });
+    }
+
+    // Download button
+    const downloadBtn = document.getElementById('download-btn');
+    if (downloadBtn) {
+        downloadBtn.addEventListener('click', downloadAudio);
+    }
+}
+
+// Generate speech using WebSocket streaming
+async function generateSpeechStreaming(event) {
+    event.preventDefault();
+    
+    const text = document.getElementById('text-input').value.trim();
+    const voice = document.getElementById('voice-select').value;
+    const format = document.getElementById('format-select').value;
+    
+    if (!text) {
+        showError('Please enter some text to convert');
+        return;
+    }
+    
+    // Reset UI
+    hideError();
+    hideResults();
+    disableForm();
+    
+    // Show streaming progress
+    const progressSection = document.getElementById('streaming-progress');
+    if (progressSection) progressSection.style.display = 'block';
+    
+    // Reset progress
+    updateStreamingProgress(0, 0, 0);
+    const chunksViz = document.getElementById('chunks-visualization');
+    if (chunksViz) chunksViz.innerHTML = '';
+    
+    // Update status
+    updateStreamingStatus('streaming');
+    
+    const startTime = Date.now();
+    let audioChunks = [];
+    
+    try {
+        const result = await wsClient.generateSpeech(text, {
+            voice: voice,
+            format: format,
+            chunkSize: 512,
+            onStart: (data) => {
+                currentStreamRequest = data.request_id;
+                console.log('Streaming started:', data);
+            },
+            onProgress: (progress) => {
+                updateStreamingProgress(
+                    progress.progress,
+                    progress.chunksCompleted,
+                    progress.totalChunks
+                );
+                
+                const elapsed = (Date.now() - startTime) / 1000;
+                const timeEl = document.getElementById('stream-time');
+                if (timeEl) timeEl.textContent = `${elapsed.toFixed(1)}s`;
+            },
+            onChunk: (chunk) => {
+                // Visualize chunk
+                const chunksViz = document.getElementById('chunks-visualization');
+                if (chunksViz) {
+                    const chunkViz = document.createElement('div');
+                    chunkViz.className = 'chunk-indicator';
+                    chunkViz.title = `Chunk ${chunk.chunkIndex + 1} - ${(chunk.audioData.byteLength / 1024).toFixed(1)}KB`;
+                    chunkViz.innerHTML = `<i class="fas fa-music"></i>`;
+                    chunksViz.appendChild(chunkViz);
+                }
+                
+                // Update data transferred
+                const dataEl = document.getElementById('data-transferred');
+                if (dataEl) {
+                    const currentData = parseFloat(dataEl.textContent) || 0;
+                    const newData = currentData + (chunk.audioData.byteLength / 1024);
+                    dataEl.textContent = `${newData.toFixed(1)} KB`;
+                }
+                
+                audioChunks.push(chunk);
+            },
+            onComplete: (result) => {
+                console.log('Streaming complete:', result);
+                
+                // Create blob from audio data
+                currentAudioBlob = new Blob([result.audioData], { type: `audio/${result.format}` });
+                currentFormat = result.format;
+                
+                // Show results
+                showResults(currentAudioBlob, result.format);
+                
+                // Update final stats
+                const totalTime = (Date.now() - startTime) / 1000;
+                showStreamingStats({
+                    chunks: result.chunks.length,
+                    totalSize: (result.audioData.byteLength / 1024).toFixed(1),
+                    totalTime: totalTime.toFixed(2),
+                    format: result.format
+                });
+            },
+            onError: (error) => {
+                showError(`Streaming error: ${error.message}`);
+                enableForm();
+                if (progressSection) progressSection.style.display = 'none';
+            }
+        });
+        
+    } catch (error) {
+        showError(`Failed to stream speech: ${error.message}`);
+        enableForm();
+        if (progressSection) progressSection.style.display = 'none';
+    } finally {
+        updateStreamingStatus('connected');
+        currentStreamRequest = null;
+    }
+}
+
+function updateStreamingProgress(progress, chunks, totalChunks) {
+    const progressBar = document.getElementById('stream-progress-bar');
+    const progressText = document.getElementById('stream-progress-text');
+    const chunksCount = document.getElementById('chunks-count');
+    const totalChunksEl = document.getElementById('total-chunks');
+    
+    if (progressBar) {
+        progressBar.style.width = `${progress}%`;
+        if (progressText) progressText.textContent = `${progress}%`;
+    }
+    if (chunksCount) chunksCount.textContent = chunks;
+    if (totalChunksEl) totalChunksEl.textContent = totalChunks;
+}
+
+function showStreamingStats(stats) {
+    const progressSection = document.getElementById('streaming-progress');
+    if (!progressSection) return;
+    
+    const statsHtml = `
+        <div class="alert alert-success mt-3">
+            <h6><i class="fas fa-check-circle me-2"></i>Streaming Complete!</h6>
+            <div class="row mt-2">
+                <div class="col-md-3">
+                    <strong>Chunks:</strong> ${stats.chunks}
+                </div>
+                <div class="col-md-3">
+                    <strong>Total Size:</strong> ${stats.totalSize} KB
+                </div>
+                <div class="col-md-3">
+                    <strong>Time:</strong> ${stats.totalTime}s
+                </div>
+                <div class="col-md-3">
+                    <strong>Format:</strong> ${stats.format.toUpperCase()}
+                </div>
+            </div>
+        </div>
+    `;
+    
+    const statsDiv = document.createElement('div');
+    statsDiv.innerHTML = statsHtml;
+    progressSection.appendChild(statsDiv);
+}
+
+// Load available voices
+async function loadVoices() {
+    try {
+        const response = await fetch('/api/voices');
+        const data = await response.json();
+        
+        const voiceSelect = document.getElementById('voice-select');
+        if (voiceSelect) {
+            voiceSelect.innerHTML = '';
+            
+            data.voices.forEach(voice => {
+                const option = document.createElement('option');
+                option.value = voice.id;
+                option.textContent = voice.name;
+                if (voice.id === 'alloy') {
+                    option.selected = true;
+                }
+                voiceSelect.appendChild(option);
+            });
+        }
+    } catch (error) {
+        console.error('Failed to load voices:', error);
+    }
+}
+
+// Load available formats
+async function loadFormats() {
+    try {
+        const response = await fetch('/api/formats');
+        const data = await response.json();
+        
+        const formatSelect = document.getElementById('format-select');
+        if (formatSelect) {
+            formatSelect.innerHTML = '';
+            
+            data.formats.forEach(format => {
+                const option = document.createElement('option');
+                option.value = format.id;
+                option.textContent = `${format.name} - ${format.quality}`;
+                if (format.id === 'mp3') {
+                    option.selected = true;
+                }
+                formatSelect.appendChild(option);
+            });
+        }
+    } catch (error) {
+        console.error('Failed to load formats:', error);
+    }
+}
+
+// Update character count
+function updateCharCount() {
+    const textInput = document.getElementById('text-input');
+    const charCount = document.getElementById('char-count');
+    const maxLengthInput = document.getElementById('max-length-input');
+    
+    if (textInput && charCount) {
+        const currentLength = textInput.value.length;
+        const maxLength = maxLengthInput ? parseInt(maxLengthInput.value) : 4096;
+        
+        charCount.textContent = currentLength;
+        
+        if (currentLength > maxLength) {
+            charCount.className = 'text-danger fw-bold';
+        } else if (currentLength > maxLength * 0.8) {
+            charCount.className = 'text-warning fw-bold';
+        } else {
+            charCount.className = '';
+        }
+    }
+}
+
+// Generate speech (original HTTP method)
+async function generateSpeech(event) {
+    event.preventDefault();
+    
+    const text = document.getElementById('text-input').value.trim();
+    const voice = document.getElementById('voice-select').value;
+    const format = document.getElementById('format-select').value;
+    const instructions = document.getElementById('instructions-input')?.value.trim() || '';
+    const apiKey = document.getElementById('api-key-input')?.value.trim() || '';
+    
+    if (!text) {
+        showError('Please enter some text to convert');
+        return;
+    }
+    
+    hideError();
+    hideResults();
+    showLoading();
+    disableForm();
+    
+    try {
+        const headers = {
+            'Content-Type': 'application/json'
+        };
+        
+        if (apiKey) {
+            headers['Authorization'] = `Bearer ${apiKey}`;
+        }
+        
+        const requestBody = {
+            text: text,
+            voice: voice,
+            format: format
+        };
+        
+        if (instructions) {
+            requestBody.instructions = instructions;
+        }
+        
+        const response = await fetch('/api/generate', {
+            method: 'POST',
+            headers: headers,
+            body: JSON.stringify(requestBody)
+        });
+        
+        if (!response.ok) {
+            let errorMessage = `Error: ${response.status} ${response.statusText}`;
+            try {
+                const errorData = await response.json();
+                if (errorData.error?.message) {
+                    errorMessage = errorData.error.message;
+                }
+            } catch (e) {
+                // Use default error message
+            }
+            throw new Error(errorMessage);
+        }
+        
+        const blob = await response.blob();
+        currentAudioBlob = blob;
+        currentFormat = format;
+        
+        showResults(blob, format);
+        
+    } catch (error) {
+        showError(error.message);
+    } finally {
+        hideLoading();
+        enableForm();
+    }
+}
+
+// Show/hide functions
+function showLoading() {
+    const loading = document.getElementById('loading-section');
+    if (loading) loading.style.display = 'block';
+}
+
+function hideLoading() {
+    const loading = document.getElementById('loading-section');
+    if (loading) loading.style.display = 'none';
+}
+
+function showResults(blob, format) {
+    const audioUrl = URL.createObjectURL(blob);
+    const audioPlayer = document.getElementById('audio-player');
+    if (audioPlayer) {
+        audioPlayer.src = audioUrl;
+    }
+    
+    const audioResult = document.getElementById('audio-result');
+    if (audioResult) {
+        audioResult.classList.remove('d-none');
+    }
+    
+    const downloadBtn = document.getElementById('download-btn');
+    if (downloadBtn) {
+        downloadBtn.disabled = false;
+    }
+    
+    enableForm();
+}
+
+function hideResults() {
+    const audioResult = document.getElementById('audio-result');
+    if (audioResult) {
+        audioResult.classList.add('d-none');
+    }
+}
+
+function showError(message) {
+    const errorDiv = document.getElementById('error-message');
+    if (errorDiv) {
+        errorDiv.textContent = message;
+        errorDiv.style.display = 'block';
+    }
+}
+
+function hideError() {
+    const errorDiv = document.getElementById('error-message');
+    if (errorDiv) {
+        errorDiv.style.display = 'none';
+    }
+}
+
+function disableForm() {
+    const elements = ['generate-btn', 'text-input', 'voice-select', 'format-select'];
+    elements.forEach(id => {
+        const el = document.getElementById(id);
+        if (el) el.disabled = true;
+    });
+}
+
+function enableForm() {
+    const elements = ['generate-btn', 'text-input', 'voice-select', 'format-select'];
+    elements.forEach(id => {
+        const el = document.getElementById(id);
+        if (el) el.disabled = false;
+    });
+}
+
+// Download audio
+function downloadAudio() {
+    if (!currentAudioBlob) return;
+    
+    const url = URL.createObjectURL(currentAudioBlob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `tts_${Date.now()}.${currentFormat}`;
+    a.click();
+    URL.revokeObjectURL(url);
+}
+
+// Add CSS for streaming visualization
+const style = document.createElement('style');
+style.textContent = `
+.streaming-controls {
+    padding: 15px;
+    background-color: #f8f9fa;
+    border-radius: 8px;
+}
+
+.streaming-status {
+    display: inline-block;
+    padding: 5px 10px;
+    border-radius: 20px;
+    font-size: 0.875rem;
+    font-weight: 500;
+}
+
+.streaming-status.connected {
+    background-color: #d4edda;
+    color: #155724;
+}
+
+.streaming-status.disconnected {
+    background-color: #f8d7da;
+    color: #721c24;
+}
+
+.streaming-status.error {
+    background-color: #fff3cd;
+    color: #856404;
+}
+
+.streaming-status.streaming {
+    background-color: #cce5ff;
+    color: #004085;
+    animation: pulse 1.5s infinite;
+}
+
+@keyframes pulse {
+    0% { opacity: 1; }
+    50% { opacity: 0.7; }
+    100% { opacity: 1; }
+}
+
+.streaming-progress-section {
+    margin-bottom: 20px;
+}
+
+.chunks-visual {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 5px;
+}
+
+.chunk-indicator {
+    width: 30px;
+    height: 30px;
+    background-color: #007bff;
+    color: white;
+    border-radius: 4px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 0.75rem;
+    animation: chunkAppear 0.3s ease-out;
+}
+
+@keyframes chunkAppear {
+    from {
+        transform: scale(0);
+        opacity: 0;
+    }
+    to {
+        transform: scale(1);
+        opacity: 1;
+    }
+}
+`;
+document.head.appendChild(style);

static/js/playground.js

@@ -0,0 +1,861 @@
+// TTSFM Playground JavaScript
+
+// Global variables
+let currentAudioBlob = null;
+let currentFormat = 'mp3';
+let batchResults = [];
+
+// Initialize playground
+document.addEventListener('DOMContentLoaded', function() {
+    initializePlayground();
+});
+
+// Check authentication status and show/hide API key field
+async function checkAuthStatus() {
+    try {
+        const response = await fetch('/api/auth-status');
+        const data = await response.json();
+
+        const apiKeySection = document.getElementById('api-key-section');
+        if (apiKeySection) {
+            if (data.api_key_required) {
+                // Show API key field and mark as required
+                apiKeySection.style.display = 'block';
+                const apiKeyInput = document.getElementById('api-key-input');
+                const label = apiKeySection.querySelector('label');
+
+                if (apiKeyInput) {
+                    apiKeyInput.required = true;
+                    apiKeyInput.placeholder = 'Enter your API key (required)';
+                }
+
+                if (label) {
+                    label.innerHTML = '<i class="fas fa-key me-2"></i>' + (window.currentLocale === 'zh' ? 'API密钥（必需）' : 'API Key (Required)');
+                }
+
+                // Update form text
+                const formText = apiKeySection.querySelector('.form-text');
+                if (formText) {
+                    formText.innerHTML = '<i class="fas fa-exclamation-triangle me-1 text-warning"></i>API key protection is enabled - this field is required';
+                }
+            } else {
+                // Hide API key field or mark as optional
+                apiKeySection.style.display = 'none';
+            }
+        }
+    } catch (error) {
+        console.warn('Could not check auth status:', error);
+        // If we can't check, assume API key might be required and show the field
+        const apiKeySection = document.getElementById('api-key-section');
+        if (apiKeySection) {
+            apiKeySection.style.display = 'block';
+        }
+    }
+}
+
+function initializePlayground() {
+    console.log('Initializing playground...');
+    checkAuthStatus();
+    loadVoices();
+    loadFormats();
+    updateCharCount();
+    setupEventListeners();
+    console.log('Playground initialization complete');
+
+    // Initialize tooltips if Bootstrap is available
+    if (typeof bootstrap !== 'undefined') {
+        const tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'));
+        tooltipTriggerList.map(function (tooltipTriggerEl) {
+            return new bootstrap.Tooltip(tooltipTriggerEl);
+        });
+    }
+}
+
+function setupEventListeners() {
+    console.log('Setting up event listeners...');
+
+    // Form and input events
+    const textInput = document.getElementById('text-input');
+    if (textInput) {
+        textInput.addEventListener('input', updateCharCount);
+        console.log('Text input event listener added');
+    } else {
+        console.error('Text input element not found!');
+    }
+
+    // Add form submit event listener with better error handling
+    const form = document.getElementById('tts-form');
+    if (form) {
+        form.addEventListener('submit', function(event) {
+            console.log('Form submit event triggered');
+            event.preventDefault(); // Prevent default form submission
+            event.stopPropagation(); // Stop event bubbling
+            generateSpeech(event);
+            return false; // Additional prevention
+        });
+    } else {
+        console.error('TTS form not found!');
+    }
+
+    const maxLengthInput = document.getElementById('max-length-input');
+    if (maxLengthInput) {
+        maxLengthInput.addEventListener('input', updateCharCount);
+        console.log('Max length input event listener added');
+    } else {
+        console.error('Max length input element not found!');
+    }
+
+    const autoCombineCheck = document.getElementById('auto-combine-check');
+    if (autoCombineCheck) {
+        autoCombineCheck.addEventListener('change', updateAutoCombineStatus);
+    }
+
+    // Enhanced button events
+    const validateBtn = document.getElementById('validate-text-btn');
+    if (validateBtn) {
+        validateBtn.addEventListener('click', validateText);
+        console.log('Validate button event listener added');
+    } else {
+        console.error('Validate button not found!');
+    }
+
+    const randomBtn = document.getElementById('random-text-btn');
+    if (randomBtn) {
+        randomBtn.addEventListener('click', loadRandomText);
+        console.log('Random text button event listener added');
+    } else {
+        console.error('Random text button not found!');
+    }
+
+    const downloadBtn = document.getElementById('download-btn');
+    if (downloadBtn) {
+        downloadBtn.addEventListener('click', downloadAudio);
+        console.log('Download button event listener added');
+    } else {
+        console.error('Download button not found!');
+    }
+
+    // Add direct click event listener for generate button as backup
+    const generateBtn = document.getElementById('generate-btn');
+    if (generateBtn) {
+        generateBtn.addEventListener('click', function(event) {
+            console.log('Generate button clicked directly');
+            event.preventDefault();
+            event.stopPropagation();
+            generateSpeech(event);
+            return false;
+        });
+    }
+
+    // New button events
+    const clearTextBtn = document.getElementById('clear-text-btn');
+    if (clearTextBtn) {
+        clearTextBtn.addEventListener('click', clearText);
+    }
+
+
+
+    const resetFormBtn = document.getElementById('reset-form-btn');
+    if (resetFormBtn) {
+        resetFormBtn.addEventListener('click', resetForm);
+    }
+
+    const replayBtn = document.getElementById('replay-btn');
+    if (replayBtn) {
+        replayBtn.addEventListener('click', replayAudio);
+    }
+
+    const shareBtn = document.getElementById('share-btn');
+    if (shareBtn) {
+        shareBtn.addEventListener('click', shareAudio);
+    }
+
+    // API Key visibility toggle
+    const toggleApiKeyBtn = document.getElementById('toggle-api-key-visibility');
+    if (toggleApiKeyBtn) {
+        toggleApiKeyBtn.addEventListener('click', toggleApiKeyVisibility);
+    }
+
+    // Voice and format selection events
+    const voiceSelect = document.getElementById('voice-select');
+    if (voiceSelect) {
+        voiceSelect.addEventListener('change', updateVoiceInfo);
+        console.log('Voice select event listener added');
+    } else {
+        console.error('Voice select element not found!');
+    }
+
+    const formatSelect = document.getElementById('format-select');
+    if (formatSelect) {
+        formatSelect.addEventListener('change', updateFormatInfo);
+        console.log('Format select event listener added');
+    } else {
+        console.error('Format select element not found!');
+    }
+
+    // Example text buttons
+    document.querySelectorAll('.use-example').forEach(button => {
+        button.addEventListener('click', function() {
+            document.getElementById('text-input').value = this.dataset.text;
+            updateCharCount();
+            // Add visual feedback
+            this.classList.add('btn-success');
+            setTimeout(() => {
+                this.classList.remove('btn-success');
+                this.classList.add('btn-outline-primary');
+            }, 1000);
+        });
+    });
+    
+    // Keyboard shortcuts
+    document.addEventListener('keydown', function(e) {
+        // Ctrl/Cmd + Enter to generate speech
+        if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') {
+            e.preventDefault();
+            document.getElementById('generate-btn').click();
+        }
+
+        // Escape to clear results
+        if (e.key === 'Escape') {
+            clearResults();
+        }
+    });
+
+    // Initialize auto-combine status
+    updateAutoCombineStatus();
+}
+
+async function loadVoices() {
+    try {
+        // Prepare headers for API key if available (OpenAI compatible format)
+        const headers = {};
+        const apiKeyInput = document.getElementById('api-key-input');
+        if (apiKeyInput && apiKeyInput.value.trim()) {
+            headers['Authorization'] = `Bearer ${apiKeyInput.value.trim()}`;
+        }
+
+        const response = await fetch('/api/voices', { headers });
+        const data = await response.json();
+        
+        const select = document.getElementById('voice-select');
+        select.innerHTML = '';
+        
+        data.voices.forEach(voice => {
+            const option = document.createElement('option');
+            option.value = voice.id;
+            option.textContent = `${voice.name} - ${voice.description}`;
+            select.appendChild(option);
+        });
+        
+        // Select default voice
+        select.value = 'alloy';
+        
+    } catch (error) {
+        console.error('Failed to load voices:', error);
+        console.log('Failed to load voices. Please refresh the page.');
+    }
+}
+
+async function loadFormats() {
+    try {
+        // Prepare headers for API key if available (OpenAI compatible format)
+        const headers = {};
+        const apiKeyInput = document.getElementById('api-key-input');
+        if (apiKeyInput && apiKeyInput.value.trim()) {
+            headers['Authorization'] = `Bearer ${apiKeyInput.value.trim()}`;
+        }
+
+        const response = await fetch('/api/formats', { headers });
+        const data = await response.json();
+
+        const select = document.getElementById('format-select');
+        select.innerHTML = '';
+
+        data.formats.forEach(format => {
+            const option = document.createElement('option');
+            option.value = format.id;
+            option.textContent = `${format.name} - ${format.description}`;
+            select.appendChild(option);
+        });
+
+        // Select default format
+        select.value = 'mp3';
+        updateFormatInfo();
+
+    } catch (error) {
+        console.error('Failed to load formats:', error);
+        console.log('Failed to load formats. Please refresh the page.');
+    }
+}
+
+function updateCharCount() {
+    const textInput = document.getElementById('text-input');
+    const maxLengthInput = document.getElementById('max-length-input');
+    const charCountElement = document.getElementById('char-count');
+
+    if (!textInput || !maxLengthInput || !charCountElement) {
+        console.warn('Required elements not found for updateCharCount');
+        return;
+    }
+
+    const text = textInput.value;
+    const maxLength = parseInt(maxLengthInput.value) || 4096;
+    const charCount = text.length;
+
+    charCountElement.textContent = charCount.toLocaleString();
+    
+    // Update length status with better visual feedback
+    const statusElement = document.getElementById('length-status');
+    if (statusElement) {
+        const percentage = (charCount / maxLength) * 100;
+
+        if (charCount > maxLength) {
+            statusElement.innerHTML = '<span class="badge bg-danger"><i class="fas fa-exclamation-triangle me-1"></i>Exceeds limit</span>';
+        } else if (percentage > 80) {
+            statusElement.innerHTML = '<span class="badge bg-warning"><i class="fas fa-exclamation me-1"></i>Near limit</span>';
+        } else if (percentage > 50) {
+            statusElement.innerHTML = '<span class="badge bg-info"><i class="fas fa-info me-1"></i>Good</span>';
+        } else {
+            statusElement.innerHTML = '<span class="badge bg-success"><i class="fas fa-check me-1"></i>OK</span>';
+        }
+    }
+    
+    updateGenerateButton();
+    updateAutoCombineStatus();
+}
+
+function updateGenerateButton() {
+    const text = document.getElementById('text-input').value;
+    const maxLength = parseInt(document.getElementById('max-length-input').value) || 4096;
+    const autoCombineCheck = document.getElementById('auto-combine-check');
+    const autoCombine = autoCombineCheck ? autoCombineCheck.checked : false;
+    const generateBtn = document.getElementById('generate-btn');
+
+    if (!generateBtn) {
+        console.warn('Generate button not found');
+        return;
+    }
+
+    const btnText = generateBtn.querySelector('.btn-text');
+
+    if (!btnText) {
+        console.warn('Button text element not found');
+        return;
+    }
+
+    if (text.length > maxLength && autoCombine) {
+        btnText.innerHTML = '<i class="fas fa-magic me-2"></i>Generate Speech (Auto-Combine)';
+        generateBtn.classList.add('btn-warning');
+        generateBtn.classList.remove('btn-primary');
+    } else {
+        btnText.innerHTML = '<i class="fas fa-magic me-2"></i>Generate Speech';
+        generateBtn.classList.add('btn-primary');
+        generateBtn.classList.remove('btn-warning');
+    }
+}
+
+async function validateText() {
+    const text = document.getElementById('text-input').value.trim();
+    const maxLength = parseInt(document.getElementById('max-length-input').value) || 4096;
+    
+    if (!text) {
+        console.log('Please enter some text to validate');
+        return;
+    }
+    
+    const validateBtn = document.getElementById('validate-text-btn');
+    setLoading(validateBtn, true);
+    
+    try {
+        const response = await fetch('/api/validate-text', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ text, max_length: maxLength })
+        });
+        
+        const data = await response.json();
+        const resultDiv = document.getElementById('validation-result');
+        
+        if (data.is_valid) {
+            resultDiv.innerHTML = `
+                <div class="alert alert-success fade-in">
+                    <i class="fas fa-check-circle me-2"></i>
+                    <strong>Text is valid!</strong> (${data.text_length.toLocaleString()} characters)
+                    <div class="progress progress-custom mt-2">
+                        <div class="progress-bar-custom" style="width: ${(data.text_length / data.max_length) * 100}%"></div>
+                    </div>
+                </div>
+            `;
+        } else {
+            resultDiv.innerHTML = `
+                <div class="alert alert-warning fade-in">
+                    <i class="fas fa-exclamation-triangle me-2"></i>
+                    <strong>Text exceeds limit!</strong> (${data.text_length.toLocaleString()}/${data.max_length.toLocaleString()} characters)
+                    <br><small class="mt-2 d-block">Suggested chunks: ${data.suggested_chunks}</small>
+                    <div class="mt-3">
+                        <strong>Preview of chunks:</strong>
+                        <div class="mt-2">
+                            ${data.chunk_preview.map((chunk, i) => `
+                                <div class="border rounded p-2 mb-2 bg-light">
+                                    <small class="text-muted">Chunk ${i+1}:</small>
+                                    <div class="small">${chunk}</div>
+                                </div>
+                            `).join('')}
+                        </div>
+
+                    </div>
+                </div>
+            `;
+        }
+        
+        resultDiv.classList.remove('d-none');
+        resultDiv.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+        
+    } catch (error) {
+        console.error('Validation failed:', error);
+        console.log('Failed to validate text. Please try again.');
+    } finally {
+        setLoading(validateBtn, false);
+    }
+}
+
+
+
+function updateAutoCombineStatus() {
+    const autoCombineCheck = document.getElementById('auto-combine-check');
+    const statusBadge = document.getElementById('auto-combine-status');
+    const textInput = document.getElementById('text-input');
+    const maxLength = parseInt(document.getElementById('max-length-input').value) || 4096;
+
+    if (!autoCombineCheck || !statusBadge) return;
+
+    const isAutoCombineEnabled = autoCombineCheck.checked;
+    const textLength = textInput.value.length;
+    const isLongText = textLength > maxLength;
+
+    // Show/hide status badge
+    if (isAutoCombineEnabled && isLongText) {
+        statusBadge.classList.remove('d-none');
+        statusBadge.classList.add('bg-success');
+        statusBadge.classList.remove('bg-warning');
+        statusBadge.innerHTML = '<i class="fas fa-magic me-1"></i>Auto-combine enabled';
+    } else if (!isAutoCombineEnabled && isLongText) {
+        statusBadge.classList.remove('d-none');
+        statusBadge.classList.add('bg-warning');
+        statusBadge.classList.remove('bg-success');
+        statusBadge.innerHTML = '<i class="fas fa-exclamation-triangle me-1"></i>Long text detected';
+    } else {
+        statusBadge.classList.add('d-none');
+    }
+
+    // Remove the recursive call to updateCharCount() - this was causing infinite recursion
+}
+
+async function generateSpeech(event) {
+    console.log('generateSpeech function called');
+
+    // Prevent default form submission behavior
+    if (event) {
+        event.preventDefault();
+        event.stopPropagation();
+    }
+
+    const button = document.getElementById('generate-btn');
+    const audioResult = document.getElementById('audio-result');
+
+    // Get form data
+    const formData = getFormData();
+
+    if (!validateFormData(formData)) {
+        console.log('Form validation failed');
+        return false;
+    }
+
+    // Show loading state
+    setLoading(button, true);
+    clearResults();
+
+    try {
+        console.log('Starting speech generation...');
+        // Always use the unified endpoint with auto-combine
+        await generateUnifiedSpeech(formData);
+        console.log('Speech generation completed successfully');
+    } catch (error) {
+        console.error('Generation failed:', error);
+        console.log(`Failed to generate speech: ${error.message}`);
+    } finally {
+        setLoading(button, false);
+    }
+
+    return false; // Ensure form doesn't submit
+}
+
+function getFormData() {
+    return {
+        text: document.getElementById('text-input').value.trim(),
+        voice: document.getElementById('voice-select').value,
+        format: document.getElementById('format-select').value,
+        instructions: document.getElementById('instructions-input').value.trim(),
+        maxLength: parseInt(document.getElementById('max-length-input').value) || 4096,
+        validateLength: document.getElementById('validate-length-check').checked,
+        autoCombine: document.getElementById('auto-combine-check').checked,
+        apiKey: document.getElementById('api-key-input').value.trim()
+    };
+}
+
+function validateFormData(formData) {
+    if (!formData.text || !formData.voice || !formData.format) {
+        console.log('Please fill in all required fields');
+        return false;
+    }
+
+    if (formData.text.length > formData.maxLength && formData.validateLength && !formData.autoCombine) {
+        console.log(`Text is too long (${formData.text.length} characters). Enable auto-combine or reduce text length.`);
+        return false;
+    }
+
+    return true;
+}
+
+function clearResults() {
+    document.getElementById('audio-result').classList.add('d-none');
+    const batchResult = document.getElementById('batch-result');
+    if (batchResult) {
+        batchResult.classList.add('d-none');
+    }
+    document.getElementById('validation-result').classList.add('d-none');
+}
+
+// Utility functions
+function setLoading(button, loading) {
+    if (loading) {
+        button.classList.add('loading');
+        button.disabled = true;
+    } else {
+        button.classList.remove('loading');
+        button.disabled = false;
+    }
+}
+
+
+
+// New unified function using OpenAI-compatible endpoint with auto-combine
+async function generateUnifiedSpeech(formData) {
+    const audioResult = document.getElementById('audio-result');
+
+    // Prepare headers
+    const headers = { 'Content-Type': 'application/json' };
+
+    // Add API key if provided (OpenAI compatible format)
+    if (formData.apiKey) {
+        headers['Authorization'] = `Bearer ${formData.apiKey}`;
+    }
+
+    const response = await fetch('/v1/audio/speech', {
+        method: 'POST',
+        headers: headers,
+        body: JSON.stringify({
+            model: 'gpt-4o-mini-tts',
+            input: formData.text,
+            voice: formData.voice,
+            response_format: formData.format,
+            instructions: formData.instructions || undefined,
+            auto_combine: formData.autoCombine,
+            max_length: formData.maxLength
+        })
+    });
+
+    if (!response.ok) {
+        const errorData = await response.json();
+        const errorMessage = errorData.error?.message || errorData.error || `HTTP ${response.status}`;
+        throw new Error(errorMessage);
+    }
+
+    // Get audio data
+    const audioBlob = await response.blob();
+    currentAudioBlob = audioBlob;
+    currentFormat = formData.format;
+
+    // Create audio URL and setup player
+    const audioUrl = URL.createObjectURL(audioBlob);
+    const audioPlayer = document.getElementById('audio-player');
+    audioPlayer.src = audioUrl;
+
+    // Get response headers for enhanced display
+    const chunksCount = response.headers.get('X-Chunks-Combined') || '1';
+    const autoCombineUsed = response.headers.get('X-Auto-Combine') === 'true';
+    const originalLength = response.headers.get('X-Original-Text-Length');
+
+    // Use enhanced display function with new metadata
+    displayAudioResult(audioBlob, formData.format, formData.voice, formData.text, {
+        chunksCount,
+        autoCombineUsed,
+        originalLength
+    });
+
+    console.log('Speech generated successfully! Click play to listen.');
+    if (autoCombineUsed && chunksCount > 1) {
+        console.log(`Auto-combine feature combined ${chunksCount} chunks into a single audio file.`);
+    }
+
+    // Auto-play if user prefers
+    if (localStorage.getItem('autoPlay') === 'true') {
+        audioPlayer.play().catch(() => {
+            // Auto-play blocked, that's fine
+        });
+    }
+}
+
+// Legacy function for backward compatibility
+async function generateSingleSpeech(formData) {
+    // Use the new unified function
+    await generateUnifiedSpeech(formData);
+}
+
+
+
+
+
+function downloadAudio() {
+    if (!currentAudioBlob) {
+        console.log('No audio to download');
+        return;
+    }
+
+    const url = URL.createObjectURL(currentAudioBlob);
+    const timestamp = new Date().toISOString().slice(0, 19).replace(/:/g, '-');
+    downloadFromUrl(url, `ttsfm-speech-${timestamp}.${currentFormat}`);
+    URL.revokeObjectURL(url);
+}
+
+
+
+function downloadFromUrl(url, filename) {
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.style.display = 'none';
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+}
+
+// New enhanced functions
+function clearText() {
+    document.getElementById('text-input').value = '';
+    updateCharCount();
+    clearResults();
+    console.log('Text cleared successfully');
+}
+
+function loadRandomText() {
+    const randomTexts = [
+        // News & Information
+        "Breaking news: Scientists have discovered a revolutionary new method for generating incredibly natural synthetic speech using advanced neural networks and machine learning algorithms.",
+        "Weather update: Today will be partly cloudy with temperatures reaching 75 degrees Fahrenheit. Light winds from the southwest at 5 to 10 miles per hour.",
+        "Technology report: The latest advancements in artificial intelligence are revolutionizing how we interact with digital devices and services.",
+
+        // Educational & Informative
+        "The human brain contains approximately 86 billion neurons, each connected to thousands of others, creating a complex network that enables consciousness, memory, and thought.",
+        "Photosynthesis is the process by which plants convert sunlight, carbon dioxide, and water into glucose and oxygen, forming the foundation of most life on Earth.",
+        "The speed of light in a vacuum is exactly 299,792,458 meters per second, making it one of the fundamental constants of physics.",
+
+        // Creative & Storytelling
+        "Once upon a time, in a land far away, there lived a wise old wizard who could speak to the stars and understand their ancient secrets.",
+        "The mysterious lighthouse stood alone on the rocky cliff, its beacon cutting through the fog like a sword of light, guiding lost ships safely home.",
+        "In the depths of the enchanted forest, where sunbeams danced through emerald leaves, a young adventurer discovered a hidden path to destiny.",
+
+        // Business & Professional
+        "Our quarterly results demonstrate strong growth across all market segments, with revenue increasing by 23% compared to the same period last year.",
+        "The new product launch exceeded expectations, capturing 15% market share within the first six months and establishing our brand as an industry leader.",
+        "We are committed to sustainable business practices that benefit our customers, employees, and the environment for generations to come.",
+
+        // Technical & Programming
+        "The TTSFM package provides a comprehensive API for text-to-speech generation with support for multiple voices and audio formats.",
+        "Machine learning algorithms process vast amounts of data to identify patterns and make predictions with remarkable accuracy.",
+        "Cloud computing has transformed how businesses store, process, and access their data, enabling scalability and flexibility like never before.",
+
+        // Conversational & Casual
+        "Welcome to TTSFM! Experience the future of text-to-speech technology with our premium AI voices.",
+        "Good morning! Today is a beautiful day to learn something new and explore the possibilities of text-to-speech technology.",
+        "Have you ever wondered what it would be like if your computer could speak with perfect human-like intonation and emotion?"
+    ];
+
+    const randomText = randomTexts[Math.floor(Math.random() * randomTexts.length)];
+    document.getElementById('text-input').value = randomText;
+    updateCharCount();
+    console.log('Random text loaded successfully');
+}
+
+
+
+function resetForm() {
+    // Reset form to default values
+    document.getElementById('text-input').value = 'Welcome to TTSFM! Experience the future of text-to-speech technology with our premium AI voices. Generate natural, expressive speech for any application.';
+    document.getElementById('voice-select').value = 'alloy';
+    document.getElementById('format-select').value = 'mp3';
+    document.getElementById('instructions-input').value = '';
+    document.getElementById('max-length-input').value = '4096';
+    document.getElementById('validate-length-check').checked = true;
+    const autoCombineCheck = document.getElementById('auto-combine-check');
+    if (autoCombineCheck) {
+        autoCombineCheck.checked = true;
+    }
+
+    updateCharCount();
+    updateGenerateButton();
+    clearResults();
+    console.log('Form reset to default values');
+}
+
+function replayAudio() {
+    const audioPlayer = document.getElementById('audio-player');
+    if (audioPlayer && audioPlayer.src) {
+        audioPlayer.currentTime = 0;
+        audioPlayer.play().catch(() => {
+            console.log('Unable to replay audio. Please check your browser settings.');
+        });
+    }
+}
+
+function shareAudio() {
+    if (navigator.share && currentAudioBlob) {
+        const file = new File([currentAudioBlob], `ttsfm-speech.${currentFormat}`, {
+            type: `audio/${currentFormat}`
+        });
+
+        navigator.share({
+            title: 'TTSFM Generated Speech',
+            text: 'Check out this speech generated with TTSFM!',
+            files: [file]
+        }).catch(() => {
+            // Fallback to copying link
+            copyAudioLink();
+        });
+    } else {
+        copyAudioLink();
+    }
+}
+
+function copyAudioLink() {
+    const audioPlayer = document.getElementById('audio-player');
+    if (audioPlayer && audioPlayer.src) {
+        navigator.clipboard.writeText(audioPlayer.src).then(() => {
+            console.log('Audio link copied to clipboard!');
+        }).catch(() => {
+            console.log('Unable to copy link. Please try downloading the audio instead.');
+        });
+    }
+}
+
+function updateVoiceInfo() {
+    const voiceSelect = document.getElementById('voice-select');
+    const previewBtn = document.getElementById('preview-voice-btn');
+
+    if (voiceSelect.value) {
+        previewBtn.disabled = false;
+        previewBtn.onclick = () => previewVoice(voiceSelect.value);
+    } else {
+        previewBtn.disabled = true;
+    }
+}
+
+function updateFormatInfo() {
+    const formatSelect = document.getElementById('format-select');
+    const formatInfo = document.getElementById('format-info');
+
+    const formatDescriptions = {
+        'mp3': '🎵 MP3 - Good quality, small file size. Best for web and general use.',
+        'opus': '📻 OPUS - Excellent quality, small file size. Best for streaming and VoIP.',
+        'aac': '📱 AAC - Good quality, medium file size. Best for Apple devices and streaming.',
+        'flac': '💿 FLAC - Lossless quality, large file size. Best for archival and high-quality audio.',
+        'wav': '🎧 WAV - Lossless quality, large file size. Best for professional audio production.',
+        'pcm': '🔊 PCM - Raw audio data, large file size. Best for audio processing.'
+    };
+
+    if (formatInfo && formatSelect.value) {
+        formatInfo.textContent = formatDescriptions[formatSelect.value] || 'High-quality audio format';
+    }
+}
+
+function previewVoice(voiceId) {
+    // This would typically play a short preview of the voice
+    console.log(`Voice preview for ${voiceId} - Feature coming soon!`);
+}
+
+// Enhanced audio result display with auto-combine metadata
+function displayAudioResult(audioBlob, format, voice, text, metadata = {}) {
+    const audioResult = document.getElementById('audio-result');
+    const audioPlayer = document.getElementById('audio-player');
+    const audioInfo = document.getElementById('audio-info');
+
+    // Create audio URL and setup player
+    const audioUrl = URL.createObjectURL(audioBlob);
+    audioPlayer.src = audioUrl;
+
+    // Update audio stats
+    const sizeKB = (audioBlob.size / 1024).toFixed(1);
+    document.getElementById('audio-size').textContent = `${sizeKB} KB`;
+    document.getElementById('audio-format').textContent = format.toUpperCase();
+    document.getElementById('audio-voice').textContent = voice.charAt(0).toUpperCase() + voice.slice(1);
+
+    // Update audio info safely without innerHTML
+    // Clear existing content
+    audioInfo.textContent = '';
+
+    // Create and append icon element
+    const icon = document.createElement('i');
+    icon.className = 'fas fa-check-circle text-success me-1';
+    audioInfo.appendChild(icon);
+
+    // Create info text with auto-combine details
+    let infoText = `Generated successfully • ${sizeKB} KB • ${format.toUpperCase()}`;
+
+    if (metadata.autoCombineUsed && metadata.chunksCount > 1) {
+        infoText += ` • Auto-combined ${metadata.chunksCount} chunks`;
+
+        // Add a special badge for auto-combine
+        const badge = document.createElement('span');
+        badge.className = 'badge bg-primary ms-2';
+        badge.innerHTML = '<i class="fas fa-magic me-1"></i>Auto-combined';
+        audioInfo.appendChild(document.createTextNode(infoText));
+        audioInfo.appendChild(badge);
+    } else {
+        // Create and append text content (safely escaped)
+        const textNode = document.createTextNode(infoText);
+        audioInfo.appendChild(textNode);
+    }
+
+    // Show result with animation
+    audioResult.classList.remove('d-none');
+    audioResult.classList.add('fade-in');
+
+    // Update duration when metadata loads
+    audioPlayer.addEventListener('loadedmetadata', function() {
+        const duration = Math.round(audioPlayer.duration);
+        document.getElementById('audio-duration').textContent = `${duration}s`;
+    }, { once: true });
+
+    // Scroll to result
+    audioResult.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+}
+
+// API Key visibility toggle function
+function toggleApiKeyVisibility() {
+    const apiKeyInput = document.getElementById('api-key-input');
+    const eyeIcon = document.getElementById('api-key-eye-icon');
+
+    if (apiKeyInput.type === 'password') {
+        apiKeyInput.type = 'text';
+        eyeIcon.className = 'fas fa-eye-slash';
+    } else {
+        apiKeyInput.type = 'password';
+        eyeIcon.className = 'fas fa-eye';
+    }
+}
+
+// Export functions for use in HTML
+window.clearText = clearText;
+window.loadRandomText = loadRandomText;
+window.resetForm = resetForm;
+window.toggleApiKeyVisibility = toggleApiKeyVisibility;

static/js/websocket-tts.js

@@ -0,0 +1,366 @@
+/**
+ * WebSocket TTS Streaming Client
+ * 
+ * Because apparently HTTP requests are so 2023.
+ * Now we need real-time streaming for everything.
+ */
+
+class WebSocketTTSClient {
+    constructor(options = {}) {
+        this.socketUrl = options.socketUrl || window.location.origin;
+        this.socket = null;
+        this.activeRequests = new Map();
+        this.reconnectAttempts = 0;
+        this.maxReconnectAttempts = options.maxReconnectAttempts || 5;
+        this.reconnectDelay = options.reconnectDelay || 1000;
+        this.debug = options.debug || false;
+        
+        // Audio context for seamless playback
+        this.audioContext = null;
+        this.audioQueue = new Map(); // request_id -> audio chunks
+        
+        // Event handlers
+        this.onConnect = options.onConnect || (() => {});
+        this.onDisconnect = options.onDisconnect || (() => {});
+        this.onError = options.onError || ((error) => console.error('WebSocket error:', error));
+        
+        // Initialize
+        this.connect();
+    }
+    
+    connect() {
+        if (this.socket && this.socket.connected) {
+            this.log('Already connected');
+            return;
+        }
+        
+        this.log('Connecting to WebSocket server...');
+        
+        // Initialize Socket.IO connection
+        this.socket = io(this.socketUrl, {
+            transports: ['websocket', 'polling'],
+            reconnection: true,
+            reconnectionAttempts: this.maxReconnectAttempts,
+            reconnectionDelay: this.reconnectDelay
+        });
+        
+        // Set up event handlers
+        this.setupEventHandlers();
+    }
+    
+    setupEventHandlers() {
+        // Connection events
+        this.socket.on('connect', () => {
+            this.log('Connected to WebSocket server');
+            this.reconnectAttempts = 0;
+            this.onConnect();
+        });
+        
+        this.socket.on('disconnect', (reason) => {
+            this.log('Disconnected from WebSocket server:', reason);
+            this.onDisconnect(reason);
+        });
+        
+        this.socket.on('connect_error', (error) => {
+            this.log('Connection error:', error);
+            this.reconnectAttempts++;
+            this.onError({
+                type: 'connection_error',
+                message: error.message,
+                attempts: this.reconnectAttempts
+            });
+        });
+        
+        // TTS streaming events
+        this.socket.on('connected', (data) => {
+            this.log('Session established:', data.session_id);
+        });
+        
+        this.socket.on('stream_started', (data) => {
+            this.log('Stream started:', data.request_id);
+            const request = this.activeRequests.get(data.request_id);
+            if (request && request.onStart) {
+                request.onStart(data);
+            }
+        });
+        
+        this.socket.on('audio_chunk', (data) => {
+            this.handleAudioChunk(data);
+        });
+        
+        this.socket.on('stream_progress', (data) => {
+            this.handleProgress(data);
+        });
+        
+        this.socket.on('stream_complete', (data) => {
+            this.handleStreamComplete(data);
+        });
+        
+        this.socket.on('stream_error', (data) => {
+            this.handleStreamError(data);
+        });
+    }
+    
+    /**
+     * Generate speech with real-time streaming
+     */
+    generateSpeech(text, options = {}) {
+        return new Promise((resolve, reject) => {
+            if (!this.socket || !this.socket.connected) {
+                reject(new Error('WebSocket not connected'));
+                return;
+            }
+            
+            const requestId = this.generateRequestId();
+            const audioChunks = [];
+            
+            // Store request info
+            this.activeRequests.set(requestId, {
+                resolve,
+                reject,
+                audioChunks,
+                options,
+                startTime: Date.now(),
+                onStart: options.onStart,
+                onProgress: options.onProgress,
+                onChunk: options.onChunk,
+                onComplete: options.onComplete,
+                onError: options.onError
+            });
+            
+            // Initialize audio queue for this request
+            this.audioQueue.set(requestId, []);
+            
+            // Emit generation request
+            this.socket.emit('generate_stream', {
+                request_id: requestId,
+                text: text,
+                voice: options.voice || 'alloy',
+                format: options.format || 'mp3',
+                chunk_size: options.chunkSize || 1024
+            });
+            
+            this.log('Requested speech generation:', requestId);
+        });
+    }
+    
+    handleAudioChunk(data) {
+        const request = this.activeRequests.get(data.request_id);
+        if (!request) {
+            this.log('Received chunk for unknown request:', data.request_id);
+            return;
+        }
+        
+        // Convert hex string back to binary
+        const audioData = this.hexToArrayBuffer(data.audio_data);
+        
+        // Store chunk
+        request.audioChunks.push({
+            index: data.chunk_index,
+            data: audioData,
+            duration: data.duration,
+            format: data.format
+        });
+        
+        // Add to audio queue for streaming playback
+        const queue = this.audioQueue.get(data.request_id);
+        if (queue) {
+            queue.push(audioData);
+        }
+        
+        // Call chunk handler if provided
+        if (request.onChunk) {
+            request.onChunk({
+                chunkIndex: data.chunk_index,
+                totalChunks: data.total_chunks,
+                audioData: audioData,
+                duration: data.duration,
+                text: data.chunk_text
+            });
+        }
+        
+        this.log(`Received chunk ${data.chunk_index + 1}/${data.total_chunks} for request ${data.request_id}`);
+    }
+    
+    handleProgress(data) {
+        const request = this.activeRequests.get(data.request_id);
+        if (request && request.onProgress) {
+            request.onProgress({
+                progress: data.progress,
+                chunksCompleted: data.chunks_completed,
+                totalChunks: data.total_chunks,
+                status: data.status
+            });
+        }
+    }
+    
+    handleStreamComplete(data) {
+        const request = this.activeRequests.get(data.request_id);
+        if (!request) {
+            this.log('Completion for unknown request:', data.request_id);
+            return;
+        }
+        
+        // Sort chunks by index
+        request.audioChunks.sort((a, b) => a.index - b.index);
+        
+        // Combine all audio chunks
+        const combinedAudio = this.combineAudioChunks(request.audioChunks);
+        
+        const result = {
+            requestId: data.request_id,
+            audioData: combinedAudio,
+            chunks: request.audioChunks,
+            duration: request.audioChunks.reduce((sum, chunk) => sum + chunk.duration, 0),
+            generationTime: Date.now() - request.startTime,
+            format: request.audioChunks[0]?.format || 'mp3'
+        };
+        
+        // Call complete handler
+        if (request.onComplete) {
+            request.onComplete(result);
+        }
+        
+        // Resolve promise
+        request.resolve(result);
+        
+        // Cleanup
+        this.activeRequests.delete(data.request_id);
+        this.audioQueue.delete(data.request_id);
+        
+        this.log('Stream completed:', data.request_id);
+    }
+    
+    handleStreamError(data) {
+        const request = this.activeRequests.get(data.request_id);
+        if (!request) {
+            this.log('Error for unknown request:', data.request_id);
+            return;
+        }
+        
+        const error = new Error(data.error);
+        error.requestId = data.request_id;
+        error.timestamp = data.timestamp;
+        
+        // Call error handler
+        if (request.onError) {
+            request.onError(error);
+        }
+        
+        // Reject promise
+        request.reject(error);
+        
+        // Cleanup
+        this.activeRequests.delete(data.request_id);
+        this.audioQueue.delete(data.request_id);
+        
+        this.log('Stream error:', data.request_id, data.error);
+    }
+    
+    /**
+     * Cancel an active stream
+     */
+    cancelStream(requestId) {
+        if (!this.socket || !this.socket.connected) {
+            throw new Error('WebSocket not connected');
+        }
+        
+        this.socket.emit('cancel_stream', { request_id: requestId });
+        
+        // Clean up local state
+        const request = this.activeRequests.get(requestId);
+        if (request) {
+            request.reject(new Error('Stream cancelled by user'));
+            this.activeRequests.delete(requestId);
+            this.audioQueue.delete(requestId);
+        }
+    }
+    
+    /**
+     * Combine audio chunks into a single buffer
+     */
+    combineAudioChunks(chunks) {
+        if (chunks.length === 0) return new ArrayBuffer(0);
+        
+        // Calculate total size
+        const totalSize = chunks.reduce((sum, chunk) => sum + chunk.data.byteLength, 0);
+        
+        // Create combined buffer
+        const combined = new ArrayBuffer(totalSize);
+        const view = new Uint8Array(combined);
+        
+        let offset = 0;
+        for (const chunk of chunks) {
+            view.set(new Uint8Array(chunk.data), offset);
+            offset += chunk.data.byteLength;
+        }
+        
+        return combined;
+    }
+    
+    /**
+     * Play audio directly (experimental streaming playback)
+     */
+    async playAudioStream(requestId) {
+        if (!this.audioContext) {
+            this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
+        }
+        
+        const queue = this.audioQueue.get(requestId);
+        if (!queue) {
+            throw new Error('No audio queue found for request');
+        }
+        
+        // This is a simplified version - real implementation would need
+        // proper audio decoding and buffering for seamless playback
+        this.log('Streaming audio playback not fully implemented yet');
+    }
+    
+    /**
+     * Utility functions
+     */
+    hexToArrayBuffer(hex) {
+        const bytes = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < hex.length; i += 2) {
+            bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+        }
+        return bytes.buffer;
+    }
+    
+    generateRequestId() {
+        return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    
+    log(...args) {
+        if (this.debug) {
+            console.log('[WebSocketTTS]', ...args);
+        }
+    }
+    
+    /**
+     * Get connection status
+     */
+    isConnected() {
+        return this.socket && this.socket.connected;
+    }
+    
+    /**
+     * Disconnect from server
+     */
+    disconnect() {
+        if (this.socket) {
+            this.socket.disconnect();
+            this.socket = null;
+        }
+        
+        // Clear all active requests
+        for (const [requestId, request] of this.activeRequests) {
+            request.reject(new Error('Client disconnected'));
+        }
+        this.activeRequests.clear();
+        this.audioQueue.clear();
+    }
+}
+
+// Export for use
+window.WebSocketTTSClient = WebSocketTTSClient;

templates/base.html

@@ -0,0 +1,363 @@
+<!DOCTYPE html>
+<html lang="{{ get_locale() }}">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block title %}TTSFM - {{ _('nav.home') }}{% endblock %}</title>
+    
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
+    
+    <!-- Font Awesome -->
+    <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css" rel="stylesheet">
+
+    <!-- Google Fonts -->
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+
+    <!-- Custom CSS -->
+    <link href="{{ url_for('static', filename='css/style.css') }}" rel="stylesheet">
+
+    <!-- Additional Performance Optimizations -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+
+    <!-- Favicon -->
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🎤</text></svg>">
+
+    <!-- Meta tags for better SEO and social sharing -->
+    <meta name="description" content="TTSFM - A Python client for text-to-speech APIs. Simple to use with support for multiple voices and audio formats.">
+    <meta name="keywords" content="text-to-speech, TTS, python, API, voice synthesis, audio generation">
+    <meta name="author" content="TTSFM">
+
+    <!-- Open Graph / Facebook -->
+    <meta property="og:type" content="website">
+    <meta property="og:url" content="{{ request.url }}">
+    <meta property="og:title" content="{% block og_title %}TTSFM - Python Text-to-Speech Client{% endblock %}">
+    <meta property="og:description" content="A Python client for text-to-speech APIs. Simple to use with support for multiple voices and audio formats.">
+
+    <!-- Twitter -->
+    <meta property="twitter:card" content="summary">
+    <meta property="twitter:url" content="{{ request.url }}">
+    <meta property="twitter:title" content="{% block twitter_title %}TTSFM - Python Text-to-Speech Client{% endblock %}">
+    <meta property="twitter:description" content="A Python client for text-to-speech APIs. Simple to use with support for multiple voices and audio formats.">
+    
+    {% block extra_css %}{% endblock %}
+
+    <!-- Language button styling -->
+    <style>
+        /* Language dropdown button styling */
+        #languageDropdown {
+            border-color: #6c757d;
+            color: #6c757d;
+            transition: all 0.2s ease-in-out;
+            font-size: 0.875rem;
+        }
+
+        #languageDropdown:hover {
+            border-color: #495057;
+            color: #495057;
+            background-color: #f8f9fa;
+        }
+
+        #languageDropdown:focus {
+            box-shadow: 0 0 0 0.2rem rgba(108, 117, 125, 0.25);
+        }
+
+        /* Responsive language button */
+        @media (max-width: 576px) {
+            #languageDropdown {
+                font-size: 0.75rem;
+                padding: 0.25rem 0.5rem;
+            }
+        }
+
+        /* Ensure consistent button heights */
+        .navbar-nav .btn {
+            display: inline-flex;
+            align-items: center;
+        }
+    </style>
+</head>
+<body>
+    <!-- Skip to content link for accessibility -->
+    <a href="#main-content" class="skip-link">Skip to main content</a>
+
+    <!-- Clean Navigation -->
+    <nav class="navbar navbar-expand-lg fixed-top" style="background-color: rgba(255, 255, 255, 0.95); backdrop-filter: blur(10px); border-bottom: 1px solid #e5e7eb;">
+        <div class="container">
+            <a class="navbar-brand" href="{{ url_for('index') }}">
+                <i class="fas fa-microphone-alt me-2"></i>
+                <span class="fw-bold">TTSFM</span>
+                <span class="badge bg-primary ms-2 small">v3.2.2</span>
+            </a>
+
+            <button class="navbar-toggler border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
+                <span class="navbar-toggler-icon"></span>
+            </button>
+
+            <div class="collapse navbar-collapse" id="navbarNav">
+                <ul class="navbar-nav me-auto">
+                    <li class="nav-item">
+                        <a class="nav-link" href="{{ url_for('index') }}" aria-label="{{ _('nav.home') }}">
+                            <i class="fas fa-home me-1"></i>{{ _('nav.home') }}
+                        </a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link" href="{{ url_for('playground') }}" aria-label="{{ _('nav.playground') }}">
+                            <i class="fas fa-play me-1"></i>{{ _('nav.playground') }}
+                        </a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link" href="{{ url_for('docs') }}" aria-label="{{ _('nav.documentation') }}">
+                            <i class="fas fa-book me-1"></i>{{ _('nav.documentation') }}
+                        </a>
+                    </li>
+                </ul>
+
+                <ul class="navbar-nav">
+                    <li class="nav-item">
+                        <span class="navbar-text d-flex align-items-center">
+                            <span id="status-indicator" class="status-indicator status-offline" aria-hidden="true"></span>
+                            <span id="status-text" class="small">{{ _('nav.status_checking') }}</span>
+                        </span>
+                    </li>
+                    <li class="nav-item dropdown ms-3">
+                        <button class="btn btn-outline-secondary btn-sm dropdown-toggle" type="button" id="languageDropdown" data-bs-toggle="dropdown" aria-expanded="false" title="{{ _('common.language') }}">
+                            {% if get_locale() == 'zh' %}🇨🇳 中文{% else %}🇺🇸 English{% endif %}
+                        </button>
+                        <ul class="dropdown-menu" aria-labelledby="languageDropdown">
+                            {% for lang_code, lang_name in get_supported_languages().items() %}
+                            <li>
+                                <a class="dropdown-item{% if get_locale() == lang_code %} active{% endif %}"
+                                   href="{{ url_for('set_language', lang_code=lang_code) }}">
+                                    {% if lang_code == 'en' %}🇺🇸{% elif lang_code == 'zh' %}🇨🇳{% endif %} {{ lang_name }}
+                                </a>
+                            </li>
+                            {% endfor %}
+                        </ul>
+                    </li>
+                    <li class="nav-item ms-3">
+                        <a class="btn btn-outline-primary btn-sm" href="https://github.com/dbccccccc/ttsfm" target="_blank" rel="noopener noreferrer" aria-label="{{ _('nav.github') }}">
+                            <i class="fab fa-github me-1"></i>{{ _('nav.github') }}
+                        </a>
+                    </li>
+                </ul>
+            </div>
+        </div>
+    </nav>
+
+    <!-- Main Content -->
+    <main id="main-content" style="padding-top: 76px;">
+        {% block content %}{% endblock %}
+    </main>
+
+    <!-- Simplified Footer -->
+    <footer class="footer py-3" style="background-color: #f9fafb; border-top: 1px solid #e5e7eb;" role="contentinfo">
+        <div class="container">
+            <div class="row align-items-center">
+                <div class="col-md-6">
+                    <div class="d-flex align-items-center">
+                        <i class="fas fa-microphone-alt me-2 text-primary"></i>
+                        <strong class="text-dark">TTSFM</strong>
+                        <span class="ms-2 text-muted">v3.2.2</span>
+                    </div>
+                </div>
+                <div class="col-md-6 text-md-end">
+                    <small class="text-muted">
+                        {{ _('home.footer_copyright') }} •
+                        <a href="{{ url_for('docs') }}" class="text-decoration-none text-muted">{{ _('nav.documentation') }}</a> •
+                        <a href="https://github.com/dbccccccc/ttsfm" class="text-decoration-none text-muted" target="_blank">{{ _('nav.github') }}</a>
+                    </small>
+                </div>
+            </div>
+        </div>
+    </footer>
+
+    <!-- Bootstrap JS -->
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js"></script>
+
+    <!-- Internationalization Support -->
+    <script src="{{ url_for('static', filename='js/i18n.js') }}"></script>
+
+    <!-- Enhanced Common JavaScript -->
+    <script>
+        // Enhanced service status checking
+        async function checkStatus() {
+            try {
+                const response = await fetch('/api/health');
+                const data = await response.json();
+
+                const indicator = document.getElementById('status-indicator');
+                const text = document.getElementById('status-text');
+
+                if (response.ok && data.status === 'healthy') {
+                    indicator.className = 'status-indicator status-online';
+                    text.textContent = '{{ _("nav.status_online") }}';
+                } else {
+                    indicator.className = 'status-indicator status-offline';
+                    text.textContent = '{{ _("nav.status_offline") }}';
+                }
+            } catch (error) {
+                const indicator = document.getElementById('status-indicator');
+                const text = document.getElementById('status-text');
+                indicator.className = 'status-indicator status-offline';
+                text.textContent = '{{ _("nav.status_offline") }}';
+            }
+        }
+
+        // Enhanced page initialization
+        document.addEventListener('DOMContentLoaded', function() {
+            // Check status immediately and periodically
+            checkStatus();
+            setInterval(checkStatus, 30000); // Check every 30 seconds
+
+            // Initialize tooltips
+            if (typeof bootstrap !== 'undefined') {
+                const tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'));
+                tooltipTriggerList.map(function (tooltipTriggerEl) {
+                    return new bootstrap.Tooltip(tooltipTriggerEl);
+                });
+            }
+
+            // Add smooth scrolling for anchor links
+            document.querySelectorAll('a[href^="#"]').forEach(anchor => {
+                anchor.addEventListener('click', function (e) {
+                    const target = document.querySelector(this.getAttribute('href'));
+                    if (target) {
+                        e.preventDefault();
+                        target.scrollIntoView({
+                            behavior: 'smooth',
+                            block: 'start'
+                        });
+                    }
+                });
+            });
+
+            // Add fade-in animation to main content
+            const mainContent = document.querySelector('main');
+            if (mainContent) {
+                mainContent.classList.add('fade-in');
+            }
+
+            // Add loading states to external links
+            document.querySelectorAll('a[target="_blank"]').forEach(link => {
+                link.addEventListener('click', function() {
+                    this.style.opacity = '0.7';
+                    setTimeout(() => {
+                        this.style.opacity = '1';
+                    }, 1000);
+                });
+            });
+        });
+
+        // Enhanced utility function to show loading state
+        function setLoading(button, loading) {
+            if (loading) {
+                button.classList.add('loading');
+                button.disabled = true;
+                button.style.cursor = 'wait';
+            } else {
+                button.classList.remove('loading');
+                button.disabled = false;
+                button.style.cursor = 'pointer';
+            }
+        }
+
+        // Enhanced utility function to show alerts
+        function showAlert(message, type = 'info', duration = 5000) {
+            const alertDiv = document.createElement('div');
+            alertDiv.className = `alert alert-${type} alert-dismissible fade show fade-in`;
+            alertDiv.style.position = 'relative';
+            alertDiv.style.zIndex = '1050';
+            alertDiv.innerHTML = `
+                <i class="fas fa-${getAlertIcon(type)} me-2"></i>
+                ${message}
+                <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
+            `;
+
+            // Find the best container to insert the alert
+            const container = document.querySelector('main .container') || document.querySelector('.container') || document.body;
+            if (container) {
+                container.insertBefore(alertDiv, container.firstChild);
+
+                // Auto-dismiss after specified duration
+                setTimeout(() => {
+                    if (alertDiv.parentNode) {
+                        alertDiv.classList.remove('show');
+                        setTimeout(() => {
+                            if (alertDiv.parentNode) {
+                                alertDiv.remove();
+                            }
+                        }, 150);
+                    }
+                }, duration);
+
+                // Scroll to alert if it's not visible
+                alertDiv.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+            }
+        }
+
+        // Helper function to get appropriate icon for alert type
+        function getAlertIcon(type) {
+            const icons = {
+                'success': 'check-circle',
+                'danger': 'exclamation-triangle',
+                'warning': 'exclamation-triangle',
+                'info': 'info-circle',
+                'primary': 'info-circle'
+            };
+            return icons[type] || 'info-circle';
+        }
+
+        // Enhanced error handling for fetch requests
+        async function safeFetch(url, options = {}) {
+            try {
+                const response = await fetch(url, options);
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                }
+                return response;
+            } catch (error) {
+                console.error('Fetch error:', error);
+                showAlert(`Network error: ${error.message}`, 'danger');
+                throw error;
+            }
+        }
+
+        // Performance monitoring
+        window.addEventListener('load', function() {
+            // Log page load time
+            const loadTime = performance.now();
+            console.log(`Page loaded in ${Math.round(loadTime)}ms`);
+
+            // Check for slow loading resources
+            if (loadTime > 3000) {
+                console.warn('Page load time is slow. Consider optimizing resources.');
+            }
+        });
+
+        // Keyboard shortcuts
+        document.addEventListener('keydown', function(e) {
+            // Alt + H for home
+            if (e.altKey && e.key === 'h') {
+                e.preventDefault();
+                window.location.href = '{{ url_for("index") }}';
+            }
+
+            // Alt + P for playground
+            if (e.altKey && e.key === 'p') {
+                e.preventDefault();
+                window.location.href = '{{ url_for("playground") }}';
+            }
+
+            // Alt + D for docs
+            if (e.altKey && e.key === 'd') {
+                e.preventDefault();
+                window.location.href = '{{ url_for("docs") }}';
+            }
+        });
+    </script>
+    
+    {% block extra_js %}{% endblock %}
+</body>
+</html>

templates/docs.html

@@ -0,0 +1,734 @@
+{% extends "base.html" %}
+
+{% block title %}TTSFM {{ _('docs.title') }}{% endblock %}
+
+{% block extra_css %}
+<style>
+    .code-block {
+        background-color: #f8f9fa;
+        border: 1px solid #e9ecef;
+        border-radius: 0.375rem;
+        padding: 1rem;
+        margin: 1rem 0;
+        overflow-x: auto;
+    }
+    
+    .endpoint-card {
+        border-left: 4px solid #007bff;
+        margin-bottom: 2rem;
+    }
+    
+    .method-badge {
+        font-size: 0.75rem;
+        padding: 0.25rem 0.5rem;
+        border-radius: 0.25rem;
+        font-weight: bold;
+        margin-right: 0.5rem;
+    }
+    
+    .method-get { background-color: #28a745; color: white; }
+    .method-post { background-color: #007bff; color: white; }
+    .method-put { background-color: #ffc107; color: black; }
+    .method-delete { background-color: #dc3545; color: white; }
+    
+    .response-example {
+        background-color: #f1f3f4;
+        border-radius: 0.375rem;
+        padding: 1rem;
+        margin-top: 1rem;
+    }
+    
+    .toc {
+        position: sticky;
+        top: 2rem;
+        max-height: calc(100vh - 4rem);
+        overflow-y: auto;
+    }
+    
+    .toc a {
+        color: #6c757d;
+        text-decoration: none;
+        display: block;
+        padding: 0.25rem 0;
+        border-left: 2px solid transparent;
+        padding-left: 1rem;
+    }
+    
+    .toc a:hover, .toc a.active {
+        color: #007bff;
+        border-left-color: #007bff;
+    }
+</style>
+{% endblock %}
+
+{% block content %}
+<div class="container py-5">
+    <div class="row">
+        <div class="col-12 text-center mb-5">
+            <h1 class="display-4 fw-bold">
+                <i class="fas fa-book me-3 text-primary"></i>{{ _('docs.title') }}
+            </h1>
+            <p class="lead text-muted">
+                {{ _('docs.subtitle') }}
+            </p>
+        </div>
+    </div>
+    
+    <div class="row">
+        <!-- Table of Contents -->
+        <div class="col-lg-3">
+            <div class="toc">
+                <h5 class="fw-bold mb-3">{{ _('docs.contents') }}</h5>
+                <a href="#overview">{{ _('docs.overview') }}</a>
+                <a href="#authentication">{{ _('docs.authentication') }}</a>
+                <a href="#text-validation">{{ _('docs.text_validation') }}</a>
+                <a href="#endpoints">{{ _('docs.endpoints') }}</a>
+                <a href="#voices">{{ _('docs.voices') }}</a>
+                <a href="#formats">{{ _('docs.formats') }}</a>
+                <a href="#generate">{{ _('docs.generate') }}</a>
+                <a href="#combined">{{ _('docs.combined') }}</a>
+                <a href="#status">{{ _('docs.status') }}</a>
+                <a href="#errors">{{ _('docs.errors') }}</a>
+                <a href="#examples">{{ _('docs.examples') }}</a>
+                <a href="#python-package">{{ _('docs.python_package') }}</a>
+                <a href="#websocket">WebSocket Streaming</a>
+            </div>
+        </div>
+        
+        <!-- Documentation Content -->
+        <div class="col-lg-9">
+            <!-- Overview -->
+            <section id="overview" class="mb-5">
+                <h2 class="fw-bold mb-3">{{ _('docs.overview_title') }}</h2>
+                <p>
+                    {{ _('docs.overview_desc') }}
+                </p>
+
+                <div class="alert alert-info">
+                    <i class="fas fa-info-circle me-2"></i>
+                    <strong>{{ _('docs.base_url') }}</strong> <code>{{ request.url_root }}api/</code>
+                </div>
+
+                <h4>{{ _('docs.key_features') }}</h4>
+                <ul>
+                    <li><strong>🎤 {{ _('docs.feature_voices') }}</strong></li>
+                    <li><strong>🎵 {{ _('docs.feature_formats') }}</strong></li>
+                    <li><strong>🤖 {{ _('docs.feature_openai') }}</strong></li>
+                    <li><strong>✨ {{ _('docs.feature_auto_combine') }}</strong></li>
+                    <li><strong>📊 {{ _('docs.feature_validation') }}</strong></li>
+                    <li><strong>📈 {{ _('docs.feature_monitoring') }}</strong></li>
+                </ul>
+
+                <div class="alert alert-success">
+                    <i class="fas fa-star me-2"></i>
+                    <strong>{{ _('docs.new_version') }}</strong> {{ _('docs.new_version_desc') }}
+                </div>
+            </section>
+            
+            <!-- Authentication -->
+            <section id="authentication" class="mb-5">
+                <h2 class="fw-bold mb-3">{{ _('docs.authentication_title') }}</h2>
+                <p>
+                    {{ _('docs.authentication_desc') }}
+                </p>
+
+                <div class="code-block">
+                    <pre><code>Authorization: Bearer YOUR_API_KEY</code></pre>
+                </div>
+            </section>
+
+            <!-- Text Validation -->
+            <section id="text-validation" class="mb-5">
+                <h2 class="fw-bold mb-3">{{ _('docs.text_validation_title') }}</h2>
+                <p>
+                    {{ _('docs.text_validation_desc') }}
+                </p>
+
+                <div class="alert alert-warning">
+                    <i class="fas fa-exclamation-triangle me-2"></i>
+                    <strong>{{ _('docs.important') }}</strong> {{ _('docs.text_validation_warning') }}
+                </div>
+
+                <h4>{{ _('docs.validation_options') }}</h4>
+                <ul>
+                    <li><code>max_length</code>: {{ _('docs.max_length_option') }}</li>
+                    <li><code>validate_length</code>: {{ _('docs.validate_length_option') }}</li>
+                    <li><code>preserve_words</code>: {{ _('docs.preserve_words_option') }}</li>
+                </ul>
+            </section>
+            
+            <!-- API Endpoints -->
+            <section id="endpoints" class="mb-5">
+                <h2 class="fw-bold mb-3">{{ _('docs.endpoints_title') }}</h2>
+
+                <!-- Voices Endpoint -->
+                <div class="card endpoint-card" id="voices">
+                    <div class="card-body">
+                        <h4 class="card-title">
+                            <span class="method-badge method-get">GET</span>
+                            /api/voices
+                        </h4>
+                        <p class="card-text">{{ _('docs.get_voices_desc') }}</p>
+
+                        <h6>{{ _('docs.response_example') }}</h6>
+                        <div class="response-example">
+                            <pre><code>{
+  "voices": [
+    {
+      "id": "alloy",
+      "name": "Alloy",
+      "description": "Alloy voice"
+    },
+    {
+      "id": "echo",
+      "name": "Echo", 
+      "description": "Echo voice"
+    }
+  ],
+  "count": 6
+}</code></pre>
+                        </div>
+                    </div>
+                </div>
+                
+                <!-- Formats Endpoint -->
+                <div class="card endpoint-card" id="formats">
+                    <div class="card-body">
+                        <h4 class="card-title">
+                            <span class="method-badge method-get">GET</span>
+                            /api/formats
+                        </h4>
+                        <p class="card-text">Get available audio formats for speech generation.</p>
+
+                        <h6>Available Formats</h6>
+                        <p>We support multiple format requests, but internally:</p>
+                        <ul>
+                            <li><strong>mp3</strong> - Returns actual MP3 format</li>
+                            <li><strong>All other formats</strong> (opus, aac, flac, wav, pcm) - Mapped to WAV format</li>
+                        </ul>
+                        
+                        <div class="alert alert-info">
+                            <i class="fas fa-info-circle me-2"></i>
+                            <strong>Note:</strong> When you request opus, aac, flac, wav, or pcm, you'll receive WAV audio data.
+                        </div>
+
+                        <h6>{{ _('docs.response_example') }}</h6>
+                        <div class="response-example">
+                            <pre><code>{
+  "formats": [
+    {
+      "id": "mp3",
+      "name": "MP3",
+      "mime_type": "audio/mp3",
+      "description": "MP3 audio format"
+    },
+    {
+      "id": "opus", 
+      "name": "Opus",
+      "mime_type": "audio/wav",
+      "description": "Returns WAV format"
+    },
+    {
+      "id": "aac",
+      "name": "AAC", 
+      "mime_type": "audio/wav",
+      "description": "Returns WAV format"
+    },
+    {
+      "id": "flac",
+      "name": "FLAC",
+      "mime_type": "audio/wav", 
+      "description": "Returns WAV format"
+    },
+    {
+      "id": "wav",
+      "name": "WAV",
+      "mime_type": "audio/wav",
+      "description": "WAV audio format"
+    },
+    {
+      "id": "pcm",
+      "name": "PCM",
+      "mime_type": "audio/wav",
+      "description": "Returns WAV format"
+    }
+  ],
+  "count": 6
+}</code></pre>
+                        </div>
+                    </div>
+                </div>
+                
+                <!-- Text Validation Endpoint -->
+                <div class="card endpoint-card">
+                    <div class="card-body">
+                        <h4 class="card-title">
+                            <span class="method-badge method-post">POST</span>
+                            /api/validate-text
+                        </h4>
+                        <p class="card-text">{{ _('docs.validate_text_desc') }}</p>
+
+                        <h6>{{ _('docs.request_body') }}</h6>
+                        <div class="code-block">
+                            <pre><code>{
+  "text": "Your text to validate",
+  "max_length": 4096
+}</code></pre>
+                        </div>
+                        
+                        <h6>{{ _('docs.response_example') }}</h6>
+                        <div class="response-example">
+                            <pre><code>{
+  "text_length": 5000,
+  "max_length": 4096,
+  "is_valid": false,
+  "needs_splitting": true,
+  "suggested_chunks": 2,
+  "chunk_preview": [
+    "First chunk preview...",
+    "Second chunk preview..."
+  ]
+}</code></pre>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Generate Speech Endpoint -->
+                <div class="card endpoint-card" id="generate">
+                    <div class="card-body">
+                        <h4 class="card-title">
+                            <span class="method-badge method-post">POST</span>
+                            /api/generate
+                        </h4>
+                        <p class="card-text">{{ _('docs.generate_speech_desc') }}</p>
+
+                        <h6>{{ _('docs.request_body') }}</h6>
+                        <div class="code-block">
+                            <pre><code>{
+  "text": "Hello, world!",
+  "voice": "alloy",
+  "format": "mp3",
+  "instructions": "Speak cheerfully",
+  "max_length": 4096,
+  "validate_length": true
+}</code></pre>
+                        </div>
+                        
+                        <h6>{{ _('docs.parameters') }}</h6>
+                        <ul>
+                            <li><code>text</code> ({{ _('docs.required') }}): {{ _('docs.text_param') }}</li>
+                            <li><code>voice</code> ({{ _('docs.optional') }}): {{ _('docs.voice_param') }}</li>
+                            <li><code>format</code> ({{ _('docs.optional') }}): {{ _('docs.format_param') }}</li>
+                            <li><code>instructions</code> ({{ _('docs.optional') }}): {{ _('docs.instructions_param') }}</li>
+                            <li><code>max_length</code> ({{ _('docs.optional') }}): {{ _('docs.max_length_param') }}</li>
+                            <li><code>validate_length</code> ({{ _('docs.optional') }}): {{ _('docs.validate_length_param') }}</li>
+                        </ul>
+
+                        <h6>{{ _('docs.response') }}</h6>
+                        <p>{{ _('docs.response_audio') }}</p>
+                    </div>
+                </div>
+                
+            </section>
+
+            <!-- Python Package -->
+            <section id="python-package" class="mb-5">
+                <h3 class="fw-bold mb-4">
+                    <i class="fab fa-python me-2 text-warning"></i>{{ _('docs.python_package_title') }}
+                </h3>
+
+                <div class="card">
+                    <div class="card-body">
+                        <h5>{{ _('docs.long_text_support') }}</h5>
+                        <p>{{ _('docs.long_text_desc') }}</p>
+
+                        <div class="code-block">
+                            <pre><code>from ttsfm import TTSClient, Voice, AudioFormat
+
+# Create client
+client = TTSClient()
+
+# Generate speech from long text (automatically splits into separate files)
+responses = client.generate_speech_long_text(
+    text="Very long text that exceeds 4096 characters...",
+    voice=Voice.ALLOY,
+    response_format=AudioFormat.MP3,
+    max_length=2000,
+    preserve_words=True
+)
+
+# Save each chunk as separate files
+for i, response in enumerate(responses, 1):
+    response.save_to_file(f"part_{i:03d}.mp3")</code></pre>
+                        </div>
+
+                        <h6 class="mt-4">{{ _('docs.developer_features') }}</h6>
+                        <ul>
+                            <li><strong>{{ _('docs.manual_splitting') }}</strong></li>
+                            <li><strong>{{ _('docs.word_preservation') }}</strong></li>
+                            <li><strong>{{ _('docs.separate_files') }}</strong></li>
+                            <li><strong>{{ _('docs.cli_support') }}</strong></li>
+                        </ul>
+
+                        <div class="alert alert-info">
+                            <i class="fas fa-info-circle me-2"></i>
+                            <strong>{{ _('docs.note') }}</strong> {{ _('docs.auto_combine_note') }}
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Combined Audio Endpoints -->
+                <div class="card endpoint-card" id="combined">
+                    <div class="card-body">
+                        <h4 class="card-title">
+                            <span class="method-badge method-post">POST</span>
+                            /api/generate-combined
+                        </h4>
+                        <p class="card-text">{{ _('docs.combined_audio_desc') }}</p>
+
+                        <h6>{{ _('docs.request_body') }}</h6>
+                        <div class="code-block">
+                            <pre><code>{
+  "text": "Very long text that exceeds the limit...",
+  "voice": "alloy",
+  "format": "mp3",
+  "instructions": "Optional voice instructions",
+  "max_length": 4096,
+  "preserve_words": true
+}</code></pre>
+                        </div>
+
+                        <h6>{{ _('docs.response') }}</h6>
+                        <p>{{ _('docs.response_combined_audio') }}</p>
+
+                        <h6>{{ _('docs.response_headers') }}</h6>
+                        <ul>
+                            <li><code>X-Chunks-Combined</code>: {{ _('docs.chunks_combined_header') }}</li>
+                            <li><code>X-Original-Text-Length</code>: {{ _('docs.original_text_length_header') }}</li>
+                            <li><code>X-Audio-Size</code>: {{ _('docs.audio_size_header') }}</li>
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- OpenAI Compatible Endpoint with Auto-Combine -->
+                <div class="card endpoint-card">
+                    <div class="card-body">
+                        <h4 class="card-title">
+                            <span class="method-badge method-post">POST</span>
+                            /v1/audio/speech
+                        </h4>
+                        <p class="card-text">{{ _('docs.openai_compatible_desc') }}</p>
+
+                        <h6>{{ _('docs.request_body') }}</h6>
+                        <div class="code-block">
+                            <pre><code>{
+  "model": "gpt-4o-mini-tts",
+  "input": "Text of any length...",
+  "voice": "alloy",
+  "response_format": "mp3",
+  "instructions": "Optional voice instructions",
+  "speed": 1.0,
+  "auto_combine": true,
+  "max_length": 4096
+}</code></pre>
+                        </div>
+
+                        <h6>{{ _('docs.enhanced_parameters') }}</h6>
+                        <ul>
+                            <li><strong>auto_combine</strong> (boolean, default: true):
+                                <ul>
+                                    <li><code>true</code>: {{ _('docs.auto_combine_param') }}</li>
+                                    <li><code>false</code>: {{ _('docs.auto_combine_false') }}</li>
+                                </ul>
+                            </li>
+                            <li><strong>max_length</strong> (integer, default: 4096): {{ _('docs.max_length_chunk_param') }}</li>
+                        </ul>
+
+                        <h6>{{ _('docs.response_headers') }}</h6>
+                        <ul>
+                            <li><code>X-Auto-Combine</code>: {{ _('docs.auto_combine_header') }}</li>
+                            <li><code>X-Chunks-Combined</code>: {{ _('docs.chunks_combined_response') }}</li>
+                            <li><code>X-Original-Text-Length</code>: {{ _('docs.original_text_response') }}</li>
+                            <li><code>X-Audio-Format</code>: {{ _('docs.audio_format_header') }}</li>
+                            <li><code>X-Audio-Size</code>: {{ _('docs.audio_size_response') }}</li>
+                        </ul>
+
+                        <h6>{{ _('docs.examples_title') }}</h6>
+                        <div class="code-block">
+                            <pre><code># {{ _('docs.short_text_comment') }}
+curl -X POST {{ request.url_root }}v1/audio/speech \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-4o-mini-tts",
+    "input": "Hello world!",
+    "voice": "alloy"
+  }'
+
+# {{ _('docs.long_text_auto_comment') }}
+curl -X POST {{ request.url_root }}v1/audio/speech \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-4o-mini-tts",
+    "input": "Very long text...",
+    "voice": "alloy",
+    "auto_combine": true
+  }'
+
+# {{ _('docs.long_text_no_auto_comment') }}
+curl -X POST {{ request.url_root }}v1/audio/speech \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-4o-mini-tts",
+    "input": "Very long text...",
+    "voice": "alloy",
+    "auto_combine": false
+  }'</code></pre>
+                        </div>
+
+                        <div class="alert alert-info mt-3">
+                            <i class="fas fa-info-circle me-2"></i>
+                            <strong>{{ _('docs.audio_combination') }}</strong> {{ _('docs.audio_combination_desc') }}
+                        </div>
+
+                        <h6 class="mt-4">{{ _('docs.use_cases') }}</h6>
+                        <ul>
+                            <li><strong>{{ _('docs.use_case_articles') }}</strong></li>
+                            <li><strong>{{ _('docs.use_case_audiobooks') }}</strong></li>
+                            <li><strong>{{ _('docs.use_case_podcasts') }}</strong></li>
+                            <li><strong>{{ _('docs.use_case_education') }}</strong></li>
+                        </ul>
+
+                        <h6 class="mt-4">{{ _('docs.example_usage') }}</h6>
+                        <div class="code-block">
+                            <pre><code># {{ _('docs.python_example_comment') }}
+import requests
+
+response = requests.post(
+    "{{ request.url_root }}api/generate-combined",
+    json={
+        "text": "Your very long text content here...",
+        "voice": "nova",
+        "format": "mp3",
+        "max_length": 2000
+    }
+)
+
+if response.status_code == 200:
+    with open("combined_audio.mp3", "wb") as f:
+        f.write(response.content)
+
+    chunks = response.headers.get('X-Chunks-Combined')
+    print(f"Combined {chunks} chunks into single file")</code></pre>
+                        </div>
+                    </div>
+                </div>
+            </section>
+            
+            <!-- WebSocket Streaming -->
+            <section id="websocket" class="mb-5">
+                <h2 class="mb-4">
+                    <i class="fas fa-bolt text-warning me-2"></i>WebSocket Streaming
+                </h2>
+                <p class="lead">
+                    Real-time audio streaming for enhanced user experience. Get audio chunks as they're generated instead of waiting for the complete file.
+                </p>
+                
+                <div class="alert alert-info">
+                    <i class="fas fa-info-circle me-2"></i>
+                    WebSocket streaming provides lower perceived latency and real-time progress tracking for TTS generation.
+                </div>
+                
+                <h3 class="mt-4">Connection</h3>
+                <div class="code-block">
+                    <pre><code>// JavaScript WebSocket client
+const client = new WebSocketTTSClient({
+    socketUrl: '{{ request.url_root[:-1] }}',
+    debug: true
+});
+
+// Connection events
+client.onConnect = () => console.log('Connected');
+client.onDisconnect = () => console.log('Disconnected');</code></pre>
+                </div>
+                
+                <h3 class="mt-4">Streaming TTS Generation</h3>
+                <div class="code-block">
+                    <pre><code>// Generate speech with real-time streaming
+const result = await client.generateSpeech('Hello, WebSocket world!', {
+    voice: 'alloy',
+    format: 'mp3',
+    chunkSize: 1024,  // Characters per chunk
+    
+    // Progress callback
+    onProgress: (progress) => {
+        console.log(`Progress: ${progress.progress}%`);
+        console.log(`Chunks: ${progress.chunksCompleted}/${progress.totalChunks}`);
+    },
+    
+    // Receive audio chunks in real-time
+    onChunk: (chunk) => {
+        console.log(`Received chunk ${chunk.chunkIndex + 1}`);
+        // Process or play audio chunk immediately
+        processAudioChunk(chunk.audioData);
+    },
+    
+    // Completion callback
+    onComplete: (result) => {
+        console.log('Streaming complete!');
+        // result.audioData contains the complete audio
+    }
+});</code></pre>
+                </div>
+                
+                <h3 class="mt-4">WebSocket Events</h3>
+                <div class="endpoint-card card">
+                    <div class="card-body">
+                        <h5>Client → Server Events</h5>
+                        <table class="table table-sm">
+                            <thead>
+                                <tr>
+                                    <th>Event</th>
+                                    <th>Description</th>
+                                    <th>Payload</th>
+                                </tr>
+                            </thead>
+                            <tbody>
+                                <tr>
+                                    <td><code>generate_stream</code></td>
+                                    <td>Start TTS generation</td>
+                                    <td><code>{text, voice, format, chunk_size}</code></td>
+                                </tr>
+                                <tr>
+                                    <td><code>cancel_stream</code></td>
+                                    <td>Cancel active stream</td>
+                                    <td><code>{request_id}</code></td>
+                                </tr>
+                            </tbody>
+                        </table>
+                        
+                        <h5 class="mt-4">Server → Client Events</h5>
+                        <table class="table table-sm">
+                            <thead>
+                                <tr>
+                                    <th>Event</th>
+                                    <th>Description</th>
+                                    <th>Payload</th>
+                                </tr>
+                            </thead>
+                            <tbody>
+                                <tr>
+                                    <td><code>stream_started</code></td>
+                                    <td>Stream initiated</td>
+                                    <td><code>{request_id, timestamp}</code></td>
+                                </tr>
+                                <tr>
+                                    <td><code>audio_chunk</code></td>
+                                    <td>Audio chunk ready</td>
+                                    <td><code>{request_id, chunk_index, audio_data, duration}</code></td>
+                                </tr>
+                                <tr>
+                                    <td><code>stream_progress</code></td>
+                                    <td>Progress update</td>
+                                    <td><code>{progress, chunks_completed, total_chunks}</code></td>
+                                </tr>
+                                <tr>
+                                    <td><code>stream_complete</code></td>
+                                    <td>Generation complete</td>
+                                    <td><code>{request_id, total_chunks, status}</code></td>
+                                </tr>
+                                <tr>
+                                    <td><code>stream_error</code></td>
+                                    <td>Error occurred</td>
+                                    <td><code>{request_id, error, timestamp}</code></td>
+                                </tr>
+                            </tbody>
+                        </table>
+                    </div>
+                </div>
+                
+                <h3 class="mt-4">Benefits</h3>
+                <ul>
+                    <li><strong>Real-time feedback:</strong> Users see progress as audio generates</li>
+                    <li><strong>Lower latency:</strong> First audio chunk arrives quickly</li>
+                    <li><strong>Cancellable:</strong> Stop generation mid-stream if needed</li>
+                    <li><strong>Efficient:</strong> Process chunks as they arrive</li>
+                </ul>
+                
+                <h3 class="mt-4">Example: Streaming Audio Player</h3>
+                <div class="code-block">
+                    <pre><code>// Create a streaming audio player
+const audioChunks = [];
+let isPlaying = false;
+
+const streamingPlayer = await client.generateSpeech(longText, {
+    voice: 'nova',
+    format: 'mp3',
+    
+    onChunk: (chunk) => {
+        // Store chunk
+        audioChunks.push(chunk.audioData);
+        
+        // Start playing after first chunk
+        if (!isPlaying && audioChunks.length >= 3) {
+            startStreamingPlayback(audioChunks);
+            isPlaying = true;
+        }
+    },
+    
+    onComplete: (result) => {
+        // Ensure all chunks are played
+        finishPlayback(result.audioData);
+    }
+});</code></pre>
+                </div>
+                
+                <div class="alert alert-success mt-4">
+                    <h6><i class="fas fa-rocket me-2"></i>Try It Out!</h6>
+                    <p class="mb-0">
+                        Experience WebSocket streaming in action at the 
+                        <a href="/websocket-demo" class="alert-link">WebSocket Demo</a> or enable streaming mode in the 
+                        <a href="/playground" class="alert-link">Playground</a>.
+                    </p>
+                </div>
+            </section>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block extra_js %}
+<script>
+    // Smooth scrolling for TOC links
+    document.querySelectorAll('.toc a').forEach(link => {
+        link.addEventListener('click', function(e) {
+            e.preventDefault();
+            const target = document.querySelector(this.getAttribute('href'));
+            if (target) {
+                target.scrollIntoView({ behavior: 'smooth' });
+                
+                // Update active link
+                document.querySelectorAll('.toc a').forEach(l => l.classList.remove('active'));
+                this.classList.add('active');
+            }
+        });
+    });
+    
+    // Highlight current section in TOC
+    window.addEventListener('scroll', function() {
+        const sections = document.querySelectorAll('section[id]');
+        const scrollPos = window.scrollY + 100;
+        
+        sections.forEach(section => {
+            const top = section.offsetTop;
+            const bottom = top + section.offsetHeight;
+            const id = section.getAttribute('id');
+            const link = document.querySelector(`.toc a[href="#${id}"]`);
+            
+            if (scrollPos >= top && scrollPos < bottom) {
+                document.querySelectorAll('.toc a').forEach(l => l.classList.remove('active'));
+                if (link) link.classList.add('active');
+            }
+        });
+    });
+</script>
+{% endblock %}

templates/index.html

@@ -0,0 +1,156 @@
+{% extends "base.html" %}
+
+{% block title %}TTSFM - {{ _('home.title') }}{% endblock %}
+
+{% block content %}
+<!-- Hero Section -->
+<section class="hero-section">
+    <div class="container">
+        <div class="row align-items-center min-vh-75">
+            <div class="col-lg-8 mx-auto text-center">
+                <div class="hero-content">
+                    <div class="badge bg-primary text-white mb-3 px-3 py-2">
+                        <i class="fas fa-code me-2"></i>Python Package
+                    </div>
+                    <h1 class="display-4 fw-bold mb-4">
+                        {{ _('home.title') }}
+                    </h1>
+                    <p class="lead mb-4">
+                        {{ _('home.subtitle') }}
+                    </p>
+                    <div class="d-flex flex-wrap gap-3 justify-content-center">
+                        <a href="{{ url_for('playground') }}" class="btn btn-primary btn-lg">
+                            <i class="fas fa-play me-2"></i>{{ _('home.try_demo') }}
+                        </a>
+                        <a href="{{ url_for('docs') }}" class="btn btn-outline-secondary btn-lg">
+                            <i class="fas fa-book me-2"></i>{{ _('home.documentation') }}
+                        </a>
+                        <a href="https://github.com/dbccccccc/ttsfm" class="btn btn-outline-secondary btn-lg" target="_blank" rel="noopener noreferrer">
+                            <i class="fab fa-github me-2"></i>{{ _('home.github') }}
+                        </a>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</section>
+
+<!-- Features Section -->
+<section class="py-5" style="background-color: #f8fafc;">
+    <div class="container">
+        <div class="row">
+            <div class="col-12 text-center mb-5">
+                <h2 class="fw-bold mb-4">{{ _('home.features_title') }}</h2>
+                <p class="lead text-muted">
+                    {{ _('home.features_subtitle') }}
+                </p>
+            </div>
+        </div>
+
+        <div class="row g-4">
+            <div class="col-lg-3">
+                <div class="text-center">
+                    <div class="feature-icon text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-3" style="width: 4rem; height: 4rem; background: linear-gradient(135deg, #4f46e5 0%, #6366f1 100%);">
+                        <i class="fas fa-key"></i>
+                    </div>
+                    <h5 class="fw-bold">{{ _('home.feature_free_title') }}</h5>
+                    <p class="text-muted">{{ _('home.feature_free_desc') }}</p>
+                </div>
+            </div>
+
+            <div class="col-lg-3">
+                <div class="text-center">
+                    <div class="feature-icon text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-3" style="width: 4rem; height: 4rem; background: linear-gradient(135deg, #f59e0b 0%, #fbbf24 100%);">
+                        <i class="fas fa-magic"></i>
+                    </div>
+                    <h5 class="fw-bold">{{ _('home.feature_openai_title') }} <span class="badge bg-success ms-1">v3.2.3</span></h5>
+                    <p class="text-muted">{{ _('home.feature_openai_desc') }}</p>
+                </div>
+            </div>
+
+            <div class="col-lg-3">
+                <div class="text-center">
+                    <div class="feature-icon text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-3" style="width: 4rem; height: 4rem; background: linear-gradient(135deg, #059669 0%, #10b981 100%);">
+                        <i class="fas fa-bolt"></i>
+                    </div>
+                    <h5 class="fw-bold">{{ _('home.feature_async_title') }}</h5>
+                    <p class="text-muted">{{ _('home.feature_async_desc') }}</p>
+                </div>
+            </div>
+
+            <div class="col-lg-3">
+                <div class="text-center">
+                    <div class="feature-icon text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-3" style="width: 4rem; height: 4rem; background: linear-gradient(135deg, #6b7280 0%, #9ca3af 100%);">
+                        <i class="fas fa-microphone-alt"></i>
+                    </div>
+                    <h5 class="fw-bold">{{ _('home.feature_voices_title') }} & {{ _('home.feature_formats_title') }}</h5>
+                    <p class="text-muted">{{ _('home.feature_voices_desc') }} {{ _('home.feature_formats_desc') }}</p>
+                </div>
+            </div>
+        </div>
+    </div>
+</section>
+
+<!-- Quick Start Section -->
+<section class="py-5">
+    <div class="container">
+        <div class="row">
+            <div class="col-12 text-center mb-5">
+                <h2 class="fw-bold mb-4">{{ _('home.quick_start_title') }}</h2>
+                <p class="lead text-muted">
+                    {{ _('home.subtitle') }}
+                </p>
+            </div>
+        </div>
+
+        <div class="row g-4">
+            <div class="col-lg-6">
+                <div class="card h-100">
+                    <div class="card-body">
+                        <h5 class="card-title">
+                            <i class="fas fa-download me-2 text-primary"></i>{{ _('home.installation_title') }}
+                        </h5>
+                        <pre class="bg-light p-3 rounded"><code>{{ _('home.installation_code') }}</code></pre>
+                        <small class="text-muted">Requires Python 3.8+</small>
+                    </div>
+                </div>
+            </div>
+
+            <div class="col-lg-6">
+                <div class="card h-100">
+                    <div class="card-body">
+                        <h5 class="card-title">
+                            <i class="fas fa-play me-2 text-success"></i>{{ _('home.usage_title') }}
+                        </h5>
+                        <pre class="bg-light p-3 rounded"><code>from ttsfm import TTSClient, Voice, AudioFormat
+
+client = TTSClient()
+response = client.generate_speech(
+    text="Hello, world!",
+    voice=Voice.ALLOY,
+    response_format=AudioFormat.MP3
+)
+response.save_to_file("hello")</code></pre>
+                        <small class="text-muted">No API keys required</small>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <div class="row mt-4">
+            <div class="col-12 text-center">
+                <div class="d-flex justify-content-center gap-3 flex-wrap">
+                    <a href="{{ url_for('playground') }}" class="btn btn-primary">
+                        <i class="fas fa-play me-2"></i>{{ _('home.try_demo') }}
+                    </a>
+                    <a href="{{ url_for('docs') }}" class="btn btn-outline-primary">
+                        <i class="fas fa-book me-2"></i>{{ _('home.documentation') }}
+                    </a>
+                </div>
+            </div>
+        </div>
+    </div>
+</section>
+
+
+{% endblock %}

templates/playground.html

@@ -0,0 +1,317 @@
+{% extends "base.html" %}
+
+{% block title %}TTSFM {{ _('nav.playground') }} - {{ _('playground.title') }}{% endblock %}
+
+{% block content %}
+<!-- Clean Playground Header -->
+<section class="py-5" style="background-color: white; border-bottom: 1px solid #e5e7eb;">
+    <div class="container">
+        <div class="row align-items-center">
+            <div class="col-lg-8">
+                <div class="fade-in">
+                    <div class="badge bg-primary text-white mb-3 px-3 py-2">
+                        <i class="fas fa-flask me-2"></i>Demo
+                    </div>
+                    <h1 class="display-4 fw-bold mb-3 text-dark">
+                        <i class="fas fa-play-circle me-3 text-primary"></i>{{ _('playground.title') }}
+                    </h1>
+                    <p class="lead mb-4 text-muted">
+                        {{ _('playground.subtitle') }}
+                    </p>
+                </div>
+            </div>
+            <div class="col-lg-4 text-center">
+                <div class="playground-visual fade-in" style="animation-delay: 0.3s;">
+                    <div class="playground-icon">
+                        <i class="fas fa-waveform-lines text-primary"></i>
+                        <div class="pulse-ring"></div>
+                        <div class="pulse-ring pulse-ring-delay"></div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</section>
+
+<div class="container py-5 playground">
+
+    <div class="row">
+        <div class="col-lg-10 mx-auto">
+            <div class="card shadow-lg-custom border-0 fade-in">
+                <div class="card-header bg-gradient-primary text-white">
+                    <h4 class="mb-0 d-flex align-items-center">
+                        <i class="fas fa-microphone me-2"></i>
+                        {{ _('playground.title') }}
+                    </h4>
+                </div>
+                <div class="card-body p-4">
+                    <form id="tts-form" onsubmit="return false;">
+                        <!-- Enhanced Text Input -->
+                        <div class="mb-4">
+                            <label for="text-input" class="form-label fw-bold d-flex align-items-center">
+                                <i class="fas fa-edit me-2 text-primary"></i>
+                                {{ _('playground.text_input_label') }}
+                            </label>
+                            <div class="position-relative">
+                                <textarea
+                                    class="form-control shadow-sm"
+                                    id="text-input"
+                                    rows="4"
+                                    placeholder="{{ _('playground.text_input_placeholder') }}"
+                                    required
+                                >Hello! This is a test of the TTSFM text-to-speech system.</textarea>
+                                <div class="position-absolute top-0 end-0 p-2">
+                                    <button type="button" class="btn btn-sm btn-outline-secondary" id="clear-text-btn" title="Clear text">
+                                        <i class="fas fa-times"></i>
+                                    </button>
+                                </div>
+                            </div>
+                            <div class="form-text d-flex justify-content-between align-items-center">
+                                <div class="d-flex align-items-center gap-3">
+                                    <span class="text-muted">
+                                        <i class="fas fa-keyboard me-1"></i>
+                                        <span id="char-count">0</span> {{ _('playground.character_count') }}
+                                    </span>
+                                    <span id="length-status" class=""></span>
+                                    <span id="auto-combine-status" class="badge bg-success d-none">
+                                        <i class="fas fa-magic me-1"></i>{{ _('playground.max_length_warning') }}
+                                    </span>
+                                    <span class="text-muted small">
+                                        <i class="fas fa-lightbulb me-1"></i>
+                                        Tip: Use Ctrl+Enter to generate
+                                    </span>
+                                </div>
+                                <div class="btn-group" role="group">
+                                    <button type="button" class="btn btn-sm btn-outline-primary" id="validate-text-btn">
+                                        <i class="fas fa-check me-1"></i>{{ _('common.validate') if _('common.validate') != 'common.validate' else 'Validate' }}
+                                    </button>
+                                    <button type="button" class="btn btn-sm btn-outline-secondary" id="random-text-btn">
+                                        <i class="fas fa-dice me-1"></i>{{ _('playground.random_text') }}
+                                    </button>
+                                </div>
+                            </div>
+                            <div id="validation-result" class="mt-2 d-none"></div>
+                        </div>
+
+                        <div class="row">
+                            <!-- Enhanced Voice Selection -->
+                            <div class="col-md-6 mb-4">
+                                <label for="voice-select" class="form-label fw-bold d-flex align-items-center">
+                                    <i class="fas fa-microphone me-2 text-primary"></i>
+                                    {{ _('playground.voice_label') }}
+                                </label>
+                                <select class="form-select shadow-sm" id="voice-select" required>
+                                    <option value="">{{ _('common.loading_voices') }}</option>
+                                </select>
+                                <div class="form-text">
+                                    <span>{{ _('common.choose_voice') }}</span>
+                                </div>
+                            </div>
+
+                            <!-- Enhanced Format Selection -->
+                            <div class="col-md-6 mb-4">
+                                <label for="format-select" class="form-label fw-bold d-flex align-items-center">
+                                    <i class="fas fa-file-audio me-2 text-primary"></i>
+                                    {{ _('playground.format_label') }}
+                                </label>
+                                <select class="form-select shadow-sm" id="format-select" required>
+                                    <option value="">{{ _('common.loading_formats') }}</option>
+                                </select>
+                                <div class="form-text">
+                                    <span>{{ _('common.select_format') }}</span>
+                                </div>
+                            </div>
+                        </div>
+
+                        <!-- Advanced Options -->
+                        <div class="row">
+                            <div class="col-md-6 mb-4">
+                                <label for="max-length-input" class="form-label fw-bold">
+                                    <i class="fas fa-ruler me-2"></i>{{ _('common.max_length') }}
+                                </label>
+                                <input
+                                    type="number"
+                                    class="form-control"
+                                    id="max-length-input"
+                                    value="4096"
+                                    min="100"
+                                    max="10000"
+                                >
+                                <div class="form-text">
+                                    {{ _('playground.max_length_description') }}
+                                </div>
+                            </div>
+
+                            <div class="col-md-6 mb-4">
+                                <label class="form-label fw-bold">
+                                    <i class="fas fa-cog me-2"></i>{{ _('common.options') }}
+                                </label>
+                                <div class="form-check">
+                                    <input class="form-check-input" type="checkbox" id="validate-length-check" checked>
+                                    <label class="form-check-label" for="validate-length-check">
+                                        {{ _('playground.enable_length_validation') }}
+                                    </label>
+                                </div>
+                                <div class="form-check">
+                                    <input class="form-check-input" type="checkbox" id="auto-combine-check" checked>
+                                    <label class="form-check-label" for="auto-combine-check">
+                                        <span class="fw-bold text-primary">{{ _('playground.auto_combine_long_text') }}</span>
+                                        <i class="fas fa-info-circle ms-1" data-bs-toggle="tooltip"
+                                           title="{{ _('playground.auto_combine_tooltip') }}"></i>
+                                    </label>
+                                    <div class="form-text small">
+                                        <i class="fas fa-magic me-1"></i>
+                                        {{ _('playground.auto_combine_description') }}
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+
+                        <!-- Instructions (Optional) -->
+                        <div class="mb-4">
+                            <label for="instructions-input" class="form-label fw-bold">
+                                <i class="fas fa-magic me-2"></i>{{ _('playground.instructions_label') }}
+                            </label>
+                            <input
+                                type="text"
+                                class="form-control"
+                                id="instructions-input"
+                                placeholder="{{ _('playground.instructions_placeholder') }}"
+                            >
+                            <div class="form-text">
+                                {{ _('playground.instructions_description') }}
+                            </div>
+                        </div>
+
+                        <!-- API Key (Optional) -->
+                        <div class="mb-4" id="api-key-section">
+                            <label for="api-key-input" class="form-label fw-bold">
+                                <i class="fas fa-key me-2"></i>{{ _('playground.api_key_optional') }}
+                            </label>
+                            <div class="input-group">
+                                <input
+                                    type="password"
+                                    class="form-control"
+                                    id="api-key-input"
+                                    placeholder="{{ _('playground.api_key_placeholder') }}"
+                                >
+                                <button class="btn btn-outline-secondary" type="button" id="toggle-api-key-visibility">
+                                    <i class="fas fa-eye" id="api-key-eye-icon"></i>
+                                </button>
+                            </div>
+                            <div class="form-text">
+                                <i class="fas fa-info-circle me-1"></i>
+                                {{ _('playground.api_key_description') }}
+                            </div>
+                        </div>
+
+                        <!-- Enhanced Generate Button -->
+                        <div class="text-center mb-4">
+                            <div class="d-grid gap-2 d-md-block">
+                                <button type="submit" class="btn btn-primary btn-lg px-4 py-3" id="generate-btn">
+                                    <span class="btn-text">
+                                        <i class="fas fa-magic me-2"></i>{{ _('playground.generate_speech') }}
+                                    </span>
+                                    <span class="loading-spinner">
+                                        <i class="fas fa-spinner fa-spin me-2"></i>{{ _('playground.generating') }}
+                                    </span>
+                                </button>
+                                <button type="button" class="btn btn-outline-secondary btn-lg ms-md-3" id="reset-form-btn">
+                                    <i class="fas fa-redo me-2"></i>{{ _('common.reset') }}
+                                </button>
+                            </div>
+                        </div>
+                    </form>
+
+                    <!-- Enhanced Audio Player -->
+                    <div id="audio-result" class="d-none">
+                        <div class="border-top pt-4 mt-4">
+                            <div class="d-flex align-items-center justify-content-between mb-3">
+                                <h5 class="mb-0 d-flex align-items-center">
+                                    <i class="fas fa-volume-up me-2 text-success"></i>
+                                    {{ _('playground.audio_player_title') }}
+                                    <span class="badge bg-success ms-2">
+                                        <i class="fas fa-check me-1"></i>Ready
+                                    </span>
+                                </h5>
+                                <div class="btn-group" role="group">
+                                    <button type="button" class="btn btn-sm btn-outline-primary" id="replay-btn" title="Replay audio">
+                                        <i class="fas fa-redo"></i>
+                                    </button>
+                                    <button type="button" class="btn btn-sm btn-outline-secondary" id="share-btn" title="Share audio">
+                                        <i class="fas fa-share"></i>
+                                    </button>
+                                </div>
+                            </div>
+
+                            <div class="audio-player-container bg-light rounded p-3 mb-3">
+                                <audio controls class="audio-player w-100" id="audio-player" preload="metadata">
+                                    Your browser does not support the audio element.
+                                </audio>
+                                <div class="audio-controls mt-2 d-flex justify-content-between align-items-center">
+                                    <div class="audio-info">
+                                        <span id="audio-info" class="text-muted small"></span>
+                                    </div>
+                                    <div class="audio-actions">
+                                        <button type="button" class="btn btn-success btn-sm" id="download-btn">
+                                            <i class="fas fa-download me-1"></i>{{ _('playground.download_audio') }}
+                                        </button>
+                                    </div>
+                                </div>
+                            </div>
+
+                            <div class="audio-stats row text-center">
+                                <div class="col-md-3 col-6">
+                                    <div class="stat-item">
+                                        <i class="fas fa-clock text-primary"></i>
+                                        <div class="stat-value" id="audio-duration">--</div>
+                                        <div class="stat-label">{{ _('playground.duration') }}</div>
+                                    </div>
+                                </div>
+                                <div class="col-md-3 col-6">
+                                    <div class="stat-item">
+                                        <i class="fas fa-file text-info"></i>
+                                        <div class="stat-value" id="audio-size">--</div>
+                                        <div class="stat-label">{{ _('playground.file_size') }}</div>
+                                    </div>
+                                </div>
+                                <div class="col-md-3 col-6">
+                                    <div class="stat-item">
+                                        <i class="fas fa-microphone text-warning"></i>
+                                        <div class="stat-value" id="audio-voice">--</div>
+                                        <div class="stat-label">{{ _('playground.voice') }}</div>
+                                    </div>
+                                </div>
+                                <div class="col-md-3 col-6">
+                                    <div class="stat-item">
+                                        <i class="fas fa-music text-success"></i>
+                                        <div class="stat-value" id="audio-format">--</div>
+                                        <div class="stat-label">{{ _('playground.format') }}</div>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
+
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block extra_js %}
+<!-- Socket.IO for WebSocket support -->
+<script src="https://cdn.socket.io/4.6.0/socket.io.min.js"></script>
+<!-- WebSocket TTS Client -->
+<script src="{{ url_for('static', filename='js/websocket-tts.js') }}"></script>
+<!-- Enhanced Playground JavaScript with WebSocket Support -->
+<script src="{{ url_for('static', filename='js/playground-enhanced-fixed.js') }}"></script>
+<script>
+    // Additional playground-specific functionality
+    console.log('TTSFM Enhanced Playground with WebSocket support loaded successfully!');
+
+
+</script>
+{% endblock %}

templates/websocket_demo.html

@@ -0,0 +1,390 @@
+{% extends "base.html" %}
+
+{% block title %}{{ _('websocket.title', 'WebSocket Streaming Demo') }} - TTSFM{% endblock %}
+
+{% block content %}
+<div class="container mt-5">
+    <div class="row">
+        <div class="col-lg-10 mx-auto">
+            <h1 class="text-center mb-4">
+                <i class="fas fa-bolt text-warning"></i>
+                {{ _('websocket.title', 'WebSocket Streaming Demo') }}
+            </h1>
+            
+            <!-- Connection Status -->
+            <div class="alert alert-info" id="connection-status">
+                <i class="fas fa-plug me-2"></i>
+                <span id="status-text">Connecting to WebSocket server...</span>
+            </div>
+            
+            <!-- Input Form -->
+            <div class="card shadow-sm mb-4">
+                <div class="card-body">
+                    <h5 class="card-title">{{ _('playground.generate_speech', 'Generate Speech') }}</h5>
+                    
+                    <form id="streaming-form">
+                        <div class="mb-3">
+                            <label for="text-input" class="form-label">
+                                {{ _('playground.text_input', 'Text to Convert') }}
+                            </label>
+                            <textarea 
+                                class="form-control" 
+                                id="text-input" 
+                                rows="4" 
+                                maxlength="4096"
+                                placeholder="{{ _('playground.text_placeholder', 'Enter your text here...') }}"
+                            >Experience the future of text-to-speech with real-time WebSocket streaming! This innovative feature delivers audio chunks as they're generated, providing a more responsive and engaging user experience.</textarea>
+                            <div class="form-text">
+                                <i class="fas fa-info-circle me-1"></i>
+                                Streaming will split text into chunks for real-time delivery
+                            </div>
+                        </div>
+                        
+                        <div class="row">
+                            <div class="col-md-6 mb-3">
+                                <label for="voice-select" class="form-label">
+                                    {{ _('playground.voice', 'Voice') }}
+                                </label>
+                                <select class="form-select" id="voice-select">
+                                    <option value="alloy">Alloy</option>
+                                    <option value="echo">Echo</option>
+                                    <option value="fable">Fable</option>
+                                    <option value="onyx">Onyx</option>
+                                    <option value="nova">Nova</option>
+                                    <option value="shimmer">Shimmer</option>
+                                </select>
+                            </div>
+                            
+                            <div class="col-md-6 mb-3">
+                                <label for="format-select" class="form-label">
+                                    {{ _('playground.format', 'Audio Format') }}
+                                </label>
+                                <select class="form-select" id="format-select">
+                                    <option value="mp3">MP3</option>
+                                    <option value="wav">WAV</option>
+                                    <option value="opus">OPUS</option>
+                                </select>
+                            </div>
+                        </div>
+                        
+                        <div class="d-grid gap-2 d-md-flex justify-content-md-end">
+                            <button type="submit" class="btn btn-primary" id="stream-btn">
+                                <i class="fas fa-bolt me-2"></i>
+                                Start Streaming
+                            </button>
+                            <button type="button" class="btn btn-danger" id="cancel-btn" style="display: none;">
+                                <i class="fas fa-stop me-2"></i>
+                                Cancel
+                            </button>
+                        </div>
+                    </form>
+                </div>
+            </div>
+            
+            <!-- Progress Section -->
+            <div class="card shadow-sm mb-4" id="progress-section" style="display: none;">
+                <div class="card-body">
+                    <h5 class="card-title">Streaming Progress</h5>
+                    
+                    <div class="progress mb-3" style="height: 25px;">
+                        <div 
+                            class="progress-bar progress-bar-striped progress-bar-animated" 
+                            id="progress-bar"
+                            role="progressbar" 
+                            style="width: 0%"
+                        >
+                            <span id="progress-text">0%</span>
+                        </div>
+                    </div>
+                    
+                    <div class="row text-center">
+                        <div class="col-md-4">
+                            <h6>Chunks Received</h6>
+                            <p class="h4"><span id="chunks-received">0</span> / <span id="total-chunks">0</span></p>
+                        </div>
+                        <div class="col-md-4">
+                            <h6>Data Transferred</h6>
+                            <p class="h4" id="data-transferred">0 KB</p>
+                        </div>
+                        <div class="col-md-4">
+                            <h6>Generation Time</h6>
+                            <p class="h4" id="generation-time">0.0s</p>
+                        </div>
+                    </div>
+                </div>
+            </div>
+            
+            <!-- Audio Chunks Display -->
+            <div class="card shadow-sm mb-4" id="chunks-section" style="display: none;">
+                <div class="card-body">
+                    <h5 class="card-title">Audio Chunks</h5>
+                    <div id="chunks-container" class="row g-2">
+                        <!-- Chunks will be added here dynamically -->
+                    </div>
+                </div>
+            </div>
+            
+            <!-- Final Audio Player -->
+            <div class="card shadow-sm" id="audio-section" style="display: none;">
+                <div class="card-body">
+                    <h5 class="card-title">Generated Audio</h5>
+                    <audio id="audio-player" controls class="w-100"></audio>
+                    <div class="mt-2">
+                        <button class="btn btn-success" id="download-btn">
+                            <i class="fas fa-download me-2"></i>
+                            Download Audio
+                        </button>
+                    </div>
+                </div>
+            </div>
+            
+            <!-- Info Section -->
+            <div class="card shadow-sm mt-4">
+                <div class="card-body">
+                    <h5 class="card-title">
+                        <i class="fas fa-info-circle text-info me-2"></i>
+                        About WebSocket Streaming
+                    </h5>
+                    <p>
+                        This demo showcases real-time audio streaming using WebSockets. Instead of waiting 
+                        for the entire audio to be generated, you receive chunks as they're processed, 
+                        providing immediate feedback and a more responsive experience.
+                    </p>
+                    <ul>
+                        <li><strong>Lower Perceived Latency:</strong> Start receiving audio before generation completes</li>
+                        <li><strong>Progress Tracking:</strong> Real-time updates on generation progress</li>
+                        <li><strong>Cancellable:</strong> Stop generation mid-stream if needed</li>
+                        <li><strong>Efficient:</strong> Stream chunks as they're ready, no waiting</li>
+                    </ul>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+
+<!-- Include Socket.IO -->
+<script src="https://cdn.socket.io/4.6.0/socket.io.min.js"></script>
+<!-- Include our WebSocket client -->
+<script src="{{ url_for('static', filename='js/websocket-tts.js') }}"></script>
+
+<script>
+// Initialize WebSocket client
+let wsClient = null;
+let currentRequestId = null;
+let startTime = null;
+
+// Initialize on page load
+document.addEventListener('DOMContentLoaded', function() {
+    // Create WebSocket client
+    wsClient = new WebSocketTTSClient({
+        debug: true,
+        onConnect: () => {
+            updateConnectionStatus('connected');
+        },
+        onDisconnect: () => {
+            updateConnectionStatus('disconnected');
+        },
+        onError: (error) => {
+            updateConnectionStatus('error');
+            showError(`Connection error: ${error.message}`);
+        }
+    });
+    
+    // Form submission
+    document.getElementById('streaming-form').addEventListener('submit', handleStreamingSubmit);
+    
+    // Cancel button
+    document.getElementById('cancel-btn').addEventListener('click', handleCancel);
+});
+
+function updateConnectionStatus(status) {
+    const statusEl = document.getElementById('connection-status');
+    const statusText = document.getElementById('status-text');
+    
+    statusEl.className = 'alert';
+    
+    switch(status) {
+        case 'connected':
+            statusEl.classList.add('alert-success');
+            statusText.innerHTML = '<i class="fas fa-check-circle me-2"></i>Connected to WebSocket server';
+            break;
+        case 'disconnected':
+            statusEl.classList.add('alert-warning');
+            statusText.innerHTML = '<i class="fas fa-exclamation-triangle me-2"></i>Disconnected from server';
+            break;
+        case 'error':
+            statusEl.classList.add('alert-danger');
+            statusText.innerHTML = '<i class="fas fa-times-circle me-2"></i>Connection error';
+            break;
+        default:
+            statusEl.classList.add('alert-info');
+            statusText.innerHTML = '<i class="fas fa-plug me-2"></i>Connecting...';
+    }
+}
+
+async function handleStreamingSubmit(e) {
+    e.preventDefault();
+    
+    if (!wsClient || !wsClient.isConnected()) {
+        showError('WebSocket not connected. Please refresh the page.');
+        return;
+    }
+    
+    // Get form values
+    const text = document.getElementById('text-input').value.trim();
+    const voice = document.getElementById('voice-select').value;
+    const format = document.getElementById('format-select').value;
+    
+    if (!text) {
+        showError('Please enter some text to convert.');
+        return;
+    }
+    
+    // Reset UI
+    resetUI();
+    
+    // Show progress section
+    document.getElementById('progress-section').style.display = 'block';
+    document.getElementById('chunks-section').style.display = 'block';
+    document.getElementById('stream-btn').disabled = true;
+    document.getElementById('cancel-btn').style.display = 'inline-block';
+    
+    startTime = Date.now();
+    
+    try {
+        const result = await wsClient.generateSpeech(text, {
+            voice: voice,
+            format: format,
+            chunkSize: 512, // Smaller chunks for more updates
+            onStart: (data) => {
+                currentRequestId = data.request_id;
+                console.log('Stream started:', data);
+            },
+            onProgress: (progress) => {
+                updateProgress(progress);
+            },
+            onChunk: (chunk) => {
+                handleAudioChunk(chunk);
+            },
+            onComplete: (result) => {
+                handleStreamComplete(result);
+            },
+            onError: (error) => {
+                showError(`Streaming error: ${error.message}`);
+            }
+        });
+        
+        console.log('Streaming completed:', result);
+        
+    } catch (error) {
+        showError(`Failed to generate speech: ${error.message}`);
+        resetUI();
+    }
+}
+
+function updateProgress(progress) {
+    const progressBar = document.getElementById('progress-bar');
+    const progressText = document.getElementById('progress-text');
+    const chunksReceived = document.getElementById('chunks-received');
+    const totalChunks = document.getElementById('total-chunks');
+    const generationTime = document.getElementById('generation-time');
+    
+    progressBar.style.width = `${progress.progress}%`;
+    progressText.textContent = `${progress.progress}%`;
+    chunksReceived.textContent = progress.chunksCompleted;
+    totalChunks.textContent = progress.totalChunks;
+    
+    if (startTime) {
+        const elapsed = (Date.now() - startTime) / 1000;
+        generationTime.textContent = `${elapsed.toFixed(1)}s`;
+    }
+}
+
+function handleAudioChunk(chunk) {
+    const container = document.getElementById('chunks-container');
+    
+    // Create chunk visualization
+    const chunkEl = document.createElement('div');
+    chunkEl.className = 'col-auto';
+    chunkEl.innerHTML = `
+        <div class="badge bg-primary p-2" title="Chunk ${chunk.chunkIndex + 1}">
+            <i class="fas fa-music me-1"></i>
+            ${chunk.chunkIndex + 1}
+            <small class="d-block">${(chunk.audioData.byteLength / 1024).toFixed(1)}KB</small>
+        </div>
+    `;
+    
+    container.appendChild(chunkEl);
+    
+    // Update data transferred
+    const currentData = parseFloat(document.getElementById('data-transferred').textContent);
+    const newData = currentData + (chunk.audioData.byteLength / 1024);
+    document.getElementById('data-transferred').textContent = `${newData.toFixed(1)} KB`;
+}
+
+function handleStreamComplete(result) {
+    // Create blob from combined audio
+    const blob = new Blob([result.audioData], { type: `audio/${result.format}` });
+    const url = URL.createObjectURL(blob);
+    
+    // Set up audio player
+    const audioPlayer = document.getElementById('audio-player');
+    audioPlayer.src = url;
+    
+    // Show audio section
+    document.getElementById('audio-section').style.display = 'block';
+    
+    // Set up download button
+    document.getElementById('download-btn').onclick = () => {
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = `tts_stream_${Date.now()}.${result.format}`;
+        a.click();
+    };
+    
+    // Update final stats
+    document.getElementById('generation-time').textContent = `${(result.generationTime / 1000).toFixed(2)}s`;
+    
+    // Reset buttons
+    document.getElementById('stream-btn').disabled = false;
+    document.getElementById('cancel-btn').style.display = 'none';
+    
+    // Update progress bar to success
+    const progressBar = document.getElementById('progress-bar');
+    progressBar.classList.remove('progress-bar-animated');
+    progressBar.classList.add('bg-success');
+}
+
+function handleCancel() {
+    if (currentRequestId) {
+        wsClient.cancelStream(currentRequestId);
+        showInfo('Stream cancelled');
+        resetUI();
+    }
+}
+
+function resetUI() {
+    document.getElementById('progress-section').style.display = 'none';
+    document.getElementById('chunks-section').style.display = 'none';
+    document.getElementById('audio-section').style.display = 'none';
+    document.getElementById('stream-btn').disabled = false;
+    document.getElementById('cancel-btn').style.display = 'none';
+    document.getElementById('chunks-container').innerHTML = '';
+    document.getElementById('progress-bar').style.width = '0%';
+    document.getElementById('progress-bar').className = 'progress-bar progress-bar-striped progress-bar-animated';
+    document.getElementById('data-transferred').textContent = '0 KB';
+    currentRequestId = null;
+    startTime = null;
+}
+
+function showError(message) {
+    console.error(message);
+    // You could add a toast notification here
+}
+
+function showInfo(message) {
+    console.info(message);
+    // You could add a toast notification here
+}
+</script>
+{% endblock %}

translations/en.json

@@ -0,0 +1,224 @@
+{
+  "nav": {
+    "home": "Home",
+    "playground": "Playground",
+    "documentation": "Documentation",
+    "github": "GitHub",
+    "status_checking": "Checking...",
+    "status_online": "Online",
+    "status_offline": "Offline"
+  },
+  "common": {
+    "loading": "Loading...",
+    "error": "Error",
+    "success": "Success",
+    "warning": "Warning",
+    "info": "Info",
+    "close": "Close",
+    "save": "Save",
+    "cancel": "Cancel",
+    "confirm": "Confirm",
+    "download": "Download",
+    "upload": "Upload",
+    "generate": "Generate",
+    "play": "Play",
+    "stop": "Stop",
+    "pause": "Pause",
+    "resume": "Resume",
+    "clear": "Clear",
+    "reset": "Reset",
+    "copy": "Copy",
+    "copied": "Copied!",
+    "language": "Language",
+    "english": "English",
+    "chinese": "中文",
+    "validate": "Validate",
+    "options": "Options",
+    "max_length": "Max Length",
+    "tip": "Tip",
+    "choose_voice": "Choose from available voices",
+    "select_format": "Select your preferred audio format",
+    "loading_voices": "Loading voices...",
+    "loading_formats": "Loading formats...",
+    "ctrl_enter_tip": "Use Ctrl+Enter to generate",
+    "auto_combine_enabled": "Auto-combine enabled"
+  },
+  "home": {
+    "title": "Free Text-to-Speech for Python",
+    "subtitle": "Generate high-quality speech from text using the free openai.fm service. No API keys, no registration - just install and start creating audio.",
+    "try_demo": "Try Demo",
+    "documentation": "Documentation",
+    "github": "GitHub",
+    "features_title": "Key Features",
+    "features_subtitle": "Simple, free, and powerful text-to-speech for Python developers.",
+    "feature_free_title": "Completely Free",
+    "feature_free_desc": "No API keys or registration required. Uses the free openai.fm service.",
+    "feature_voices_title": "11 Voices",
+    "feature_voices_desc": "All OpenAI-compatible voices available for different use cases.",
+    "feature_formats_title": "6 Audio Formats",
+    "feature_formats_desc": "MP3, WAV, OPUS, AAC, FLAC, and PCM support for any application.",
+    "feature_docker_title": "Docker Ready",
+    "feature_docker_desc": "One-command deployment with web interface and API endpoints.",
+    "feature_openai_title": "OpenAI Compatible",
+    "feature_openai_desc": "Drop-in replacement for OpenAI's TTS API with auto-combine for long text.",
+    "feature_async_title": "Async & Sync",
+    "feature_async_desc": "Both asyncio and synchronous clients for maximum flexibility.",
+    "quick_start_title": "Quick Start",
+    "installation_title": "Installation",
+    "installation_code": "pip install ttsfm",
+    "usage_title": "Basic Usage",
+    "docker_title": "Docker Deployment",
+    "docker_desc": "Run TTSFM with web interface:",
+    "api_title": "OpenAI-Compatible API",
+    "api_desc": "Use with OpenAI Python client:",
+    "footer_copyright": "© 2024 dbcccc"
+  },
+  "playground": {
+    "title": "Interactive TTS Playground",
+    "subtitle": "Test different voices and audio formats in real-time",
+    "text_input_label": "Text to Convert",
+    "text_input_placeholder": "Enter the text you want to convert to speech...",
+    "voice_label": "Voice",
+    "format_label": "Audio Format",
+    "instructions_label": "Voice Instructions (Optional)",
+    "instructions_placeholder": "Additional instructions for voice generation...",
+    "character_count": "characters",
+    "max_length_warning": "Text exceeds maximum length. It will be automatically split and combined.",
+    "generate_speech": "Generate Speech",
+    "generating": "Generating...",
+    "download_audio": "Download Audio",
+    "audio_player_title": "Generated Audio",
+    "file_size": "File Size",
+    "duration": "Duration",
+    "format": "Format",
+    "voice": "Voice",
+    "chunks_combined": "Chunks Combined",
+    "random_text": "Random Text",
+    "clear_text": "Clear Text",
+    "max_length_description": "Maximum characters per request (default: 4096)",
+    "enable_length_validation": "Enable length validation",
+    "auto_combine_long_text": "Auto-combine long text",
+    "auto_combine_tooltip": "Automatically split long text and combine audio chunks into a single file",
+    "auto_combine_description": "Automatically handles text longer than the limit",
+    "instructions_description": "Provide optional instructions for voice modulation",
+    "api_key_optional": "API Key (Optional)",
+    "api_key_placeholder": "Enter your API key if required",
+    "api_key_description": "Only required if API key protection is enabled on the server",
+    "sample_texts": {
+      "welcome": "Welcome to TTSFM! This is a free text-to-speech service that converts your text into high-quality audio using advanced AI technology.",
+      "story": "Once upon a time, in a digital world far away, there lived a small Python package that could transform any text into beautiful speech. This package was called TTSFM, and it brought joy to developers everywhere.",
+      "technical": "TTSFM is a Python client for text-to-speech APIs that provides both synchronous and asynchronous interfaces. It supports multiple voices and audio formats, making it perfect for various applications.",
+      "multilingual": "TTSFM supports multiple languages and voices, allowing you to create diverse audio content for global audiences. The service is completely free and requires no API keys.",
+      "long": "This is a longer text sample designed to test the auto-combine feature of TTSFM. When text exceeds the maximum length limit, TTSFM automatically splits it into smaller chunks, generates audio for each chunk, and then seamlessly combines them into a single audio file. This process is completely transparent to the user and ensures that you can convert text of any length without worrying about technical limitations. The resulting audio maintains consistent quality and natural flow throughout the entire content."
+    },
+    "error_messages": {
+      "empty_text": "Please enter some text to convert.",
+      "generation_failed": "Failed to generate speech. Please try again.",
+      "network_error": "Network error. Please check your connection and try again.",
+      "invalid_format": "Invalid audio format selected.",
+      "invalid_voice": "Invalid voice selected.",
+      "text_too_long": "Text is too long. Please reduce the length or enable auto-combine.",
+      "server_error": "Server error. Please try again later."
+    },
+    "success_messages": {
+      "generation_complete": "Speech generated successfully!",
+      "text_copied": "Text copied to clipboard!",
+      "download_started": "Download started!"
+    }
+  },
+  "docs": {
+    "title": "API Documentation",
+    "subtitle": "Complete reference for the TTSFM Text-to-Speech API. Free, simple, and powerful.",
+    "contents": "Contents",
+    "overview": "Overview",
+    "authentication": "Authentication",
+    "text_validation": "Text Validation",
+    "endpoints": "API Endpoints",
+    "voices": "Voices",
+    "formats": "Audio Formats",
+    "generate": "Generate Speech",
+    "combined": "Combined Audio",
+    "status": "Status & Health",
+    "errors": "Error Handling",
+    "examples": "Code Examples",
+    "python_package": "Python Package",
+    "overview_title": "Overview",
+    "overview_desc": "The TTSFM API provides a modern, OpenAI-compatible interface for text-to-speech generation. It supports multiple voices, audio formats, and includes advanced features like text length validation and intelligent auto-combine functionality.",
+    "base_url": "Base URL:",
+    "key_features": "Key Features",
+    "feature_voices": "11 different voice options - Choose from alloy, echo, nova, and more",
+    "feature_formats": "Multiple audio formats - MP3, WAV, OPUS, AAC, FLAC, PCM support",
+    "feature_openai": "OpenAI compatibility - Drop-in replacement for OpenAI's TTS API",
+    "feature_auto_combine": "Auto-combine feature - Automatically handles long text (>4096 chars) by splitting and combining audio",
+    "feature_validation": "Text length validation - Smart validation with configurable limits",
+    "feature_monitoring": "Real-time monitoring - Status endpoints and health checks",
+    "new_version": "New in v3.2.3:",
+    "new_version_desc": "Enhanced `/v1/audio/speech` endpoint with intelligent auto-combine feature. Streamlined web interface with clean, user-friendly design and automatic long-text handling!",
+    "authentication_title": "Authentication",
+    "authentication_desc": "Currently, the API supports optional API key authentication. If configured, include your API key in the request headers.",
+    "text_validation_title": "Text Length Validation",
+    "text_validation_desc": "TTSFM includes built-in text length validation to ensure compatibility with TTS models. The default maximum length is 4096 characters, but this can be customized.",
+    "important": "Important:",
+    "text_validation_warning": "Text exceeding the maximum length will be rejected unless validation is disabled or the text is split into chunks.",
+    "validation_options": "Validation Options",
+    "max_length_option": "Maximum allowed characters (default: 4096)",
+    "validate_length_option": "Enable/disable validation (default: true)",
+    "preserve_words_option": "Avoid splitting words when chunking (default: true)",
+    "endpoints_title": "API Endpoints",
+    "get_voices_desc": "Get list of available voices.",
+    "get_formats_desc": "Get list of supported audio formats.",
+    "validate_text_desc": "Validate text length and get splitting suggestions.",
+    "generate_speech_desc": "Generate speech from text.",
+    "response_example": "Response Example:",
+    "request_body": "Request Body:",
+    "parameters": "Parameters:",
+    "text_param": "Text to convert to speech",
+    "voice_param": "Voice ID (default: \"alloy\")",
+    "format_param": "Audio format (default: \"mp3\")",
+    "instructions_param": "Voice modulation instructions",
+    "max_length_param": "Maximum text length (default: 4096)",
+    "validate_length_param": "Enable validation (default: true)",
+    "response": "Response:",
+    "response_audio": "Returns audio file with appropriate Content-Type header.",
+    "response_combined_audio": "Returns a single audio file containing all chunks combined seamlessly.",
+    "required": "required",
+    "optional": "optional",
+    "python_package_title": "Python Package",
+    "long_text_support": "Long Text Support",
+    "long_text_desc": "The TTSFM Python package includes built-in long text splitting functionality for developers who need fine-grained control:",
+    "developer_features": "Developer Features:",
+    "manual_splitting": "Manual Splitting: Full control over text chunking for advanced use cases",
+    "word_preservation": "Word Preservation: Maintains word boundaries for natural speech",
+    "separate_files": "Separate Files: Each chunk saved as individual audio file",
+    "cli_support": "CLI Support: Use `--split-long-text` flag for command-line usage",
+    "note": "Note:",
+    "auto_combine_note": "For web users, the auto-combine feature in `/v1/audio/speech` is recommended as it automatically handles long text and returns a single seamless audio file.",
+    "combined_audio_desc": "Generate a single combined audio file from long text. Automatically splits text into chunks, generates speech for each chunk, and combines them into one seamless audio file.",
+    "response_headers": "Response Headers:",
+    "chunks_combined_header": "Number of chunks that were combined",
+    "original_text_length_header": "Original text length in characters",
+    "audio_size_header": "Final audio file size in bytes",
+    "openai_compatible_desc": "Enhanced OpenAI-compatible endpoint with auto-combine feature. Automatically handles long text by splitting and combining audio chunks when needed.",
+    "enhanced_parameters": "Enhanced Parameters:",
+    "auto_combine_param": "Automatically split long text and combine audio chunks into a single file",
+    "auto_combine_false": "Return error if text exceeds max_length (standard OpenAI behavior)",
+    "max_length_chunk_param": "Maximum characters per chunk when splitting",
+    "auto_combine_header": "Whether auto-combine was enabled (true/false)",
+    "chunks_combined_response": "Number of audio chunks combined (1 for short text)",
+    "original_text_response": "Original text length (for long text processing)",
+    "audio_format_header": "Audio format of the response",
+    "audio_size_response": "Audio file size in bytes",
+    "short_text_comment": "Short text (works normally)",
+    "long_text_auto_comment": "Long text with auto-combine (default)",
+    "long_text_no_auto_comment": "Long text without auto-combine (will error)",
+    "audio_combination": "Audio Combination:",
+    "audio_combination_desc": "Uses advanced audio processing (PyDub) when available, with intelligent fallbacks for different environments. Supports all audio formats.",
+    "use_cases": "Use Cases:",
+    "use_case_articles": "Long Articles: Convert blog posts or articles to single audio files",
+    "use_case_audiobooks": "Audiobooks: Generate chapters as single audio files",
+    "use_case_podcasts": "Podcasts: Create podcast episodes from scripts",
+    "use_case_education": "Educational Content: Convert learning materials to audio",
+    "example_usage": "Example Usage:",
+    "python_example_comment": "Python example"
+  }
+}

translations/zh.json

@@ -0,0 +1,224 @@
+{
+  "nav": {
+    "home": "首页",
+    "playground": "试用平台",
+    "documentation": "文档",
+    "github": "GitHub",
+    "status_checking": "检查中...",
+    "status_online": "在线",
+    "status_offline": "离线"
+  },
+  "common": {
+    "loading": "加载中...",
+    "error": "错误",
+    "success": "成功",
+    "warning": "警告",
+    "info": "信息",
+    "close": "关闭",
+    "save": "保存",
+    "cancel": "取消",
+    "confirm": "确认",
+    "download": "下载",
+    "upload": "上传",
+    "generate": "生成",
+    "play": "播放",
+    "stop": "停止",
+    "pause": "暂停",
+    "resume": "继续",
+    "clear": "清除",
+    "reset": "重置",
+    "copy": "复制",
+    "copied": "已复制！",
+    "language": "语言",
+    "english": "English",
+    "chinese": "中文",
+    "validate": "验证",
+    "options": "选项",
+    "max_length": "最大长度",
+    "tip": "提示",
+    "choose_voice": "从可用声音中选择",
+    "select_format": "选择您偏好的音频格式",
+    "loading_voices": "加载声音中...",
+    "loading_formats": "加载格式中...",
+    "ctrl_enter_tip": "使用 Ctrl+Enter 生成",
+    "auto_combine_enabled": "自动合并已启用"
+  },
+  "home": {
+    "title": "免费的Python文本转语音",
+    "subtitle": "使用免费的openai.fm服务从文本生成高质量语音。无需API密钥，无需注册 - 只需安装即可开始创建音频。",
+    "try_demo": "试用演示",
+    "documentation": "文档",
+    "github": "GitHub",
+    "features_title": "主要特性",
+    "features_subtitle": "简单、免费且强大的Python开发者文本转语音工具。",
+    "feature_free_title": "完全免费",
+    "feature_free_desc": "无需API密钥或注册。使用免费的openai.fm服务。",
+    "feature_voices_title": "11种声音",
+    "feature_voices_desc": "提供所有OpenAI兼容的声音，适用于不同使用场景。",
+    "feature_formats_title": "6种音频格式",
+    "feature_formats_desc": "支持MP3、WAV、OPUS、AAC、FLAC和PCM格式，适用于任何应用。",
+    "feature_docker_title": "Docker就绪",
+    "feature_docker_desc": "一键部署，包含Web界面和API端点。",
+    "feature_openai_title": "OpenAI兼容",
+    "feature_openai_desc": "OpenAI TTS API的直接替代品，支持长文本自动合并。",
+    "feature_async_title": "异步和同步",
+    "feature_async_desc": "提供asyncio和同步客户端，最大化灵活性。",
+    "quick_start_title": "快速开始",
+    "installation_title": "安装",
+    "installation_code": "pip install ttsfm",
+    "usage_title": "基本用法",
+    "docker_title": "Docker部署",
+    "docker_desc": "运行带有Web界面的TTSFM：",
+    "api_title": "OpenAI兼容API",
+    "api_desc": "与OpenAI Python客户端一起使用：",
+    "footer_copyright": "© 2024 dbcccc"
+  },
+  "playground": {
+    "title": "交互式TTS试用平台",
+    "subtitle": "实时测试不同的声音和音频格式",
+    "text_input_label": "要转换的文本",
+    "text_input_placeholder": "输入您想要转换为语音的文本...",
+    "voice_label": "声音",
+    "format_label": "音频格式",
+    "instructions_label": "声音指令（可选）",
+    "instructions_placeholder": "语音生成的额外指令...",
+    "character_count": "字符",
+    "max_length_warning": "文本超过最大长度。将自动分割并合并。",
+    "generate_speech": "生成语音",
+    "generating": "生成中...",
+    "download_audio": "下载音频",
+    "audio_player_title": "生成的音频",
+    "file_size": "文件大小",
+    "duration": "时长",
+    "format": "格式",
+    "voice": "声音",
+    "chunks_combined": "合并片段",
+    "random_text": "随机文本",
+    "clear_text": "清除文本",
+    "max_length_description": "每个请求的最大字符数（默认：4096）",
+    "enable_length_validation": "启用长度验证",
+    "auto_combine_long_text": "自动合并长文本",
+    "auto_combine_tooltip": "自动分割长文本并将音频片段合并为单个文件",
+    "auto_combine_description": "自动处理超过限制的文本",
+    "instructions_description": "为声音调制提供可选指令",
+    "api_key_optional": "API密钥（可选）",
+    "api_key_placeholder": "如果需要，请输入您的API密钥",
+    "api_key_description": "仅在服务器启用API密钥保护时需要",
+    "sample_texts": {
+      "welcome": "欢迎使用TTSFM！这是一个免费的文本转语音服务，使用先进的AI技术将您的文本转换为高质量音频。",
+      "story": "很久很久以前，在一个遥远的数字世界里，住着一个小小的Python包，它能够将任何文本转换成美妙的语音。这个包叫做TTSFM，它为世界各地的开发者带来了快乐。",
+      "technical": "TTSFM是一个用于文本转语音API的Python客户端，提供同步和异步接口。它支持多种声音和音频格式，非常适合各种应用。",
+      "multilingual": "TTSFM支持多种语言和声音，让您能够为全球受众创建多样化的音频内容。该服务完全免费，无需API密钥。",
+      "long": "这是一个较长的文本示例，用于测试TTSFM的自动合并功能。当文本超过最大长度限制时，TTSFM会自动将其分割成较小的片段，为每个片段生成音频，然后无缝地将它们合并成一个音频文件。这个过程对用户完全透明，确保您可以转换任何长度的文本，而无需担心技术限制。生成的音频在整个内容中保持一致的质量和自然的流畅性。"
+    },
+    "error_messages": {
+      "empty_text": "请输入要转换的文本。",
+      "generation_failed": "语音生成失败。请重试。",
+      "network_error": "网络错误。请检查您的连接并重试。",
+      "invalid_format": "选择的音频格式无效。",
+      "invalid_voice": "选择的声音无效。",
+      "text_too_long": "文本太长。请减少长度或启用自动合并。",
+      "server_error": "服务器错误。请稍后重试。"
+    },
+    "success_messages": {
+      "generation_complete": "语音生成成功！",
+      "text_copied": "文本已复制到剪贴板！",
+      "download_started": "下载已开始！"
+    }
+  },
+  "docs": {
+    "title": "API文档",
+    "subtitle": "TTSFM文本转语音API的完整参考。免费、简单且强大。",
+    "contents": "目录",
+    "overview": "概述",
+    "authentication": "身份验证",
+    "text_validation": "文本验证",
+    "endpoints": "API端点",
+    "voices": "声音",
+    "formats": "音频格式",
+    "generate": "生成语音",
+    "combined": "合并音频",
+    "status": "状态和健康检查",
+    "errors": "错误处理",
+    "examples": "代码示例",
+    "python_package": "Python包",
+    "overview_title": "概述",
+    "overview_desc": "TTSFM API提供现代的、OpenAI兼容的文本转语音生成接口。它支持多种声音、音频格式，并包含高级功能，如文本长度验证和智能自动合并功能。",
+    "base_url": "基础URL：",
+    "key_features": "主要特性",
+    "feature_voices": "11种不同的声音选项 - 从alloy、echo、nova等中选择",
+    "feature_formats": "多种音频格式 - 支持MP3、WAV、OPUS、AAC、FLAC、PCM",
+    "feature_openai": "OpenAI兼容性 - OpenAI TTS API的直接替代品",
+    "feature_auto_combine": "自动合并功能 - 自动处理长文本（>4096字符），通过分割和合并音频",
+    "feature_validation": "文本长度验证 - 智能验证，可配置限制",
+    "feature_monitoring": "实时监控 - 状态端点和健康检查",
+    "new_version": "v3.2.3新功能：",
+    "new_version_desc": "增强的`/v1/audio/speech`端点，具有智能自动合并功能。简化的Web界面，设计简洁、用户友好，自动处理长文本！",
+    "authentication_title": "身份验证",
+    "authentication_desc": "目前，API支持可选的API密钥身份验证。如果已配置，请在请求头中包含您的API密钥。",
+    "text_validation_title": "文本长度验证",
+    "text_validation_desc": "TTSFM包含内置的文本长度验证，以确保与TTS模型的兼容性。默认最大长度为4096个字符，但可以自定义。",
+    "important": "重要：",
+    "text_validation_warning": "超过最大长度的文本将被拒绝，除非禁用验证或将文本分割成块。",
+    "validation_options": "验证选项",
+    "max_length_option": "允许的最大字符数（默认：4096）",
+    "validate_length_option": "启用/禁用验证（默认：true）",
+    "preserve_words_option": "分块时避免分割单词（默认：true）",
+    "endpoints_title": "API端点",
+    "get_voices_desc": "获取可用声音列表。",
+    "get_formats_desc": "获取支持的音频格式列表。",
+    "validate_text_desc": "验证文本长度并获取分割建议。",
+    "generate_speech_desc": "从文本生成语音。",
+    "response_example": "响应示例：",
+    "request_body": "请求体：",
+    "parameters": "参数：",
+    "text_param": "要转换为语音的文本",
+    "voice_param": "声音ID（默认：\"alloy\"）",
+    "format_param": "音频格式（默认：\"mp3\"）",
+    "instructions_param": "声音调制指令",
+    "max_length_param": "最大文本长度（默认：4096）",
+    "validate_length_param": "启用验证（默认：true）",
+    "response": "响应：",
+    "response_audio": "返回带有适当Content-Type头的音频文件。",
+    "response_combined_audio": "返回包含所有块无缝合并的单个音频文件。",
+    "required": "必需",
+    "optional": "可选",
+    "python_package_title": "Python包",
+    "long_text_support": "长文本支持",
+    "long_text_desc": "TTSFM Python包包含内置的长文本分割功能，为需要精细控制的开发者提供支持：",
+    "developer_features": "开发者功能：",
+    "manual_splitting": "手动分割：对高级用例的文本分块进行完全控制",
+    "word_preservation": "单词保护：维护单词边界以获得自然语音",
+    "separate_files": "单独文件：每个块保存为单独的音频文件",
+    "cli_support": "CLI支持：使用`--split-long-text`标志进行命令行使用",
+    "note": "注意：",
+    "auto_combine_note": "对于Web用户，建议使用`/v1/audio/speech`中的自动合并功能，因为它会自动处理长文本并返回单个无缝音频文件。",
+    "combined_audio_desc": "从长文本生成单个合并的音频文件。自动将文本分割成块，为每个块生成语音，并将它们合并成一个无缝的音频文件。",
+    "response_headers": "响应头：",
+    "chunks_combined_header": "合并的块数",
+    "original_text_length_header": "原始文本长度（字符数）",
+    "audio_size_header": "最终音频文件大小（字节）",
+    "openai_compatible_desc": "增强的OpenAI兼容端点，具有自动合并功能。在需要时自动处理长文本，通过分割和合并音频块。",
+    "enhanced_parameters": "增强参数：",
+    "auto_combine_param": "自动分割长文本并将音频块合并为单个文件",
+    "auto_combine_false": "如果文本超过max_length则返回错误（标准OpenAI行为）",
+    "max_length_chunk_param": "分割时每个块的最大字符数",
+    "auto_combine_header": "是否启用了自动合并（true/false）",
+    "chunks_combined_response": "合并的音频块数（短文本为1）",
+    "original_text_response": "原始文本长度（用于长文本处理）",
+    "audio_format_header": "响应的音频格式",
+    "audio_size_response": "音频文件大小（字节）",
+    "short_text_comment": "短文本（正常工作）",
+    "long_text_auto_comment": "带自动合并的长文本（默认）",
+    "long_text_no_auto_comment": "不带自动合并的长文本（将出错）",
+    "audio_combination": "音频合并：",
+    "audio_combination_desc": "在可用时使用高级音频处理（PyDub），在不同环境中具有智能回退。支持所有音频格式。",
+    "use_cases": "使用场景：",
+    "use_case_articles": "长文章：将博客文章或文章转换为单个音频文件",
+    "use_case_audiobooks": "有声书：将章节生成为单个音频文件",
+    "use_case_podcasts": "播客：从脚本创建播客剧集",
+    "use_case_education": "教育内容：将学习材料转换为音频",
+    "example_usage": "使用示例：",
+    "python_example_comment": "Python示例"
+  }
+}

websocket_handler.py

@@ -0,0 +1,231 @@
+"""
+WebSocket handler for real-time TTS streaming.
+
+Because apparently waiting 2 seconds for audio generation is too much for modern users.
+At least this will make it FEEL faster.
+"""
+
+import asyncio
+import json
+import logging
+import uuid
+import time
+from typing import Optional, Dict, Any
+from datetime import datetime
+
+from flask_socketio import SocketIO, emit, disconnect
+from flask import request
+
+from ttsfm import TTSClient, Voice, AudioFormat, TTSException
+from ttsfm.utils import split_text_by_length, estimate_audio_duration
+
+logger = logging.getLogger(__name__)
+
+
+class WebSocketTTSHandler:
+    """
+    Handles WebSocket connections for streaming TTS generation.
+    
+    Because your users can't wait 2 seconds for a complete response.
+    """
+    
+    def __init__(self, socketio: SocketIO, tts_client: TTSClient):
+        self.socketio = socketio
+        self.tts_client = tts_client
+        self.active_sessions: Dict[str, Dict[str, Any]] = {}
+        
+        # Register WebSocket events
+        self._register_events()
+        
+    def _register_events(self):
+        """Register all WebSocket event handlers."""
+        
+        @self.socketio.on('connect')
+        def handle_connect():
+            """Handle new WebSocket connection."""
+            session_id = request.sid
+            self.active_sessions[session_id] = {
+                'connected_at': datetime.now(),
+                'request_count': 0,
+                'last_request': None
+            }
+            logger.info(f"WebSocket client connected: {session_id}")
+            emit('connected', {'session_id': session_id, 'status': 'ready'})
+            
+        @self.socketio.on('disconnect')
+        def handle_disconnect():
+            """Handle WebSocket disconnection."""
+            session_id = request.sid
+            if session_id in self.active_sessions:
+                del self.active_sessions[session_id]
+            logger.info(f"WebSocket client disconnected: {session_id}")
+            
+        @self.socketio.on('generate_stream')
+        def handle_generate_stream(data):
+            """
+            Handle streaming TTS generation request.
+            
+            Expected data format:
+            {
+                'text': str,
+                'voice': str,
+                'format': str,
+                'chunk_size': int (optional, default 1024 chars),
+                'instructions': str (optional, voice modulation instructions)
+            }
+            """
+            session_id = request.sid
+            request_id = data.get('request_id', str(uuid.uuid4()))
+            
+            # Update session info
+            if session_id in self.active_sessions:
+                self.active_sessions[session_id]['request_count'] += 1
+                self.active_sessions[session_id]['last_request'] = datetime.now()
+            
+            # Emit acknowledgment
+            emit('stream_started', {
+                'request_id': request_id,
+                'timestamp': time.time()
+            })
+            
+            # Start async generation
+            self.socketio.start_background_task(
+                self._generate_stream,
+                session_id,
+                request_id,
+                data
+            )
+            
+        @self.socketio.on('cancel_stream')
+        def handle_cancel_stream(data):
+            """Handle stream cancellation request."""
+            request_id = data.get('request_id')
+            session_id = request.sid
+            
+            # In a real implementation, you'd track and cancel the actual generation
+            logger.info(f"Stream cancellation requested: {request_id}")
+            emit('stream_cancelled', {'request_id': request_id})
+    
+    def _generate_stream(self, session_id: str, request_id: str, data: Dict[str, Any]):
+        """
+        Generate TTS audio in chunks and stream to client.
+        
+        This is where the magic happens. And by magic, I mean
+        chunking text and pretending it's real-time.
+        """
+        try:
+            # Extract parameters
+            text = data.get('text', '')
+            voice = data.get('voice', 'alloy')
+            format_str = data.get('format', 'mp3')
+            chunk_size = data.get('chunk_size', 1024)
+            instructions = data.get('instructions', None)  # Voice instructions support!
+            
+            if not text:
+                self._emit_error(session_id, request_id, "No text provided")
+                return
+                
+            # Convert string parameters to enums
+            try:
+                voice_enum = Voice(voice.lower())
+                format_enum = AudioFormat(format_str.lower())
+            except ValueError as e:
+                self._emit_error(session_id, request_id, f"Invalid parameter: {str(e)}")
+                return
+            
+            # Split text into chunks for "streaming" effect
+            chunks = split_text_by_length(text, chunk_size, preserve_words=True)
+            total_chunks = len(chunks)
+            
+            logger.info(f"Starting stream generation: {request_id} with {total_chunks} chunks")
+            
+            # Emit initial progress
+            self.socketio.emit('stream_progress', {
+                'request_id': request_id,
+                'progress': 0,
+                'total_chunks': total_chunks,
+                'status': 'processing'
+            }, room=session_id)
+            
+            # Process each chunk
+            for i, chunk in enumerate(chunks):
+                # Check if client is still connected
+                if session_id not in self.active_sessions:
+                    logger.warning(f"Client disconnected during generation: {session_id}")
+                    break
+                
+                try:
+                    # Generate audio for chunk
+                    start_time = time.time()
+                    response = self.tts_client.generate_speech(
+                        text=chunk,
+                        voice=voice_enum,
+                        response_format=format_enum,
+                        instructions=instructions,  # Pass voice instructions!
+                        validate_length=False  # We already chunked it
+                    )
+                    generation_time = time.time() - start_time
+                    
+                    # Emit chunk data
+                    chunk_data = {
+                        'request_id': request_id,
+                        'chunk_index': i,
+                        'total_chunks': total_chunks,
+                        'audio_data': response.audio_data.hex(),  # Convert bytes to hex string
+                        'format': format_enum.value,
+                        'duration': response.duration,
+                        'generation_time': generation_time,
+                        'chunk_text': chunk[:50] + '...' if len(chunk) > 50 else chunk
+                    }
+                    
+                    self.socketio.emit('audio_chunk', chunk_data, room=session_id)
+                    
+                    # Emit progress update
+                    progress = int(((i + 1) / total_chunks) * 100)
+                    self.socketio.emit('stream_progress', {
+                        'request_id': request_id,
+                        'progress': progress,
+                        'total_chunks': total_chunks,
+                        'chunks_completed': i + 1,
+                        'status': 'processing'
+                    }, room=session_id)
+                    
+                    # Small delay to prevent overwhelming the client
+                    # (and to make it feel more "real-time")
+                    self.socketio.sleep(0.1)
+                    
+                except Exception as e:
+                    logger.error(f"Error generating chunk {i}: {str(e)}")
+                    self._emit_error(session_id, request_id, f"Chunk {i} generation failed: {str(e)}")
+                    # Continue with next chunk instead of failing completely
+                    continue
+            
+            # Emit completion
+            self.socketio.emit('stream_complete', {
+                'request_id': request_id,
+                'total_chunks': total_chunks,
+                'status': 'completed',
+                'timestamp': time.time()
+            }, room=session_id)
+            
+            logger.info(f"Stream generation completed: {request_id}")
+            
+        except Exception as e:
+            logger.error(f"Stream generation failed: {str(e)}")
+            self._emit_error(session_id, request_id, str(e))
+    
+    def _emit_error(self, session_id: str, request_id: str, error_message: str):
+        """Emit error to specific session."""
+        self.socketio.emit('stream_error', {
+            'request_id': request_id,
+            'error': error_message,
+            'timestamp': time.time()
+        }, room=session_id)
+    
+    def get_active_sessions_count(self) -> int:
+        """Get count of active WebSocket sessions."""
+        return len(self.active_sessions)
+    
+    def get_session_info(self, session_id: str) -> Optional[Dict[str, Any]]:
+        """Get information about a specific session."""
+        return self.active_sessions.get(session_id)