Skip to main content

​
AudioSource

Base class representing an audio stream. The audio stream can be Opus encoded or not, however if the audio stream is not Opus encoded then the audio format must be 16-bit 48KHz stereo PCM.
The audio source reads are done in a separate thread.

​
Methods

​
read

read() -> bytes
Reads 20ms worth of audio. Subclasses must implement this. If the audio is complete, then returning an empty bytes-like object to signal this is the way to do so. If is_opus() method returns True, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio). Returns: bytes - A bytes like object that represents the PCM or Opus data.

​
is_opus

is_opus() -> bool
Checks if the audio source is already encoded in Opus. Returns: bool - Whether the audio is Opus encoded.

​
cleanup

cleanup() -> None
Called when clean-up is needed to be done. Useful for clearing buffer data or processes after it is done playing audio.

​
PCMAudio

Represents raw 16-bit 48KHz stereo PCM audio source.

​
Attributes

​
stream
file object
A file-like object that reads byte data representing raw PCM.

​
Constructor

PCMAudio(stream: io.BufferedIOBase)
​
stream
io.BufferedIOBase
required
A file-like object that reads byte data representing raw PCM.

​
Example

import discord
import io

# Read PCM data from a file
with open('audio.pcm', 'rb') as f:
    source = discord.PCMAudio(f)
    voice_client.play(source)

​
FFmpegPCMAudio

An audio source from FFmpeg (or AVConv). This launches a sub-process to a specific input file given.
You must have the ffmpeg or avconv executable in your path environment variable in order for this to work.

​
Constructor

FFmpegPCMAudio(
    source: str | io.BufferedIOBase,
    *,
    executable: str = "ffmpeg",
    pipe: bool = False,
    stderr: Optional[file object] = None,
    before_options: Optional[str] = None,
    options: Optional[str] = None
)
​
source
Union[str, io.BufferedIOBase]
required
The input that ffmpeg will take and convert to PCM bytes. If pipe is True then this is a file-like object that is passed to the stdin of ffmpeg.
​
executable
str
default:"ffmpeg"
The executable name (and path) to use. Defaults to ffmpeg.
​
pipe
bool
default:"False"
If True, denotes that source parameter will be passed to the stdin of ffmpeg.
​
stderr
Optional[file object]
A file-like object to pass to the Popen constructor. Could also be an instance of subprocess.PIPE.
​
before_options
Optional[str]
Extra command line arguments to pass to ffmpeg before the -i flag.
​
options
Optional[str]
Extra command line arguments to pass to ffmpeg after the -i flag.
Raises:
  • ClientException - The subprocess failed to be created.

​
Example

import discord

# Play from a URL
source = discord.FFmpegPCMAudio('https://example.com/audio.mp3')
voice_client.play(source)

# Play from a local file
source = discord.FFmpegPCMAudio('path/to/audio.mp3')
voice_client.play(source)

# With custom options
source = discord.FFmpegPCMAudio(
    'audio.mp3',
    before_options='-reconnect 1 -reconnect_streamed 1 -reconnect_delay_max 5'
)
voice_client.play(source)

​
FFmpegOpusAudio

An audio source from FFmpeg (or AVConv). This launches a sub-process to a specific input file given. However, rather than producing PCM packets like FFmpegPCMAudio does that need to be encoded to Opus, this class produces Opus packets, skipping the encoding step done by the library. Alternatively, instead of instantiating this class directly, you can use FFmpegOpusAudio.from_probe() to probe for bitrate and codec information. This can be used to opportunistically skip pointless re-encoding of existing Opus audio data for a boost in performance at the cost of a short initial delay to gather the information.
You must have the ffmpeg or avconv executable in your path environment variable in order for this to work.

​
Constructor

