Update app.py

app.py

@@ -1,3 +1,4 @@
+
 import streamlit as st
 import uuid
 from harmonic_engine import (
@@ -22,11 +23,155 @@ st.markdown("""
         font-size: 22px; font-weight: bold; color: #f0f6fc;
         border-left: 4px solid #58a6ff; padding-left: 12px; margin-bottom: 8px;
     }
+    .help-box {
+        background: #161b22;
+        border-left: 4px solid #58a6ff;
+        padding: 1rem;
+        border-radius: 8px;
+        margin: 1rem 0;
+    }
+    .example-box {
+        background: #1c2128;
+        border: 1px solid #30363d;
+        padding: 0.75rem;
+        border-radius: 6px;
+        margin: 0.5rem 0;
+        font-family: monospace;
+    }
 </style>
 """, unsafe_allow_html=True)
 
 st.title("🎹 Harmonic Catalyst PRO")
-st.caption("Genre-Aware Voicing Engine • Multi-Section Builder • Voice Leading • Spectral Analysis")
+st.caption("Genre-Aware Chord Voicing Engine • Multi-Section Builder • Professional Mix Planning")
+
+# Help/Instructions Section
+with st.expander("📖 Quick Start Guide (Click to expand)", expanded=False):
+    st.markdown("""
+    ### 🎯 What This Tool Does
+    
+    Transform chord progressions into **professional piano voicings** across different genres, 
+    with smart voice leading and frequency-aware arrangement planning.
+    
+    ### 🚀 How to Use
+    
+    1. **Add a Section** - Click ➕ to create verse, chorus, bridge, etc.
+    2. **Enter Chords** - Type your progression (supports 20+ chord types + slash chords!)
+    3. **Pick Genre** - Choose from 17 styles (Pop, Jazz, Gospel, Afrobeats, etc.)
+    4. **Generate** - See piano voicings, frequency analysis, and download MIDI
+    
+    ### 💡 Try These Examples
+    """)
+    
+    col1, col2 = st.columns(2)
+    
+    with col1:
+        st.markdown("""
+        **🎵 Pop Ballad:**
+        ```
+        Section 1 (Verse): C Am F G
+        Section 2 (Chorus): C Am F G
+        Genre: Pop → Gospel (for lift!)
+        ```
+        
+        **🎷 Jazz Standard:**
+        ```
+        Chords: Dm7 G7 Cmaj7 A7
+        Genre: Jazz
+        Tip: Add slash chords for smooth bass!
+        ```
+        
+        **🌍 Afrobeats Vibe:**
+        ```
+        Chords: Em D C Bm
+        Genre: Afrobeats
+        Tip: Try same chords in Trap for contrast
+        ```
+        """)
+    
+    with col2:
+        st.markdown("""
+        **🎸 Slash Chord Magic:**
+        ```
+        C C/B Am Am/G F G/B C
+        Creates smooth bass line!
+        Genre: Any (works everywhere)
+        ```
+        
+        **🇮🇳 Bollywood Fusion:**
+        ```
+        Section 1: Cmaj7 Am7 (Hindustani Classical)
+        Section 2: Fmaj7 G7 (Pop)
+        = Traditional intro → Modern verse
+        ```
+        
+        **🎹 Genre Morphing:**
+        ```
+        Same chords, different sections:
+        Verse: Neo-Soul
+        Chorus: Gospel
+        Bridge: Jazz
+        ```
+        """)
+    
+    st.markdown("""
+    ### 🎼 Supported Chord Types
+    
+    | Type | Example | Type | Example |
+    |------|---------|------|---------|
+    | Major | `C`, `Cmaj` | Minor | `Cm`, `Cmin` |
+    | Major 7th | `Cmaj7` | Minor 7th | `Cm7`, `Cmin7` |
+    | Dominant 7th | `C7` | Suspended | `Csus2`, `Csus4` |
+    | Diminished | `Cdim`, `Cdim7` | Augmented | `Caug`, `C+` |
+    | Add 9 | `Cadd9` | 6th | `C6`, `Cm6` |
+    | Extended | `C9`, `C11`, `C13` | **Slash** | `C/E`, `Am/G` |
+    
+    ### 🎨 All 17 Genres
+    
+    **Western:** Pop • Jazz • Gospel • Blues • Classical • RnB • Waltz • Neo-Soul  
+    **Modern:** Afrobeats • Trap • K-Pop • Lo-fi • Funk  
+    **World:** Bossa Nova • Hindustani Classical • Reggae • Latin
+    
+    ### 💡 Pro Tips
+    
+    - **Use Slash Chords** for smooth bass lines: `C C/B Am Am/G`
+    - **Genre Morphing**: Same chords, different genres per section = dynamic arrangement
+    - **Voice Leading** (enabled by default): Connects sections smoothly even across genre changes
+    - **Frequency Analysis**: Warns if piano clashes with vocals in 160-400Hz zone
+    - **Duplicate Sections**: Use 📋 button to copy verse → verse 2 instantly
+    
+    ### 🎯 Workflow Example: Recreating "Raabta"
+    
+    1. Section 1: "Intro" → Chords: `Cmaj7 Am7` → Genre: Hindustani Classical
+    2. Section 2: "Verse" → Chords: `Cmaj7 Am7 Fmaj7 G7` → Genre: Pop
+    3. Section 3: "Chorus" → Same chords → Genre: Afrobeats (for modern twist!)
+    4. Generate → Download MIDI → Import to DAW → Add your sounds! 🎧
+    """)
+
+with st.expander("❓ FAQ & Troubleshooting", expanded=False):
+    st.markdown("""
+    **Q: What's the difference between genres?**  
+    A: Each genre uses different voicing techniques:
+    - **Jazz** = Shell voicings (root+7th in LH, 3-7-9-13 in RH)
+    - **Gospel** = Thick clusters with stacked 4ths and suspensions
+    - **Afrobeats** = Open 5ths, modern spacious sound
+    
+    **Q: When should I use slash chords?**  
+    A: When you want a specific bass note instead of the root:
+    - `C/E` = C major chord with E in bass (smoother transitions)
+    - Common in ballads, R&B, and jazz
+    
+    **Q: What does "MUD WARNING" mean?**  
+    A: Your piano has notes in 160-400Hz (where vocals sit). The tool auto-shifts them up an octave to keep your mix clean.
+    
+    **Q: Can I use Roman numerals?**  
+    A: Yes! Switch to Roman Numeral mode in sidebar, select your key, then use: `I vi IV V`
+    
+    **Q: How do I save my work?**  
+    A: Download the MIDI files, then you can reload them in your DAW anytime.
+    
+    **Q: Why are voicings different even with same chords?**  
+    A: That's the magic! Each genre has unique voicing rules. `Cmaj7` in Jazz sounds completely different from `Cmaj7` in Gospel.
+    """)
 
 if 'song_sections' not in st.session_state:
     st.session_state.song_sections = []
@@ -79,7 +224,8 @@ with st.sidebar:
     
     input_mode = st.radio(
         "Input Mode",
-        ["Chord Symbols (Cmaj7, Am7...)", "Roman Numerals (I, vi, IV, V)"]
+        ["Chord Symbols (Cmaj7, Am7...)", "Roman Numerals (I, vi, IV, V)"],
+        help="Choose how you want to enter chords. Roman numerals require selecting a key."
     )
     
     if "Roman" in input_mode:
@@ -89,19 +235,40 @@ with st.sidebar:
         key_pc = 0
     
     st.divider()
-    context = st.radio("🎚️ Mix Context", ["Full Band", "Solo Piano"])
+    context = st.radio(
+        "🎚️ Mix Context", 
+        ["Full Band", "Solo Piano"],
+        help="Full Band = Strict frequency checking. Solo Piano = More freedom in mid-range."
+    )
     
     st.divider()
     st.subheader("🔧 Voice Leading")
-    use_voice_leading = st.checkbox("🔗 Connect sections smoothly", value=True)
+    use_voice_leading = st.checkbox(
+        "🔗 Connect sections smoothly", 
+        value=True,
+        help="Automatically finds smoothest voicings between chords (minimal hand movement)"
+    )
     
     st.divider()
-    use_negative = st.checkbox("🌌 Negative Harmony", value=False)
+    use_negative = st.checkbox(
+        "🌌 Negative Harmony", 
+        value=False,
+        help="Experimental: Mirror chords around axis (Jacob Collier style)"
+    )
     if use_negative:
         neg_key = st.selectbox("Mirror Key", NOTE_NAMES, index=0)
         neg_key_pc = note_name_to_pc(neg_key)
     
     st.divider()
+    st.markdown("### 💡 Quick Tips")
+    st.info("""
+    **Try these now:**
+    - Enter: `C/E Am/G`
+    - Mix genres in one song
+    - Duplicate sections with 📋
+    - Download MIDI for your DAW
+    """)
+    
     if st.button("🗑️ Clear All Sections"):
         st.session_state.song_sections = []
         st.session_state.section_counter = 0
@@ -161,10 +328,27 @@ def draw_piano_svg(notes, label, start_midi=36, num_keys=37):
 
 st.markdown("---")
 st.subheader("🎵 Song Structure Builder")
-st.caption("Build your song section by section. Add any section in any order!")
+
+# Inline help text
+st.markdown("""
+<div class="help-box">
+    <strong>💡 How it works:</strong> Add sections in any order (Verse, Chorus, Bridge, etc.). 
+    Each section can have different chords and genres. Voice leading automatically connects them smoothly!
+</div>
+""", unsafe_allow_html=True)
 
 if len(st.session_state.song_sections) == 0:
-    st.info("👇 Click below to add your first section (Verse, Chorus, Intro, Bridge, etc.)")
+    st.markdown("""
+    <div class="example-box">
+    <strong>🎯 Try this example:</strong><br>
+    1. Click "Add First Section" below<br>
+    2. Name it "Verse", enter chords: <code>Cmaj7 Am7 Fmaj7 G7</code><br>
+    3. Select genre: Pop<br>
+    4. Add another section with same chords, but choose "Gospel" genre<br>
+    5. Click "Generate" and hear the difference!
+    </div>
+    """, unsafe_allow_html=True)
+    
     if st.button("➕ Add First Section", type="primary", use_container_width=True):
         add_section()
         st.rerun()
@@ -182,26 +366,27 @@ for idx, section in enumerate(st.session_state.song_sections):
                 value=section['name'],
                 key=f"name_{section['id']}",
                 label_visibility="collapsed",
-                placeholder="e.g., Verse 1, Chorus, Bridge, Drop..."
+                placeholder="e.g., Verse 1, Chorus, Bridge, Drop...",
+                help="Give this section a name (Verse, Chorus, etc.)"
             )
         
         with col_up:
