Skip to content

docker.md

Latest commit

 

History

History
169 lines (119 loc) · 4.91 KB

docker.md

File metadata and controls

169 lines (119 loc) · 4.91 KB
Raw

Running audio.cpp in Docker

Table of Contents

Prerequisites

  • Docker must be installed and running on your system.
  • For CUDA:
  • For Vulkan:
    • The host must expose a working Vulkan device to Docker, typically through /dev/dri on Linux.
    • The container user needs access to the host render/video device groups.

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
  • vulkan
  • 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
  • vulkan: ghcr.io/0xshug0/audio.cpp:full-vulkan
  • 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 .

Build for a specific set of GPU architectures (e.g. for faster, less portable builds):

docker build -f .devops/cuda.Dockerfile -t local/audio.cpp:full-cuda12 --build-arg CUDA_DOCKER_ARCH="86;89" .

Vulkan

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

CPU

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

Usage

For CLI use, mount the model directory <models-dir> into the container. An additional <output-dir> should be mounted for tasks that write files.

CUDA

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

Vulkan

docker run --rm --device /dev/dri \
  --group-add "$(getent group render | cut -d: -f3)" \
  --group-add "$(getent group video | cut -d: -f3)" \
  -v "<models-dir>:/models:ro" \
  ghcr.io/0xshug0/audio.cpp:full-vulkan \
  <cli|server> --backend vulkan --model /models/<model> <...>

Native WebUI

For the native WebUI with model downloads and dynamic model management, mount a writable model directory and expose the server port:

docker run --rm --gpus all \
  -p 8080:8080 \
  -v "<models-dir>:/app/models" \
  ghcr.io/0xshug0/audio.cpp:full-cuda12 \
  server --ui --ui-management --host 0.0.0.0 --port 8080 --backend cuda

For Vulkan, expose the host render device and use the Vulkan backend:

docker run --rm --device /dev/dri \
  --group-add "$(getent group render | cut -d: -f3)" \
  --group-add "$(getent group video | cut -d: -f3)" \
  -p 8080:8080 \
  -v "<models-dir>:/app/models" \
  ghcr.io/0xshug0/audio.cpp:full-vulkan \
  server --ui --ui-management --host 0.0.0.0 --port 8080 --backend vulkan

Open http://127.0.0.1:8080 on the host. Use a writable mount when the UI should download or prepare models. For a read-only model directory, omit --ui-management or mount the directory as read-only and load only models that already exist in the configured path.

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