Song Master

A powerful (yet easy to use) tool for generating song lyrics using AI models, specifically designed for creating Suno AI-compatible songs with custom styles, metadata, and structured formatting.

NEW: Now includes a modern web interface with real-time generation progress!

Overview

Song Master leverages AI models from multiple providers (Anthropic Claude, OpenAI GPT, Google Gemini, OpenRouter, or local models) to generate complete song lyrics with proper formatting, style tags, and metadata for Suno AI. It includes pre-flight checks, song drafting, and review processes to ensure high-quality output.

Features:

• 🌐 Web Interface: Modern React SPA with real-time progress tracking
• 🚀 FastAPI Backend: RESTful API with WebSocket support
• 🎸 HookHouse Integration: Professional songwriting workflow with Storysmith Muse + Sanctified Funksmith
• 🎵 Song Library: Browse, search, and manage generated songs
• ⚙️ Provider Configuration: Switch between AI providers without editing files
• 📊 Real-time Progress: Watch your song being created step-by-step
• 💻 CLI Support: Original command-line interface still available

Quick Start

For the web interface (recommended): See QUICKSTART.md for detailed setup instructions.

TL;DR:

# Install dependencies
pip install -r requirements.txt
cd frontend && npm install && cd ..

# Configure .env with your API key
cp .env.example .env

# Start backend and frontend
uvicorn backend.main:app --reload &
cd frontend && npm run dev

Then open http://localhost:5173 in your browser!

Table of Contents

• Quick Start
• Features
• HookHouse Workflow
• Installation
• Web Interface
• Usage (CLI)
  • Basic Usage
  • With Local Model
  • With Prompt File
  • With Custom Song Name
  • With Persona
  • Regenerate Cover Art
  • Command Line Options
• Examples
  • Example Input
  • Local Model Output
  • OpenRouter Model Output
  • Cover Art Output
  • Key Differences Between Models
• Configuration
  • Environment Variables
  • Custom Styles
• Technical Deep Dive: Agentic Songwriting Flow
• Project Structure
• Contributing
• License
• Support

Features

• Multi-Provider AI Support: Works with Anthropic (Claude), OpenAI (GPT), Google (Gemini), OpenRouter, and local AI models
• Flexible Configuration: Easy provider switching via environment variables
• Structured Output: Generates Suno AI-compatible format with styles, metadata, and lyrics
• Pre-flight Checks: Validates prompts and suggests improvements before generation
• Custom Styles: Supports custom style definitions and tagging
• Metadata Generation: Automatically generates emotional arc, target audience, and commercial potential data
• Review Process: Built-in song review and refinement capabilities
• Album Art Generation: Supports DALL-E, Google Imagen, and OpenRouter for cover art

HookHouse Workflow

HookHouse v2.6.1 is a professional songwriting system that generates Suno-compliant lyrics with production blueprints, arrangement cues, and physiological resonance. It combines Storysmith Muse (narrative development) with Sanctified Funksmith (groove refinement) to create radio-ready songs.

What Makes HookHouse Different?

Unlike the standard workflow, HookHouse uses a specialized 8-step process:

1. 🎭 Narrative Development - Storysmith Muse crafts 3 story concepts with emotional arcs
2. ✍️ HookHouse Draft - Generates Suno-compliant lyrics with arrangement cues
3. 🔍 HookHouse Review - Quality check against 10 HookHouse standards (must score ≥8.5/10)
4. 🎸 Funksmith Refinement - Adds breath points, physiological resonance, and groove
5. ✅ Preflight Checks - Final validation before metadata generation
6. 📋 HookHouse Metadata - Generates 4 metadata blocks (Style ≤1000 chars, Excluded Styles, Title/Artist, Summary ≤500 chars)
7. 🎨 Album Art - Generates cover artwork
8. 💾 Saving - Finalizes and saves complete song

HookHouse Output Format

HookHouse songs include:

