Getting Started:

Quickstart

You can view documentation on the core library here:

Obsidian.py Documentation
- Node
- Players
- Tracks
- Filters
- Events
- Queues
- Enums
- Stats
- Exceptions and Errors
Obsidian.py Changelog
- v0.2.0

You can view documentation on the extension here:

Adding Spotify support to Obsidian.py
- Enabling spotify support
- Making use of Spotify support

Obsidian.py Documentation¶

Node¶

class obsidian.Node(*args, **kwargs)¶

Represents a connection to Obsidian that manages requests and websockets.

Parameters

bot (discord.Client) – The client or bot that this node belongs to.
host (str) – The IP of the host that Obsidian is running on.
port (str) – The port of the host that Obsidian is running on.
password (Optional[str]) – The password needed to connect to Obsidian.
identifier (Optional[str]) – The name to use to refer to this node. Defaults to ‘MAIN’
region (Optional[discord.VoiceRegion]) – The voice region this node will be in.

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

The discord.Client that this node corresponds to.

Type: discord.Client

async connect(*, session: Optional[aiohttp.client.ClientSession] = None, loop: Optional[asyncio.events.AbstractEventLoop] = None) → None¶

Establishes a websocket connection for this node.

Parameters

session (Optional[aiohttp.ClientSession]) – The session to use when connecting.
loop (Optional[asyncio.AbstractEventLoop]) – The event loop to use when connecting.

property connected: bool¶

Whether or not this node is connected.

Type: bool

async decode_track(id: str, /, *, cls: type = <class 'obsidian.track.Track'>, **kwargs) → Optional[obsidian.track.Track]¶

This function is a coroutine.

Decodes a track given it’s Base 64 ID.

Parameters

id (str) – The track’s ID, usually represented in Base 64.
cls (type, default: Track) – The class to cast the track to.
kwargs – Extra keyword arguments to pass into the class constructor.

Returns

The decoded track, if any.

Return type

Optional[Track]

See also

Node.decode_tracks()

async decode_tracks(ids: str, /, *, cls: type = <class 'obsidian.track.Track'>, **kwargs) → Optional[List[obsidian.track.Track]]¶

This function is a coroutine.

Decodes multiple tracks, given their Base 64 ID’s.

Parameters

ids (List[str]) – A list of base 64 track ID’s to decode.
cls (type, default: Track) – The class to cast the tracks to.
kwargs – Extra keyword arguments to pass into the class constructor.

Returns

A list of constructed tracks, if any.

Return type

Optional[List[Track]]

See also

Node.decode_track()

async destroy(*, force: bool = False) → None¶

Disconnects, deletes, and destroys this node.

Parameters: force (bool, default: False) – Whether or not to force disconnection.

destroy_player(guild: Union[discord.guild.Guild, discord.object.Object, int]) → None¶

Destroys and deletes a player.

Parameters: guild (Union[discord.Guild, discord.Object, int]) – The player’s corresponding guild.

async disconnect(*, force: bool = False) → None¶

Disconnects the current websocket connection for this node.

Parameters: force (bool, default: False) – Whether or not to force disconnection.

get_player(guild: Union[discord.guild.Guild, discord.object.Object, int], cls: type = <class 'obsidian.player.Player'>, must_exist: bool = False, *args, **kwargs) → Optional[obsidian.player.Player]¶

Gets an existing Player, or if not found, creates it.

Parameters

guild (Union[discord.Guild, discord.Object, int]) – The guild that this player corresponds to.
cls (type, default: Player) – The class to cast the player to.
must_exist (bool, default: False) – Whether or not to return None if the player doesn’t already exist.
args – Extra arguments to pass into the class constructor.
kwargs – Extra keyword arguments to pass into the class constructor.

Returns

The player found, or if it didn’t exist, created.

Return type

Player

property host: str¶

The IP of the host of Obsidian.

Type: str

property identifier: str¶

The identifier for this node, specified in the constructor.

Type: str

property password: str¶

The password needed to connect to Obsidian.

Type: str

property port: str¶

The port of the host of Obsidian.

Type: str

property region: Optional[discord.enums.VoiceRegion]¶

The voice region for this node, specified in the constructor.

Type: discord.VoiceRegion

async search_track(*args, **kwargs)¶

Searches for one single track given a query or URL.

Warning

If the track is a direct URL, the source kwarg will be ignored.

Parameters

query (str) – The search query or URL.
source (Optional[Source]) – The source that the track should come from.
cls (type, default: Track) – The class to cast the track to.
suppress (bool, default: False) – Whether or not to suppress NoSearchMatchesFound

Returns

The track or playlist that was found, if any.

Return type

Optional[Union[Track, Playlist]]

async search_tracks(*args, **kwargs)¶

Searches for multiple tracks given a query or URL.

Warning

If the track is a direct URL, the source kwarg will be ignored.

Warning

If a playlist is found, the return type will not be a list, rather just the playlist itself.

Parameters

query (str) – The search query or URL.
source (Optional[Source]) – The source that the tracks should come from.
cls (type, default: Track) – The class to cast the tracks to.
suppress (bool, default: False) – Whether or not to suppress NoSearchMatchesFound
limit (Optional[int]) – The maximum amount of tracks to return.

Returns

A list of tracks found, or a playlist.

Return type

Union[List[Track], Playlist]

async send(op: Union[obsidian.enums.OpCode, int], data: dict) → None¶

Sends a message to the Obsidian websocket.

Parameters

op (Union[OpCode, int]) – The Op-Code of the request.
data (Dict[str, Any]) – The JSON payload to send.

property stats: obsidian.stats.Stats¶: Stats The statistics for this node returned by the websocket.