-            if st.button("⬆️", key=f"up_{section['id']}", help="Move up", disabled=(idx == 0)):
+            if st.button("⬆️", key=f"up_{section['id']}", help="Move section up", disabled=(idx == 0)):
                 move_section_up(section['id'])
                 st.rerun()
         
         with col_down:
-            if st.button("⬇️", key=f"down_{section['id']}", help="Move down", disabled=(idx == len(st.session_state.song_sections) - 1)):
+            if st.button("⬇️", key=f"down_{section['id']}", help="Move section down", disabled=(idx == len(st.session_state.song_sections) - 1)):
                 move_section_down(section['id'])
                 st.rerun()
         
         with col_dup:
-            if st.button("📋", key=f"dup_{section['id']}", help="Duplicate"):
+            if st.button("📋", key=f"dup_{section['id']}", help="Duplicate this section"):
                 duplicate_section(section['id'])
                 st.rerun()
         
         with col_del:
-            if st.button("🗑️", key=f"del_{section['id']}", help="Delete"):
+            if st.button("🗑️", key=f"del_{section['id']}", help="Delete this section"):
                 remove_section(section['id'])
                 st.rerun()
         
@@ -209,24 +394,27 @@ for idx, section in enumerate(st.session_state.song_sections):
         
         with col1:
             if "Roman" in input_mode:
