This repository no longer receives updates (bug fixes or new features). If you still wanna maintain it, please fork this repository. Thank you.

An easy-to-use music extension for discord.py

• It's easy to use and can be used for complex process.
• Complete playback controls and thread-safe.
• The audio source can be used in discord.py audio library.
  • NOTE: The audio sources from discord.py cannot be played in discord-ext-music library, see Reusable audio sources

Python 3.8 or higher required.

You can install discord-ext-music stable version directly from PyPI by the following command:

pip install discord-ext-music

or by the cloning repository with latest stable version:

git clone --branch v0.3.0 https://github.com/mansuf/discord-ext-music.git
cd discord-ext-music

You also can install development version by cloning the repository, see below:

git clone https://github.com/mansuf/discord-ext-music.git
cd discord-ext-music

These are optional packages that you are not required to install it, but you get extra benefit once you install it.

• scipy and pydub for equalizer support.
• miniaudio for miniaudio music source support.
• PyAV for FFmpeg libraries music source support.

You can install all additional packages in one command:

pip install discord-ext-music[all]

basically, you can play these formats without additional packages:

• Raw PCM
• WAV

with miniaudio, you can play these formats:

• MP3
• FLAC
• All formats that vorbis encoded
• WAV

with PyAV, you can almost play anything that supported by ffmpeg libraries

Without additional packages or with miniaudio you can only play local file.

But, with PyAV you can almost play any sources that supported by ffmpeg protocols

from discord.ext.commands import Bot
from discord.ext.music import MusicClient, WAVAudio, Track

bot = Bot()

@bot.command()
async def play(ctx):
    voice_user = ctx.message.author.voice
    music_client = await voice_user.channel.connect(cls=MusicClient)
    track = Track(
        WAVAudio('audio.wav'), # AudioSource
        'This is audio' # name
    )
    await music_client.play(track)

bot.run('token')

When you're installing discord-ext-music, opus encoder already shipped with it (because of discord.py audio library). This is called native opus encoder good for compatibility and stability. But, if you want to have much better performance and low CPU usage you can use alternative opus encoder using PyAV library (by installing av package pip install av).

By default, discord-ext-music auto detect opus encoder. If you have PyAV installed, it will use PyAV opus encoder, otherwise it will use native encoder.

Alternatively, you can set environment to override opus encoder.

For windows:

# PyAV opus encoder
set OPUS_ENCODER=av

# Native opus encoder
set OPUS_ENCODER=native

For linux / Mac OS:

# PyAV opus encoder
export OPUS_ENCODER=av

# Native opus encoder
export OPUS_ENCODER=native

Because discord-ext-music is specialized for music, all audio sources in discord-ext-music are reusable. So if you call MusicClient.stop(), MusicClient.next_track(), MusicClient.previous_track(), or MusicClient.play_track_from_pos() the audio source will be recreated with same configurations (NOTE: Some audio sources are not reusable, for example: if you pass unseekable stream to RawPCMAudio or WAVAudio it will become non-reusable). And if the audio ended, the audio sources will not cleaned up, it will stay there until you removed it from playlist or reused by the library. Meanwhile, all audio sources in discord.py library are not reusable and cannot be played in MusicClient. But, the audio sources in discord-ext-music can be played in VoiceClient.

To be clear, discord-ext-music is just music extension with: playlist integrated with voice client, equalizer (if you install scipy and pydub), audio playback with thread-safe controls, and audio source that play streamable url. If you want to play youtube stream you must install additional packages like youtube-dl to extract streamable url and play it under discord-ext-music library.

• Documentation
• PyPI