class obsidian.BaseNode(bot: Union[discord.client.Client, discord.shard.AutoShardedClient, discord.ext.commands.bot.Bot, discord.ext.commands.bot.AutoShardedBot], host: str = '127.0.0.1', port: Union[str, int] = '3030', password: Optional[str] = None, identifier: Optional[str] = None, region: Optional[discord.enums.VoiceRegion] = None, *, session: Optional[aiohttp.client.ClientSession] = 'None', loop: Optional[asyncio.events.AbstractEventLoop] = 'None', heartbeat: Optional[float] = 'None', secure: Optional[bool] = 'None', **kwargs)¶

Represents the base class for all nodes.

You should use Node instead.

Parameters

bot (discord.Client) – The client or bot that this node belongs to.
host (str) – The IP of the host that Obsidian is running on.
port (str) – The port of the host that Obsidian is running on.
password (Optional[str]) – The password needed to connect to Obsidian.
identifier (Optional[str]) – The name to use to refer to this node. Defaults to ‘MAIN’
region (Optional[discord.VoiceRegion]) – The voice region this node will be in.

See also

Node

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

The discord.Client that this node corresponds to.

Type: discord.Client

async connect(*, session: Optional[aiohttp.client.ClientSession] = None, loop: Optional[asyncio.events.AbstractEventLoop] = None) → None¶

Establishes a websocket connection for this node.

Parameters

session (Optional[aiohttp.ClientSession]) – The session to use when connecting.
loop (Optional[asyncio.AbstractEventLoop]) – The event loop to use when connecting.

property connected: bool¶

Whether or not this node is connected.

Type: bool

async decode_track(id: str, /, *, cls: type = <class 'obsidian.track.Track'>, **kwargs) → Optional[obsidian.track.Track]¶

This function is a coroutine.

Decodes a track given it’s Base 64 ID.

Parameters

id (str) – The track’s ID, usually represented in Base 64.
cls (type, default: Track) – The class to cast the track to.
kwargs – Extra keyword arguments to pass into the class constructor.

Returns

The decoded track, if any.

Return type

Optional[Track]

See also

Node.decode_tracks()

async decode_tracks(ids: str, /, *, cls: type = <class 'obsidian.track.Track'>, **kwargs) → Optional[List[obsidian.track.Track]]¶

This function is a coroutine.

Decodes multiple tracks, given their Base 64 ID’s.

Parameters

ids (List[str]) – A list of base 64 track ID’s to decode.
cls (type, default: Track) – The class to cast the tracks to.
kwargs – Extra keyword arguments to pass into the class constructor.

Returns

A list of constructed tracks, if any.

Return type

Optional[List[Track]]

See also

Node.decode_track()

async destroy(*, force: bool = False) → None¶

Disconnects, deletes, and destroys this node.

Parameters: force (bool, default: False) – Whether or not to force disconnection.

destroy_player(guild: Union[discord.guild.Guild, discord.object.Object, int]) → None¶

Destroys and deletes a player.

Parameters: guild (Union[discord.Guild, discord.Object, int]) – The player’s corresponding guild.

async disconnect(*, force: bool = False) → None¶

Disconnects the current websocket connection for this node.

Parameters: force (bool, default: False) – Whether or not to force disconnection.

Gets an existing Player, or if not found, creates it.

Parameters

guild (Union[discord.Guild, discord.Object, int]) – The guild that this player corresponds to.
cls (type, default: Player) – The class to cast the player to.
must_exist (bool, default: False) – Whether or not to return None if the player doesn’t already exist.
args – Extra arguments to pass into the class constructor.
kwargs – Extra keyword arguments to pass into the class constructor.

Returns

The player found, or if it didn’t exist, created.

Return type

Player

property host: str¶

The IP of the host of Obsidian.

Type: str

property identifier: str¶

The identifier for this node, specified in the constructor.

Type: str

property password: str¶

The password needed to connect to Obsidian.

Type: str

property port: str¶

The port of the host of Obsidian.

Type: str

property region: Optional[discord.enums.VoiceRegion]¶

The voice region for this node, specified in the constructor.

Type: discord.VoiceRegion

async search_track(query: str, *, source: Optional[obsidian.enums.Source] = 'None', cls: type = 'Track', suppress: bool = 'False', **kwargs) → Optional[Union[obsidian.track.Track, obsidian.track.Playlist]]¶

Searches for one single track given a query or URL.

Warning

If the track is a direct URL, the source kwarg will be ignored.

Parameters

query (str) – The search query or URL.
source (Optional[Source]) – The source that the track should come from.
cls (type, default: Track) – The class to cast the track to.
suppress (bool, default: False) – Whether or not to suppress NoSearchMatchesFound

Returns

The track or playlist that was found, if any.

Return type

Optional[Union[Track, Playlist]]

async search_tracks(query: str, *, source: Optional[obsidian.enums.Source] = 'None', cls: type = 'Track', suppress: bool = 'True', limit: Optional[int] = 'None', **kwargs) → Optional[Union[List[obsidian.track.Track], obsidian.track.Playlist]]¶

Searches for multiple tracks given a query or URL.

Warning

If the track is a direct URL, the source kwarg will be ignored.

Warning

If a playlist is found, the return type will not be a list, rather just the playlist itself.

Parameters

query (str) – The search query or URL.
source (Optional[Source]) – The source that the tracks should come from.
cls (type, default: Track) – The class to cast the tracks to.
suppress (bool, default: False) – Whether or not to suppress NoSearchMatchesFound
limit (Optional[int]) – The maximum amount of tracks to return.

Returns

A list of tracks found, or a playlist.

Return type

Union[List[Track], Playlist]

async send(op: Union[obsidian.enums.OpCode, int], data: dict) → None¶

Sends a message to the Obsidian websocket.

Parameters

op (Union[OpCode, int]) – The Op-Code of the request.
data (Dict[str, Any]) – The JSON payload to send.

property stats: obsidian.stats.Stats¶: Stats The statistics for this node returned by the websocket.

Players¶

Player¶

class obsidian.Player(*args, **kwargs)¶

Represents a guild’s music player.

This class is recommended to be subclassed for custom behaviors. This class also inherits from NodeListenerMixin.

Parameters

node (BaseNode) – The node constructing this player.
bot (discord.Client) – The bot of the corresponding node.
guild (Union[discord.Guild, discord.Object]) – The guild that this player corresponds to.

async add_filter(*filters: obsidian.filters.BaseFilter) → None¶

Appends a new filter, or filters, to the current filter sink.

Parameters: filters (BaseFilter) – The filter(s) to add.

async add_filters(*filters: obsidian.filters.BaseFilter) → None¶

Appends a new filter, or filters, to the current filter sink.

Parameters: filters (BaseFilter) – The filter(s) to add.

property bot: Union[discord.client.Client, discord.shard.AutoShardedClient, discord.ext.commands.bot.Bot, discord.ext.commands.bot.AutoShardedBot]¶: discord.Client The bot that this player uses.

property channel: discord.channel.VoiceChannel¶

The voice channel that this player is connected to.

Type: discord.VoiceChannel

async connect(channel: discord.channel.VoiceChannel, *, cls: type = <class 'obsidian.player.Protocol'>, timeout: Optional[float] = None, reconnect: Optional[bool] = None, self_deaf: bool = False) → obsidian.player.Protocol¶

Connects to a discord.VoiceChannel.

Parameters

channel (discord.VoiceChannel) – The channel to connect to.
cls (type, default: Protocol) – The connection protocol class to use.
timeout (float, optional) – The timeout to use when connecting.
reconnect (bool, optional) – Whether or not to reconnect.
self_deaf (bool, default: False) – Whether or not to self-deafen upon connecting.

Returns

The connection protocol created.

Return type

Protocol

property connected: bool¶

Whether or not this player is connected.

Type: bool

property current: obsidian.track.Track¶

The current track this player is playing.

Type: Track

property current_track_id: Optional[str]¶

The raw base 64 ID of the current track playing.

Type: Optional[str]

async destroy(*, force: bool = False) → None¶

Destroys, disconnects, and deletes this player.

Parameters: force (bool, default: False) – Whether or not to force disconnection.

async disconnect(*, force: bool = False) → None¶

Disconnects from the current voice connection.

Parameters: force (bool, default: False) – Whether or not to force disconnection.

property eq: Optional[obsidian.filters.Equalizer]¶

The current equalizer of the music audio.

Type: Optional[Equalizer]

property equalizer: Optional[obsidian.filters.Equalizer]¶

The current equalizer of the music audio.

Type: Optional[Equalizer]

property filters: obsidian.filters.FilterSink¶

The FilterSink of filters this player is using.

Type: FilterSink

property guild: Union[discord.guild.Guild, discord.object.Object]¶

The guild that corresponds to this player.

Type: Union[discord.Guild, discord.Object]

property guild_id: int¶

The ID of the guild that corresponds to this player.

Type: int

property listeners: List[discord.member.Member]¶

Returns a list of discord.Member in the voice channel that are undeafened.

Type: List[discord.Member]

async move(channel: discord.channel.VoiceChannel) → None¶

Moves the connection to another voice channel.

Parameters: channel (discord.VoiceChannel) – The channel to move to.

property node¶

The node that this player uses.

Type: Node

async overwrite_filters(filters: obsidian.filters.FilterSink) → None¶

Completely overwrites the current filter sink into a new one.

Parameters: filters (FilterSink) – The new filter sink to use.

See also

Player.add_filter(): Appends a new filter to the current filter sink.

property paused: bool¶

Whether or not this player is paused.

Type: bool

async play(track: Union[obsidian.track.Track, obsidian.track.Playlist], *, start_time: int = 0, end_time: int = 0, no_replace: bool = False) → None¶

Plays a track using this player.

If you provide a playlist, the player will play the Playlist.selected_track.

Parameters

track (Track) – The track to play.
start_time (int, default: 0) – The start time offset of the track, in milliseconds.
end_time (int, default: 0) – When to end the track, in milliseconds.
no_replace (bool, default: False) – If set to True, this will do nothing if a track is already playing. If set to False, this will overwrite the current playing track.

property playing: bool¶: Whether or not this player is playing music.

property position: float¶

The position, in milliseconds, of the current track playing.

For example, this can return 62000 if the track is 62 seconds in.

Type: float

async remove_filter(*filters) → None¶

Removes a filter from the current filter sink.

Parameters: filters (BaseFilter) – The filter(s) to remove.

async remove_filters(*filters) → None¶

Removes a filter from the current filter sink.

Parameters: filters (BaseFilter) – The filter(s) to remove.

async reset_filter() → None¶: Resets the current filter sink.

async reset_filters() → None¶: Resets the current filter sink.

async seek(position: float) → None¶

Sets the current time position, in milliseconds, of the current playing track.

Parameters: position (float) – The new time position, in milliseconds.

async set_eq(equalizer: obsidian.filters.Equalizer) → None¶

Overwrites and changes the current audio equalizer.

Parameters: equalizer (Equalizer) – The new equalizer to use.

async set_equalizer(equalizer: obsidian.filters.Equalizer) → None¶

Overwrites and changes the current audio equalizer.

Parameters: equalizer (Equalizer) – The new equalizer to use.

async set_filter(filters: obsidian.filters.FilterSink) → None¶

Completely overwrites the current filter sink into a new one.

