Kazagumo Autoplay

Advanced autoplay system for Kazagumo/Shoukaku Discord music bots with intelligent track recommendations. Check the examples on the GitHub Repo, No proper documentation available rn. https://github.com/WannaBeGhoSt/kazagumo-autoplay

Features

• Smart YouTube autoplay based on listening history
• Intelligent track prefetching for seamless playback
• Built-in caching system to reduce API calls
• Seed-based recommendations using manual track history
• Per-guild statistics and state management

Installation

npm install kazagumo-autoplay

Command Examples

Basic Autoplay Toggle Command

client.on('messageCreate', async (message) => {
  if (message.content === '!autoplay') {
    const guildId = message.guild.id;
    const player = kazagumo.players.get(guildId);
    
    if (!player) {
      return message.reply('No active player in this guild!');
    }
    

    const newStatus = autoplay.toggle(guildId);
    
    message.reply(`Autoplay is now **${newStatus ? 'enabled' : 'disabled'}**!`);
  }
});

Advanced Command with Slash Commands

const { SlashCommandBuilder } = require('discord.js');


const autoplayCommand = new SlashCommandBuilder()
  .setName('autoplay')
  .setDescription('Manage autoplay settings')
  .addSubcommand(subcommand =>
    subcommand
      .setName('toggle')
      .setDescription('Toggle autoplay on/off')
  )
  .addSubcommand(subcommand =>
    subcommand
      .setName('status')
      .setDescription('Check autoplay status')
  )
  .addSubcommand(subcommand =>
    subcommand
      .setName('stats')
      .setDescription('View autoplay statistics')
  );


client.on('interactionCreate', async (interaction) => {
  if (!interaction.isChatInputCommand()) return;
  if (interaction.commandName !== 'autoplay') return;
  
  const guildId = interaction.guild.id;
  const player = kazagumo.players.get(guildId);
  
  if (!player) {
    return interaction.reply({
      content: '❌ No active player found!',
      ephemeral: true
    });
  }
  
  const subcommand = interaction.options.getSubcommand();
  
  if (subcommand === 'toggle') {
    const newStatus = autoplay.toggle(guildId);
    
    await interaction.reply({
      embeds: [{
        color: newStatus ? 0x00ff00 : 0xff0000,
        title: '🎵 Autoplay',
        description: `Autoplay is now **${newStatus ? 'enabled' : 'disabled'}**!`,
        footer: { text: 'Autoplay will queue similar songs automatically' }
      }]
    });
  }
  
  else if (subcommand === 'status') {
    const isEnabled = autoplay.isEnabled(guildId);
    
    await interaction.reply({
      embeds: [{
        color: isEnabled ? 0x00ff00 : 0xff0000,
        title: '🎵 Autoplay Status',
        description: `Autoplay is currently **${isEnabled ? 'enabled ✅' : 'disabled ❌'}**`,
        timestamp: new Date()
      }]
    });
  }
  
  else if (subcommand === 'stats') {
    const stats = autoplay.getStats(guildId);
    
    await interaction.reply({
      embeds: [{
        color: 0x0099ff,
        title: '📊 Autoplay Statistics',
        fields: [
          {
            name: 'Status',
            value: stats.enabled ? '✅ Enabled' : '❌ Disabled',
            inline: true
          },
          {
            name: 'Cached Tracks',
            value: `${stats.cacheSize} tracks`,
            inline: true
          },
          {
            name: 'History Size',
            value: `${stats.historyLength} tracks`,
            inline: true
          },
          {
            name: 'Seed Tracks',
            value: stats.seeds.length > 0 ? `${stats.seeds.length} tracks` : 'None',
            inline: true
          }
        ],
        timestamp: new Date()
      }]
    });
  }
});

API Reference

Constructor

new KazagumoAutoplay(kazagumo, options)

Parameters:

• kazagumo - Kazagumo instance (required)
• options - Configuration object
  • client - Discord.js client instance (required for notifications)
  • cacheSize - Number of tracks to prefetch (default: 6)
  • historySize - Maximum autoplay history per guild (default: 50)
  • enableNotifications - Send autoplay notifications (default: true)
  • fetchTimeout - YouTube fetch timeout in ms (default: 8000)
  • autoplayLockDuration - Lock duration to prevent race conditions (default: 5000)