• Block 1 (Lyrics): Complete song with [arrangement_cues | ...] at top, proper section headers [Verse], [Chorus], etc.
• Block 2 (Style): Flowing prose production blueprint (≤1000 chars) with BPM, key, instrument arrangement
• Block 3 (Excluded Styles): 5-12 comma-separated genres to avoid
• Block 4 (Title/Artist): Song title from lyrics + invented artist name fitting the genre
• Block 5 (Summary): Emotional/physiological arc summary (≤500 chars) with concrete imagery
• Funksmith Changelog: Detailed explanation of every refinement made

Using HookHouse in the Web Interface

1. Navigate to the New Song page
2. Enable the "Use HookHouse Workflow" toggle
3. Fill in the required HookHouse parameters:
   • Song Description: What kind of song you want
   • Blend: 2-3 musical styles (e.g., "Southern Rock, Gospel")
   • Mood: "dark" or "clean"
4. Optional parameters: BPM, Key, Time Signature, POV, Setting, Themes
5. Click Generate Song and watch the 8-step HookHouse workflow in real-time

Manual HookHouse Workflow (Claude Desktop)

For detailed instructions on running the HookHouse workflow manually in Claude Desktop using the prompt files, see:

• HOOKHOUSE_CLAUDE_DESKTOP_INSTRUCTIONS.md - Complete 7-step manual workflow guide

HookHouse Philosophy

• Spoken-first: Would this sound natural muttered in a bar?
• Concrete over abstract: Show with objects/actions, don't tell emotions
• Groove-aware: Does the rhythm suggest physical movement?
• Physiologically resonant: Does it mirror breath, heartbeat, tension/release?
• Suno-compliant: Proper bracket formatting for AI music generation
• Character limits enforced: Auto-trims Block 2 (Style) to ≤1000 chars, Block 5 (Summary) to ≤500 chars

Installation

1. Clone the repository:

git clone https://github.com/your-username/song-master.git
cd song-master

2. Install dependencies:

pip install -r requirements.txt

3. Set up environment variables:

cp .env.example .env
# Edit .env with your API keys and configuration

4. Configure your preferred AI provider:

For Anthropic (Claude):

• Get your API key from console.anthropic.com
• Set LLM_PROVIDER=anthropic and ANTHROPIC_API_KEY in .env

For OpenAI (GPT):

• Get your API key from platform.openai.com
• Set LLM_PROVIDER=openai and OPENAI_API_KEY in .env

For Google (Gemini):

• Get your API key from aistudio.google.com
• Set LLM_PROVIDER=google and GOOGLE_API_KEY in .env

For OpenRouter:

• Get your API key from openrouter.ai
• Set OPENROUTER_API_KEY in .env (no LLM_PROVIDER needed)

For Local Models:

• Use LM Studio or similar
• Run with --local flag

Web Interface

Starting the Web Interface

1. Start the backend:

   uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
   

2. Start the frontend (in a separate terminal):

   cd frontend
   npm run dev
   

3. Open your browser to http://localhost:5173

Web Interface Features

• Home Page: Generate new songs with a user-friendly form
  • HookHouse Toggle: Switch between standard and HookHouse professional workflows
  • Dynamic Form: Shows HookHouse-specific fields (Blend, Mood, BPM, etc.) when enabled
• Live Progress: Real-time WebSocket updates showing generation progress
  • Workflow-Specific Steps: Displays different progress steps for HookHouse vs standard workflow
• Library Page: Browse all generated songs with search functionality
• Song Detail Page: View full lyrics, metadata, and album art
• Settings Page: Switch AI providers and models without editing config files

API Documentation

Visit http://localhost:8000/docs for interactive API documentation.

Usage (CLI)

The original command-line interface is still fully supported:

Basic Usage

python song_master.py "Your song prompt here"

With Local Model

python song_master.py "Your song prompt here" --local

With Prompt File

python song_master.py --prompt-file path/to/prompt.txt

With Custom Song Name

python song_master.py "Your song prompt here" --name "My Song Title"

With Persona

python song_master.py "Your song prompt here" --persona "antidote"

Regenerate Cover Art

python song_master.py --regen-cover path/to/song.md

