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 noguild
property.discodo.NodeNotConnected – There is no discodo node that is connected.
asyncio.TimeoutError – The connection is not established in 10 seconds.
- Return type
- 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
- 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 isFalse
.- Return type
- 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
orport
isNone
, 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
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 theevent
- 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 theevent
- 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 fortimeout
- Parameters
- Raises
asyncio.TimeoutError – The timeout is provided and it was reached.
- Return type
Any
- discodo.utils.status.getMemory()[source]¶
Get system memory usage. the unit is mega bytes.
- Return type
- discodo.utils.status.getNetworkInbound()[source]¶
Get network inbound counters. the unit is mega bytes.
- Return type
- discodo.utils.status.getNetworkOutbound()[source]¶
Get network outbound counters. the unit is mega bytes.
- Return type
- discodo.utils.status.getProcessCpu()[source]¶
Get process cpu usage. the unit is percent.
- Return type
- discodo.utils.status.getProcessMemory()[source]¶
Get process memory usage. the unit is mega bytes.
- Return type
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.
- async connect()[source]¶
Connect to the node.
- Raises
ValueError – The node is already connected.
- 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.
- getVC(guildID, safe=False)[source]¶
Get a voice client from the guild.
- Parameters
- Raises
discodo.VoiceClientNotFound – The voice client was not found and the
safe
value isFalse
.- Return type
- async send(op, data=None)[source]¶
Send websocket payload to the node
- Parameters
- Raises
discodo.NodeNotConnected – The node is not connnected.
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.
- 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]
- property filter¶
Represents the autoplay state of this guild.
Note
For more information, check the documentation of the FFmpeg Filter
- Return type
- async getSubtitle(*args, callback, **kwargs)[source]¶
Request to send synced subtitle to discodo node and handle event to callback function.
lang
orurl
is required.
- async moveTo(node)[source]¶
Move the player’s current Node.
- Parameters
node (discodo.Node) – The node to move to.
- 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
- 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.
- async shuffle()[source]¶
Shuffle the queue
- Return type
list[AudioData or AudioSource]
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 moveTo(index)¶
Move this source to index in the queue.
- async put()¶
Put the source into the queue.
- Raises
ValueError – The source is already in the queue.
- Return type
- async seek(offset)¶
Seek this source to offset.
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
Errors¶
- 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.HTTPException(status: int, data=None)[source]¶
Exception that is thrown when HTTP operation failed.
- exception discodo.NotSeekable[source]¶
Exception that is thrown when trying to seek the source which is not seekable.