### Ace Server Examples

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Examples demonstrating how to launch the ace-server with different configurations, including specifying model directories, adapters, custom ports, and batch limits.

```bash
# all models in one directory
./ace-server --models /path/to/models
```

```bash
# with adapters
./ace-server --models /path/to/models --adapters /path/to/adapters
```

```bash
# custom port and batch limit
./ace-server --models /path/to/models --host 0.0.0.0 --port 8085 --max-batch 2
```

--------------------------------

### Starting ACE Server with Adapters

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Starts the ACE server, specifying model and adapter directories. Adapters are loaded from the `adapters/` directory.

```bash
# Place adapters in the adapters/ folder
ls adapters/
# french-musette-v1.safetensors
# singer-peft-v2/
#   adapter_model.safetensors
#   adapter_config.json
# lycoris-qinglong.safetensors

# Start server with adapter directory
./build/ace-server --models models --adapters adapters
```

--------------------------------

### Starting the Ace Server

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Commands to start the Ace Server with various configurations, including custom host/port, adapter usage, and memory optimization.

```APIDOC
## Starting the server

```bash
# Default: localhost:8080
./build/ace-server --models models

# Custom host/port with adapters
./build/ace-server \
    --models models \
    --adapters adapters \
    --host 0.0.0.0 \
    --port 8085 \
    --max-batch 2

# Keep models in VRAM between requests (low-latency, more VRAM)
./build/ace-server --models models --keep-loaded

# Memory-constrained: smaller VAE tiles
./build/ace-server --models models --vae-chunk 512 --vae-overlap 32
```
```

--------------------------------

### Start ace-server

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Launch the ace-server with default settings or customize host, port, and batch size. Models can be kept in VRAM for lower latency.

```bash
./build/ace-server --models models
```

```bash
./build/ace-server \
    --models models \
    --adapters adapters \
    --host 0.0.0.0 \
    --port 8085 \
    --max-batch 2
```

```bash
./build/ace-server --models models --keep-loaded
```

```bash
./build/ace-server --models models --vae-chunk 512 --vae-overlap 32
```

--------------------------------

### Selecting Adapter in Request JSON

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Example of making a synthesis request to the ACE server, specifying an adapter and its scale.

```bash
# Select adapter in request JSON (adapter_scale defaults to 1.0)
curl -sf http://127.0.0.1:8085/synth \
    -H "Content-Type: application/json" \
    -d '{
        "caption": "French accordion musette waltz with violin",
        "vocal_language": "fr",
        "adapter": "french-musette-v1.safetensors",
        "adapter_scale": 0.8
    }' | jq -r '.id'
```

--------------------------------

### Run ACE Server with Adapters

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/adapters/README.md

Use this command to start the ACE server and specify the directory containing your adapter files.

```bash
./build/ace-server --models ./models --adapters ./adapters
```

--------------------------------

### Execute Example Scripts

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Navigate to the `examples/` directory to run provided shell scripts that demonstrate various functionalities, including single song generation, batch processing, partial/full metadata usage, DiT-only synthesis, audio understanding, and server/client interactions.

```bash
cd examples
./simple.sh                    # caption only, LLM fills everything
./simple-batch.sh              # 2 songs from one prompt (lm_batch_size=2)
./partial.sh                   # caption + lyrics + duration
./full.sh                      # all metadata provided
./dit-only.sh                  # skip LLM, DiT from noise
./ace-understand.sh <audio>    # audio : understand : SFT DiT : MP3 roundtrip
./server-turbo.sh              # start HTTP server (turbo model)
./server-sft.sh                # start HTTP server (SFT model)
./client.sh                    # test server (single song)
./client-batch.py              # test server batch (2 songs)
./client-understand.sh <audio> # test /understand + /synth roundtrip
```

--------------------------------

### Run Server on Windows

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Execute the server command to start the ACE-Step AI music generation server on Windows. Access the UI via http://localhost:8085.

```cmd
server.cmd        # Windows
```

--------------------------------

### GET /props

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Retrieves available models, server configuration, and default parameters.

```APIDOC
## GET /props

### Description
Available models, server config, default parameters.

### Method
GET

### Endpoint
/props
```

--------------------------------

### Build for Windows with Vulkan

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Use the provided batch script to build the project with Vulkan support on Windows. Ensure Visual C++ Build Tools and Vulkan SDK are installed.

```cmd
buildvulkan.cmd   # AMD/Intel GPU (Vulkan)
```

--------------------------------

### Run Server on Linux/macOS

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Execute the server script to start the ACE-Step AI music generation server on Linux or macOS. Access the UI via http://localhost:8085.

```bash
./server.sh       # Linux / macOS
```

--------------------------------

### Ace-Server Command-Line Options

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Use these options to configure the Ace-Server when starting it. Required arguments include the model directory, with optional arguments for adapters, memory control, output format, server settings, and debugging.

```bash
Usage: ./ace-server --models <dir> [options]

Required:
  --models <dir>          Directory of GGUF model files

Adapter:
  --adapters <dir>        Directory of adapters

Memory control:
  --keep-loaded           Keep models in VRAM between requests
  --vae-chunk <N>         Latent frames per tile (default: 1024)
  --vae-overlap <N>       Overlap frames per side (default: 64)

Output:
  --mp3-bitrate <kbps>    MP3 bitrate (default: 128)

Server:
  --host <addr>           Listen address (default: 127.0.0.1)
  --port <N>              Listen port (default: 8080)
  --max-batch <N>         LM batch limit (default: 1)
  --max-seq <N>           KV cache size (default: 8192)

Debug:
  --no-fsm                Disable FSM constrained decoding
  --no-fa                 Disable flash attention
  --no-batch-cfg          Split CFG into two separate forwards (LM + DiT)
  --clamp-fp16            Clamp hidden states to FP16 range
```

--------------------------------

### Ace Server Usage

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Basic command-line usage for starting the ace-server. Specify the directory containing GGUF model files.

```bash
Usage: ./ace-server --models <dir> [options]

Required:
  --models <dir>          Directory of GGUF model files

Adapter:
  --adapters <dir>        Directory of adapters

Memory control:
  --keep-loaded           Keep models in VRAM between requests
  --vae-chunk <N>         Latent frames per tile (default: 1024)
  --vae-overlap <N>       Overlap frames per side (default: 64)

Server:
  --host <addr>           Listen address (default: 127.0.0.1)
  --port <N>              Listen port (default: 8080)
  --max-batch <N>         LM batch limit (default: 1)
  --max-seq <N>           KV cache size (default: 8192)

Debug:
  --no-fsm                Disable FSM constrained decoding
  --no-fa                 Disable flash attention
  --no-batch-cfg          Split CFG into two separate forwards (LM + DiT)
  --clamp-fp16            Clamp hidden states to FP16 range
```

--------------------------------

### Outpaint Audio with ace-synth

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Generates audio before the start of an existing track by setting a negative `repainting_start`. Requires `--src-audio`.

```bash
cat > /tmp/outpaint.json << 'EOF'
{
    "task_type": "repaint",
    "caption": "Cinematic orchestral intro building into the main theme",
    "lyrics": "[Instrumental]",
    "repainting_start": -5.0,
    "inference_steps": 50,
    "guidance_scale": 1.0,
    "shift": 1.0
}
EOF

./build/ace-synth --models models --src-audio song.wav --request /tmp/outpaint.json
```

--------------------------------

### Build for Linux/macOS with Vulkan

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Use the provided shell script to build the project with Vulkan support on Linux or macOS. Ensure necessary Vulkan development libraries are installed.

```bash
./buildvulkan.sh  # AMD/Intel GPU (Vulkan)
```

--------------------------------

### Get Server Configuration

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Retrieve server configuration, including available models, adapters, and default request parameters.

```json
{
  "models": {
    "lm": ["acestep-5Hz-lm-0.6B-Q8_0.gguf", "acestep-5Hz-lm-4B-Q8_0.gguf"],
    "embedding": ["Qwen3-Embedding-0.6B-Q8_0.gguf"],
    "dit": ["acestep-v15-turbo-Q8_0.gguf", "acestep-v15-xl-turbo-Q8_0.gguf"],
    "vae": ["vae-BF16.gguf"]
  },
  "adapters": [],
  "cli": { "max_batch": 1 },
  "default": { "caption": "", "duration": 0, ... }
}
```

--------------------------------

### Get Server Properties

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Retrieve server configuration, including available models, adapters, and default request parameters.

```http
GET /props
  response: application/json
```

--------------------------------

### Build for Windows with CUDA

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Use the provided batch script to build the project with CUDA support on Windows. Ensure Visual C++ Build Tools and CUDA Toolkit are installed.

```cmd
buildcuda.cmd     # NVIDIA GPU
```

--------------------------------

### Repaint Mode Configuration - Bash

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Configure the repaint mode to regenerate a specific time region of source audio. Define the start and end times in seconds for the region to be repainted. Default start is 0, and default end (-1) resolves to source duration.

```bash
cat > /tmp/repaint.json << 'EOF' \
{
    "task_type": "repaint",
    "caption": "Smooth jazz guitar solo with reverb",
    "lyrics": "[Instrumental]",
    "repainting_start": 10.0,
    "repainting_end": 25.0,
    "inference_steps": 50,
    "guidance_scale": 1.0,
    "shift": 1.0
}
'EOF'

```

--------------------------------

### Build for Linux/macOS with CUDA

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Use the provided shell script to build the project with CUDA support on Linux or macOS. Ensure necessary CUDA development libraries are installed.

```bash
./buildcuda.sh    # NVIDIA GPU
```

--------------------------------

### Ace LM Command Line Usage

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Example command-line usage for the ace-lm executable, specifying model directories and request JSON files. Includes options for debugging and performance tuning.