Command Line Options

• prompt: The song description or request (optional if using --prompt-file)
• --prompt-file: Path to a .txt file containing the song description
• --local: Use local LM Studio LLM and disable image generation
• --name: Optional song name/title
• --persona: Specify persona by name or path to persona .md file
• --regen-cover: Path to existing song file to regenerate album art

Examples

Example Input

The following input was used to generate the example outputs:

Generate some lyrics for a song that's all about testing ideas. Make it in the style of an 80s hair band and give it a thumping beat.

Local Model Output

The local model generates a more narrative-focused song with detailed storytelling:

Audio Sample:

## Testing Ideas
### A powerful 80s hair metal anthem about confronting inner doubts and boldly testing personal truths, driven by explosive guitar riffs, pounding drums, and a soaring, anthemic chorus. The song blends raw emotional intensity with glam rock swagger and stadium-ready energy.

## Suno Styles
80s hair metal, glam rock, arena rock, explosive guitar riffs, pounding drums, anthemic, party anthem, high-energy, melodic hooks, gang vocals, power ballad dynamics, rock and roll lifestyle, catchy chorus, guitar solo, festive, passionate, raw energy, stadium rock, glam metal swagger, Spatial Audio, Dolby Atmos mix, high-fidelity

## Suno Exclude-styles
melodic hooks, catchy chorus

## Additional Metadata
- **Emotional Arc**: happy
- **Target Audience**: Fans of classic 80s rock, arena rock enthusiasts, and listeners who enjoy high-energy, emotionally charged performances with a nostalgic edge.
- **Commercial Potential**: High — ideal for rock radio, sports events, and nostalgic playlists, with strong potential as a viral anthem for self-empowerment and personal breakthrough.
- **Technical Notes**: BPM: 120, Key: C, Instruments: guitar,bass,drums
- **User Prompt**: Generate some lyrics for a song that's all about testing ideas. Make it in the style of an 80s hair band and give it a thumping beat.

### Song Lyrics:
## Testing Ideas

[Verse 1]  
Cracked coffee cup on the kitchen sink,  
Steam still rising—water's been cold for hours.  
A letter folded twice in my coat pocket—  
The name I wrote, then erased, then rewrote.  
Saw it in the subway light,  
A face I still see in every mirror.  
No map, no proof—just the weight of a word  
I've carried since the night you left.

[Pre-Chorus]  
I don't need a name,  
I don't need a stage—  
The silence broke, and my voice found its way.  
Got the wound, got the truth,  
Gonna say it now—no more running.

[Chorus]  
Feel the rush, feel the rise—  
No fear, no lie—just the truth that won't stay quiet.  
One breath, and the air went still—  
The world held its breath, and I heard my own name.  
Yeah, I'm testin' ideas,  
Gonna break the mold, gonna make it real—  
One word, and the silence breaks.

[Verse 2]  
Wired for waiting, built for the pause,  
Got a line I've written, and I'm gonna say it.  
From the train's cold hum to the stair's worn wood,  
From the silence to the breath I've been afraid to say.  
I don't care if it's right or wrong—  
If it breaks, it's already strong.  
Got a rhythm in my throat,  
A truth I've been afraid to speak—  
And I've been told I'm too soft to be heard.

[Pre-Chorus]  
I don't need a plan,  
I don't need a plan—  
The silence broke, and my voice found its way.  
Got the fire, got the drive,  
Gonna light it up, gonna give it life.

[Chorus]  
Feel the rush, feel the rise—  
No fear, no lie—just the truth that won't stay quiet.  
One breath, and the air went still—  
The world held its breath, and I heard my own name.  
Yeah, I'm testin' ideas,  
Gonna break the mold, gonna make it real—  
One word, and the silence breaks.

[Bridge]  
No second guess, no time to wait—  
The world's a cup, and I'm the hand that holds it.  
I don't need a name, I don't need a crown—  
Just the word I've been afraid to say.