Parameters: filters (FilterSink) – The new filter sink to use.

See also

Player.add_filter(): Appends a new filter to the current filter sink.

async set_filters(filters: obsidian.filters.FilterSink) → None¶

Completely overwrites the current filter sink into a new one.

Parameters: filters (FilterSink) – The new filter sink to use.

See also

Player.add_filter(): Appends a new filter to the current filter sink.

async set_pause(pause: Optional[bool] = None) → bool¶

Sets the paused state for the current track.

Parameters: pause (bool, optional) – The new paused state. If this is left as None, the new paused state will be the opposite of the current.
Returns: The new paused state (for confirmation).
Return type: bool

async set_position(position: float) → None¶

Sets the current time position, in milliseconds, of the current playing track.

Parameters: position (float) – The new time position, in milliseconds.

async set_vol(volume: int = 100) → None¶

Sets the player volume in percent.

The volume must be at least 0 and at most 500.

Warning

It is recommended not to allow users to set the volume past 200 as it is then virtually earrape.

Parameters: volume (int, default: 100) – The new volume of the player.

async set_volume(volume: int = 100) → None¶

Sets the player volume in percent.

The volume must be at least 0 and at most 500.

Warning

It is recommended not to allow users to set the volume past 200 as it is then virtually earrape.

Parameters: volume (int, default: 100) – The new volume of the player.

async stop(*, force: bool = False) → None¶

Stops the current playing track.

Parameters: force (bool, default: False) – Whether or not to force stop the track.

property voice_client: obsidian.player.Protocol¶

The Protocol this player is currently using.

Type: Protocol

property volume: int¶

The current volume of the music playing.

Type: int

PresetPlayer¶

class obsidian.PresetPlayer(*args, **kwargs)¶

Basic music player with many things already built and handled for you.

Note that this class should still be inherited from in order to add required methods.

async add_filter(*filters: obsidian.filters.BaseFilter) → None¶

Appends a new filter, or filters, to the current filter sink.

Parameters: filters (BaseFilter) – The filter(s) to add.

async add_filters(*filters: obsidian.filters.BaseFilter) → None¶

Appends a new filter, or filters, to the current filter sink.

Parameters: filters (BaseFilter) – The filter(s) to add.

property bot: Union[discord.client.Client, discord.shard.AutoShardedClient, discord.ext.commands.bot.Bot, discord.ext.commands.bot.AutoShardedBot]¶: discord.Client The bot that this player uses.

property channel: discord.channel.VoiceChannel¶

The voice channel that this player is connected to.

Type: discord.VoiceChannel

Connects to a discord.VoiceChannel.

Parameters

channel (discord.VoiceChannel) – The channel to connect to.
cls (type, default: Protocol) – The connection protocol class to use.
timeout (float, optional) – The timeout to use when connecting.
reconnect (bool, optional) – Whether or not to reconnect.
self_deaf (bool, default: False) – Whether or not to self-deafen upon connecting.

Returns

The connection protocol created.

Return type

Protocol

property connected: bool¶

Whether or not this player is connected.

Type: bool

property current: obsidian.track.Track¶

The current track that is playing.

Type: Track

property current_track_id: Optional[str]¶

The raw base 64 ID of the current track playing.

Type: Optional[str]

async destroy(*, force: bool = False) → None¶

Destroys, disconnects, and deletes this player.

Parameters: force (bool, default: False) – Whether or not to force disconnection.

async disconnect(*, force: bool = False) → None¶

Disconnects from the current voice connection.

Parameters: force (bool, default: False) – Whether or not to force disconnection.

property dj: discord.member.Member¶

The current DJ of this player.

Type: discord.Member

async do_next() → Optional[obsidian.track.Track]¶

Plays the track fetched from PointerBasedQueue.get().

Returns: The track that will be played, if any.
Return type: Optional[Track]

enqueue(track: Union[obsidian.track.Track, obsidian.track.Playlist]) → None¶

Enqueues a Track or an entire Playlist.

Parameters: track (Union[Track, Playlist]) – The track or playlist to enqueue.

property eq: Optional[obsidian.filters.Equalizer]¶

The current equalizer of the music audio.

Type: Optional[Equalizer]

property equalizer: Optional[obsidian.filters.Equalizer]¶

The current equalizer of the music audio.

Type: Optional[Equalizer]

property filters: obsidian.filters.FilterSink¶

The FilterSink of filters this player is using.

Type: FilterSink

property guild: Union[discord.guild.Guild, discord.object.Object]¶

The guild that corresponds to this player.

Type: Union[discord.Guild, discord.Object]

property guild_id: int¶

The ID of the guild that corresponds to this player.

Type: int

property index: int¶

The pointer index of the queue.

Type: int

property listeners: List[discord.member.Member]¶

Returns a list of discord.Member in the voice channel that are undeafened.

Type: List[discord.Member]

async move(channel: discord.channel.VoiceChannel) → None¶

Moves the connection to another voice channel.

Parameters: channel (discord.VoiceChannel) – The channel to move to.

property node¶

The node that this player uses.

Type: Node

property now_playing: obsidian.track.Track¶

The current track that is playing.

Type: Track

async overwrite_filters(filters: obsidian.filters.FilterSink) → None¶

Completely overwrites the current filter sink into a new one.

Parameters: filters (FilterSink) – The new filter sink to use.

See also

Player.add_filter(): Appends a new filter to the current filter sink.

property paused: bool¶

Whether or not this player is paused.

Type: bool

async play(track: Union[obsidian.track.Track, obsidian.track.Playlist], *, start_time: int = 0, end_time: int = 0, no_replace: bool = False) → None¶

Plays a track using this player.

If you provide a playlist, the player will play the Playlist.selected_track.