```bash
Usage: ./ace-lm --models <dir> --request <json> [options]

Required:
  --models <dir>         Directory of GGUF model files
  --request <json>       Input request JSON (carries lm_model)

Debug:
  --max-seq <N>          KV cache size (default: 8192)
  --no-fsm               Disable FSM constrained decoding
  --no-fa                Disable flash attention
  --no-batch-cfg         Split CFG into two separate forwards
  --clamp-fp16           Clamp hidden states to FP16 range
  --dump-logits <path>   Dump prefill logits (binary f32)
  --dump-tokens <path>   Dump prompt token IDs (CSV)
```

--------------------------------

### Outpaint Audio Generation

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Generates audio 5 seconds before the song starts using the 'repaint' task type. Ensure the JSON request file is correctly named.

```json
{
    "task_type": "repaint",
    "caption": "Smooth jazz intro building into the main theme",
    "lyrics": "[Instrumental]",
    "repainting_start": -5.0,
    "inference_steps": 50,
    "guidance_scale": 1.0,
    "shift": 1.0
}
```

```bash
./ace-synth \
    --models models \
    --src-audio song.wav \
    --request /tmp/repaint.json
```

--------------------------------

### Build ACESTEP.cpp on Windows (All Backends)

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Builds the project on Windows with multiple backends enabled (CUDA, Vulkan, CPU) and runtime loading.

```cmd
git submodule update --init

call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"

mkdir build
cd build

rem all backends (CUDA + Vulkan + CPU, runtime loading)
cmake .. -DGGML_CPU_ALL_VARIANTS=ON -DGGML_CUDA=ON -DGGML_VULKAN=ON -DGGML_BACKEND_DL=ON

cmake --build . --config Release -j %NUMBER_OF_PROCESSORS%
```

--------------------------------

### GET /health

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Checks the health status of the server.

```APIDOC
## GET /health

### Description
Performs a health check on the server.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Indicates the server status, typically "ok".

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### GET /logs

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Streams server logs in Server-Sent Events (SSE) format.

```APIDOC
## GET /logs

### Description
Provides a stream of server logs in Server-Sent Events (SSE) format, equivalent to server stderr.

### Method
GET

### Endpoint
/logs

### Response
#### Success Response (200)
- Streams log data in SSE format.
```

--------------------------------

### Build for Windows with All Backends

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Use the provided batch script to build the project with support for all backends (CUDA, Vulkan, CPU) on Windows, enabling runtime loading.

```cmd
buildall.cmd      # all backends (CUDA + Vulkan + CPU, runtime loading)
```

--------------------------------

### GET /job

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Polls the status of a job or fetches its result. Supports job cancellation.

```APIDOC
## GET /job — Poll job status and fetch results

### Description
Polls the status of a job using its ID. If the job is completed, results can be fetched. Jobs can also be cancelled.

### Method
GET

### Endpoint
/job

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the job to poll.
- **result** (integer) - Optional - If set to 1, fetches the job result.
- **cancel** (integer) - Optional - If set to 1, cancels the job.

### Request Example (Check Status)
```bash
curl -sf "http://127.0.0.1:8085/job?id=5"
```

### Request Example (Fetch Result)
```bash
curl -sf "http://127.0.0.1:8085/job?id=5&result=1" -o result.mp3
```

### Request Example (Cancel Job)
```bash
curl -sf -X POST "http://127.0.0.1:8085/job?id=5&cancel=1"
```

### Response
#### Success Response (200 - Status Check)
- **status** (string) - The current status of the job (e.g., "running", "done", "failed").

#### Success Response (200 - Fetch Result)
- Returns the job result data (e.g., MP3 file).

#### Success Response (200 - Cancel Job)
- **status** (string) - The status of the job, should be "cancelled".

#### Response Example (Status)
```json
{
  "status": "done"
}
```
```

--------------------------------

### Build ACESTEP.cpp on Windows (Vulkan)

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Builds the project on Windows with Vulkan support. Requires Visual C++ Build Tools and optionally Vulkan SDK.

```cmd
git submodule update --init

call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"

mkdir build
cd build

rem AMD/Intel GPU (Vulkan)
cmake .. -DGGML_VULKAN=ON

cmake --build . --config Release -j %NUMBER_OF_PROCESSORS%
```

--------------------------------

### GET /health

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Checks the health status of the server. Returns a JSON object indicating the status.

```APIDOC
## GET /health

### Description
Returns `{"status":"ok"}`.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the server.
```

--------------------------------

### Build ACESTEP.cpp on Linux (Vulkan)

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Builds the project on Linux systems with Vulkan support enabled.

```bash
git submodule update --init

mkdir build && cd build

# Linux with Vulkan
cmake .. -DGGML_VULKAN=ON

cmake --build . --config Release -j$(nproc)
```

--------------------------------

### Properties Endpoint

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

The GET /props endpoint returns information about available models, server configuration, and default parameters.

```http
GET /props
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Clone the ACE-Step repository recursively to ensure all submodules are included, then change into the project directory.

```bash
git clone --recurse-submodules https://github.com/ServeurpersoCom/acestep.cpp.git
cd acestep.cpp
```

