Pomice

Enums

class pomice.enums.SearchType(value)

Bases: enum.Enum

The enum for the different search types for Pomice. This feature is exclusively for the Spotify search feature of Pomice. If you are not using this feature, this class is not necessary.

SearchType.ytsearch searches using regular Youtube, which is best for all scenarios.

SearchType.ytmsearch searches using YouTube Music, which is best for getting audio-only results.

SearchType.scsearch searches using SoundCloud, which is an alternative to YouTube or YouTube Music.

scsearch = 'scsearch'
ytmsearch = 'ytmsearch'
ytsearch = 'ytsearch'

Events

class pomice.events.PomiceEvent

Bases: object

The base class for all events dispatched by a node. Every event must be formatted within your bot’s code as a listener. i.e: If you want to listen for when a track starts, the event would be: `py @bot.listen async def on_pomice_track_start(self, event): `

dispatch(bot: Union[discord.ext.commands.bot.AutoShardedBot, discord.shard.AutoShardedClient, discord.ext.commands.bot.Bot, discord.client.Client])
handler_args = ()
name = 'event'
class pomice.events.TrackEndEvent(data: dict)

Bases: pomice.events.PomiceEvent

Fired when a track has successfully ended. Returns the player associated with the event along with the pomice.Track object and reason.

name = 'track_end'
class pomice.events.TrackExceptionEvent(data: dict)

Bases: pomice.events.PomiceEvent

Fired when a track error has occured. Returns the player associated with the event along with the error code and exception.

name = 'track_exception'
class pomice.events.TrackStartEvent(data: dict)

Bases: pomice.events.PomiceEvent

Fired when a track has successfully started. Returns the player associated with the event and the pomice.Track object.

name = 'track_start'
class pomice.events.TrackStuckEvent(data: dict)

Bases: pomice.events.PomiceEvent

Fired when a track is stuck and cannot be played. Returns the player associated with the event along with the pomice.Track object to be further parsed by the end user.

name = 'track_stuck'
class pomice.events.WebSocketClosedEvent(data: dict)

Bases: pomice.events.PomiceEvent

Fired when a websocket connection to a node has been closed. Returns the reason and the error code.

name = 'websocket_closed'
class pomice.events.WebSocketClosedPayload(data: dict)

Bases: object

class pomice.events.WebSocketOpenEvent(data: dict)

Bases: pomice.events.PomiceEvent

Fired when a websocket connection to a node has been initiated. Returns the target and the session SSRC.

name = 'websocket_open'

Exceptions

exception pomice.exceptions.FilterInvalidArgument

Bases: pomice.exceptions.PomiceException

An invalid argument was passed to a filter.

exception pomice.exceptions.InvalidSpotifyClientAuthorization

Bases: pomice.exceptions.PomiceException

No Spotify client authorization was provided for track searching.

exception pomice.exceptions.NoNodesAvailable

Bases: pomice.exceptions.PomiceException

There are no nodes currently available.

exception pomice.exceptions.NodeConnectionClosed

Bases: pomice.exceptions.NodeException

The node’s connection is closed.

exception pomice.exceptions.NodeConnectionFailure

Bases: pomice.exceptions.NodeException

There was a problem while connecting to the node.

exception pomice.exceptions.NodeCreationError

Bases: pomice.exceptions.NodeException

There was a problem while creating the node.

exception pomice.exceptions.NodeException

Bases: Exception

Base exception for nodes.

exception pomice.exceptions.NodeNotAvailable

Bases: pomice.exceptions.PomiceException

The node is currently unavailable.

exception pomice.exceptions.PomiceException

Bases: Exception

Base of all Pomice exceptions.

exception pomice.exceptions.SpotifyAlbumLoadFailed

Bases: pomice.exceptions.PomiceException

The pomice Spotify client was unable to load an album.

exception pomice.exceptions.SpotifyPlaylistLoadFailed

Bases: pomice.exceptions.PomiceException

The pomice Spotify client was unable to load a playlist.

exception pomice.exceptions.SpotifyTrackLoadFailed

Bases: pomice.exceptions.PomiceException

The pomice Spotify client was unable to load a track.

exception pomice.exceptions.TrackInvalidPosition

Bases: pomice.exceptions.PomiceException

An invalid position was chosen for a track.

exception pomice.exceptions.TrackLoadError

Bases: pomice.exceptions.PomiceException

There was an error while loading a track.

Filters

class pomice.filters.ChannelMix(*, left_to_left: float = 1, right_to_right: float = 1, left_to_right: float = 0, right_to_left: float = 0)

Bases: pomice.filters.Filter

Filter which manually adjusts the panning of the audio, which can make for some cool effects when done correctly.

class pomice.filters.Distortion(*, sin_offset: float = 0, sin_scale: float = 1, cos_offset: float = 0, cos_scale: float = 1, tan_offset: float = 0, tan_scale: float = 1, offset: float = 0, scale: float = 1)

Bases: pomice.filters.Filter

Filter which generates a distortion effect. Useful for certain filter implementations where distortion is needed.

class pomice.filters.Equalizer(*, levels: list)

Bases: object

Filter which represents a 15 band equalizer. You can adjust the dynamic of the sound using this filter. i.e: Applying a bass boost filter to emphasize the bass in a song. The format for the levels is: List[Tuple[int, float]]

class pomice.filters.Filter

Bases: object

class pomice.filters.Karaoke(*, level: float = 1.0, mono_level: float = 1.0, filter_band: float = 220.0, filter_width: float = 100.0)

Bases: pomice.filters.Filter

Filter which filters the vocal track from any song and leaves the instrumental. Best for karaoke as the filter implies.

class pomice.filters.LowPass(*, smoothing: float = 20)

Bases: pomice.filters.Filter

Filter which supresses higher frequencies and allows lower frequencies to pass. You can also do this with the Equalizer filter, but this is an easier way to do it.

class pomice.filters.Rotation(*, rotation_hertz: float = 5)

Bases: pomice.filters.Filter

Filter which produces a stereo-like panning effect, which sounds like the audio is being rotated around the listener’s head

class pomice.filters.Timescale(*, speed: float = 1.0, pitch: float = 1.0, rate: float = 1.0)

Bases: pomice.filters.Filter

Filter which changes the speed and pitch of a track. Do be warned that this filter is bugged as of the lastest Lavalink dev version due to the filter patch not corresponding with the track time.

In short this means that your track will either end prematurely or end later due to this. This is not the library’s fault.

class pomice.filters.Tremolo(*, frequency: float = 2.0, depth: float = 0.5)

Bases: pomice.filters.Filter

Filter which produces a wavering tone in the music, causing it to sound like the music is changing in volume rapidly.

class pomice.filters.Vibrato(*, frequency: float = 2.0, depth: float = 0.5)

Bases: pomice.filters.Filter

Filter which produces a wavering tone in the music, similar to the Tremolo filter, but changes in pitch rather than volume.

Objects

class pomice.objects.Playlist(*, playlist_info: dict, tracks: list, ctx: Optional[discord.ext.commands.context.Context] = None, spotify: bool = False, thumbnail: Optional[str] = None, uri: Optional[str] = None)

Bases: object

The base playlist object. Returns critical playlist information needed for parsing by Lavalink. You can also pass in commands.Context to get a discord.py Context object in your tracks.

property thumbnail: Optional[str]

Spotify album/playlist thumbnail, or None if not a Spotify object.

property uri: Optional[str]

Spotify album/playlist URI, or None if not a Spotify object.

class pomice.objects.Track(*, track_id: str, info: dict, ctx: Optional[discord.ext.commands.context.Context] = None, spotify: bool = False, search_type: pomice.enums.SearchType = SearchType.ytsearch)

Bases: object

The base track object. Returns critical track information needed for parsing by Lavalink. You can also pass in commands.Context to get a discord.py Context object in your track.

Player

class pomice.player.Player(client: Optional[Union[discord.ext.commands.bot.AutoShardedBot, discord.shard.AutoShardedClient, discord.ext.commands.bot.Bot, discord.client.Client]] = None, channel: Optional[discord.channel.VoiceChannel] = None, **kwargs)

Bases: discord.voice_client.VoiceProtocol

The base player class for Pomice. In order to initiate a player, you must pass it in as a cls when you connect to a channel. i.e: `py await ctx.author.voice.channel.connect(cls=pomice.Player) `

property bot: Union[discord.ext.commands.bot.AutoShardedBot, discord.shard.AutoShardedClient, discord.ext.commands.bot.Bot, discord.client.Client]

Property which returns the bot associated with this player instance

async connect(*, timeout: float, reconnect: bool)

|coro|

An abstract method called when the client initiates the connection request.

When a connection is requested initially, the library calls the constructor under __init__ and then calls connect(). If connect() fails at some point then disconnect() is called.

Within this method, to start the voice connection flow it is recommended to use Guild.change_voice_state() to start the flow. After which, on_voice_server_update() and on_voice_state_update() will be called. The order that these two are called is unspecified.

timeout: float

The timeout for the connection.

reconnect: bool

Whether reconnection is expected.

property current: pomice.objects.Track

Property which returns the currently playing track

async destroy()

Disconnects and destroys the player, and runs internal cleanup.

async disconnect(*, force: bool = False)

Disconnects the player from voice.

property filter: pomice.filters.Filter

Property which returns the currently applied filter, if one is applied

async get_tracks(query: str, *, ctx: Optional[discord.ext.commands.context.Context] = None, search_type: pomice.enums.SearchType = SearchType.ytsearch)

Fetches tracks from the node’s REST api to parse into Lavalink.

If you passed in Spotify API credentials when you created the node, you can also pass in a Spotify URL of a playlist, album or track and it will be parsed accordingly.

You can also pass in a discord.py Context object to get a Context object on any track you search.

property guild: discord.guild.Guild

Property which returns the guild associated with the player