[Guitar Solo — bendy, bluesy, soaring over pounding drums]  
[Big Finish]  
[Explosive Riff]  
[Choir]  
[Male Vocal]  
[Chorus — Gang Vocals, Anthemic, Full Band]  
Feel the rush, feel the rise—  
No fear, no lie—just the truth that won't stay quiet.  
One breath, and the air went still—  
The world held its breath, and I heard my own name.  
Yeah, I'm testin' ideas,  
Gonna break the mold, gonna make it real—  
One word, and the silence breaks.

[Outro]  
[Fade Out and End]  
[End]  
[Big Finish]  
[Powerful Outro]  
[Fading, layered, triumphant]

OpenRouter Model Output

The OpenRouter model generates a more energetic, performance-focused song with explicit style tags:

Audio Sample:

## Testing Ideas
### High‑energy 80s hair‑metal anthem about bold creativity and pushing ideas into the spotlight with swagger and arena‑rock power.

## Suno Styles
80s hair metal, glam rock, arena rock, anthemic, high-energy, glam metal, party anthem, explosive guitar riffs, pounding drums, melodic hooks, gang vocals, power ballad dynamics, rock and roll lifestyle, catchy chorus, guitar solo, festive, passionate, raw energy, stadium rock, glam metal swagger, Spatial Audio, Dolby Atmos mix, high-fidelity

## Suno Exclude-styles
None

## Additional Metadata
- **Emotional Arc**: happy
- **Target Audience**: Fans of 80s rock, glam metal, and energetic stadium‑style anthems.
- **Commercial Potential**: Strong potential for nostalgia‑driven rock playlists and high‑energy promotional use.
- **Technical Notes**: BPM: 120, Key: C, Instruments: guitar,bass,drums
- **User Prompt**: Generate some lyrics for a song that's all about testing ideas. Make it in the style of an 80s hair band and give it a thumping beat.

### Song Lyrics:
## Testing Ideas

[Intro] [style: 80s hair metal, glam rock, arena rock, party anthem, high-energy]  
Lights rise, crowds surge, hearts rumble through the night  
We cut the neon haze, break open the sky's white  

[Verse 1] [style: 80s hair metal]  
Got a wild plan ridin' on the restless air  
Clear visions sparkin' as the brave ones dare  
Chasin' echoes down a half‑lit road  
Every bold impulse primed to overload  

[Pre-chorus] [style: glam rock]  
Turn it up, turn it up, feel the pull draw near  
Unchained heartbeats roarin' loud and clear  

[Chorus] [style: arena rock, anthemic]  
We're breakin' the silence, makin' truth reveal  
Pushin' the edge till the moment feels real  
Cut through the doubt, shake off the old fear  
Lift your voice high — we're breakin' the silence  

[Verse 2] [style: hair metal swagger]  
Got a live spark rollin' through the riff  
A shockwave risin' with a skyline lift  
Every wrong turn feeds fire to our mark  
We carve our path with voices cuttin' the dark  

[Pre-chorus] [style: glam metal]  
Turn it up, turn it up, let the weight fall free  
Every strike we throw's a raw victory  

[Chorus] [style: arena rock, anthemic]  
We're breakin' the silence, makin' truth reveal  
Pushin' the edge till the moment feels real  
Cut through the doubt, shake off the old fear  
Lift your voice high — we're breakin' the silence  

[Guitar Solo — wild, bend-heavy, high-energy]

[Bridge] [style: power ballad dynamics]  
When the world says "stop," we just shout back "go!"  
Every spark hits harder, drivin' through the low  
Hold tight to the madness, feel the quake come down  
We light the whole sky up every time we stand our ground  

[Chorus] [style: arena rock + gang vocals]  
We're breakin' the silence, makin' truth reveal  
Pushin' the edge till the moment feels real  
Cut through the doubt, shake off the old fear  
Lift your voice high — we're breakin' the silence  

[Big Finish]  
Breakin' the silence — keep shoutin' through the years!

Key Differences Between Models