--------------------------------

### CLI Usage with Adapter

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Demonstrates using the command-line interface for ACE, including specifying adapters for language model and synthesis tasks.

```bash
# CLI usage with adapter
cat > /tmp/adapter-req.json << 'EOF'
{
    "caption": "Chinese new year festive music with traditional instruments",
    "adapter": "ACE-Step-v1.5-chinese-new-year-LoRA",
    "adapter_scale": 1.0,
    "vocal_language": "zh"
}
EOF

./build/ace-lm --models models --request /tmp/adapter-req.json
./build/ace-synth --models models --adapters adapters --request /tmp/adapter-req0.json
```

--------------------------------

### Download ACESTEP.cpp Models

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Downloads pre-quantized GGUF models from Hugging Face using a helper script. Specify model variants or quantizations as needed.

```bash
pip install hf
./models.sh              # Q8_0 turbo essentials (~7.7 GB)
./models.sh --all        # every model, every quant (~97 GB)
./models.sh --quant Q6_K # pick a specific quant (Q4_K_M, Q5_K_M, Q6_K, Q8_0, BF16)
./models.sh --sft        # add SFT DiT variant
./models.sh --shifts     # add shift1/shift3/continuous variants
```

--------------------------------

### Build acestep.cpp with CMake

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Build the project using CMake. Choose the appropriate backend flag for your GPU hardware (CUDA for NVIDIA, HIP for AMD ROCm, Vulkan for AMD/Intel, or CPU_ALL_VARIANTS for Windows).

```bash
git clone --recurse-submodules https://github.com/ServeurpersoCom/acestep.cpp.git
cd acestep.cpp

mkdir build && cd build

# macOS – Metal + Accelerate BLAS are auto-enabled
cmake ..

# Linux – NVIDIA GPU
cmake .. -DGGML_CUDA=ON

# Linux – AMD GPU (ROCm)
cmake .. -DGGML_HIP=ON

# Linux – AMD/Intel GPU (Vulkan)
cmake .. -DGGML_VULKAN=ON

# Windows – all backends (CUDA + Vulkan + CPU, runtime loading)
cmake .. -DGGML_CPU_ALL_VARIANTS=ON -DGGML_CUDA=ON -DGGML_VULKAN=ON -DGGML_BACKEND_DL=ON

cmake --build . --config Release -j$(nproc)
# Result: ace-lm  ace-synth  ace-server  ace-understand  neural-codec  mp3-codec  quantize
```

--------------------------------

### Health Check Endpoint

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

The GET /health endpoint provides a simple status check for the server. It returns a JSON object with a status field.

```http
GET /health
```

--------------------------------

### Understand audio with ace-understand

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Processes source audio through a VAE encode, FSQ tokenize, and LM understand pipeline to generate metadata and lyrics. Requires a directory of GGUF models.

```bash
./ace-understand --models <dir> --src-audio <path> [--request <json>] [options]
```

--------------------------------

### Build for Linux/macOS with All Backends

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Use the provided shell script to build the project with support for all backends (CUDA, Vulkan, CPU) on Linux or macOS, enabling runtime loading. macOS automatically enables Metal and Accelerate BLAS.

```bash
./buildall.sh     # all backends (CUDA + Vulkan + CPU, runtime loading)
```

--------------------------------

### Build ACESTEP.cpp on Windows (NVIDIA GPU)

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Builds the project on Windows with NVIDIA GPU support. Requires Visual C++ Build Tools and optionally CUDA Toolkit.

```cmd
git submodule update --init

call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"

mkdir build
cd build

rem NVIDIA GPU
cmake .. -DGGML_CUDA=ON

cmake --build . --config Release -j %NUMBER_OF_PROCESSORS%
```

--------------------------------

### Build ACESTEP.cpp on macOS

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Builds the project on macOS, automatically enabling Metal and Accelerate BLAS.

```bash
git submodule update --init

mkdir build && cd build

# macOS (Metal + Accelerate BLAS auto-enabled)
cmake ..

cmake --build . --config Release -j$(nproc)
```

--------------------------------

### Build ACESTEP.cpp on Linux (CUDA)

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Builds the project on Linux systems with NVIDIA GPU support enabled. Requires CUDA.

```bash
git submodule update --init

mkdir build && cd build

# Linux with NVIDIA GPU
cmake .. -DGGML_CUDA=ON

cmake --build . --config Release -j$(nproc)
```

--------------------------------

### Download ACE-Step Models

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Download pre-quantized GGUF model files using the provided script. You can download the default set, all models, or specific quantizations. Additional variants like SFT or shift models can also be included.

