Add background music support and audio diagnostics

Updated the version to 0.1.4 in `__init__.py`. Added `render_background_music_html` to `gradio_ui.py` for managing background music playback and volume. Modified `render_audio_player_html` to handle sound effects with temporary audio elements. Enhanced `handle_audio_settings_change` to return additional HTML for music and audio previews. Introduced `handle_sfx_volume_change` and `handle_music_volume_change` for real-time audio feedback. Updated `create_app` to integrate new audio elements. Added `check_audio_setup.py` for verifying audio file configurations.

check_audio_setup.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""
+Diagnostic script to check audio setup for Wrdler Gradio UI.
+Run this to verify audio files and directories are properly configured.
+"""
+
+import os
+from pathlib import Path
+
+def check_audio_setup():
+    """Check if audio directories and files exist."""
+    print("=" * 70)
+    print("Wrdler Audio Setup Diagnostic")
+    print("=" * 70)
+    
+    wrdler_dir = Path(__file__).parent / "wrdler"
+    
+    # Check music directory
+    music_dir = wrdler_dir / "assets" / "audio" / "music"
+    print(f"\n?? Music Directory: {music_dir}")
+    if music_dir.exists():
+        print("   ? Directory exists")
+        music_files = list(music_dir.glob("*.mp3"))
+        if music_files:
+            print(f"   ?? Found {len(music_files)} MP3 file(s):")
+            for f in music_files:
+                size_kb = f.stat().st_size / 1024
+                print(f"      - {f.name} ({size_kb:.1f} KB)")
+        else:
+            print("   ??  No MP3 files found")
+    else:
+        print("   ? Directory does NOT exist")
+        print(f"   ?? Create it with: mkdir -p {music_dir}")
+    
+    # Check effects directory
+    effects_dir = wrdler_dir / "assets" / "audio" / "effects"
+    print(f"\n?? Sound Effects Directory: {effects_dir}")
+    if effects_dir.exists():
+        print("   ? Directory exists")
+        
+        required_effects = ["correct_guess", "incorrect_guess", "hit", "miss", "congratulations"]
+        found_effects = []
+        missing_effects = []
+        
+        for effect in required_effects:
+            mp3_file = effects_dir / f"{effect}.mp3"
+            wav_file = effects_dir / f"{effect}.wav"
+            
+            if mp3_file.exists():
+                size_kb = mp3_file.stat().st_size / 1024
+                found_effects.append(f"{effect}.mp3 ({size_kb:.1f} KB)")
+            elif wav_file.exists():
+                size_kb = wav_file.stat().st_size / 1024
+                found_effects.append(f"{effect}.wav ({size_kb:.1f} KB)")
+            else:
+                missing_effects.append(effect)
+        
+        if found_effects:
+            print(f"   ?? Found {len(found_effects)} effect file(s):")
+            for f in found_effects:
+                print(f"      - {f}")
+        
+        if missing_effects:
+            print(f"   ??  Missing {len(missing_effects)} effect file(s):")
+            for f in missing_effects:
+                print(f"      - {f}.mp3 or {f}.wav")
+    else:
+        print("   ? Directory does NOT exist")
+        print(f"   ?? Create it with: mkdir -p {effects_dir}")
+    
+    # Summary
+    print("\n" + "=" * 70)
+    print("Summary:")
+    print("=" * 70)
+    
+    all_ok = True
+    
+    if not music_dir.exists() or not list(music_dir.glob("*.mp3")):
+        print("??  Background music will not work (no music files found)")
+        all_ok = False
+    else:
+        print("? Background music should work")
+    
+    if not effects_dir.exists():
+        print("? Sound effects will not work (effects directory missing)")
+        all_ok = False
+    else:
+        required_effects = ["correct_guess", "incorrect_guess", "hit", "miss", "congratulations"]
+        missing_count = sum(1 for e in required_effects 
+                          if not (effects_dir / f"{e}.mp3").exists() 
+                          and not (effects_dir / f"{e}.wav").exists())
+        if missing_count > 0:
+            print(f"??  Sound effects partially working ({missing_count} missing)")
+            all_ok = False
+        else:
+            print("? All sound effects should work")
+    
+    if all_ok:
+        print("\n?? Audio setup is complete!")
+    else:
+        print("\n?? To generate missing sound effects, run:")
+        print("   python wrdler/sounds.py")
+        print("   or")
+        print("   python wrdler/generate_sounds.py")
+    
+    print("=" * 70)
+
+if __name__ == "__main__":
+    check_audio_setup()

wrdler/__init__.py

@@ -8,5 +8,5 @@ Key differences from BattleWords:
 - 2 free letter guesses at game start
 """
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 __all__ = ["models", "generator", "logic", "ui", "word_loader"]

