Working With Music in Big Box Themes

Big Box has two music systems that matter for theme developers:

• background music, which can be supplied globally by the user or directly inside a theme

• game music, which comes from a game's music file or playlist and can autoplay while browsing

Theme developers do not need to write code to use these systems. Most music behavior is controlled by Big Box settings, theme-specific settings, and files placed in the expected theme folders.

Background Music in a Theme

A Big Box theme can include its own background music by adding files here:

LaunchBox\Themes\[theme name]\Music\Background

When background music is enabled, Big Box checks the active theme's music folder before falling back to the user's global background music folder:

LaunchBox\Music\Background

This makes theme music a good fit when your theme has a specific mood, menu loop, or arcade cabinet presentation that should come with the theme itself.

Platform, Playlist, and Category-Specific Music

Big Box can also use more specific background music based on the current platform, playlist, or platform category.

Theme-specific folders use this structure:

LaunchBox\Themes\[theme name]\Music\Background\Platforms\[platform name]    LaunchBox\Themes\[theme name]\Music\Background\Playlists\[playlist name]    LaunchBox\Themes\[theme name]\Music\Background\Platform Categories\[category name]

Global user folders use this structure:

LaunchBox\Music\Background\Platforms\[platform name]    LaunchBox\Music\Background\Playlists\[playlist name]    LaunchBox\Music\Background\Platform Categories\[category name]

For example:

LaunchBox\Themes\My Theme\Music\Background\Platforms\Nintendo Entertainment System    LaunchBox\Themes\My Theme\Music\Background\Platform Categories\Arcade    LaunchBox\Themes\My Theme\Music\Background\Playlists\Favorites

These folder names must match the platform, playlist, or platform category name.

Background Music Lookup Order

When Use Platform/Playlist/Category-Specific Background Music is enabled, Big Box looks for music in this general order:

1. Theme-specific platform or playlist folder

2. Theme-specific platform category folder

3. Global platform or playlist folder

4. Global platform category folder

5. Theme's main Music\Background folder

6. Global background music folder

The theme's main Music\Background folder is only checked at the top level. Platform, playlist, and category-specific folders should go inside the exact folder names shown above.

Supported Music File Types

Big Box accepts common audio formats and several game music formats, including:

.mp3, .m4a, .wv, .mp4a, .wav, .aac, .wma, .ape, .ogg, .oga, .flac, .sid, .ac3, .alac, .amr, .dts, .xm, .it, .mod, .opus, .qcp, .nsf, .spc

For theme distribution, common formats like .mp3, .ogg, and .flac are usually the safest choices.

Game Music vs. Background Music

Game music is different from background music.

Game music comes from a game's music file. Big Box can find it from the game's assigned MusicPath, or from the platform's music folder by matching the game ID, game title, or application filename.

When game music starts, it can override background music. When the game music stops, background music can resume.

Theme developers should keep this in mind when designing views that also show videos. The user's sound options determine whether game music, background music, or video audio should take priority.

Important Big Box Music Settings

Users can control these options in Big Box under sound-related settings. Theme-specific overrides can also be saved through BigBoxSettingsOverrides.xml.

Important options include:

• RepeatGameMusic

• AutoPlayMusicGamesList

• AutoPlayMusicGameDetails

• AutoPlayMusicRecentFavorites

• EnableBackgroundMusic

• ShuffleBackgroundMusic

• UsePlatformPlaylistCategorySpecificBackgroundMusic

• ShuffleSoundtrackMusic

• PrioritizeMusicOverVideoAudio

• PlayVideoAudioWithBackgroundMusic

• EnableMusicOnScreenDisplay

• VolumeMusic

• VolumeBackgroundMusic

A theme should generally respect these settings. If you want your theme to ship with recommended defaults, set them through Big Box's Theme Specific Options and include the generated BigBoxSettingsOverrides.xml file with your theme.

Theme-Specific Music Defaults

If your theme is designed around a specific music experience, you can include a BigBoxSettingsOverrides.xml file with your theme.

This file belongs in the root of your theme folder:

LaunchBox\Themes\[theme name]\BigBoxSettingsOverrides.xml

For example:

LaunchBox\Themes\My Theme\BigBoxSettingsOverrides.xml

This file does not permanently change the user's global Big Box settings. It only supplies theme-specific defaults while your theme is active. Users can still change these options later through Big Box's Theme Specific Options menu.

Creating BigBoxSettingsOverrides.xml Manually

A music-only override file should use this structure:

<?xml version="1.0" standalone="yes"?>    
   <LaunchBox>
      <BigBoxSettings>
        <RepeatGameMusic>true</RepeatGameMusic>
        <AutoPlayMusicGamesList>true</AutoPlayMusicGamesList>
        <AutoPlayMusicGameDetails>true</AutoPlayMusicGameDetails>        <AutoPlayMusicRecentFavorites>true</AutoPlayMusicRecentFavorites>
        <EnableBackgroundMusic>true</EnableBackgroundMusic>
        <ShuffleBackgroundMusic>true</ShuffleBackgroundMusic>
        <UsePlatformPlaylistCategorySpecificBackgroundMusic>true</UsePlatformPlaylistCategorySpecificBackgroundMusic>
        <ShuffleSoundtrackMusic>false</ShuffleSoundtrackMusic>
        <PrioritizeMusicOverVideoAudio>true</PrioritizeMusicOverVideoAudio>
        <PlayVideoAudioWithBackgroundMusic>false</PlayVideoAudioWithBackgroundMusic>
        <EnableMusicOnScreenDisplay>true</EnableMusicOnScreenDisplay>
        <VolumeMusic>75</VolumeMusic>
        <VolumeBackgroundMusic>75</VolumeBackgroundMusic>
      </BigBoxSettings>
    </LaunchBox>