```bash
pip install hf

./models.sh              # default Q8_0 turbo set (~7.7 GB)
./models.sh --all        # every model, every quantization (~97 GB)
./models.sh --quant Q4_K_M   # specific quantization (Q4_K_M / Q5_K_M / Q6_K / Q8_0 / BF16)
./models.sh --sft        # add SFT DiT variant (50-step, higher quality)
./models.sh --shifts     # add shift1/shift3/continuous DiT variants

# Files placed in models/:
#   Qwen3-Embedding-0.6B-Q8_0.gguf    748 MB   text encoder
#   acestep-5Hz-lm-4B-Q8_0.gguf      4.2 GB   causal LM
#   acestep-v15-turbo-Q8_0.gguf       2.4 GB   DiT (turbo, 8 steps)
#   vae-BF16.gguf                     322 MB   AutoencoderOobleck VAE
```

--------------------------------

### POST /lm — Submit LM generation job

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Submits a Language Model (LM) generation job. Accepts an AceRequest JSON and returns a job ID. Results can be fetched using GET /job?id=N&result=1.

```APIDOC
## POST /lm — Submit LM generation job

Accepts an `AceRequest` JSON. Returns a job ID. Fetch result with `GET /job?id=N&result=1` (returns JSON array of enriched AceRequest objects).

```bash
# Submit LM job
LM_ID=$(curl -sf http://127.0.0.1:8085/lm \
    -H "Content-Type: application/json" \
    -d '{
        "caption": "Upbeat pop rock with driving guitars and catchy hooks",
        "vocal_language": "fr",
        "inference_steps": 8,
        "shift": 3.0,
        "guidance_scale": 1.0
    }' | jq -r '.id')
echo "Job: $LM_ID"

# Poll until done
while true; do
    STATUS=$(curl -sf "http://127.0.0.1:8085/job?id=${LM_ID}" | jq -r '.status')
    [ "$STATUS" = "done" ] && break
    [ "$STATUS" = "failed" ] && echo "FAILED" && exit 1
    sleep 2
done

# Fetch enriched request (JSON array, one element per lm_batch_size)
curl -sf "http://127.0.0.1:8085/job?id=${LM_ID}&result=1" | jq '.[0]' > enriched.json
# enriched.json contains: caption, lyrics, bpm, keyscale, duration, audio_codes, …
```
```

--------------------------------

### Server Options

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Command-line options for configuring and running the Ace-Server.

```APIDOC
## Server Options

```
Usage: ./ace-server --models <dir> [options]

Required:
  --models <dir>          Directory of GGUF model files

Adapter:
  --adapters <dir>        Directory of adapters

Memory control:
  --keep-loaded           Keep models in VRAM between requests
  --vae-chunk <N>         Latent frames per tile (default: 1024)
  --vae-overlap <N>       Overlap frames per side (default: 64)

Output:
  --mp3-bitrate <kbps>    MP3 bitrate (default: 128)

Server:
  --host <addr>           Listen address (default: 127.0.0.1)
  --port <N>              Listen port (default: 8080)
  --max-batch <N>         LM batch limit (default: 1)
  --max-seq <N>           KV cache size (default: 8192)

Debug:
  --no-fsm                Disable FSM constrained decoding
  --no-fa                 Disable flash attention
  --no-batch-cfg          Split CFG into two separate forwards (LM + DiT)
  --clamp-fp16            Clamp hidden states to FP16 range
```
```

--------------------------------

### POST /understand

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Submits an audio file for understanding and returns a job ID. The result is a multipart/mixed response containing metadata and audio codes.

```APIDOC
## POST /understand — Submit understand job

### Description
Accepts multipart/form-data with an audio file (or pre-encoded latents). Returns a job ID. Result is `multipart/mixed`: one JSON part (AceRequest with extracted metadata) + one latent part.

### Method
POST

### Endpoint
/understand

### Parameters
#### Request Body
- **audio** (file) - Required - An audio file to process.

### Request Example
```bash
curl -sf http://127.0.0.1:8085/understand -F "audio=@song.wav"
```

### Response
#### Success Response (200)
- **id** (string) - The job ID for the submitted understand job.

#### Response Example
```json
{
  "id": "some_job_id"
}
```
```

--------------------------------

### Build for Linux/macOS with CPU Only

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

Use the provided shell script to build the project with CPU-only support on Linux or macOS. BLAS is enabled if available.

```bash
./buildcpu.sh     # CPU only (with BLAS)
```

--------------------------------

### Build neural-codec Executable

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/CMakeLists.txt

Sets up the neural-codec executable for Oobleck VAE neural audio codec operations, encoding and decoding WAV to latent representations. It links against ggml backends.

```cmake
# neural-codec: Oobleck VAE neural audio codec (encode/decode WAV <-> latent)
add_executable(neural-codec tools/neural-codec.cpp)
link_ggml_backends(neural-codec)
```

--------------------------------

### Generate Audio with Adapter using ace-synth

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Synthesize audio using a specified adapter (e.g., LoRA) by providing the adapter file in the JSON and the adapter directory path to the `--adapters` argument. The `adapter_scale` can also be adjusted.

```bash
# JSON carries the adapter name, CLI passes the directory
cat > /tmp/request.json << 'EOF' {
    "caption": "Upbeat pop rock with driving guitars and catchy hooks",
    "adapter": "best_sft_v2_2338_comfyui.safetensors",
    "adapter_scale": 1.0,
    "vocal_language": "fr"
}
EOF

./ace-synth \
    --models models \
    --adapters adapters \
    --request /tmp/request0.json
```

