DDEV Openai Edge TTS

Overview

This add-on integrates Openai Edge TTS into your DDEV project.

Openai Edge TTS provides a local, OpenAI-compatible text-to-speech (TTS) API using edge-tts. edge-tts uses Microsoft Edge's online text-to-speech service, so it is completely free.

Installation

ddev add-on get tyler36/ddev-openai-edge-tts
ddev restart

After installation, make sure to commit the .ddev directory to version control.

Features

This addon is a helper wrapper for https://github.com/travisvn/openai-edge-tts. The following features are stated as available:

• OpenAI-Compatible Endpoint: /v1/audio/speech with similar request structure and behavior.
• SSE Streaming Support: Real-time audio streaming via Server-Sent Events when stream_format: "sse" is specified.
• Supported Voices: Maps OpenAI voices (alloy, echo, fable, onyx, nova, shimmer) to edge-tts equivalents.
• Flexible Formats: Supports multiple audio formats (mp3, opus, aac, flac, wav, pcm).
• Adjustable Speed: Option to modify playback speed (0.25x to 4.0x).
• Optional Direct Edge-TTS Voice Selection: Use either OpenAI voice mappings or specify any edge-tts voice directly.

To preview edge-tts voices, see Voice Samples.

Usage

This addon provides the service via an API endpoint.

Access	Endpoint
Host	https://{PROJECT_NAME}:5050/v1/audio/speech
Container	openai-edge-tts:5050/v1/audio/speech

OpenAI-Compatible Edge-TTS API tries to maintain compatibility with the OpenAI audio/speech endpoint.

@see OpenAI-Compatible Edge-TTS API for all available options.

For non-English languages, set the voice to an appropriate language list on Voice Samples.

Curl

Use curl to make request to the endpoint.

Below, is an example of a command from the host that:

• transforms the "Hello, I am your AI assistant!" input
• using the echo voice
• into a mp3 format
• at 1.1 speed (faster than normal)
• into a file called speech.mp3.

ddev exec curl -X POST openai-edge-tts:5050/v1/audio/speech \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer your_api_key_here" \
    -d '{
      "input": "Hello, I am your AI assistant!",
      "voice": "echo",
      "response_format": "mp3",
      "speed": 1.1
    }' \
    --output speech.mp3

[!Note] "your_api_key_here" is the default API KEY and does not need to be changed for local development.

OpenAI-php

OpenAI-php can be used with this addon.

• Use the factory() function to generate a new $client that points to this addon.
• Then, use the $client as normal.

    $client = \OpenAI::factory()
        ->withApiKey('your_api_key_here'))
        ->withBaseUri('http://openai-edge-tts:5050/v1/')
        ->make();

    // This is a standard OpenAI TTS API call.
    $mp3 = $client->audio()->speech([
        'input' => "What can I help you with today?",
        'voice' => 'echo',
        'response_format' => 'mp3',
    ]);

Other Commands

Command	Description
ddev describe	View service status and used ports for Openai Edge Tts
ddev logs -s openai-edge-tts	Check Openai Edge Tts logs

Advanced Customization

To change the Docker image:

ddev dotenv set .ddev/.env.openai-edge-tts --openai-edge-tts-docker-image="ddev/ddev-utilities:latest"
ddev add-on get tyler36/ddev-openai-edge-tts
ddev restart

Make sure to commit the .ddev/.env.openai-edge-tts file to version control.

All customization options (use with caution):

Variable	Flag	Default
OPENAI_EDGE_TTS_DOCKER_IMAGE	--openai-edge-tts-docker-image	ddev/ddev-utilities:latest

Ports

To change the HTTP/S ports exposed to the host system:

• Use DDEV dotenv command

  ddev dotenv set .ddev/.env --tts-http-port="${TTS_HTTP_PORT}"   # HTTP
  ddev dotenv set .ddev/.env --tts-https-port="${TTS_HTTPS_PORT}" # HTTPS

• or, update the .ddev/.env file directly.

  TTS_HTTP_PORT=5010
  TTS_HTTPS_PORT=5011

Restart DDEV to apply the changes.

Credits

Contributed and maintained by @tyler36