Methods

enable(guildId)

Enable autoplay for a guild.

• Returns: boolean - Returns true if autoplay was just enabled

disable(guildId)

Disable autoplay for a guild.

• Returns: boolean - Returns true if autoplay was previously enabled

toggle(guildId)

Toggle autoplay status for a guild.

• Returns: boolean - New autoplay status

isEnabled(guildId)

Check if autoplay is enabled for a guild.

• Returns: boolean - Current autoplay status

getStats(guildId)

Get autoplay statistics for a guild.

• Returns: Object - Statistics object with enabled, historyLength, cacheSize, and seeds

cleanupGuildState(guildId)

Clean up all autoplay state for a guild (useful when player is destroyed).

Events

The autoplay system extends EventEmitter and emits the following events:

ready

Emitted when the autoplay system is initialized and ready.

autoplay.on('ready', () => {
  console.log('Autoplay ready!');
});

autoplayEnabled

Emitted when autoplay is enabled for a guild.

autoplay.on('autoplayEnabled', (guildId) => {
  console.log(`Autoplay enabled in ${guildId}`);
});

autoplayDisabled

Emitted when autoplay is disabled for a guild.

autoplay.on('autoplayDisabled', (guildId) => {
  console.log(`Autoplay disabled in ${guildId}`);
});

trackAdded

Emitted when a track is added via autoplay.

autoplay.on('trackAdded', (player, track) => {
  console.log(`Added ${track.title} to ${player.guildId}`);
});

trackStart

Emitted when a track starts playing (mirrors Kazagumo playerStart).

autoplay.on('trackStart', (player, track) => {
  console.log(`Now playing: ${track.title}`);
});

noTracksFound

Emitted when no suitable autoplay tracks are found.

autoplay.on('noTracksFound', (player) => {
  console.log(`No tracks found for ${player.guildId}`);
});

error

Emitted when an error occurs.

autoplay.on('error', (error, context) => {
  console.error(`Error in ${context}:`, error);
});

guildCleanup

Emitted when guild state is cleaned up.

autoplay.on('guildCleanup', (guildId) => {
  console.log(`Cleaned up state for ${guildId}`);
});

How It Works

1. Seed Track Recording

The system automatically records manually played tracks as "seeds" for recommendations:

• Initial seed: First manually played track
• Recent seeds: Up to 2 most recent different tracks

2. Recommendation Algorithm

When the queue ends and autoplay is enabled:

1. Check prefetched cache for available tracks
2. Fetch YouTube autoplay recommendations (RD list)
3. Weight tracks based on overlap with previous track recommendations
4. Filter out already played tracks
5. Shuffle and select the best candidate

3. Intelligent Caching

• Prefetches tracks in the background while music is playing
• Reduces latency when queue ends
• Uses multiple seeds for diverse recommendations
• Automatically maintains cache size

4. Fallback System

If no recommendations are found:

1. Search for "songs by [artist]"
2. Search for "similar to [title]"
3. If still nothing found, disconnect player

Configuration Tips

High Activity Bot

const autoplay = new KazagumoAutoplay(kazagumo, {
  client: client,
  cacheSize: 10,           // More cached tracks
  historySize: 100,        // Larger history
  fetchTimeout: 6000       // Faster timeout
});

Resource-Constrained Bot

const autoplay = new KazagumoAutoplay(kazagumo, {
  client: client,
  cacheSize: 3,            // Fewer cached tracks
  historySize: 25,         // Smaller history
  fetchTimeout: 10000      // More lenient timeout
});

Silent Mode (No Notifications)

const autoplay = new KazagumoAutoplay(kazagumo, {
  client: client,
  enableNotifications: false  // No autoplay messages
});

Requirements

• Node.js 16.0.0 or higher
• Kazagumo 2.x or 3.x
• Discord.js 14.x
• Active Lavalink server

License

MIT

Support

If you encounter any issues or have any questions, open an issue on GitHub Discord Server: https://discord.gg/4KUYQ5GNcK

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.