Documentation · Developers

Build your first package

A Transcend extension is a folder containing a manifest and a Lua script. In about ten minutes you'll write one that adds two commands to the command palette and logs every time playback starts.

1Create the package

1. In Transcend, open Settings ▸ Packages ▸ Installed and click New Package....
2. Name it Octave Tools and check the author name. The id fills itself in, such as com.yourname.octave-tools. It's reverse-DNS, like a Java package or an Apple bundle id, and it's how Transcend recognises your package, so keep it once you share it.
3. Leave the location as Documents/Transcend Extensions or choose your own, then click Create.

Transcend creates the folder and loads it straight away. To check it's running, press Ctrl+P (Windows) or Cmd+P (macOS) and run Octave Tools: Say Hello; its message appears under Settings ▸ Packages ▸ Console.

com.yourname.octave-tools/
├── manifest.json        what the package is
├── README.md
├── scripts/
│   └── main.lua         your code
├── .luarc.json          editor set-up (never exported)
├── .transcend/          API definitions for autocomplete (never exported)
└── .vscode/             suggests the Lua extension (never exported)

The package shows as Linked in the list: Transcend runs it straight from this folder, never changes or deletes it, and Unlink only stops loading it.

Using a folder you made yourself

A package folder only needs manifest.json and scripts/main.lua. If you'd rather create them by hand, as shown in steps 3 and 4, click Load Folder... and choose the folder. Transcend checks it and shows the same prompt a user sees when installing it, listing what it asks for, before loading it.

2Open it in your editor

Any text editor works. We recommend Visual Studio Code (free, Windows and macOS):

1. In VS Code, choose File ▸ Open Folder... and open your package folder.
2. VS Code offers to install the Lua extension (by sumneko). Accept.
3. Open scripts/main.lua and type transcend.. Every function Transcend offers appears with its parameters and a short description, and a misspelled call is underlined before you ever run it.

The autocomplete comes from .transcend/transcend.d.lua, which New Package writes for you. For a folder you made by hand, download transcend.d.lua, put it in a .transcend folder inside your package, and add a .luarc.json next to manifest.json:

{
  "runtime.version": "Lua 5.4",
  "runtime.path": ["scripts/lib/?.lua"],
  "runtime.builtin": { "io": "disable", "debug": "disable", "package": "disable" },
  "workspace.library": [".transcend"]
}

The runtime.builtin line makes the editor flag io, debug and package, which don't exist inside Transcend's sandbox.

3The manifest

New Package wrote this for you; it describes the package to Transcend. Edit the description if you like.

manifest.json

{
  "format": "transcend.package",
  "formatVersion": 1,
  "id": "com.yourname.octave-tools",
  "name": "Octave Tools",
  "version": "0.1.0",
  "author": "Your Name",
  "description": "Counts and transposes the notes in the open pattern.",
  "apiLevel": 3,
  "provides": ["scripts"],
  "entry": "scripts/main.lua"
}

4Write the script

Replace everything in scripts/main.lua with the code below. Everything at the top level runs once each time the package starts: on install, on enable, on every launch, when you press Reload Scripts, and each time you save a file in a linked folder.

scripts/main.lua

-- Octave Tools: two commands for the open pattern, plus a playback log.
print("Octave Tools loaded")

-- The pattern open in the piano roll, or nil. Nothing is open in a fresh
-- project, so always check.
local function openPattern()
    local id = transcend.project.activePattern()
    if id == nil or id == "" then
        print("Open a pattern in the piano roll first.")
        return nil
    end
    return id
end

