Your first plugin

Plugins are written in Lua 5.4. A plugin can:

• add lyrics providers, music providers (library sources), sound effects and visualizers
• build UI with Nari’s own components or plain Godot nodes
• change screens when they open, add Home entries and Now Playing tabs, open lists of its own songs
• add its own settings, on its own page or inside any Settings category
• shape the sound with the built-in equalizer
• run code in background threads that keep going while Android pauses the app

Caution

Plugins run with full access to Nari and to the user’s files. There is no sandbox, so be careful with what your plugin does and where it sends data.

Make one

1. Create a folder named after your plugin’s id, like hello, with a manifest.json:

   hello/manifest.json

   { "id": "hello", "name": "Hello", "version": "1.0.0", "author": "you", "description": "Says hi", "api": 1 }

2. Add a main.lua next to it. This one logs every song that starts:

   hello/main.lua

   nari.on("track", function(song)
     if song then
       nari.log("Now playing " .. song.title .. " by " .. song.artist)
     end
   end)

3. Zip the folder. The files can sit at the root of the zip or inside one folder, like the zips GitHub makes.

4. In Nari, open Settings → Plugins → Install plugin, pick the zip and turn the plugin on.

5. Play a song. The log shows [plugin hello] Now playing …: open it with F12 in developer mode, or look at the Godot output (logcat on Android).

Folder layout

• Directoryhello/

  • manifest.json
  • main.lua runs when the plugin turns on
  • library.lua a module, loaded with require("library")
  • Directorypreview/

    • icon.png
    • 1.jpg

Any other file in the folder (Lua modules, images, shaders, fonts…) is yours to use. Installed plugins live in user://plugins/<id>/.

Manifest

Field	Required	Description
id	yes	Unique id. It’s also the folder name, so it must be a valid file name.
name	yes	Name shown in Settings.
api	yes	Plugin API version the plugin was written for. The current one is 1.
main	no	Entry script, main.lua by default.
version	no	Shown in Settings.
author	no	Shown in Settings.
description	no	Shown in Settings.
icon	no	Image shown next to the plugin in Settings (png, jpg, webp or svg), relative to the plugin folder.
screenshots	no	Images shown in the plugin’s info: paths in the folder or https:// links, downloaded once and cached.
min_version	no	Oldest Nari version the plugin works with, like "1.2.0". Older versions won’t turn it on and say why.

Plugins with a missing or broken manifest, a missing main script or a newer api than Nari supports are skipped, and the reason is logged.

Next

Read How plugins run to know when your code runs, then Events and the nari API. The Examples are good starting points.