Queue
The Queue system in Yukino manages the order and playback sequence of tracks. It provides features for track management, shuffling, and repeat modes.
Queue Structure
A queue in Yukino has these key components:
- Current track
- Track history
- Upcoming tracks
- Loop mode
- Shuffle state
Queue Events and Player Integration
Note: All queue events (such as
trackAdd,trackRemove,shuffle, etc.) are also re-emitted by the Player instance that owns the queue. This means you can listen for queue events directly on the Player:player.on('queue:trackAdd', (track, position) => {
// Handle track added to queue
});Or, if you prefer, you can listen on the queue itself:
queue.on('trackAdd', (track, position) => { ... });This makes it easy to react to queue changes at the Player level, which is useful for bots and integrations.
Basic Operations
Adding Tracks
// Add a single track
queue.add(track);
// Add multiple tracks
queue.addMany([track1, track2, track3]);
// Add track at specific position
queue.add(track, { position: 2 });
// Add with options
queue.add(track, {
position: 0, // Position in queue
immediate: true, // Play immediately
unshift: true // Add to start of queue
});
Removing Tracks
// Remove by position
queue.remove(0);
// Remove range
queue.remove(0, 3); // Remove first 3 tracks
// Remove by predicate
queue.remove(track => track.info.length > 600000); // Remove tracks > 10min
// Clear queue
queue.clear();
Queue Navigation
Track Access
// Get current track
const current = queue.current;
// Get next track
const next = queue.next;
// Get previous track
const previous = queue.previous;
// Get track at position
const track = queue.at(2);
Queue Information
// Get queue length
console.log('Tracks in queue:', queue.length);
// Get queue duration
console.log('Total duration:', queue.duration);
// Check if queue has tracks
console.log('Has tracks:', queue.hasTrack);
console.log('Is empty:', queue.isEmpty);
Queue Manipulation
Reordering
// Move track
queue.move(0, 2); // Move first track to third position
// Swap tracks
queue.swap(1, 3); // Swap second and fourth tracks
// Reverse queue
queue.reverse();
Shuffling
// Shuffle entire queue
queue.shuffle();
// Shuffle range
queue.shuffle(0, 5); // Shuffle first 5 tracks
// Shuffle with options
queue.shuffle(undefined, {
startFrom: 1, // Start shuffling from second track
preserveFirst: true // Keep first track in place
});
Loop Modes
Setting Loop Mode
// Set loop mode
queue.setLoop('none'); // No looping
queue.setLoop('track'); // Loop current track
queue.setLoop('queue'); // Loop entire queue
// Check current loop mode
console.log('Loop mode:', queue.loop);
Loop Behavior
// Track loop example
queue.on('trackEnd', () => {
if (queue.loop === 'track') {
// Current track will automatically replay
console.log('Replaying:', queue.current.info.title);
}
});
// Queue loop example
queue.on('queueEnd', () => {
if (queue.loop === 'queue') {
// Queue will automatically restart
console.log('Restarting queue');
}
});
History Management
Track History
// Get history
const history = queue.history;
// Get last played track
const lastPlayed = queue.history.last;
// Get specific track from history
const trackFromHistory = queue.history.at(-2); // Second to last track
// Clear history
queue.history.clear();
Navigation Through History
// Go back to previous track
queue.previous();
// Go forward if available
queue.next();
// Check if navigation is possible
console.log('Can go back:', queue.canGoBack);
console.log('Can go forward:', queue.canGoForward);
Advanced Features
Queue Filtering
// Filter tracks
const filtered = queue.filter(track =>
track.info.length < 300000 // Filter songs under 5 minutes
);
// Find tracks
const found = queue.find(track =>
track.info.title.includes('keyword')
);
// Map tracks
const titles = queue.map(track => track.info.title);
Queue Events
// Track added
queue.on('trackAdd', (track, position) => {
console.log(`Added ${track.info.title} at position ${position}`);
});
// Track removed
queue.on('trackRemove', (track, position) => {
console.log(`Removed ${track.info.title} from position ${position}`);
});
// Queue shuffled
queue.on('shuffle', () => {
console.log('Queue has been shuffled');
});
State Management
// Save queue state
const state = queue.save();
// Load queue state
queue.load(state);
// Reset queue
queue.reset();
Custom Sorting
// Sort by duration
queue.sort((a, b) => a.info.length - b.info.length);
// Sort by title
queue.sort((a, b) => a.info.title.localeCompare(b.info.title));
// Sort with custom criteria
queue.sort((a, b) => {
const weightA = getTrackWeight(a);
const weightB = getTrackWeight(b);
return weightA - weightB;
});
Performance Optimization
Batch Operations
// Batch add tracks
queue.transaction(() => {
tracks.forEach(track => queue.add(track));
});
// Batch remove tracks
queue.transaction(() => {
tracksToRemove.forEach(track => queue.remove(track));
});
Memory Management
// Trim history to save memory
queue.history.trim(10); // Keep only last 10 tracks
// Clear unused resources
queue.cleanup();