Skip to main content

Player

A Player in Yukino manages audio playback for a specific voice channel. It handles track playback, audio filtering, and voice connection state.


Player & Queue API Quick Reference​

See full Player & Queue API Reference →


Creating a Player​

// Basic player creation
const player = await yukino.createPlayer({
guildId: 'guild-id',
voiceChannelId: 'channel-id'
});

// Player with additional options
const player = await yukino.createPlayer({
guildId: 'guild-id',
voiceChannelId: 'channel-id',
textChannelId: 'text-channel-id',
selfDeaf: true,
selfMute: false,
volume: 100
});

Playback Control​

Basic Controls​

// Start playing
await player.play();

// Pause/Resume
await player.pause(); // Pause playback
await player.pause(false); // Resume playback (or use player.resume())

// Resume (alias for pause(false))
await player.resume();

// Stop
await player.stop();

// Destroy (cleanup)
await player.destroy();

Track Management​

// Play specific track
await player.play({ track: trackData });

// Skip current track
await player.skip();

// Seek to position
await player.seek(60000); // Seek to 1 minute

// Set volume (0-1000)
await player.setVolume(100);

Playback Information​

// Get current track
const track = player.current;
console.log('Now playing:', track.info.title);

// Get playback position
const position = player.position;
console.log('Current position:', position);

// Get formatted position (human-readable time)
const formattedPosition = player.getFormattedPosition();
console.log('Current position formatted:', formattedPosition); // e.g. "1:45"

// Check playback state
console.log('Is playing:', player.playing);
console.log('Is paused:', player.paused);

Queue Management​

Basic Queue Operations​

// Add tracks
player.queue.add(track);
player.queue.addMany([track1, track2]);

// Remove tracks
player.queue.remove(0);
player.queue.clear();

// Get queue information
console.log('Queue length:', player.queue.length);
console.log('Current track:', player.queue.current);
console.log('Next track:', player.queue.next);

Queue Manipulation​

// Shuffle queue
player.queue.shuffle();

// Move tracks
player.queue.move(0, 2); // Move first track to third position

// Filter tracks
const filtered = player.queue.filter(track =>
track.info.length < 300000 // Filter songs under 5 minutes
);

Loop Modes​

// Set loop mode
player.setLoop('none'); // No loop
player.setLoop('track'); // Loop current track
player.setLoop('queue'); // Loop entire queue

// Check current loop mode
console.log('Loop mode:', player.loop);

Audio Effects​

Audio effects and filter documentation has been moved. See Audio Effects & Filters for all usage, API, and best practices.

Voice Connection​

Voice State Management​

// Update voice state
await player.updateVoice({
channelId: 'new-channel-id',
selfDeaf: true,
selfMute: false
});

// Disconnect from voice
await player.disconnect();

// Reconnect to voice
await player.reconnect();

Voice Events​

// Voice state update
player.on('voiceStateUpdate', (state) => {
console.log('Voice state changed:', state);
});

// Voice disconnected
player.on('voiceDisconnected', (reason) => {
console.log('Disconnected:', reason);
});

Event Handling​

Playback Events​

// Track started
player.on('trackStart', (track) => {
console.log('Now playing:', track.info.title);
});

// Track ended
player.on('trackEnd', (track) => {
console.log('Finished playing:', track.info.title);
});

// Track stuck
player.on('trackStuck', (track, thresholdMs) => {
console.warn(`Track stuck for ${thresholdMs}ms`);
});

// Track error
player.on('trackError', (track, error) => {
console.error('Playback error:', error);
});

State Events​

// Player state update
player.on('stateUpdate', (oldState, newState) => {
console.log('State changed from', oldState, 'to', newState);
});

// Player destroyed
player.on('destroyed', () => {
console.log('Player cleaned up');
});

Advanced Usage​

Custom Player Options​

// Create player with custom options
const player = await yukino.createPlayer({
guildId: 'guild-id',
voiceChannelId: 'channel-id',
options: {
inactivityTimeout: 300000, // 5 minutes
volumeDecrementer: 0.75, // Reduce volume by 25%
bufferingTimeout: 5000 // 5 seconds buffer timeout
}
});

Playback Statistics​

// Get detailed stats
const stats = player.stats;
console.log('Frames sent:', stats.framesSent);
console.log('Frames nulled:', stats.framesNulled);
console.log('Frames deficit:', stats.framesDeficit);

// Monitor frame stats
player.on('stats', (stats) => {
if (stats.framesNulled > 100) {
console.warn('Poor connection quality');
}
});

Resource Management​

// Clean up resources
await player.cleanup({
removeListeners: true,
destroyQueue: true
});

// Monitor resource usage
player.on('debug', (message) => {
console.debug('[Player Debug]:', message);
});