> For the complete documentation index, see [llms.txt](https://audacity.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://audacity.gitbook.io/dev/scripting/creating-custom-themes.md).

# Creating custom themes

Audacity supports themes via files called ImageCache.png which can be shared and installed by users.

{% hint style="info" %}
**Note:** It is recommended to only use the ImageCache.png to *distribute* themes, not to author them. This is due to the ImageCache breaking whenever buttons are added or removed from Audacity, which may happen more often in the coming releases.
{% endhint %}

## Creating a custom theme from source

Audacity stores the source files for the built-in themes in [`libraries/lib-theme-resources/`](https://github.com/audacity/audacity/tree/master/libraries/lib-theme-resources) as a group of individual files.

To create a custom theme out of this, use the following steps:

### Set up a build environment

1. get a copy of the audacity source and set up a build environment. Details can be found in [BUILDING.md](https://github.com/audacity/audacity/blob/master/BUILDING.md).

### Set up a new theme

{% hint style="info" %}
Note: You may skip steps 2-6 and edit an existing theme directly. However, making a new theme is beneficial if you want to create multiple new themes and/or maintain them across multiple versions of Audacity.
{% endhint %}

2. Copy an existing theme folder in lib-theme-resources to create a base for your own theme and rename it with your theme name (for this example, `Yourtheme`).
3. Replace all relevant files with your own themed versions. Some files found in the sources are no longer (or not yet) used in current versions of Audacity.\
   Note: Make sure to use an editor that's capable of handling transparencies - MSPaint will not work. Additionally, make sure to not resize any images.
4. Create a copy of ClassicThemeAsCeeCode.cpp and edit it:

```cpp
static const std::vector<unsigned char> ImageCacheAsData {
// Include the generated file full of numbers
#include "YourthemeThemeAsCeeCode.h"
};

static ThemeBase::RegisteredTheme theme{
   /* i18n-hint: the name of a theme */
   { "Yourtheme", XO("Your theme") }, PreferredSystemAppearance::Light, ImageCacheAsData
                                   //PreferredSystemAppearance can be Light, Dark, and HighContrastDark. 
                                   //It gives a hint to the OS what kind of theme you'd prefer for the 
                                   //system-native buttons, but usually is ignored.
};
```

5. Open lib-theme-resources' CMakeLists.txt file and add your theme like the others:

```cmake
foreach( pair
   "classic;ClassicThemeAsCeeCode"
   # ...
   "yourtheme;YourThemeAsCeeCode"

# ...

set( SOURCES
   ClassicThemeAsCeeCode.cpp
   ClassicThemeAsCeeCode.h
   # ...
   YourthemeThemeAsCeeCode.cpp
   YourthemeThemeAsCeeCode.h
```

6. In `libraries/lib-theme/Theme.cpp`'s function `GUITheme()`, add your theme to the list:

```cpp
     static const Identifier names[] = {
         "classic", "light", "dark", "high-contrast", "yourtheme"
      };
```

### Enable experimental theming options

7. In src/Experimental.cmake, uncomment the THEME\_PREFS flag (remove the `#` before `THEME_PREFS`):

```cmake
   #August 2009 - Theming not locked down enough for a stable release.
   # This turns on the Theme panel in Prefs dialog. It is independent of THEMING.
   THEME_PREFS
```

8. Compile and run Audacity.

### Export the ImageCache.png

9. Open the preferences.
10. Press OK and restart Audacity.
11. You'll see an experimental option called Theme:\
    ![image](https://user-images.githubusercontent.com/87814144/204311961-b2faea23-1784-4616-9141-2a04073353ef.png)\
    From here, you can do various things. Most importantly, "**Save Theme Cache**" creates the **ImageCache.png** you can share with other people. It will be stored in the Theme folder of the Audacity settings (ie %appdata%\Audacity if on Windows).

### Updating a custom theme

To update an existing theme to work with a new version, you'll need to pull the latest `master` from the `audacity/audacity` repo.

Once you have updated your fork, simply build Audacity again and export the ImageCache.png again (steps 8-11).

#### Updating Audacity from git

In your Github fork, there usually is a button for this:

<figure><img src="https://2511476368-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9ZM0AACxI0iUTeAM2egf%2Fuploads%2FJ7aMef4UDcOauZOAN3bt%2Fimage.png?alt=media&amp;token=19ee9b78-afc9-4996-9105-eae4c1ee39ab" alt=""><figcaption></figcaption></figure>

Alternatively, you can use git for this. Depending on your setup, it is likely to be one of the following

```
//this should work if you are using a github fork
git pull upstream master 

//this should work if you cloned the audacity repo without forking
git pull origin master 

//or, if neither works, add a remote and pull from there
git remote add upstream https://github.com/audacity/audacity.git
git fetch upstream
git pull upstream master
```

## Editing the ImageCache.png directly

If you want to avoid the dance described above, you can also edit the ImageCache.png directly. A copy for the version found in 3.6.x can be found below.

<figure><img src="https://2511476368-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9ZM0AACxI0iUTeAM2egf%2Fuploads%2FwUrs4tSuh5wYujWM5UZD%2FImageCache.png?alt=media&amp;token=eaa89d98-fc15-4996-9020-d31dcb31b1c9" alt=""><figcaption><p>ImageCache.png</p></figcaption></figure>

Additionally, an accompanying HTML explains what each button is called. Simply download both the PNG and HTML into the same folder, open the HTML in a browser and mouseover a button or color to get its name.

{% file src="/files/PgvPub2VdYMFLXNybu37" %}

But again, the version of the ImageCache above will likely only work for one version of Audacity.

## For users

Our [help pages](https://support.audacityteam.org/basics/customizing-audacity/using-themes) contain info on how to use custom themes as a user.