Documentation

Extensions and packages

Themes, layouts and extensions all come as a single .tpkg file. You install, turn off and remove them all the same way.

What a package is

A package is a .tpkg file. It can hold any mix of:

• A theme: the colours of the whole app.
• A layout: where the panels sit.
• Icons that replace some of Transcend's own.
• An extension: a script that adds commands, reacts to what you do, talks to MIDI hardware, or draws its own panel or even a whole page of its own.

Themes, layouts and icons are just data; they can't run anything. Extensions contain code, so Transcend treats them differently. It tells you before installing one, and it runs the code in a sandbox that only reaches what the package was allowed.

Transcend comes with some packages built in: its standard themes (including Walnut, Midnight and Moss), the Clip Launcher, Chord Practice and a Circle of Fifths panel. You can turn built-in packages off but not remove them.

Getting extensions

View ▸ Get Extensions... opens the Store over the window: featured extensions at the top, then every extension by kind (themes, layouts, pages and panels, tools), with a search box and lists of what you have installed and what has an update. Browser ▸ Extensions ▸ Get Extensions shows the same list in the sidebar. Click Get on a card to install it, or Update when a newer version is out.

The list has two sections:

• Reviewed: made by Transcend, or read line by line by Transcend before being listed. These carry a small "Reviewed" mark.
• Community: made by anyone and published on the author's own GitHub. The card shows the author's GitHub name. Before you install one, Transcend tells you "Transcend hasn't read this one's code yet."

The list itself is signed, and every listed file is checked against the exact file that was listed before it installs, so a file swapped afterwards is refused. An extension that needs a newer Transcend than yours says so on its card instead of offering Get.

Install from a link

If someone shares an extension that is on GitHub, paste the address of its GitHub release, or just owner/repository, into the Install from a link box at the top of the Store or on the sidebar list. Transcend downloads the release's .tpkg and shows you what it asks for before installing.

Installing a package file

Either:

• drag the .tpkg file onto the Transcend window, or
• open Settings ▸ Packages ▸ Installed and click Install Package....

If the package contains code, Transcend first tells you so, shows the author name the package gives and lists the permissions it asks for. A package file can carry any author name, so only install files from people you trust. Nothing is written until you click Install, and Cancel leaves nothing behind. Packages that only hold themes, layouts or icons install without asking, because there's nothing to approve.

Installing a theme or layout doesn't switch to it. It is added to the list; to use it, select the package in Settings ▸ Packages and click Use This Theme or Use This Layout. An extension is different: its script starts the moment it's installed, and again every time Transcend launches.

To update a package, install the newer .tpkg over it. The old version is replaced, and anything the extension saved is kept.

If an install is refused

Transcend explains why in one sentence. The common ones:

• "This package contains scripts. Scripting is not enabled...": scripting was switched off on this computer. Switch it back on and try again.
• "This package needs script API level N": the package was written for a newer version of Transcend. Update Transcend.
• "...uses backslash separators": the file was zipped with a tool Transcend can't safely read. Ask the author to re-zip it (see Build a package).

Managing packages

Everything lives in Settings ▸ Packages ▸ Installed. Select a package to see what it is, who made it, what it contains, what it's allowed to do and any error it hit.

Buttons that don't apply to the package you've selected are hidden.

Turning scripting off

Scripted extensions are on in every copy of Transcend. To run Transcend with no extension code at all (themes and layouts still work), start it with the TRANSCEND_EXTENSIONS environment variable set to 0. Packages containing code then can't be installed either.

setx TRANSCEND_EXTENSIONS 0

open -a Transcend --env TRANSCEND_EXTENSIONS=0

For a one-off, hold Shift while Transcend starts instead: that is safe mode, where no packages load at all. Settings ▸ Packages ▸ Console says whether scripting is on.

Permissions

An extension lists the permissions it wants, and you see that list before installing. Anything it didn't ask for is refused, even if the script tries it anyway.

Using extensions

Commands

Extensions can add commands. Open the command palette with Ctrl+P on Windows or Cmd+P on macOS and start typing a command's name. Extension commands can be bound to a key in Settings ▸ Shortcuts, just like built-in ones, and extensions can make them undoable.

Panels

Some extensions draw their own view, such as the built-in Circle of Fifths. Open View ▸ Extension Panels. Panels appear in a dock under the arrangement, one tab per panel. Hidden panels cost nothing, and a panel that gets too slow is automatically slowed down so the rest of Transcend stays smooth.

Some extensions put their panel on the Browser's home screen instead, as a card you click to open.

Pages

An extension can also add a whole page, which fills the workspace beside the arrangement, the piano roll and the mixer. Its button sits in the main bar next to theirs. Open a page with that button, from View ▸ Extension Pages and Windows, or from the command palette (type Open Page and its name), which also lets you give it a key in Settings ▸ Shortcuts. Click the button again, or the arrangement button, to go back. A hidden page costs nothing.

Windows

An extension can also open a floating window above Transcend, which remembers its size and place. Windows open only when you ask: from View ▸ Extension Pages and Windows, from the command palette, or from a button in the extension itself.

Right-click menus

Extensions can add their own entries to the right-click menu of a clip, a track header or a mixer strip, and to the piano roll's Tools menu. They are grouped under Extensions.

The Extension Console

Settings ▸ Packages ▸ Console shows everything extensions print, plus every error they hit, labelled by package. You can filter it to one package, copy lines, or save it to a text file, which is the most useful thing to attach to a bug report about an extension.

When something goes wrong

Safe mode

Hold Shift while Transcend starts. In safe mode no packages load at all, including any theme that came from a package. Open Settings ▸ Packages, disable the package causing trouble, and restart Transcend normally.

Extensions protect themselves

• A broken package never stops Transcend from starting. It is skipped, and the reason is shown on its entry in Settings ▸ Packages.
• An extension stuck in an endless loop, or in a text search that would take too long, is stopped automatically and unloaded, with the reason in the console.
• An error in one extension doesn't affect the others.
• Extensions never run on the audio thread, so a slow extension can't cause audio dropouts.

Turning scripting off entirely

Set TRANSCEND_EXTENSIONS to 0 and restart, as described under Turning scripting off. Installed extensions stay on disk but none of their code runs.

Where packages are stored

Each package is a folder named after its id. What extensions save is kept in a hidden .state folder next to them, so updating a package keeps it and removing a package deletes it. Settings ▸ Packages also shows these paths.

Not in the beta yet

• No automatic updates. The Store shows an Update button when a newer version is listed. A package installed from a file is updated by installing the new file over the old one.
• No audio processing. Extensions work on the project, commands and MIDI. Effects and instruments are separate plugins.
• No file or network access, as described under Permissions.