Add background music feature with controls

Updated .gitattributes to manage .mp3 files with Git LFS.
Enhanced README.md with changelog for new music feature.
Bumped version in __init__.py to 0.2.2.

Introduced audio.py module for handling audio tracks and
playback using Streamlit. Updated ui.py to integrate audio
controls, preserving music settings across sessions.

Improved CSS compatibility in _render_grid and adjusted
HTML formatting in _render_score_panel. Modified final
score color in _render_game_over modal.

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text

README.md

@@ -104,6 +104,13 @@ docker run -p 8501:8501 battlewords
 4. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.**
 
 ## Changelog
+
+- 0.2.2
+  - Add Musical background and settings to toggle sound on/off.
+
+- 0.2.1
+  - Add Theme toggle (light/dark/custom) in sidebar.
+
 - 0.2.0
   - Added a loading screen when starting a new game.
   - Added a congratulations screen with your final score and tier when the game ends.

battlewords/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 __all__ = ["models", "generator", "logic", "ui"]

battlewords/audio.py

@@ -0,0 +1,133 @@
+import os
+from typing import Optional
+import streamlit as st
+
+def _get_audio_dir() -> str:
+    return os.path.join(os.path.dirname(__file__), "assets", "audio")
+
+def get_audio_tracks() -> list[tuple[str, str]]:
+    """Return list of (label, absolute_path) for .mp3 files in assets/audio."""
+    audio_dir = _get_audio_dir()
+    if not os.path.isdir(audio_dir):
+        return []
+    files = [f for f in os.listdir(audio_dir) if f.lower().endswith(".mp3")]
+    files.sort()
+    return [(os.path.splitext(f)[0].replace("_", " ").title(), os.path.join(audio_dir, f)) for f in files]
+
+@st.cache_data(show_spinner=False)
+def _load_audio_data_url(path: str) -> str:
+    """Return a data: URL for the given audio file so the browser can play it."""
+    import base64, mimetypes
+    mime, _ = mimetypes.guess_type(path)
+    if not mime:
+        mime = "audio/mpeg"
+    with open(path, "rb") as fp:
+        encoded = base64.b64encode(fp.read()).decode("ascii")
+    return f"data:{mime};base64,{encoded}"
+
+def _mount_background_audio(enabled: bool, src_data_url: Optional[str], volume: float) -> None:
+    """Create/update a single hidden <audio> element in the top page and play/pause it."""
+    from streamlit.components.v1 import html as _html
+
+    if not enabled or not src_data_url:
+        _html(
+            """
+            <script>
+            (function(){
+              const doc = window.parent?.document || document;
+              const el = doc.getElementById('bw-bg-audio');
+              if (el) { try { el.pause(); } catch(e){} }
+            })();
+            </script>
+            """,
+            height=0,
+        )
+        return
+
+    # Clamp volume
+    vol = max(0.0, min(1.0, float(volume)))
+    # Inject or update a single persistent audio element and make sure it starts after interaction if autoplay is blocked
+    _html(
+        f"""
+        <script>
+        (function(){{
+          const doc = window.parent?.document || document;
+          let audio = doc.getElementById('bw-bg-audio');
+          if (!audio) {{
+            audio = doc.createElement('audio');
+            audio.id = 'bw-bg-audio';
+            audio.style.display = 'none';
+            audio.setAttribute('loop', '');
+            audio.setAttribute('autoplay', '');
+            doc.body.appendChild(audio);
+          }}
+          const newSrc = "{src_data_url}";
+          if (audio.src !== newSrc) {{
+            audio.src = newSrc;
+          }}
+          audio.muted = false;
+          audio.volume = {vol:.3f};
+
+          const tryPlay = () => {{
+            const p = audio.play();
+            if (p && p.catch) {{ p.catch(() => {{ /* ignore autoplay block until user gesture */ }}); }}
+          }};
+          tryPlay();
+
+          const unlock = () => {{
+            tryPlay();
+          }};
+          // Add once-only listeners to resume playback after first user interaction
+          doc.addEventListener('pointerdown', unlock, {{ once: true }});
+          doc.addEventListener('keydown', unlock, {{ once: true }});
+          doc.addEventListener('touchstart', unlock, {{ once: true }});
+        }})();
+        </script>
+        """,
+        height=0,
+    )
+
+def _inject_audio_control_sync():
+    """Inject JS to sync volume and enable/disable state immediately."""
+    from streamlit.components.v1 import html as _html
+    _html(
+        '''
+        <script>
+        (function(){
+          const doc = window.parent?.document || document;
+          const audio = doc.getElementById('bw-bg-audio');
+          if (!audio) return;
+          // Get values from Streamlit DOM
+          const volInput = doc.querySelector('input[type="range"][aria-label="Volume"]');
+          const enableInput = doc.querySelector('input[type="checkbox"][aria-label="Enable music"]');
+          if (volInput) {
+            volInput.addEventListener('input', function(){
+              audio.volume = parseFloat(this.value)/100;
+            });
+            // Set initial volume
+            audio.volume = parseFloat(volInput.value)/100;
+          }
+          if (enableInput) {
+            enableInput.addEventListener('change', function(){
+              if (this.checked) {
+                audio.muted = false;
+                audio.play().catch(()=>{});
+              } else {
+                audio.muted = true;
+                audio.pause();
+              }
+            });
+            // Set initial mute state
+            if (enableInput.checked) {
+              audio.muted = false;
+              audio.play().catch(()=>{});
+            } else {
+              audio.muted = true;
+              audio.pause();
+            }
+          }
+        })();
+        </script>
+        ''',
+        height=0,
+    )

