Plugin Quickstart

Prerequisites

• Tabatura installed and running on your machine
• A plain-text editor — Notepad, TextEdit, VS Code, anything works
• No prior Lua experience required for the quickstart

How Plugins Work

Each plugin lives in its own subdirectory inside the Tabatura plugins folder. Tabatura discovers and loads every subdirectory that contains a valid plugin.toml manifest on startup.

~/tabatura/plugins/
└── note-display/          ← your plugin folder
    ├── plugin.toml        ← metadata & entry point
    └── main.lua           ← plugin code

The Lua runtime calls plugin.on_init() once at load time. From there your plugin subscribes to events and builds UI using the plugin.* global table provided by the host. When Tabatura quits, plugin.on_shutdown() is called so your plugin can clean up.

Step 1 — Open your plugins folder

In Tabatura, open the Plugins menu and click Open Plugin Folder. This opens the plugins directory in your file manager. Inside that folder, create a new subfolder called note-display.

The folder is created automatically the first time Tabatura runs. If it doesn't exist yet, just create it.

Step 2 — Write plugin.toml

Inside the note-display folder, create a new file named plugin.toml (make sure your editor saves it as plain text, not rich text or .txt). This is the manifest Tabatura reads to discover your plugin.

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

See the Manifest reference for all available fields.

Step 3 — Write main.lua

In the same note-display folder, create a file named main.lua. The plugin opens a small floating window and listens for the note event, which fires for every note that plays during playback.

local win
local note_label
local pos_label

function plugin.on_init()
  -- Create two labels: one for pitch, one for position.
  note_label = plugin.new_label("Open a file and press ▶ to start…")
  pos_label  = plugin.new_label("")

  -- Pack them into a floating window.
  win = plugin.new_window("Note Display")
  plugin.window_set_content(win, plugin.new_vbox(note_label, pos_label))
  plugin.window_show(win)

  -- Add a toolbar button so the window can be reopened if closed.
  plugin.add_toolbar_item("Note Display", function()
    plugin.window_show(win)
  end)

  -- Update the display whenever a note fires during playback.
  plugin.on("note", function(e)
    plugin.set_label_text(note_label,
      string.format("String %d  ·  Fret %d", e.string, e.fret))
    plugin.set_label_text(pos_label,
      string.format("Track %d  ·  Measure %d  ·  Beat %d",
        e.track + 1, e.measure, e.beat))
  end)

  -- Reset when the file is closed.
  plugin.on("file.close", function(_)
    plugin.set_label_text(note_label, "Open a file and press ▶ to start…")
    plugin.set_label_text(pos_label, "")
  end)
end

function plugin.on_shutdown()
  print("[Note Display] shutting down")
end

Step 4 — Install and test

note-display/
├── plugin.toml
└── main.lua

Next Steps

You have a working plugin. Here's what to explore next: