Writing OxiGuitar plugins
OxiGuitar is a small core with plugins. The core holds the score, shows it, exports it as a PDF, edits it and plays it; everything else comes from plugins: every file format, every sound, other exports, and tabs in the window’s panels. Our own Guitar Pro readers are plugins like any you write, and the app makes no distinction between ours and yours.
This guide shows how to write one, in Rust, with the SDK (oxiguitar-plugin). The fastest way in is to copy the template plugin: it builds, passes the contract suite and opens in the app as it is, and each part of it is explained in the pages that follow.
What you need
- Rust 1.99 or later, from rustup, for the SDK of v0.9.0.
- OxiGuitar 0.9 or later (0.5 for a plugin on interface 1.2, 0.2 for one on 1.0 or 1.1), to try your plugin in the app (the user manual).
- Nothing else: the SDK and the contract suite come through Cargo, and you write no
unsafecode.
The pages
| Page | What it covers |
|---|---|
| What a plugin is | What a plugin can and can’t do, and when it runs |
| Start from the template | Copy, rename, build, test, try it in the app |
| The plugin file and its manifest | The .oxp file and manifest.json, key by key |
| The SDK | The Plugin trait, export_plugin!, the host, errors and threads |
| Formats | Reading a file into a score, writing a score into a file |
| Tabs | A tab in one of the window’s areas: widgets and a canvas |
| Events and the open score | Following the score, the selection and playback |
| Services | Implementations of an interface, chosen per system |
| Instruments | What comes with the player |
| Settings | Keeping a plugin’s settings |
| Testing | cargo test, the contract suite, trying it in the app |
| Building for every system | Six targets, one file each, from one workflow |
| Installing and sharing | Where users put the file, and what to tell them |
| Interface versions | What 1.0 and 1.1 hold, and what stays compatible |
The design behind all this is in docs/design/plugins.md and ADR 0008. The SDK’s own reference is its rustdoc: cargo doc --open in your plugin’s folder.