Migrate from v7 to v8
Update a v7 music bot in a safe order, from runtime to sources to saved data.
v8 keeps the Player, GuildQueue, Track, and Playlist you know from v7. What changes is the engine underneath: Remedia decodes audio and handles Discord voice, source plugins replace the extractor bundle, and your bot forwards gateway packets instead of passing a client.
This is a major upgrade. A v7 setup and an extractor bundle are not enough to run a v8 bot.
Migration steps
Choose where audio runs
Use Node.js 22.18 or newer with ESM. Choose an embedded or remote Remedia node. Embedded nodes need FFmpeg 9 shared libraries.
Replace Player creation
Change new Player(client) to new Player({ nodes, send, plugins }). Forward every raw gateway packet with player.receive(), then call await player.initialize(botUserId).
Move your sources
Register a definePlugin() source, or keep a supported BaseExtractor with player.extractors.register(). Not every v7 extractor package works unchanged.
Update playback controls
Use queue.node.pause(), resume(), seek(ms), setVolume(percent), and queue.node.filters. Remove old stream pipes and audio processing overrides.
Update saved data
Use serialize() and deserialize() for tracks and playlists. Register a source plugin before you play restored tracks.
Test before you ship
Run the verification checklist on a test server.
Create the Player
v7
import { Player } from 'discord-player';
import { DefaultExtractors } from '@discord-player/extractor';
const player = new Player(client);
await player.extractors.loadMulti(DefaultExtractors);v8
import { Events } from 'discord.js';
import { Player } from 'discord-player';
const player = new Player({
plugins: [mySourcePlugin()],
send: (guildId, payload) => sendToShard(guildId, payload),
});
client.on(Events.Raw, (packet) => player.receive(packet));
client.once(Events.ClientReady, (ready) => player.initialize(ready.user.id));mySourcePlugin and sendToShard are yours. See create the player and build a source plugin for complete versions.
Do not mix runtimes
Do not run an old voice or audio dispatcher next to Remedia for the same guild. Remedia owns voice, and the queue owns track order. Mixing them creates duplicate events and conflicting sessions.
More detail
API changes
What changed in constructors, queues, controls, and events.
Extractors
Keep extractors for now, or port them to plugins.
Saved data
Import v7 tracks and playlists.
Compatibility
What carries over, what changed, and what is gone.
Checklist
Verify the upgrade before production.
Continue reading
Review the API changes