From bed3f8e2d5656e92bea022433ff56d3ead3eb1a7 Mon Sep 17 00:00:00 2001
From: xashr <xashr@sr01.eu>
Date: Sun, 5 Jul 2026 18:39:12 +0000
Subject: [PATCH 1/2] Add Dockerfiles and Docker examples

---
 .devops/cpu.Dockerfile                 |  96 +++++++++++++++++++++++
 .devops/cuda.Dockerfile                | 102 +++++++++++++++++++++++++
 .devops/entrypoint.sh                  |  31 ++++++++
 .dockerignore                          |   9 +++
 examples/docker/cli/.gitignore         |   1 +
 examples/docker/cli/README.md          |  46 +++++++++++
 examples/docker/cli/cpu-tts.sh         |  22 ++++++
 examples/docker/cli/cuda-tts.sh        |  24 ++++++
 examples/docker/models/.gitignore      |   2 +
 examples/docker/models/put_models_here |   4 +
 examples/docker/server/.gitignore      |   1 +
 examples/docker/server/README.md       |  43 +++++++++++
 examples/docker/server/cpu-server.yml  |  20 +++++
 examples/docker/server/cuda-server.yml |  27 +++++++
 examples/docker/server/server.json     |  22 ++++++
 examples/docker/server/tts.sh          |  13 ++++
 16 files changed, 463 insertions(+)
 create mode 100644 .devops/cpu.Dockerfile
 create mode 100644 .devops/cuda.Dockerfile
 create mode 100755 .devops/entrypoint.sh
 create mode 100644 .dockerignore
 create mode 100644 examples/docker/cli/.gitignore
 create mode 100644 examples/docker/cli/README.md
 create mode 100755 examples/docker/cli/cpu-tts.sh
 create mode 100755 examples/docker/cli/cuda-tts.sh
 create mode 100644 examples/docker/models/.gitignore
 create mode 100644 examples/docker/models/put_models_here
 create mode 100644 examples/docker/server/.gitignore
 create mode 100644 examples/docker/server/README.md
 create mode 100644 examples/docker/server/cpu-server.yml
 create mode 100644 examples/docker/server/cuda-server.yml
 create mode 100644 examples/docker/server/server.json
 create mode 100755 examples/docker/server/tts.sh

