Sounds Ext#
Sounds is an extension to easily play sounds on your local machine plugged directly into your bot. Sounds is currently a Beta release, and as such should be treated so.
Currently sounds supports local files and YouTube searches. See below for more details.
Sounds requires a few extra steps to get started, below is a short guide on how to get started with sounds:
Installation:
1 - First install TwitchIO with the following commands:
Windows:
py -3.9 -m pip install -U twitchio[sounds]
Linux:
python3.9 -m pip install -U twitchio[sounds]
If you are on Linux you can skip to step 3.
2 - Windows users require an extra step to get sounds working, in your console run the following commands:
py -3.9 -m pip install -U pipwin
Then:
pipwin install pyaudio
3 - If you are on windows, download ffmpeg and make sure you add it your path. You can find the .exe required in the /bin folder. Alternatively copy and paste ffmpeg.exe into your bots Working Directory.
Linux/MacOS users should use their package manager to download and install ffmpeg on their system.
Recipes#
A simple Bot with an AudioPlayer:
This bot will search YouTube for a relevant video and playback its audio.
from twitchio.ext import commands, sounds
class Bot(commands.Bot):
def __init__(self):
super().__init__(token='...', prefix='!', initial_channels=['...'])
self.player = sounds.AudioPlayer(callback=self.player_done)
async def event_ready(self) -> None:
print('Successfully logged in!')
async def player_done(self):
print('Finished playing song!')
@commands.command()
async def play(self, ctx: commands.Context, *, search: str) -> None:
track = await sounds.Sound.ytdl_search(search)
self.player.play(track)
await ctx.send(f'Now playing: {track.title}')
bot = Bot()
bot.run()
Sound with a Local File:
This Sound will target a local file on your machine. Just pass the location to source.
sound = sounds.Sound(source='my_audio.mp3')
Multiple Players:
This example shows how to setup multiple players. Useful for playing music in addition to sounds on events!
import twitchio
from twitchio.ext import commands, sounds
class Bot(commands.Bot):
def __init__(self):
super().__init__(token='...', prefix='!', initial_channels=['...'])
self.music_player = sounds.AudioPlayer(callback=self.music_done)
self.event_player = sounds.AudioPlayer(callback=self.sound_done)
async def event_ready(self) -> None:
print('Successfully logged in!')
async def music_done(self):
print('Finished playing song!')
async def sound_done(self):
print('Finished playing sound!')
@commands.command()
async def play(self, ctx: commands.Context, *, search: str) -> None:
track = await sounds.Sound.ytdl_search(search)
self.music_player.play(track)
await ctx.send(f'Now playing: {track.title}')
async def event_message(self, message: twitchio.Message) -> None:
# This is just an example only...
# Playing a sound on every message could get extremely spammy...
sound = sounds.Sound(source='beep.mp3')
self.event_player.play(sound)
bot = Bot()
bot.run()
Common AudioPlayer actions:
# Set the volume of the player...
player.volume = 50
# Pause the player...
player.pause()
# Resume the player...
player.resume()
# Stop the player...
player.stop()
# Check if the player is playing...
player.is_playing
API Reference#
- class twitchio.ext.sounds.OutputDevice(name: str, index: int, channels: int)#
Class which represents an OutputDevice usable with
AudioPlayer
.Pass this into the appropriate
AudioPlayer
method to set or change device.
- class twitchio.ext.sounds.Sound(source: Optional[Union[str, BufferedIOBase]] = None, *, info: Optional[dict] = None)#
TwitchIO Sound Source.
This is the class that represents a TwitchIO Sound, able to be played in
AudioPlayer
.Warning
This class is still in Beta stages and currently only supports generating sounds via
ytdl_search()
or locally downloaded audio files. Future versions will have support for file like objects.- Parameters
source (Optional[Union[str, io.BufferedIOBase]]) – The source to play. Could be a string representing a local file or bytes. To search YouTube, use
ytdl_search()
instead.info (Optional[dict]) – The info dict provided via ytdl. Only available when searching via YouTube. Do not pass this directly.
- title#
The title of the track. Will be None if
io.BufferedIOBase
is supplied as a source.- Type
- url#
The url of the track searched via YouTube. Will be None if source is supplied.
- Type
Optional[str]
- classmethod coroutine ytdl_search(search: str, *, loop: Optional[BaseEventLoop] = None)#
This function is a coroutine.
Search songs via YouTube ready to be played.
- property channels#
The audio source channels.
- property rate#
The audio source sample rate.
- property source#
The raw audio source.
- clsAudioPlayer.with_device
- defpause
- defplay
- defresume
- defstop
- class twitchio.ext.sounds.AudioPlayer(*, callback: Callable[[...], Coroutine[Any, Any, None]])#
TwitchIO Sounds Audio Player.
Use this class to control and play sounds generated with
Sound
.- Parameters
callback (Coroutine) – The coroutine called when a Sound has finished playing.
Note
To use this player with the system non default output device, see
with_device()
, oractive_device
. The output device can be changed live by setting active_device with anOutputDevice
.- pause()#
Method which pauses the player.
- play(sound: Sound, *, replace: bool = False) None #
Play a
Sound
object.When play has finished playing, the event
event_player_finished()
is called.
- resume()#
Method which resumes the player.
- stop()#
Stops the player and clears the source.
- classmethod with_device(*, callback: Callable[[...], Coroutine[Any, Any, None]], device: OutputDevice) AP #
Method which returns a player ready to be used with the given
OutputDevice
.- Returns
- property active_device: Optional[OutputDevice]#
Return the active output device for this player. Could be None if default is being used.
This property can also be set with a new
OutputDevice
to change audio output.
- property devices: Dict[int, OutputDevice]#
Return a dict of
OutputDevice
that can be used to output audio.
- property is_playing#
Property which returns whether the player is currently playing.