You only need to include the settings you want your theme to override. Any omitted settings will continue using the user's global Big Box settings.

Boolean values should be:

true    false

Volume values are whole numbers from 0 to 100.

Music Override Settings

These are the music-related settings theme developers are most likely to use:

Creating the Override File From Big Box

You can also let Big Box create the file for you.

1. Activate your theme in Big Box.

2. Open the System Menu.

3. Go to Options.

4. Open Theme Specific Options.

5. Change the music settings you want your theme to recommend.

6. Big Box will save those changed theme-specific values to:

LaunchBox\Themes\[theme name]\BigBoxSettingsOverrides.xml

This is usually the safest way to create the file, because Big Box writes the setting names and values in the correct format.

After Big Box creates the file, you can open it and remove unrelated settings if you only want to ship music-specific overrides with your theme.

Customizing the Music Notification

The music on-screen display uses this theme view:

LaunchBox\Themes\[theme name]\Views\MusicNotificationView.xaml

This view appears when Big Box starts a new music track and Enable Music On-Screen Display is enabled.

The default theme includes a working example, and it is the best starting point:

LaunchBox\Themes\Default\Views\MusicNotificationView.xaml

Music Notification Bindings

MusicNotificationView.xaml has a focused set of bindings:

<Image Source="{Binding ImagePath}" />
    <TextBlock Text="{Binding Title}" />
    <TextBlock Text="{Binding ArtistAlbum}" />
    <TextBlock Text="{Binding Track}" />

These bindings mean:

• ImagePath is the album artwork path when available, or the default music icon

• Title is the current track title

• ArtistAlbum combines artist and album text

• Track displays the current track number and total track count

A simple notification layout could look like this:

<UserControl xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
                 HorizontalAlignment="Stretch"
                 VerticalAlignment="Stretch"
                 FocusVisualStyle="{x:Null}">
        <Grid>
            <Border HorizontalAlignment="Right"
                    VerticalAlignment="Bottom"
                    Width="520"
                    Margin="40"
                    Padding="18"
                    Background="#DD111111"
                    CornerRadius="8">
                <DockPanel LastChildFill="True">
                    <Image Source="{Binding ImagePath}"
                           Width="90"
                           Height="90"
                           DockPanel.Dock="Left"
                           Stretch="UniformToFill"
                           RenderOptions.BitmapScalingMode="HighQuality" />
                    <StackPanel Margin="16,0,0,0"
                                VerticalAlignment="Center">
                        <TextBlock Text="{Binding Title}"
                                   Foreground="White"
                                   FontSize="24"
                                   FontWeight="Bold"
                                   TextTrimming="CharacterEllipsis" />
                        <TextBlock Text="{Binding ArtistAlbum}"
                                   Foreground="#CCCCCC"
                                   FontSize="20"
                                   TextTrimming="CharacterEllipsis" />
                        <TextBlock Text="{Binding Track}"
                                   Foreground="#999999"
                                   FontSize="18"
                                   TextTrimming="CharacterEllipsis" />
                    </StackPanel>
                </DockPanel>
            </Border>
        </Grid>
</UserControl>

Video Audio and Music

Big Box video controls react to music playback. When music is playing, video audio may be muted depending on the user's settings:

• If game music is playing and PrioritizeMusicOverVideoAudio is enabled, video audio is muted.

• If background music is playing and PlayVideoAudioWithBackgroundMusic is disabled, video audio is muted.

• If the user allows video audio alongside background music, both can play.

For theme developers, the safest approach is to let Big Box's built-in video controls handle this behavior. Avoid adding independent audio playback that competes with Big Box music, because it will not automatically follow these settings.

Recommendations

• Put theme-supplied background music in Music\Background.

• Use platform, playlist, and category-specific folders only when the music is meaningfully different.

• Keep theme music files reasonably sized, especially if distributing the theme publicly.

• Use common formats such as .mp3, .ogg, or .flac.

• Start from the default theme's MusicNotificationView.xaml.

• Keep the music notification small and readable; it appears on top of the active Big Box view.

• Use BigBoxSettingsOverrides.xml for recommended defaults instead of trying to force behavior in XAML.

• Test with background music, game music, and videos enabled so you can confirm the experience works in all common combinations.

In Short

Theme developers can package music directly with a Big Box theme, provide platform-specific music, customize the music notification popup, and ship recommended music defaults through theme-specific settings.

The main rule is to let Big Box manage playback. Use the expected folders, bind to the music notification view model, and respect the user's sound settings so background music, game music, and video audio work together cleanly.