Documentation · Developers

Make a theme or a layout

A theme changes every colour in Transcend, and can put a picture behind the arrangement. A layout changes where the panels and buttons sit. Neither needs any code: you start from what is on your screen, edit one text file, and Transcend updates every time you save.

1Make a theme

1. Pick the theme closest to what you want, in Browser ▸ Extensions ▸ Themes or Settings ▸ General ▸ Appearance. Your theme starts as a copy of it.
2. In Browser ▸ Extensions ▸ Themes, click + New Theme Package... and give it a name.
3. Transcend writes a package folder in Documents/Transcend/Themes, switches to it, and opens the folder.
4. Open theme.json in any text editor. Change a colour and save. Transcend recolours itself straight away.

My Theme/
├── manifest.json    what the package is: id, name, version, author
├── theme.json       every colour, by name
└── README.md        what each colour name is used for

The folder is linked: Transcend reads it where it is and never changes it. You can keep it anywhere, put it under version control, and edit it while Transcend is open.

2The colours

theme.json

{
    "format": "transcend-theme",
    "version": 3,
    "name": "My Theme",
    "colors": {
        "workspaceBg": "#0E0E0E",
        "panelBg": "#1D1D1D",
        "accent": "#F48240",
        "textStandard": "#D7D7D7",
        ...
    }
}

Every colour has a name that says where it is used, such as workspaceBg, panelBg, accent or trackLane. New Theme Package writes every one of them, so nothing is left to guess, and the README.md beside it explains each name. Colours are #rrggbb.

• Change a few, not all. The quickest good theme starts from one you like and changes the accent and the background family. The built-in Walnut, Midnight and Moss themes were made exactly this way from Stealth Dark 2.
• Keep text readable. Check the text colours against the backgrounds they sit on, especially textOnAccent against accent.
• A colour you leave out is worked out from the others, so a short theme file, or one from an older version, still loads.

3A picture behind the arrangement

A theme can carry a picture that shows behind the arrangement's lanes, frosted so the clips stay easy to read. Put the image (PNG, JPG, WebP or BMP) in the package folder next to theme.json and name it in a wallpaper entry:

"wallpaper": {
    "image": "wallpaper.jpg",
    "strength": 0.8,
    "blur": 0.0,
    "fit": "fill"
}

If you already have a picture set when you click New Theme Package..., it is copied into the package for you. The picture stays still while the arrangement scrolls. Use a picture you made or have the right to share.

4Make a layout

1. Arrange Transcend the way you want, as far as you can by hand: open or close the browser, the mixer and the docked piano roll, and drag the panel edges.
2. In Browser ▸ Extensions ▸ Layouts, click + New Layout Package... and give it a name.
3. Transcend writes a package folder in Documents/Transcend/Layouts with layout.json holding every setting of the window as it is now, switches to it, and opens the folder.
4. Edit layout.json and save. The window rearranges straight away.

The README.md in the folder lists every setting and every button name you can use. It is written from Transcend itself, so it is always complete for your version.

5What a layout can change

layout.json (part of the Stage layout)

{
    "format": "transcend-layout",
    "version": 1,
    "name": "Stage",
    "layout": {
        "mainSplitterOrder": ["browser", "trackHeaders", "timeline", "assets"],
        "mainSplitterSizes": [300, 180, 1080, 260],
        "pianoRollDockOpen": true,
        "headerLeft":   ["menus", "lcd"],
        "headerCenter": ["transport.restart", "transport.play", "transport.record", "tools"],
        "headerRight":  ["view.timeline", "view.pianoRoll", "view.mixer", "separator", "status"]
    }
}

• Where the panels are: the order and width of the main columns, which docks are open and how tall, which sidebar tab and which Browser page are showing.
• The main bar: every button in the transport bar has a name (transport.play, view.mixer, ...). List them in headerLeft, headerCenter and headerRight in any order. A button you list nowhere is hidden. "transport" stands for the whole standard transport group, and "separator" adds a gap.
• The sidebar and mixer toolbars: patternsHeader, samplesHeader, filesHeader and mixerToolbar take button names the same way.
• Leave a setting out and it is left as the user had it. A layout that names no toolbar lists keeps the user's own toolbar.

A layout moves Transcend's own controls; it cannot change how they look. Colours belong to themes.

6Share it

• Select the package in Settings ▸ Packages, check the name, author and description in its manifest.json, and click Export .tpkg.... Anyone can install the file by dragging it onto the Transcend window.
• Themes and layouts are data, not code, so they install without a permission prompt and can never run anything.
• To get it on the Get Extensions shelf, publish it the same way as a scripted extension: see Share and publish it. On the shelf, a theme's card shows a picture of Transcend wearing it, so put a shelf.png screenshot (16:9, at least 480×270) in the package.
• To release an update, raise version in manifest.json and keep the same id.