--------------------------------

### Download ACE-Step Models

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/models/README.md

Use this script to download all necessary GGUF model files from the Hugging Face repository. Ensure you have execute permissions for the script.

```bash
./models.sh
```

--------------------------------

### Server Configuration

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Retrieves the server's configuration, including available models, presets, and defaults.

```APIDOC
## GET /props

### Description
Server config, models, presets, defaults.

### Method
GET

### Endpoint
/props

### Response
#### Success Response (200)
- **models** (object) - Contains lists of available models for different tasks (lm, embedding, dit, vae).
- **adapters** (array) - List of available adapters.
- **cli** (object) - Command-line interface configuration, including max batch size.
- **default** (object) - Default AceRequest parameters.
```

--------------------------------

### Build quantize Executable

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/CMakeLists.txt

Configures the quantize executable, a GGUF requantizer for converting BF16 to K-quants. It links against ggml backends.

```cmake
# quantize: GGUF requantizer (BF16 -> K-quants)
add_executable(quantize tools/quantize.cpp)
link_ggml_backends(quantize)
```

--------------------------------

### Text-to-Music Generation (Default Mode)

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Generates music from a text caption. Requires specifying caption, lyrics (optional), duration, and inference steps.

```bash
cat > /tmp/t2m.json << 'EOF'
{
    "caption": "Cinematic orchestral score, sweeping strings, dramatic brass, epic battle theme",
    "lyrics": "[Instrumental]",
    "duration": 60,
    "inference_steps": 8,
    "shift": 3.0
}
EOF
./build/ace-lm --models models --request /tmp/t2m.json
./build/ace-synth --models models --request /tmp/t2m0.json
```

--------------------------------

### POST /understand

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

A reverse pipeline that takes audio input and outputs metadata, lyrics, and codes. Accepts multipart requests only.

```APIDOC
## POST /understand

### Description
Reverse pipeline: audio in, metadata + lyrics + codes out. Multipart only (source audio or pre-encoded latents required, optional request JSON for params).

Understand responses are multipart/mixed too: one JSON part plus the latent of the input source audio.

### Method
POST

### Endpoint
/understand
```

--------------------------------

### Build ACESTEP.cpp on Linux (ROCm)

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Builds the project on Linux systems with AMD GPU support enabled. Requires ROCm.

```bash
git submodule update --init

mkdir build && cd build

# Linux with AMD GPU (ROCm)
cmake .. -DGGML_HIP=ON

cmake --build . --config Release -j$(nproc)
```

--------------------------------

### Accuracy Testing Scripts

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Command-line instructions for running accuracy comparison scripts between GGML C++ and Python implementations.

```bash
cd tests
python3 debug-lm-logits.py    # Qwen3 LM: first-token logits GGML vs PyTorch (0.6B/1.7B/4B)
python3 debug-detok-cossim.py # FSQ detokenizer: step-by-step cossim C++ vs Python
python3 debug-dit-cossim.py   # DiT: per-layer cossim GGML vs Python (turbo/SFT, BF16/quantized)
```

--------------------------------

### Build ace-understand Executable

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/CMakeLists.txt

Defines the ace-understand executable, used for understanding purposes. It depends on the acestep-core library.

```cmake
add_executable(ace-understand tools/ace-understand.cpp)
target_link_libraries(ace-understand PRIVATE acestep-core)
link_ggml_backends(ace-understand)
```

--------------------------------

### Generate Audio with ace-lm and ace-synth

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Use `ace-lm` to generate metadata, lyrics, and codes from a request JSON, then use `ace-synth` to synthesize audio. Ensure the `--models` argument points to the model directory.

```bash
cat > /tmp/request.json << 'EOF' {
    "caption": "Upbeat pop rock with driving guitars and catchy hooks",
    "inference_steps": 8,
    "shift": 3.0,
    "vocal_language": "fr"
}
EOF

# LLM: request.json -> request0.json (enriched with metadata + lyrics + codes)
./ace-lm \
    --models models \
    --request /tmp/request.json

# DiT+VAE: request0.json -> request00.mp3
./ace-synth \
    --models models \
    --request /tmp/request0.json
```

--------------------------------

### Build ace-server Executable

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/CMakeLists.txt

Configures the main ace-server executable, which includes the embedded web UI. It links against the acestep-core and httplib libraries.

```cmake
# ace-server: HTTP server (LM + synth endpoints + embedded webui)
add_executable(ace-server tools/ace-server.cpp ${WEBUI_OUTPUT})
target_include_directories(ace-server PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
target_link_libraries(ace-server PRIVATE acestep-core httplib)
link_ggml_backends(ace-server)
```

--------------------------------

### Generate Multiple Songs in Batch with ace-lm and ace-synth

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Generate multiple songs from a single prompt by setting `lm_batch_size` in the request JSON. `ace-lm` will produce multiple request files, and `ace-synth` can process them in a single GPU batch.

