add reusable menu music helpers

README.md

@@ -11,6 +11,7 @@ Reusable NVGT helpers for Storm projects.
 - `speech_history.nvgt`: `speak_with_history()` wrapper plus comma/period history navigation.
 - `notifications.nvgt`: Queued notifications with history and optional sound playback.
 - `menu_helpers.nvgt`: Simple menu runner + filter helpers with `sounds/menu` defaults.
+- `menu_music.nvgt`: Reusable menu music start/pause/stop helpers with blocking fade-out pause by default.
 - `audio_paths.nvgt`: Shared `.ogg` / `.wav` audio path resolution helper.
 - `learn_sounds.nvgt`: Reusable learn-sounds browser with project-level exclusion/description hooks.
 - `docs_browser.nvgt`: Reusable document discovery/opening helpers for menus.
@@ -30,6 +31,7 @@ Reusable NVGT helpers for Storm projects.
 #include "libstorm-nvgt/speech_history.nvgt"
 #include "libstorm-nvgt/notifications.nvgt"
 #include "libstorm-nvgt/menu_helpers.nvgt"
+#include "libstorm-nvgt/menu_music.nvgt"
 #include "libstorm-nvgt/learn_sounds.nvgt"
 #include "libstorm-nvgt/docs_browser.nvgt"
 #include "libstorm-nvgt/dict_utils.nvgt"
@@ -85,6 +87,23 @@ menu_apply_prefix_filter(filterText, options, filteredIndices, filteredOptions);
 bool changed = menu_update_prefix_filter(filterText, options, filteredIndices, filteredOptions, selection);
 ```
 
+## menu_music Example
+
+```nvgt
+#include "music.nvgt"
+#include "libstorm-nvgt/menu_music.nvgt"
+
+music_manager mainMenuMusic;
+
+void start_main_menu_music() {
+    menu_music_resume_or_play(mainMenuMusic, "sounds/menu/theme.ogg; loop; f=1", 1);
+}
+
+void stop_main_menu_music() {
+    menu_music_pause(mainMenuMusic, 800);
+}
+```
+
 ## file_viewer Example
 
 ```nvgt

menu_music.nvgt

@@ -0,0 +1,30 @@
+#include "music.nvgt"
+
+// Resume paused menu music when possible, otherwise start a new track.
+void menu_music_resume_or_play(music_manager &inout manager, const string track, const int fadeInMs = 0) {
+	if (manager.resume(fadeInMs)) {
+		return;
+	}
+
+	if (manager.playing) {
+		// Normalize state before fading back up.
+		manager.pause(0, true);
+		manager.resume(fadeInMs);
+		return;
+	}
+
+	manager.play(track);
+}
+
+// Pause menu music. Blocking is enabled by default so fade-out fully completes.
+bool menu_music_pause(music_manager &inout manager, const int fadeOutMs = 0, const bool blocking = true) {
+	if (!manager.playing) {
+		return false;
+	}
+	return manager.pause(fadeOutMs, blocking);
+}
+
+// Stop menu music and reset playback state.
+void menu_music_stop(music_manager &inout manager, const int fadeOutMs = 0, const bool blocking = false) {
+	manager.stop(fadeOutMs, blocking);
+}