navidrome/plugins/examples/discord-rich-presence

Discord Rich Presence Plugin

This example plugin integrates Navidrome with Discord Rich Presence. It shows how a plugin can keep a real-time connection to an external service while remaining completely stateless. This plugin is based on the Navicord project, which provides similar functionality.

⚠️ WARNING: This plugin is for demonstration purposes only. It relies on the user's Discord token being stored in the Navidrome configuration file, which is not secure and may be against Discord's terms of service. Use it at your own risk.

Overview

The plugin exposes three capabilities:

• Scrobbler – receives NowPlaying notifications from Navidrome
• WebSocketCallback – handles Discord gateway messages
• SchedulerCallback – used to clear presence and send periodic heartbeats

It relies on several host services declared in the manifest:

• http – queries Discord API endpoints
• websocket – maintains gateway connections
• scheduler – schedules heartbeats and presence cleanup
• cache – stores sequence numbers for heartbeats
• artwork – resolves track artwork URLs

Architecture

The plugin registers capabilities by exporting the required functions:

// Scrobbler capability
//export nd_scrobbler_is_authorized
//export nd_scrobbler_now_playing
//export nd_scrobbler_scrobble

// WebSocket callback capability
//export nd_websocket_on_text_message
//export nd_websocket_on_binary_message
//export nd_websocket_on_error
//export nd_websocket_on_close

// Scheduler callback capability
//export nd_scheduler_callback

When NowPlaying is invoked the plugin:

1. Loads clientid and user tokens from the configuration (because plugins are stateless).
2. Connects to Discord using WebSocketService if no connection exists.
3. Sends the activity payload with track details and artwork.
4. Schedules a one-time callback to clear the presence after the track finishes.

Heartbeat messages are sent by a recurring scheduler job. Sequence numbers received from Discord are stored in CacheService to remain available across plugin instances.

The scheduler callback uses the payload field to route to the appropriate handler:

• "heartbeat" – sends a heartbeat to Discord (recurring)
• "clear-activity" – clears the presence and disconnects (one-time)

Stateless Operation

Navidrome plugins are completely stateless – each method call instantiates a new plugin instance and discards it afterwards.

To work within this model the plugin stores no in-memory state. Connections are keyed by username inside the host services and any transient data (like Discord sequence numbers) is kept in the cache. Configuration is reloaded on every method call.

Configuration

Configure in the Navidrome UI (Settings → Plugins → discord-rich-presence):

Key	Description	Example
clientid	Your Discord application ID	123456789012345678
users	Comma-separated list of username:token pairs	alice:token123,bob:token456

Building

From the plugins/examples/ directory:

make discord-rich-presence.ndp

Or manually:

cd discord-rich-presence
tinygo build -target wasip1 -buildmode=c-shared -o plugin.wasm .
zip -j discord-rich-presence.ndp manifest.json plugin.wasm

Installation

Place the resulting discord-rich-presence.ndp in your Navidrome plugins folder and enable plugins in your configuration:

[Plugins]
Enabled = true
Folder = "/path/to/plugins"

Files

File	Description
main.go	Plugin entry point, manifest, scrobbler implementation
rpc.go	Discord gateway communication and RPC logic
pdk.gen.go	Generated types from XTP schemas (combined)
go.mod	Go module file (imports ndhost SDK)

Host SDK

This plugin imports the Go host SDK directly:

import ndhost "github.com/navidrome/navidrome/plugins/host/go"

The go.mod file uses a replace directive to point to the local SDK:

require github.com/navidrome/navidrome/plugins/host/go v0.0.0
replace github.com/navidrome/navidrome/plugins/host/go => ../../host/go

Host Services Used

Service	Purpose
Cache	Store Discord sequence numbers and processed image URLs
Scheduler	Schedule heartbeats (recurring) and activity clearing (one-time)
WebSocket	Maintain persistent connection to Discord gateway
Artwork	Get track artwork URLs for rich presence display

Implementation Details

See main.go and rpc.go for the complete implementation.