```bash
# 2 different songs from one prompt (different lyrics, codes, metadata)
cat > /tmp/request.json << 'EOF' {
    "caption": "Upbeat pop rock anthem with driving guitars and catchy hooks",
    "vocal_language": "fr",
    "lm_batch_size": 2
}
EOF

# LM: request.json (lm_batch_size=2) -> request0.json, request1.json
./ace-lm \
    --models models \
    --request /tmp/request.json

# DiT+VAE: both requests in one GPU batch -> request00.mp3, request10.mp3
./ace-synth \
    --models models \
    --request /tmp/request0.json /tmp/request1.json
```

--------------------------------

### Ace-LM and Ace-Synth CLI Usage

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

These CLI tools can be used for scripting audio generation tasks without the server. Ace-LM generates lyrics and codes, while Ace-Synth renders audio from codes. Both require model and request file paths.

```bash
# LM generates lyrics + codes
./build/ace-lm \
    --models models \
    --request /tmp/request.json
```

```bash
# DiT + VAE render to audio
./build/ace-synth \
    --models models \
    --request /tmp/request0.json
```

--------------------------------

### Submit Understand Job

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Submit an 'understand' job. Requires multipart/form-data with audio or src_latents, and an optional request JSON.

```http
POST /understand
  body: multipart/form-data (audio or src_latents required, optional request JSON)
  response: {"id":"3"}
```

--------------------------------

### Transform Audio with ace-synth using --src-audio

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

Transform an existing audio file into a new song with specified parameters using `ace-synth`. The LLM is not involved in this process. Provide the source audio path with `--src-audio` and the transformation request in JSON.

```bash
cat > /tmp/cover.json << 'EOF' {
    "task_type": "cover",
    "caption": "Jazz piano cover with brushed drums and walking bass",
    "lyrics": "[Instrumental]"
}
EOF

./ace-synth \
    --models models \
    --src-audio song.wav \
    --request /tmp/cover.json
```

--------------------------------

### SDE Stochastic Sampling for Varied Outputs

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Generates music using stochastic differential equations (SDE) for varied outputs based on a seed. Requires specifying caption, vocal language, inference method, seed, and inference steps.

```bash
cat > /tmp/sde.json << 'EOF'
{
    "caption": "Lo-fi hip hop with mellow chords and vinyl crackle",
    "vocal_language": "en",
    "infer_method": "sde",
    "seed": 42,
    "inference_steps": 50,
    "shift": 1.0
}
EOF
./build/ace-lm --models models --request /tmp/sde.json
./build/ace-synth --models models --request /tmp/sde0.json
```

--------------------------------

### Multi-File Batch Synthesis with ace-synth

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Processes multiple request JSONs in a single GPU batch for efficient synthesis of batched audio files.

```bash
./build/ace-synth \
    --models models \
    --request /tmp/batch0.json /tmp/batch1.json /tmp/batch2.json
```

--------------------------------

### Build mp3-codec Executable with Platform-Specific Options

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/CMakeLists.txt

Configures the mp3-codec executable for standalone MP3 encoding/decoding. It includes platform-specific compile options for MSVC and GCC/Clang, and links against the 'm' and Threads::Threads libraries.

```cmake
# mp3-codec: MP3 encoder/decoder (standalone, no ggml needed)
# The mp3/ headers are header-only and usable by ace-synth too via #include "mp3/mp3enc.h"
add_executable(mp3-codec tools/mp3-codec.cpp)
target_include_directories(mp3-codec PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/src
    ${CMAKE_CURRENT_SOURCE_DIR}
    ${CMAKE_CURRENT_BINARY_DIR}
)
add_dependencies(mp3-codec version)
if(MSVC)
    target_compile_options(mp3-codec PRIVATE /W4 /wd4100 /wd4505)
else()
    target_compile_options(mp3-codec PRIVATE -Wall -Wextra -Wconversion
                          -Wno-unused-parameter -Wno-unused-function -Wno-sign-conversion)
    target_link_libraries(mp3-codec PRIVATE m)
endif()
target_link_libraries(mp3-codec PRIVATE Threads::Threads)
```

--------------------------------

### Understand API Endpoint

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/README.md

The POST /understand endpoint performs a reverse pipeline, taking audio as input and returning metadata, lyrics, and codes. It requires multipart requests with source audio or pre-encoded latents.

```http
POST /understand
```

--------------------------------

### Synthesis with LoRA Adapter using ace-synth

Source: https://context7.com/serveurpersocom/acestep.cpp/llms.txt

Applies a LoRA adapter to modify the generation style. Specify the adapter file with `--adapters` and the adapter name in the request JSON.

```bash
cat > /tmp/adapter.json << 'EOF'
{
    "caption": "Upbeat French pop with accordion and musette rhythm",
    "adapter": "french-musette-v1.safetensors",
    "adapter_scale": 1.0,
    "vocal_language": "fr"
}
EOF

./build/ace-synth \
    --models models \
    --adapters adapters \
    --request /tmp/adapter.json
```

