Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+.cache/
+data/
+*.wav
+*.flac
+*.mp3
+.DS_Store

README.md

@@ -1,13 +1,49 @@
 ---
-title: ACE Step Inspire
-emoji: 🏢
-colorFrom: yellow
-colorTo: green
+title: ACE-Step Inspire
+emoji: 🎶
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 6.22.0
-python_version: '3.12'
+sdk_version: 5.49.1
+python_version: "3.11"
 app_file: app.py
 pinned: false
+license: mit
+short_description: Creative ACE-Step 1.5 text-to-song with genre-first UI
+suggested_hardware: zero-a10g
+models:
+  - ACE-Step/acestep-v15-sft
+  - ACE-Step/acestep-v15-base
+  - ACE-Step/acestep-v15-xl-turbo-diffusers
+tags:
+  - music
+  - text-to-audio
+  - ace-step
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ACE-Step Inspire
+
+A simplified, inspiration-first Hugging Face Space for **ACE-Step 1.5** text-to-song generation.
+
+## Why this Space
+
+Official demos expose many technical controls and can feel unreliable. This Space:
+
+- Guides you with **genre → style → mood → tempo → lyrics**
+- Keeps expert diffusion settings collapsed
+- Defaults to the **non-XL SFT** checkpoint, with **XL Turbo** available for faster ZeroGPU runs
+- Treats **lyric generation as the primary path** (editable afterward)
+
+## Models
+
+| UI label | Repo |
+|----------|------|
+| SFT (default) | `ACE-Step/acestep-v15-sft` |
+| Base | `ACE-Step/acestep-v15-base` |
+| XL Turbo | `ACE-Step/acestep-v15-xl-turbo-diffusers` |
+
+Built with [`diffusers.AceStepPipeline`](https://huggingface.co/docs/diffusers/api/pipelines/ace_step).
+
+## License
+
+MIT. ACE-Step models are MIT-licensed by ACE Studio / StepFun. Please disclose AI use and respect copyright when sharing outputs.

app.py

@@ -0,0 +1,426 @@
+"""ACE-Step Inspire — creative text-to-song Space for ACE-Step 1.5."""
+
+from __future__ import annotations
+
+import os
+import random
+import tempfile
+from typing import Optional
+
+# ZeroGPU: import spaces BEFORE torch
+try:
+    import spaces
+
+    HAS_SPACES = True
+except ImportError:
+    HAS_SPACES = False
+
+for _proxy in ("http_proxy", "https_proxy", "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY"):
+    os.environ.pop(_proxy, None)
+os.environ.setdefault("GRADIO_ANALYTICS_ENABLED", "False")
+os.environ.setdefault("HF_MODULES_CACHE", "/tmp/hf_modules")
+os.environ.setdefault("MPLCONFIGDIR", "/tmp/matplotlib")
+
+import gradio as gr
+import soundfile as sf
+import torch
+from diffusers import AceStepPipeline
+
+from lyrics_gen import build_caption, generate_lyrics
+from presets import (
+    DEFAULT_DURATION,
+    DEFAULT_GENRE,
+    DEFAULT_MODEL,
+    GENRES,
+    KEYS_ALL,
+    MODELS,
+    MOOD_EXTRA,
+    STRUCTURES,
+    TIME_SIGNATURES,
+    USE_CASES,
+    VOCAL_LANGUAGES,
+)
+
+# ── Pipeline cache (CPU-resident; moved to CUDA inside @spaces.GPU) ──────────
+_pipes: dict[str, AceStepPipeline] = {}
+_current_repo: Optional[str] = None
+
+
+def _load_pipe(repo_id: str) -> AceStepPipeline:
+    global _current_repo
+    if repo_id in _pipes:
+        return _pipes[repo_id]
+    # Keep only one heavy pipeline in memory on ZeroGPU
+    _pipes.clear()
+    pipe = AceStepPipeline.from_pretrained(repo_id, torch_dtype=torch.bfloat16)
+    if hasattr(pipe, "vae") and hasattr(pipe.vae, "enable_tiling"):
+        pipe.vae.enable_tiling()
+    _pipes[repo_id] = pipe
+    _current_repo = repo_id
+    return pipe
+
+
+def _model_cfg(model_name: str) -> dict:
+    return MODELS.get(model_name, MODELS[DEFAULT_MODEL])
+
+
+def apply_genre(genre: str):
+    """Fill creative defaults from genre (all still user-overridable)."""
+    g = GENRES[genre]
+    styles = g["styles"]
+    moods = sorted(set(g["moods"] + MOOD_EXTRA))
+    vocals = g["vocal"]
+    instruments = g["instruments"]
+    keys = g["keys"]
+    return (
+        gr.update(choices=styles, value=styles[0]),
+        gr.update(choices=moods, value=g["moods"][0]),
+        gr.update(choices=vocals, value=vocals[0]),
+        gr.update(choices=instruments, value=instruments[:3]),
+        gr.update(value=g["default_bpm"]),
+        gr.update(value=keys[0] if keys else "C major"),
+        gr.update(value=g["time_signature"]),
+    )
+
+
+def surprise_me(genre: str, theme: str):
+    """Randomize creative controls within the selected genre."""
+    g = GENRES.get(genre, GENRES[DEFAULT_GENRE])
+    style = random.choice(g["styles"])
+    mood = random.choice(g["moods"])
+    vocal = random.choice(g["vocal"])
+    n_inst = min(3, len(g["instruments"]))
+    instruments = random.sample(g["instruments"], k=n_inst)
+    bpm = random.randint(*g["bpm"])
+    key = random.choice(g["keys"])
+    structure = random.choice([s for s in STRUCTURES if s != "Instrumental (no lyrics)"])
+    use_case = random.choice(USE_CASES[1:])
+    lyrics = generate_lyrics(genre, mood, theme or mood, structure, instrumental=False)
+    caption = build_caption(
+        genre, style, mood, instruments, vocal, bpm, use_case, instrumental=False
+    )
+    return (
+        style,
+        mood,
+        vocal,
+        instruments,
+        bpm,
+        key,
+        g["time_signature"],
+        structure,
+        use_case,
+        lyrics,
+        caption,
+    )
+
+
+def on_generate_lyrics(genre, mood, theme, structure, instrumental, seed):
+    seed_i = int(seed) if seed is not None and int(seed) >= 0 else None
+    text = generate_lyrics(
+        genre=genre,
+        mood=mood or "emotional",
+        theme=theme or mood or genre,
+        structure_name=structure,
+        instrumental=bool(instrumental),
+        seed=seed_i,
+    )
+    return text
+
+
+def on_build_prompt(genre, style, mood, instruments, vocal, bpm, use_case, extra, instrumental):
+    inst_list = instruments if isinstance(instruments, list) else []
+    return build_caption(
+        genre=genre,
+        style=style,
+        mood=mood,
+        instruments=inst_list,
+        vocal=vocal,
+        bpm=int(bpm),
+        use_case=use_case,
+        extra=extra or "",
+        instrumental=bool(instrumental),
+    )
+
+
+def _generate_impl(
+    model_name,
+    prompt,
+    lyrics,
+    duration,
+    bpm,
+    keyscale,
+    timesignature,
+    language_label,
+    instrumental,
+    steps,
+    guidance,
+    shift,
+    seed,
+    random_seed,
+    genre=None,
+    style=None,
+    mood=None,
+    instruments=None,
+    vocal=None,
+    use_case=None,
+    extra_tags=None,
+):
+    # Auto-build prompt if the user skipped that step
+    if not prompt or not str(prompt).strip():
+        prompt = build_caption(
+            genre=genre or DEFAULT_GENRE,
+            style=style or "",
+            mood=mood or "",
+            instruments=instruments if isinstance(instruments, list) else [],
+            vocal=vocal or "",
+            bpm=int(bpm) if bpm else 120,
+            use_case=use_case or "(none)",
+            extra=extra_tags or "",
+            instrumental=bool(instrumental),
+        )
+    if not prompt or not str(prompt).strip():
+        raise gr.Error("Prompt/caption is empty. Click Build prompt or fill creative controls.")
+
+    cfg = _model_cfg(model_name)
+    repo_id = cfg["repo_id"]
+    pipe = _load_pipe(repo_id)
+    pipe.to("cuda")
+
+    duration = int(duration)
+    duration = max(10, min(duration, 600))
+
+    if instrumental:
+        lyrics_text = "[Instrumental]"
+    else:
+        lyrics_text = (lyrics or "").strip() or "[Instrumental]"
+
+    seed_val = -1 if seed is None else int(seed)
+    use_seed = random.randint(0, 2**31 - 1) if random_seed or seed_val < 0 else seed_val
+    generator = torch.Generator(device="cuda").manual_seed(use_seed)
+
+    steps = int(steps) if steps else cfg["steps"]
+    guidance = float(guidance) if guidance is not None else cfg["guidance"]
+    shift = float(shift) if shift is not None else cfg["shift"]
+    if cfg["turbo"]:
+        guidance = 1.0
+
+    lang = VOCAL_LANGUAGES.get(language_label, "en")
+
+    kwargs = dict(
+        prompt=str(prompt).strip(),
+        lyrics=lyrics_text,
+        audio_duration=float(duration),
+        vocal_language=lang,
+        num_inference_steps=steps,
+        guidance_scale=guidance,
+        shift=shift,
+        generator=generator,
+        bpm=int(bpm) if bpm else None,
+        keyscale=keyscale or None,
+        timesignature=str(timesignature) if timesignature else None,
+        task_type="text2music",
+    )
+
+    output = pipe(**kwargs)
+    audio = output.audios[0]
+    if isinstance(audio, torch.Tensor):
+        audio = audio.detach().float().cpu().numpy()
+    if audio.ndim == 2:
+        # (channels, samples) -> (samples, channels)
+        if audio.shape[0] <= 8 and audio.shape[0] < audio.shape[1]:
+            audio = audio.T
+
+    sr = getattr(pipe, "sample_rate", 48000)
+    tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+    sf.write(tmp.name, audio, samplerate=sr)
+
+    meta = (
+        f"Model: {repo_id}\n"
+        f"Seed: {use_seed} | Steps: {steps} | Guidance: {guidance} | Shift: {shift}\n"
+        f"Duration: {duration}s | BPM: {bpm} | Key: {keyscale} | Meter: {timesignature}/4\n"
+        f"Language: {lang}"
+    )
+    return tmp.name, meta
+
+
+if HAS_SPACES:
+    # ZeroGPU max duration is set high; actual budget depends on model
+    generate_music = spaces.GPU(duration=300)(_generate_impl)
+else:
+    generate_music = _generate_impl
+
+
+# ── UI ───────────────────────────────────────────────────────────────────────
+
+CUSTOM_CSS = """
+.gradio-container { max-width: 1100px !important; }
+footer { display: none !important; }
+"""
+
+INTRO = """
+# ACE-Step Inspire
+Creative **text-to-song** studio powered by [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5).
+
+Pick a **genre**, tune mood / style / tempo, **generate lyrics**, then render.
+Technical knobs stay tucked away for debugging — defaults are chosen to just work on ZeroGPU.
+"""
+
+with gr.Blocks(title="ACE-Step Inspire", theme=gr.themes.Soft(primary_hue="teal", secondary_hue="slate"), css=CUSTOM_CSS) as demo:
+    gr.Markdown(INTRO)
+
+    with gr.Row():
+        model = gr.Dropdown(
+            choices=list(MODELS.keys()),
+            value=DEFAULT_MODEL,
+            label="Model",
+            info="Default is non-XL SFT. Switch to XL Turbo if ZeroGPU queues feel slow.",
+        )
+        duration = gr.Number(
+            value=DEFAULT_DURATION,
+            precision=0,
+            minimum=10,
+            maximum=600,
+            label="Duration (seconds)",
+        )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            gr.Markdown("### Creative direction")
+            genre = gr.Dropdown(choices=list(GENRES.keys()), value=DEFAULT_GENRE, label="Genre")
+            style = gr.Dropdown(choices=GENRES[DEFAULT_GENRE]["styles"], value=GENRES[DEFAULT_GENRE]["styles"][0], label="Style")
+            mood = gr.Dropdown(
+                choices=sorted(set(GENRES[DEFAULT_GENRE]["moods"] + MOOD_EXTRA)),
+                value=GENRES[DEFAULT_GENRE]["moods"][0],
+                label="Mood",
+            )
+            use_case = gr.Dropdown(choices=USE_CASES, value="(none)", label="Use case / scene")
+            theme = gr.Textbox(
+                label="Song theme / idea",
+                placeholder="e.g. leaving a small town, neon heartbreak, victory after failure…",
+                lines=2,
+            )
+            vocal = gr.Dropdown(choices=GENRES[DEFAULT_GENRE]["vocal"], value=GENRES[DEFAULT_GENRE]["vocal"][0], label="Vocal character")
+            instruments = gr.CheckboxGroup(
+                choices=GENRES[DEFAULT_GENRE]["instruments"],
+                value=GENRES[DEFAULT_GENRE]["instruments"][:3],
+                label="Instruments / textures",
+            )
+            instrumental = gr.Checkbox(label="Instrumental (ignore lyrics)", value=False)
+            language = gr.Dropdown(choices=list(VOCAL_LANGUAGES.keys()), value="English", label="Lyric language")
+
+            with gr.Row():
+                bpm = gr.Slider(30, 220, value=GENRES[DEFAULT_GENRE]["default_bpm"], step=1, label="Tempo (BPM)")
+                keyscale = gr.Dropdown(choices=KEYS_ALL, value=GENRES[DEFAULT_GENRE]["keys"][0], label="Key")
+                timesignature = gr.Dropdown(choices=TIME_SIGNATURES, value="4", label="Time signature")
+
+            surprise_btn = gr.Button("Surprise me", variant="secondary")
+
+        with gr.Column(scale=1):
+            gr.Markdown("### Lyrics (generate first, then edit)")
+            structure = gr.Dropdown(
+                choices=list(STRUCTURES.keys()),
+                value=list(STRUCTURES.keys())[0],
+                label="Song structure",
+            )
+            lyric_seed = gr.Number(value=-1, precision=0, label="Lyric seed (-1 = random)")
+            with gr.Row():
+                gen_lyrics_btn = gr.Button("Generate lyrics", variant="primary")
+                regen_lyrics_btn = gr.Button("Regenerate")
+            lyrics = gr.Textbox(
+                label="Lyrics",
+                lines=16,
+                placeholder="Click Generate lyrics, or paste your own with [verse] / [chorus] tags…",
+            )
+
+            gr.Markdown("### Prompt / caption")
+            extra_tags = gr.Textbox(label="Extra tags (optional)", placeholder="warm tape saturation, wide stereo, radio mix…")
+            build_prompt_btn = gr.Button("Build prompt from controls")
+            prompt = gr.Textbox(label="Final prompt sent to the model", lines=3)
+
+    with gr.Accordion("Expert / debugging", open=False):
+        steps = gr.Slider(4, 60, value=_model_cfg(DEFAULT_MODEL)["steps"], step=1, label="Inference steps")
+        guidance = gr.Slider(1.0, 15.0, value=_model_cfg(DEFAULT_MODEL)["guidance"], step=0.5, label="Guidance scale (ignored by turbo)")
+        shift = gr.Slider(1.0, 5.0, value=3.0, step=0.5, label="Shift")
+        seed = gr.Number(value=-1, precision=0, label="Audio seed (-1 = random)")
+        random_seed = gr.Checkbox(value=True, label="Randomize audio seed each run")
+
+    generate_btn = gr.Button("Generate song", variant="primary", size="lg")
+    audio_out = gr.Audio(label="Generated song", type="filepath")
+    meta_out = gr.Textbox(label="Run info", lines=4)
+
+    # ── Wiring ───────────────────────────────────────────────────────────────
+    genre.change(
+        fn=apply_genre,
+        inputs=[genre],
+        outputs=[style, mood, vocal, instruments, bpm, keyscale, timesignature],
+    )
+
+    def _sync_expert(model_name):
+        cfg = _model_cfg(model_name)
+        return cfg["steps"], cfg["guidance"], cfg["shift"]
+
+    model.change(fn=_sync_expert, inputs=[model], outputs=[steps, guidance, shift])
+
+    gen_lyrics_btn.click(
+        fn=on_generate_lyrics,
+        inputs=[genre, mood, theme, structure, instrumental, lyric_seed],
+        outputs=[lyrics],
+    )
+    regen_lyrics_btn.click(
+        fn=on_generate_lyrics,
+        inputs=[genre, mood, theme, structure, instrumental, lyric_seed],
+        outputs=[lyrics],
+    )
+
+    build_prompt_btn.click(
+        fn=on_build_prompt,
+        inputs=[genre, style, mood, instruments, vocal, bpm, use_case, extra_tags, instrumental],
+        outputs=[prompt],
+    )
+
+    surprise_btn.click(
+        fn=surprise_me,
+        inputs=[genre, theme],
+        outputs=[style, mood, vocal, instruments, bpm, keyscale, timesignature, structure, use_case, lyrics, prompt],
+    )
+
+    generate_btn.click(
+        fn=generate_music,
+        inputs=[
+            model,
+            prompt,
+            lyrics,
+            duration,
+            bpm,
+            keyscale,
+            timesignature,
+            language,
+            instrumental,
+            steps,
+            guidance,
+            shift,
+            seed,
+            random_seed,
+            genre,
+            style,
+            mood,
+            instruments,
+            vocal,
+            use_case,
+            extra_tags,
+        ],
+        outputs=[audio_out, meta_out],
+    )
+
+    gr.Markdown(
+        """
+---
+**Tips:** Start with **Generate lyrics** → **Build prompt** → **Generate song**.  
+For long tracks on ZeroGPU, prefer **XL Turbo**. Non-XL SFT is the quality default.  
+Lyrics here use a creative composer tuned to genre/mood (fast & reliable). ACE-Step’s own 5Hz planner LM is part of the heavy full stack and is intentionally not loaded in this Space.
+"""
+    )
+
+
+if __name__ == "__main__":
+    demo.queue(max_size=10).launch(server_name="0.0.0.0", server_port=7860)

lyrics_gen.py

@@ -0,0 +1,271 @@
+"""Genre-aware lyric and caption builders."""
+
+from __future__ import annotations
+
+import random
+from typing import Optional
+
+from presets import GENRES, STRUCTURES
+
+# Theme fragments for combinatorial lyric writing
+_OPENINGS = [
+    "In the quiet of the {place}",
+    "I remember when we {action}",
+    "Every neon light says {hook}",
+    "They told me not to {action}",
+    "Under skies of {color}",
+    "Walking through the {place}",
+    "Your voice still echoes in the {place}",
+    "Midnight on the {place}",
+    "I built a fire out of {object}",
+    "Counting heartbeats in the {place}",
+]
+
+_PLACES = [
+    "city",
+    "rain",
+    "hallway",
+    "station",
+    "kitchen light",
+    "empty road",
+    "crowded room",
+    "morning fog",
+    "rooftop",
+    "backseat",
+    "ocean edge",
+    "glow of screens",
+]
+
+_ACTIONS = [
+    "left",
+    "stayed",
+    "danced",
+    "promised",
+    "ran",
+    "believed",
+    "broke the rules",
+    "held on",
+    "let go",
+    "called your name",
+]
+
+_COLORS = ["blue", "gold", "violet", "silver", "crimson", "amber", "indigo"]
+_OBJECTS = ["paper dreams", "old photos", "broken clocks", "borrowed time", "static nights"]
+
+_HOOKS = [
+    "don't look back",
+    "we are still alive",
+    "hold me closer",
+    "this is our night",
+    "I won't fade away",
+    "run with me",
+    "say my name",
+    "keep the fire burning",
+    "never let me go",
+    "feel the thunder",
+    "dance until dawn",
+    "heart on the line",
+]
+
+_CHORUS_TEMPLATES = [
+    "{hook}\n{hook}\nWe turn the silence into sound\n{hook}",
+    "Oh {hook}\nOh {hook}\nEvery heartbeat loud and proud\n{hook}",
+    "{hook}, {hook}\nRising higher than the crowd\n{hook}, {hook}",
+    "Sing it with me: {hook}\nLouder than the storm tonight\nSing it with me: {hook}",
+]
+
+_VERSE_TEMPLATES = [
+    "{line1}\n{line2}\n{line3}\n{line4}",
+]
+
+_BRIDGE_TEMPLATES = [
+    "If tomorrow never comes\nI'll still remember this\nAll the words we never said\nMeet me in the {place}",
+    "Break it down, rebuild it slow\nLet the feeling overflow\nIn the {place} we both know\nThis is where we let it go",
+    "No map, no script, just light\nWe rewrite the ending tonight\nFrom the {place} to the sky\nWe were never meant to hide",
+]
+
+_GENRE_FLAVOR = {
+    "Hip-Hop / Rap": {
+        "verse_extra": [
+            "Bars stacked like city bricks, I carve my name in time",
+            "Pocket full of lessons, every scar a silver line",
+            "Beat knocks twice, then I step into the rhyme",
+        ],
+        "hook_bias": ["rise up", "keep grinding", "real talk", "no fake love"],
+    },
+    "Metal": {
+        "verse_extra": [
+            "Iron skies and thunder veins, we roar against the night",
+            "Ash and steel, we stand unbroken in the fight",
+        ],
+        "hook_bias": ["rise from the ashes", "we will never die", "feel the fire"],
+    },
+    "Latin": {
+        "verse_extra": [
+            "Bailando bajo estrellas, corazón en flor",
+            "La noche nos llama con sabor y calor",
+        ],
+        "hook_bias": ["baila conmigo", "esta noche", "mi corazón"],
+    },
+    "K-Pop": {
+        "verse_extra": [
+            "Spotlight hits, we sparkle through the frame",
+            "Heartbeat sync, we rewrite our name",
+        ],
+        "hook_bias": ["shine with me", "don't stop now", "we glow tonight"],
+    },
+    "Reggae / Dancehall": {
+        "verse_extra": [
+            "Irons in the fire, still we keep the vibe",
+            "One love in the valley, feel the rhythm thrive",
+        ],
+        "hook_bias": ["easy now", "feel the vibe", "one love"],
+    },
+    "Country": {
+        "verse_extra": [
+            "Dust on the dashboard, radio low",
+            "Two-lane highway, nowhere left to go",
+        ],
+        "hook_bias": ["take me home", "small town lights", "hold on tight"],
+    },
+    "Blues": {
+        "verse_extra": [
+            "Guitar cries midnight, whiskey in my hand",
+            "Lord, I tried to leave, but the blues still stand",
+        ],
+        "hook_bias": ["have mercy", "gone too long", "blue as night"],
+    },
+}
+
+
+def _pick(seq, rng: random.Random):
+    return rng.choice(seq)
+
+
+def _line(rng: random.Random, theme: str = "") -> str:
+    opening = _pick(_OPENINGS, rng).format(
+        place=_pick(_PLACES, rng),
+        action=_pick(_ACTIONS, rng),
+        color=_pick(_COLORS, rng),
+        object=_pick(_OBJECTS, rng),
+        hook=_pick(_HOOKS, rng),
+    )
+    if theme.strip():
+        # Lightly weave theme words into a supporting line
+        words = [w for w in theme.replace(",", " ").split() if len(w) > 2]
+        if words:
+            w = _pick(words, rng)
+            return f"{opening}\nThinking about {w}, making it mine"
+    return opening
+
+
+def _hook(rng: random.Random, genre: str, theme: str) -> str:
+    flavor = _GENRE_FLAVOR.get(genre, {})
+    pool = list(_HOOKS) + list(flavor.get("hook_bias", []))
+    if theme.strip():
+        # Use a short theme phrase as hook sometimes
+        short = " ".join(theme.strip().split()[:4])
+        if len(short) > 3 and rng.random() < 0.45:
+            return short
+    return _pick(pool, rng)
+
+
+def _verse(rng: random.Random, genre: str, theme: str) -> str:
+    flavor = _GENRE_FLAVOR.get(genre, {})
+    pulse = _pick(["pulse", "weight", "glow", "storm", "quiet"], rng)
+    subject = theme.strip() or "this moment"
+    lines = [
+        _line(rng, theme).split("\n")[0],
+        f"I feel the {pulse} of {subject}",
+        _pick(
+            [
+                f"We {_pick(_ACTIONS, rng)} like the world forgot our names",
+                f"Shadows on the {_pick(_PLACES, rng)}, playing little games",
+                f"Promises in {_pick(_COLORS, rng)}, catching fire in frames",
+            ],
+            rng,
+        ),
+        _pick(flavor.get("verse_extra", ["And still we find a way to shine"]), rng),
+    ]
+    # Clean overly long theme echo
+    lines[1] = lines[1][:90]
+    return "\n".join(lines)
+
+
+def _chorus(rng: random.Random, hook: str) -> str:
+    return _pick(_CHORUS_TEMPLATES, rng).format(hook=hook)
+
+
+def _bridge(rng: random.Random) -> str:
+    return _pick(_BRIDGE_TEMPLATES, rng).format(place=_pick(_PLACES, rng))
+
+
+def generate_lyrics(
+    genre: str,
+    mood: str,
+    theme: str,
+    structure_name: str,
+    instrumental: bool = False,
+    seed: Optional[int] = None,
+) -> str:
+    """Generate structured lyrics. Primary creative path for the Space."""
+    if instrumental or structure_name == "Instrumental (no lyrics)":
+        return "[Instrumental]"
+
+    rng = random.Random(seed)
+    code = STRUCTURES.get(structure_name, "vcvcbc")
+    hook = _hook(rng, genre, theme)
+    parts: list[str] = []
+
+    mapping = {
+        "i": ("[intro]", f"(instrumental intro — {mood})"),
+        "v": ("[verse]", _verse(rng, genre, theme)),
+        "p": ("[pre-chorus]", f"Building up the feeling\n{mood.title()} hearts are stealing\nCloser to the meaning"),
+        "c": ("[chorus]", _chorus(rng, hook)),
+        "b": ("[bridge]", _bridge(rng)),
+        "o": ("[outro]", f"{hook}\n({mood} fade out)"),
+    }
+
+    # Avoid duplicate identical choruses looking empty — regenerate lightly
+    for ch in code:
+        if ch not in mapping:
+            continue
+        tag, body = mapping[ch]
+        if ch == "v":
+            body = _verse(rng, genre, theme)
+        if ch == "c":
+            body = _chorus(rng, hook)
+        parts.append(f"{tag}\n{body}")
+
+    return "\n\n".join(parts)
+
+
+def build_caption(
+    genre: str,
+    style: str,
+    mood: str,
+    instruments: list[str],
+    vocal: str,
+    bpm: int,
+    use_case: str,
+    extra: str = "",
+    instrumental: bool = False,
+) -> str:
+    """Assemble an ACE-Step style prompt/caption from UI choices."""
+    bits = [
+        f"{style} {genre.lower()} track",
+        f"{mood} mood",
+        f"{bpm} BPM",
+    ]
+    if instruments:
+        bits.append("featuring " + ", ".join(instruments[:4]))
+    if instrumental or vocal.lower() == "instrumental":
+        bits.append("instrumental, no vocals")
+    else:
+        bits.append(f"{vocal}")
+    if use_case and use_case != "(none)":
+        bits.append(f"perfect for {use_case}")
+    if extra.strip():
+        bits.append(extra.strip())
+    # ACE-Step likes comma-separated descriptive tags
+    return ", ".join(bits)

presets.py

@@ -0,0 +1,507 @@
+"""Creative presets for ACE-Step Inspire."""
+
+from __future__ import annotations
+
+GENRES: dict[str, dict] = {
+    "Pop": {
+        "styles": [
+            "mainstream pop",
+            "synth-pop",
+            "dance-pop",
+            "indie pop",
+            "electropop",
+            "power pop",
+            "bubblegum pop",
+            "art pop",
+        ],
+        "bpm": (100, 128),
+        "default_bpm": 118,
+        "keys": ["C major", "G major", "D major", "A major", "F major", "A minor", "E minor"],
+        "time_signature": "4",
+        "instruments": [
+            "bright synths",
+            "punchy drums",
+            "bass guitar",
+            "electric guitar",
+            "piano",
+            "vocal chops",
+        ],
+        "moods": ["uplifting", "romantic", "confident", "nostalgic", "playful", "bittersweet"],
+        "vocal": ["female lead", "male lead", "duet", "stacked harmonies"],
+    },
+    "Hip-Hop / Rap": {
+        "styles": [
+            "boom bap",
+            "trap",
+            "lo-fi hip-hop",
+            "conscious rap",
+            "cloud rap",
+            "drill",
+            "old-school hip-hop",
+            "melodic rap",
+        ],
+        "bpm": (70, 160),
+        "default_bpm": 92,
+        "keys": ["C minor", "A minor", "D minor", "F minor", "G minor", "Bb minor"],
+        "time_signature": "4",
+        "instruments": [
+            "808 bass",
+            "crisp hi-hats",
+            "sampled piano",
+            "vinyl crackle",
+            "trap snares",
+            "atmospheric pads",
+        ],
+        "moods": ["confident", "introspective", "aggressive", "chill", "storytelling", "dark"],
+        "vocal": ["male rapper", "female rapper", "sung chorus", "spoken word"],
+    },
+    "Rock": {
+        "styles": [
+            "classic rock",
+            "indie rock",
+            "alternative rock",
+            "punk rock",
+            "hard rock",
+            "soft rock",
+            "garage rock",
+            "post-rock",
+        ],
+        "bpm": (90, 160),
+        "default_bpm": 128,
+        "keys": ["E minor", "A minor", "D major", "G major", "C major", "B minor"],
+        "time_signature": "4",
+        "instruments": [
+            "distorted electric guitars",
+            "live drums",
+            "bass guitar",
+            "organ",
+            "clean guitar arpeggios",
+        ],
+        "moods": ["rebellious", "anthemic", "melancholic", "energetic", "raw", "hopeful"],
+        "vocal": ["male grit vocals", "female rock vocals", "gang vocals", "shouted chorus"],
+    },
+    "Electronic / Dance": {
+        "styles": [
+            "house",
+            "techno",
+            "trance",
+            "drum and bass",
+            "synthwave",
+            "future bass",
+            "deep house",
+            "ambient techno",
+        ],
+        "bpm": (110, 174),
+        "default_bpm": 124,
+        "keys": ["A minor", "F minor", "C minor", "D minor", "G minor", "E minor"],
+        "time_signature": "4",
+        "instruments": [
+            "four-on-the-floor kick",
+            "analog synths",
+            "arpeggiators",
+            "sidechain bass",
+            "filtered pads",
+            "risers",
+        ],
+        "moods": ["euphoric", "hypnotic", "dark", "dreamy", "peak-time", "late-night"],
+        "vocal": ["female vocal hooks", "male vocal chops", "instrumental", "spoken phrases"],
+    },
+    "R&B / Soul": {
+        "styles": [
+            "contemporary R&B",
+            "neo-soul",
+            "classic soul",
+            "quiet storm",
+            "funk-soul",
+            "alt-R&B",
+        ],
+        "bpm": (65, 110),
+        "default_bpm": 84,
+        "keys": ["Db major", "Ab major", "F minor", "Bb minor", "C minor", "Eb major"],
+        "time_signature": "4",
+        "instruments": [
+            "warm electric piano",
+            "smooth bass",
+            "brushed drums",
+            "horn section",
+            "gospel organ",
+            "guitar licks",
+        ],
+        "moods": ["sensual", "vulnerable", "smooth", "late-night", "romantic", "empowered"],
+        "vocal": ["silky female vocals", "silky male vocals", "falsetto lead", "harmony stacks"],
+    },
+    "Jazz": {
+        "styles": [
+            "jazz trio",
+            "smooth jazz",
+            "bebop",
+            "nu-jazz",
+            "jazz-funk",
+            "vocal jazz",
+            "cool jazz",
+        ],
+        "bpm": (70, 180),
+        "default_bpm": 112,
+        "keys": ["Bb major", "F major", "Eb major", "C minor", "D minor", "A minor"],
+        "time_signature": "4",
+        "instruments": [
+            "upright bass",
+            "piano",
+            "brushed drums",
+            "saxophone",
+            "trumpet",
+            "rhodes",
+        ],
+        "moods": ["sophisticated", "smoky", "playful", "intimate", "swinging", "nocturnal"],
+        "vocal": ["crooner", "scat vocals", "instrumental", "lounge singer"],
+    },
+    "Folk / Acoustic": {
+        "styles": [
+            "contemporary folk",
+            "indie folk",
+            "singer-songwriter",
+            "americana",
+            "campfire folk",
+            "celtic folk",
+        ],
+        "bpm": (70, 120),
+        "default_bpm": 96,
+        "keys": ["G major", "D major", "C major", "A major", "E minor", "A minor"],
+        "time_signature": "4",
+        "instruments": [
+            "acoustic guitar",
+            "fingerpicking",
+            "harmonica",
+            "light percussion",
+            "mandolin",
+            "soft piano",
+        ],
+        "moods": ["wistful", "warm", "storytelling", "pastoral", "intimate", "hopeful"],
+        "vocal": ["gentle male vocals", "gentle female vocals", "harmony duet", "whispered verses"],
+    },
+    "Metal": {
+        "styles": [
+            "heavy metal",
+            "metalcore",
+            "power metal",
+            "doom metal",
+            "progressive metal",
+            "thrash",
+        ],
+        "bpm": (90, 200),
+        "default_bpm": 140,
+        "keys": ["E minor", "D minor", "B minor", "F# minor", "A minor", "C minor"],
+        "time_signature": "4",
+        "instruments": [
+            "distorted guitars",
+            "double bass drums",
+            "thunderous bass",
+            "shred solos",
+            "orchestral hits",
+        ],
+        "moods": ["aggressive", "epic", "dark", "triumphant", "brooding", "chaotic"],
+        "vocal": ["harsh vocals", "clean epic vocals", "growls + cleans", "choir backing"],
+    },
+    "Latin": {
+        "styles": [
+            "reggaeton",
+            "latin pop",
+            "salsa",
+            "bachata",
+            "cumbia",
+            "latin trap",
+            "bossa nova",
+        ],
+        "bpm": (85, 130),
+        "default_bpm": 96,
+        "keys": ["A minor", "D minor", "G major", "C major", "E minor", "F major"],
+        "time_signature": "4",
+        "instruments": [
+            "syncopated percussion",
+            "nylon guitar",
+            "tropical synths",
+            "congas",
+            "bass groove",
+            "brass stabs",
+        ],
+        "moods": ["romantic", "festive", "sensual", "sunny", "dancefloor", "nostalgic"],
+        "vocal": ["Spanish male vocals", "Spanish female vocals", "bilingual vocals", "reggaeton flow"],
+    },
+    "Country": {
+        "styles": [
+            "modern country",
+            "country pop",
+            "outlaw country",
+            "bluegrass",
+            "country ballad",
+            "americana",
+        ],
+        "bpm": (70, 140),
+        "default_bpm": 108,
+        "keys": ["G major", "D major", "A major", "C major", "E major", "A minor"],
+        "time_signature": "4",
+        "instruments": [
+            "acoustic guitar",
+            "pedal steel",
+            "fiddle",
+            "banjo",
+            "twangy electric guitar",
+            "kick-snare groove",
+        ],
+        "moods": ["heartfelt", "road-trip", "heartbroken", "celebratory", "homey", "bittersweet"],
+        "vocal": ["male country vocals", "female country vocals", "harmony chorus", "storyteller"],
+    },
+    "Lo-Fi / Chill": {
+        "styles": [
+            "lo-fi hip-hop",
+            "chillhop",
+            "study beats",
+            "downtempo",
+            "chillwave",
+            "bedroom pop",
+        ],
+        "bpm": (70, 95),
+        "default_bpm": 82,
+        "keys": ["C major", "A minor", "F major", "D minor", "G major", "E minor"],
+        "time_signature": "4",
+        "instruments": [
+            "dusty piano samples",
+            "soft drums",
+            "vinyl crackle",
+            "mellow bass",
+            "tape hiss",
+            "jazzy chords",
+        ],
+        "moods": ["relaxed", "cozy", "melancholy", "dreamy", "focus", "rainy-day"],
+        "vocal": ["soft mumbled vocals", "instrumental", "distant vocal sample", "whispered hooks"],
+    },
+    "Cinematic / Soundtrack": {
+        "styles": [
+            "epic orchestral",
+            "hybrid trailer",
+            "intimate score",
+            "adventure theme",
+            "dark ambient score",
+            "heroic fanfare",
+        ],
+        "bpm": (60, 140),
+        "default_bpm": 100,
+        "keys": ["D minor", "C minor", "Bb major", "F major", "A minor", "E minor"],
+        "time_signature": "4",
+        "instruments": [
+            "string orchestra",
+            "brass section",
+            "timpani",
+            "choir",
+            "piano motif",
+            "hybrid percussion",
+        ],
+        "moods": ["epic", "tender", "suspenseful", "triumphant", "mysterious", "emotional"],
+        "vocal": ["instrumental", "wordless choir", "operatic vocals", "narrative spoken word"],
+    },
+    "K-Pop": {
+        "styles": [
+            "bright K-pop",
+            "dark K-pop",
+            "EDM K-pop",
+            "ballad K-pop",
+            "hip-hop K-pop",
+            "city-pop flavored K-pop",
+        ],
+        "bpm": (95, 140),
+        "default_bpm": 122,
+        "keys": ["C major", "G major", "A minor", "F major", "D major", "E minor"],
+        "time_signature": "4",
+        "instruments": [
+            "polished synths",
+            "tight drums",
+            "bass drops",
+            "vocal stacks",
+            "brass hits",
+            "guitar hooks",
+        ],
+        "moods": ["catchy", "confident", "emotional", "playful", "dramatic", "glossy"],
+        "vocal": ["group vocals", "female idol lead", "male idol lead", "rap bridge"],
+    },
+    "Reggae / Dancehall": {
+        "styles": [
+            "roots reggae",
+            "dancehall",
+            "dub",
+            "ska",
+            "lovers rock",
+            "modern reggae fusion",
+        ],
+        "bpm": (70, 110),
+        "default_bpm": 78,
+        "keys": ["A minor", "G major", "C major", "D major", "E minor", "F major"],
+        "time_signature": "4",
+        "instruments": [
+            "offbeat guitar skank",
+            "deep bass",
+            "rimshot drums",
+            "organ bubble",
+            "horn section",
+            "echo delays",
+        ],
+        "moods": ["sunny", "relaxed", "spiritual", "groovy", "romantic", "protest"],
+        "vocal": ["reggae toasting", "smooth singers", "dancehall toast", "harmony chorus"],
+    },
+    "Blues": {
+        "styles": [
+            "electric blues",
+            "delta blues",
+            "blues rock",
+            "soul blues",
+            "chicago blues",
+        ],
+        "bpm": (60, 120),
+        "default_bpm": 88,
+        "keys": ["E major", "A major", "G major", "C major", "A minor", "E minor"],
+        "time_signature": "4",
+        "instruments": [
+            "blues guitar",
+            "harmonica",
+            "upright piano",
+            "shuffle drums",
+            "walking bass",
+        ],
+        "moods": ["soulful", "heartbroken", "gritty", "late-night", "resilient"],
+        "vocal": ["raspy male vocals", "powerful female blues", "call and response", "instrumental"],
+    },
+    "World / Fusion": {
+        "styles": [
+            "afrobeats",
+            "afro-fusion",
+            "middle-eastern fusion",
+            "indian classical fusion",
+            "balkan beat",
+            "global pop",
+        ],
+        "bpm": (90, 130),
+        "default_bpm": 110,
+        "keys": ["D minor", "A minor", "G minor", "C major", "F major", "E minor"],
+        "time_signature": "4",
+        "instruments": [
+            "hand percussion",
+            "world flutes",
+            "plucked strings",
+            "modern drums",
+            "synth bass",
+            "choir textures",
+        ],
+        "moods": ["celebratory", "spiritual", "adventurous", "warm", "hypnotic", "joyful"],
+        "vocal": ["multilingual vocals", "chant-like vocals", "smooth lead", "call and response"],
+    },
+}
+
+MOOD_EXTRA: list[str] = [
+    "uplifting",
+    "melancholic",
+    "euphoric",
+    "intimate",
+    "dark",
+    "playful",
+    "cinematic",
+    "nostalgic",
+    "aggressive",
+    "dreamy",
+    "romantic",
+    "mysterious",
+]
+
+USE_CASES: list[str] = [
+    "(none)",
+    "workout / gym",
+    "study / focus",
+    "road trip",
+    "late-night drive",
+    "party / club",
+    "wedding first dance",
+    "game trailer",
+    "YouTube intro",
+    "meditation / calm",
+    "rainy afternoon",
+    "sunrise / morning",
+]
+
+STRUCTURES: dict[str, str] = {
+    "Verse–Chorus–Verse–Chorus–Bridge–Chorus": "vcvcbc",
+    "Verse–Chorus–Verse–Chorus": "vcvc",
+    "Intro–Verse–Chorus–Verse–Chorus–Outro": "ivcvco",
+    "Verse–Pre–Chorus–Chorus (x2) + Bridge": "vppcpb",
+    "Instrumental (no lyrics)": "instrumental",
+}
+
+KEYS_ALL: list[str] = [
+    "C major",
+    "C minor",
+    "C# major",
+    "C# minor",
+    "D major",
+    "D minor",
+    "Eb major",
+    "Eb minor",
+    "E major",
+    "E minor",
+    "F major",
+    "F minor",
+    "F# major",
+    "F# minor",
+    "G major",
+    "G minor",
+    "Ab major",
+    "Ab minor",
+    "A major",
+    "A minor",
+    "Bb major",
+    "Bb minor",
+    "B major",
+    "B minor",
+]
+
+TIME_SIGNATURES: list[str] = ["2", "3", "4", "6"]
+
+VOCAL_LANGUAGES: dict[str, str] = {
+    "English": "en",
+    "German": "de",
+    "Spanish": "es",
+    "French": "fr",
+    "Japanese": "ja",
+    "Korean": "ko",
+    "Chinese": "zh",
+    "Portuguese": "pt",
+    "Italian": "it",
+    "Russian": "ru",
+}
+
+MODELS: dict[str, dict] = {
+    "SFT (quality, non-XL) — default": {
+        "repo_id": "ACE-Step/acestep-v15-sft",
+        "steps": 28,
+        "guidance": 7.0,
+        "shift": 3.0,
+        "turbo": False,
+        "gpu_seconds": 300,
+    },
+    "Base (more diversity, non-XL)": {
+        "repo_id": "ACE-Step/acestep-v15-base",
+        "steps": 32,
+        "guidance": 7.0,
+        "shift": 3.0,
+        "turbo": False,
+        "gpu_seconds": 320,
+    },
+    "XL Turbo (fast, ZeroGPU-friendly)": {
+        "repo_id": "ACE-Step/acestep-v15-xl-turbo-diffusers",
+        "steps": 8,
+        "guidance": 1.0,
+        "shift": 3.0,
+        "turbo": True,
+        "gpu_seconds": 180,
+    },
+}
+
+DEFAULT_MODEL = "SFT (quality, non-XL) — default"
+DEFAULT_GENRE = "Pop"
+DEFAULT_DURATION = 180

requirements.txt

@@ -0,0 +1,16 @@
+# ACE-Step Inspire — Hugging Face Space deps
+torch
+torchaudio
+torchvision
+diffusers>=0.37.0
+transformers>=4.51.0
+accelerate>=1.12.0
+safetensors
+sentencepiece
+protobuf
+gradio>=5.0.0
+spaces
+soundfile
+numpy
+scipy
+huggingface_hub>=0.20.0