Extend Noctis.

Install and manage

Everything happens in Settings → Plugins. The same steps cover content packs and code plugins; the difference is that code waits for you to switch it on.

1. 1

   Open Settings → Plugins.

   Everything plugin-related lives on this one page.

2. 2

   Choose Install from file… and pick the plugin’s .zip.

   Noctis checks the zip before anything is written to disk.

3. 3

   Content packs are on right away. A code plugin lands switched off.

   Nothing from a code plugin runs until you say so.

4. 4

   To run code plugins, turn on Community plugins.

   It is off by default on new installs. That is restricted mode: no third-party code loads at all.

5. 5

   Switch the plugin on and review what it asks for.

   Noctis shows the plugin’s permissions and asks you to approve them.

6. 6

   Update by installing a newer zip of the same plugin.

   Its data and settings are kept. It only asks again if the update wants new permissions.

7. 7

   Remove it with the Remove button.

   The plugin’s data is kept unless you tick “Also delete its data and settings”.

8. 8

   Settings for a plugin are on its card.

   Open plugins folder and Reload plugins are on the same page.

Is it safe?

The honest version: it depends on which of the three you use.

• Content packs can’t run code. Noctis refuses a pack that contains a DLL, a script or XAML, and validates every file in it.
• Restricted mode is the default. With Community plugins off, no third-party code loads at all. New installs start that way. Installs that already had plugins before 1.5.3 start with it on, so updating doesn’t break an existing setup.
• A misbehaving plugin is stopped, not the app. If a plugin crashes, or holds the app for more than one second, it’s stopped and marked Failed. Noctis keeps running. Lyrics sources get eight seconds.
• Off means off. Disabling or removing a plugin removes everything it registered, even if the plugin forgot to clean up.
• Zips are checked before anything is written. A malformed archive, a missing entry DLL, more than 2,000 files or 256 MB, or any path that tries to escape the plugin folder rejects the whole file.

What the approval dialog shows

Reading what’s playing, the audio taps, visual layers, the scrobble hook, settings and private storage need no permission. Everything else is listed when you switch a plugin on:

network is a disclosure: plugins declare it if they go online. If an update asks for more permissions than you approved, the plugin waits in Needs approval until you switch it on again.

Content packs

Plain JSON, no code. A pack is on as soon as it’s installed, needs no approval or permissions, and works while Community plugins is off.

If a pack is switched off while its theme is in use, Noctis falls back to the default theme. Translations of Noctis itself belong on Crowdin; language packs are for languages or variants that aren’t there yet.

A theme in ten lines

{
  "id": "dusk",
  "name": "Dusk",
  "base": "dark",
  "accent": "#FF8A5B",
  "colors": {
    "AppMainBackground": "#17131F",
    "AppSidebarBackground": "#1F1929"
  }
}

The pack’s plugin.json lists what it contains:

{
  "id": "dev.example.sunset",
  "name": "Sunset",
  "version": "1.0.0",
  "author": "You",
  "type": "content",
  "minAppVersion": "1.5.3",
  "contents": {
    "themes": ["themes/dusk.json"],
    "lyricsPresets": ["lyrics/karaoke.json"],
    "languages": ["languages/en-XA.json"]
  }
}

Allowed files: .json, .md, .txt, .png, .jpg, .jpeg, .webp, plus LICENSE and README-style files. Anything else refuses the pack. Limits: 200 files, 2 MB per file, 20 MB per pack. Full content pack reference.

Local API

For apps that live outside Noctis: a stream overlay, a Stream Deck button, a script. Nothing runs inside Noctis, and it’s off until you turn it on.

1. 1

   Turn it on in Settings → Account & Devices → Local API.

   It listens on 127.0.0.1 only, never on your network. The default port is 9421.

2. 2

   Find the token in local-api.json.

   While the API is on, Noctis writes the port, base URL and token to its data folder: %APPDATA%\Noctis on Windows, ~/.config/Noctis on macOS and Linux.

3. 3

   Send it with every request.

   As Authorization: Bearer <token>, or as ?token= for OBS browser sources.

curl -H "Authorization: Bearer <token>" http://127.0.0.1:9421/api/v1/now-playing

Under /api/v1 you’ll find status, now playing, artwork, the queue (read and add), library search, the current lyrics, playback control (play, pause, next, previous, seek, volume, shuffle, repeat) and a live events stream over Server-Sent Events for track changes, play state, position, the queue and synced lyric lines.

The token is 256-bit, ten bad attempts in a minute lock requests out, and requests are protected against DNS rebinding. If a token leaks, say in a stream screenshot, press Regenerate token.

Local API reference OBS overlay and other samples

For developers

A code plugin is a .NET class library targeting net10.0 plus a plugin.json. It builds against the plugin kit, Noctis.Plugins.Abstractions, API version 1.1.

Quick start

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <EnableDynamicLoading>true</EnableDynamicLoading>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Noctis.Plugins.Abstractions" Version="1.1.*" ExcludeAssets="runtime" PrivateAssets="all" />
  </ItemGroup>
</Project>

using Noctis.Plugins;

public sealed class HelloPlugin : INoctisPlugin
{
    private readonly List<IDisposable> _hooks = new();
    public PluginInfo Info { get; } = new("dev.example.hello", "Hello", "1.0.0", "You", "Says hello.");

    public void Initialize(IPluginHost host)
    {
        _hooks.Add(host.RegisterTrackCommand("Say hello", icon: null,
            track => host.Notify($"Hello, {track.Artist}!")));
    }

    public void Shutdown()
    {
        foreach (var h in _hooks) h.Dispose();
        _hooks.Clear();
    }
}

{
  "id": "dev.example.hello",
  "name": "Hello",
  "version": "1.0.0",
  "author": "You",
  "type": "dotnet",
  "entry": "MyPlugin.dll",
  "apiVersion": "1.1",
  "minAppVersion": "1.5.3",
  "permissions": ["menu.commands", "notifications"]
}

The kit is coming to NuGet. Until then, build it from the repo with dotnet pack src/Noctis.Plugins.Abstractions -c Release, or reference the project the way the samples do.

What the API offers

Not possible yet: writing tags or the library, editing the queue, adding pages or sidebar entries.

Packaging

• A plugin is a .zip with plugin.json at the top, next to the DLL.
• Don’t ship Noctis.Plugins.Abstractions.dll, Avalonia*.dll or SkiaSharp*.dll. Noctis provides them.
• Each plugin loads in its own isolated context, so dependencies never clash and its folder is never locked. That is for stability, not security.
• A plugin built for a different API major version is refused. Minor versions only add, so 1.0 plugins run on 1.1.

Samples in the repo

• Pulse Ring: a visual layer that pulses with the beat.
• Track Tools: a menu command, library search, a notice, a lyrics source stub, a scrobble hook and declared settings.
• A sample content pack: two themes, a karaoke lyrics preset and a pseudo-language.
• The Local API samples: an OBS overlay, a PowerShell script and curl examples.

FAQ

Share plugins and ask for help on Discord