Manages background music playback in menus with smart song selection, caching, and URL validation.
[heading: "Description"]BackgroundMusic handles the playback of music in menu screens, featuring intelligent song selection, caching for performance, URL accessibility validation, and seamless transitions between songs.
[heading: "Key Features"] [list] * Smart song randomization * Performance-optimized caching (30 second cache duration) * Last song persistence * URL accessibility checking with timeout * Error recovery and fallback * Visibility change handling (pause/resume) [/list] [heading: "Methods"] [table header] [ Method | Parameters | Description ] [ constructor | () | Initializes background music system ] [ registerVisibilityChangeListener | () | Sets up visibility handling ] [ playLastSong | () | Plays last played or random song ] [ playRandomSong | () | Selects and plays random song ] [ getCachedAvailableSongs | () | Gets cached song list (30s cache) ] [ getAllAvailableSongsFast | () | Builds fast song list without URL checking ] [ isValidAudioUrl | (url) | Validates audio URLs (excludes invalid patterns) ] [ checkUrlAccessible | (url) | Tests URL accessibility (800ms timeout) ] [ playSong | (songData) | Plays specified song ] [ removeSongFromCache | (failedUrl) | Removes failed song from cache ] [ stop | () | Stops music playback ] [ setVolume | (volume) | Sets playback volume ] [ refreshCache | () | Refreshes song cache ] [ destroy | () | Destroys background music system ] [/table] [heading: "Properties"] [table header] [ Property | Type | Description ] [ audio | HTMLAudioElement | Audio playback element ] [ randomSong | Boolean | Whether to randomize songs ] [ isPlaying | Boolean | Whether music is playing ] [ currentSong | Object | Currently playing song data ] [ availableSongsCache | Array | Cached available songs ] [ cacheTimestamp | Number | Cache creation time ] [ cacheDuration | Number | Cache validity duration (30 seconds) ] [ wasMusicPlaying | Boolean | Previous play state for pauses ] [ originalMusicTime | Number | Previous time for resuming ] [/table] [heading: "Song Selection Logic"] [table header] [ Condition | Behavior ] [ Last song available | Play last played song ] [ Random mode enabled | Select random song ] [ Song URL inaccessible | Remove from cache, fallback to random ] [ No songs available | Silent operation ] [/table] [heading: "URL Validation"]URLs are considered invalid if they:
[list] * Are null or undefined * Contain "assets/no-" * Are "undefined" or "null" strings * Are empty strings [/list] [heading: "Cache Performance"] [table header] [ Setting | Value | Description ] [ Cache Duration | 30 seconds | How long cache is valid ] [ URL Check Timeout | 800ms | Maximum URL test time ] [ Fallback Delay | 100ms | Delay before trying next song ] [/table] [heading: "Example Usage"] [codeblock javascript] // Background music is automatically initialized backgroundMusic.playLastSong(); // Manual control backgroundMusic.stop(); backgroundMusic.setVolume(3); // 75% // Refresh cache after adding new songs backgroundMusic.refreshCache(); [/codeblock] [footer: "© Retora 2026"]