Parameters

track (Track) – The track to play.
start_time (int, default: 0) – The start time offset of the track, in milliseconds.
end_time (int, default: 0) – When to end the track, in milliseconds.
no_replace (bool, default: False) – If set to True, this will do nothing if a track is already playing. If set to False, this will overwrite the current playing track.

property playing: bool¶: Whether or not this player is playing music.

property position: float¶

The position, in milliseconds, of the current track playing.

For example, this can return 62000 if the track is 62 seconds in.

Type: float

property queue: obsidian.queue.Queue¶

The current queue for this player.

Type: PointerBasedQueue

async remove_filter(*filters) → None¶

Removes a filter from the current filter sink.

Parameters: filters (BaseFilter) – The filter(s) to remove.

async remove_filters(*filters) → None¶

Removes a filter from the current filter sink.

Parameters: filters (BaseFilter) – The filter(s) to remove.

async reset_filter() → None¶: Resets the current filter sink.

async reset_filters() → None¶: Resets the current filter sink.

async seek(position: float) → None¶

Sets the current time position, in milliseconds, of the current playing track.

Parameters: position (float) – The new time position, in milliseconds.

async set_eq(equalizer: obsidian.filters.Equalizer) → None¶

Overwrites and changes the current audio equalizer.

Parameters: equalizer (Equalizer) – The new equalizer to use.

async set_equalizer(equalizer: obsidian.filters.Equalizer) → None¶

Overwrites and changes the current audio equalizer.

Parameters: equalizer (Equalizer) – The new equalizer to use.

async set_filter(filters: obsidian.filters.FilterSink) → None¶

Completely overwrites the current filter sink into a new one.

Parameters: filters (FilterSink) – The new filter sink to use.

See also

Player.add_filter(): Appends a new filter to the current filter sink.

async set_filters(filters: obsidian.filters.FilterSink) → None¶

Completely overwrites the current filter sink into a new one.

Parameters: filters (FilterSink) – The new filter sink to use.

See also

Player.add_filter(): Appends a new filter to the current filter sink.

set_loop_type(new: obsidian.queue.LoopType) → None¶

Changes the LoopType of the queue.

Parameters: new (LoopType) – The new loop type to use.

async set_pause(pause: Optional[bool] = None) → bool¶

Sets the paused state for the current track.

Parameters: pause (bool, optional) – The new paused state. If this is left as None, the new paused state will be the opposite of the current.
Returns: The new paused state (for confirmation).
Return type: bool

async set_position(position: float) → None¶

Sets the current time position, in milliseconds, of the current playing track.

Parameters: position (float) – The new time position, in milliseconds.

async set_vol(volume: int = 100) → None¶

Sets the player volume in percent.

The volume must be at least 0 and at most 500.

Warning

It is recommended not to allow users to set the volume past 200 as it is then virtually earrape.

Parameters: volume (int, default: 100) – The new volume of the player.

async set_volume(volume: int = 100) → None¶

Sets the player volume in percent.

The volume must be at least 0 and at most 500.

Warning

It is recommended not to allow users to set the volume past 200 as it is then virtually earrape.

Parameters: volume (int, default: 100) – The new volume of the player.

async skip() → Optional[obsidian.track.Track]¶

Skips the current track regardless of the loop type.

This uses PointerBasedQueue.skip().

Returns: The new track to be played, if any.
Return type: Optional[Track]

async stop(*, force: bool = False) → None¶

Stops the current playing track.

Parameters: force (bool, default: False) – Whether or not to force stop the track.

property voice_client: obsidian.player.Protocol¶

The Protocol this player is currently using.

Type: Protocol

property volume: int¶

The current volume of the music playing.

Type: int

Protocol¶

class obsidian.player.Protocol(player: obsidian.player.Player)¶

async connect(*, timeout: Optional[float] = None, reconnect: Optional[bool] = None, self_deaf: bool = False) → None¶

This function is a coroutine.

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.

Parameters

timeout (float) – The timeout for the connection.
reconnect (bool) – Whether reconnection is expected.

async disconnect(*, force: bool = False) → None¶

This function is a coroutine.

An abstract method called when the client terminates the connection.

See cleanup().

Parameters: force (bool) – Whether the disconnection was forced.

async on_voice_server_update(data: Dict[str, Any]) → None¶

This function is a coroutine.

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

Parameters

data (dict) –

The raw voice server update payload.

async on_voice_state_update(data: Dict[str, Any]) → None¶

This function is a coroutine.

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

Parameters

data (dict) –

The raw voice state payload.

Tracks¶

Track¶

class obsidian.Track(*, id: str, info: Dict[str, Any], ctx: Optional[discord.ext.commands.context.Context] = None, **kwargs)¶

Represents an obsidian song track.

Parameters

id (str) – The base 64 track ID.
info (Dict[str, Any]) – The raw JSON payload returned by Obsidian, containing information about this track.
ctx (Optional[commands.Context]) – An optional context to use for this track. By default, if this is provided, Track.requester will be the author of the context.
kwargs – Extra keyword arguments to pass into the constructor.

property author: str¶

The author of the track.

Type: str

property ctx: Optional[discord.ext.commands.context.Context]¶

The Context that invoked the track. Could be None .

Type: Optional[Context]

property id: str¶

The Base64 Track ID, can be used to rebuild track objects.

See also

Node.decode_track()

Type: str

property identifier: str¶

The tracks identifier.

Type: str

property length: int¶

The duration of the track in milliseconds.

Type: int

property position: int¶

The current position of the track in milliseconds.

Type: int

property requester: Optional[discord.member.Member]¶

The discord.Member that requested the track.

Type: Optional[discord.Member]

property seekable: bool¶

