navidrome/plugins/examples/subsonicapi-demo/README.md

SubsonicAPI Demo Plugin

This example plugin demonstrates how to use the SubsonicAPI host service to access Navidrome's Subsonic API from within a plugin.

What it does

The plugin performs the following operations during initialization:

1. Ping the server: Calls /rest/ping to check if the Subsonic API is responding
2. Get license info: Calls /rest/getLicense to retrieve server license information

Key Features

• Shows how to request subsonicapi permission in the manifest
• Demonstrates making Subsonic API calls using the subsonicapi.Call() method
• Handles both successful responses and errors
• Uses proper lifecycle management with OnInit

Usage

Manifest Configuration

{
  "permissions": {
    "subsonicapi": {
      "reason": "Demonstrate accessing Navidrome's Subsonic API from within plugins",
      "allowAdmins": true
    }
  }
}

Plugin Implementation

import "github.com/navidrome/navidrome/plugins/host/subsonicapi"

var subsonicService = subsonicapi.NewSubsonicAPIService()

// OnInit is called when the plugin is loaded
func (SubsonicAPIDemoPlugin) OnInit(ctx context.Context, req *api.InitRequest) (*api.InitResponse, error) {
    // Make API calls
    response, err := subsonicService.Call(ctx, &subsonicapi.CallRequest{
        Url: "/rest/ping?u=admin",
    })
    // Handle response...
}

When running Navidrome with this plugin installed, it will automatically call the Subsonic API endpoints during the server startup, and you can see the results in the logs:

INFO[0000] 2022/01/01 00:00:00 SubsonicAPI Demo Plugin initializing...
DEBU[0000] API: New request /ping                        client=subsonicapi-demo username=admin version=1.16.1
DEBU[0000] API: Successful response                      endpoint=/ping status=OK
DEBU[0000] API: New request /getLicense                  client=subsonicapi-demo username=admin version=1.16.1
INFO[0000] 2022/01/01 00:00:00 SubsonicAPI ping response: {"subsonic-response":{"status":"ok","version":"1.16.1","type":"navidrome","serverVersion":"dev","openSubsonic":true}}
DEBU[0000] API: Successful response                      endpoint=/getLicense status=OK
DEBU[0000] Plugin initialized successfully               elapsed=41.9ms plugin=subsonicapi-demo
INFO[0000] 2022/01/01 00:00:00 SubsonicAPI license info: {"subsonic-response":{"status":"ok","version":"1.16.1","type":"navidrome","serverVersion":"dev","openSubsonic":true,"license":{"valid":true}}}

Important Notes

1. Authentication: The plugin must provide valid authentication parameters in the URL:
   • Required: u (username) - The service validates this parameter is present
   • Example: "/rest/ping?u=admin"
2. URL Format: Only the path and query parameters from the URL are used - host, protocol, and method are ignored
3. Automatic Parameters: The service automatically adds:
   • c: Plugin name (client identifier)
   • v: Subsonic API version (1.16.1)
   • f: Response format (json)
4. Internal Authentication: The service sets up internal authentication using the u parameter
5. Lifecycle: This plugin uses LifecycleManagement with only the OnInit method

Building

This plugin uses the wasip1 build constraint and must be compiled for WebAssembly:

# Using the project's make target (recommended)
make plugin-examples

# Manual compilation (when using the proper toolchain)
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o plugin.wasm plugin.go