Using Themes

What's a Theme?

A theme specifies the look of a set of overlays. You add them to a location of your choice, and then tell Soothsayer where to find them.

Installing Themes

Themes should be placed in separate folders inside your chosen theme directory. Each theme folder should have a theme.json file accessible at the root of the theme folder.

Downloading Themes

Themes can be downloaded from URLs. Here's how:

1. Make sure you specify a location for your theme files first.
2. Under Config > Themes click the Download button.
3. Enter in a URL to a ZIP file containing a theme. Theme Authors: see below for packaging instructions
4. Click Download.
5. If success, enjoy the new theme! If error, check the app for error messages, check that your URL is correct, and if you're still having problems, submit a bug report.

Soothsayer will cache the URLs used to download themes, and will provide a button in the top right of the theme description that allows you to quickly re-download the theme from the same URL. Assuming your theme provider uploads updates to the same link every time, you shouldn't have to manually enter in another URL after the first time. If the link changes, you can simply change the URL when using the re-download option.

Where can I get themes?

You might notice that the public build for Soothsayer doesn't include any themes beyond the base examples (many of which are pretty rough). You can find a list of publicly available themes on the Public Resources page.

Writing Themes

To create a theme for Soothsayer, all you need to do is create a folder with a theme.json file. This file requires the following schema:

{
  "name": [required: string],
  "version": [required: string],
  "author": [required: string],
  "folderName" : [required: string],
  "description" : [optional: string],
  "links" : {
    // object with optional fields, none are urls
    "twitter" : [string, handle without @],
    "twitch" : [string, username],
    "discord" : [string],
    "telegram" : [string, handle without @],
    "github" : [string, username],
    "kofi" : [string, username]
  }
}

folderName must be the name of the folder containing theme.json. Themes may override any CSS properties defined in the obs_src html files by creating a css file to replace one of the default src/obs_src/css files. You must name the theme css file the same as one of the default css files, and you must place it in a css folder in your theme directory. If you do not do this, the system will be unable to properly load your theme.

Your theme directory structure should look like this:

my-theme
  theme.json
  /css
  /images
  ...

At this time, themes may not provide js override files.

Packaging Themes

To let Soothsayer automatically download your theme, you need to create a zip archive where the theme.json file is in the root of the archive. Soothsayer will not install the theme if it can't find this file. The app will use the folderName contained in theme.json when creating the downloaded theme's install folder.

CSS File List

Themes must override one of the following css files to be properly loaded:

• caster-frame.css
  • caster-frame.html
  • caster-single-frame.html
  • caster-duo-frame.html
  • caster-single-side-facts.html
• draft.css
  • draft.html
• in-game.css
  • in-game.html
• map-select.css (Heroes of the Storm Specific)
  • map-select.html
  • map-select-list.html
  • map-select-tiles.html
• player-popups.css
  • player-popups.html
• single-image.css
  • blue-team-logo.html
  • red-team-logo.html
  • logo.html
• stat-lower-third.css
  • stat-lower-third.html
• tournament-standings.css
  • tournament-standings.html
• ticker-lower-third.css
  • ticker-lower-third.html