wrdler/gradio_ui.py

@@ -158,12 +158,122 @@ def load_audio_data_url(path: str) -> str:
         return ""
 
 
+def render_background_music_html(enabled: bool, volume: float) -> str:
+    """Generate HTML to control background music player.
+    
+    Creates or updates a persistent audio element in the parent document.
+    The music will loop continuously when enabled.
+    
+    Args:
+        enabled: Whether background music should play
+        volume: Volume level (0.0 to 1.0)
+    
+    Returns:
+        HTML/JavaScript to inject into the page
+    """
+    # Get the first available music track (background.mp3 preferred)
+    tracks = get_audio_tracks()
+    if not tracks:
+        return ""
+    
+    # Prefer background.mp3, otherwise use first track
+    music_path = None
+    for name, path in tracks:
+        if name.lower() == "background":
+            music_path = path
+            break
+    if not music_path:
+        music_path = tracks[0][1]
+    
+    data_url = load_audio_data_url(music_path)
+    if not data_url:
+        return ""
+    
+    vol = max(0.0, min(1.0, float(volume)))
+    
+    if enabled:
+        return f'''
+<script>
+(function(){{
+    const doc = window.parent?.document || document;
+    let audio = doc.getElementById('wrdler-bg-music');
+    
+    if (!audio) {{
+        audio = doc.createElement('audio');
+        audio.id = 'wrdler-bg-music';
+        audio.loop = true;
+        audio.style.display = 'none';
+        doc.body.appendChild(audio);
+    }}
+    
+    const newSrc = "{data_url}";
+    if (audio.src !== newSrc) {{
+        audio.src = newSrc;
+    }}
+    
+    audio.volume = {vol:.3f};
+    audio.muted = false;
+    
+    const tryPlay = () => {{
+        const p = audio.play();
+        if (p && p.catch) {{
+            p.catch(() => {{
+                console.log('Music autoplay blocked - waiting for user interaction');
+                console.log('Click anywhere on the page to start music');
+            }});
+        }}
+    }};
+    
+    tryPlay();
+    
+    // Add user interaction listeners to unlock autoplay
+    const unlock = () => {{
+        tryPlay();
+        doc.removeEventListener('pointerdown', unlock);
+        doc.removeEventListener('keydown', unlock);
+        doc.removeEventListener('touchstart', unlock);
+    }};
+    
+    doc.addEventListener('pointerdown', unlock, {{ once: true }});
+    doc.addEventListener('keydown', unlock, {{ once: true }});
+    doc.addEventListener('touchstart', unlock, {{ once: true }});
+}})();
+</script>
+'''
+    else:
+        # Pause music when disabled
+        return '''
+<script>
+(function(){
+    const doc = window.parent?.document || document;
+    const audio = doc.getElementById('wrdler-bg-music');
+    if (audio) {
+        audio.pause();
+        audio.muted = true;
+    }
+})();
+</script>
+'''
+
+
 def render_audio_player_html(
     effect_name: Optional[str] = None,
     volume: float = 0.5,
     enabled: bool = True
 ) -> str:
-    """Generate HTML to play a sound effect."""
+    """Generate HTML to play a sound effect.
+    
+    Creates a temporary audio element that plays once and removes itself.
+    Sound effects are independent of background music.
+    
+    Args:
+        effect_name: Name of the sound effect to play
+        volume: Volume level (0.0 to 1.0)
+        enabled: Whether sound effects are enabled
+    
+    Returns:
+        HTML/JavaScript to inject into the page
+    """
     if not enabled or not effect_name:
         return ""
 