If you are able to seek the track’s position or not.

Type: bool

property source: obsidian.enums.Source¶

Return an enum indicates the type of the Source .

Type: Source

property stream: bool¶

Whether the track is a stream or not.

Type: bool

property thumbnail: str¶

Return the image URL of the track’s thumbnail, could be an empty str depending on the Source .

Type: str

property title: str¶

The track title.

Type: str

property uri: str¶

The track’s URI.

Type: str

Playlist¶

class obsidian.Playlist(*, info: Dict[str, Any], tracks: List[Dict[str, Any]], ctx: Optional[discord.ext.commands.context.Context] = None, cls: type = <class 'obsidian.track.Track'>, **kwargs)¶

Represents a playlist of tracks.

property count: int¶

Return the total amount of tracks in the playlist.

Type: int

property ctx: Optional[discord.ext.commands.context.Context]¶

The Context that invoked the playlist. Could be None .

Type: Optional[Context]

property name: str¶

The name of the playlist.

Type: str

property requester: Optional[discord.member.Member]¶

The discord.Member that requested the playlist.

Type: Optional[discord.Member]

property selected_track: Optional[obsidian.track.Track]¶: The selected track returned by Obsidian, could be None .

property source: obsidian.enums.Source¶

Return an enum indicates the type of the Source .

Type: Source

property tracks: List[obsidian.track.Track]¶

Return a list of Track s.

Type: List[Track]

property uri: Optional[str]¶

The playlist’s URI.

Type: str

Filters¶

FilterSink¶

class obsidian.FilterSink(player)¶: Represents a sink of filters.

BaseFilter¶

class obsidian.BaseFilter¶

VolumeFilter¶

class obsidian.VolumeFilter(volume: float = 1.0)¶

TimescaleFilter¶

class obsidian.TimescaleFilter(*, pitch: Optional[float] = None, pitch_octaves: Optional[float] = None, pitch_semitones: Optional[float] = None, rate: Optional[float] = None, rate_change: Optional[float] = None, speed: Optional[float] = None, speed_change: Optional[float] = None)¶

RotationFilter¶

class obsidian.RotationFilter(hz: float = 5.0)¶

Equalizer¶

class obsidian.Equalizer(*gains: float, name: str = 'custom')¶

VibratoFilter¶

class obsidian.VibratoFilter(frequency: float = 2.0, depth: float = 0.5)¶

TremoloFilter¶

class obsidian.TremoloFilter(frequency: float = 2.0, depth: float = 0.5)¶

KaraokeFilter¶

class obsidian.KaraokeFilter(level: float = 1.0, mono_level: float = 1.0, *, filter_band: float = 220.0, filter_width: float = 100.0)¶

ChannelMixFilter¶

class obsidian.ChannelMixFilter(*, left_to_left: float = 1, right_to_right: float = 1, left_to_right: float = 0, right_to_left: float = 0)¶

LowPassFilter¶

class obsidian.LowPassFilter(smoothing: float = 20)¶

Events¶

class obsidian.events.BaseEvent(data: Dict[str, Any])¶

The base event class that all events inherit from.

property guild_id: int¶: The snowflake ID of the guild of the corresponding player this event occured in.

property type: obsidian.enums.EventType¶: The type of the event.

class obsidian.events.TrackEndEvent(data: Dict[str, Any])¶

The event for when a track ends.

property reason: obsidian.enums.TrackEndReason¶: A TrackEndReason on why this track ended.

property track_id: str¶: The raw base 64 track ID of the track that ended.

class obsidian.events.TrackExceptionEvent(data: Dict[str, Any])¶

Event for when Obsidian encounters an error while playing a track.

property cause: str¶: The cause of the error.

property message: str¶: The error message provided by Obsidian.

property severity: obsidian.enums.TrackExceptionSeverity¶: A TrackExceptionSeverity representing the severity of this exception.

property track_id: str¶: The raw base 64 track ID of the track.

class obsidian.events.TrackStartEvent(data: Dict[str, Any])¶

The event for when a track starts playing.

property track_id: str¶: The raw base 64 track ID of the track that started.

class obsidian.events.TrackStuckEvent(data: Dict[str, Any])¶

The event for when a track gets stuck.

property threshold: float¶: The wait threshold that was exceeded for this event to trigger, in seconds.

property threshold_ms: int¶: The wait threshold that was exceeded for this event to trigger, in milliseconds.

property track_id: str¶: The raw base 64 track ID of the track that got stuck.

class obsidian.events.WebsocketCloseEvent(data: Dict[str, Any])¶

Event for when the websocket gets closed.

property by_remote: bool¶: Whether or not the websocket was closed remotely.

property code: int¶: The websocket close code, provided by Discord.

property reason: str¶: Reason on why the websocket was closed.

class obsidian.events.WebsocketOpenEvent(data: Dict[str, Any])¶

Event for when Obsidian’s websocket is opened.

property target: str¶: The target IP of the websocket.

Queues¶

Utility queue classes are built into obsidian.py.

Queue¶

class obsidian.Queue(max_size: Optional[int], *, cls: type = <class 'collections.deque'>)¶

Utility queue class made only for Tracks and Playlists.

Warning

You can only queue Tracks and Playlists. Playlists will be implicitly handled for you.

Parameters

max_size (Optional[int]) – The maximum number of tracks that the queue can hold.
cls (type, default: collections.deque) – The deque class to use for the internal queue.

add(track: Union[obsidian.track.Track, obsidian.track.Playlist], *, left: bool = False) → None¶

Adds a Track or Playlist to the queue.

If a playlist is provided, the queue will extend from it’s tracks.

Parameters

track (Union[Track, Playlist]) – The track or playlist to add.
left (bool, default: False) – Whether or not to add this track to the beginning of the queue.

