Backups

Custom Soundboard lets you create backups of your soundboards so you can share them with other people, use them on another device, or simply to back them up somewhere.

Backup types

When developing the format used for backups – and hence, for exposing them to the outside – I wanted to use existing standards instead of creating anything proprietary. As a result, Custom Soundboard only uses .xml and .zip files.

These are referred to as configuration backups and full backups respectively throughout this documentation.

Configuration backups

Configuration backups are .xml files that contain the configuration parameters of the soundboard they’re created for. This includes things like the soundboard’s names, its configured layout, colors, and more. The file also includes absolute paths to the files that are used by the soundboard, like recorded or imported audio files and thumbnails.

Importing such a backup on another device usually doesn’t make sense for two reasons.

1. The absolute paths referenced by the backup are typically different on different devices.
2. The backup is just a single file that does not include the actual files used by the soundboard.

Full backups

Full backups are .zip files that contain all the files required for your soundboard to work. This includes a configuration backup as well as all files it references, like audio files and thumbnails.

This can be imported on another device without requiring any pre-existing files or configuration.

Creating backups

Open a soundboard

To create a backup, you first need to open the soundboard you want to back up by tapping its card on the start screen of the app.

Open the backup dialog via the options menu

Open the options menu by tapping the three dots in the top-right corner of the soundboard screen and tap “Create backup”.

Select the backup type

Select the type of backup you want to create. The available options are configuration backups and full backups. After that, tap “Create”. You will then be prompted to choose a location you want the backup to be saved to. Choose something that suits your needs (the Downloads folder is usually a good choice) and wait for the backup to completed. The app will show you a message when it’s done creating your backup.

Importing backups

If you haven’t added any soundboards to the app yet, you can skip the full import process described below. Simply tap the “Import an existing soundboard” button on the welcome screen as can be seen in the screenshot. This will open a file picker that prompts you for a .xml or a .zip file.

If you’ve already added soundboards to the app, the button on the welcome screen isn’t available anymore. Follow the steps below to import a soundboard.

Open the app’s settings

Since importing a backup isn’t specific to any one soundboard, the option is not found within a soundboard. Instead, you’ll need to open the settings by tapping the three dots in the top-right corner and selecting “Settings”.

Navigate to “Files and backups”

Go to the “Files and backups” category within the settings.

Import your backup

Tap the “Import soundboard” option. This will open a file picker that prompts you to select a .zip or an .xml file.

The backup format

As described before, Custom Soundboard stores the main soundboard information in .xml files. You can see an example of such a file below.

When you create a full backup, the app creates a .zip file. You can also see an example of the format of such a backup below.

Configuration backups

Configuration backups follow a relatively simple format. However, this format changes once in a while. You can see the version the app used when creating your backup in the version attribute of the root soundboard tag. These versions are backwards-compatible. This means you can import older backups in newer versions of the app. However, you can’t import a newer backup in an older version of the app.

Because the app uses XML for backups, you can open them up, look at the format, and change the files so you’re happy with them. This allows for really advanced use cases like automation of soundboard creation, or advanced batch editing.

When looking through the format, you may notice a couple things that look odd. For example, each sound contains a list of sources. There’s also the empty <main/> tag in each soundboard’s configuration. These parts mostly show features that aren’t yet implemented or are planned for future versions of the app. While the format may change at all points, these are places that are especially likely to change.

Example

<?xml version="1.0" encoding="UTF-8"?>
<soundboard name="Example" position="0" id="475a031cc00931101d23debbbd2a64c529339697baa0e99b09f74b83a3664d69" creationTimeMillis="1644413820000" version="9" type="ZIP">
    <configuration>
        <main/>
        <portrait consistentSoundSize="false" maxNameLength="30" soundsPerRow="3"/>
        <landscape consistentSoundSize="false" maxNameLength="30" soundsPerRow="5"/>
    </configuration>
    <sounds>
        <sound name="Example sound" creationTimeMillis="1644413840000" id="3e54332ef32d15a04d5c50d286099a186a4fe859c6c5195778b25139c409e428" position="0">
            <sources>
                <source type="FILE" path="content://me.maagk.johannes.customsoundboard.me.maagk.johannes.customsoundboard.provider/files/475a031cc00931101d23debbbd2a64c529339697baa0e99b09f74b83a3664d69/recorded/09_02_2022_13_37_15.mp3" volume="1.0">
                    <fadeOptions fadeIn="false" fadeInOnPlay="false" fadeInTime="0" fadeOut="false" fadeOutOnPause="false" fadeOutOnStop="false" fadeOutTime="0"/>
                    <loopOptions count="0" space="0"/>
                    <timeOptions startTime="1250" stopTime="0"/>
                </source>
            </sources>
            <color code=""/>
            <thumbnail path=""/>
        </sound>
    </sounds>
</soundboard>

Full backups

Full backups follow a really simple format. They are a single .zip file that contains the following entries:

• <soundboard name>.xml

The configuration backup for the soundboard.

• sounds/

A directory containing all the audio files for the sounds added to the soundboard.

The files are named using their corresponding sound’s ID (id attribute in each sound tag) instead of their visible name and don’t carry a file extension.

• thumbnails/

A directory containing all thumbnails associated with the sounds added to the soundboard.

The files are named using their corresponding sound’s ID (id attribute in each sound tag) instead of their visible name and don’t carry a file extension.

This entry is only present when the soundboard contains at least one thumbnail.

Example