Guides

Searching & Sources

Query tracks from different sources and handle search results.

This guide covers how to search for tracks from the manager or player level, and how to handle different result types.

Search from Manager

Use manager search to resolve tracks before creating or using a player.

manager-search.ts
import {  } from 'hoshimi';
import type {  } from 'hoshimi';

declare const : ;

const  = await .({
  : 'Daft Punk - Harder Better Faster Stronger',
  : .,
  : {
    : '123',
    : 'demo-user',
  },
});

.(.);
.(..);

Search from Player

Use player search in command handlers when the player already exists.

player-search.ts
import {  } from 'hoshimi';
import type {  } from 'hoshimi';

declare const : ;

const  = await .({
  : 'Lofi hip hop',
  : {
    : '123',
    : 'demo-user',
  },
});

if (. === . || . === .) {
  await ..(.[0]);

  if (!.()) {
    await .();
  }
}

Handling Load Types

Always branch by loadType to handle different search outcomes:

  • Track: Single track found.
  • Playlist: Multiple tracks in a playlist.
  • Search: Search results (multiple candidate tracks).
  • Empty: No results found.
  • Error: Search failed (provider error or network issue).

Source Configuration

  • Set a default source in manager options (defaultSearchSource) during bootstrap.
  • Override per query with the source parameter in SearchOptions when needed.
  • Build source identifiers using Source Registry for custom providers.