High Level API¶

This section outlines the API of discodo.

Note

This module uses the Python logging module to log diagnostic and errors in an output independent way. If the logging module is not configured, logs will not be output anywhere. See Setting Up Logging for more information.

Client¶

class discodo.DPYClient(client)[source]¶

Represents a client connection that connects to Discodo. This class will interact with Discodo nodes.

Parameters

class (discord.Client) – The client of the bot with discord.py

Variables

Nodes (list) – The list of discodo.Node that is registered.
dispatcher (EventDispatcher) – The event dispatcher that the client dispatches events.
loop (asyncio.AbstractEventLoop) – The event loop that the client uses for operation.

async connect(channel: discord.channel.VoiceChannel, node: Optional[discodo.client.DPYClient.NodeClient] = None) → None[source]¶

Connect to the voice channel.

Parameters

channel (discord.VoiceChannel) – The channel to connect to.
node (Optional[discodo.Node]) – The node to connect with, defaults to getBestNode()

Raises

ValueError – The channel value has no guild property.
discodo.NodeNotConnected – There is no discodo node that is connected.
asyncio.TimeoutError – The connection is not established in 10 seconds.

Return type

discodo.VoiceClient

async destroy(guild: discord.guild.Guild) → None[source]¶

Destroy the voice client and disconnect from the voice channel

Parameters: guild (discord.Guild) – The guild to destroy the voice client.
Raises: discodo.VoiceClientNotFound – The voice client was not found.

async disconnect(guild: discord.guild.Guild) → None[source]¶

Disconnect from the voice channel.

Note

This coroutine doesn’t destroy the voice client. Recommand to use destroy()

Parameters: guild (discord.Guild) – The guild to disconnect from.

property event¶

A decorator that registers an event to listen to.

Parameters: event (str) – The event name to listen to.

getBestNode(exceptNode=None)[source]¶

Get the node with the fewest connected players.

Parameters: exceptNode (Optional[discodo.Node]) – The host to except from the list.
Return type: discodo.Node

getVC(guild, safe=False)[source]¶

Get a voice client from the guild.

Parameters

guild (int or discord.Guild) – Guild or guild ID from which to get the voice client.
safe (bool) – Whether to raise an exception when the voice client cannot be found, defaults to False.

Raises

discodo.VoiceClientNotFound – The voice client was not found and the safe value is False.

Return type

discodo.VoiceClient

getWebsocket(id)[source]¶

Get a websocket object of the shard from discord.py

Parameters: id (int) – The shard id to get a object.
Return type: discord.gateway.DiscordWebSocket

registerNode(host=None, port=None, password='hellodiscodo', region=None, launchOptions=None)[source]¶

Creates a websocket connection of the node and register it on the client.

If the value host or port is None, it will launch local node process.

Parameters

host (Optional[str]) – The host of the node to connect to.
port (Optional[int]) – The port of the node to connect to.
password (Optional[str]) – The password of the node to connect to, defaults to hellodiscodo.
region (Optional[str]) – The region of the node to connect to. This is like a annotation. It is not involved in the actual connection.
launchOptions (Optional[dict]) – The options to use when launching a local node

Returns

The scheduled task to connect with the node

Return type

asyncio.Task

property voiceClients¶

A property that returns all voice clients from all of connected nodes.

Return type: dict

Utils¶

class discodo.utils.EventDispatcher(loop: Optional[asyncio.events.AbstractEventLoop] = None)[source]¶

Represents an event dispatcher similar to EventEmitter

Variables: loop (Optional[asyncio.AbstractEventLoop]) – The event loop that the dispatcher uses for operation, defaults to asyncio.get_event_loop()

dispatch(event_: str, *args, **kwargs) → None[source]¶

Call the listeners which is matched with event name.

Parameters

event (str) – The event name to dispatch.
*args – An argument list of data to dispatch with.
*kwargs – A keyword argument list of data to dispatch with.

event(event: str)[source]¶

A decorator that registers an event to listen to.

Parameters: event (str) – The event name to listen to.

off(event: str, func: Callable)[source]¶

Remove the func function from the listeners list of the event

Parameters

event (str) – The event name to remove from.
func (Callable) – The function to remove from the list.

Return type

discodo.EventDispatcher

offAny(func: Callable)[source]¶

Remove the func function from the listeners list

Parameters: func (Callable) – The function to remove from the list.
Return type: discodo.EventDispatcher

on(event: str, func: Callable)[source]¶

