### Linux ROCm GPU Setup - Start Service

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Launch the ACE-Step service with the specified port after installation.

```bash
# 4. Start the service
python -m acestep.acestep_v15_pipeline --port 7680
```

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

### Nano-vLLM Quick Start Example

Source: https://github.com/ace-step/ace-step-1.5/blob/main/acestep/third_parts/nano-vllm/README.md

Initialize the LLM with your model path and generate text using specified sampling parameters. The API mirrors vLLM's interface.

```python
from nanovllm import LLM, SamplingParams
llm = LLM("/YOUR/MODEL/PATH", enforce_eager=True, tensor_parallel_size=1)
sampling_params = SamplingParams(temperature=0.6, max_tokens=256)
prompts = ["Hello, Nano-vLLM."]
outputs = llm.generate(prompts, sampling_params)
outputs[0]["text"]
```

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

### Install uv package manager

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/ace_step_musicians_guide.md

On Mac or Linux, install the 'uv' package manager as a one-time setup step before installing ACE-Step.

```bash
Step 1:  Install the "uv" package manager (a one-time setup)
```

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

### Run Training with Wizard Mode

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/sidestep/End-to-End Tutorial.md

Use this command to start the training process in wizard mode, which loads a preset at the beginning. This is useful for quick setup and optimization based on GPU VRAM.

```bash
uv run train.py    # wizard mode, load a preset at the start
```

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

### Install uv and ACE-Step Dependencies

Source: https://github.com/ace-step/ace-step-1.5/blob/main/README.md

Installs the `uv` package manager and then synchronizes project dependencies using `uv sync`. Ensure Python 3.11-3.12 is installed. CUDA GPU is recommended.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh          # macOS / Linux
#powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

git clone https://github.com/ACE-Step/ACE-Step-1.5.git
cd ACE-Step-1.5
uv sync
```

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

### Run ACE-Step CLI Wizard

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/CLI.md

Launches the interactive wizard to guide through ACE-Step inference setup.

```bash
python cli.py
```

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

### Install Side-Step on Windows using PowerShell

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/sidestep/RepositoryREADME.md

This PowerShell script clones the Side-Step repository and executes the Windows installation script. It automates the setup of 'uv', Python 3.11, Side-Step dependencies, and optionally ACE-Step for checkpoints and vanilla training mode.

```powershell
# Or run from PowerShell directly:
git clone https://github.com/koda-dernet/Side-Step.git
cd Side-Step
.
install_windows.ps1
```

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

### Install Dependencies

Source: https://github.com/ace-step/ace-step-1.5/blob/main/AGENTS.md

Installs project dependencies using uv.

```bash
# Install dependencies
uv sync
```

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

### Launch Gradio UI on Linux

Source: https://github.com/ace-step/ace-step-1.5/blob/main/README.md

Make the shell script executable and then run it to start the Gradio UI on a Linux system. This script handles environment setup.

```bash
chmod +x start_gradio_ui.sh && ./start_gradio_ui.sh
```

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

### Install ACE-Step dependencies

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/ace_step_musicians_guide.md

On Mac or Linux, run 'uv sync' to install all necessary dependencies after downloading ACE-Step from GitHub.

```bash
Step 3:  Run "uv sync" to install everything
```

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

### Install ACE-Step and Dependencies

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/Large_Scale_SFT_Training_Guide.md

Clone the ACE-Step repository and install necessary Python dependencies. Ensure the Hugging Face CLI is also installed for dataset management.

```bash
git clone https://github.com/ace-step/ACE-Step-1.5.git
cd ACE-Step-1.5

pip install -r requirements.txt

pip install huggingface_hub[cli]
```

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

### Install Dependencies from requirements.txt

Source: https://github.com/ace-step/ace-step-1.5/blob/main/requirements-rocm.txt

Installs all remaining core and optional training dependencies listed in the requirements-rocm.txt file.

```bash
pip install -r requirements-rocm.txt
```

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

### Set up Vanilla Training Mode

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/sidestep/RepositoryREADME.md

Clone the ACE-Step repository alongside Side-Step to enable vanilla training mode. The setup wizard will prompt for configuration on the first run.

```bash
# Clone ACE-Step alongside Side-Step
git clone https://github.com/ace-step/ACE-Step-1.5.git
cd ACE-Step-1.5 && uv sync && cd ..