Aspect	Local Model (Qwen3 30B A3B 2507)	OpenRouter Model (GPT-5.1 CHAT)
Style	More narrative and emotional	More energetic and performance-focused
Structure	Traditional verse-chorus structure	Explicit style tags per section
Content	Storytelling with personal elements	Direct and energetic messaging
Formatting	Standard formatting	Detailed style annotations
Exclude Styles	Specific exclusions (melodic hooks, catchy chorus)	No exclusions

HookHouse Workflow Output

The HookHouse workflow generates professional, Suno-compliant songs with complete metadata blocks, arrangement cues, and Funksmith refinements:

Example Input:

A song about finding redemption on dusty back roads, leaving behind old mistakes
and finding peace in simple faith

--blend "Southern Rock" "Gospel" --mood clean --bpm 95 --key G --pov first-person

Output:

## On These Dusty Back Roads
### A slow-burning Southern gospel journey from desperation to grace, moving through dusty back roads toward spiritual homecoming. Opens with gravel-road imagery and restrained baritone, building through a church-light revelation into full-throated affirmation of belonging. Physiologically mirrors held tension in verses, exhale and release in chorus, vulnerability whisper in bridge. Ends with the lingering image of coming home, never walking alone—a redemption arc grounded in simple faith and concrete imagery.

## Suno Styles
Southern gospel rock at 95 BPM in 4/4, anchored in conversational authenticity and redemptive arc. Intro opens with fingerpicked acoustic guitar—sparse, open tuning, natural room tone. Verses sit intimate: baritone vocal delivery with natural breath breaks, minimal percussion (brushed snare only), clean Telecaster arpeggios underneath. Pre-chorus builds tension as bass enters low and steady, vocal compression tightens slightly, drums shift to driving pocket. Chorus explodes full-band: tight kick-snare groove, walking bass, electric guitar melodic and confident, vocal sits front-center with conviction.

## Suno Exclude-styles
synthpop, EDM, dubstep, trap, K-pop, J-pop, eurobeat, vaporwave, synthwave, chiptune, bubblegum pop, electro house

### Song Lyrics:
[arrangement_cues |
- Intro: fingerpicked acoustic guitar, sparse and open, room tone, 95 BPM steady
- Verse 1: conversational delivery, natural breath at line breaks, minimal percussion
- Pre-Chorus: bass enters low and steady, slight compression on vocal, building momentum
- Chorus: full band kicks in—drums, bass, electric guitar—open and driving
- Bridge: stripped back to acoustic only, vulnerability peak, vocal intimate and raw
]

[Intro]
[Fingerpicked acoustic guitar, sparse and open]

[Verse 1]
Took the long way out of town
Left some wreckage on the ground
Couldn't face what I had done
So I ran toward the setting sun

Dust on my boots / Doubt in my chest
Figured moving on was better than the rest
Mile markers blur into the night
Hoping distance makes it right

[Pre-Chorus]
But the road keeps asking me
Who I'm gonna be
(Who am I?)

[Chorus]
On these dusty back roads, I'm finding my way
Leaving all the old ghosts where they lay
Simple faith and gravel underneath my feet
That's all I need to feel complete
On these dusty back roads, I'm coming home
Never have to walk this alone

[Bridge]
[Acoustic guitar only, intimate and raw]
I don't need the city lights
Don't need to run through the night

Just a quiet place to breathe
And the grace to believe

