Providers

Providers API for Plugins

Providers are modules that fulfill specific data requests from Nuclear. When the player needs to search for tracks, stream audio, or populate the dashboard, it queries the providers for that kind of request. Different provider kinds serve different purposes, and plugins can register as many providers as they need.

All registration and lookup goes through api.Providers.

{% hint style="info" %} Every provider extends the ProviderDescriptor base type, which requires an id, kind, and name. Each provider kind then adds its own domain-specific methods (e.g., searchArtists for metadata, getStreamUrl for streaming). {% endhint %}

Provider kinds

Registration

Register providers in your plugin's onEnable hook and unregister them in onDisable:

import type { NuclearPluginAPI, MetadataProvider } from '@nuclearplayer/plugin-sdk';

let providerId: string;

export default {
  onEnable(api: NuclearPluginAPI) {
    const provider: MetadataProvider = {
      id: 'my-metadata-source',
      kind: 'metadata',
      name: 'My Metadata Source',
      searchCapabilities: ['artists', 'albums'],
      searchArtists: async (params) => { /* ... */ },
      searchAlbums: async (params) => { /* ... */ },
      fetchAlbumDetails: async (albumId) => { /* ... */ },
    };

    providerId = api.Providers.register(provider);
  },

  onDisable(api: NuclearPluginAPI) {
    api.Providers.unregister(providerId);
  },
};

register() returns the provider's ID, which you pass to unregister() later. The first provider registered for a given kind becomes the active provider automatically. If the user hasn't changed the selection in Sources, subsequent registrations don't override it.

Provider lifecycle

Always register in onEnable and unregister in onDisable. If you skip unregistration, the provider stays in Nuclear's registry after your plugin is disabled, and the player may still pass queries to that phantom provider.

Base type

All providers share this shape:

type ProviderDescriptor<K extends ProviderKind = ProviderKind> = {
  id: string;
  kind: K;
  name: string;
  pluginId?: string;
};

Each provider kind (e.g., MetadataProvider, StreamingProvider, DashboardProvider) extends ProviderDescriptor with its own methods. See the individual guides linked above for details.

Sources view

Users manage providers in the Sources view, accessible from the sidebar. Metadata and streaming providers have an active selection that determines which provider handles search queries and stream resolution. The first provider registered for a kind becomes the active one automatically, and the selection persists across restarts. Users can switch the active provider at any time in the Sources view.

When you register a new provider kind, it appears in the Sources view automatically.