# On first run, Side-Step's setup wizard will ask if you want vanilla mode
# and where your ACE-Step installation is.
```

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

### Run Automatic Setup Script

Source: https://github.com/ace-step/ace-step-1.5/blob/main/README-XPU.md

Execute the batch file to automatically set up the ACE-Step environment for Intel XPU. This is the recommended setup method.

```bat
setup_xpu.bat
```

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

### Music Caption Example

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/GRADIO_GUIDE.md

An example of a detailed music caption for guiding music generation.

```text
upbeat pop rock with electric guitars, driving drums, and catchy synth hooks
```

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

### Configure start_api_server.bat for ACE-Step

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Configure LLM initialization via environment variable in start_api_server.bat.

```batch
REM LLM initialization via environment variable
REM set ACESTEP_INIT_LLM=true   # Force enable LLM
REM set ACESTEP_INIT_LLM=false  # Force disable LLM (DiT-only mode)
```

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

### Configure start_gradio_ui.bat for ACE-Step

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Set UI language, download source, update check, and model paths in start_gradio_ui.bat.

```batch
REM UI language (en, zh, he, ja)
set LANGUAGE=zh

REM Download source (auto, huggingface, modelscope)
set DOWNLOAD_SOURCE=--download-source modelscope

REM Git update check (true/false)
set CHECK_UPDATE=true

REM Model configuration
set CONFIG_PATH=--config_path acestep-v15-turbo
set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-1.7B
```

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

### Linux ROCm GPU Setup - Install ACE-Step

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Install ACE-Step in editable mode after setting up the ROCm environment.

```bash
# 3. Install ACE-Step
pip install -e .
```

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

### Linux ROCm GPU Setup - Install PyTorch

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Install a ROCm-compatible version of PyTorch using the specified index URL.

```bash
# 2. Install ROCm-compatible PyTorch
pip install torch --index-url https://download.pytorch.org/whl/rocm6.0
```

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

### Copy and Edit .env Example

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Copy the example .env file to create your own configuration file and edit it with your custom settings.

```bash
cp .env.example .env
```

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

### Windows ROCm GPU Setup - Install Dependencies

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Install the necessary ROCm SDK and PyTorch wheels from AMD's repository using the provided requirements file.

```bash
# 3. Follow the installation steps in requirements-rocm.txt
# This installs ROCm SDK and PyTorch wheels from AMD's repository

# 4. Install dependencies
pip install -r requirements-rocm.txt
```

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

### Full SFT Training Command Example

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/Large_Scale_SFT_Training_Guide.md

Example command to initiate full SFT training using 8 H100 GPUs. Ensure the code modifications for DeepSpeed are applied.

```bash
# 8x H100 full SFT
python -m acestep.training_v2.cli.train_fixed \
    --dataset-dir ./preprocessed_tensors_all \
    --output-dir ./output/full_sft_muse \
    --checkpoint-dir ./checkpoints \
    --model-variant turbo \
    --full-sft \
    --batch-size 8 \
    --gradient-accumulation-steps 4 \
    --max-epochs 20 \
    --learning-rate 1e-5 \
    --warmup-steps 2000 \
    --weight-decay 0.01 \
    --optimizer-type adamw \
    --scheduler-type cosine \
    --gradient-checkpointing \
    --num-devices 8 \
    --strategy ddp \
    --save-every-n-epochs 2 \
    --yes
```

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

### Get Random Sample

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/API.md

Returns random sample parameters from pre-loaded example data for form filling.

```APIDOC
## POST /create_random_sample

### Description
Returns random sample parameters from pre-loaded example data for form filling.

### Method
POST

### Endpoint
/create_random_sample

### Parameters
#### Request Body
- **sample_type** (string) - Optional - Sample type: `"simple_mode"` or `"custom_mode"`

