### Python Client Integration with Neutts German TTS Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Demonstrates how to integrate the Neutts German TTS service into Python applications. It shows usage with the OpenAI SDK for a familiar interface and direct HTTP requests for more control. The examples cover speech generation and retrieving timing information. ```python # Using OpenAI SDK import openai client = openai.OpenAI( base_url="http://localhost:8136/v1/", api_key="dummy" # API key not required but SDK needs a value ) # Generate speech response = client.audio.speech.create( model="gpt-4o-mini-tts", voice="greta", input="Hallo, wie geht es Ihnen heute?" ) # Save to file response.stream_to_file("output.mp3") # Using requests library import requests import base64 # Direct API call response = requests.post( "http://localhost:8136/v1/audio/speech", json={ "input": "Dies ist ein direkter API-Aufruf.", "voice": "mateo", "response_format": "wav" } ) with open("speech.wav", "wb") as f: f.write(response.content) # Get timing info via extended endpoint response = requests.post( "http://localhost:8136/synthesize", json={"text": "Mit Timing-Informationen."} ) data = response.json() audio_bytes = base64.b64decode(data["audio"]) print(f"Latency: {data['timing']['latency_ms']:.2f}ms") print(f"Duration: {data['timing']['duration_seconds']:.2f}s") ``` -------------------------------- ### Docker Compose CLI Commands Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt A set of essential command-line interface commands for managing the Neutts German TTS service deployed via Docker Compose. These commands cover starting, stopping, viewing logs, and running the service in the background. ```bash # Start the service docker-compose up --build # Run in background docker-compose up -d --build # View logs docker-compose logs -f neutts-german # Stop service docker-compose down ``` -------------------------------- ### GET /v1/voices - List Available Voices Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Retrieves a list of all available voices, including built-in German voices and any custom voices that have been loaded. ```APIDOC ## GET /v1/voices ### Description Retrieves a list of all available voices, including built-in German voices and any custom voices that have been loaded. ### Method GET ### Endpoint /v1/voices ### Parameters None ### Response #### Success Response (200) - **voices** (array) - A list of voice objects. - **voice_id** (string) - The unique identifier for the voice. - **name** (string) - The display name of the voice. - **language** (string) - The language code for the voice (e.g., "de"). - **has_reference** (boolean) - Indicates if a reference text is available for this voice. #### Response Example ```json { "voices": [ { "voice_id": "greta", "name": "German Greta (built-in)", "language": "de", "has_reference": true }, { "voice_id": "mateo", "name": "German Mateo (built-in)", "language": "de", "has_reference": true }, { "voice_id": "juliette", "name": "German Juliette (built-in)", "language": "de", "has_reference": true }, { "voice_id": "custom_voice", "name": "Custom voice: custom_voice", "language": "de", "has_reference": false } ] } ``` ``` -------------------------------- ### GET /health - Health Check Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Provides the current health status of the service, including whether the TTS model has been initialized and which voices are available. ```APIDOC ## GET /health ### Description Provides the current health status of the service, including whether the TTS model has been initialized and which voices are available. This endpoint is useful for monitoring and orchestration. ### Method GET ### Endpoint /health ### Parameters None ### Response #### Success Response (200) - **status** (string) - The overall status of the service (e.g., "healthy"). - **tts_initialized** (boolean) - Indicates if the Text-to-Speech model has been successfully loaded and initialized. - **available_voices** (array) - A list of voice IDs currently available for use. #### Response Example (Healthy) ```json { "status": "healthy", "tts_initialized": true, "available_voices": ["greta", "mateo", "juliette"] } ``` #### Response Example (During Startup) ```json { "status": "healthy", "tts_initialized": false, "available_voices": [] } ``` ``` -------------------------------- ### Docker Compose Deployment Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Instructions and configuration for deploying the service using Docker Compose, including model caching, custom voice mounting, and device configuration. ```APIDOC ## Docker Compose Deployment The service is designed for containerized deployment with Docker Compose, featuring automatic model caching, custom voice mounting, and configurable device settings for CPU or GPU operation. ```yaml # docker-compose.yml services: neutts-german: build: context: . dockerfile: Dockerfile container_name: neutts-german-api ports: - "8136:8136" volumes: # Mount custom voices directory - ${PWD}/voices:/app/voices # Cache for downloaded HuggingFace models - ${PWD}/model_cache:/app/model_cache environment: - HOST=0.0.0.0 - PORT=8136 - MODEL_REPO=neuphonic/neutts-nano-german-q4-gguf - CODEC_REPO=neuphonic/neucodec - BACKBONE_DEVICE=cpu - CODEC_DEVICE=cpu - VOICES_DIR=/app/voices - HF_HOME=/app/model_cache restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8136/health"] interval: 30s timeout: 10s retries: 3 start_period: 60s ``` ```bash # Start the service docker-compose up --build # Run in background docker-compose up -d --build # View logs docker-compose logs -f neutts-german # Stop service docker-compose down ``` ``` -------------------------------- ### TTSService Class API Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Details the core `TTSService` class methods for initializing the TTS model, managing voices, and synthesizing audio. ```APIDOC ## TTSService Class API The core `TTSService` class manages model initialization, voice caching, and audio synthesis. It provides methods for loading voices, generating speech, and streaming audio output. ```python from tts_service import tts_service # Initialize the TTS model (called automatically on first request) tts_service.initialize_tts() # Check initialization status if tts_service.is_initialized(): print("TTS ready") # Get available voices voices = tts_service.get_available_voices() # Returns: { # "greta": {"name": "German Greta (built-in)", "is_builtin": True, "has_ref_text": True}, # "mateo": {"name": "German Mateo (built-in)", "is_builtin": True, "has_ref_text": True}, # ... # } # Get voice reference data ref_codes, ref_text = tts_service.get_voice_data("greta") # Synthesize speech wav_data, timing = tts_service.synthesize( text="Guten Morgen!", voice_id="greta" ) # wav_data: bytes (WAV format) # timing: {"latency_ms": 245.3, "sample_rate": 24000, "duration_seconds": 1.2} # Save to file with open("output.wav", "wb") as f: f.write(wav_data) # Streaming synthesis (for real-time output) for audio_chunk in tts_service.synthesize_streaming("Langer Text...", "mateo"): # Process audio chunks as they're generated process_chunk(audio_chunk) # Reload custom voices at runtime available = tts_service.reload_custom_voices() print(f"Available voices: {available}") ``` ``` -------------------------------- ### Python Client Integration Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Demonstrates how to integrate the TTS service into Python applications using the OpenAI SDK or direct HTTP requests. ```APIDOC ## Python Client Integration The service integrates with Python applications through the OpenAI SDK or direct HTTP requests, making it easy to add German TTS capabilities to existing applications that already use OpenAI's API. ```python # Using OpenAI SDK import openai client = openai.OpenAI( base_url="http://localhost:8136/v1/", api_key="dummy" # API key not required but SDK needs a value ) # Generate speech response = client.audio.speech.create( model="gpt-4o-mini-tts", voice="greta", input="Hallo, wie geht es Ihnen heute?" ) # Save to file response.stream_to_file("output.mp3") # Using requests library import requests import base64 # Direct API call response = requests.post( "http://localhost:8136/v1/audio/speech", json={ "input": "Dies ist ein direkter API-Aufruf.", "voice": "mateo", "response_format": "wav" } ) with open("speech.wav", "wb") as f: f.write(response.content) # Get timing info via extended endpoint response = requests.post( "http://localhost:8136/synthesize", json={"text": "Mit Timing-Informationen."} ) data = response.json() audio_bytes = base64.b64decode(data["audio"]) print(f"Latency: {data['timing']['latency_ms']:.2f}ms") print(f"Duration: {data['timing']['duration_seconds']:.2f}s") ``` ``` -------------------------------- ### Basic Speech Synthesis with OpenAI-Compatible Endpoint Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Synthesizes German speech using the OpenAI-compatible `/v1/audio/speech` endpoint. Supports various output formats (MP3, WAV, OPUS) and built-in or custom voices. The endpoint maps OpenAI voice names to available German voices. ```bash curl -X POST http://localhost:8136/v1/audio/speech \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini-tts", "input": "Guten Tag! Willkommen bei der deutschen Sprachsynthese.", "voice": "greta", "response_format": "mp3" }' --output speech.mp3 curl -X POST http://localhost:8136/v1/audio/speech \ -H "Content-Type: application/json" \ -d '{ "input": "Dies ist ein Test mit der Stimme von Mateo.", "voice": "mateo", "response_format": "wav" }' --output speech.wav curl -X POST http://localhost:8136/v1/audio/speech \ -H "Content-Type: application/json" \ -d '{ "input": "OpenAI-Stimmenaliase werden automatisch zugeordnet.", "voice": "coral", "response_format": "opus" }' --output speech.opus ``` -------------------------------- ### Extended Synthesize Endpoint with Timing Information Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt An alternative TTS endpoint that provides base64-encoded audio along with detailed timing information and metadata about the synthesis process. It offers more control over synthesis parameters. ```bash curl -X POST http://localhost:8136/synthesize \ -H "Content-Type: application/json" \ -d '{ "text": "Dies ist ein erweiterter Synthesetest." }' ``` -------------------------------- ### POST /synthesize - Extended Synthesize Endpoint Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt An alternative TTS endpoint that returns base64-encoded audio with detailed timing information. Provides more control over synthesis parameters and returns metadata about the generation process. ```APIDOC ## POST /synthesize ### Description An alternative TTS endpoint that returns base64-encoded audio with detailed timing information. Provides more control over synthesis parameters and returns metadata about the generation process including latency, sample rate, and audio duration. ### Method POST ### Endpoint /synthesize ### Parameters #### Request Body - **text** (string) - Required - The text to synthesize. - **voice** (string) - Optional - The voice to use for synthesis. - **output_format** (string) - Optional - The desired output format (e.g., "mp3", "wav"). - **sample_rate** (integer) - Optional - The desired sample rate for the audio. ### Request Example ```json { "text": "Dies ist ein erweiterter Synthesetest." } ``` ### Response #### Success Response (200) - **audio_content** (string) - Base64 encoded audio data. - **timing_info** (object) - Detailed timing information about the synthesis process. - **generation_time_ms** (number) - Time taken for audio generation in milliseconds. - **sample_rate** (integer) - The sample rate of the generated audio. - **audio_duration_ms** (number) - The duration of the generated audio in milliseconds. #### Response Example ```json { "audio_content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkK..." "timing_info": { "generation_time_ms": 150.75, "sample_rate": 24000, "audio_duration_ms": 1234 } } ``` ``` -------------------------------- ### POST /v1/voices/reload - Reload Custom Voices Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Dynamically rescans the configured voices directory and loads any new custom voice samples without requiring a service restart. ```APIDOC ## POST /v1/voices/reload ### Description Dynamically rescans the configured voices directory and loads any new custom voice samples without requiring a service restart. Place `.wav` audio files (and optional `.txt` reference text files) in the mounted voices directory, then call this endpoint to make them available. ### Method POST ### Endpoint /v1/voices/reload ### Parameters None ### Response #### Success Response (200) - **success** (boolean) - Indicates if the voice reload operation was successful. - **available_voices** (array) - An updated list of all available voice IDs after the reload. #### Response Example ```json { "success": true, "available_voices": ["greta", "mateo", "juliette", "my_custom_voice"] } ``` ### Custom Voice File Structure Place custom voice files in the `voices/` directory with the following structure: ``` voices/ ├── my_custom_voice.wav # Required: Reference audio sample └── my_custom_voice.txt # Optional: Transcript of the audio ``` ``` -------------------------------- ### POST /synthesize Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Synthesizes speech audio and returns timing information along with the audio data. ```APIDOC ## POST /synthesize ### Description Synthesizes speech audio and returns timing information along with the audio data. ### Method POST ### Endpoint /synthesize ### Parameters #### Query Parameters None #### Request Body - **text** (string) - Required - The text to synthesize. - **voice_id** (string) - Optional - The ID of the voice to use (default: "greta"). ### Request Example ```json { "text": "Mit Timing-Informationen.", "voice_id": "mateo" } ``` ### Response #### Success Response (200) - **audio** (string) - Base64 encoded audio data. - **timing** (object) - Timing information for the synthesis. - **latency_ms** (number) - Latency in milliseconds. - **sample_rate** (integer) - The sample rate of the audio. - **duration_seconds** (number) - The duration of the synthesized speech in seconds. #### Response Example ```json { "audio": "UklGRi4AAABXQVZFZm10IBAAAAABAAEA...", "timing": { "latency_ms": 312.45, "sample_rate": 24000, "duration_seconds": 2.34 } } ``` ``` -------------------------------- ### TTSService Class API for Neutts German TTS Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Details the core `TTSService` class in Python, which manages the TTS model, voice caching, and audio synthesis. It provides methods for initialization, checking status, retrieving voice data, synthesizing speech (including streaming), and reloading custom voices. ```python from tts_service import tts_service # Initialize the TTS model (called automatically on first request) tts_service.initialize_tts() # Check initialization status if tts_service.is_initialized(): print("TTS ready") # Get available voices voices = tts_service.get_available_voices() # Returns: { # "greta": {"name": "German Greta (built-in)", "is_builtin": True, "has_ref_text": True}, # "mateo": {"name": "German Mateo (built-in)", "is_builtin": True, "has_ref_text": True}, # ... # } # Get voice reference data ref_codes, ref_text = tts_service.get_voice_data("greta") # Synthesize speech wav_data, timing = tts_service.synthesize( text="Guten Morgen!", voice_id="greta" ) # wav_data: bytes (WAV format) # timing: {"latency_ms": 245.3, "sample_rate": 24000, "duration_seconds": 1.2} # Save to file with open("output.wav", "wb") as f: f.write(wav_data) # Streaming synthesis (for real-time output) for audio_chunk in tts_service.synthesize_streaming("Langer Text...", "mateo"): # Process audio chunks as they're generated process_chunk(audio_chunk) # Reload custom voices at runtime available = tts_service.reload_custom_voices() print(f"Available voices: {available}") ``` -------------------------------- ### List Available Voices Endpoint Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Retrieves a list of all available voices, including built-in German voices and any custom voices loaded. Each voice entry provides its ID, display name, language code, and whether reference text is available. ```bash curl -X GET http://localhost:8136/v1/voices ``` -------------------------------- ### Docker Compose Deployment for Neutts German TTS Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt This configuration sets up a Dockerized environment for the Neutts German TTS service. It includes automatic model caching, custom voice mounting, and configurable device settings (CPU/GPU). The service is exposed on port 8136 and includes a health check. ```yaml # docker-compose.yml services: neutts-german: build: context: . dockerfile: Dockerfile container_name: neutts-german-api ports: - "8136:8136" volumes: # Mount custom voices directory - ${PWD}/voices:/app/voices # Cache for downloaded HuggingFace models - ${PWD}/model_cache:/app/model_cache environment: - HOST=0.0.0.0 - PORT=8136 - MODEL_REPO=neuphonic/neutts-nano-german-q4-gguf - CODEC_REPO=neuphonic/neucodec - BACKBONE_DEVICE=cpu - CODEC_DEVICE=cpu - VOICES_DIR=/app/voices - HF_HOME=/app/model_cache restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8136/health"] interval: 30s timeout: 10s retries: 3 start_period: 60s ``` -------------------------------- ### Reload Custom Voices Endpoint Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Dynamically reloads custom voices from the configured directory without restarting the service. This allows for adding new custom voices on the fly by placing `.wav` and optional `.txt` files in the voices directory. ```bash curl -X POST http://localhost:8136/v1/voices/reload ``` -------------------------------- ### POST /v1/audio/speech Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Generates speech audio from the provided text using the specified voice and format. Compatible with OpenAI's audio API. ```APIDOC ## POST /v1/audio/speech ### Description Generates speech audio from the provided text using the specified voice and format. Compatible with OpenAI's audio API. ### Method POST ### Endpoint /v1/audio/speech ### Parameters #### Query Parameters None #### Request Body - **input** (string) - Required - The text to synthesize. - **voice** (string) - Optional - The ID of the voice to use (default: "greta"). - **response_format** (string) - Optional - The format of the output audio (e.g., "mp3", "wav", "opus", "flac", "aac", "pcm"). Defaults to "mp3". - **model** (string) - Optional - Model identifier (for compatibility, not actively used for selection in this implementation). - **instructions** (string) - Optional - Style instructions (not used in current implementation). - **speed** (number) - Optional - Speed multiplier (not used in current implementation). ### Request Example ```json { "input": "Text zu sprechen.", "voice": "greta", "response_format": "mp3" } ``` ### Response #### Success Response (200) - **audio** (bytes) - The synthesized speech audio in the requested format. #### Response Example (Binary audio data) ``` -------------------------------- ### POST /v1/audio/speech - OpenAI-Compatible Speech Synthesis Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Synthesizes speech from the provided text using a specified voice and returns the audio in the requested format. This endpoint is compatible with OpenAI's TTS API. ```APIDOC ## POST /v1/audio/speech ### Description Synthesizes speech from the provided text using a specified voice and returns the audio in the requested format. This endpoint is compatible with OpenAI's TTS API. ### Method POST ### Endpoint /v1/audio/speech ### Parameters #### Query Parameters - **model** (string) - Optional - The model to use for synthesis (e.g., "gpt-4o-mini-tts"). - **input** (string) - Required - The text to synthesize. - **voice** (string) - Required - The voice to use for synthesis (e.g., "greta", "mateo", "juliette", or custom voice IDs). - **response_format** (string) - Optional - The format of the output audio (e.g., "mp3", "wav", "opus", "flac", "aac", "pcm"). Defaults to "mp3". ### Request Example ```json { "model": "gpt-4o-mini-tts", "input": "Guten Tag! Willkommen bei der deutschen Sprachsynthese.", "voice": "greta", "response_format": "mp3" } ``` ### Response #### Success Response (200) - **audio_data** (binary) - The synthesized audio stream in the requested format. - **X-Audio-Latency** (string) - The latency of the audio generation in milliseconds. #### Response Example (Binary audio data for speech.mp3) ``` -------------------------------- ### Request Models for Neutts German TTS API Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Defines the Pydantic models used for structuring API requests and responses in the Neutts German TTS service. These models ensure type safety and automatic data validation for API interactions, including OpenAI-compatible speech requests. ```python from models import OpenAISpeechRequest, TextRequest, VoicesResponse # OpenAI-compatible speech request speech_request = OpenAISpeechRequest( model="gpt-4o-mini-tts", # Model identifier (for compatibility) input="Text zu sprechen.", # Required: Text to synthesize voice="greta", # Voice ID (default: "greta") instructions=None, # Optional: Style instructions (not used) response_format="mp3", # Output format: mp3, wav, opus, flac, aac, pcm speed=1.0 # Speed multiplier (not used in current impl) ) ``` -------------------------------- ### Health Check Endpoint Source: https://context7.com/maglat/neutts-german-openai-api/llms.txt Checks the health status of the TTS service, indicating if the TTS model is initialized and listing available voices. This endpoint is useful for monitoring and orchestration systems. ```bash curl -X GET http://localhost:8136/health ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.