NPM
GuideAPI
Guides

Plugin Registry

Map Lavalink plugins to capabilities and validate what a node can do.

Nodes report their installed plugins in /v4/info, but a feature is rarely tied to one plugin — lyrics work with any of three. The plugin registry maps capabilities to the plugin names that provide them, so the library asks "can this node do lyrics?" instead of "does it have this exact plugin?".

Built-in capabilities

capabilities.ts
import { ,  } from 'hoshimi';

.(.);
// ["lavalyrics-plugin", "java-lyrics-plugin", "lavasrc-plugin"]

.('lavasrc-plugin');
// ["lyrics", "extra-sources"]
CapabilityProvided by
Lyricslavalyrics-plugin, java-lyrics-plugin, lavasrc-plugin
ExtraSourceslavasrc-plugin, jiosaavn-plugin
Filterslavalink-filter-plugin
Dspxlavadspx-plugin
SponsorBlocksponsorblock-plugin
Youtubeyoutube-plugin
Searchlavasearch-plugin

Registering a fork or a new plugin

Bind your plugin to a built-in capability so existing features accept it, or declare a capability of your own for your code to check.

register-plugin.ts
import { ,  } from 'hoshimi';

.(
  { : ., : 'lavasrc-fork-plugin' },
  { : ., : 'lavasrc-fork-plugin' },
);

declare module 'hoshimi' {
  interface CustomizablePluginNames {
    : 'lavasrc-fork-plugin';
  }
}

Validating a node

validate throws a NodeError when the node cannot satisfy the request. required demands every capability, any demands at least one.

validate-node.ts
import { ,  } from 'hoshimi';
import type {  } from 'hoshimi';

declare const : ;

.({ , : [.] });
.({ , : [.] });

// Non-throwing check against a node's reported plugins
const  = .(.?. ?? [], .);

Skipping validation

Some forks under-report their plugins. Turn the check off globally or per capability instead of patching around the error.

skip-validation.ts
import { ,  } from 'hoshimi';

.(true);                         // everything
.(.);   // one capability
.([., .]);

.(.); // true
.();                            // back to normal

Key Concepts

  • Capability, not plugin: features check a capability, so any registered plugin providing it works.
  • Nodelink: validation is skipped automatically for nodes that report themselves as Nodelink.
  • Node must be ready: validate throws until the node has answered /v4/info.
  • Registration is global: do it at bootstrap, before players start using the feature.

Node Management

Select nodes, check health, and perform low-level node operations.

Custom Structures & Types

Override built-in structures and use inferred structure types.

On this page

Built-in capabilitiesRegistering a fork or a new pluginValidating a nodeSkipping validationKey Concepts