append(track: Union[obsidian.track.Track, obsidian.track.Playlist], *, left: bool = False) → None¶

Adds a Track or Playlist to the queue.

If a playlist is provided, the queue will extend from it’s tracks.

Parameters

track (Union[Track, Playlist]) – The track or playlist to add.
left (bool, default: False) – Whether or not to add this track to the beginning of the queue.

clear() → None¶: Clears this queue and removes all tracks.

copy() → obsidian.queue.Queue¶

Copies this queue and returns a new queue with the same tracks.

Returns: The new, copied queue.
Return type: Queue

property count: int¶

The amount of tracks currently enqueued.

Type: int

extend(tracks: Iterable[Union[obsidian.track.Track, obsidian.track.Playlist]]) → None¶

Extends the queue by an iterable of Track .

Because this just called Queue.add() for each track in the iterable, Playlist will run this method recursively.

Parameters: tracks (Iterable[Union[Track, Playlist]]) – An iterable of tracks to add.

property full: bool¶

Whether or not this queue is full.

Type: bool

get() → obsidian.track.Track¶

Pops and returns the next track in the queue.

Returns: The track to play.
Return type: Track

insert(index: int, track: Union[obsidian.track.Track, obsidian.track.Playlist]) → None¶

Inserts a track at the given index.

Parameters

index (int) – The index to insert the track at.
track (Track) – The track to insert.

property internal_queue: collections.deque¶

The internal collections.deque class this queue uses.

Type: collections.deque

property max_size: Optional[int]¶

The max size of the queue, passed into the class constructor.

Type: Optional[int]

pop(index: int = 0) → obsidian.track.Track¶

The rough equivalent of Queue.remove() but is internally done differently.

Note: This removes from the left, not the right unlike regular Python lists. This is because queues would usually work like this.

Parameters: index (int, default: 0) – The index of the track to pop
Returns: The track that was popped.
Return type: Track

put(track: Union[obsidian.track.Track, obsidian.track.Playlist], *, left: bool = False) → None¶

Adds a Track or Playlist to the queue.

If a playlist is provided, the queue will extend from it’s tracks.

Parameters

track (Union[Track, Playlist]) – The track or playlist to add.
left (bool, default: False) – Whether or not to add this track to the beginning of the queue.

remove(track_or_index: Union[int, obsidian.track.Track]) → None¶

Removes a Track from the queue.

If a Track is provided, it will search and remove it, linearly. If an integer is provided, it will simply remove the track at that index.

Parameters: track_or_index (Union[int, Track]) – The track or index of the track to remove.

set(index: int, new: obsidian.track.Track) → None¶

Sets the track at the given index to the given track.

Parameters

index (int) – The index to overwrite.
new (Track) – The track to replace with.

skip() → obsidian.track.Track¶

Skips and returns the next track in the queue.

Returns: The next track to play.
Return type: Track

PointerBasedQueue¶

class obsidian.PointerBasedQueue(max_size: Optional[int] = None, *, cls: type = <class 'collections.deque'>, default_loop_type: obsidian.queue.LoopType = LoopType.NONE)¶

A certain type of queue that uses a pointer to point to a track in the queue, rather than popping tracks.

This allows for looping, therefore it is also implemented in this class.

add(track: Union[obsidian.track.Track, obsidian.track.Playlist], *, left: bool = False) → None¶

Adds a Track or Playlist to the queue.

If a playlist is provided, the queue will extend from it’s tracks.

Parameters

track (Union[Track, Playlist]) – The track or playlist to add.
left (bool, default: False) – Whether or not to add this track to the beginning of the queue.

append(track: Union[obsidian.track.Track, obsidian.track.Playlist], *, left: bool = False) → None¶

Adds a Track or Playlist to the queue.

If a playlist is provided, the queue will extend from it’s tracks.

Parameters

track (Union[Track, Playlist]) – The track or playlist to add.
left (bool, default: False) – Whether or not to add this track to the beginning of the queue.

clear() → None¶: Clears this queue and removes all tracks.

copy() → obsidian.queue.Queue¶

Copies this queue and returns a new queue with the same tracks.

Returns: The new, copied queue.
Return type: Queue

property count: int¶

The amount of tracks currently enqueued.

Type: int

property current: obsidian.track.Track¶

The current track the queue is pointing to.

Type: Track

extend(tracks: Iterable[Union[obsidian.track.Track, obsidian.track.Playlist]]) → None¶

Extends the queue by an iterable of Track .

Because this just called Queue.add() for each track in the iterable, Playlist will run this method recursively.

Parameters: tracks (Iterable[Union[Track, Playlist]]) – An iterable of tracks to add.

property full: bool¶

Whether or not this queue is full.

Type: bool

get() → Optional[obsidian.track.Track]¶

Retrieves the next track in the queue.

If the Queue is NONE and the queue has been exhausted, this will return None instead.

If the Queue is TRACK, this will return the same track playing. See PointerBasedQueue.skip() to skip the current track.

property index: int¶

The index of the current track.

Type: int

insert(index: int, track: Union[obsidian.track.Track, obsidian.track.Playlist]) → None¶

Inserts a track at the given index.

Parameters

index (int) – The index to insert the track at.
track (Track) – The track to insert.

property internal_queue: collections.deque¶

The internal collections.deque class this queue uses.

Type: collections.deque

property loop_type: obsidian.queue.LoopType¶

The Queue of the queue.

Type: Queue

property max_size: Optional[int]¶

The max size of the queue, passed into the class constructor.

Type: Optional[int]

pop(index: int = 0) → obsidian.track.Track¶

The rough equivalent of Queue.remove() but is internally done differently.