-                help_text = "Roman numerals: I ii iii IV V vi vii°"
+                help_text = "Roman numerals: I ii iii IV V vi vii°. Add 7 for seventh chords (V7, IVmaj7)"
+                placeholder = "e.g., I vi IV V"
             else:
-                help_text = "e.g., Cmaj7 Am7 Fmaj7 G7"
+                help_text = "Supports: maj, min, 7, maj7, sus2, sus4, add9, 9, 11, 13, dim, aug. Use / for slash chords!"
+                placeholder = "e.g., Cmaj7 Am7 F/A G or C C/B Am Am/G"
             
             section['chords'] = st.text_input(
                 "Chord Progression",
                 value=section['chords'],
                 key=f"chords_{section['id']}",
-                placeholder=help_text,
+                placeholder=placeholder,
                 help=help_text
             )
         
         with col2:
             section['genre'] = st.selectbox(
                 "Genre/Style",
-                ["Pop", "Jazz", "Gospel", "Blues", "Classical", "RnB", "Waltz"],
-                index=["Pop", "Jazz", "Gospel", "Blues", "Classical", "RnB", "Waltz"].index(section['genre']),
-                key=f"genre_{section['id']}"
+                ["Pop", "Jazz", "Gospel", "Blues", "Classical", "RnB", "Waltz", "Afrobeats", "Trap", "Bossa Nova", "Hindustani Classical", "Neo-Soul", "Reggae", "Latin", "K-Pop", "Lo-fi", "Funk"],
+                index=["Pop", "Jazz", "Gospel", "Blues", "Classical", "RnB", "Waltz", "Afrobeats", "Trap", "Bossa Nova", "Hindustani Classical", "Neo-Soul", "Reggae", "Latin", "K-Pop", "Lo-fi", "Funk"].index(section['genre']),
+                key=f"genre_{section['id']}",
+                help="Each genre uses different professional voicing techniques"
             )
         
         with st.expander("⚙️ Advanced Settings", expanded=False):