battlewords/ui.py

@@ -16,6 +16,13 @@ from .logic import build_letter_map, reveal_cell, guess_word, is_game_over, comp
 from .models import Coord, GameState, Puzzle
 from .word_loader import get_wordlist_files, load_word_list  # use loader directly
 from .version_info import versions_html  # version info footer
+from .audio import (
+    _get_audio_dir,
+    get_audio_tracks,
+    _load_audio_data_url,
+    _mount_background_audio,
+    _inject_audio_control_sync,
+)
 
 
 CoordLike = Tuple[int, int]
@@ -332,6 +339,10 @@ def _new_game() -> None:
     mode = st.session_state.get("game_mode")
     show_grid_ticks = st.session_state.get("show_grid_ticks", False)
     spacer = st.session_state.get("spacer", 1)
+    # --- Preserve music settings ---
+    music_enabled = st.session_state.get("music_enabled", False)
+    music_track_path = st.session_state.get("music_track_path")
+    music_volume = st.session_state.get("music_volume", 20)
     st.session_state.clear()
     if selected:
         st.session_state.selected_wordlist = selected
@@ -339,6 +350,11 @@ def _new_game() -> None:
         st.session_state.game_mode = mode
     st.session_state.show_grid_ticks = show_grid_ticks
     st.session_state.spacer = spacer
+    # --- Restore music settings ---
+    st.session_state.music_enabled = music_enabled
+    if music_track_path:
+        st.session_state.music_track_path = music_track_path
+    st.session_state.music_volume = music_volume
     st.session_state.radar_gif_path = None  # Reset radar GIF path
     st.session_state.radar_gif_signature = None  # Reset signature
     _init_session()
@@ -436,7 +452,61 @@ def _render_sidebar():
             index=spacer_options.index(st.session_state.spacer),
             key="spacer"
         )
-        
+
+        # Audio settings
+        st.header("Audio")
+        tracks = get_audio_tracks()
+        # Show how many audio files were found
+        st.caption(f"{len(tracks)} audio file{'s' if len(tracks) != 1 else ''} found in battlewords/assets/audio")
+
+        if "music_enabled" not in st.session_state:
+            # Enable by default
+            st.session_state.music_enabled = True if tracks else True
+        if "music_volume" not in st.session_state:
+            st.session_state.music_volume = 20
+
+        enabled = st.checkbox("Enable music", value=st.session_state.music_enabled, key="music_enabled")
+
+        # Always show volume slider; disable when music disabled or no tracks
+        st.slider(
+            "Volume",
+            0,
+            100,
+            value=int(st.session_state.music_volume),
+            step=1,
+            key="music_volume",
+            disabled=not (enabled and bool(tracks)),
+        )
+
+        selected_path = None
+        if tracks:
+            options = [p for _, p in tracks]
+            # Default to first track if none chosen yet
+            if "music_track_path" not in st.session_state or st.session_state.music_track_path not in options:
+                st.session_state.music_track_path = options[0]
+
+            def _fmt(p: str) -> str:
+                # Find friendly label for path
+                for name, path in tracks:
+                    if path == p:
+                        return name
+                return os.path.splitext(os.path.basename(p))[0]
+
+            selected_path = st.selectbox(
+                "Track",
+                options=options,
+                index=options.index(st.session_state.music_track_path),
+                format_func=_fmt,
+                key="music_track_path",
+                disabled=not enabled,
+            )
+            src_url = _load_audio_data_url(selected_path) if enabled else None
+            _mount_background_audio(enabled, src_url, (st.session_state.music_volume or 0) / 100)
+        else:
+            st.caption("Place .mp3 files in battlewords/assets/audio to enable music.")
+            _mount_background_audio(False, None, 0.0)
+
+        _inject_audio_control_sync()
         st.markdown(versions_html(), unsafe_allow_html=True)
 
 def get_scope_image(uid: str, size=4, bgcolor="none", scope_color="green"):