(That I'm enough)

[Outro]
[Fingerpicked acoustic, sustained vocal hum, reverb tail]
On these dusty back roads
Yeah, I'm coming home

[5 second fade out]
[end]

HookHouse Features Demonstrated:

• Arrangement Cues Block: [arrangement_cues | ...] at the top with micro-dynamics
• Block 2 (Style): Flowing prose production blueprint (911 chars, auto-trimmed to ≤1000)
• Block 3 (Excluded Styles): 12 comma-separated genres to avoid
• Block 5 (Summary): Emotional/physiological arc with concrete imagery (500 chars, auto-trimmed)
• Funksmith Refinements: Breath points indicated with /, vocal texture cues in parentheses
• Physiological Resonance: "Dust on my boots / Doubt in my chest" (breath space), "my legs could stand" (concrete)
• Suno Compliance: Perfect bracket formatting, proper section headers, ends with [end]

Funksmith Changelog Extract:

Verse 1, Line 5: Changed "and" to "/" to create breath space at 95 BPM Verse 2, Line 4: Changed "that I" to "my legs" for concrete physicality Bridge: Added "(That I'm enough)" as vulnerability whisper—core realization

See full example: examples/hookhouse/On_These_Dusty_Back_Roads.md

Cover Art Output

The script also generates cover art for the songs using Nano Banana on OpenRouter. Here's an example of the cover art created for the "Testing Ideas" song:

Configuration

Environment Variables

Create a .env file with the following variables:

# === LLM Provider Configuration ===
# Choose your preferred provider: anthropic, openai, google, or leave blank for legacy config
LLM_PROVIDER=anthropic

# Anthropic (Claude)
ANTHROPIC_API_KEY=your_anthropic_api_key_here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

# OpenAI (GPT)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o

# Google (Gemini)
GOOGLE_API_KEY=your_google_api_key_here
GOOGLE_MODEL=gemini/gemini-2.0-flash-exp

# OpenRouter (optional, for accessing multiple models)
OPENROUTER_API_KEY=your_openrouter_api_key_here

# === Image Generation ===
IMAGE_PROVIDER=openai  # Options: openai, google, openrouter
IMAGE_MODEL=dall-e-3

# === Local LM Studio (for --local flag) ===
LMSTUDIO_BASE_URL=http://localhost:1234/v1
LMSTUDIO_LLM_MODEL=qwen/qwen3-30b-a3b-2507

# === General Settings ===
LLM_MAX_TOKENS=8192
LLM_TEMPERATURE=0.1
REVIEW_MAX_ROUNDS=3
REVIEW_SCORE_THRESHOLD=8.0

Provider Options:

• Anthropic: Use Claude models (3.5 Sonnet, 3.5 Haiku, Opus, Sonnet 4.5)
• OpenAI: Use GPT models (GPT-4o, GPT-4o-mini, o1, o3-mini)
• Google: Use Gemini models (2.0 Flash, 1.5 Pro, 1.5 Flash)
• OpenRouter: Access any model through OpenRouter
• Local: Use LM Studio with local models

Custom Styles

Edit styles/styles.json to add custom style definitions:

{
  "custom_styles": {
    "your_style": {
      "description": "Description of your style",
      "tags": ["tag1", "tag2", "tag3"],
      "exclude_tags": ["exclude1"]
    }
  }
}

Technical Deep Dive: Agentic Songwriting Flow

The agentic process implemented via LangGraph produces superior results through its structured, multi-stage approach to song creation. Unlike single-shot generation methods, this agentic workflow breaks down the complex task of songwriting into specialized subtasks, each handled by dedicated AI agents with specific expertise. The parallel review system ensures multiple perspectives are considered simultaneously, while the iterative refinement loop allows for continuous improvement based on quantitative scoring. This architecture mimics human collaborative songwriting processes, where different specialists contribute their strengths—drafting, critiquing, revising, and polishing—resulting in lyrics that are more coherent, stylistically consistent, and emotionally resonant. The state management provided by LangGraph ensures that context and quality metrics are preserved throughout the entire workflow, enabling the system to make intelligent decisions about when to continue refining versus when to finalize the output.

• Orchestration (song_master.py): A LangGraph StateGraph wires together the agentic steps and keeps shared state (lyrics, score, metadata, persona, resources, round counters). The CLI parses prompt/name/persona/local-mode flags and seeds the graph with defaults from .env.

• Resource loading (helpers.load_resources): Styles from styles/styles.json, tag snippets in tags/*.txt, persona-specific style tokens from personas/*.md, and baseline song params (genre/tempo/key/instruments/mood). Persona style tokens get re-used later to bias metadata and tags.

• Prompt assembly (ai_functions.build_prompts): The drafter/reviewer/critic/preflight/revision/scoring/metadata prompts are built once, with the styles/tags/persona tokens inlined so every call has the same grounding data.

• Drafting (draft_node): User input is optionally titled, then sent to the drafter LLM with styles, tags, persona styles, and defaults. The LLM backend is chosen at runtime (local LM Studio via OpenAI-compatible API, LiteLLM relay, OpenRouter, or OpenAI) based on env vars.

• Parallel review loop (review_node): Three reviewers run in parallel threads (run_parallel_reviews), feedback is merged, revise_lyrics applies the edits, and score_lyrics parses a JSON score. The graph loops review rounds until the score crosses REVIEW_SCORE_THRESHOLD or REVIEW_MAX_ROUNDS.

• Critic pass (critic_node): A single critic prompt adds a last improvement pass before safety/format checks.

• Preflight + targeted fixes (preflight_node → targeted_revise_node): Lyrics are validated against style/tag rules. triage_preflight distills LLM feedback into a boolean pass + issue list; any issues trigger a targeted revision loop (and another review cycle) until resolved or rounds are exhausted.

• Metadata + cover art (metadata_node → album_art_node): The metadata agent emits JSON (description, Suno styles/exclude, target audience, commercial potential) and injects persona style tokens to keep the song “on persona.” Album art is generated unless --local is set; regeneration can be run directly with --regen-cover.

• Persistence (save_node): The final song, metadata, and user prompt are saved to songs/{YYYYMMDD}_{Title}.md, with optional {Title}_cover.jpg beside it.

flowchart TD
    A[CLI prompt/name/persona] --> B[Load styles, tags, persona tokens, defaults]
    B --> C[Build prompts and enhance input]
    C --> D[Draft song]
    D --> E[Parallel reviews x3]
    E --> F[Revise and score]
    F -->|below threshold and rounds left| E
    F --> G[Critic revision]
    G --> H[Preflight checks]
    H -->|issues and rounds left| I[Targeted fixes]
    I --> E
    H --> J[Metadata summary]
    J --> K{Local mode}
    K -->|yes| L[Skip cover art]
    K -->|no| M[Generate cover art]
    L --> N[Save song and metadata]
    M --> N

Project Structure

song-master/
├── README.md                                    # This file
├── HOOKHOUSE_CLAUDE_DESKTOP_INSTRUCTIONS.md     # HookHouse manual workflow guide
├── song_master.py                               # Main script with HookHouse workflow
├── ai_functions.py                              # AI interaction functions
├── helpers.py                                   # Utility functions
├── requirements.txt                             # Python dependencies
├── .env.example                                 # Environment variables template
├── backend/                                     # FastAPI backend
│   ├── main.py                                  # API server
│   ├── models/                                  # Request/response models
│   ├── routers/                                 # API endpoints
│   └── services/                                # Business logic
├── frontend/                                    # React SPA
│   ├── src/
│   │   ├── components/                          # React components (including ProgressTracker)
│   │   ├── pages/                               # Page components (including NewSong with HookHouse toggle)
│   │   ├── hooks/                               # Custom hooks (WebSocket, etc.)
│   │   └── api/                                 # API client
│   └── package.json
├── examples/                                    # Example outputs
│   ├── local/                                   # Local model examples
│   ├── openrouter/                              # OpenRouter model examples
│   └── testing-ideas.txt                        # Example input
├── prompts/                                     # AI prompts
│   ├── narrative_development.md                 # HookHouse: Storysmith Muse
│   ├── hookhouse_draft.md                       # HookHouse: Draft lyrics
│   ├── hookhouse_review.md                      # HookHouse: Quality review
│   ├── funksmith_critique.md                    # HookHouse: Funksmith refinement
│   ├── hookhouse_metadata.md                    # HookHouse: Metadata blocks
│   ├── hookhouse_image.md                       # HookHouse: Image prompt
│   └── caption_generation.md                    # HookHouse: Social captions
├── styles/                                      # Style definitions
├── personas/                                    # AI personas
└── tags/                                        # Default tags

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Check the examples directory for reference outputs
• Review the prompts directory for AI interaction templates