### Request Example
{
  "sample_type": "simple_mode"
}

### Response
#### Success Response (200)
- **data** (object) - Contains the random sample parameters.
  - **caption** (string) - Upbeat pop song with guitar accompaniment.
  - **lyrics** (string) - Verse 1 of the lyrics.
  - **bpm** (integer) - Beats per minute.
  - **key_scale** (string) - Musical key and scale.
  - **time_signature** (string) - Time signature.
  - **duration** (integer) - Duration in seconds.
  - **vocal_language** (string) - Language of the vocals.
- **code** (integer) - HTTP status code.
- **error** (null) - Error message, if any.
- **timestamp** (integer) - Timestamp of the response.
- **extra** (null) - Additional data, if any.

#### Response Example
{
  "data": {
    "caption": "Upbeat pop song with guitar accompaniment",
    "lyrics": "[Verse 1]\nSunshine on my face...",
    "bpm": 120,
    "key_scale": "G Major",
    "time_signature": "4",
    "duration": 180,
    "vocal_language": "en"
  },
  "code": 200,
  "error": null,
  "timestamp": 1700000000000,
  "extra": null
}
```

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

### Clone Side-Step and Install Dependencies on Linux/macOS

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/sidestep/RepositoryREADME.md

This snippet shows how to clone the Side-Step repository and install its dependencies using 'uv', which automatically handles Python, PyTorch with CUDA, and other required packages. The first run will prompt for setup details.

```bash
# 1. Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone Side-Step
git clone https://github.com/koda-dernet/Side-Step.git
cd Side-Step

# 3. Install dependencies (includes PyTorch with CUDA + Flash Attention)
uv sync

# 4. First run will guide you through setup (checkpoint path, etc.)
uv run python train.py
```

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

### Run Vanilla Training with ACE-Step

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/sidestep/RepositoryREADME.md

This command initiates vanilla training using ACE-Step, reproducing its original behavior. Ensure ACE-Step and Side-Step are installed. Specify directories for checkpoints, audio, and output.

```bash
uv run python train.py vanilla \
    --checkpoint-dir ./ACE-Step-1.5/checkpoints \
    --audio-dir ./my_audio \
    --output-dir ./output/my_vanilla_lora
```

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

### Linux ROCm GPU Setup - Virtual Environment

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Create and activate a Python virtual environment for your ROCm installation on Linux.

```bash
# 1. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate
```

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

### Pre-initialize Models on Startup

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Starts the ACE-Step service with models pre-initialized to speed up the first generation.

```bash
uv run acestep --init_service true --config_path acestep-v15-turbo
```

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

### Windows ROCm GPU Setup - Virtual Environment

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Create and activate a Python virtual environment for your ROCm installation on Windows.

```bash
# 2. Create and activate a virtual environment
python -m venv venv_rocm
venv_rocm\Scripts\activate
```

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

### Good Captions for Music Generation

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INFERENCE.md

Examples of specific and descriptive captions, including mood and genre, to guide music generation.

```python
# Specific and descriptive
caption="upbeat electronic dance music with heavy bass and synthesizer leads"

# Include mood and genre
caption="melancholic indie folk with acoustic guitar and soft vocals"
```

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

### Launch ACE-Step Applications

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Launches the Gradio Web UI or the REST API server using uv. Models are downloaded automatically on first run.

```bash
# Gradio Web UI (Recommended):
uv run acestep

# REST API Server:
uv run acestep-api
```

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

### Windows ROCm GPU Setup - Python Version Check

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Verify that Python 3.12 is installed, as it is required for AMD ROCm 7.2 on Windows.

```bash
# 1. Ensure you have Python 3.12 installed
python --version  # Should show Python 3.12.x
```

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

### Update Workflow Example (Windows)

Source: https://github.com/ace-step/ace-step-1.5/blob/main/docs/en/INSTALL.md

Execute check_update.bat followed by merge_config.bat for the update workflow on Windows.

```bash
check_update.bat          # 1. Check for updates (requires PortableGit/)
```

```bash
merge_config.bat          # 2. Merge settings back if conflicts occur
```