SunoShoot

A guided prompt engine for Suno AI Custom Mode — turns a short wizard (or one free-text sentence) into a ready-to-paste Style, Lyrics, and Config prompt.

Local-first · Ministral 8B via MLX (optional) · deterministic template fallback

Quick start

git clone <this-repo> && cd sunoshoot
pip install -r requirements.txt
uvicorn app.main:app --port 8801

Open http://127.0.0.1:8801.

Optional local LLM refinement (Apple Silicon): pip install mlx-lm, then set SUNOSHOOT_MODEL (see .env.example). The app is fully functional without it — refinement only polishes an already-complete deterministic output.

How it works

flowchart LR
    UI[Browser UI\nwizard / Fast Track] --> API[FastAPI routes]
    API --> ENGINE[Template engine]
    ENGINE --> GUARD[Word Count Guard\n<= 120 words]
    ENGINE --> LYRICS[Tagged lyrics builder]
    GUARD --> LLM{MLX available?}
    LLM -->|yes| REFINE[Ministral 8B refine]
    LLM -->|no| OUT[Style / Lyrics / Config output]
    REFINE -->|valid| OUT
    REFINE -->|invalid or error| OUT
    LYRICS --> OUT

Loading

• 9-step guided elicitation or Fast Track: answer genre, voice, structure and vibe one step at a time, or paste a single sentence and let Fast Track resolve it to a genre preset.
• Music DNA: each genre carries its own core production tags, suggested BPM, default structure and drop architecture, and known pitfalls.
• Word Count Guard: the style prompt is assembled as a priority-ordered tag list and trimmed — lowest priority first — to stay at or under the 120-word hard limit Suno enforces.
• Tagged lyrics sections: every section ([intro], [verse], [chorus], [drop], [bridge], [outro]...) ships with a writing directive and seed lines in the target language, never spliced mid-line.
• DA Filter: surfaces genre-specific pitfalls (contradictory tags, missing language markers, mismatched instrumentation) before you paste into Suno.
• A/B/C variations: three deterministic variants per generation — faithful, more cinematic, and maximum detail — plus an Optimize mode that diagnoses and rewrites prompts you already have.

Stack

Python, FastAPI, vanilla JS/CSS (no framework, no CDN dependency), optional MLX (Apple Silicon) for local LLM refinement.

Examples

• examples/dark-trap.md — real engine output for a Dark Trap track.
• examples/french-house.md — real engine output for a French House track.
• examples/orchestral-epic.md — real engine output for a Cinematic Orchestral track.

Roadmap

• Preset sharing (export/import a full wizard configuration as a single link or file).
• Additional genre packs beyond the current ten Music DNA profiles.
• Suno API integration once a public API is available, to skip the copy-paste step entirely.
• Persona-free voice-tag presets (timbre and delivery only, no named-artist cloning).

License

MIT — see LICENSE.