@@ -180,9 +290,34 @@ def render_audio_player_html(
     return f'''
 <script>
 (function(){{
-    const audio = new Audio("{data_url}");
+    const doc = window.parent?.document || document;
+    const audio = doc.createElement('audio');
+    audio.src = "{data_url}";
     audio.volume = {vol:.3f};
-    audio.play().catch(e => console.log('Audio play blocked'));
+    audio.style.display = 'none';
+    doc.body.appendChild(audio);
+    
+    // Play and remove after playback
+    const playPromise = audio.play();
+    if (playPromise) {{
+        playPromise.catch(e => {{
+            console.log('Sound effect play blocked:', e.message);
+            doc.body.removeChild(audio);
+        }});
+    }}
+    
+    audio.addEventListener('ended', () => {{
+        if (audio.parentNode) {{
+            doc.body.removeChild(audio);
+        }}
+    }});
+    
+    // Fallback cleanup after 10 seconds
+    setTimeout(() => {{
+        if (audio.parentNode) {{
+            doc.body.removeChild(audio);
+        }}
+    }}, 10000);
 }})();
 </script>
 '''
@@ -1053,8 +1188,12 @@ def handle_audio_settings_change(
     music_enabled: bool,
     music_volume: int,
     state: Dict[str, Any]
-) -> Dict[str, Any]:
-    """Handle audio settings changes."""
+) -> Tuple[Dict[str, Any], str, str]:
+    """Handle audio settings changes and return updated state + music HTML + preview audio.
+    
+    Returns:
+        Tuple of (updated_state, music_html, preview_audio_html)
+    """
     state = ensure_state(state)
 
     # Create a deep copy to ensure Gradio detects the change
