Manifest Reference

Overview

Every plugin must have a plugin.toml file in its root directory. Tabatura reads this file to determine the plugin's name, version, entry point, and licensing requirements before running any Lua code. Plugin folders live inside the Tabatura plugins directory for your platform:

🍎 macOS ~/Library/Application Support/tabatura/plugins/

🪟 Windows %AppData%\tabatura\plugins\

🐧 Linux ~/.config/tabatura/plugins/

name        = "My Plugin"
version     = "1.0.0"
description = "A short description shown in the Plugins menu."
author      = "Your Name"
entry       = "main.lua"

Fields

name Required string

Human-readable name shown in the Plugins menu and Settings dialog. Must be unique across all installed plugins — Tabatura uses the name as an internal identifier for preferences and enable/disable state.

name = "Note Display"

version Required string

Semver-style version string displayed in the Settings dialog. Not parsed or enforced — any non-empty string is accepted.

version = "1.2.0"

description Optional string

Short description shown in the Plugins → Settings dialog. Keep it to one sentence.

description = "Displays each note as it plays during playback."

author Optional string

Your name or organisation. Displayed in the Settings dialog alongside the plugin name.

author = "Jane Smith"

entry Optional string

Filename of the Lua entry point relative to the plugin directory. Defaults to main.lua if omitted. You can split logic across multiple files and require() them from the entry file.

entry = "main.lua"   -- default, can be omitted

licensed Optional bool

Set to true if the plugin requires a purchased license key. When licensed = true, the Settings dialog shows a license key entry field and the plugin is not loaded until a valid key is entered. Defaults to false.

license_id Required if licensed = true string

A stable, URL-safe identifier for this plugin (e.g. chord-pro). Used to scope license key verification. Contact the Tabatura team to obtain a signing key for your plugin ID.

licensed   = true
license_id = "chord-pro"

Validation

Tabatura includes a built-in validator that checks your plugin before you share it. It confirms that plugin.toml is valid, the entry script loads without errors, and that plugin.on_init and plugin.on_shutdown are defined. Run it from a terminal using the --validate-plugin flag, pointing at your plugin folder.

🍎 macOS

/Applications/Tabatura.app/Contents/MacOS/tabatura \
  --validate-plugin ~/Library/Application\ Support/tabatura/plugins/note-display

🪟 Windows

tabatura.exe --validate-plugin "%AppData%\tabatura\plugins\note-display"

🐧 Linux

./tabatura --validate-plugin ~/.config/tabatura/plugins/note-display

Exits with a success message on pass. Prints a descriptive error and exits with a non-zero code on failure.

Complete Example

Two plugin.toml files — one for a free plugin, one for a paid (licensed) plugin.

# plugin.toml — free plugin
name        = "Note Display"
version     = "1.0.0"
description = "Shows each note as it plays during playback."
author      = "Your Name"
entry       = "main.lua"

# plugin.toml — paid plugin requiring a license key
name        = "ChordPro Export"
version     = "2.1.0"
description = "Export tabs as ChordPro-formatted text."
author      = "Your Name"
entry       = "main.lua"
licensed    = true
license_id  = "chord-pro"