@@ -644,10 +714,10 @@ def _render_grid(state: GameState, letter_map, show_grid_ticks: bool = True):
     st.markdown(
         """
         <style>
-        div[data-testid="column"] {
+        div[data-testid=\"column\"] {
             padding: 0 !important;
         }
-        button[data-testid="stButton"] {
+        button[data-testid=\"stButton\"] {
             width: 32px !important;
             height: 32px !important;
             min-width: 32px !important;
@@ -662,7 +732,7 @@ def _render_grid(state: GameState, letter_map, show_grid_ticks: bool = True):
             font-size: 1.4rem;
         }
         /* Further tighten vertical spacing between rows inside the grid container */
-        .bw-grid-row-anchor + div[data-testid="stHorizontalBlock"] {
+        .bw-grid-row-anchor + div[data-testid=\"stHorizontalBlock\"] {
             margin: 2px 0 !important;
         }
         .st-emotion-cache-14d5v98 {
@@ -864,9 +934,9 @@ def _render_score_panel(state: GameState):
                 extra_pts = max(0, pts - letters_display)
                 row_html = (
                     "<tr>"
-                    f"<td class=\"blue-background \"'>{word_display}</td>"
-                    f"<td class=\"blue-background \"'>{letters_display}</td>"
-                    f"<td class=\"blue-background \"'>{extra_pts}</td>"
+                    f"<td class=\"blue-background \"'>{{{{{word_display}}}}}</td>"
+                    f"<td class=\"blue-background \"'>{{{{{letters_display}}}}}</td>"
+                    f"<td class=\"blue-background \"'>{{{{{extra_pts}}}}}</td>"
                     "</tr>"
                 )
                 rows_html.append(row_html)
@@ -891,7 +961,7 @@ def _render_game_over(state: GameState):
             f"<tr><td class='blue-background'>{w.text}</td><td class='blue-background'>{len(w.text)}</td><td class='blue-background'>{extra_pts}</td></tr>"
         )
     table_html = (
-        "<table class='shiny-border' style=\"background: linear-gradient(-45deg, #a1a1a1, #ffffff, #a1a1a1, #666666); width:100%; margin: 0 auto;border-collapse:separate; border-spacing:0;\">"
+        "<table class='shiny-border' style=\"background: linear-gradient(-45deg, #1d64c8, #ffffff, #1d64c8, #666666); width:100%; margin: 0 auto;border-collapse:separate; border-spacing:0;\">"
         "<tr>"
         "<th class='blue-background bold-text'>Word</th>"
         "<th class='blue-background bold-text'>Letters</th>"
@@ -909,7 +979,7 @@ def _render_game_over(state: GameState):
                 <a href="?overlay=0" title="Close" style="position:absolute;top:12px;right:12px;display:inline-grid;place-items:center;width:40px;height:40px;border-radius:50%;background:rgba(0,0,0,0.25);color:#fff;text-decoration:none;font-size:1.6rem;font-weight:700;">&times;</a>
                 <h1 style="color:#fff;font-size:2.5rem;margin-bottom:0.5rem;">Congratulations!</h1>
                 <h2 style="color:#fff;font-size:2rem;margin-bottom:1rem;">Game Over</h2>
-                <div style="font-size:1.5rem;color:#1d64c8;margin-bottom:1rem;">Final score: <span style="color:#1d64c8;font-weight:800;">{state.score}</span></div>
+                <div style="font-size:1.5rem;color:#1d64c8;margin-bottom:1rem;">Final score: <span style="color:#1ca41c;font-weight:800;">{state.score}</span></div>
                 <div style="font-size:1.2rem;color:#fff;margin-bottom:2rem;">Tier: <strong>{compute_tier(state.score)}</strong></div>
                 <div style="margin-bottom:2rem;">{table_html}</div>
                 <div style="color:#fff;opacity:0.7;font-size:1rem;margin-bottom:2rem;background:#1d64c8;text-align:center;">Thank you for playing BattleWords!</div>