transcend.actions.register("countNotes", "Octave Tools: Count Notes", function()
    local id = openPattern()
    if not id then return false end
    local notes = transcend.project.notes(id) or {}
    print(string.format("%d notes in the open pattern", #notes))
    return true
end)

transcend.actions.register("octaveUp", "Octave Tools: Up an Octave", function()
    local id = openPattern()
    if not id then return false end

    local moved = {}
    for _, n in ipairs(transcend.project.notes(id) or {}) do
        moved[#moved + 1] = {
            note        = math.min(127, n.note + 12),
            velocity    = n.velocity,
            startStep   = n.startStep,
            lengthSteps = n.lengthSteps,
            pluginId    = n.pluginId,
        }
    end

    -- Scripts never edit the project directly. They ask Transcend to run an
    -- action, which is what puts the change on the undo stack.
    local ok = transcend.actions.invoke("pattern.setNotes", { patternId = id, notes = moved })
    if not ok then
        print("Transcend declined the edit. Is the pattern placed on the arrangement?")
    end
    return ok
end, { undoable = true })

transcend.events.on("transportStarted", function(e)
    print(string.format("Playback started at %.2f s, %.1f BPM", e.seconds, e.tempo))
end)

Three things to notice:

• Reading goes straight through transcend.project. Writing always goes through an action (transcend.actions.invoke), so every change your script makes can be undone like a hand edit.
• A command handler returns true when it did its job and false to decline, for example when nothing is open.
• Command ids are prefixed with your package id automatically, so "octaveUp" becomes com.yourname.octave-tools.octaveUp and can't collide with anyone else's.

5Reload and try it

1. Save main.lua. Because the folder is linked, Transcend reloads the package by itself a moment later. (You can also select Octave Tools in Settings ▸ Packages and click Reload Scripts.) The Console tab shows Octave Tools loaded.
2. Open a pattern with some notes in the piano roll. For Up an Octave, the pattern must be placed on the arrangement.
3. Press Ctrl+P (Windows) or Cmd+P (macOS) and type octave. Both commands are there.
4. Run Octave Tools: Up an Octave. The notes jump up. Press Ctrl/Cmd+Z and the whole edit undoes in one step.
5. Press play and check the Console for the playback line.

Your commands also appear in Settings ▸ Shortcuts, where they can be bound to a key.

6Edit and reload

Change main.lua in your editor and save. Transcend notices the change and reloads the package a moment later. There's no build step, no copying and no button to press: Transcend runs the folder you're editing. If you save something that breaks the manifest, the package stops and the Console says why.

• Each reload is a fresh start. Global variables are gone. Anything you want to keep goes in transcend.state (below), which survives reloads, restarts and updates.
• If the script errors, the error shows in the Console and on the package's entry in the Installed list, and the rest of Transcend carries on.
• If an event handler errors, that one handler is switched off. Fix it and reload.

7Test it

Transcend can run your extension's tests by itself, with no window and no sound, against a pretend project. Put test files in a tests folder next to manifest.json. Each file is a list of tests:

tests/octave_test.lua

test("Up an Octave moves every note up 12", function()
    local before = transcend.project.notes("p1")
    testkit.truthy(testkit.run("octaveUp"))             -- run your own command
    testkit.equal(#testkit.calls("pattern.setNotes"), 1) -- what it asked Transcend to do
    local after = transcend.project.notes("p1")
    testkit.equal(after[1].note, before[1].note + 12)   -- and the result
end)

Then run Transcend with --test-extension and your package folder:

& "C:\Program Files\Transcend\Transcend.exe" --test-extension . | Out-Host

/Applications/Transcend.app/Contents/MacOS/Transcend --test-extension . | cat

It prints a line per test and exits with 0 when everything passed, 1 when a test failed and 2 when nothing could run, so it works in an automated check too.

• Your code runs in the real sandbox, with the same API and the same limits as inside Transcend. require finds your scripts/lib modules.
• The pretend project comes from tests/project.json if you write one, using the same field names transcend.project gives you. Anything you leave out has a default: 120 BPM, 4/4, two tracks, and a pattern p1 called "Pattern 1" holding a C major chord.
• Commands your extension asks for are recorded (testkit.calls), and the common ones, such as pattern.setNotes or track.rename, change the pretend project the way Transcend would.
• Events don't happen by themselves. Fire the one you want: testkit.fire("transportStarted", { seconds = 0, tempo = 120 }).
• Panels can be tested too: testkit.draw draws one and tells you what text it drew, and testkit.click clicks it.

The API reference lists every testkit helper, and testkit.d.lua gives them autocomplete. Your saved state goes to a scratch folder during a test run, never to your real packages.

8Package it as a .tpkg

Select your package in Settings ▸ Packages and click Export .tpkg.... Transcend packs the folder and leaves out things that don't belong in a package, such as .git, .vscode and .DS_Store. It then checks the file with the same rules the installer uses. If the export succeeds, the file will install.

Zipping by hand instead

A .tpkg is a zip file with a different extension. If you'd rather make one yourself, two things trip people up:

7z a -tzip ..\com.yourname.octave-tools.tpkg *

zip -r -X ../com.yourname.octave-tools.tpkg . -x ".*" -x "*/.*"

To test the result the way a user would, Unlink your folder first (Transcend won't install a package whose id is currently linked), then drag the .tpkg onto the Transcend window.

9Share and publish it

There are three ways to get your extension to other people, from quickest to widest.

Send the file

A .tpkg installs by dragging it onto the Transcend window, or with Settings ▸ Packages ▸ Install Package.... Send it any way you like.

Install from a link

Put your extension on GitHub and attach the .tpkg to a release. Anyone can then install it by pasting your-name/your-repo, or the release's address, into the Install from a link box. The box is in Browser ▸ Extensions ▸ Get Extensions and at the top of the Store (View ▸ Get Extensions...). Transcend finds the newest release, downloads its .tpkg, and shows the person what it asks for before installing.

On the Get Extensions shelf

The shelf, and the larger Store, list extensions in two sections:

• Reviewed: written by Transcend, or read line by line by Transcend before listing. They carry a small "Reviewed" mark.
• Community: anyone's. The file stays on the author's own GitHub release, and the card shows their GitHub name. Before installing one, Transcend tells the person "Transcend hasn't read this one's code yet."

The easiest way into Community is the extension template on GitHub: transcend-extension-template. Click Use this template and you get an example extension with tests, a script that runs them in your installed Transcend, and an automatic check that builds the .tpkg and attaches it to a release every time you push a version tag (git tag v1.0.0, then push the tag). To be listed, add one small file naming your repository to the extensions index in a pull request. The pull request runs the same checks the shelf does. The template's README walks through every step.

What the shelf checks: the manifest is valid and names what is really in the folder, a script names an API level Transcend has, no file is over 4 MB and the package is under 64 MB, and a Community extension does not ask for network access. Give it a shelf.png (16:9, at least 480×270) and the shelf card shows it.

Updates

• Raise version, keep the same id, and ship a new .tpkg. Installing it replaces the old version and keeps the package's saved data. On the shelf, people who have it see an Update button.
• A listed version is pinned to its file's exact size and checksum. If the file on a release is replaced after listing, every copy of Transcend refuses it, so always publish a new version instead.
• Adding a README.md or LICENSE at the top of the package shows it in the package's details in Settings. A 128×128 icon.png gives it an icon in the list.

10What a script can reach

Everything is on one global table, transcend. The full API reference lists every function and the exact data each event receives.

11Rules worth knowing

• Check before using something newer. transcend.api.has("panels.create") tells you whether this version of Transcend has a function. That's better than raising apiLevel, which stops the package installing on older versions at all.
• api.has and permissions.has are different questions. The first asks whether Transcend has a function; the second asks whether the user granted your package a permission. Something like MIDI output needs both.
• It's a sandbox, not full Lua. There's no io, no os beyond os.time, os.clock and os.date, and no load or debug. require works only for modules in your own scripts/lib/ folder.
• Scripts run on the interface thread, never the audio thread. A slow script can stall the interface but never the audio. Transcend stops a script that runs too long, and unloads the whole package when it does. The startup run and each command get 10 million instructions. Each event handler or panel input call gets only 200,000, because it runs in the middle of something else Transcend is doing. So keep event handlers short, and do heavy setup at the top of main.lua. Each package gets 64 MB of memory.
• Note uids last for one session only. They're renumbered when a project loads, so never save one. The same goes for plugin ids.
• A page's button icon goes in images/, never icons/. A package's icons/ folder replaces Transcend's own icons, so a scripts package with one is refused unless it declares "icons".
• Track numbers start at 0, Lua lists start at 1. transcend.project.tracks()[1] is the track whose index is 0. Always pass a track's index to the track.* commands.
• print goes to the Extension Console, labelled with your package, and it's the quickest way to debug.