Adds the func function to the end of the listeners list of the event

Parameters

event (str) – The event name to listen to.
func (Callable) – The function to call when event dispatching.

Return type

discodo.EventDispatcher

onAny(func: Callable)[source]¶

Adds the func function to the end of the listeners list

Parameters: func (Callable) – The function to call when event dispatching.
Return type: discodo.EventDispatcher

async wait_for(event: str, condition: Optional[Callable] = None, timeout: Optional[float] = None)[source]¶

Waits for an event that is matching with condition to be dispatched for timeout

Parameters

event (str) – The event name to wait for
condition (Optional[Callable]) – A predicate to check what to wait for. this function must return bool
timeout (Optional[float]) – The number of seconds to wait.

Raises

asyncio.TimeoutError – The timeout is provided and it was reached.

Return type

Any

discodo.utils.status.getCpuCount()[source]¶

Get cpu core count.

Return type: int

discodo.utils.status.getMemory()[source]¶

Get system memory usage. the unit is mega bytes.

Return type: int

discodo.utils.status.getNetworkInbound()[source]¶

Get network inbound counters. the unit is mega bytes.

Return type: int

discodo.utils.status.getNetworkOutbound()[source]¶

Get network outbound counters. the unit is mega bytes.

Return type: int

discodo.utils.status.getProcessCpu()[source]¶

Get process cpu usage. the unit is percent.

Return type: int

discodo.utils.status.getProcessMemory()[source]¶

Get process memory usage. the unit is mega bytes.

Return type: int

discodo.utils.status.getProcessThreads()[source]¶

Get process thread count.

Return type: int

discodo.utils.status.getStatus()[source]¶

Represents all information to dictionary

Return type: dict

discodo.utils.status.getTotalCpu()[source]¶

Get system cpu usage. the unit is percent.

Return type: int

class discodo.utils.CallbackList(iterable=(), /)[source]¶

A list that has callback when the value is changed.

static callback(name, *args)[source]¶: Override this function to use callback

tcp.getFreePort() → int¶

Get free port from the system.

Return type: int

Node¶

class discodo.Node(client, host, port, user_id, shard_id=None, password='hellodiscodo', region=None)[source]¶

Represents a discodo node connection.

Variables

client (discodo.DPYClient) – The client which the node is binded.
ws (Optional) – The websocket gateway the client is currently connected to.
dispatcher (EventDispatcher) – The event dispatcher that the client dispatches events.
loop (asyncio.AbstractEventLoop) – The event loop that the client uses for operation.
host (str) – The host of the node to connect to.
port (int) – The port of the node to connect to.
password (str) – The password of the node to connect to.
user_id (int) – This bot’s ID
shard_id (Optional[int]) – This bot’s shard ID, could be None
region (Optional[str]) – Region set when registering a node
voiceClients (dict) – A dictionary consisting of pairs of guild IDs and voice clients.

property URL: str¶

Represents the restful api url of the node.

Return type: str

property WS_URL: str¶

Represents the websocket url of the node.

Return type: str

async close()[source]¶: some action to do after disconnected from node

async connect()[source]¶

Connect to the node.

Raises: ValueError – The node is already connected.

async destroy()[source]¶: Destroy the node and remove from the client.

async discordDispatch(payload)[source]¶

Dispatch the discord payload to the node.

Note

If you are using discodo.DPYClient, you don’t have to use this.

Parameters: payload (dict) – The event data from the discord.

async getStatus()[source]¶

Get status like cpu usage from the node with websocket.

Return type: dict

getVC(guildID, safe=False)[source]¶

Get a voice client from the guild.

Parameters

guildID (int) – guild ID from which to get the voice client.
safe (bool) – Whether to raise an exception when the voice client cannot be found, defaults to False.

Raises

discodo.VoiceClientNotFound – The voice client was not found and the safe value is False.

Return type

discodo.VoiceClient

property is_connected: bool¶

Represents whether the node is connected.

Return type: bool

async send(op, data=None)[source]¶

Send websocket payload to the node

Parameters

op (str) – Operation name of the payload
data (Optional[dict]) – Operation data to send with

Raises

discodo.NodeNotConnected – The node is not connnected.

class discodo.Nodes(iterable=(), /)[source]¶

Represents a discodo node connection list.

You can also use it like list.

async connect()[source]¶

Try to connect to all registered nodes.

Return type: list

async getStatus()[source]¶

Try to get status from all registered nodes.

Return type: list

VoiceClient¶

