Skip to content

This PR resolves a critical runtime crash during the audio export stage on Linux systems, specifically occurring in Cloud environments like Lightning AI. #1089

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sobiswriter wants to merge 8 commits into
base: main
Choose a base branch
from
Open

This PR resolves a critical runtime crash during the audio export stage on Linux systems, specifically occurring in Cloud environments like Lightning AI. #1089

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ed95f0e
fix(audio): resolve export crashes on Linux/Cloud envs like lightning…
Apr 11, 2026
0457406
Fix audio export handling and improve cloud GPU compatibility
Apr 13, 2026
7f4b5db
Merge branch 'main' into fix/audio-export-linux
sobiswriter Apr 13, 2026
025006e
Merge branch 'ace-step:main' into fix/audio-export-linux
sobiswriter Apr 15, 2026
16be021
feat: fixed the default .env.example & the install.md documentation f…
Apr 15, 2026
6dba85e
Update INSTALL.md for clarity and formatting
sobiswriter Apr 15, 2026
da822f3
Clean up blank lines in .env.example
sobiswriter Apr 15, 2026
b5601df
Merge branch 'main' into fix/audio-export-linux
sobiswriter Apr 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ ACESTEP_LM_BACKEND=vllm
#
# Default: auto (based on GPU VRAM detection)
ACESTEP_INIT_LLM=auto

ACESTEP_FORCE_FLAC_EXPORT=1
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
# ==================== Model Storage ====================
# Shared checkpoints directory (useful when running multiple installations)
# Point all installations to the same folder to avoid duplicate model downloads.
Expand Down
8 changes: 7 additions & 1 deletion acestep/audio_utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,10 @@ def save_audio(
Actual saved file path
"""
format = (format or self.default_format).lower()

force_flac = os.getenv("ACESTEP_FORCE_FLAC_EXPORT", "0") == "1"
if force_flac:
format = "flac"
Comment on lines +219 to +221
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Forced FLAC can produce extension/content mismatch (e.g., .mp3 file containing FLAC).

At Line 221, format is forced to "flac", but if output_path already has .mp3/.wav (Line 233), suffix normalization won’t rewrite it. With upstream callers prebuilding names from requested format, this can save FLAC bytes under non-FLAC extensions.

Proposed fix 
         force_flac = os.getenv("ACESTEP_FORCE_FLAC_EXPORT", "0") == "1"
         if force_flac:
-            format = "flac" 
+            format = "flac"

         # Ensure output path has correct extension
         output_path = Path(output_path)
+        if force_flac and output_path.suffix.lower() != ".flac":
+            output_path = output_path.with_suffix(".flac")

Also applies to: 228-240

🧰 Tools
🪛 Ruff (0.15.9)

[error] 222-222: Variable format is shadowing a Python builtin

(A001)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@acestep/audio_utils.py` around lines 220 - 222, The current force_flac branch
sets format = "flac" but leaves output_path's filename/extension unchanged,
causing extension/content mismatches; when ACESTEP_FORCE_FLAC_EXPORT is "1"
(force_flac), update output_path to match the forced format (e.g., use
pathlib.Path(output_path).with_suffix(f".{format}") or rebuild the filename from
format) and ensure any downstream suffix normalization logic (the block around
output_path and its suffix handling) uses the updated format so saved bytes and
file extension are consistent; reference the force_flac variable, format
assignment, and output_path handling in your change.

if format not in ["flac", "wav", "mp3", "wav32", "opus", "aac"]:
logger.warning(f"Unsupported format {format}, using {self.default_format}")
format = self.default_format
Expand Down Expand Up @@ -308,8 +312,10 @@ def save_audio(
str(output_path),
audio_tensor,
sample_rate,
channels_first=True,
channels_first=channels_first,
#backend="soundfile" #safe dependency
)


logger.debug(f"[AudioSaver] Saved audio to {output_path} ({format}, {sample_rate}Hz)")
return str(output_path)
Expand Down
11 changes: 11 additions & 0 deletions docs/en/INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,8 +126,19 @@ chmod +x start_gradio_ui.sh start_api_server.sh

# Launch REST API Server
./start_api_server.sh

> [!IMPORTANT]
> **Cloud GPU Users (Lightning AI, Lambda, etc.):**
> To prevent audio export crashes (`libtorchcodec` or `libavutil` errors), you must install the following system dependencies before running the application:
> ```bash
> sudo apt-get update && sudo apt-get install -y ffmpeg libavdevice60 libavcodec-extra
> If you encounter torchcodec / FFmpeg related errors during audio export:
> export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
```




> **Note:** Git must be installed via your system package manager (`sudo apt install git`, `sudo yum install git`, `sudo pacman -S git`).

### macOS (Apple Silicon / MLX)
Expand Down