UI Support Baseline

This document defines the current ACE-Step UI surface area before work begins on a new beginner-friendly UI. It separates product UI, experimental UI, command-line workflows, and API-only integration surfaces so future UI work can preserve capability coverage without keeping multiple overlapping frontends alive.

Support Boundary

Surface	Entry point	Status	Notes
Gradio Web UI	acestep/acestep_v15_pipeline.py, acestep.ui.gradio	Primary supported UI	Main interactive product surface for generation, editing, training, dataset building, model setup, help, and i18n.
Gradio-mounted REST API	--enable-api, acestep/ui/gradio/api/api_routes.py	Supported integration surface	Optional API routes hosted alongside Gradio. Keep behavior stable for local integrations.
Standalone REST API server	acestep-api, acestep/api_server.py	Supported API-only surface	Service/integration interface. Not a UI, but a likely backend dependency for future UIs.
OpenRouter-compatible API server	acestep-openrouter, openrouter/openrouter_api_server.py	Supported API-only surface	OpenAI/OpenRouter-compatible integration path. Not a UI.
Generation CLI	cli.py, acestep console script	Supported command-line workflow	Useful for scripting, configuration, and non-browser generation. Not a replacement for the web UI.
Side-Step training CLI/wizard	train.py, acestep/training_v2/ui	Supported or separately scoped training workflow	Rich terminal workflow for training. Do not remove until Gradio training parity and Side-Step ownership are explicitly reviewed.
Static Studio HTML UI	ui/studio.html	Removed	The experimental frontend-only prototype was removed to avoid duplicating product UI surface area before new UI work.
Streamlit UI	acestep/ui/streamlit	Removed	The experimental prototype was removed because it duplicated product UI responsibilities with its own model cache, navigation, settings, project storage, and docs.

Near-Term Cleanup Plan

1. Keep Gradio as the supported product UI while the next UI is designed.
2. Keep API servers as integration surfaces, not as UI cleanup targets.
3. Defer any CLI or Side-Step training wizard decisions until feature parity is reviewed.

Gradio Feature Coverage Matrix

Any future UI should preserve the functional coverage below, even if it presents the workflow with friendlier defaults and progressive disclosure.

Area	Current capability	Current location	Audience tier	Future UI requirement
Launch and runtime setup	Port, share, debug, server name, allowed paths, authentication	acestep/acestep_v15_pipeline.py	Admin	Preserve as launch/configuration options, not first-run clutter.
Hardware adaptation	GPU detection, VRAM tiers, duration/batch limits, LM defaults, offload defaults, quantization defaults	acestep/acestep_v15_pipeline.py, acestep/gpu_config.py	Beginner/Admin	Show a clear readiness summary and hide unsafe options by default.
Model initialization	DiT model selection, device, flash attention, compile, offload, quantization, download source	Gradio service configuration	Admin	Keep full control, but provide an obvious recommended path.
LM initialization	LM model selection, backend, init toggle, CPU offload	Gradio service configuration	Advanced/Admin	Explain optional vs required LM behavior in plain language.
LoRA inference	LoRA path, load/unload, use toggle	Gradio advanced settings	Advanced	Preserve adapter loading and clear compatibility warnings.
Simple generation	Natural-language song request, random sample, instrumental toggle, language hint, LM sample creation	Generation tab, Simple mode	Beginner	Make this the primary first-run path.
Custom generation	Caption, lyrics, reference audio, sample creation, caption/lyrics formatting	Generation tab, Custom mode	Beginner/Advanced	Keep manual control while guiding users through required inputs.
Remix	Source audio, target caption/lyrics, source codes, remix/code strength, no-FSQ option	Generation tab, Remix mode	Intermediate	Explain that Remix performs cover-style transformation.
Repaint	Source audio, time range, repaint mode, repaint strength, caption/lyrics	Generation tab, Repaint mode	Intermediate	Provide timeline-oriented controls when possible.
Extract	Source audio and target track selection	Generation tab, Extract mode	Advanced	Preserve base-model-only gating.
Lego	Source audio, target track, caption/lyrics	Generation tab, Lego mode	Advanced	Preserve base-model-only gating and track guidance.
Complete	Source audio, track selection, caption/lyrics	Generation tab, Complete mode	Advanced	Preserve base-model-only gating and arrangement-oriented help.
Audio codes	Source audio code extraction, code hints, transcription/analysis hooks	Generation tab source/code controls	Expert	Keep available behind an expert section.
Metadata controls	Duration, BPM, key/scale, time signature, vocal language, seed, inference steps	Generation tab optional controls	Beginner/Advanced	Offer auto defaults first, then explicit controls.
Diffusion controls	Guidance, shift, CFG interval, ADG, inference method, scheduler/timesteps, DCW	Advanced DiT settings	Expert	Keep out of the default path; preserve exact parameter access.
LM controls	Thinking, temperature, CFG scale, top-k, top-p, CoT toggles, constrained decoding	Advanced LM settings	Expert	Preserve with concise help and safe defaults.
Batch generation	Batch size, random seeds, explicit seed lists, background next-batch generation	Generation controls and results events	Advanced	Preserve efficient repeated generation and seed reproducibility.
Results playback	Up to eight audio slots, batch file download, status output	Results section	Beginner	Make listening, comparing, and saving simpler.
Result reuse	Send to Remix, send to Repaint, restore params to UI	Results section and event handlers	Intermediate	Preserve one-click iteration from a good result.
Result details	Audio codes, quality score, LRC generation, LRC save/download, generation metadata	Results details accordions	Advanced	Keep discoverable without overwhelming first-time users.
Dataset builder	Scan/load audio folder, preview samples, label/edit/save dataset metadata	Training tab dataset builder	Advanced	Preserve as a guided training preparation flow.
Dataset preprocessing	Tensor preprocessing and status updates	Training tab dataset builder	Advanced	Preserve clear status and failure recovery.
LoRA training	Dataset path, LoRA settings, run/stop training, logs, plots, export	Training tab LoRA	Advanced	Preserve complete Gradio training path.
LoKr training	Dataset path, LoKr settings, run/stop training, logs, export	Training tab LoKr	Expert	Preserve experimental/advanced positioning.
Help content	Inline help buttons, modal markdown, field tooltips	acestep/ui/gradio/help_content.py, i18n JSON	Beginner/Advanced	Expand into task-level help, examples, and recovery guidance.
i18n	English, Chinese, Japanese, Hebrew, Portuguese UI strings	acestep/ui/gradio/i18n	Beginner	Preserve language switching and avoid hard-coded UI text.
Service mode	Restricted UI defaults and hidden training tab	Gradio init params and interface composition	Admin	Preserve deployment-friendly mode.
API mode	Optional Gradio-hosted endpoints for health, models, release task, query result, sample creation, formatting	acestep/ui/gradio/api/api_routes.py	Integration	Preserve API behavior even if UI code changes.

Design Implications For The Next UI

• The first screen should prioritize one successful generation over exposing every parameter.
• Advanced controls should remain complete, but grouped by intent: model setup, song structure, generation quality, LM behavior, source audio editing, and expert code controls.
• Editing modes should be explained as user tasks rather than internal task names.
• Results should support an iteration loop: listen, compare, save, reuse settings, remix, repaint.
• Training should remain available, but separated from first-run generation.
• API services should remain framework-neutral so future UI experiments do not duplicate model loading, generation, dataset, or training logic.