@@ -235,20 +423,22 @@ for idx, section in enumerate(st.session_state.song_sections):
                 section['lh_octave'] = st.slider(
                     "Left Hand Octave",
                     1, 4, section['lh_octave'],
-                    key=f"lh_{section['id']}"
+                    key=f"lh_{section['id']}",
+                    help="Lower = deeper bass. Default: 2"
                 )
             with col_rh:
                 section['rh_octave'] = st.slider(
                     "Right Hand Octave",
                     3, 6, section['rh_octave'],
-                    key=f"rh_{section['id']}"
+                    key=f"rh_{section['id']}",
+                    help="Higher = brighter sound. Default: 4"
                 )
         
         st.markdown("---")
 
 col_add, col_space = st.columns([1, 3])
 with col_add:
-    if st.button("➕ Add Section", use_container_width=True):
+    if st.button("➕ Add Section", use_container_width=True, help="Add another section to your song"):
         add_section()
         st.rerun()
 
@@ -278,14 +468,16 @@ if st.button("🎹 Generate Full Song", type="primary", use_container_width=True
                     if "Roman" in input_mode:
                         root_pc, quality = roman_to_chord(token, key_pc)
                         chord_label = f"{pc_to_note_name(root_pc)}{quality} ({token})"
+                        slash_bass = None
                     else:
-                        root_pc, quality = parse_chord_symbol(token)
+                        root_pc, quality, slash_bass = parse_chord_symbol(token)
                         chord_label = token
                     
                     lh, rh = GenreVoicer.voice(
                         root_pc, quality, section['genre'],
                         octave_lh=section['lh_octave'],
-                        octave_rh=section['rh_octave']
+                        octave_rh=section['rh_octave'],
+                        slash_bass=slash_bass
                     )
                     
                     if use_negative:
@@ -349,6 +541,7 @@ if st.button("🎹 Generate Full Song", type="primary", use_container_width=True
         
         if progression_data:
             st.subheader("💾 Export Full Song")
+            st.info("💡 **Tip:** Import these MIDI files into your DAW, assign sounds, and produce your track!")
             
             try:
                 files = MidiExporter.export(progression_data, filename_prefix="full_song")
@@ -384,3 +577,12 @@ if st.button("🎹 Generate Full Song", type="primary", use_container_width=True
                     'Status': '✅ Clear' if not r['has_issues'] else '⚠️ Fixed'
                 })
             st.dataframe(summary_data, use_container_width=True)
+
+# Footer
+st.markdown("---")
+st.markdown("""
+<div style='text-align: center; color: #8b949e; padding: 2rem 0;'>
+    <p>🎹 Built for musicians, by musicians • Free & Open Source</p>
+    <p>Found a bug or have a suggestion? Let us know!</p>
+</div>
+""", unsafe_allow_html=True)