@@ -1063,90 +1202,92 @@ def handle_audio_settings_change(
     new_state["sound_effects_volume"] = sfx_volume
     new_state["music_enabled"] = music_enabled
     new_state["music_volume"] = music_volume
-    return new_state
+    
+    # Generate music control HTML (updates background music volume)
+    music_html = render_background_music_html(music_enabled, music_volume / 100.0)
+    
+    # No preview audio by default
+    preview_audio = ""
+    
+    return new_state, music_html, preview_audio
 
 
-def handle_share_challenge(
-    username: str,
+def handle_sfx_volume_change(
+    sfx_enabled: bool,
+    sfx_volume: int,
+    music_enabled: bool,
+    music_volume: int,
     state: Dict[str, Any]
-) -> Tuple[str, str, Dict[str, Any]]:
-    """Handle share challenge button click."""
+) -> Tuple[Dict[str, Any], str, str]:
+    """Handle sound effects volume change with preview sound.
+    
+    Returns:
+        Tuple of (updated_state, music_html, preview_audio_html)
+    """
     state = ensure_state(state)
 
-    if not state.get("game_over"):
-        return "Game not finished yet.", "", state
-
-    username = username.strip() if username else "Anonymous"
-    if not username:
-        username = "Anonymous"
-
-    # Get game data
-    word_list = [text for text, x, y, direction in state["puzzle_words"]]
-    wordlist_source = state.get("wordlist", "classic.txt")
-    game_mode = state.get("game_mode", "classic")
-    score = state.get("score", 0)
-
-    # Calculate elapsed time
-    start_time = state.get("start_time")
-    end_time = state.get("end_time")
-    if end_time and start_time:
-        start = datetime.fromisoformat(start_time)
-        end = datetime.fromisoformat(end_time)
-        elapsed_seconds = int((end - start).total_seconds())
-    else:
-        elapsed_seconds = 0
-
-    # Check if this is a shared challenge being completed
-    is_shared_game = state.get("challenge_sid") is not None
-    existing_sid = state.get("challenge_sid")
-
-    try:
-        if is_shared_game and existing_sid:
-            # Add result to existing challenge
-            success = add_user_result_to_game(
-                sid=existing_sid,
-                username=username,
-                word_list=word_list,
-                score=score,
-                time_seconds=elapsed_seconds
-            )
-
-            if success:
-                share_url = get_shareable_url(existing_sid)
-                new_state = copy.deepcopy(state)
-                new_state["share_url"] = share_url
-                new_state["share_sid"] = existing_sid
-                return f"Result submitted for {username}!", share_url, new_state
-            else:
-                return "Failed to submit result.", "", state
-        else:
-            # Create new challenge
-            challenge_id, full_url, sid = save_game_to_hf(
-                word_list=word_list,
-                username=username,
-                score=score,
-                time_seconds=elapsed_seconds,
-                game_mode=game_mode,
-                grid_size=6,  # Wrdler: 6 rows
-                spacer=0,
-                may_overlap=False,
-                wordlist_source=wordlist_source,
-                game_title=APP_SETTINGS.get("game_title", "Wrdler Gradio AI"),
-                show_incorrect_guesses=state.get("show_incorrect_guesses", True),
-                enable_free_letters=state.get("enable_free_letters", True)
-            )
+    # Create a deep copy to ensure Gradio detects the change
+    new_state = copy.deepcopy(state)
+    new_state["sound_effects_enabled"] = sfx_enabled
+    new_state["sound_effects_volume"] = sfx_volume
+    new_state["music_enabled"] = music_enabled
+    new_state["music_volume"] = music_volume
+    
+    # Generate music control HTML
+    music_html = render_background_music_html(music_enabled, music_volume / 100.0)
+    
+    # Play preview sound effect at new volume level (only if enabled)
+    preview_audio = ""
+    if sfx_enabled:
+        preview_audio = render_audio_player_html("hit", sfx_volume / 100.0, True)
+    
+    return new_state, music_html, preview_audio
+
+
+def handle_music_volume_change(
+    sfx_enabled: bool,
+    sfx_volume: int,
+    music_enabled: bool,
+    music_volume: int,
+    state: Dict[str, Any]
+) -> Tuple[Dict[str, Any], str, str]:
+    """Handle music volume change with preview (updates background music).
+    
+    Returns:
+        Tuple of (updated_state, music_html, preview_audio_html)
+    """
+    state = ensure_state(state)
 
-            if sid:
-                share_url = get_shareable_url(sid)
-                new_state = copy.deepcopy(state)
-                new_state["share_url"] = share_url
-                new_state["share_sid"] = sid
-                return f"Share link generated!", share_url, new_state
-            else:
-                return "Failed to generate share link.", "", state
+    # Create a deep copy to ensure Gradio detects the change
+    new_state = copy.deepcopy(state)
+    new_state["sound_effects_enabled"] = sfx_enabled
+    new_state["sound_effects_volume"] = sfx_volume
+    new_state["music_enabled"] = music_enabled
+    new_state["music_volume"] = music_volume
+    
+    # Generate music control HTML (this updates the volume in real-time)
+    music_html = render_background_music_html(music_enabled, music_volume / 100.0)
+    
+    # No preview audio by default
+    preview_audio = ""
+    
+    return new_state, music_html, preview_audio
+
+def handle_show_incorrect_change(show_incorrect, wordlist, ai_topic, game_mode, sfx_en, sfx_vol, music_en, music_vol, enable_fl, show_chal, state):
+            state = ensure_state(state)
+            new_state = create_new_game_state(wordlist=wordlist, game_mode=game_mode, ai_topic=ai_topic)
+            # Apply all settings
+            new_state["sound_effects_enabled"] = sfx_en
+            new_state["sound_effects_volume"] = sfx_vol
+            new_state["music_enabled"] = music_en
+            new_state["music_volume"] = music_vol
+            new_state["show_incorrect_guesses"] = show_incorrect
+            new_state["enable_free_letters"] = enable_fl
+            new_state["show_challenge_links"] = show_chal
+            if not enable_fl:
+                new_state["last_action"] = "Free letters disabled. Click grid cells to reveal letters!"
 
-    except Exception as e:
-        return f"Error: {str(e)}", "", state
+            return build_ui_outputs(new_state)
 
 
 # ---------------------------------------------------------------------------
@@ -1254,8 +1395,6 @@ def create_app() -> gr.Blocks:
                                         )
                                         grid_buttons.append(btn)
 
-                        # Guess form
-                        with gr.Row():
                             # New Game button
                             new_game_btn = gr.Button("New Game", variant="primary", size="lg")
 
@@ -1311,7 +1450,7 @@ def create_app() -> gr.Blocks:
                             choices=["classic", "easy", "too easy"],
                             value="classic",
                             label="Game Mode"