FFmpegOpusAudio(
    source: str | io.BufferedIOBase,
    *,
    bitrate: int = 128,
    codec: Optional[str] = None,
    executable: str = "ffmpeg",
    pipe: bool = False,
    stderr: Optional[file object] = None,
    before_options: Optional[str] = None,
    options: Optional[str] = None
)
​
source
Union[str, io.BufferedIOBase]
required
The input that ffmpeg will take and convert to Opus bytes. If pipe is True then this is a file-like object that is passed to the stdin of ffmpeg.
​
bitrate
int
default:"128"
The bitrate in kbps to encode the output to. Defaults to 128.
​
codec
Optional[str]
The codec to use to encode the audio data. Normally this would be just libopus, but is used by FFmpegOpusAudio.from_probe() to opportunistically skip pointlessly re-encoding Opus audio data by passing copy as the codec value. Any values other than copy, or libopus will be considered libopus.
​
executable
str
default:"ffmpeg"
The executable name (and path) to use. Defaults to ffmpeg.
​
pipe
bool
default:"False"
If True, denotes that source parameter will be passed to the stdin of ffmpeg.
​
stderr
Optional[file object]
A file-like object to pass to the Popen constructor. Could also be an instance of subprocess.PIPE.
​
before_options
Optional[str]
Extra command line arguments to pass to ffmpeg before the -i flag.
​
options
Optional[str]
Extra command line arguments to pass to ffmpeg after the -i flag.
Raises:
  • ClientException - The subprocess failed to be created.

​
Class Methods

​
from_probe

await from_probe(
    source: str,
    *,
    method: Optional[Union[str, Callable]] = None,
    **kwargs
) -> FFmpegOpusAudio
A factory method that creates a FFmpegOpusAudio after probing the input source for audio codec and bitrate information.
​
source
str
required
The input source to probe and play.
​
method
Optional[Union[str, Callable]]
The probing method used to determine bitrate and codec information. As a string, valid values are native to use ffprobe (or avprobe) and fallback to use ffmpeg (or avconv). As a callable, it must take two string arguments, source and executable.
​
**kwargs
The remaining parameters to be passed to the FFmpegOpusAudio constructor, excluding bitrate and codec.
Returns: FFmpegOpusAudio - An instance of this class. Raises:
  • AttributeError - Invalid probe method, must be ‘native’ or ‘fallback’.
  • TypeError - Invalid value for probe parameter, must be str or a callable.
Example: 
source = await discord.FFmpegOpusAudio.from_probe("song.webm")
voice_client.play(source)

​
probe

await probe(
    source: str,
    *,
    method: Optional[Union[str, Callable]] = None,
    executable: Optional[str] = None
) -> Tuple[Optional[str], Optional[int]]
Probes the input source for bitrate and codec information.
​
source
str
required
The input source to probe.
​
method
Optional[Union[str, Callable]]
Identical to the method parameter for from_probe.
​
executable
Optional[str]
The executable name to use. Defaults to ffmpeg.
Returns: Tuple[Optional[str], Optional[int]] - A 2-tuple with the codec and bitrate of the input source. Raises:
  • AttributeError - Invalid probe method.
  • TypeError - Invalid value for probe parameter.

​
Example

import discord

# Basic usage
source = discord.FFmpegOpusAudio('audio.mp3')
voice_client.play(source)

# With probing for optimal performance
source = await discord.FFmpegOpusAudio.from_probe('song.webm')
voice_client.play(source)

# Using fallback method on Windows without ffprobe
source = await discord.FFmpegOpusAudio.from_probe(
    'song.webm',
    method='fallback'
)
voice_client.play(source)

​
PCMVolumeTransformer

Transforms a previous AudioSource to have volume controls. This does not work on audio sources that have AudioSource.is_opus() set to True.

​
Constructor

PCMVolumeTransformer(original: AudioSource, volume: float = 1.0)
​
original
AudioSource
required
The original AudioSource to transform.
​
volume
float
default:"1.0"
The initial volume to set it to. See volume property for more info.
Raises:
  • TypeError - Not an audio source.
  • ClientException - The audio source is opus encoded.

​
Properties

​
volume
float
Retrieves or sets the volume as a floating point percentage (e.g. 1.0 for 100%).
​
original
AudioSource
The original audio source being transformed.

​
Example

import discord

# Create a volume-controllable source
source = discord.FFmpegPCMAudio('audio.mp3')
source = discord.PCMVolumeTransformer(source)

# Set volume to 50%
source.volume = 0.5

voice_client.play(source)

# Change volume while playing
source.volume = 0.75

Build docs developers (and LLMs) love

Get started for freeTalk to us