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);
});