class discodo.VoiceClient(Node, id, guild_id)[source]¶

Represents a voice connection of the guild.

Variables

Node (discodo.Node) – The node which the connection is connected with.
client (discodo.DPYClient) – The client which the connection is binded.
loop (asyncio.AbstractEventLoop) – The event loop that the client uses for operation.
id (str) – The id of the voice client, which is used on restful api.
guild_id (int) – The guild id which is connected to.
channel_id (Optional[int]) – The channel id which is connected to.
dispatcher (EventDispatcher) – The event dispatcher that the client dispatches events.
Queue (list) – The queue of the guild, it is synced to node and readonly.

property autoplay¶

Represents the autoplay state of this guild.

Return type: bool

property crossfade¶

Represents the crossfade duration of this guild.

Return type: float

async destroy()[source]¶: Destroy the client

async fetchContext()[source]¶

Fetch the context from the node.

Return type: dict

async fetchQueue(ws=True)[source]¶

Fetch queue to force refresh the internal queue.

Parameters: ws (Optional[bool]) – Whether to request queue on websocket or not.
Return type: list[AudioData or AudioSource]

async fetchState()[source]¶

Fetch current player state.

Return type: dict

property filter¶

Represents the autoplay state of this guild.

Note

For more information, check the documentation of the FFmpeg Filter

Return type: bool

async getCurrent()[source]¶

Fetch current playing source

Return type: AudioSource

async getOptions()[source]¶

Get options of the player

Return type: dict

async getSource(query)[source]¶

Search the query and get source from extractor

Parameters: query (str) – The query to search.
Return type: AudioData

async getSubtitle(*args, callback, **kwargs)[source]¶

Request to send synced subtitle to discodo node and handle event to callback function.

lang or url is required.

Parameters

callback (callable) – The callback function on subtitle event, must be coroutine function.
lang (Optional[str]) – The language to get subtitle.
url (Optional[str]) – The subtitle url to fetch.

Return type

dict

async loadSource(query)[source]¶

Search the query and put source to the queue

Parameters: query (str) – The query to search.
Return type: AudioData or list

async moveTo(node)[source]¶

Move the player’s current Node.

Parameters: node (discodo.Node) – The node to move to.

async pause()[source]¶: Pause the player

async putSource(source)[source]¶

Search the query and get sources from extractor

Parameters: source (AudioData or AudioSource or list) – The source to put on the queue.
Return type: AudioData or AudioSource or list

async query(op, data=None, event=None, timeout=10.0)[source]¶

Send websocket payload to the node with guild id and await response.

Parameters

op (str) – Operation name of the payload
data (Optional[dict]) – Operation data to send with
event (Optional[str]) – Event name to receive response, defaults to op
timeout (Optional[float]) – Seconds to wait for response

Raises

asyncio.TimeoutError – The query is timed out.
discodo.NodeException – The node returned some exceptions.

Return type

Any

async requestSubtitle(lang=None, url=None)[source]¶

Request to send synced subtitle to discodo node.

One of the parameters is required.

Parameters

lang (Optional[str]) – The language to get subtitle.
url (Optional[str]) – The subtitle url to fetch.

Return type

dict

async resume()[source]¶: Resume the player

async searchSources(query)[source]¶

Search the query and get sources from extractor

Parameters: query (str) – The query to search.
Return type: list[AudioData]

async seek(offset)[source]¶

Seek the player

Parameters: offset (float) – The position to seek

async send(op, data)[source]¶

Send websocket payload to the node with guild id

Parameters

op (str) – Operation name of the payload
data (Optional[dict]) – Operation data to send with

async setAutoplay(autoplay)[source]¶

Set autoplay state of the player

Parameters: autoplay (bool) – The autoplay state of the player to change.
Return type: dict

async setContext(data)[source]¶

Set the context to the node.

Parameters: data (dict) – The context to set.
Return type: dict

async setCrossfade(crossfade)[source]¶

Set crossfade of the player

Parameters: crossfade (float) – The crossfade of the player to change.
Return type: dict

async setFilter(filter)[source]¶

Set filter of the player

Parameters: crossfade (float) – The filter object of the player to change.
Return type: dict

async setOptions(**options)[source]¶

Set options of the player

Parameters

volume (Optional[float]) – The volume of the player to change.
crossfade (Optional[float]) – The crossfade of the player to change.
autoplay (Optional[bool]) – The autoplay state of the player to change.
filter (Optional[dict]) – The filter object of the player to change.