diff --git a/.devops/cpu.Dockerfile b/.devops/cpu.Dockerfile
new file mode 100644
index 0000000..a1a458d
--- /dev/null
+++ b/.devops/cpu.Dockerfile
@@ -0,0 +1,96 @@
+# audio.cpp — CPU Dockerfile
+#
+# Usage:
+#   docker build -f .devops/cpu.Dockerfile -t local/audiocpp:full-cpu .
+
+# ============================================================
+# [BUILD] Compile all release binaries
+# ============================================================
+ARG UBUNTU_VERSION=24.04
+ARG BUILD_DATE=N/A
+ARG APP_VERSION=N/A
+ARG APP_REVISION=N/A
+ARG GCC_VERSION=14
+
+FROM docker.io/ubuntu:$UBUNTU_VERSION AS build
+
+ARG GCC_VERSION=14
+
+# Install build toolchain
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        gcc-${GCC_VERSION} g++-${GCC_VERSION} make cmake libgomp1 && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+ENV CC=gcc-${GCC_VERSION} CXX=g++-${GCC_VERSION}
+
+WORKDIR /app
+COPY . .
+
+# Configure
+RUN cmake -S . -B build \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DENGINE_ENABLE_CUDA=OFF \
+        -DENGINE_ENABLE_VULKAN=OFF \
+        -DENGINE_ENABLE_OPENMP=ON \
+        -DENGINE_BUILD_EXAMPLES=OFF \
+        -DENGINE_BUILD_TESTS=OFF \
+        -DENGINE_BUILD_WARMBENCH=OFF && \
+    cmake --build build --parallel $(nproc) \
+        --target audiocpp_cli \
+        --target audiocpp_server \
+        --target model_perf \
+        --target miocodec_wavlm_parity
+
+# Collect all binaries + multiplexer into /app/full
+RUN mkdir -p /app/full && \
+    cp build/bin/audiocpp_cli build/bin/audiocpp_server \
+       build/bin/model_perf build/bin/miocodec_wavlm_parity /app/full/ && \
+    cp .devops/entrypoint.sh /app/full/entrypoint.sh && \
+    chmod +x /app/full/entrypoint.sh
+
+# ============================================================
+# [BASE] Shared runtime (OS + common libs)
+# ============================================================
+FROM docker.io/ubuntu:$UBUNTU_VERSION AS base
+
+ARG BUILD_DATE=N/A
+ARG APP_VERSION=N/A
+ARG APP_REVISION=N/A
+ARG IMAGE_URL=https://github.com/0xShug0/audio.cpp
+ARG IMAGE_SOURCE=https://github.com/0xShug0/audio.cpp
+
+LABEL org.opencontainers.image.created=$BUILD_DATE \
+      org.opencontainers.image.version=$APP_VERSION \
+      org.opencontainers.image.revision=$APP_REVISION \
+      org.opencontainers.image.title="audio.cpp" \
+      org.opencontainers.image.description="An all-in-one, pure C++ inference engine for audio models, powered by ggml" \
+      org.opencontainers.image.url=$IMAGE_URL \
+      org.opencontainers.image.source=$IMAGE_SOURCE
+
+# Runtime deps: OpenMP threading, curl (healthcheck), ffmpeg (audio I/O)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        libgomp1 curl ffmpeg && \
+    apt-get autoremove -y && \
+    apt-get clean -y && \
+    rm -rf /tmp/* /var/tmp/* && \
+    find /var/cache/apt/archives /var/lib/apt/lists -not -name lock -type f -delete && \
+    find /var/cache -type f -delete
+
+WORKDIR /app
+
+# ============================================================
+# [FULL] All binaries + entrypoint.sh multiplexer
+# ============================================================
+FROM base AS full
+
+COPY --from=build /app/full /app
+
+USER ubuntu
+
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=15s \
+  CMD curl -f http://localhost:8080/health || exit 1
+
+ENTRYPOINT ["/app/entrypoint.sh"]
diff --git a/.devops/cuda.Dockerfile b/.devops/cuda.Dockerfile
new file mode 100644
index 0000000..e4aa52b
--- /dev/null
+++ b/.devops/cuda.Dockerfile
@@ -0,0 +1,102 @@
+# audio.cpp — CUDA Dockerfile
+#
+# Usage:
+#   docker build -f .devops/cuda.Dockerfile -t local/audiocpp:full-cuda .
+
+# ============================================================
+# [BUILD] Compile all release binaries with CUDA
+# ============================================================
+ARG UBUNTU_VERSION=24.04
+ARG CUDA_VERSION=12.9.0
+ARG BUILD_DATE=N/A
+ARG APP_VERSION=N/A
+ARG APP_REVISION=N/A
+ARG GCC_VERSION=14
+
+ARG BASE_CUDA_DEV_CONTAINER=docker.io/nvidia/cuda:${CUDA_VERSION}-devel-ubuntu${UBUNTU_VERSION}
+ARG BASE_CUDA_RUN_CONTAINER=docker.io/nvidia/cuda:${CUDA_VERSION}-runtime-ubuntu${UBUNTU_VERSION}
+
+FROM ${BASE_CUDA_DEV_CONTAINER} AS build
+
+ARG GCC_VERSION=14
+
+# Install build toolchain
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        gcc-${GCC_VERSION} g++-${GCC_VERSION} cmake && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+ENV CC=gcc-${GCC_VERSION} CXX=g++-${GCC_VERSION} CUDAHOSTCXX=g++-${GCC_VERSION}
+
+WORKDIR /app
+COPY . .
+
+# Configure
+RUN cmake -S . -B build \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DENGINE_ENABLE_CUDA=ON \
+        -DENGINE_ENABLE_CUDA_GRAPHS=ON \
+        -DENGINE_ENABLE_VULKAN=OFF \
+        -DENGINE_ENABLE_OPENMP=ON \
+        -DENGINE_BUILD_EXAMPLES=OFF \
+        -DENGINE_BUILD_TESTS=OFF \
+        -DENGINE_BUILD_WARMBENCH=OFF && \
+    cmake --build build --parallel $(nproc) \
+        --target audiocpp_cli \
+        --target audiocpp_server \
+        --target model_perf \
+        --target miocodec_wavlm_parity
+
+# Collect all binaries + multiplexer into /app/full
+RUN mkdir -p /app/full && \
+    cp build/bin/audiocpp_cli build/bin/audiocpp_server \
+       build/bin/model_perf build/bin/miocodec_wavlm_parity /app/full/ && \
+    cp .devops/entrypoint.sh /app/full/entrypoint.sh && \
+    chmod +x /app/full/entrypoint.sh
+
+# ============================================================
+# [BASE] Shared runtime (NVIDIA CUDA + common libs)
+# ============================================================
+FROM ${BASE_CUDA_RUN_CONTAINER} AS base
+
+ARG BUILD_DATE=N/A
+ARG APP_VERSION=N/A
+ARG APP_REVISION=N/A
+ARG IMAGE_URL=https://github.com/0xShug0/audio.cpp
+ARG IMAGE_SOURCE=https://github.com/0xShug0/audio.cpp
+
+LABEL org.opencontainers.image.created=$BUILD_DATE \
+      org.opencontainers.image.version=$APP_VERSION \
+      org.opencontainers.image.revision=$APP_REVISION \
+      org.opencontainers.image.title="audio.cpp" \
+      org.opencontainers.image.description="An all-in-one, pure C++ inference engine for audio models, powered by ggml" \
+      org.opencontainers.image.url=$IMAGE_URL \
+      org.opencontainers.image.source=$IMAGE_SOURCE
+
+# Runtime deps: OpenMP threading, curl (healthcheck), ffmpeg (audio I/O)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        libgomp1 curl ffmpeg && \
+    apt-get autoremove -y && \
+    apt-get clean -y && \
+    rm -rf /tmp/* /var/tmp/* && \
+    find /var/cache/apt/archives /var/lib/apt/lists -not -name lock -type f -delete && \
+    find /var/cache -type f -delete
+
+WORKDIR /app
+
+# ============================================================
+# [FULL] All binaries + entrypoint.sh multiplexer
+# ============================================================
+FROM base AS full
+
+COPY --from=build /app/full /app
+
+USER ubuntu
+
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=15s \
+  CMD curl -f http://localhost:8080/health || exit 1
+
+ENTRYPOINT ["/app/entrypoint.sh"]
+
diff --git a/.devops/entrypoint.sh b/.devops/entrypoint.sh
new file mode 100755
index 0000000..bf58da7
--- /dev/null
+++ b/.devops/entrypoint.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# ============================================================
+# audio.cpp Docker multiplexer
+#
+# Dispatches to the correct binary based on the first
+# argument. All remaining arguments are forwarded verbatim.
+# ============================================================
+set -e
+
+arg1="$1"
+shift || true
+
+if [[ "$arg1" == "cli" ]]; then
+    exec ./audiocpp_cli "$@"
+elif [[ "$arg1" == "server" ]]; then
+    exec ./audiocpp_server "$@"
+elif [[ "$arg1" == "perf" ]]; then
+    exec ./model_perf "$@"
+elif [[ "$arg1" == "parity" ]]; then
+    exec ./miocodec_wavlm_parity "$@"
+else
+    echo "Unknown command: $arg1"
+    echo ""
+    echo "Available commands:"
+    echo "  cli     Run audio tasks (TTS, ASR, VAD, VC, diar, etc.)"
+    echo "  server  Run the HTTP server"
+    echo "  perf    Run model performance benchmarks"
+    echo "  parity  Run Miocodec WavLM parity tests"
+    exit 1
+fi
+
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..5359d35
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,9 @@
+.git/
+.gitignore
+.github/
+examples/
+scripts/
+docs/
+tools/
+build/
+*.md
diff --git a/examples/docker/cli/.gitignore b/examples/docker/cli/.gitignore
new file mode 100644
index 0000000..ea1472e
--- /dev/null
+++ b/examples/docker/cli/.gitignore
@@ -0,0 +1 @@
+output/
diff --git a/examples/docker/cli/README.md b/examples/docker/cli/README.md
new file mode 100644
index 0000000..1276c38
--- /dev/null
+++ b/examples/docker/cli/README.md
@@ -0,0 +1,46 @@
+# Docker CLI
+
+Run the audio.cpp CLI tool inside a Docker container for text-to-speech.
+
+## Setup
+
+**1. Download the PocketTTS model**
+
+Get the English model from [kyutai/pocket-tts](https://huggingface.co/kyutai/pocket-tts/) on Hugging Face.
+Place the files from `languages/english/` into `../models/pocket-tts/languages/english/`:
+
+The directory should look like:
+```
+../models/pocket-tts/languages/english/
+├── model.safetensors
+├── tokenizer.model
+└── embeddings/
+    ├── alba.safetensors
+    └── ...
+```
+
+**2. Build the image**
+
+CPU:
+
+```bash
+docker build -f ../../../.devops/cpu.Dockerfile -t local/audiocpp:full-cpu ../../..
+```
+
+GPU (CUDA):
+
+```bash
+docker build -f ../../../.devops/cuda.Dockerfile -t local/audiocpp:full-cuda ../../..
+```
+
+## Usage
+
+```bash
+./cpu-tts.sh
+```
+
+```bash
+./cuda-tts.sh
+```
+
+Speech is saved to `output/speech.wav`.
diff --git a/examples/docker/cli/cpu-tts.sh b/examples/docker/cli/cpu-tts.sh
new file mode 100755
index 0000000..1ce266b
--- /dev/null
+++ b/examples/docker/cli/cpu-tts.sh
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -e
+
+OUTPUT_DIR="$(cd "$(dirname "$0")" && pwd)/output"
+mkdir -p "$OUTPUT_DIR"
+MODEL_DIR="$(cd "$(dirname "$0")/../models" && pwd)"
+
+docker run --rm \
+  --user "$(id -u):$(id -g)" \
+  -v "$MODEL_DIR:/models:ro" \
+  -v "$OUTPUT_DIR:/output" \
+  local/audiocpp:full-cpu \
+  cli \
+  --task tts \
+  --family pocket_tts \
+  --model /models/pocket-tts \
+  --backend cpu \
+  --text "You are successfully running a text-to-speech model using audio.cpp, a pure C++ inference engine for audio models." \
+  --voice-id alba \
+  --out /output/speech.wav
+
+echo "Saved to: $OUTPUT_DIR/speech.wav"
diff --git a/examples/docker/cli/cuda-tts.sh b/examples/docker/cli/cuda-tts.sh
new file mode 100755
index 0000000..f5cd895
--- /dev/null
+++ b/examples/docker/cli/cuda-tts.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -e
+
+OUTPUT_DIR="$(cd "$(dirname "$0")" && pwd)/output"
+mkdir -p "$OUTPUT_DIR"
+MODEL_DIR="$(cd "$(dirname "$0")/../models" && pwd)"
+
+docker run --rm \
+  --gpus all \
+  --user "$(id -u):$(id -g)" \
+  -v "$MODEL_DIR:/models:ro" \
+  -v "$OUTPUT_DIR:/output" \
+  local/audiocpp:full-cuda \
+  cli \
+  --task tts \
+  --family pocket_tts \
+  --model /models/pocket-tts \
+  --backend cuda \
+  --device 0 \
+  --text "You are successfully running a text-to-speech model using audio.cpp, a pure C++ inference engine for audio models." \
+  --voice-id alba \
+  --out /output/speech.wav
+
+echo "Saved to: $OUTPUT_DIR/speech.wav"
diff --git a/examples/docker/models/.gitignore b/examples/docker/models/.gitignore
new file mode 100644
index 0000000..8904211
--- /dev/null
+++ b/examples/docker/models/.gitignore
@@ -0,0 +1,2 @@
+*
+!put_models_here
diff --git a/examples/docker/models/put_models_here b/examples/docker/models/put_models_here
new file mode 100644
index 0000000..f307ddb
--- /dev/null
+++ b/examples/docker/models/put_models_here
@@ -0,0 +1,4 @@
+# Download PocketTTS model files here:
+#   models/pocket-tts/languages/english/model.safetensors
+#   models/pocket-tts/languages/english/tokenizer.model
+#   models/pocket-tts/languages/english/embeddings/*.safetensors
diff --git a/examples/docker/server/.gitignore b/examples/docker/server/.gitignore
new file mode 100644
index 0000000..ea1472e
--- /dev/null
+++ b/examples/docker/server/.gitignore
@@ -0,0 +1 @@
+output/
diff --git a/examples/docker/server/README.md b/examples/docker/server/README.md
new file mode 100644
index 0000000..4a444e4
--- /dev/null
+++ b/examples/docker/server/README.md
@@ -0,0 +1,43 @@
+# Docker Compose Server
+
+Run the audio.cpp TTS server (as configured in server.json) in Docker.
+
+## Setup
+
+**1. Download the PocketTTS model**
+
+Get the English model from [kyutai/pocket-tts](https://huggingface.co/kyutai/pocket-tts/) on Hugging Face.
+Place the files from `languages/english/` into `../models/pocket-tts/languages/english/`:
+
+The directory should look like:
+```
+../models/pocket-tts/languages/english/
+├── model.safetensors
+├── tokenizer.model
+└── embeddings/
+    ├── alba.safetensors
+    └── ...
+```
+
+**2. Start the server**
+
+CPU:
+
+```bash
+docker compose -f cpu-server.yml up
+```
+
+GPU (CUDA):
+
+```bash
+docker compose -f cuda-server.yml up
+```
+
+## Generate speech
+
+```bash
+./generate.sh
+```
+
+This sends a TTS request to `http://localhost:8080/v1/audio/speech` and saves the result to `output/speech.wav`.
+
diff --git a/examples/docker/server/cpu-server.yml b/examples/docker/server/cpu-server.yml
new file mode 100644
index 0000000..9f52629
--- /dev/null
+++ b/examples/docker/server/cpu-server.yml
@@ -0,0 +1,20 @@
+services:
+  audiocpp-server:
+    image: local/audiocpp:full-cpu
+    build:
+      context: ../../../
+      dockerfile: .devops/cpu.Dockerfile
+    restart: unless-stopped
+    stop_grace_period: 30s
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./../models:/models:ro
+      - ./server.json:/app/server.json:ro
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 15s
+    command: ["server", "--config", "/app/server.json", "--backend", "cpu"]
diff --git a/examples/docker/server/cuda-server.yml b/examples/docker/server/cuda-server.yml
new file mode 100644
index 0000000..023ddc8
--- /dev/null
+++ b/examples/docker/server/cuda-server.yml
@@ -0,0 +1,27 @@
+services:
+  audiocpp-server:
+    image: local/audiocpp:full-cuda
+    build:
+      context: ../../../
+      dockerfile: .devops/cuda.Dockerfile
+    restart: unless-stopped
+    stop_grace_period: 30s
+    ports:
+      - "8080:8080"
+    environment:
+      - NVIDIA_VISIBLE_DEVICES=all
+    volumes:
+      - ./../models:/models:ro
+      - ./server.json:/app/server.json:ro
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - capabilities: ["gpu"]
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 15s
+    command: ["server", "--config", "/app/server.json"]
diff --git a/examples/docker/server/server.json b/examples/docker/server/server.json
new file mode 100644
index 0000000..c772e7f
--- /dev/null
+++ b/examples/docker/server/server.json
@@ -0,0 +1,22 @@
+{
+  "host": "0.0.0.0",
+  "port": 8080,
+  "device": 0,
+  "threads": 1,
+  "models": [
+    {
+      "id": "pocket-tts",
+      "family": "pocket_tts",
+      "path": "/models/pocket-tts",
+      "task": "tts",
+      "mode": "offline",
+      "load_options": {
+        "language": "english"
+      },
+      "session_options": {
+        "language": "english"
+      }
+    }
+  ]
+}
+
diff --git a/examples/docker/server/tts.sh b/examples/docker/server/tts.sh
new file mode 100755
index 0000000..28608cd
--- /dev/null
+++ b/examples/docker/server/tts.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+mkdir -p output
+curl http://localhost:8080/v1/audio/speech -H 'Content-Type: application/json' -o output/speech.wav -d '
+{
+  "model": "pocket-tts",
+  "input": "You are successfully running a text-to-speech model using audio.cpp, a pure C++ inference engine for audio models.",
+  "voice": "alba"
+}
+'
+
+echo "Saved to: output/speech.wav"
+

From 796a6f65dae77079cee8e347c9389d4dc9617462 Mon Sep 17 00:00:00 2001
From: xashr <xashr@sr01.eu>
Date: Sun, 5 Jul 2026 18:39:13 +0000
Subject: [PATCH 2/2] Update README

---
 examples/docker/cli/README.md    | 12 +++++++-----
 examples/docker/server/README.md |  4 ++--
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/examples/docker/cli/README.md b/examples/docker/cli/README.md
index 1276c38..baebad2 100644
--- a/examples/docker/cli/README.md
+++ b/examples/docker/cli/README.md
@@ -21,26 +21,28 @@ The directory should look like:
 
 **2. Build the image**
 
+Run from repository root:
+
 CPU:
 
 ```bash
-docker build -f ../../../.devops/cpu.Dockerfile -t local/audiocpp:full-cpu ../../..
+docker build -f .devops/cpu.Dockerfile -t local/audiocpp:full-cpu .
 ```
 
 GPU (CUDA):
 
 ```bash
-docker build -f ../../../.devops/cuda.Dockerfile -t local/audiocpp:full-cuda ../../..
+docker build -f .devops/cuda.Dockerfile -t local/audiocpp:full-cuda .
 ```
 
 ## Usage
 
-```bash
-./cpu-tts.sh
-```
+Run one of:
 
 ```bash
+./cpu-tts.sh
 ./cuda-tts.sh
 ```
 
 Speech is saved to `output/speech.wav`.
+
diff --git a/examples/docker/server/README.md b/examples/docker/server/README.md
index 4a444e4..9fd650e 100644
--- a/examples/docker/server/README.md
+++ b/examples/docker/server/README.md
@@ -36,8 +36,8 @@ docker compose -f cuda-server.yml up
 ## Generate speech
 
 ```bash
-./generate.sh
+./tts.sh
 ```
 
-This sends a TTS request to `http://localhost:8080/v1/audio/speech` and saves the result to `output/speech.wav`.
+This sends a request to `http://localhost:8080/v1/audio/speech` and saves the result to `output/speech.wav`.