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

Attributes

• channels
• index
• name

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.

name

The name of the device.

Type

str

index

The index of the device.

Type

int

channels

The amount of available channels this device has.

Type

int

Attributes

• channels
• rate
• source
• title
• url

Methods

• clsSound.ytdl_search

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

str

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.

Attributes

• active_device
• current
• devices
• is_paused
• is_playing
• source
• volume

Methods

• 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(), or active_device. The output device can be changed live by setting active_device with an OutputDevice.

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

OutputDevice

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 current

An alias to source().

property devices: Dict[int, OutputDevice]

Return a dict of OutputDevice that can be used to output audio.

property is_paused: bool

Property which returns whether the player is currently paused.

property is_playing

Property which returns whether the player is currently playing.

property source

The currently playing Sound object.

property volume: int

Property which returns the current volume.

This property can also be set with a volume between 1 and 100, to change the volume.