--------------------------------

### Text-to-Music Request Parameters

Source: https://github.com/serveurpersocom/acestep.cpp/blob/master/docs/ARCHITECTURE.md

This section details the parameters available for configuring text-to-music generation requests. All fields have default values, and omitting a field is equivalent to using its default. The `caption` field is effectively required for meaningful output.

```APIDOC
## Request JSON Reference

Every field below has a default. Omitting a field from the JSON is strictly
equivalent to sending that field with its default value. Only `caption` is
effectively required: the other defaults produce a valid text2music job on
their own, but without caption the LLM has nothing to work from.

```json
{
    "caption":              "",
    "lyrics":               "",
    "bpm":                  0,
    "duration":             0,
    "keyscale":             "",
    "timesignature":        "",
    "vocal_language":       "",
    "seed":                 -1,
    "lm_batch_size":        1,
    "synth_batch_size":     1,
    "lm_temperature":       0.85,
    "lm_cfg_scale":         2.0,
    "lm_top_p":             0.9,
    "lm_top_k":             0,
    "lm_negative_prompt":   "",
    "use_cot_caption":      true,
    "audio_codes":          "",
    "inference_steps":      0,
    "guidance_scale":       0.0,
    "shift":                0.0,
    "dcw_scaler":           0.0,
    "dcw_high_scaler":      0.0,
    "dcw_mode":             "low",
    "audio_cover_strength": 1.0,
    "cover_noise_strength": 0.0,
    "repainting_start":     0,
    "repainting_end":       -1,
    "latent_shift":         0.0,
    "latent_rescale":       1.0,
    "custom_timesteps":     "",
    "task_type":            "text2music",
    "track":                "",
    "infer_method":         "ode",
    "lm_mode":              "generate",
    "output_format":        "mp3",
    "peak_clip":            10,
    "mp3_bitrate":          128,
    "synth_model":          "",
    "lm_model":             "",
    "adapter":              "",
    "adapter_scale":        1.0
}
```

`synth_model`, `lm_model` and `adapter` are resolved through the model
registry, scanned from `--models <dir>` (and `--adapters <dir>` for
adapters), by both the HTTP server and the CLI binaries (`ace-lm`,
`ace-synth`, `ace-understand`). Values are GGUF filenames without the
`.gguf` suffix; an empty string falls to the first matching entry of the
registry. There is no CLI flag to bypass the JSON: model selection is a
property of the request, not of the command line.

`lm_mode` picks the LM instruction: `"generate"` (full: metadata + lyrics
+ codes), `"inspire"` (short query to metadata + lyrics, no codes),
`"format"` (caption + lyrics to metadata + lyrics, no codes). `output_format`
picks the audio encoder: `"mp3"`, `"wav16"`, `"wav24"`, `"wav32"`.

### Text conditioning (ace-lm + ace-synth)

**`caption`** (string, required)
Natural language description of the music style, mood, instruments, etc.
Fed to both the LLM and the DiT text encoder.

**`lyrics`** (string, default `""`)
Controls vocal generation. Three valid states:
- `""`: LLM generates lyrics from the caption (phase 1 "Expand" prompt).
- `"[Instrumental]"`: no vocals. Passed directly to the DiT, LLM skips lyrics generation.
- Any other string: user-provided lyrics used as-is, LLM only fills missing metadata.

There is no `instrumental` flag. This field is the single source of truth for
vocal content.

### Metadata (LLM-filled if unset)

**`bpm`** (int, default `0` = unset)
Beats per minute. LLM generates one if 0.

**`duration`** (float seconds, default `0` = unset)
Target audio duration. `0` means the LLM picks it. FSM constrains LLM output
to [10, 600]s; values <= 0 after generation fall back to 120s.

**`keyscale`** (string, default `""` = unset)
Musical key and scale, e.g. `"C major"`, `"F# minor"`. LLM fills if empty.

**`timesignature`** (string, default `""` = unset)
Time signature numerator as a string, e.g. `"4"` for 4/4, `"3"` for 3/4.
LLM fills if empty.

**`vocal_language`** (string, default `""` = unset)
BCP-47 language code for lyrics, e.g. `"en"`, `"fr"`, `"ja"`. Three states:
- `""`: LLM detects the language via CoT and fills this field.
- `"unknown"`: explicit "no specific language" signal to the DiT.
- Any language code: used as-is. When lyrics are being generated, the FSM
  constrains the LLM output to that language.

### Generation control

**`seed`** (int64, default `-1` = random)
RNG seed for the DiT pipeline (Philox noise). The LM always uses a
random seed internally.

**`lm_batch_size`** (int, default `1`)
Number of LM variations. Has no effect on ace-synth.

**`synth_batch_size`** (int, default `1`)
Number of DiT variations per request. Works in all modes: text2music,
cover, repaint, lego, extract, complete. Combined with `lm_batch_size`, you get
`lm_batch_size * synth_batch_size` total outputs.

```