By default, docker compose up --build creates a minimal image without ffmpeg. If you're building locally (after cloning this repository) and need ffmpeg for audio format conversions (beyond MP3), you can include it in the build.

This is controlled by the INSTALL_FFMPEG_ARG build argument. Set this environment variable to true in one of these ways:

1. Prefixing the command:

   INSTALL_FFMPEG_ARG=true docker compose up --build

2. Adding to your .env file: Add this line to the .env file in the project root:

   INSTALL_FFMPEG_ARG=true

   Then, run docker compose up --build.
3. Exporting in your shell environment: Add export INSTALL_FFMPEG_ARG=true to your shell configuration (e.g., ~/.zshrc, ~/.bashrc) and reload your shell. Then docker compose up --build will use it.

This is for local builds. For pre-built Docker Hub images, add the latest-ffmpeg tag to the version

docker run -d -p 5050:5050 -e API_KEY=your_api_key_here -e PORT=5050 travisvn/openai-edge-tts:latest-ffmpeg

To build Docker images for both ARM64 and AMD64 architectures:

Using the build script:

# Build and push multi-platform to registry
./build-multi-platform.sh --push

# Build with FFmpeg support and push
./build-multi-platform.sh --ffmpeg --push

# Build for local use (current platform only)
./build-multi-platform.sh

# See all options
./build-multi-platform.sh --help

Note: Multi-platform builds require pushing to a registry. Local builds without --push will only build for your current platform.

Using Docker Buildx directly:

# Create builder if needed
docker buildx create --name multiarch-builder --driver docker-container --use --bootstrap

# Build and push multi-platform image
docker buildx build --platform linux/amd64,linux/arm64 \
  --build-arg INSTALL_FFMPEG=true \
  -t yourusername/openai-edge-tts:latest \
  --push .

# Verify platforms
docker buildx imagetools inspect yourusername/openai-edge-tts:latest

If you prefer to run this project directly with Python, follow these steps to set up a virtual environment, install dependencies, and start the server.

git clone https://github.com/travisvn/openai-edge-tts.git
cd openai-edge-tts

Create and activate a virtual environment to isolate dependencies:

# For macOS/Linux
python3 -m venv venv
source venv/bin/activate

# For Windows
python -m venv venv
venv\Scripts\activate

Use pip to install the required packages listed in requirements.txt:

pip install -r requirements.txt

If you want to run the Python tests locally, install the test-only dependencies:

pip install -r requirements-test.txt

Note: For local transcription (the test suite uses Whisper) and for some audio format conversions, ffmpeg must be installed and available on your PATH. Verify by running:

ffmpeg -version

Note: The Docker image installs only requirements.txt to keep the runtime image minimal; test-only packages are excluded from the image.

Create a .env file in the root directory and set the following variables:

API_KEY=your_api_key_here
PORT=5050

DEFAULT_VOICE=en-US-AvaNeural
DEFAULT_RESPONSE_FORMAT=mp3
DEFAULT_SPEED=1.0

DEFAULT_LANGUAGE=en-US

REQUIRE_API_KEY=True
REMOVE_FILTER=False
EXPAND_API=True
DETAILED_ERROR_LOGGING=True

Once configured, start the server with:

python app/server.py

The server will start running at http://localhost:5050.

You can now interact with the API at http://localhost:5050/v1/audio/speech and other available endpoints. See the Usage section for request examples.

Generates audio from the input text. Available parameters:

Required Parameter:

• input (string): The text to be converted to audio (up to 4096 characters).

Optional Parameters:

• model (string): Set to "tts-1" or "tts-1-hd" (default: "tts-1").
• voice (string): One of the OpenAI-compatible voices (alloy, echo, fable, onyx, nova, shimmer) or any valid edge-tts voice (default: "en-US-AvaNeural").
• response_format (string): Audio format. Options: mp3, opus, aac, flac, wav, pcm (default: mp3).
• speed (number): Playback speed (0.25 to 4.0). Default is 1.0.
• stream_format (string): Response format. Options: "audio" (raw audio data, default), "audio_stream" (streaming raw audio with chunked transfer), or "sse" (Server-Sent Events streaming with JSON events).

Note: The API is fully compatible with OpenAI's TTS API specification. The instructions parameter (for fine-tuning voice characteristics) is not currently supported, but all other parameters work identically to OpenAI's implementation.

Example request with curl and saving the output to an mp3 file:

curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "input": "Hello, I am your AI assistant! Just let me know how I can help bring your ideas to life.",
    "voice": "echo",
    "response_format": "mp3",
    "speed": 1.1
  }' \
  --output speech.mp3

You can pipe the audio directly to ffplay for immediate playback, just like OpenAI's API:

curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Today is a wonderful day to build something people love!",
    "voice": "alloy",
    "response_format": "mp3"
  }' | ffplay -i -

Or for immediate playback without saving to file:

curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "This will play immediately without saving to disk!",
    "voice": "shimmer"
  }' | ffplay -autoexit -nodisp -i -

Or, to be in line with the OpenAI API endpoint parameters:

curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "model": "tts-1",
    "input": "Hello, I am your AI assistant! Just let me know how I can help bring your ideas to life.",
    "voice": "alloy"
  }' \
  --output speech.mp3

For low-latency browser playback with immediate streaming, use audio_stream format:

curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "input": "This will stream raw audio chunks for immediate playback!",
    "voice": "alloy",
    "stream_format": "audio_stream"
  }' | ffplay -i -

Benefits of audio_stream:

• Lowest latency for browser playback
• Starts playing within 1-2 seconds
• Uses HTTP chunked transfer encoding
• Raw audio bytes (no base64 encoding overhead)
• Best for real-time applications

For applications that need structured streaming events (like web applications), use SSE format:

curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "model": "tts-1",
    "input": "This will stream as Server-Sent Events with JSON data containing base64-encoded audio chunks.",
    "voice": "alloy",
    "stream_format": "sse"
  }'

SSE Response Format:

data: {"type": "speech.audio.delta", "audio": "base64-encoded-audio-chunk"}

data: {"type": "speech.audio.delta", "audio": "base64-encoded-audio-chunk"}

data: {"type": "speech.audio.done", "usage": {"input_tokens": 12, "output_tokens": 0, "total_tokens": 12}}

Example using fetch API for raw audio streaming (lowest latency):

async function streamTTSWithAudioStream(text) {
  const response = await fetch('http://localhost:5050/v1/audio/speech', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer your_api_key_here',
    },
    body: JSON.stringify({
      input: text,
      voice: 'alloy',
      stream_format: 'audio_stream',
    }),
  });

  const reader = response.body.getReader();
  const chunks = [];

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
  }

  // Combine and play
  const audioBlob = new Blob(chunks, { type: 'audio/mpeg' });
  const audioUrl = URL.createObjectURL(audioBlob);
  const audio = new Audio(audioUrl);
  audio.play();
}

// Usage
streamTTSWithAudioStream('Hello from raw audio streaming!');

Example using fetch API for SSE streaming:

async function streamTTSWithSSE(text) {
  const response = await fetch('http://localhost:5050/v1/audio/speech', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer your_api_key_here',
    },
    body: JSON.stringify({
      input: text,
      voice: 'alloy',
      stream_format: 'sse',
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  const audioChunks = [];

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));

        if (data.type === 'speech.audio.delta') {
          // Decode base64 audio chunk
          const audioData = atob(data.audio);
          const audioArray = new Uint8Array(audioData.length);
          for (let i = 0; i < audioData.length; i++) {
            audioArray[i] = audioData.charCodeAt(i);
          }
          audioChunks.push(audioArray);
        } else if (data.type === 'speech.audio.done') {
          console.log('Speech synthesis complete:', data.usage);

          // Combine all chunks and play
          const totalLength = audioChunks.reduce(
            (sum, chunk) => sum + chunk.length,
            0
          );
          const combinedArray = new Uint8Array(totalLength);
          let offset = 0;
          for (const chunk of audioChunks) {
            combinedArray.set(chunk, offset);
            offset += chunk.length;
          }

          const audioBlob = new Blob([combinedArray], { type: 'audio/mpeg' });
          const audioUrl = URL.createObjectURL(audioBlob);
          const audio = new Audio(audioUrl);
          audio.play();
          return;
        }
      }
    }
  }
}

// Usage
streamTTSWithSSE('Hello from SSE streaming!');

And an example of a language other than English:

curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "model": "tts-1",
    "input": "じゃあ、行く。電車の時間、調べておくよ。",
    "voice": "ja-JP-KeitaNeural"
  }' \
  --output speech.mp3

• POST/GET /v1/models: Lists available TTS models.
• POST/GET /v1/voices: Lists edge-tts voices for a given language / locale.
• POST/GET /v1/voices/all: Lists all edge-tts voices, with language support information.