Upload 26 files

.env.example

@@ -0,0 +1,10 @@
+# Server configuration
+HOST=0.0.0.0
+PORT=7000
+
+# SSL configuration
+VERIFY_SSL=true
+
+# Flask configuration
+FLASK_ENV=production
+FLASK_APP=app.py

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/docker-build.yml

@@ -0,0 +1,78 @@
+name: Docker Build and Push
+
+on:
+  release:
+    types: [published]
+
+env:
+  REGISTRY_DOCKERHUB: docker.io
+  REGISTRY_GHCR: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver: docker-container
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY_GHCR }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ secrets.DOCKERHUB_USERNAME }}/ttsfm
+            ${{ env.REGISTRY_GHCR }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=tag
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest
+          labels: |
+            org.opencontainers.image.source=${{ github.repositoryUrl }}
+            org.opencontainers.image.description=Free TTS API server compatible with OpenAI's TTS API format using openai.fm
+            org.opencontainers.image.licenses=MIT
+            org.opencontainers.image.title=TTSFM - Free TTS API Server
+            org.opencontainers.image.vendor=dbcccc
+
+      - name: Build and push
+        id: build-and-push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Show image info
+        run: |
+          echo "Pushed tags: ${{ steps.meta.outputs.tags }}"
+          echo "Image digest: ${{ steps.build-and-push.outputs.digest }}"

.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: Release and Publish
+
+on:
+  push:
+    tags:
+      - 'v*'  # Triggers on version tags like v1.0.0, v3.0.1, etc.
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Test package import
+      run: |
+        pip install -e .
+        python -c "import ttsfm; print(f'✅ TTSFM imported successfully')"
+        python -c "from ttsfm import TTSClient; print('✅ TTSClient imported successfully')"
+
+    - name: Build package
+      run: |
+        python -m build
+        echo "📦 Package built successfully"
+        ls -la dist/
+
+    - name: Check package
+      run: |
+        twine check dist/*
+        echo "✅ Package validation passed"
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v1
+      with:
+        body: |
+          ## 🎉 TTSFM ${{ github.ref_name }}
+
+          New release of TTSFM - Free Text-to-Speech API with OpenAI compatibility.
+
+          ### 📦 Installation
+          ```bash
+          pip install ttsfm==${{ github.ref_name }}
+          ```
+
+          ### 🚀 Quick Start
+          ```python
+          from ttsfm import TTSClient
+
+          client = TTSClient()
+          response = client.generate_speech("Hello from TTSFM!")
+          response.save_to_file("hello")
+          ```
+
+          ### 🐳 Docker
+          ```bash
+          docker run -p 8000:8000 dbcccc/ttsfm:latest
+          ```
+
+          ### ✨ Features
+          - 🆓 Completely free (uses openai.fm service)
+          - 🎯 OpenAI-compatible API
+          - 🗣️ 11 voices available
+          - 🎵 6 audio formats (MP3, WAV, OPUS, AAC, FLAC, PCM)
+          - ⚡ Async and sync clients
+          - 🌐 Web interface included
+          - 🔧 CLI tool available
+
+          ### 📚 Documentation
+          See [README](https://github.com/dbccccccc/ttsfm#readme) for full documentation.
+        draft: false
+        prerelease: false

.gitignore

@@ -0,0 +1,156 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.venv/
+
+# Environment variables
+.env
+.env.local
+.env.production
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.spyderproject
+.spyproject
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Generated audio files (for testing)
+*.mp3
+*.wav
+*.opus
+*.aac
+*.flac
+*.pcm
+test_output.*
+output.*
+hello.*
+speech.*
+
+# Logs
+*.log
+logs/
+.pytest_cache/
+
+# Temporary files
+tmp/
+temp/
+.tmp/
+
+# Coverage reports
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+
+# Documentation builds
+docs/_build/
+site/
+
+# Package builds
+*.tar.gz
+*.whl
+dist/
+build/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# Pyre type checker
+.pyre/
+
+# Additional exclusions for GitHub
+
+# API Keys and Secrets
+config.json
+secrets.json
+.secrets
+api_keys.txt
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+
+# Backup files
+*.bak
+*.backup
+*~
+
+# Node.js (if using any JS tools)
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Docker
+.dockerignore
+Dockerfile.dev
+docker-compose.override.yml
+
+# Local configuration
+local_settings.py
+local_config.py

CHANGELOG.md

@@ -0,0 +1,191 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.1.0] - 2024-12-19
+
+### 🔧 Format Support Improvements
+
+This release focuses on fixing audio format handling and improving format delivery optimization.
+
+### ✨ Added
+
+- **Smart Header Selection**: Intelligent HTTP header selection to optimize format delivery from openai.fm service
+- **Format Mapping Functions**: Helper functions for better format handling and optimization
+- **Enhanced Web Interface**: Improved format selection with detailed descriptions for each format
+- **Comprehensive Format Documentation**: Updated README and documentation with complete format information
+
+### 🔄 Changed
+
+- **File Naming Logic**: Files are now saved with extensions based on the actual returned format, not the requested format
+- **Enhanced Logging**: Added format-specific log messages for better debugging
+- **Web API Enhancement**: `/api/formats` endpoint now provides detailed information about all supported formats
+- **Documentation Updates**: README and package documentation now include comprehensive format guides
+
+### 🐛 Fixed
+
+- **MAJOR FIX**: Resolved file naming issue where files were saved with incorrect double extensions (e.g., `test.wav.mp3`, `test.opus.wav`)
+- **Correct File Extensions**: Files now save with proper single extensions based on actual audio format (e.g., `test.mp3`, `test.wav`)
+- **Format Optimization**: Improved format delivery through smart request optimization
+- **Format Handling**: Better handling of all supported audio formats
+
+### 📝 Technical Details
+
+- **Format Optimization**: Smart request optimization to deliver the best quality for each format
+- **Backward Compatibility**: Existing code continues to work unchanged
+- **Enhanced Format Support**: Improved support for all 6 audio formats (MP3, WAV, OPUS, AAC, FLAC, PCM)
+
+## [3.0.0] - 2025-06-06
+
+### 🎉 First Python Package Release
+
+This is the first release of TTSFM as an installable Python package. Previous versions (v1.x and v2.x) were service-only releases that provided the API server but not a pip-installable package.
+
+### ✨ Added
+
+- **Complete Package Restructure**: Modern Python package structure with proper typing
+- **Async Support**: Full asynchronous client implementation with `asyncio`
+- **OpenAI API Compatibility**: Drop-in replacement for OpenAI TTS API
+- **Type Hints**: Complete type annotation support throughout the codebase
+- **CLI Interface**: Command-line tool for easy TTS generation
+- **Web Application**: Optional Flask-based web interface
+- **Docker Support**: Multi-architecture Docker images (linux/amd64, linux/arm64)
+- **Comprehensive Error Handling**: Detailed exception hierarchy
+- **Multiple Audio Formats**: Support for MP3, WAV, FLAC, and more
+- **Voice Options**: Multiple voice models (alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer)
+- **Text Processing**: Automatic text length validation and splitting
+- **Rate Limiting**: Built-in rate limiting and retry mechanisms
+- **Configuration**: Environment variable and configuration file support
+
+### 🔧 Technical Improvements
+
+- **Modern Build System**: Using `pyproject.toml` with setuptools
+- **GitHub Actions**: Automated Docker builds and PyPI publishing
+- **Development Tools**: Pre-commit hooks, linting, testing setup
+- **Documentation**: Comprehensive README and inline documentation
+- **Package Management**: Proper dependency management with optional extras
+
+### 🌐 API Changes
+
+- **Breaking**: Complete API redesign for better usability
+- **OpenAI Compatible**: `/v1/audio/speech` endpoint compatibility
+- **RESTful Design**: Clean REST API design
+- **Health Checks**: Built-in health check endpoints
+- **CORS Support**: Cross-origin resource sharing enabled
+
+### 📦 Installation Options
+
+```bash
+# Basic installation
+pip install ttsfm
+
+# With web application support
+pip install ttsfm[web]
+
+# With development tools
+pip install ttsfm[dev]
+
+# Docker
+docker run -p 8000:8000 ghcr.io/dbccccccc/ttsfm:latest
+```
+
+### 🚀 Quick Start
+
+```python
+from ttsfm import TTSClient, Voice
+
+client = TTSClient()
+response = client.generate_speech(
+    text="Hello! This is TTSFM v3.0.0",
+    voice=Voice.CORAL
+)
+
+with open("speech.mp3", "wb") as f:
+    f.write(response.audio_data)
+```
+
+### 📦 Package vs Service History
+
+**Important Note**: This v3.0.0 is the first release of TTSFM as a Python package available on PyPI. Previous versions (v1.x and v2.x) were service/API server releases only and were not available as installable packages.
+
+- **v1.x - v2.x**: Service releases (API server only, not pip-installable)
+- **v3.0.0+**: Full Python package releases (pip-installable with service capabilities)
+
+### 🐛 Bug Fixes
+
+- Fixed Docker build issues with dependency resolution
+- Improved error handling and user feedback
+- Better handling of long text inputs
+- Enhanced stability and performance
+
+### 📚 Documentation
+
+- Complete API documentation
+- Usage examples and tutorials
+- Docker deployment guide
+- Development setup instructions
+
+---
+
+## Previous Service Releases (Not Available as Python Packages)
+
+The following versions were service/API server releases only and were not available as pip-installable packages:
+
+### [2.0.0-alpha9] - 2025-04-09
+- Service improvements (alpha release)
+
+### [2.0.0-alpha8] - 2025-04-09
+- Service improvements (alpha release)
+
+### [2.0.0-alpha7] - 2025-04-07
+- Service improvements (alpha release)
+
+### [2.0.0-alpha6] - 2025-04-07
+- Service improvements (alpha release)
+
+### [2.0.0-alpha5] - 2025-04-07
+- Service improvements (alpha release)
+
+### [2.0.0-alpha4] - 2025-04-07
+- Service improvements (alpha release)
+
+### [2.0.0-alpha3] - 2025-04-07
+- Service improvements (alpha release)
+
+### [2.0.0-alpha2] - 2025-04-07
+- Service improvements (alpha release)
+
+### [2.0.0-alpha1] - 2025-04-07
+- Alpha release (DO NOT USE)
+
+### [1.3.0] - 2025-03-28
+- Support for additional audio file formats in the API
+- Alignment with formats supported by the official API
+
+### [1.2.2] - 2025-03-28
+- Fixed Docker support
+
+### [1.2.1] - 2025-03-28
+- Color change for indicator for status
+- Voice preview on webpage for each voice
+
+### [1.2.0] - 2025-03-26
+- Enhanced stability and availability by implementing advanced request handling mechanisms
+- Removed the proxy pool
+
+### [1.1.2] - 2025-03-26
+- Version display on webpage
+- Last version of 1.1.x
+
+### [1.1.1] - 2025-03-26
+- Build fixes
+
+### [1.1.0] - 2025-03-26
+- Project restructuring for better future development experiences
+- Added .env settings
+
+### [1.0.0] - 2025-03-26
+- First service release

Dockerfile

@@ -0,0 +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 && rm -rf /var/lib/apt/lists/*
+
+# Copy source code first
+COPY ttsfm/ ./ttsfm/
+COPY ttsfm-web/ ./ttsfm-web/
+COPY pyproject.toml ./
+COPY requirements.txt ./
+
+# 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
+
+# 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
+CMD ["python", "-m", "waitress", "--host=0.0.0.0", "--port=8000", "app:app"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dbcccc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyproject.toml

@@ -0,0 +1,161 @@
+[build-system]
+requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ttsfm"
+version = "3.1.0"
+description = "Text-to-Speech API Client with OpenAI compatibility"
+readme = "README.md"
+license = "MIT"
+authors = [
+    {name = "dbcccc", email = "[email protected]"}
+]
+maintainers = [
+    {name = "dbcccc", email = "[email protected]"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+keywords = [
+    "tts",
+    "text-to-speech", 
+    "speech-synthesis",
+    "openai",
+    "api-client",
+    "audio",
+    "voice",
+    "speech"
+]
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.25.0",
+    "aiohttp>=3.8.0",
+    "fake-useragent>=1.4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=6.0",
+    "pytest-asyncio>=0.18.0",
+    "pytest-cov>=2.0",
+    "black>=22.0",
+    "isort>=5.0",
+    "flake8>=4.0",
+    "mypy>=0.900",
+    "pre-commit>=2.0",
+]
+docs = [
+    "sphinx>=4.0",
+    "sphinx-rtd-theme>=1.0",
+    "myst-parser>=0.17",
+]
+web = [
+    "flask>=2.0.0",
+    "flask-cors>=3.0.10",
+    "waitress>=3.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/dbccccccc/ttsfm"
+Documentation = "https://github.com/dbccccccc/ttsfm/blob/main/docs/"
+Repository = "https://github.com/dbccccccc/ttsfm"
+"Bug Tracker" = "https://github.com/dbccccccc/ttsfm/issues"
+
+[project.scripts]
+ttsfm = "ttsfm.cli:main"
+
+[tool.setuptools]
+packages = ["ttsfm"]
+
+[tool.setuptools.package-data]
+ttsfm = ["py.typed"]
+
+[tool.black]
+line-length = 100
+target-version = ['py38']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+line_length = 100
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+use_parentheses = true
+ensure_newline_before_comments = true
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q --strict-markers --strict-config"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "unit: marks tests as unit tests",
+]
+
+[tool.coverage.run]
+source = ["ttsfm"]
+omit = [
+    "*/tests/*",
+    "*/test_*",
+    "setup.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]

requirements.txt

@@ -0,0 +1,4 @@
+# Core dependencies for the TTSFM package
+requests>=2.25.0
+aiohttp>=3.8.0
+fake-useragent>=1.4.0

ttsfm-web/app.py

@@ -0,0 +1,574 @@
+"""
+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
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+from flask import Flask, request, jsonify, send_file, Response, render_template
+from flask_cors import CORS
+from dotenv import load_dotenv
+
+# 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')
+CORS(app)
+
+# Configuration
+HOST = os.getenv("HOST", "localhost")
+PORT = int(os.getenv("PORT", "8000"))
+DEBUG = os.getenv("DEBUG", "false").lower() == "true"
+
+# Create TTS client - now uses openai.fm directly, no configuration needed
+tts_client = TTSClient()
+
+logger.info("Initialized web app with TTSFM using openai.fm free service")
+
+@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('/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'])
+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": str(e)}), 400
+        
+    except APIException as e:
+        logger.error(f"API error: {e}")
+        return jsonify({
+            "error": str(e),
+            "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",
+            "details": str(e)
+        }), 503
+        
+    except TTSException as e:
+        logger.error(f"TTS error: {e}")
+        return jsonify({"error": str(e)}), 500
+        
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
+        return jsonify({"error": "Internal server error"}), 500
+
+@app.route('/api/generate-batch', methods=['POST'])
+def generate_speech_batch():
+    """Generate speech from long text by splitting into chunks."""
+    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
+
+        # Validate voice and format
+        try:
+            voice_enum = Voice(voice.lower())
+            format_enum = AudioFormat(response_format.lower())
+        except ValueError as e:
+            return jsonify({"error": f"Invalid voice or format: {e}"}), 400
+
+        # Split text into chunks
+        chunks = split_text_by_length(text, max_length, preserve_words)
+
+        if not chunks:
+            return jsonify({"error": "No valid text chunks found"}), 400
+
+        logger.info(f"Processing {len(chunks)} chunks for batch generation")
+
+        # Generate speech for each chunk
+        results = []
+        for i, chunk in enumerate(chunks):
+            try:
+                response = tts_client.generate_speech(
+                    text=chunk,
+                    voice=voice_enum,
+                    response_format=format_enum,
+                    instructions=instructions,
+                    max_length=max_length,
+                    validate_length=False  # Already split
+                )
+
+                # Convert to base64 for JSON response
+                import base64
+                audio_b64 = base64.b64encode(response.audio_data).decode('utf-8')
+
+                results.append({
+                    "chunk_index": i + 1,
+                    "chunk_text": chunk[:100] + "..." if len(chunk) > 100 else chunk,
+                    "audio_data": audio_b64,
+                    "content_type": response.content_type,
+                    "size": response.size,
+                    "format": response.format.value
+                })
+
+            except Exception as e:
+                logger.error(f"Failed to generate chunk {i+1}: {e}")
+                results.append({
+                    "chunk_index": i + 1,
+                    "chunk_text": chunk[:100] + "..." if len(chunk) > 100 else chunk,
+                    "error": str(e)
+                })
+
+        return jsonify({
+            "total_chunks": len(chunks),
+            "successful_chunks": len([r for r in results if "audio_data" in r]),
+            "results": results
+        })
+
+    except Exception as e:
+        logger.error(f"Batch generation error: {e}")
+        return jsonify({"error": "Batch 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.0.0",
+            "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": str(e),
+            "timestamp": datetime.now().isoformat()
+        }), 503
+
+@app.route('/api/health', methods=['GET'])
+def health_check():
+    """Simple health check endpoint."""
+    return jsonify({
+        "status": "healthy",
+        "timestamp": datetime.now().isoformat()
+    })
+
+# OpenAI-compatible API endpoints
+@app.route('/v1/audio/speech', methods=['POST'])
+def openai_speech():
+    """OpenAI-compatible speech generation endpoint."""
+    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
+
+        # 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}")
+
+        # 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=4096,
+            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-Powered-By': 'TTSFM-OpenAI-Compatible'
+            }
+        )
+
+    except ValidationException as e:
+        logger.warning(f"OpenAI API validation error: {e}")
+        return jsonify({
+            "error": {
+                "message": str(e),
+                "type": "invalid_request_error",
+                "code": "validation_error"
+            }
+        }), 400
+
+    except APIException as e:
+        logger.error(f"OpenAI API error: {e}")
+        return jsonify({
+            "error": {
+                "message": str(e),
+                "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}")
+    
+    try:
+        app.run(
+            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()

ttsfm-web/requirements.txt

@@ -0,0 +1,9 @@
+# Web application dependencies
+flask>=2.0.0
+flask-cors>=3.0.10
+waitress>=3.0.0
+python-dotenv>=1.0.0
+
+# TTSFM package (install from local directory or PyPI)
+# For local development: pip install -e ../
+# For Docker/production: installed via pyproject.toml[web] dependencies

ttsfm-web/static/css/style.css

@@ -0,0 +1,1390 @@
+/* TTSFM Web Application Custom Styles */
+
+:root {
+    /* Clean Color Palette */
+    --primary-color: #2563eb;
+    --primary-dark: #1d4ed8;
+    --primary-light: #3b82f6;
+    --secondary-color: #64748b;
+    --secondary-dark: #475569;
+    --accent-color: #10b981;
+    --accent-dark: #059669;
+
+    /* Status Colors */
+    --success-color: #10b981;
+    --warning-color: #f59e0b;
+    --danger-color: #ef4444;
+    --info-color: #3b82f6;
+
+    /* Clean Neutral Colors */
+    --light-color: #ffffff;
+    --light-gray: #f8fafc;
+    --medium-gray: #64748b;
+    --dark-color: #1e293b;
+    --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: var(--border-radius-sm);
+    transition: all 0.2s ease;
+    letter-spacing: 0.025em;
+}
+
+.btn-primary {
+    background-color: var(--primary-color);
+    border-color: var(--primary-color);
+    color: white;
+}
+
+.btn-primary:hover {
+    background-color: var(--primary-dark);
+    border-color: var(--primary-dark);
+    color: white;
+}
+
+.btn-outline-primary {
+    border: 2px solid var(--primary-color);
+    color: var(--primary-color);
+    background: transparent;
+}
+
+.btn-outline-primary:hover {
+    background: var(--primary-color);
+    border-color: var(--primary-color);
+    color: white;
+}
+
+.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 2px rgba(0, 0, 0, 0.05);
+    transition: all 0.2s ease;
+    border-radius: 12px;
+    background: white;
+}
+
+.card:hover {
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.07);
+    border-color: #d1d5db;
+}
+
+.card-body {
+    padding: 2rem;
+}
+
+/* Clean Hero Section */
+.hero-section {
+    background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%);
+    color: var(--text-color);
+    padding: 6rem 0;
+    min-height: 80vh;
+    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: var(--border-radius-sm);
+    border: 2px solid #e2e8f0;
+    transition: var(--transition);
+    padding: 0.875rem 1rem;
+    font-size: 1rem;
+    background-color: #ffffff;
+    color: var(--text-color);
+}
+
+.form-control:focus, .form-select:focus {
+    border-color: var(--primary-color);
+    box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.1);
+    outline: none;
+    background-color: #ffffff;
+}
+
+.form-control:hover, .form-select:hover {
+    border-color: #cbd5e1;
+}
+
+.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;
+    }
+}

ttsfm-web/static/js/playground.js

@@ -0,0 +1,745 @@
+// TTSFM Playground JavaScript
+
+// Global variables
+let currentAudioBlob = null;
+let currentFormat = 'mp3';
+let batchResults = [];
+
+// Initialize playground
+document.addEventListener('DOMContentLoaded', function() {
+    initializePlayground();
+});
+
+function initializePlayground() {
+    loadVoices();
+    loadFormats();
+    updateCharCount();
+    setupEventListeners();
+    
+    // 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() {
+    // Form and input events
+    document.getElementById('text-input').addEventListener('input', updateCharCount);
+    document.getElementById('tts-form').addEventListener('submit', generateSpeech);
+    document.getElementById('max-length-input').addEventListener('input', updateCharCount);
+    document.getElementById('auto-split-check').addEventListener('change', updateGenerateButton);
+
+    // Enhanced button events
+    document.getElementById('validate-text-btn').addEventListener('click', validateText);
+    document.getElementById('random-text-btn').addEventListener('click', loadRandomText);
+    document.getElementById('download-btn').addEventListener('click', downloadAudio);
+    document.getElementById('download-all-btn').addEventListener('click', downloadAllAudio);
+
+    // 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);
+    }
+
+    // Voice and format selection events
+    document.getElementById('voice-select').addEventListener('change', updateVoiceInfo);
+    document.getElementById('format-select').addEventListener('change', updateFormatInfo);
+
+    // 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();
+        }
+    });
+}
+
+async function loadVoices() {
+    try {
+        const response = await fetch('/api/voices');
+        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 {
+        const response = await fetch('/api/formats');
+        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 text = document.getElementById('text-input').value;
+    const maxLength = parseInt(document.getElementById('max-length-input').value) || 4096;
+    const charCount = text.length;
+    
+    document.getElementById('char-count').textContent = charCount.toLocaleString();
+    
+    // Update length status with better visual feedback
+    const statusElement = document.getElementById('length-status');
+    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();
+}
+
+function updateGenerateButton() {
+    const text = document.getElementById('text-input').value;
+    const maxLength = parseInt(document.getElementById('max-length-input').value) || 4096;
+    const autoSplit = document.getElementById('auto-split-check').checked;
+    const generateBtn = document.getElementById('generate-btn');
+    const btnText = generateBtn.querySelector('.btn-text');
+    
+    if (text.length > maxLength && autoSplit) {
+        btnText.innerHTML = '<i class="fas fa-layer-group me-2"></i>Generate Speech (Batch Mode)';
+        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>
+                        <button class="btn btn-sm btn-outline-primary mt-2" onclick="enableAutoSplit()">
+                            <i class="fas fa-magic me-1"></i>Enable Auto-Split
+                        </button>
+                    </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 enableAutoSplit() {
+    document.getElementById('auto-split-check').checked = true;
+    updateGenerateButton();
+    console.log('Auto-split enabled! Click Generate Speech to process in batch mode.');
+}
+
+async function generateSpeech(event) {
+    event.preventDefault();
+    
+    const button = document.getElementById('generate-btn');
+    const audioResult = document.getElementById('audio-result');
+    const batchResult = document.getElementById('batch-result');
+    
+    // Get form data
+    const formData = getFormData();
+    
+    if (!validateFormData(formData)) {
+        return;
+    }
+    
+    // Check if we need batch processing
+    const needsBatch = formData.text.length > formData.maxLength && formData.autoSplit;
+    
+    // Show loading state
+    setLoading(button, true);
+    clearResults();
+    
+    try {
+        if (needsBatch) {
+            await generateBatchSpeech(formData);
+        } else {
+            await generateSingleSpeech(formData);
+        }
+    } catch (error) {
+        console.error('Generation failed:', error);
+        console.log(`Failed to generate speech: ${error.message}`);
+    } finally {
+        setLoading(button, false);
+    }
+}
+
+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,
+        autoSplit: document.getElementById('auto-split-check').checked
+    };
+}
+
+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.autoSplit) {
+        console.log(`Text is too long (${formData.text.length} characters). Enable auto-split or reduce text length.`);
+        return false;
+    }
+
+    return true;
+}
+
+function clearResults() {
+    document.getElementById('audio-result').classList.add('d-none');
+    document.getElementById('batch-result').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;
+    }
+}
+
+
+
+async function generateSingleSpeech(formData) {
+    const audioResult = document.getElementById('audio-result');
+
+    const response = await fetch('/api/generate', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            text: formData.text,
+            voice: formData.voice,
+            format: formData.format,
+            instructions: formData.instructions || undefined,
+            max_length: formData.maxLength,
+            validate_length: formData.validateLength
+        })
+    });
+
+    if (!response.ok) {
+        const errorData = await response.json();
+        throw new Error(errorData.error || `HTTP ${response.status}`);
+    }
+
+    // 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;
+
+    // Use enhanced display function
+    displayAudioResult(audioBlob, formData.format, formData.voice, formData.text);
+
+    console.log('Speech generated successfully! Click play to listen.');
+
+    // Auto-play if user prefers
+    if (localStorage.getItem('autoPlay') === 'true') {
+        audioPlayer.play().catch(() => {
+            // Auto-play blocked, that's fine
+        });
+    }
+}
+
+async function generateBatchSpeech(formData) {
+    const batchResult = document.getElementById('batch-result');
+
+    const response = await fetch('/api/generate-batch', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            text: formData.text,
+            voice: formData.voice,
+            format: formData.format,
+            instructions: formData.instructions || undefined,
+            max_length: formData.maxLength,
+            preserve_words: true
+        })
+    });
+
+    if (!response.ok) {
+        const errorData = await response.json();
+        throw new Error(errorData.error || `HTTP ${response.status}`);
+    }
+
+    const data = await response.json();
+    batchResults = data.results;
+
+    // Update batch summary
+    const summaryDiv = document.getElementById('batch-summary');
+    summaryDiv.innerHTML = `
+        <i class="fas fa-layer-group me-2"></i>
+        <strong>Batch Processing Complete!</strong>
+        Generated ${data.successful_chunks} of ${data.total_chunks} audio chunks successfully.
+        ${data.successful_chunks < data.total_chunks ?
+            `<br><small class="text-warning">⚠️ ${data.total_chunks - data.successful_chunks} chunks failed to generate.</small>` :
+            '<br><small class="text-success">✅ All chunks generated successfully!</small>'
+        }
+    `;
+
+    // Display chunks
+    displayBatchChunks(data.results, formData.format);
+
+    // Show batch result with animation
+    batchResult.classList.remove('d-none');
+    batchResult.classList.add('fade-in');
+
+    console.log(`Batch processing completed! Generated ${data.successful_chunks} audio files.`);
+}
+
+function displayBatchChunks(results, format) {
+    const chunksDiv = document.getElementById('batch-chunks');
+    chunksDiv.innerHTML = '';
+
+    results.forEach((result, index) => {
+        const chunkDiv = document.createElement('div');
+        chunkDiv.className = 'col-md-6 col-lg-4 mb-3';
+
+        if (result.audio_data) {
+            // Convert base64 to blob
+            const audioBlob = base64ToBlob(result.audio_data, result.content_type);
+            const audioUrl = URL.createObjectURL(audioBlob);
+
+            chunkDiv.innerHTML = `
+                <div class="card batch-chunk-card h-100">
+                    <div class="card-body">
+                        <div class="d-flex justify-content-between align-items-start mb-2">
+                            <h6 class="card-title mb-0">
+                                <i class="fas fa-music me-1"></i>Chunk ${result.chunk_index}
+                            </h6>
+                            <span class="badge bg-success">
+                                <i class="fas fa-check me-1"></i>Success
+                            </span>
+                        </div>
+                        <p class="card-text small text-muted mb-3">${result.chunk_text}</p>
+                        <audio controls class="w-100 mb-3" preload="metadata">
+                            <source src="${audioUrl}" type="${result.content_type}">
+                            Your browser does not support audio playback.
+                        </audio>
+                        <div class="d-flex justify-content-between align-items-center">
+                            <small class="text-muted">
+                                <i class="fas fa-file-audio me-1"></i>
+                                ${(result.size / 1024).toFixed(1)} KB
+                            </small>
+                            <button class="btn btn-sm btn-outline-primary download-chunk"
+                                    data-url="${audioUrl}"
+                                    data-filename="chunk_${result.chunk_index}.${result.format}"
+                                    title="Download this chunk">
+                                <i class="fas fa-download"></i>
+                            </button>
+                        </div>
+                    </div>
+                </div>
+            `;
+        } else {
+            chunkDiv.innerHTML = `
+                <div class="card border-danger h-100">
+                    <div class="card-body">
+                        <div class="d-flex justify-content-between align-items-start mb-2">
+                            <h6 class="card-title mb-0 text-danger">
+                                <i class="fas fa-exclamation-triangle me-1"></i>Chunk ${result.chunk_index}
+                            </h6>
+                            <span class="badge bg-danger">
+                                <i class="fas fa-times me-1"></i>Failed
+                            </span>
+                        </div>
+                        <p class="card-text small text-muted mb-3">${result.chunk_text}</p>
+                        <div class="alert alert-danger small mb-0">
+                            <i class="fas fa-exclamation-circle me-1"></i>
+                            ${result.error}
+                        </div>
+                    </div>
+                </div>
+            `;
+        }
+
+        chunksDiv.appendChild(chunkDiv);
+    });
+
+    // Add download event listeners
+    document.querySelectorAll('.download-chunk').forEach(btn => {
+        btn.addEventListener('click', function() {
+            const url = this.dataset.url;
+            const filename = this.dataset.filename;
+            downloadFromUrl(url, filename);
+
+            // Visual feedback
+            const icon = this.querySelector('i');
+            icon.className = 'fas fa-check';
+            setTimeout(() => {
+                icon.className = 'fas fa-download';
+            }, 1000);
+        });
+    });
+}
+
+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 downloadAllAudio() {
+    const downloadButtons = document.querySelectorAll('.download-chunk');
+    if (downloadButtons.length === 0) {
+        console.log('No batch audio files to download');
+        return;
+    }
+
+    console.log(`Starting download of ${downloadButtons.length} files...`);
+
+    downloadButtons.forEach((btn, index) => {
+        setTimeout(() => {
+            btn.click();
+        }, index * 500); // Stagger downloads to avoid browser limits
+    });
+}
+
+function base64ToBlob(base64, contentType) {
+    const byteCharacters = atob(base64);
+    const byteNumbers = new Array(byteCharacters.length);
+    for (let i = 0; i < byteCharacters.length; i++) {
+        byteNumbers[i] = byteCharacters.charCodeAt(i);
+    }
+    const byteArray = new Uint8Array(byteNumbers);
+    return new Blob([byteArray], { type: contentType });
+}
+
+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;
+    document.getElementById('auto-split-check').checked = false;
+
+    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
+function displayAudioResult(audioBlob, format, voice, text) {
+    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
+    audioInfo.innerHTML = `
+        <i class="fas fa-check-circle text-success me-1"></i>
+        Generated successfully • ${sizeKB} KB • ${format.toUpperCase()}
+    `;
+
+    // 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' });
+}
+
+// Export functions for use in HTML
+window.enableAutoSplit = enableAutoSplit;
+window.clearText = clearText;
+window.loadRandomText = loadRandomText;
+window.resetForm = resetForm;

ttsfm-web/templates/base.html

@@ -0,0 +1,349 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block title %}TTSFM - Text-to-Speech{% endblock %}</title>
+    
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/[email protected]/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 %}
+</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.0</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="Home page">
+                            <i class="fas fa-home me-1"></i>Home
+                        </a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link" href="{{ url_for('playground') }}" aria-label="Interactive playground">
+                            <i class="fas fa-play me-1"></i>Playground
+                        </a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link" href="{{ url_for('docs') }}" aria-label="API documentation">
+                            <i class="fas fa-book me-1"></i>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">Checking...</span>
+                        </span>
+                    </li>
+                    <li class="nav-item ms-2">
+                        <a class="btn btn-outline-primary btn-sm" href="https://github.com/dbccccccc/ttsfm" target="_blank" rel="noopener noreferrer" aria-label="View source code on GitHub">
+                            <i class="fab fa-github me-1"></i>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-4" style="background-color: #f8fafc; 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 mb-2 mb-md-0">
+                        <i class="fas fa-microphone-alt me-2 text-primary"></i>
+                        <strong class="text-dark">TTSFM</strong>
+                        <span class="ms-2 text-muted">Free Text-to-Speech for Python</span>
+                    </div>
+                </div>
+                <div class="col-md-6 text-md-end">
+                    <div class="d-flex justify-content-md-end gap-3">
+                        <a href="{{ url_for('playground') }}" class="text-decoration-none" style="color: #6b7280;">
+                            <i class="fas fa-play me-1"></i>Demo
+                        </a>
+                        <a href="{{ url_for('docs') }}" class="text-decoration-none" style="color: #6b7280;">
+                            <i class="fas fa-book me-1"></i>Docs
+                        </a>
+                        <a href="https://github.com/dbccccccc/ttsfm" class="text-decoration-none" style="color: #6b7280;" target="_blank" rel="noopener noreferrer">
+                            <i class="fab fa-github me-1"></i>GitHub
+                        </a>
+                    </div>
+                </div>
+            </div>
+            <hr class="my-3" style="border-color: #e5e7eb;">
+            <div class="row align-items-center">
+                <div class="col-md-6">
+                    <small class="text-muted">&copy; 2024 TTSFM. MIT License.</small>
+                </div>
+                <div class="col-md-6 text-md-end">
+                    <small class="text-muted">
+                        <span id="footer-status" class="d-inline-flex align-items-center">
+                            <span class="status-indicator status-offline me-2"></span>
+                            Status: <span id="footer-status-text" class="ms-1">Checking...</span>
+                        </span>
+                    </small>
+                </div>
+            </div>
+        </div>
+    </footer>
+
+    <!-- Bootstrap JS -->
+    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.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');
+                const footerIndicator = document.querySelector('#footer-status .status-indicator');
+                const footerText = document.getElementById('footer-status-text');
+
+                if (response.ok && data.status === 'healthy') {
+                    // Update navbar status
+                    indicator.className = 'status-indicator status-online';
+                    text.textContent = 'Online';
+
+                    // Update footer status
+                    if (footerIndicator) footerIndicator.className = 'status-indicator status-online';
+                    if (footerText) footerText.textContent = 'Online';
+                } else {
+                    // Update navbar status
+                    indicator.className = 'status-indicator status-offline';
+                    text.textContent = 'Offline';
+
+                    // Update footer status
+                    if (footerIndicator) footerIndicator.className = 'status-indicator status-offline';
+                    if (footerText) footerText.textContent = 'Offline';
+                }
+            } catch (error) {
+                // Update navbar status
+                const indicator = document.getElementById('status-indicator');
+                const text = document.getElementById('status-text');
+                indicator.className = 'status-indicator status-offline';
+                text.textContent = 'Offline';
+
+                // Update footer status
+                const footerIndicator = document.querySelector('#footer-status .status-indicator');
+                const footerText = document.getElementById('footer-status-text');
+                if (footerIndicator) footerIndicator.className = 'status-indicator status-offline';
+                if (footerText) footerText.textContent = '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>

ttsfm-web/templates/docs.html

@@ -0,0 +1,369 @@
+{% extends "base.html" %}
+
+{% block title %}TTSFM API Documentation{% 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"></i>API Documentation
+            </h1>
+            <p class="lead text-muted">
+                Complete reference for the TTSFM Text-to-Speech API
+            </p>
+        </div>
+    </div>
+    
+    <div class="row">
+        <!-- Table of Contents -->
+        <div class="col-lg-3">
+            <div class="toc">
+                <h5 class="fw-bold mb-3">Contents</h5>
+                <a href="#overview">Overview</a>
+                <a href="#authentication">Authentication</a>
+                <a href="#text-validation">Text Validation</a>
+                <a href="#endpoints">API Endpoints</a>
+                <a href="#voices">Voices</a>
+                <a href="#formats">Audio Formats</a>
+                <a href="#generate">Generate Speech</a>
+                <a href="#batch">Batch Processing</a>
+                <a href="#status">Status & Health</a>
+                <a href="#errors">Error Handling</a>
+                <a href="#examples">Code Examples</a>
+                <a href="#python-package">Python Package</a>
+            </div>
+        </div>
+        
+        <!-- Documentation Content -->
+        <div class="col-lg-9">
+            <!-- Overview -->
+            <section id="overview" class="mb-5">
+                <h2 class="fw-bold mb-3">Overview</h2>
+                <p>
+                    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 batch processing.
+                </p>
+                
+                <div class="alert alert-info">
+                    <i class="fas fa-info-circle me-2"></i>
+                    <strong>Base URL:</strong> <code>{{ request.url_root }}api/</code>
+                </div>
+                
+                <h4>Key Features</h4>
+                <ul>
+                    <li>11 different voice options</li>
+                    <li>Multiple audio formats (MP3, WAV, OPUS, etc.)</li>
+                    <li>Text length validation (4096 character limit)</li>
+                    <li>Automatic text splitting for long content</li>
+                    <li>Batch processing capabilities</li>
+                    <li>Real-time status monitoring</li>
+                </ul>
+            </section>
+            
+            <!-- Authentication -->
+            <section id="authentication" class="mb-5">
+                <h2 class="fw-bold mb-3">Authentication</h2>
+                <p>
+                    Currently, the API supports optional API key authentication. If configured,
+                    include your API key in the request headers.
+                </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">Text Length Validation</h2>
+                <p>
+                    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.
+                </p>
+                
+                <div class="alert alert-warning">
+                    <i class="fas fa-exclamation-triangle me-2"></i>
+                    <strong>Important:</strong> Text exceeding the maximum length will be rejected unless
+                    validation is disabled or the text is split into chunks.
+                </div>
+                
+                <h4>Validation Options</h4>
+                <ul>
+                    <li><code>max_length</code>: Maximum allowed characters (default: 4096)</li>
+                    <li><code>validate_length</code>: Enable/disable validation (default: true)</li>
+                    <li><code>preserve_words</code>: Avoid splitting words when chunking (default: true)</li>
+                </ul>
+            </section>
+            
+            <!-- API Endpoints -->
+            <section id="endpoints" class="mb-5">
+                <h2 class="fw-bold mb-3">API Endpoints</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">Get list of available voices.</p>
+                        
+                        <h6>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 list of supported audio formats.</p>
+                        
+                        <h6>Response Example:</h6>
+                        <div class="response-example">
+                            <pre><code>{
+  "formats": [
+    {
+      "id": "mp3",
+      "name": "MP3",
+      "mime_type": "audio/mp3",
+      "description": "MP3 audio 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">Validate text length and get splitting suggestions.</p>
+                        
+                        <h6>Request Body:</h6>
+                        <div class="code-block">
+                            <pre><code>{
+  "text": "Your text to validate",
+  "max_length": 4096
+}</code></pre>
+                        </div>
+                        
+                        <h6>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">Generate speech from text.</p>
+                        
+                        <h6>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>Parameters:</h6>
+                        <ul>
+                            <li><code>text</code> (required): Text to convert to speech</li>
+                            <li><code>voice</code> (optional): Voice ID (default: "alloy")</li>
+                            <li><code>format</code> (optional): Audio format (default: "mp3")</li>
+                            <li><code>instructions</code> (optional): Voice modulation instructions</li>
+                            <li><code>max_length</code> (optional): Maximum text length (default: 4096)</li>
+                            <li><code>validate_length</code> (optional): Enable validation (default: true)</li>
+                        </ul>
+                        
+                        <h6>Response:</h6>
+                        <p>Returns audio file with appropriate Content-Type header.</p>
+                    </div>
+                </div>
+                
+                <!-- Batch Processing Endpoint -->
+                <div class="card endpoint-card" id="batch">
+                    <div class="card-body">
+                        <h4 class="card-title">
+                            <span class="method-badge method-post">POST</span>
+                            /api/generate-batch
+                        </h4>
+                        <p class="card-text">Generate speech from long text by automatically splitting into chunks.</p>
+                        
+                        <h6>Request Body:</h6>
+                        <div class="code-block">
+                            <pre><code>{
+  "text": "Very long text that exceeds the limit...",
+  "voice": "alloy",
+  "format": "mp3",
+  "max_length": 4096,
+  "preserve_words": true
+}</code></pre>
+                        </div>
+                        
+                        <h6>Response Example:</h6>
+                        <div class="response-example">
+                            <pre><code>{
+  "total_chunks": 3,
+  "successful_chunks": 3,
+  "results": [
+    {
+      "chunk_index": 1,
+      "chunk_text": "First chunk text...",
+      "audio_data": "base64_encoded_audio",
+      "content_type": "audio/mp3",
+      "size": 12345,
+      "format": "mp3"
+    }
+  ]
+}</code></pre>
+                        </div>
+                    </div>
+                </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 %}

ttsfm-web/templates/index.html

@@ -0,0 +1,146 @@
+{% extends "base.html" %}
+
+{% block title %}TTSFM - Free Text-to-Speech for Python{% 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">
+                        Free Text-to-Speech for Python
+                    </h1>
+                    <p class="lead mb-4">
+                        Access free text-to-speech using openai.fm's service. No API keys required,
+                        just install and use immediately.
+                    </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>Try Demo
+                        </a>
+                        <a href="{{ url_for('docs') }}" class="btn btn-outline-secondary btn-lg">
+                            <i class="fas fa-book me-2"></i>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>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">Key Features</h2>
+                <p class="lead text-muted">
+                    Simple, free, and powerful text-to-speech for Python developers.
+                </p>
+            </div>
+        </div>
+
+        <div class="row g-4">
+            <div class="col-lg-4">
+                <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-color: #2563eb;">
+                        <i class="fas fa-key"></i>
+                    </div>
+                    <h5 class="fw-bold">No API Keys</h5>
+                    <p class="text-muted">Completely free service with no registration or API keys required.</p>
+                </div>
+            </div>
+
+            <div class="col-lg-4">
+                <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-color: #10b981;">
+                        <i class="fas fa-bolt"></i>
+                    </div>
+                    <h5 class="fw-bold">Easy to Use</h5>
+                    <p class="text-muted">Simple Python API with both sync and async support for all use cases.</p>
+                </div>
+            </div>
+
+            <div class="col-lg-4">
+                <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-color: #64748b;">
+                        <i class="fas fa-microphone-alt"></i>
+                    </div>
+                    <h5 class="fw-bold">Multiple Voices</h5>
+                    <p class="text-muted">Access to various voice options and audio formats for your needs.</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">Getting Started</h2>
+                <p class="lead text-muted">
+                    Install TTSFM and start generating speech with just a few lines of code.
+                </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>Installation
+                        </h5>
+                        <pre class="bg-light p-3 rounded"><code>pip install ttsfm</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>Basic Usage
+                        </h5>
+                        <pre class="bg-light p-3 rounded"><code>from ttsfm import TTSClient
+
+client = TTSClient()
+response = client.generate_speech(
+    text="Hello, world!",
+    voice="alloy"
+)
+response.save_to_file("hello.wav")</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>Try Demo
+                    </a>
+                    <a href="{{ url_for('docs') }}" class="btn btn-outline-primary">
+                        <i class="fas fa-book me-2"></i>Documentation
+                    </a>
+                </div>
+            </div>
+        </div>
+    </div>
+</section>
+
+
+{% endblock %}

ttsfm-web/templates/playground.html

@@ -0,0 +1,295 @@
+{% extends "base.html" %}
+
+{% block title %}TTSFM Playground - Try Text-to-Speech{% 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>TTS Playground
+                    </h1>
+                    <p class="lead mb-4 text-muted">
+                        Test the TTSFM text-to-speech functionality with different voices and formats.
+                    </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>
+                        Text-to-Speech Generator
+                    </h4>
+                </div>
+                <div class="card-body p-4">
+                    <form id="tts-form">
+                        <!-- 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>
+                                Text to Convert
+                            </label>
+                            <div class="position-relative">
+                                <textarea
+                                    class="form-control shadow-sm"
+                                    id="text-input"
+                                    rows="4"
+                                    placeholder="Enter the text you want to convert to speech..."
+                                    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> characters
+                                    </span>
+                                    <span id="length-status" class=""></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>Validate
+                                    </button>
+                                    <button type="button" class="btn btn-sm btn-outline-secondary" id="random-text-btn">
+                                        <i class="fas fa-dice me-1"></i>Random
+                                    </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>
+                                    Voice
+                                </label>
+                                <select class="form-select shadow-sm" id="voice-select" required>
+                                    <option value="">Loading voices...</option>
+                                </select>
+                                <div class="form-text">
+                                    <span>Choose from available voices</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>
+                                    Audio Format
+                                </label>
+                                <select class="form-select shadow-sm" id="format-select" required>
+                                    <option value="">Loading formats...</option>
+                                </select>
+                                <div class="form-text">
+                                    <span>Select your preferred audio 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>Max Length
+                                </label>
+                                <input
+                                    type="number"
+                                    class="form-control"
+                                    id="max-length-input"
+                                    value="4096"
+                                    min="100"
+                                    max="10000"
+                                >
+                                <div class="form-text">
+                                    Maximum characters per request (default: 4096)
+                                </div>
+                            </div>
+
+                            <div class="col-md-6 mb-4">
+                                <label class="form-label fw-bold">
+                                    <i class="fas fa-cog me-2"></i>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">
+                                        Enable length validation
+                                    </label>
+                                </div>
+                                <div class="form-check">
+                                    <input class="form-check-input" type="checkbox" id="auto-split-check">
+                                    <label class="form-check-label" for="auto-split-check">
+                                        Auto-split long text
+                                    </label>
+                                </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>Instructions (Optional)
+                            </label>
+                            <input
+                                type="text"
+                                class="form-control"
+                                id="instructions-input"
+                                placeholder="e.g., Speak in a cheerful and upbeat tone"
+                            >
+                            <div class="form-text">
+                                Provide optional instructions for voice modulation
+                            </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>Generate Speech
+                                    </span>
+                                    <span class="loading-spinner">
+                                        <i class="fas fa-spinner fa-spin me-2"></i>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>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>
+                                    Generated Audio
+                                    <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>Download
+                                        </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">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">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">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">Format</div>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Batch Results -->
+                    <div id="batch-result" class="d-none">
+                        <hr>
+                        <h5 class="mb-3">
+                            <i class="fas fa-layer-group me-2"></i>Batch Processing Results
+                        </h5>
+                        <div class="alert alert-info" id="batch-summary"></div>
+                        <div id="batch-chunks" class="row g-3"></div>
+                        <div class="mt-3">
+                            <button type="button" class="btn btn-outline-primary" id="download-all-btn">
+                                <i class="fas fa-download me-2"></i>Download All Audio Files
+                            </button>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block extra_js %}
+<!-- Playground JavaScript -->
+<script src="{{ url_for('static', filename='js/playground.js') }}"></script>
+<script>
+    // Additional playground-specific functionality
+    console.log('TTSFM Playground loaded successfully!');
+
+
+</script>
+{% endblock %}

ttsfm/__init__.py

@@ -0,0 +1,183 @@
+"""
+TTSFM - Text-to-Speech for Free using OpenAI.fm
+
+A Python library for generating high-quality text-to-speech audio using the free OpenAI.fm service.
+Supports multiple voices and audio formats with a simple, intuitive API.
+
+Features:
+- 🎤 6 premium AI voices (alloy, echo, fable, nova, onyx, shimmer)
+- 🎵 6 audio formats (MP3, WAV, OPUS, AAC, FLAC, PCM)
+- 🚀 Fast and reliable speech generation
+- 📝 Comprehensive text processing and validation
+- 🔄 Automatic retry with exponential backoff
+- 📊 Detailed response metadata and statistics
+- 🌐 Both synchronous and asynchronous APIs
+- 🎯 OpenAI-compatible API format
+- 🔧 Smart format optimization for best quality
+
+Audio Format Support:
+- MP3: Good quality, small file size - ideal for web and general use
+- WAV: Lossless quality, large file size - ideal for professional use
+- OPUS: High-quality compressed audio - ideal for streaming
+- AAC: Advanced audio codec - ideal for mobile devices
+- FLAC: Lossless compression - ideal for archival
+- PCM: Raw audio data - ideal for processing
+
+Example:
+    >>> from ttsfm import TTSClient, Voice, AudioFormat
+    >>>
+    >>> client = TTSClient()
+    >>>
+    >>> # Generate MP3 audio
+    >>> mp3_response = client.generate_speech(
+    ...     text="Hello, world!",
+    ...     voice=Voice.ALLOY,
+    ...     response_format=AudioFormat.MP3
+    ... )
+    >>> mp3_response.save_to_file("hello")  # Saves as hello.mp3
+    >>>
+    >>> # Generate WAV audio
+    >>> wav_response = client.generate_speech(
+    ...     text="High quality audio",
+    ...     voice=Voice.NOVA,
+    ...     response_format=AudioFormat.WAV
+    ... )
+    >>> wav_response.save_to_file("audio")  # Saves as audio.wav
+    >>>
+    >>> # Generate OPUS audio
+    >>> opus_response = client.generate_speech(
+    ...     text="Compressed audio",
+    ...     voice=Voice.ECHO,
+    ...     response_format=AudioFormat.OPUS
+    ... )
+    >>> opus_response.save_to_file("compressed")  # Saves as compressed.wav
+"""
+
+from .client import TTSClient
+from .async_client import AsyncTTSClient
+from .models import (
+    TTSRequest,
+    TTSResponse,
+    Voice,
+    AudioFormat,
+    TTSError,
+    APIError,
+    NetworkError,
+    ValidationError
+)
+from .exceptions import (
+    TTSException,
+    APIException,
+    NetworkException,
+    ValidationException,
+    RateLimitException,
+    AuthenticationException
+)
+from .utils import (
+    validate_text_length,
+    split_text_by_length
+)
+
+__version__ = "3.0.0"
+__author__ = "dbcccc"
+__email__ = "[email protected]"
+__description__ = "Text-to-Speech API Client with OpenAI compatibility"
+__url__ = "https://github.com/dbccccccc/ttsfm"
+
+# Default client instance for convenience
+default_client = None
+
+def create_client(base_url: str = None, api_key: str = None, **kwargs) -> TTSClient:
+    """
+    Create a new TTS client instance.
+    
+    Args:
+        base_url: Base URL for the TTS service
+        api_key: API key for authentication (if required)
+        **kwargs: Additional client configuration
+        
+    Returns:
+        TTSClient: Configured client instance
+    """
+    return TTSClient(base_url=base_url, api_key=api_key, **kwargs)
+
+def create_async_client(base_url: str = None, api_key: str = None, **kwargs) -> AsyncTTSClient:
+    """
+    Create a new async TTS client instance.
+    
+    Args:
+        base_url: Base URL for the TTS service
+        api_key: API key for authentication (if required)
+        **kwargs: Additional client configuration
+        
+    Returns:
+        AsyncTTSClient: Configured async client instance
+    """
+    return AsyncTTSClient(base_url=base_url, api_key=api_key, **kwargs)
+
+def set_default_client(client: TTSClient) -> None:
+    """Set the default client instance for convenience functions."""
+    global default_client
+    default_client = client
+
+def generate_speech(text: str, voice: str = "alloy", **kwargs) -> bytes:
+    """
+    Convenience function to generate speech using the default client.
+    
+    Args:
+        text: Text to convert to speech
+        voice: Voice to use for generation
+        **kwargs: Additional generation parameters
+        
+    Returns:
+        bytes: Generated audio data
+        
+    Raises:
+        TTSException: If no default client is set or generation fails
+    """
+    if default_client is None:
+        raise TTSException("No default client set. Use create_client() first.")
+    
+    return default_client.generate_speech(text=text, voice=voice, **kwargs)
+
+# Export all public components
+__all__ = [
+    # Main classes
+    "TTSClient",
+    "AsyncTTSClient",
+    
+    # Models
+    "TTSRequest",
+    "TTSResponse", 
+    "Voice",
+    "AudioFormat",
+    "TTSError",
+    "APIError",
+    "NetworkError",
+    "ValidationError",
+    
+    # Exceptions
+    "TTSException",
+    "APIException",
+    "NetworkException",
+    "ValidationException",
+    "RateLimitException",
+    "AuthenticationException",
+    
+    # Factory functions
+    "create_client",
+    "create_async_client",
+    "set_default_client",
+    "generate_speech",
+
+    # Utility functions
+    "validate_text_length",
+    "split_text_by_length",
+    
+    # Package metadata
+    "__version__",
+    "__author__",
+    "__email__",
+    "__description__",
+    "__url__"
+]

ttsfm/async_client.py

@@ -0,0 +1,464 @@
+"""
+Asynchronous TTS client implementation.
+
+This module provides the AsyncTTSClient class for asynchronous
+text-to-speech generation with OpenAI-compatible API.
+"""
+
+import json
+import uuid
+import asyncio
+import logging
+from typing import Optional, Dict, Any, Union, List
+
+import aiohttp
+from aiohttp import ClientTimeout, ClientSession
+
+from .models import (
+    TTSRequest, TTSResponse, Voice, AudioFormat,
+    get_content_type, get_format_from_content_type
+)
+from .exceptions import (
+    TTSException, APIException, NetworkException, ValidationException,
+    create_exception_from_response
+)
+from .utils import (
+    get_realistic_headers, sanitize_text, validate_url, build_url,
+    exponential_backoff, estimate_audio_duration, format_file_size,
+    validate_text_length, split_text_by_length
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncTTSClient:
+    """
+    Asynchronous TTS client for text-to-speech generation.
+    
+    This client provides an async interface for generating speech from text
+    using OpenAI-compatible TTS services with support for concurrent requests.
+    
+    Attributes:
+        base_url: Base URL for the TTS service
+        api_key: API key for authentication (if required)
+        timeout: Request timeout in seconds
+        max_retries: Maximum number of retry attempts
+        verify_ssl: Whether to verify SSL certificates
+        max_concurrent: Maximum concurrent requests
+    """
+    
+    def __init__(
+        self,
+        base_url: str = "https://www.openai.fm",
+        api_key: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        verify_ssl: bool = True,
+        max_concurrent: int = 10,
+        **kwargs
+    ):
+        """
+        Initialize the async TTS client.
+        
+        Args:
+            base_url: Base URL for the TTS service
+            api_key: API key for authentication
+            timeout: Request timeout in seconds
+            max_retries: Maximum retry attempts
+            verify_ssl: Whether to verify SSL certificates
+            max_concurrent: Maximum concurrent requests
+            **kwargs: Additional configuration options
+        """
+        self.base_url = base_url.rstrip('/')
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.verify_ssl = verify_ssl
+        self.max_concurrent = max_concurrent
+        
+        # Validate base URL
+        if not validate_url(self.base_url):
+            raise ValidationException(f"Invalid base URL: {self.base_url}")
+        
+        # Session will be created when needed
+        self._session: Optional[ClientSession] = None
+        self._semaphore = asyncio.Semaphore(max_concurrent)
+        
+        logger.info(f"Initialized async TTS client with base URL: {self.base_url}")
+    
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self._ensure_session()
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+    
+    async def _ensure_session(self):
+        """Ensure HTTP session is created."""
+        if self._session is None or self._session.closed:
+            # Setup headers
+            headers = get_realistic_headers()
+            if self.api_key:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            
+            # Create timeout configuration
+            timeout = ClientTimeout(total=self.timeout)
+            
+            # Create session
+            connector = aiohttp.TCPConnector(
+                verify_ssl=self.verify_ssl,
+                limit=self.max_concurrent * 2
+            )
+            
+            self._session = ClientSession(
+                headers=headers,
+                timeout=timeout,
+                connector=connector
+            )
+    
+    async def generate_speech(
+        self,
+        text: str,
+        voice: Union[Voice, str] = Voice.ALLOY,
+        response_format: Union[AudioFormat, str] = AudioFormat.MP3,
+        instructions: Optional[str] = None,
+        max_length: int = 4096,
+        validate_length: bool = True,
+        **kwargs
+    ) -> TTSResponse:
+        """
+        Generate speech from text asynchronously.
+
+        Args:
+            text: Text to convert to speech
+            voice: Voice to use for generation
+            response_format: Audio format for output
+            instructions: Optional instructions for voice modulation
+            max_length: Maximum allowed text length in characters (default: 4096)
+            validate_length: Whether to validate text length (default: True)
+            **kwargs: Additional parameters
+
+        Returns:
+            TTSResponse: Generated audio response
+
+        Raises:
+            TTSException: If generation fails
+            ValueError: If text exceeds max_length and validate_length is True
+        """
+        # Create and validate request
+        request = TTSRequest(
+            input=sanitize_text(text),
+            voice=voice,
+            response_format=response_format,
+            instructions=instructions,
+            max_length=max_length,
+            validate_length=validate_length,
+            **kwargs
+        )
+
+        return await self._make_request(request)
+
+    async def generate_speech_long_text(
+        self,
+        text: str,
+        voice: Union[Voice, str] = Voice.ALLOY,
+        response_format: Union[AudioFormat, str] = AudioFormat.MP3,
+        instructions: Optional[str] = None,
+        max_length: int = 4096,
+        preserve_words: bool = True,
+        **kwargs
+    ) -> List[TTSResponse]:
+        """
+        Generate speech from long text by splitting it into chunks asynchronously.
+
+        This method automatically splits text that exceeds max_length into
+        smaller chunks and generates speech for each chunk concurrently.
+
+        Args:
+            text: Text to convert to speech
+            voice: Voice to use for generation
+            response_format: Audio format for output
+            instructions: Optional instructions for voice modulation
+            max_length: Maximum length per chunk (default: 4096)
+            preserve_words: Whether to avoid splitting words (default: True)
+            **kwargs: Additional parameters
+
+        Returns:
+            List[TTSResponse]: List of generated audio responses
+
+        Raises:
+            TTSException: If generation fails for any chunk
+        """
+        # Sanitize text first
+        clean_text = sanitize_text(text)
+
+        # Split text into chunks
+        chunks = split_text_by_length(clean_text, max_length, preserve_words)
+
+        if not chunks:
+            raise ValueError("No valid text chunks found after processing")
+
+        # Create requests for all chunks
+        requests = []
+        for chunk in chunks:
+            request = TTSRequest(
+                input=chunk,
+                voice=voice,
+                response_format=response_format,
+                instructions=instructions,
+                max_length=max_length,
+                validate_length=False,  # We already split the text
+                **kwargs
+            )
+            requests.append(request)
+
+        # Process all chunks concurrently
+        return await self.generate_speech_batch(requests)
+
+    async def generate_speech_batch(
+        self,
+        requests: List[TTSRequest]
+    ) -> List[TTSResponse]:
+        """
+        Generate speech for multiple requests concurrently.
+        
+        Args:
+            requests: List of TTS requests
+            
+        Returns:
+            List[TTSResponse]: List of generated audio responses
+            
+        Raises:
+            TTSException: If any generation fails
+        """
+        if not requests:
+            return []
+        
+        # Process requests concurrently with semaphore limiting
+        tasks = [self._make_request(request) for request in requests]
+        responses = await asyncio.gather(*tasks, return_exceptions=True)
+        
+        # Check for exceptions and convert them
+        results = []
+        for i, response in enumerate(responses):
+            if isinstance(response, Exception):
+                raise TTSException(f"Request {i} failed: {str(response)}")
+            results.append(response)
+        
+        return results
+    
+    async def generate_speech_from_request(self, request: TTSRequest) -> TTSResponse:
+        """
+        Generate speech from a TTSRequest object asynchronously.
+        
+        Args:
+            request: TTS request object
+            
+        Returns:
+            TTSResponse: Generated audio response
+        """
+        return await self._make_request(request)
+    
+    async def _make_request(self, request: TTSRequest) -> TTSResponse:
+        """
+        Make the actual HTTP request to the TTS service.
+        
+        Args:
+            request: TTS request object
+            
+        Returns:
+            TTSResponse: Generated audio response
+            
+        Raises:
+            TTSException: If request fails
+        """
+        await self._ensure_session()
+        
+        async with self._semaphore:  # Limit concurrent requests
+            url = build_url(self.base_url, "api/generate")
+
+            # Prepare form data for openai.fm API
+            form_data = {
+                'input': request.input,
+                'voice': request.voice.value,
+                'generation': str(uuid.uuid4()),
+                'response_format': request.response_format.value if hasattr(request.response_format, 'value') else str(request.response_format)
+            }
+
+            # Add prompt/instructions if provided
+            if request.instructions:
+                form_data['prompt'] = request.instructions
+            else:
+                # Default prompt for better quality
+                form_data['prompt'] = (
+                    "Affect/personality: Natural and clear\n\n"
+                    "Tone: Friendly and professional, creating a pleasant listening experience.\n\n"
+                    "Pronunciation: Clear, articulate, and steady, ensuring each word is easily understood "
+                    "while maintaining a natural, conversational flow.\n\n"
+                    "Pause: Brief, purposeful pauses between sentences to allow time for the listener "
+                    "to process the information.\n\n"
+                    "Emotion: Warm and engaging, conveying the intended message effectively."
+                )
+
+            logger.info(f"Generating speech for text: '{request.input[:50]}...' with voice: {request.voice}")
+
+            # Make request with retries
+            for attempt in range(self.max_retries + 1):
+                try:
+                    # Add random delay for rate limiting (except first attempt)
+                    if attempt > 0:
+                        delay = exponential_backoff(attempt - 1)
+                        logger.info(f"Retrying request after {delay:.2f}s (attempt {attempt + 1})")
+                        await asyncio.sleep(delay)
+
+                    # Use form data as required by openai.fm
+                    async with self._session.post(url, data=form_data) as response:
+                        # Handle different response types
+                        if response.status == 200:
+                            return await self._process_openai_fm_response(response, request)
+                        else:
+                            # Try to parse error response
+                            try:
+                                error_data = await response.json()
+                            except (json.JSONDecodeError, ValueError):
+                                text = await response.text()
+                                error_data = {"error": {"message": text or "Unknown error"}}
+                            
+                            # Create appropriate exception
+                            exception = create_exception_from_response(
+                                response.status,
+                                error_data,
+                                f"TTS request failed with status {response.status}"
+                            )
+                            
+                            # Don't retry for certain errors
+                            if response.status in [400, 401, 403, 404]:
+                                raise exception
+                            
+                            # For retryable errors, continue to next attempt
+                            if attempt == self.max_retries:
+                                raise exception
+                            
+                            logger.warning(f"Request failed with status {response.status}, retrying...")
+                            continue
+                            
+                except asyncio.TimeoutError:
+                    if attempt == self.max_retries:
+                        raise NetworkException(
+                            f"Request timed out after {self.timeout}s",
+                            timeout=self.timeout,
+                            retry_count=attempt
+                        )
+                    logger.warning(f"Request timed out, retrying...")
+                    continue
+                    
+                except aiohttp.ClientError as e:
+                    if attempt == self.max_retries:
+                        raise NetworkException(
+                            f"Client error: {str(e)}",
+                            retry_count=attempt
+                        )
+                    logger.warning(f"Client error, retrying...")
+                    continue
+            
+            # This should never be reached, but just in case
+            raise TTSException("Maximum retries exceeded")
+    
+    async def _process_openai_fm_response(
+        self,
+        response: aiohttp.ClientResponse,
+        request: TTSRequest
+    ) -> TTSResponse:
+        """
+        Process a successful response from the openai.fm TTS service.
+
+        Args:
+            response: HTTP response object
+            request: Original TTS request
+
+        Returns:
+            TTSResponse: Processed response object
+        """
+        # Get content type from response headers
+        content_type = response.headers.get("content-type", "audio/mpeg")
+
+        # Get audio data
+        audio_data = await response.read()
+
+        if not audio_data:
+            raise APIException("Received empty audio data from openai.fm")
+
+        # Determine format from content type
+        if "audio/mpeg" in content_type or "audio/mp3" in content_type:
+            actual_format = AudioFormat.MP3
+        elif "audio/wav" in content_type:
+            actual_format = AudioFormat.WAV
+        elif "audio/opus" in content_type:
+            actual_format = AudioFormat.OPUS
+        elif "audio/aac" in content_type:
+            actual_format = AudioFormat.AAC
+        elif "audio/flac" in content_type:
+            actual_format = AudioFormat.FLAC
+        else:
+            # Default to MP3 for openai.fm
+            actual_format = AudioFormat.MP3
+
+        # Estimate duration based on text length
+        estimated_duration = estimate_audio_duration(request.input)
+
+        # Check if returned format differs from requested format
+        requested_format = request.response_format
+        if isinstance(requested_format, str):
+            try:
+                requested_format = AudioFormat(requested_format.lower())
+            except ValueError:
+                requested_format = AudioFormat.MP3  # Default fallback
+
+        # Import here to avoid circular imports
+        from .models import maps_to_wav
+
+        # Check if format differs from request
+        if actual_format != requested_format:
+            if maps_to_wav(requested_format.value) and actual_format.value == "wav":
+                logger.debug(
+                    f"Format '{requested_format.value}' requested, returning WAV format."
+                )
+            else:
+                logger.warning(
+                    f"Requested format '{requested_format.value}' but received '{actual_format.value}' "
+                    f"from service."
+                )
+
+        # Create response object
+        tts_response = TTSResponse(
+            audio_data=audio_data,
+            content_type=content_type,
+            format=actual_format,
+            size=len(audio_data),
+            duration=estimated_duration,
+            metadata={
+                "response_headers": dict(response.headers),
+                "status_code": response.status,
+                "url": str(response.url),
+                "service": "openai.fm",
+                "voice": request.voice.value,
+                "original_text": request.input[:100] + "..." if len(request.input) > 100 else request.input,
+                "requested_format": requested_format.value,
+                "actual_format": actual_format.value
+            }
+        )
+
+        logger.info(
+            f"Successfully generated {format_file_size(len(audio_data))} "
+            f"of {actual_format.value.upper()} audio from openai.fm using voice '{request.voice.value}'"
+        )
+
+        return tts_response
+    
+    async def close(self):
+        """Close the HTTP session."""
+        if self._session and not self._session.closed:
+            await self._session.close()

ttsfm/cli.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+"""
+Command-line interface for TTSFM.
+
+This module provides a command-line interface for the TTSFM package,
+allowing users to generate speech from text using various options.
+"""
+
+import argparse
+import sys
+import os
+from typing import Optional
+from pathlib import Path
+
+from .client import TTSClient
+from .models import Voice, AudioFormat
+from .exceptions import TTSException, APIException, NetworkException
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create and configure the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="ttsfm",
+        description="TTSFM - Text-to-Speech API Client",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  ttsfm "Hello, world!" --output hello.mp3
+  ttsfm "Hello, world!" --voice nova --format wav --output hello.wav
+  ttsfm "Hello, world!" --url http://localhost:7000 --output hello.mp3
+  ttsfm --text-file input.txt --output speech.mp3
+        """
+    )
+    
+    # Text input options (mutually exclusive)
+    text_group = parser.add_mutually_exclusive_group(required=True)
+    text_group.add_argument(
+        "text",
+        nargs="?",
+        help="Text to convert to speech"
+    )
+    text_group.add_argument(
+        "--text-file", "-f",
+        type=str,
+        help="Read text from file"
+    )
+    
+    # Output options
+    parser.add_argument(
+        "--output", "-o",
+        type=str,
+        required=True,
+        help="Output file path"
+    )
+    
+    # TTS options
+    parser.add_argument(
+        "--voice", "-v",
+        type=str,
+        default="alloy",
+        choices=["alloy", "echo", "fable", "onyx", "nova", "shimmer"],
+        help="Voice to use for speech generation (default: alloy)"
+    )
+    
+    parser.add_argument(
+        "--format",
+        type=str,
+        default="mp3",
+        choices=["mp3", "opus", "aac", "flac", "wav", "pcm"],
+        help="Audio format (default: mp3)"
+    )
+    
+    parser.add_argument(
+        "--speed",
+        type=float,
+        default=1.0,
+        help="Speech speed (0.25 to 4.0, default: 1.0)"
+    )
+    
+    # Client options
+    parser.add_argument(
+        "--url", "-u",
+        type=str,
+        default="http://localhost:7000",
+        help="TTS service URL (default: http://localhost:7000)"
+    )
+    
+    parser.add_argument(
+        "--api-key", "-k",
+        type=str,
+        help="API key for authentication"
+    )
+    
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=30.0,
+        help="Request timeout in seconds (default: 30.0)"
+    )
+    
+    parser.add_argument(
+        "--retries",
+        type=int,
+        default=3,
+        help="Maximum number of retries (default: 3)"
+    )
+
+    # Text length validation options
+    parser.add_argument(
+        "--max-length",
+        type=int,
+        default=4096,
+        help="Maximum text length in characters (default: 4096)"
+    )
+
+    parser.add_argument(
+        "--no-length-validation",
+        action="store_true",
+        help="Disable text length validation"
+    )
+
+    parser.add_argument(
+        "--split-long-text",
+        action="store_true",
+        help="Automatically split long text into chunks"
+    )
+
+    # Other options
+    parser.add_argument(
+        "--verbose", "-V",
+        action="store_true",
+        help="Enable verbose output"
+    )
+    
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {get_version()}"
+    )
+    
+    return parser
+
+
+def get_version() -> str:
+    """Get the package version."""
+    try:
+        from . import __version__
+        return __version__
+    except ImportError:
+        return "unknown"
+
+
+def read_text_file(file_path: str) -> str:
+    """Read text from a file."""
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            return f.read().strip()
+    except FileNotFoundError:
+        print(f"Error: File '{file_path}' not found.", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error reading file '{file_path}': {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def validate_speed(speed: float) -> float:
+    """Validate and return the speed parameter."""
+    if not 0.25 <= speed <= 4.0:
+        print("Error: Speed must be between 0.25 and 4.0", file=sys.stderr)
+        sys.exit(1)
+    return speed
+
+
+def get_voice_enum(voice_str: str) -> Voice:
+    """Convert voice string to Voice enum."""
+    voice_map = {
+        "alloy": Voice.ALLOY,
+        "echo": Voice.ECHO,
+        "fable": Voice.FABLE,
+        "onyx": Voice.ONYX,
+        "nova": Voice.NOVA,
+        "shimmer": Voice.SHIMMER,
+    }
+    return voice_map[voice_str.lower()]
+
+
+def get_format_enum(format_str: str) -> AudioFormat:
+    """Convert format string to AudioFormat enum."""
+    format_map = {
+        "mp3": AudioFormat.MP3,
+        "opus": AudioFormat.OPUS,
+        "aac": AudioFormat.AAC,
+        "flac": AudioFormat.FLAC,
+        "wav": AudioFormat.WAV,
+        "pcm": AudioFormat.PCM,
+    }
+    return format_map[format_str.lower()]
+
+
+def handle_long_text(args, text: str, voice: Voice, audio_format: AudioFormat, speed: float) -> None:
+    """Handle long text by splitting it into chunks and generating multiple files."""
+    from .utils import split_text_by_length
+    import os
+
+    # Split text into chunks
+    chunks = split_text_by_length(text, args.max_length, preserve_words=True)
+
+    if not chunks:
+        print("Error: No valid text chunks found after processing.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Split text into {len(chunks)} chunks")
+
+    # Create client
+    try:
+        client = TTSClient(
+            base_url=args.url,
+            api_key=args.api_key,
+            timeout=args.timeout,
+            max_retries=args.retries
+        )
+
+        # Generate speech for each chunk
+        base_name, ext = os.path.splitext(args.output)
+
+        for i, chunk in enumerate(chunks, 1):
+            if args.verbose:
+                print(f"Processing chunk {i}/{len(chunks)} ({len(chunk)} characters)...")
+
+            # Generate filename for this chunk
+            if len(chunks) == 1:
+                output_file = args.output
+            else:
+                output_file = f"{base_name}_part{i:03d}{ext}"
+
+            # Generate speech for this chunk
+            audio_data = client.generate_speech(
+                text=chunk,
+                voice=voice,
+                response_format=audio_format,
+                speed=speed,
+                max_length=args.max_length,
+                validate_length=False  # We already split the text
+            )
+
+            # Save to file
+            with open(output_file, 'wb') as f:
+                f.write(audio_data)
+
+            print(f"Generated: {output_file}")
+
+        if len(chunks) > 1:
+            print(f"\nGenerated {len(chunks)} audio files from long text.")
+            print(f"Files: {base_name}_part001{ext} to {base_name}_part{len(chunks):03d}{ext}")
+
+    except Exception as e:
+        print(f"Error processing long text: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = create_parser()
+    args = parser.parse_args()
+    
+    # Get text input
+    if args.text:
+        text = args.text
+    else:
+        text = read_text_file(args.text_file)
+    
+    if not text:
+        print("Error: No text provided.", file=sys.stderr)
+        sys.exit(1)
+    
+    # Validate parameters
+    speed = validate_speed(args.speed)
+    voice = get_voice_enum(args.voice)
+    audio_format = get_format_enum(args.format)
+    
+    # Create output directory if needed
+    output_path = Path(args.output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Check text length and handle accordingly
+    text_length = len(text)
+    validate_length = not args.no_length_validation
+
+    if args.verbose:
+        print(f"Text: {text[:50]}{'...' if len(text) > 50 else ''}")
+        print(f"Text length: {text_length} characters")
+        print(f"Max length: {args.max_length}")
+        print(f"Length validation: {'enabled' if validate_length else 'disabled'}")
+        print(f"Voice: {args.voice}")
+        print(f"Format: {args.format}")
+        print(f"Speed: {speed}")
+        print(f"URL: {args.url}")
+        print(f"Output: {args.output}")
+        print()
+
+    # Handle long text
+    if text_length > args.max_length:
+        if args.split_long_text:
+            print(f"Text is {text_length} characters, splitting into chunks...")
+            return handle_long_text(args, text, voice, audio_format, speed)
+        elif validate_length:
+            print(f"Error: Text is too long ({text_length} characters). "
+                  f"Maximum allowed is {args.max_length} characters.", file=sys.stderr)
+            print("Use --split-long-text to automatically split the text, "
+                  "or --no-length-validation to disable this check.", file=sys.stderr)
+            sys.exit(1)
+    
+    # Create client
+    try:
+        client = TTSClient(
+            base_url=args.url,
+            api_key=args.api_key,
+            timeout=args.timeout,
+            max_retries=args.retries
+        )
+        
+        if args.verbose:
+            print("Generating speech...")
+        
+        # Generate speech
+        audio_data = client.generate_speech(
+            text=text,
+            voice=voice,
+            response_format=audio_format,
+            speed=speed,
+            max_length=args.max_length,
+            validate_length=validate_length
+        )
+        
+        # Save to file
+        with open(args.output, 'wb') as f:
+            f.write(audio_data)
+        
+        print(f"Speech generated successfully: {args.output}")
+        
+    except NetworkException as e:
+        print(f"Network error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except APIException as e:
+        print(f"API error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except TTSException as e:
+        print(f"TTS error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ttsfm/client.py

@@ -0,0 +1,481 @@
+"""
+Main TTS client implementation.
+
+This module provides the primary TTSClient class for synchronous
+text-to-speech generation with OpenAI-compatible API.
+"""
+
+import json
+import time
+import uuid
+import logging
+from typing import Optional, Dict, Any, Union, List
+from urllib.parse import urljoin
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from .models import (
+    TTSRequest, TTSResponse, Voice, AudioFormat,
+    get_content_type, get_format_from_content_type
+)
+from .exceptions import (
+    TTSException, APIException, NetworkException, ValidationException,
+    create_exception_from_response
+)
+from .utils import (
+    get_realistic_headers, sanitize_text, validate_url, build_url,
+    exponential_backoff, estimate_audio_duration, format_file_size,
+    validate_text_length, split_text_by_length
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class TTSClient:
+    """
+    Synchronous TTS client for text-to-speech generation.
+    
+    This client provides a simple interface for generating speech from text
+    using OpenAI-compatible TTS services.
+    
+    Attributes:
+        base_url: Base URL for the TTS service
+        api_key: API key for authentication (if required)
+        timeout: Request timeout in seconds
+        max_retries: Maximum number of retry attempts
+        verify_ssl: Whether to verify SSL certificates
+    """
+    
+    def __init__(
+        self,
+        base_url: str = "https://www.openai.fm",
+        api_key: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        verify_ssl: bool = True,
+        preferred_format: Optional[AudioFormat] = None,
+        **kwargs
+    ):
+        """
+        Initialize the TTS client.
+
+        Args:
+            base_url: Base URL for the TTS service
+            api_key: API key for authentication
+            timeout: Request timeout in seconds
+            max_retries: Maximum retry attempts
+            verify_ssl: Whether to verify SSL certificates
+            preferred_format: Preferred audio format (affects header selection)
+            **kwargs: Additional configuration options
+        """
+        self.base_url = base_url.rstrip('/')
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.verify_ssl = verify_ssl
+        self.preferred_format = preferred_format or AudioFormat.WAV
+        
+        # Validate base URL
+        if not validate_url(self.base_url):
+            raise ValidationException(f"Invalid base URL: {self.base_url}")
+        
+        # Setup HTTP session with retry strategy
+        self.session = requests.Session()
+
+        # Configure retry strategy
+        retry_strategy = Retry(
+            total=max_retries,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["HEAD", "GET", "POST"],  # Updated parameter name
+            backoff_factor=1
+        )
+
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+
+        # Set default headers
+        self.session.headers.update(get_realistic_headers())
+
+        if self.api_key:
+            self.session.headers["Authorization"] = f"Bearer {self.api_key}"
+        
+        logger.info(f"Initialized TTS client with base URL: {self.base_url}")
+
+    def _get_headers_for_format(self, requested_format: AudioFormat) -> Dict[str, str]:
+        """
+        Get appropriate headers to get the desired format from openai.fm.
+
+        Based on testing, openai.fm returns:
+        - MP3: When using simple/minimal headers
+        - WAV: When using full Chrome security headers
+
+        Args:
+            requested_format: The desired audio format
+
+        Returns:
+            Dict[str, str]: HTTP headers optimized for the requested format
+        """
+        from .models import get_supported_format
+
+        # Map requested format to supported format
+        target_format = get_supported_format(requested_format)
+
+        if target_format == AudioFormat.MP3:
+            # Use minimal headers to get MP3 response
+            return {
+                'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
+                'Accept': 'audio/*,*/*;q=0.9'
+            }
+        else:
+            # Use full realistic headers to get WAV response
+            # This works for WAV, OPUS, AAC, FLAC, PCM formats
+            return get_realistic_headers()
+
+    def generate_speech(
+        self,
+        text: str,
+        voice: Union[Voice, str] = Voice.ALLOY,
+        response_format: Union[AudioFormat, str] = AudioFormat.MP3,
+        instructions: Optional[str] = None,
+        max_length: int = 4096,
+        validate_length: bool = True,
+        **kwargs
+    ) -> TTSResponse:
+        """
+        Generate speech from text.
+
+        Args:
+            text: Text to convert to speech
+            voice: Voice to use for generation
+            response_format: Audio format for output
+            instructions: Optional instructions for voice modulation
+            max_length: Maximum allowed text length in characters (default: 4096)
+            validate_length: Whether to validate text length (default: True)
+            **kwargs: Additional parameters
+
+        Returns:
+            TTSResponse: Generated audio response
+
+        Raises:
+            TTSException: If generation fails
+            ValueError: If text exceeds max_length and validate_length is True
+        """
+        # Create and validate request
+        request = TTSRequest(
+            input=sanitize_text(text),
+            voice=voice,
+            response_format=response_format,
+            instructions=instructions,
+            max_length=max_length,
+            validate_length=validate_length,
+            **kwargs
+        )
+
+        return self._make_request(request)
+    
+    def generate_speech_from_request(self, request: TTSRequest) -> TTSResponse:
+        """
+        Generate speech from a TTSRequest object.
+
+        Args:
+            request: TTS request object
+
+        Returns:
+            TTSResponse: Generated audio response
+        """
+        return self._make_request(request)
+
+    def generate_speech_batch(
+        self,
+        text: str,
+        voice: Union[Voice, str] = Voice.ALLOY,
+        response_format: Union[AudioFormat, str] = AudioFormat.MP3,
+        instructions: Optional[str] = None,
+        max_length: int = 4096,
+        preserve_words: bool = True,
+        **kwargs
+    ) -> List[TTSResponse]:
+        """
+        Generate speech from long text by splitting it into chunks.
+
+        This method automatically splits text that exceeds max_length into
+        smaller chunks and generates speech for each chunk separately.
+
+        Args:
+            text: Text to convert to speech
+            voice: Voice to use for generation
+            response_format: Audio format for output
+            instructions: Optional instructions for voice modulation
+            max_length: Maximum length per chunk (default: 4096)
+            preserve_words: Whether to avoid splitting words (default: True)
+            **kwargs: Additional parameters
+
+        Returns:
+            List[TTSResponse]: List of generated audio responses
+
+        Raises:
+            TTSException: If generation fails for any chunk
+        """
+
+        # Sanitize text first
+        clean_text = sanitize_text(text)
+
+        # Split text into chunks
+        chunks = split_text_by_length(clean_text, max_length, preserve_words)
+
+        if not chunks:
+            raise ValueError("No valid text chunks found after processing")
+
+        responses = []
+
+        for i, chunk in enumerate(chunks):
+            logger.info(f"Processing chunk {i+1}/{len(chunks)} ({len(chunk)} characters)")
+
+            # Create request for this chunk (disable length validation since we already split)
+            request = TTSRequest(
+                input=chunk,
+                voice=voice,
+                response_format=response_format,
+                instructions=instructions,
+                max_length=max_length,
+                validate_length=False,  # We already split the text
+                **kwargs
+            )
+
+            response = self._make_request(request)
+            responses.append(response)
+
+        return responses
+    
+    def _make_request(self, request: TTSRequest) -> TTSResponse:
+        """
+        Make the actual HTTP request to the openai.fm TTS service.
+
+        Args:
+            request: TTS request object
+
+        Returns:
+            TTSResponse: Generated audio response
+
+        Raises:
+            TTSException: If request fails
+        """
+        url = build_url(self.base_url, "api/generate")
+
+        # Prepare form data for openai.fm API
+        form_data = {
+            'input': request.input,
+            'voice': request.voice.value,
+            'generation': str(uuid.uuid4()),
+            'response_format': request.response_format.value if hasattr(request.response_format, 'value') else str(request.response_format)
+        }
+
+        # Add prompt/instructions if provided
+        if request.instructions:
+            form_data['prompt'] = request.instructions
+        else:
+            # Default prompt for better quality
+            form_data['prompt'] = (
+                "Affect/personality: Natural and clear\n\n"
+                "Tone: Friendly and professional, creating a pleasant listening experience.\n\n"
+                "Pronunciation: Clear, articulate, and steady, ensuring each word is easily understood "
+                "while maintaining a natural, conversational flow.\n\n"
+                "Pause: Brief, purposeful pauses between sentences to allow time for the listener "
+                "to process the information.\n\n"
+                "Emotion: Warm and engaging, conveying the intended message effectively."
+            )
+
+        # Get optimized headers for the requested format
+        # Convert string format to AudioFormat enum if needed
+        requested_format = request.response_format
+        if isinstance(requested_format, str):
+            try:
+                requested_format = AudioFormat(requested_format.lower())
+            except ValueError:
+                requested_format = AudioFormat.WAV  # Default to WAV for unknown formats
+
+        format_headers = self._get_headers_for_format(requested_format)
+
+        logger.info(f"Generating speech for text: '{request.input[:50]}...' with voice: {request.voice}")
+        logger.debug(f"Using headers optimized for {requested_format.value} format")
+
+        # Make request with retries
+        for attempt in range(self.max_retries + 1):
+            try:
+                # Add random delay for rate limiting (except first attempt)
+                if attempt > 0:
+                    delay = exponential_backoff(attempt - 1)
+                    logger.info(f"Retrying request after {delay:.2f}s (attempt {attempt + 1})")
+                    time.sleep(delay)
+
+                # Use multipart form data as required by openai.fm
+                response = self.session.post(
+                    url,
+                    data=form_data,
+                    headers=format_headers,
+                    timeout=self.timeout,
+                    verify=self.verify_ssl
+                )
+                
+                # Handle different response types
+                if response.status_code == 200:
+                    return self._process_openai_fm_response(response, request)
+                else:
+                    # Try to parse error response
+                    try:
+                        error_data = response.json()
+                    except (json.JSONDecodeError, ValueError):
+                        error_data = {"error": {"message": response.text or "Unknown error"}}
+                    
+                    # Create appropriate exception
+                    exception = create_exception_from_response(
+                        response.status_code,
+                        error_data,
+                        f"TTS request failed with status {response.status_code}"
+                    )
+                    
+                    # Don't retry for certain errors
+                    if response.status_code in [400, 401, 403, 404]:
+                        raise exception
+                    
+                    # For retryable errors, continue to next attempt
+                    if attempt == self.max_retries:
+                        raise exception
+                    
+                    logger.warning(f"Request failed with status {response.status_code}, retrying...")
+                    continue
+                    
+            except requests.exceptions.Timeout:
+                if attempt == self.max_retries:
+                    raise NetworkException(
+                        f"Request timed out after {self.timeout}s",
+                        timeout=self.timeout,
+                        retry_count=attempt
+                    )
+                logger.warning(f"Request timed out, retrying...")
+                continue
+                
+            except requests.exceptions.ConnectionError as e:
+                if attempt == self.max_retries:
+                    raise NetworkException(
+                        f"Connection error: {str(e)}",
+                        retry_count=attempt
+                    )
+                logger.warning(f"Connection error, retrying...")
+                continue
+                
+            except requests.exceptions.RequestException as e:
+                if attempt == self.max_retries:
+                    raise NetworkException(
+                        f"Request error: {str(e)}",
+                        retry_count=attempt
+                    )
+                logger.warning(f"Request error, retrying...")
+                continue
+        
+        # This should never be reached, but just in case
+        raise TTSException("Maximum retries exceeded")
+    
+    def _process_openai_fm_response(self, response: requests.Response, request: TTSRequest) -> TTSResponse:
+        """
+        Process a successful response from the openai.fm TTS service.
+
+        Args:
+            response: HTTP response object
+            request: Original TTS request
+
+        Returns:
+            TTSResponse: Processed response object
+        """
+        # Get content type from response headers
+        content_type = response.headers.get("content-type", "audio/mpeg")
+
+        # Get audio data
+        audio_data = response.content
+
+        if not audio_data:
+            raise APIException("Received empty audio data from openai.fm")
+
+        # Determine format from content type
+        if "audio/mpeg" in content_type or "audio/mp3" in content_type:
+            actual_format = AudioFormat.MP3
+        elif "audio/wav" in content_type:
+            actual_format = AudioFormat.WAV
+        elif "audio/opus" in content_type:
+            actual_format = AudioFormat.OPUS
+        elif "audio/aac" in content_type:
+            actual_format = AudioFormat.AAC
+        elif "audio/flac" in content_type:
+            actual_format = AudioFormat.FLAC
+        else:
+            # Default to MP3 for openai.fm
+            actual_format = AudioFormat.MP3
+
+        # Estimate duration based on text length (rough approximation)
+        estimated_duration = estimate_audio_duration(request.input)
+
+        # Check if returned format differs from requested format
+        requested_format = request.response_format
+        if isinstance(requested_format, str):
+            try:
+                requested_format = AudioFormat(requested_format.lower())
+            except ValueError:
+                requested_format = AudioFormat.WAV  # Default fallback
+
+        # Import here to avoid circular imports
+        from .models import get_supported_format, maps_to_wav
+
+        # Check if format differs from request
+        if actual_format != requested_format:
+            if maps_to_wav(requested_format.value) and actual_format.value == "wav":
+                logger.debug(
+                    f"Format '{requested_format.value}' requested, returning WAV format."
+                )
+            else:
+                logger.warning(
+                    f"Requested format '{requested_format.value}' but received '{actual_format.value}' "
+                    f"from service."
+                )
+
+        # Create response object
+        tts_response = TTSResponse(
+            audio_data=audio_data,
+            content_type=content_type,
+            format=actual_format,
+            size=len(audio_data),
+            duration=estimated_duration,
+            metadata={
+                "response_headers": dict(response.headers),
+                "status_code": response.status_code,
+                "url": str(response.url),
+                "service": "openai.fm",
+                "voice": request.voice.value,
+                "original_text": request.input[:100] + "..." if len(request.input) > 100 else request.input,
+                "requested_format": requested_format.value,
+                "actual_format": actual_format.value
+            }
+        )
+
+        logger.info(
+            f"Successfully generated {format_file_size(len(audio_data))} "
+            f"of {actual_format.value.upper()} audio from openai.fm using voice '{request.voice.value}'"
+        )
+
+        return tts_response
+    
+    def close(self):
+        """Close the HTTP session."""
+        if hasattr(self, 'session'):
+            self.session.close()
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()

ttsfm/exceptions.py

@@ -0,0 +1,243 @@
+"""
+Exception classes for the TTSFM package.
+
+This module defines the exception hierarchy used throughout the package
+for consistent error handling and reporting.
+"""
+
+from typing import Optional, Dict, Any
+
+
+class TTSException(Exception):
+    """
+    Base exception class for all TTSFM-related errors.
+    
+    Attributes:
+        message: Human-readable error message
+        code: Error code for programmatic handling
+        details: Additional error details
+    """
+    
+    def __init__(
+        self, 
+        message: str, 
+        code: Optional[str] = None, 
+        details: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code or self.__class__.__name__
+        self.details = details or {}
+    
+    def __str__(self) -> str:
+        if self.code:
+            return f"[{self.code}] {self.message}"
+        return self.message
+    
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message='{self.message}', code='{self.code}')"
+
+
+class APIException(TTSException):
+    """
+    Exception raised for API-related errors.
+    
+    This includes HTTP errors, invalid responses, and server-side issues.
+    """
+    
+    def __init__(
+        self, 
+        message: str, 
+        status_code: Optional[int] = None,
+        response_data: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ):
+        super().__init__(message, **kwargs)
+        self.status_code = status_code
+        self.response_data = response_data or {}
+    
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[HTTP {self.status_code}] {self.message}"
+        return super().__str__()
+
+
+class NetworkException(TTSException):
+    """
+    Exception raised for network-related errors.
+    
+    This includes connection timeouts, DNS resolution failures, and other
+    network connectivity issues.
+    """
+    
+    def __init__(
+        self, 
+        message: str, 
+        timeout: Optional[float] = None,
+        retry_count: int = 0,
+        **kwargs
+    ):
+        super().__init__(message, **kwargs)
+        self.timeout = timeout
+        self.retry_count = retry_count
+
+
+class ValidationException(TTSException):
+    """
+    Exception raised for input validation errors.
+    
+    This includes invalid parameters, missing required fields, and
+    data format issues.
+    """
+    
+    def __init__(
+        self, 
+        message: str, 
+        field: Optional[str] = None,
+        value: Optional[Any] = None,
+        **kwargs
+    ):
+        super().__init__(message, **kwargs)
+        self.field = field
+        self.value = value
+    
+    def __str__(self) -> str:
+        if self.field:
+            return f"Validation error for '{self.field}': {self.message}"
+        return f"Validation error: {self.message}"
+
+
+class RateLimitException(APIException):
+    """
+    Exception raised when API rate limits are exceeded.
+    
+    Attributes:
+        retry_after: Seconds to wait before retrying (if provided by server)
+        limit: Rate limit that was exceeded
+        remaining: Remaining requests in current window
+    """
+    
+    def __init__(
+        self, 
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[int] = None,
+        limit: Optional[int] = None,
+        remaining: Optional[int] = None,
+        **kwargs
+    ):
+        super().__init__(message, status_code=429, **kwargs)
+        self.retry_after = retry_after
+        self.limit = limit
+        self.remaining = remaining
+    
+    def __str__(self) -> str:
+        msg = super().__str__()
+        if self.retry_after:
+            msg += f" (retry after {self.retry_after}s)"
+        return msg
+
+
+class AuthenticationException(APIException):
+    """
+    Exception raised for authentication and authorization errors.
+    
+    This includes invalid API keys, expired tokens, and insufficient
+    permissions.
+    """
+    
+    def __init__(
+        self, 
+        message: str = "Authentication failed",
+        **kwargs
+    ):
+        super().__init__(message, status_code=401, **kwargs)
+
+
+class ServiceUnavailableException(APIException):
+    """
+    Exception raised when the TTS service is temporarily unavailable.
+    
+    This includes server maintenance, overload conditions, and
+    temporary service outages.
+    """
+    
+    def __init__(
+        self, 
+        message: str = "Service temporarily unavailable",
+        retry_after: Optional[int] = None,
+        **kwargs
+    ):
+        super().__init__(message, status_code=503, **kwargs)
+        self.retry_after = retry_after
+
+
+class QuotaExceededException(APIException):
+    """
+    Exception raised when usage quotas are exceeded.
+    
+    This includes monthly limits, character limits, and other
+    usage-based restrictions.
+    """
+    
+    def __init__(
+        self, 
+        message: str = "Usage quota exceeded",
+        quota_type: Optional[str] = None,
+        limit: Optional[int] = None,
+        used: Optional[int] = None,
+        **kwargs
+    ):
+        super().__init__(message, status_code=402, **kwargs)
+        self.quota_type = quota_type
+        self.limit = limit
+        self.used = used
+
+
+class AudioProcessingException(TTSException):
+    """
+    Exception raised for audio processing errors.
+    
+    This includes format conversion issues, audio generation failures,
+    and output processing problems.
+    """
+    
+    def __init__(
+        self, 
+        message: str,
+        audio_format: Optional[str] = None,
+        **kwargs
+    ):
+        super().__init__(message, **kwargs)
+        self.audio_format = audio_format
+
+
+def create_exception_from_response(
+    status_code: int, 
+    response_data: Dict[str, Any],
+    default_message: str = "API request failed"
+) -> APIException:
+    """
+    Create appropriate exception from API response.
+    
+    Args:
+        status_code: HTTP status code
+        response_data: Response data from API
+        default_message: Default message if none in response
+        
+    Returns:
+        APIException: Appropriate exception instance
+    """
+    message = response_data.get("error", {}).get("message", default_message)
+    
+    if status_code == 401:
+        return AuthenticationException(message, response_data=response_data)
+    elif status_code == 402:
+        return QuotaExceededException(message, response_data=response_data)
+    elif status_code == 429:
+        retry_after = response_data.get("retry_after")
+        return RateLimitException(message, retry_after=retry_after, response_data=response_data)
+    elif status_code == 503:
+        retry_after = response_data.get("retry_after")
+        return ServiceUnavailableException(message, retry_after=retry_after, response_data=response_data)
+    else:
+        return APIException(message, status_code=status_code, response_data=response_data)

ttsfm/models.py

@@ -0,0 +1,283 @@
+"""
+Data models and types for the TTSFM package.
+
+This module defines the core data structures used throughout the package,
+including request/response models, enums, and error types.
+"""
+
+from enum import Enum
+from typing import Optional, Dict, Any, Union
+from dataclasses import dataclass
+from datetime import datetime
+
+
+class Voice(str, Enum):
+    """Available voice options for TTS generation."""
+    ALLOY = "alloy"
+    ASH = "ash"
+    BALLAD = "ballad"
+    CORAL = "coral"
+    ECHO = "echo"
+    FABLE = "fable"
+    NOVA = "nova"
+    ONYX = "onyx"
+    SAGE = "sage"
+    SHIMMER = "shimmer"
+    VERSE = "verse"
+
+
+class AudioFormat(str, Enum):
+    """Supported audio output formats."""
+    MP3 = "mp3"
+    WAV = "wav"
+    OPUS = "opus"
+    AAC = "aac"
+    FLAC = "flac"
+    PCM = "pcm"
+
+
+@dataclass
+class TTSRequest:
+    """
+    Request model for TTS generation.
+
+    Attributes:
+        input: Text to convert to speech
+        voice: Voice to use for generation
+        response_format: Audio format for output
+        instructions: Optional instructions for voice modulation
+        model: Model to use (for OpenAI compatibility, usually ignored)
+        speed: Speech speed (for OpenAI compatibility, usually ignored)
+        max_length: Maximum allowed text length (default: 4096 characters)
+        validate_length: Whether to validate text length (default: True)
+    """
+    input: str
+    voice: Union[Voice, str] = Voice.ALLOY
+    response_format: Union[AudioFormat, str] = AudioFormat.MP3
+    instructions: Optional[str] = None
+    model: Optional[str] = None
+    speed: Optional[float] = None
+    max_length: int = 4096
+    validate_length: bool = True
+    
+    def __post_init__(self):
+        """Validate and normalize fields after initialization."""
+        # Ensure voice is a valid Voice enum
+        if isinstance(self.voice, str):
+            try:
+                self.voice = Voice(self.voice.lower())
+            except ValueError:
+                raise ValueError(f"Invalid voice: {self.voice}. Must be one of {list(Voice)}")
+
+        # Ensure response_format is a valid AudioFormat enum
+        if isinstance(self.response_format, str):
+            try:
+                self.response_format = AudioFormat(self.response_format.lower())
+            except ValueError:
+                raise ValueError(f"Invalid format: {self.response_format}. Must be one of {list(AudioFormat)}")
+
+        # Validate input text
+        if not self.input or not self.input.strip():
+            raise ValueError("Input text cannot be empty")
+
+        # Validate text length if enabled
+        if self.validate_length:
+            text_length = len(self.input)
+            if text_length > self.max_length:
+                raise ValueError(
+                    f"Input text is too long ({text_length} characters). "
+                    f"Maximum allowed length is {self.max_length} characters. "
+                    f"Consider splitting your text into smaller chunks or disable "
+                    f"length validation with validate_length=False."
+                )
+
+        # Validate max_length parameter
+        if self.max_length <= 0:
+            raise ValueError("max_length must be a positive integer")
+
+        # Validate speed if provided
+        if self.speed is not None and (self.speed < 0.25 or self.speed > 4.0):
+            raise ValueError("Speed must be between 0.25 and 4.0")
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert request to dictionary for API calls."""
+        data = {
+            "input": self.input,
+            "voice": self.voice.value if isinstance(self.voice, Voice) else self.voice,
+            "response_format": self.response_format.value if isinstance(self.response_format, AudioFormat) else self.response_format
+        }
+        
+        if self.instructions:
+            data["instructions"] = self.instructions
+        
+        if self.model:
+            data["model"] = self.model
+            
+        if self.speed is not None:
+            data["speed"] = self.speed
+            
+        return data
+
+
+@dataclass
+class TTSResponse:
+    """
+    Response model for TTS generation.
+    
+    Attributes:
+        audio_data: Generated audio as bytes
+        content_type: MIME type of the audio data
+        format: Audio format used
+        size: Size of audio data in bytes
+        duration: Estimated duration in seconds (if available)
+        metadata: Additional response metadata
+    """
+    audio_data: bytes
+    content_type: str
+    format: AudioFormat
+    size: int
+    duration: Optional[float] = None
+    metadata: Optional[Dict[str, Any]] = None
+    
+    def __post_init__(self):
+        """Calculate derived fields after initialization."""
+        if self.size is None:
+            self.size = len(self.audio_data)
+    
+    def save_to_file(self, filename: str) -> str:
+        """
+        Save audio data to a file.
+
+        Args:
+            filename: Target filename (extension will be added if missing)
+
+        Returns:
+            str: Final filename used
+        """
+        import os
+
+        # Use the actual returned format for the extension, not any requested format
+        expected_extension = f".{self.format.value}"
+
+        # Check if filename already has the correct extension
+        if filename.endswith(expected_extension):
+            final_filename = filename
+        else:
+            # Remove any existing extension and add the correct one
+            base_name = filename
+            # Remove common audio extensions if present
+            for ext in ['.mp3', '.wav', '.opus', '.aac', '.flac', '.pcm']:
+                if base_name.endswith(ext):
+                    base_name = base_name[:-len(ext)]
+                    break
+            final_filename = f"{base_name}{expected_extension}"
+
+        # Create directory if it doesn't exist
+        os.makedirs(os.path.dirname(final_filename) if os.path.dirname(final_filename) else ".", exist_ok=True)
+
+        # Write audio data
+        with open(final_filename, "wb") as f:
+            f.write(self.audio_data)
+
+        return final_filename
+
+
+@dataclass
+class TTSError:
+    """
+    Error information from TTS API.
+    
+    Attributes:
+        code: Error code
+        message: Human-readable error message
+        type: Error type/category
+        details: Additional error details
+        timestamp: When the error occurred
+    """
+    code: str
+    message: str
+    type: Optional[str] = None
+    details: Optional[Dict[str, Any]] = None
+    timestamp: Optional[datetime] = None
+    
+    def __post_init__(self):
+        """Set timestamp if not provided."""
+        if self.timestamp is None:
+            self.timestamp = datetime.now()
+
+
+@dataclass
+class APIError(TTSError):
+    """API-specific error information."""
+    status_code: int = 500
+    headers: Optional[Dict[str, str]] = None
+
+
+@dataclass
+class NetworkError(TTSError):
+    """Network-related error information."""
+    timeout: Optional[float] = None
+    retry_count: int = 0
+
+
+@dataclass
+class ValidationError(TTSError):
+    """Validation error information."""
+    field: Optional[str] = None
+    value: Optional[Any] = None
+
+
+# Content type mappings for audio formats
+CONTENT_TYPE_MAP = {
+    AudioFormat.MP3: "audio/mpeg",
+    AudioFormat.OPUS: "audio/opus",
+    AudioFormat.AAC: "audio/aac",
+    AudioFormat.FLAC: "audio/flac",
+    AudioFormat.WAV: "audio/wav",
+    AudioFormat.PCM: "audio/pcm"
+}
+
+# Reverse mapping for content type to format
+FORMAT_FROM_CONTENT_TYPE = {v: k for k, v in CONTENT_TYPE_MAP.items()}
+
+
+def get_content_type(format: Union[AudioFormat, str]) -> str:
+    """Get MIME content type for audio format."""
+    if isinstance(format, str):
+        format = AudioFormat(format.lower())
+    return CONTENT_TYPE_MAP.get(format, "audio/mpeg")
+
+
+def get_format_from_content_type(content_type: str) -> AudioFormat:
+    """Get audio format from MIME content type."""
+    return FORMAT_FROM_CONTENT_TYPE.get(content_type, AudioFormat.MP3)
+
+
+def get_supported_format(requested_format: AudioFormat) -> AudioFormat:
+    """
+    Map requested format to supported format.
+
+    Args:
+        requested_format: The requested audio format
+
+    Returns:
+        AudioFormat: MP3 or WAV (the supported formats)
+    """
+    if requested_format == AudioFormat.MP3:
+        return AudioFormat.MP3
+    else:
+        # All other formats (WAV, OPUS, AAC, FLAC, PCM) return WAV
+        return AudioFormat.WAV
+
+
+def maps_to_wav(format_value: str) -> bool:
+    """
+    Check if a format maps to WAV.
+
+    Args:
+        format_value: Format string to check
+
+    Returns:
+        bool: True if the format maps to WAV
+    """
+    return format_value.lower() in ['wav', 'opus', 'aac', 'flac', 'pcm']

ttsfm/utils.py

@@ -0,0 +1,421 @@
+"""
+Utility functions for the TTSFM package.
+
+This module provides common utility functions used throughout the package,
+including HTTP helpers, validation utilities, and configuration management.
+"""
+
+import os
+import re
+import time
+import random
+import logging
+from typing import Dict, Any, Optional, Union, List
+from urllib.parse import urljoin, urlparse
+
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+def get_user_agent() -> str:
+    """
+    Generate a realistic User-Agent string.
+    
+    Returns:
+        str: User-Agent string for HTTP requests
+    """
+    try:
+        from fake_useragent import UserAgent
+        ua = UserAgent()
+        return ua.random
+    except ImportError:
+        # Fallback if fake_useragent is not available
+        return "TTSFM-Client/3.0.0 (Python)"
+
+
+def get_realistic_headers() -> Dict[str, str]:
+    """
+    Generate realistic HTTP headers for requests.
+    
+    Returns:
+        Dict[str, str]: HTTP headers dictionary
+    """
+    user_agent = get_user_agent()
+    
+    headers = {
+        "Accept": "application/json, audio/*",
+        "Accept-Encoding": "gzip, deflate, br",
+        "Accept-Language": random.choice(["en-US,en;q=0.9", "en-GB,en;q=0.8", "en-CA,en;q=0.7"]),
+        "Cache-Control": "no-cache",
+        "DNT": "1",
+        "Pragma": "no-cache",
+        "User-Agent": user_agent,
+        "X-Requested-With": "XMLHttpRequest",
+    }
+    
+    # Add browser-specific headers for Chromium-based browsers
+    if any(browser in user_agent.lower() for browser in ['chrome', 'edge', 'chromium']):
+        version_match = re.search(r'(?:Chrome|Edge|Chromium)/(\d+)', user_agent)
+        major_version = version_match.group(1) if version_match else "121"
+        
+        brands = []
+        if 'google chrome' in user_agent.lower():
+            brands.extend([
+                f'"Google Chrome";v="{major_version}"',
+                f'"Chromium";v="{major_version}"',
+                '"Not A(Brand";v="99"'
+            ])
+        elif 'microsoft edge' in user_agent.lower():
+            brands.extend([
+                f'"Microsoft Edge";v="{major_version}"',
+                f'"Chromium";v="{major_version}"',
+                '"Not A(Brand";v="99"'
+            ])
+        else:
+            brands.extend([
+                f'"Chromium";v="{major_version}"',
+                '"Not A(Brand";v="8"'
+            ])
+        
+        headers.update({
+            "Sec-Ch-Ua": ", ".join(brands),
+            "Sec-Ch-Ua-Mobile": "?0",
+            "Sec-Ch-Ua-Platform": random.choice(['"Windows"', '"macOS"', '"Linux"']),
+            "Sec-Fetch-Dest": "empty",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Site": "same-origin"
+        })
+    
+    # Randomly add some optional headers
+    if random.random() < 0.5:
+        headers["Upgrade-Insecure-Requests"] = "1"
+    
+    return headers
+
+
+def validate_text_length(text: str, max_length: int = 4096, raise_error: bool = True) -> bool:
+    """
+    Validate text length against maximum allowed characters.
+
+    Args:
+        text: Text to validate
+        max_length: Maximum allowed length in characters
+        raise_error: Whether to raise an exception if validation fails
+
+    Returns:
+        bool: True if text is within limits, False otherwise
+
+    Raises:
+        ValueError: If text exceeds max_length and raise_error is True
+    """
+    if not text:
+        return True
+
+    text_length = len(text)
+
+    if text_length > max_length:
+        if raise_error:
+            raise ValueError(
+                f"Text is too long ({text_length} characters). "
+                f"Maximum allowed length is {max_length} characters. "
+                f"TTS models typically support up to 4096 characters per request."
+            )
+        return False
+
+    return True
+
+
+def split_text_by_length(text: str, max_length: int = 4096, preserve_words: bool = True) -> List[str]:
+    """
+    Split text into chunks that don't exceed the maximum length.
+
+    Args:
+        text: Text to split
+        max_length: Maximum length per chunk
+        preserve_words: Whether to avoid splitting words
+
+    Returns:
+        List[str]: List of text chunks
+    """
+    if not text:
+        return []
+
+    if len(text) <= max_length:
+        return [text]
+
+    chunks = []
+
+    if preserve_words:
+        # Split by sentences first, then by words if needed
+        sentences = re.split(r'[.!?]+', text)
+        current_chunk = ""
+
+        for sentence in sentences:
+            sentence = sentence.strip()
+            if not sentence:
+                continue
+
+            # Add sentence ending punctuation back
+            if not sentence.endswith(('.', '!', '?')):
+                sentence += '.'
+
+            # Check if adding this sentence would exceed the limit
+            test_chunk = current_chunk + (" " if current_chunk else "") + sentence
+
+            if len(test_chunk) <= max_length:
+                current_chunk = test_chunk
+            else:
+                # Save current chunk if it has content
+                if current_chunk:
+                    chunks.append(current_chunk.strip())
+
+                # If single sentence is too long, split by words
+                if len(sentence) > max_length:
+                    word_chunks = _split_by_words(sentence, max_length)
+                    chunks.extend(word_chunks)
+                    current_chunk = ""
+                else:
+                    current_chunk = sentence
+
+        # Add remaining chunk
+        if current_chunk:
+            chunks.append(current_chunk.strip())
+    else:
+        # Simple character-based splitting
+        for i in range(0, len(text), max_length):
+            chunks.append(text[i:i + max_length])
+
+    return [chunk for chunk in chunks if chunk.strip()]
+
+
+def _split_by_words(text: str, max_length: int) -> List[str]:
+    """
+    Split text by words when sentences are too long.
+
+    Args:
+        text: Text to split
+        max_length: Maximum length per chunk
+
+    Returns:
+        List[str]: List of word-based chunks
+    """
+    words = text.split()
+    chunks = []
+    current_chunk = ""
+
+    for word in words:
+        test_chunk = current_chunk + (" " if current_chunk else "") + word
+
+        if len(test_chunk) <= max_length:
+            current_chunk = test_chunk
+        else:
+            if current_chunk:
+                chunks.append(current_chunk)
+
+            # If single word is too long, split it
+            if len(word) > max_length:
+                for i in range(0, len(word), max_length):
+                    chunks.append(word[i:i + max_length])
+                current_chunk = ""
+            else:
+                current_chunk = word
+
+    if current_chunk:
+        chunks.append(current_chunk)
+
+    return chunks
+
+
+def sanitize_text(text: str) -> str:
+    """
+    Sanitize input text for TTS processing.
+
+    Args:
+        text: Input text to sanitize
+
+    Returns:
+        str: Sanitized text
+    """
+    if not text:
+        return ""
+
+    # Remove HTML tags
+    text = re.sub(r'<[^>]+>', '', text)
+
+    # Remove script tags and content
+    text = re.sub(r'<script.*?</script>', '', text, flags=re.DOTALL | re.IGNORECASE)
+
+    # Remove potentially dangerous characters
+    text = re.sub(r'[<>"\']', '', text)
+
+    # Normalize whitespace
+    text = re.sub(r'\s+', ' ', text)
+
+    return text.strip()
+
+
+def validate_url(url: str) -> bool:
+    """
+    Validate if a URL is properly formatted.
+    
+    Args:
+        url: URL to validate
+        
+    Returns:
+        bool: True if URL is valid, False otherwise
+    """
+    try:
+        result = urlparse(url)
+        return all([result.scheme, result.netloc])
+    except Exception:
+        return False
+
+
+def build_url(base_url: str, path: str) -> str:
+    """
+    Build a complete URL from base URL and path.
+    
+    Args:
+        base_url: Base URL
+        path: Path to append
+        
+    Returns:
+        str: Complete URL
+    """
+    # Ensure base_url ends with /
+    if not base_url.endswith('/'):
+        base_url += '/'
+    
+    # Ensure path doesn't start with /
+    if path.startswith('/'):
+        path = path[1:]
+    
+    return urljoin(base_url, path)
+
+
+def get_random_delay(min_delay: float = 1.0, max_delay: float = 5.0) -> float:
+    """
+    Get a random delay with jitter for rate limiting.
+    
+    Args:
+        min_delay: Minimum delay in seconds
+        max_delay: Maximum delay in seconds
+        
+    Returns:
+        float: Random delay in seconds
+    """
+    base_delay = random.uniform(min_delay, max_delay)
+    jitter = random.uniform(0.1, 0.5)
+    return base_delay + jitter
+
+
+def exponential_backoff(attempt: int, base_delay: float = 1.0, max_delay: float = 60.0) -> float:
+    """
+    Calculate exponential backoff delay.
+    
+    Args:
+        attempt: Attempt number (0-based)
+        base_delay: Base delay in seconds
+        max_delay: Maximum delay in seconds
+        
+    Returns:
+        float: Delay in seconds
+    """
+    delay = base_delay * (2 ** attempt)
+    jitter = random.uniform(0.1, 0.3) * delay
+    return min(delay + jitter, max_delay)
+
+
+def load_config_from_env(prefix: str = "TTSFM_") -> Dict[str, Any]:
+    """
+    Load configuration from environment variables.
+    
+    Args:
+        prefix: Prefix for environment variables
+        
+    Returns:
+        Dict[str, Any]: Configuration dictionary
+    """
+    config = {}
+    
+    for key, value in os.environ.items():
+        if key.startswith(prefix):
+            config_key = key[len(prefix):].lower()
+            
+            # Try to convert to appropriate type
+            if value.lower() in ('true', 'false'):
+                config[config_key] = value.lower() == 'true'
+            elif value.isdigit():
+                config[config_key] = int(value)
+            elif '.' in value and value.replace('.', '').isdigit():
+                config[config_key] = float(value)
+            else:
+                config[config_key] = value
+    
+    return config
+
+
+def setup_logging(level: Union[str, int] = logging.INFO, format_string: Optional[str] = None) -> None:
+    """
+    Setup logging configuration for the package.
+    
+    Args:
+        level: Logging level
+        format_string: Custom format string
+    """
+    if format_string is None:
+        format_string = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    
+    logging.basicConfig(
+        level=level,
+        format=format_string,
+        handlers=[logging.StreamHandler()]
+    )
+
+
+def estimate_audio_duration(text: str, words_per_minute: float = 150.0) -> float:
+    """
+    Estimate audio duration based on text length.
+    
+    Args:
+        text: Input text
+        words_per_minute: Average speaking rate
+        
+    Returns:
+        float: Estimated duration in seconds
+    """
+    if not text:
+        return 0.0
+    
+    # Count words (simple whitespace split)
+    word_count = len(text.split())
+    
+    # Calculate duration in seconds
+    duration = (word_count / words_per_minute) * 60.0
+    
+    # Add some buffer for pauses and processing
+    return duration * 1.1
+
+
+def format_file_size(size_bytes: int) -> str:
+    """
+    Format file size in human-readable format.
+    
+    Args:
+        size_bytes: Size in bytes
+        
+    Returns:
+        str: Formatted size string
+    """
+    if size_bytes == 0:
+        return "0 B"
+    
+    size_names = ["B", "KB", "MB", "GB"]
+    i = 0
+    
+    while size_bytes >= 1024 and i < len(size_names) - 1:
+        size_bytes /= 1024.0
+        i += 1
+    
+    return f"{size_bytes:.1f} {size_names[i]}"