-                        )
+                        )   
                         show_incorrect_guesses = gr.Checkbox(
                             value=APP_SETTINGS.get("show_incorrect_guesses", True),
                             label="Show Incorrect Guesses"
@@ -1352,11 +1491,14 @@ def create_app() -> gr.Blocks:
 
         # Audio player for sound effects (hidden via CSS but still executes)
         audio_player_html = gr.HTML(value="", elem_id="audio-player", elem_classes=["hidden-audio"])
+        
+        # Background music player (hidden but persistent)
+        music_player_html = gr.HTML(value="", elem_id="music-player", elem_classes=["hidden-audio"])
 
         # Timer for updating elapsed time (ticks every second)
         game_timer = gr.Timer(value=1, active=True)
 
-        # Game Over Modal Dialog (outside tabs) - contains game over display and share challenge section
+        # Game Over Modal Dialog (contains game over display and share challenge section)
         with Modal(visible=False) as game_over_modal:
             # Game Over Content
             game_over_html = gr.HTML(
@@ -1541,17 +1683,6 @@ def create_app() -> gr.Blocks:
             fn=lambda: gr.Timer(active=True),
             inputs=None,
             outputs=game_timer
-        ).then(
-            fn=lambda topic: topic.strip() if topic.strip() else "AI Generated",
-            inputs=[ai_topic_input],
-            outputs=topic_display
-        )
-
-        # AI Topic textbox submit (pressing Enter)
-        ai_topic_input.submit(
-            fn=handle_new_game,
-            inputs=[wordlist_dropdown, ai_topic_input, game_mode_dropdown, sfx_enabled, sfx_volume, music_enabled, music_volume, show_incorrect_guesses, enable_free_letters, show_challenge_links, game_state],
-            outputs=common_outputs
         ).then(
             fn=lambda: gr.Timer(active=True),
             inputs=None,
@@ -1625,24 +1756,24 @@ def create_app() -> gr.Blocks:
 
         # Audio settings change handlers
         sfx_enabled.change(
-            fn=handle_audio_settings_change,
+            fn=handle_audio_settings_change,            
             inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
-            outputs=[game_state]
+            outputs=[game_state, music_player_html, audio_player_html]
         )
         sfx_volume.change(
-            fn=handle_audio_settings_change,
+            fn=handle_sfx_volume_change,
             inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
-            outputs=[game_state]
+            outputs=[game_state, music_player_html, audio_player_html]
         )
         music_enabled.change(
             fn=handle_audio_settings_change,
             inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
-            outputs=[game_state]
+            outputs=[game_state, music_player_html, audio_player_html]
         )
         music_volume.change(
-            fn=handle_audio_settings_change,
+            fn=handle_music_volume_change,
             inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
-            outputs=[game_state]
+            outputs=[game_state, music_player_html, audio_player_html]
         )
 
         # Show incorrect guesses toggle handler - starts new game
@@ -1688,7 +1819,6 @@ def create_app() -> gr.Blocks:
             inputs=[enable_free_letters, wordlist_dropdown, ai_topic_input, game_mode_dropdown, sfx_enabled, sfx_volume, music_enabled, music_volume, show_incorrect_guesses, show_challenge_links, game_state],
             outputs=common_outputs
         )
-
         # Show challenge links toggle handler - starts new game
         def handle_show_challenge_links_change(enabled, wordlist, ai_topic, game_mode, sfx_en, sfx_vol, music_en, music_vol, show_inc, enable_fl, state):
             state = ensure_state(state)
@@ -1754,12 +1884,17 @@ def create_app() -> gr.Blocks:
         def initialize_ui(state):
             """Initialize UI components on app load."""
             state = ensure_state(state)
-            return build_ui_outputs(state)
+            # Generate initial music HTML based on settings
+            music_html = render_background_music_html(
+                state.get("music_enabled", False),
+                state.get("music_volume", 30) / 100.0
+            )
+            return (*build_ui_outputs(state), music_html)
 
         demo.load(
             fn=initialize_ui,
             inputs=[game_state],
-            outputs=common_outputs
+            outputs=[*common_outputs, music_player_html]
         )
 
-    return demo
+    return demo