Setup & Integration

This guide covers the complete setup flow: creating the manager, connecting to your bot lifecycle, forwarding voice packets, and using the player in commands.

Step 1: Create the Manager

Initialize Hoshimi with your node configuration and gateway sender.

bootstrap.ts

const  = ({
  ,
  : .,
  : [
    {
      : 'localhost',
      : 2333,
      : 'youshallnotpass',
    },
  ],
  : {
    : {
      : true,
      : true,
      : 60, // in seconds
    }
  },
  : {
    : {
      : true,
    },
  },
});

Step 2: Initialize on Bot Ready

Call manager.init() once your bot client is ready with user info.

ready-handler.ts

import type {  } from 'hoshimi';

declare const : ;
declare const : {
  : string;
  : string;
  : string | null;
};

.();

Step 3: Forward Voice Packets

Route all raw voice packets to manager.updateVoiceState() in your gateway raw event handler.

raw-handler.ts

import type {
  ,
  VoicePacket,
  VoiceServer,
  VoiceState,
  ChannelDeletePacket,
} from 'hoshimi';

type  = VoicePacket | VoiceServer | VoiceState | ChannelDeletePacket;

declare const : ;
declare const : ;

await .();

Step 4: Create Players in Commands

Use createPlayer() to get or create a player per guild. It's idempotent—calling it multiple times returns the same instance.

command-handler.ts

import type {  } from 'hoshimi';

declare const : ;
declare const : string;
declare const : string;
declare const : string;

const  = .({
  ,
  ,
  ,
  : 100,
  : true,
});

if (!.) await .();

Key Patterns

Idempotent creation: createPlayer() returns existing players by guild ID.
Health checks: Use manager.isUsable() before command execution — it is only true once a node is connected.
Session options: nodeOptions.sessionOptions holds resumable, timeout (seconds) and byLibrary, and persists playback across restarts.
Auto-destroy: Set playerOptions.onDisconnect.autoDestroy to clean up players when the bot leaves a voice channel.
Client id is required: init() throws unless you pass a real one — the default "0" is a placeholder, not a usable id.

Step 1: Create the Manager

Step 2: Initialize on Bot Ready

Step 3: Forward Voice Packets

Step 4: Create Players in Commands

Key Patterns

On this page