Voice API

This page assumes you’ve completed Creating a Simple Hello World Module. If not, check the previous pages.

If you want play some nice beats on your voice channels, you can use the voice API.

Connecting To A Channel

To connect to a channel, create a new VoiceManager instance and call connect:

vm = VoiceManager(self.client, message.author.voice_channel)

Playing Audio

There are two functions that deal with actually sending audio to Discord: play_file and play_url:

await vm.play_file("test.mp3")
await vm.play_url("https://www.youtube.com/watch?v=63qtYi1nwcs")

Music Queues & YouTube Playlists


The playlist parts of the voice API (Especially with YouTube interaction) can be inconsistent, slow and unreliable. Proceed with caution.

To support both music queues and YouTube playlists, the PlaylistManager wrapper must be used:

pm = PlaylistManager(vm)

Adding Music To Playlist

To add music to the playlist simply use the add function:

pm.add(PlaylistType.URL, "https://www.youtube.com/watch?v=dQw4w9WgXcQ")

Importing Playlists From YouTube

To import a playlist from YouTube, use import_from:

await pm.import_from("https://www.youtube.com/playlist?list=PLOy0j9AvlVZPto6IkjKfpu0Scx--7PGTC")


Importing a playlist from YouTube can take a long time depending on the video count and your internet speed as all videos metadata need to be downloaded before import.

YouTube Searches

To add a video from a YouTube search, use search_and_add:

await pm.search_and_add("streets agent 112")


Searching on YouTube can take a some time depending on your internet speed as the search must happen and metadata need to be downloaded before import.

Music Control

When using PlaylistManager, there are some music control functions that need to be ran from the PlaylistManager instead of the VoiceManager. These are play, stop and skip:

await pm.play()

Doing Something When A Playlist Item Starts Playing

To do something when a playlist item starts playing, use the callback argument:

def on_play(self, m: discord.Message):
    async def actual_on_play():
        pm: PlaylistManager = get_pm_from_somewhere(m.server.id)

        if not pm.voice.is_player_ytdl:
            # Non-YTDL players don't have as much information. This is a discord.py
            # Thing.
            await self.client.send_message(m.channel, embed=success_embed(
                title="Started playing!"

        e = discord.Embed(

        await self.client.send_message(m.channel, embed=e)

    return actual_on_play

await pm.play(callback=self.on_play(message))