property is_connected: bool

Property which returns whether or not the player is connected

property is_dead: bool

Returns a bool representing whether the player is dead or not. A player is considered dead if it has been destroyed and removed from stored players.

property is_paused: bool

Property which returns whether or not the player has a track which is paused or not.

property is_playing: bool

Property which returns whether or not the player is actively playing a track.

property node: pomice.pool.Node

Property which returns the node the player is connected to

async on_voice_server_update(data: dict)

|coro|

An abstract method that is called when initially connecting to voice. This corresponds to VOICE_SERVER_UPDATE.

data: dict

The raw voice server update payload.

async on_voice_state_update(data: dict)

|coro|

An abstract method that is called when the client’s voice state has changed. This corresponds to VOICE_STATE_UPDATE.

data: dict

The raw voice state payload.

async play(track: pomice.objects.Track, *, start: int = 0, end: int = 0, ignore_if_playing: bool = False) → pomice.objects.Track

Plays a track. If a Spotify track is passed in, it will be handled accordingly.

property position: float

Property which returns the player’s position in a track in milliseconds

async seek(position: float) → float

Seeks to a position in the currently playing track milliseconds

async set_filter(filter: pomice.filters.Filter) → pomice.filters.Filter

Sets a filter of the player. Takes a pomice.Filter object. This will only work if you are using the development version of Lavalink.

async set_pause(pause: bool) → bool

Sets the pause state of the currently playing track.

async set_volume(volume: int) → int

Sets the volume of the player as an integer. Lavalink accepts values from 0 to 500.

async stop()

Stops the currently playing track.

property volume: int

Property which returns the players current volume

Pool

class pomice.pool.Node(*, pool, bot: Union[discord.ext.commands.bot.AutoShardedBot, discord.shard.AutoShardedClient, discord.ext.commands.bot.Bot, discord.client.Client], host: str, port: int, password: str, identifier: str, session: Optional[aiohttp.client.ClientSession], spotify_client_id: Optional[str], spotify_client_secret: Optional[str])

Bases: object

The base class for a node. This node object represents a Lavalink node. To enable Spotify searching, pass in a proper Spotify Client ID and Spotify Client Secret

property bot: Union[discord.ext.commands.bot.AutoShardedBot, discord.shard.AutoShardedClient, discord.ext.commands.bot.Bot, discord.client.Client]

Property which returns the discord.py client linked to this node

async build_track(identifier: str, ctx: Optional[discord.ext.commands.context.Context] = None) → pomice.objects.Track

Builds a track using a valid track identifier

You can also pass in a discord.py Context object to get a Context object on the track it builds.

async connect()

Initiates a connection with a Lavalink node and adds it to the node pool.

async disconnect()

Disconnects a connected Lavalink node and removes it from the node pool. This also destroys any players connected to the node.

get_player(guild_id: int)

Takes a guild ID as a parameter. Returns a pomice Player object.

async get_tracks(query: str, *, ctx: Optional[discord.ext.commands.context.Context] = None, search_type: pomice.enums.SearchType = SearchType.ytsearch)

Fetches tracks from the node’s REST api to parse into Lavalink.

If you passed in Spotify API credentials, you can also pass in a Spotify URL of a playlist, album or track and it will be parsed accordingly.

You can also pass in a discord.py Context object to get a Context object on any track you search.

property is_connected: bool

“Property which returns whether this node is connected or not

property latency: int

Property which returns the latency of the node in milliseconds

property player_count: int

Property which returns how many players are connected to this node

property players: Dict[int, Player]

Property which returns a dict containing the guild ID and the player object.

property pool

Property which returns the pool this node is apart of

async send(**data)
property stats: pomice.utils.NodeStats

Property which returns the node stats.

class pomice.pool.NodePool

Bases: object

The base class for the node pool. This holds all the nodes that are to be used by the bot.

async classmethod create_node(*, bot: Union[discord.ext.commands.bot.AutoShardedBot, discord.shard.AutoShardedClient, discord.ext.commands.bot.Bot, discord.client.Client], host: str, port: str, password: str, identifier: str, spotify_client_id: Optional[str], spotify_client_secret: Optional[str], session: Optional[aiohttp.client.ClientSession] = None) → pomice.pool.Node

Creates a Node object to be then added into the node pool. For Spotify searching capabilites, pass in valid Spotify API credentials.

classmethod get_node(*, identifier: Optional[str] = None) → pomice.pool.Node

Fetches a node from the node pool using it’s identifier. If no identifier is provided, it will choose a node at random.

property node_count
property nodes: Dict[str, pomice.pool.Node]

Property which returns a dict with the node identifier and the Node object.

Utils

The MIT License (MIT) Copyright (c) 2015-present Rapptz Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

class pomice.utils.ExponentialBackoff(base: int = 1, *, integral: bool = False)

Bases: object

delay() → float
class pomice.utils.NodeStats(data: dict)

Bases: object

The base class for the node stats object. Gives critical information on the node, which is updated every minute.