Autoplay System

Ryanlink includes a built-in Autoplay class that automatically finds and queues similar tracks when the queue empties. It uses a multi-source fetch chain with weighted scoring to pick the best match.

Enabling Autoplay

Autoplay is triggered via the onEmptyQueue.autoPlayFunction option. Set player.autoplay = true to activate it per-player:

import { RyanlinkManager, Autoplay } from 'ryanlink';

const manager = new RyanlinkManager({
  playerOptions: {
    onEmptyQueue: {
      autoPlayFunction: async (player, lastTrack) => {
        if (!player.autoplay) return;
        await Autoplay.defaultAutoplay(player, lastTrack);
      },
      destroyAfterMs: 20000, // leave VC after 20s if queue empty and autoplay off
    },
  },
});

// Enable per-player
player.autoplay = true;

// Disable
player.autoplay = false;

---

AutoplayConfig Options

Fine-tune the selection algorithm via playerOptions.autoplayConfig:

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | enabled | boolean | true | Whether the built-in Autoplay class is active | | defaultSource | string | 'ytsearch' | Fallback search source | | limit | number | 1 | Tracks to add per autoplay trigger | | minDuration | number | 20000 | Minimum track duration (ms) | | maxDuration | number | 900000 | Maximum track duration (ms) | | durationTolerance | number | 90000 | Max delta (ms) between last track and candidate for full duration score | | historyLimit | number | 20 | Circular buffer size — tracks in this buffer are never re-queued | | prefetchThreshold | number | 1 | Trigger autoplay early when queue drops to this many tracks | | excludeKeywords | string[] | See below | Keyword blacklist applied to track titles | | fetchRelatedTracks | function | undefined | Custom async function to fetch candidates: (player, lastTrack) => Promise<Track[]> |

Default excluded keywords: nightcore, bass boosted, 8d audio, slowed, reverb, bass boost, pitch shift, speed up, sped up.

const manager = new RyanlinkManager({
  playerOptions: {
    autoplayConfig: {
      limit: 1,
      minDuration: 20000,
      maxDuration: 900000,
      durationTolerance: 90000,
      historyLimit: 20,
      prefetchThreshold: 1,
      excludeKeywords: ['nightcore', 'slowed', 'reverb', '8d'],
    },
  },
});

---

How Selection Works

1. Multi-Source Fetch Chain

The engine tries sources in order until enough candidates are found:

1. YouTube — ytrec:{identifier} recommendation query (if source is YouTube and track is not a stream)
2. Spotify — sprec:seed_artists={artistId}&seed_tracks={trackId} (if Spotify IDs are available)
3. Same-artist search — {source}search:{artist} on the native source
4. Title+artist search — {source}search:{title} {artist} on the native source
5. Final fallback — ytsearch:{artist} search

2. Weighted Scoring

Each candidate is scored (higher = better):

| Factor | Points | | :--- | :--- | | Duration within durationTolerance | 0–40 | | Same artist (exact match) | +50 | | Partial artist match | +25 | | Random jitter | 0–10 |

Candidates are sorted by score descending. The top limit tracks are selected.

3. Filtering

Before scoring, candidates are filtered out if:

• Their identifier is in the history buffer
• Their ISRC is in the history buffer
• Their normalized title is in the history buffer
• Their title contains an excluded keyword
• Their normalized title matches the last track’s normalized title
• Their duration is outside [minDuration, maxDuration]

4. Circular History Buffer

Track identifiers are stored in a per-player buffer (autoplay_history_buf). Any track in this buffer is hard-excluded from selection. The buffer is capped at historyLimit entries and synced with player.recentHistory.

5. Pre-fetch

When queue.tracks.length <= prefetchThreshold, autoplay triggers early — the next track is resolved and queued before the current one ends, eliminating the silence gap.

---

Custom Fetch Function

Override the entire candidate-fetching logic:

const manager = new RyanlinkManager({
  playerOptions: {
    autoplayConfig: {
      fetchRelatedTracks: async (player, lastTrack) => {
        // Return an array of Track objects
        const result = await player.search(
          { query: `${lastTrack.info.author} radio`, source: 'ytsearch' },
          'Autoplay'
        );
        return result.tracks;
      },
    },
  },
});

---

Keyword Exclusion

Keywords are matched case-insensitively against the candidate’s title. The last track’s own keywords are not used to filter candidates.

autoplayConfig: {
  excludeKeywords: ['nightcore', 'bass boosted', '8d audio', 'slowed', 'reverb'],
}

---

Runtime Toggle

player.autoplay = true;   // enable
player.autoplay = false;  // disable

The autoplay flag is also settable via createPlayer:

const player = manager.createPlayer({
  guildId: '...',
  voiceChannelId: '...',
  autoplay: true,
});