Running audio.cpp in Docker

July 26, 2026 ยท View on GitHub

Table of Contents

Prerequisites

Image Variants

The following image variants are available:

  • full: Provides the main tools cli and server and test binaries in one image. When running the container, the first argument selects the tool to execute.

The following backends are supported:

  • cuda12
  • cuda13
  • cpu

The following architectures are supported:

  • amd64
  • arm64

Published Images

Docker images are published daily when new commits are available. The images are provided as multiarch images (amd64/arm64).

Pull the latest images using these tags:

  • cuda12: ghcr.io/0xshug0/audio.cpp:full-cuda12
  • cuda13: ghcr.io/0xshug0/audio.cpp:full-cuda13
  • cpu: ghcr.io/0xshug0/audio.cpp:full-cpu

Images for a specific day/commit can be found in the versions history. The format is: full-<backend>-<date>-<shortsha>, e.g. full-cuda12-20260725-db7d2c4

Build Images locally

If you would like to build the images locally, you can use the available Dockerfiles in .devops.

CUDA

Build with the default CUDA 12.x version. See .devops/cuda.Dockerfile.

docker build -f .devops/cuda.Dockerfile -t local/audio.cpp:full-cuda12 .

Build with a specific CUDA version, for example 13.3.0:

docker build -f .devops/cuda.Dockerfile -t local/audio.cpp:full-cuda13 --build-arg CUDA_VERSION=13.3.0 .

CPU

docker build -f .devops/cpu.Dockerfile -t local/audio.cpp:full-cpu .

Usage

The model directory <models-dir> must be mounted into the container. An additional <output-dir> should be mounted for TTS tasks.

CUDA

docker run --rm --gpus all -v "<models-dir>:/models:ro" ghcr.io/0xshug0/audio.cpp:full-cuda12 <cli|server> --model /models/<model> <...>

CPU

docker run --rm -v "<models-dir>:/models:ro" ghcr.io/0xshug0/audio.cpp:full-cpu <cli|server> --model /models/<model> <...>

See the fully working examples below.

Examples

Examples for Docker, including CUDA and CPU, are available in examples/docker.

CLI

The examples in examples/docker/cli demonstrate how to run the audio.cpp CLI with docker run. The examples include:

  • PocketTTS: Text-to-Speech
  • Qwen3-TTS: Text-to-Speech with Voice Cloning

Server

The examples in examples/docker/server demonstrate how to run the audio.cpp server with docker compose. The examples include:

  • PocketTTS: Text-to-Speech
  • Qwen3-TTS: Text-to-Speech with Voice Cloning