Return type

dict

async setVolume(volume)[source]¶

Set volume of the player

Parameters: volume (float) – The volume of the player to change.
Return type: dict

async shuffle()[source]¶

Shuffle the queue

Return type: list[AudioData or AudioSource]

async skip(offset=1)[source]¶

Skip the source

Parameters: offset (int) – how many to skip the sources

property volume¶

Represents the volume of this guild.

The maximum value is 2.0

Note

This value is a percentage with decimal points. For example, 100% is 1.0, and 5% is 0.05.

Return type: float

AudioData¶

class discodo.models.AudioData(VoiceClient, data)¶

Object with playback information

x == y: Checks if two AudioSources are equal.

x != y: Checks if two AudioSources are not equal.

Variables

tag (str) – The tag of the object
id (str) – The id of the source
title (Optional[str]) – The title of the source
webpage_url (Optional[str]) – The webpage url of the source
thumbnail (Optional[str]) – The thumbnail url of the source
url (Optional[str]) – The stream url of the source
duration (Optional[int]) – The duration of the source
is_live (bool) – Whether the source is live stream or not
uploader (Optional[str]) – The uploader of the source
description (Optional[str]) – The description of the source
subtitles (dict) – The description of the source
chapters (dict) – The description of the source
related (bool) – Whether this source is added by autoplay
context (dict) – The context of the object
start_position (float) – The start position of the source

async getContext()¶

Get the context from the node.

Return type: dict

async moveTo(index)¶

Move this source to index in the queue.

Parameters: index (int) – The index to move to
Return type: AudioData

async put()¶

Put the source into the queue.

Raises: ValueError – The source is already in the queue.
Return type: AudioData

async remove()¶

Remove this source from the queue.

Return type: AudioData

async seek(offset)¶

Seek this source to offset.

Parameters: offset (float) – The position to start playing
Return type: AudioData

async setContext(data)¶

Set the context to the node.

Parameters: data (dict) – The context to set.
Return type: dict

AudioSource¶

class discodo.models.AudioSource(VoiceClient, data)¶

Object with playback information that is loaded

x == y: Checks if two AudioSources are equal.

x != y: Checks if two AudioSources are not equal.

Variables

tag (str) – The tag of the object
id (str) – The id of the source
title (Optional[str]) – The title of the source
webpage_url (Optional[str]) – The webpage url of the source
thumbnail (Optional[str]) – The thumbnail url of the source
url (Optional[str]) – The stream url of the source
duration (float) – The duration of the source
is_live (bool) – Whether the source is live stream or not
uploader (Optional[str]) – The uploader of the source
description (Optional[str]) – The description of the source
subtitles (dict) – The description of the source
chapters (dict) – The description of the source
related (bool) – Whether this source is added by autoplay
context (dict) – The context of the object
start_position (float) – The start position of the source
seekable (bool) – Whether the source is seekable or not
position (Optional[float]) – The current position of the source

async getContext()¶

Get the context from the node.

Return type: dict

async setContext(data)¶

Set the context to the node.

Parameters: data (dict) – The context to set.
Return type: dict

Errors¶

exception discodo.DiscodoException[source]¶: The basic exception class of discodo

exception discodo.EncryptModeNotReceived[source]¶

Exception that is thrown when trying to send packet before receveing encrypt mode.

It’s only raise in DiscordVoiceClient

exception discodo.NotPlaying[source]¶: Exception that is thrown when trying to operate something while not playing.

exception discodo.VoiceClientNotFound[source]¶: Exception that is thrown when there is no voice client.

exception discodo.NoSearchResults[source]¶: Exception that is thrown when there is no search results.

exception discodo.OpusLoadError[source]¶: Exception that is thrown when loading libopus failed.

exception discodo.HTTPException(status: int, data=None)[source]¶

Exception that is thrown when HTTP operation failed.

Variables

status (int) – HTTP status code
description (str) – Description of the HTTP status code
message (str) – Server message with this request

exception discodo.Forbidden[source]¶: Exception that is thrown when HTTP status code is 403.

exception discodo.TooManyRequests[source]¶: Exception that is thrown when HTTP status code is 429.

exception discodo.NotSeekable[source]¶: Exception that is thrown when trying to seek the source which is not seekable.

exception discodo.NodeException(name, reason)[source]¶: Exception that is thrown when discodo node returns some exception.

exception discodo.NodeNotConnected[source]¶: Exception that is thrown when there is no discodo node that is connected.