Refactor background music: robust BGM handling, proper attribution, and service-worker caching

[asterdoescomputing]

Summary

The closed PR #8 added two MP3 files and a quick BGM implementation, but it contains several architectural, UX, and correctness issues. This issue collects the required, reviewer-requested, and recommended changes so contributors can implement a clean, maintainable background-music system, proper attributions, and robust offline caching.

Goals

• Move audio assets into a dedicated ./assets/audio/ folder.
• Implement a robust BGM system (stable across browsers and mobile) that respects the existing mute preference and user gesture/autoplay policies.
• Fix bugs and memory leaks in play/stop/resume logic.
• Ensure the Service Worker caches the right paths for offline play (or uses on-demand caching for large files).
• Preserve and expand credits with full attribution; add CREDITS.md and make the in-game credits modal scrollable.
• Add first-touch initialization so music reliably starts on first user interaction, and include two more tracks for world and boss modes.

Owner / reviewer feedback (from @aster-does-computing, May 22)

"Good choice of music by the way. It fits quite well with the game concept and story. However, the tracks and their artists were not given due credit in that matter. This is not reflected in the Credits section.

Additionally, could the music logic be improved to start playing on first touch by the user, just as the full screen function is operating for near almost perfect uptime.

It would also be a good idea to add two more tracks, one for world mode and another for boss fights, which in particular could be more cinematic and dramatic in mood."

Files to change (file-by-file guidance)

1. Add/move audio files

• Move bgm-menu.mp3 and bgm-playing.mp3 from the repository root to ./assets/audio/.
• Add two additional recommended tracks (placeholders until assets are approved): ./assets/audio/bgm-world.mp3 and ./assets/audio/bgm-boss.mp3.
• Keep exact filenames and update references in code and the service worker.
• Rationale: keeps repo root tidy and makes deployment/caching paths predictable.

2. script.js — refactor Audio handling

• Replace the quick implementation in PR Add copyright-free music options and update credits #8 with a robust pattern that preserves the public API (Audio.playBGM(path), Audio.stopBGM(), Audio.toggleMute(), etc.).
• Implementation notes:
  • Use persistent HTMLAudioElement(s) per track and reuse them; change src when switching tracks.
  • If an AudioContext is available, connect MediaElementAudioSourceNode -> GainNode -> destination to handle global volume/mute; keep element.muted as a fallback.
  • Do NOT create a new audio element on every play; reuse and cleanup correctly (audio.pause(); audio.src = ""; audio.load(); release references).
  • When AudioContext is suspended, store pendingTrack and resume playback after the first user gesture or whenever resume() completes.
  • Resume logic should resume the AudioContext first, then resume the BGM (use promises and handle errors).
  • Mute toggling should immediately affect the gain node (if present) and persist to localStorage; update UI state immediately.
  • Ensure sound effects (Audio.play(...)) continue to use the same AudioContext and remain unaffected.
• API additions (compatible with existing callers):
  • Audio.initBGM() — init context & nodes (call on first touch or app init).
  • Audio.initOnFirstTouch() — binds a one-time listener to resume/init on first meaningful user interaction.
  • Audio.playBGM(path)
  • Audio.stopBGM()
  • Audio.resumeBGM()
  • Audio.setMuted(boolean)
• Bug fixes to address from PR Add copyright-free music options and update credits #8 diff:
  • Don’t early-return from playBGM when ctx.state === 'suspended'; instead, remember the desired track.
  • Replace this.bgmNode.remove() with safe cleanup (src = ""; load()) to avoid DOM quirks.
  • Keep this.currentTrackPath accurate and clear it on stop.
  • Gracefully handle play() promise rejections and log diagnostics.
  • Debounce quick state-driven BGM switches to avoid stutter.

3. sw.js — caching & offline

• Update CORE_ASSETS to reference new audio paths (./assets/audio/...).
• Evaluate audio file sizes; if <= ~1–2 MB, precaching in install is acceptable. If larger, prefer on-demand caching: fetch-on-first-play then cache for offline.
• Ensure caching strategy does not block install for large files; implement background cache option if necessary.

4. Credits & repository attribution

• Preserve the full original credit data (do not oversimplify). Add or update CREDITS.md in the repo root with exact attribution lines and links to the original Pixabay Music pages for each track, and include Pixabay's license/usage note.
• Update the in-game credits modal to be scrollable and show the complete credit text (preserve formatting). Include:
  • Track title
  • Artist name
  • Direct link to Pixabay Music track page
  • Short license note (e.g., "Provided via Pixabay Music — free to use; see link for details")
• If Pixabay requires a specific attribution text, include that verbatim for each track.

5. UX improvements and app lifecycle

• Add a global, one-time user gesture initializer: on first meaningful user interaction call Audio.initBGM() / Audio.resume() and start menu BGM if the menu is active (mirrors fullscreen-first-touch UX).
• Do not autoplay audio before user interaction.
• Bind BGM switching to explicit game state transitions (menu → gameplay → world → boss); ensure switches are debounce-safe.
• Add a UI toggle for "Background music" separate from sound effects.

Acceptance criteria / How to test

1. Asset locations and references

• Files exist at ./assets/audio/bgm-menu.mp3, ./assets/audio/bgm-playing.mp3, ./assets/audio/bgm-world.mp3, and ./assets/audio/bgm-boss.mp3 (or placeholder files).
• sw.js references correct paths or on-demand cache logic caches them on first play.

2. Autoplay & gesture behavior

• No audio plays on initial page load before user interaction.
• On first user interaction (click/tap) the AudioContext resumes and menu BGM starts if menu active.

3. Mute & volume

• Mute toggle persists across reloads (localStorage) and immediately silences/resumes BGM without leaving dangling nodes.

4. Track switching

• Switching menu → gameplay → world → boss switches tracks cleanly with no unintended overlap and no memory leaks; debouncing prevents stutter.

5. Credits & attribution

• CREDITS.md added and readable with full preserved credit data.
• In-game Credits modal displays the full credit text, is scrollable, and contains titles, artists, and links to Pixabay.

6. Offline

• After playing once (or after install if pre-cached), tracks play offline via Service Worker.

Notes & suggested implementation details

• Preferred approach: HTMLAudioElement + MediaElementAudioSourceNode + GainNode for long-looped music; keep sound effects on oscillator/buffer paths as currently implemented.
• Consider extracting an audio-manager.js module to encapsulate complexity and keep script.js smaller.
• Keep references to ./assets/audio/ stable for deployments.

Links

• Closed PR for reference: Add copyright-free music options and update credits #8