Note: This removes from the left, not the right unlike regular Python lists. This is because queues would usually work like this.

Parameters: index (int, default: 0) – The index of the track to pop
Returns: The track that was popped.
Return type: Track

put(track: Union[obsidian.track.Track, obsidian.track.Playlist], *, left: bool = False) → None¶

Adds a Track or Playlist to the queue.

If a playlist is provided, the queue will extend from it’s tracks.

Parameters

track (Union[Track, Playlist]) – The track or playlist to add.
left (bool, default: False) – Whether or not to add this track to the beginning of the queue.

remove(track_or_index: Union[int, obsidian.track.Track]) → None¶

Removes a Track from the queue.

If a Track is provided, it will search and remove it, linearly. If an integer is provided, it will simply remove the track at that index.

Parameters: track_or_index (Union[int, Track]) – The track or index of the track to remove.

set(index: int, new: obsidian.track.Track) → None¶

Sets the track at the given index to the given track.

Parameters

index (int) – The index to overwrite.
new (Track) – The track to replace with.

skip() → Optional[obsidian.track.Track]¶

Skips the current track in the queue.

This will always retrieve a new track (or None). See PointerBasedQueue.get() if you aren’t skipping the track.

This is different to PointerBasedQueue.get() as it will always skip the current track regardless of the LoopType.

Enums¶

class obsidian.enums.EventType(value)¶

This class is an enum.

Represents the type of event Obsidian has sent.

TRACK_START¶: A track has started.

TRACK_END¶: A track has ended.

TRACK_STUCK¶: A track has gotten stuck.

TRACK_EXCEPTION¶: There was an error while playing the track.

WEBSOCKET_OPEN¶: A websocket connection with Obsidian has been opened.

WEBSOCKET_CLOSED¶: A websocket connection with Obsidian has been closed.

class obsidian.enums.LoadType(value)¶

This class is an enum.

Represents load types that Obsidian sends.

NO_MATCHES¶: No matches were found.

LOAD_FAILED¶: Something went wrong while trying to load tracks.

PLAYLIST_LOADED¶: A playlist was loaded.

TRACK_LOADED¶: A track (or tracks) were loaded.

SEARCH_RESULT¶: A result from a search query was loaded.

class obsidian.enums.Source(value)¶

This class is an enum.

Represents a search source.

YOUTUBE¶: The search source for Youtube.

YOUTUBE_MUSIC¶: The search source for Youtube Music.

SOUNDCLOUD¶: The search source for Soundcloud.

SPOTIFY¶: The search soruce for Spotify. Your node must have a valid SpotifyClient in order to use this source.

YARN¶: The search source for Yarn.

BANDCAMP¶: The search source for Bandcamp.

TWITCH¶: The search source for Twitch.

VIMEO¶: The search source for Vimeo.

NICO¶: The search source Nico.

LOCAL¶: Searches your local files.

HTTP¶: If the query is a direct URL, allow them.

See also

Node.search_track(), Node.search_tracks()

class obsidian.enums.TrackEndReason(value)¶

This class is an enum.

Represents a reason on why a track has ended.

STOPPED¶: The track was manually stopped.

REPLACED¶: The track was replaced by another track.

CLEANUP¶: The track was cleared on cleanup.

LOAD_FAILED¶: The track failed to load.

FINISHED¶: The track finished.

See also

TrackEndEvent

class obsidian.enums.TrackExceptionSeverity(value)¶

This class is an enum.

Represents a severity rating for the exception from TrackExceptionEvent.

COMMON¶: A common exception occured.

SUSPICIOUS¶: A suspicious exception occured.

FAULT¶: A faulty exception occured.

Stats¶

class obsidian.Stats(data: Dict[str, Any])¶

Stats of a Obsidian node.

cpu_cores¶

cpu_process_load¶

cpu_system_load¶

heap_used_committed¶

heap_used_init¶

heap_used_max¶

heap_used_used¶

non_heap_used_committed¶

non_heap_used_init¶

non_heap_used_max¶

non_heap_used_used¶

players_active¶

players_total¶

threads_daemon¶

threads_peak¶

threads_running¶

threads_total_started¶

Exceptions and Errors¶

exception obsidian.errors.HTTPError(message: str, response: aiohttp.client_reqrep.ClientResponse)¶: Raised when an error via HTTP request occurs.

exception obsidian.errors.NoSearchMatchesFound(query: str)¶: Raised when no matches are found via search query.

exception obsidian.errors.NodeAlreadyExists(identifier: str)¶: Raised when a node with the same identifier already exists.

exception obsidian.errors.NodeCreationError¶: Raised when a node could not be successfully created.

exception obsidian.errors.NodeNotConnected¶: Raised when a socket request is sent without the node being connected.

exception obsidian.errors.ObsidianAuthorizationFailure(node, *args, **kwargs)¶: Raised when connecting fails due to invalid authorization.

exception obsidian.errors.ObsidianConnectionFailure(node, error: BaseException)¶

Raised when connecting fails.

node¶

The node that failed to connect.

Type: BaseNode

original¶

The exception that was raised.

Type: Exception

exception obsidian.errors.ObsidianException¶: Raised when an error related to this module occurs.

exception obsidian.errors.ObsidianSearchFailure¶: Raised when searching for a track fails.

exception obsidian.errors.ObsidianSpotifyException¶: Raised when an error related to spotify occurs.

exception obsidian.errors.SpotifyAuthorizationFailure(message: str, response: aiohttp.client_reqrep.ClientResponse)¶: Raised when authorizing to spotify fails.

exception obsidian.errors.SpotifyHTTPError(message: str, response: aiohttp.client_reqrep.ClientResponse)¶: Raised when an error via HTTP request [Spotify] occurs.