![]() |
D++ (DPP)
C++ Discord API Bot Library
|
Implements a discord voice connection. Each discord_voice_client connects to one voice channel and derives from a websocket client. More...
Public Types | |
enum | send_audio_type_t { satype_recorded_audio, satype_live_audio, satype_overlap_audio } |
The audio type to be sent. More... | |
Public Member Functions | |
void | set_user_gain (snowflake user_id, float factor) |
Sets the gain for the specified user. More... | |
virtual void | log (dpp::loglevel severity, const std::string &msg) const |
Log a message to whatever log the user is using. The logged message is passed up the chain to the on_log event in user code which can then do whatever it wants to do with it. More... | |
virtual void | one_second_timer () |
Fires every second from the underlying socket I/O loop, used for sending heartbeats. More... | |
bool | is_ready () |
voice client is ready to stream audio. The voice client is considered ready if it has a secret key. More... | |
bool | is_connected () |
Returns true if the voice client is connected to the websocket. More... | |
dpp::utility::uptime | get_uptime () |
Returns the connection time of the voice client. More... | |
discord_voice_client (dpp::cluster *_cluster, snowflake _channel_id, snowflake _server_id, const std::string &_token, const std::string &_session_id, const std::string &_host) | |
virtual | ~discord_voice_client () |
Destroy the discord voice client object. More... | |
virtual bool | handle_frame (const std::string &buffer) |
Handle JSON from the websocket. More... | |
virtual void | error (uint32_t errorcode) |
Handle a websocket error. More... | |
void | run () |
Start and monitor I/O loop. More... | |
discord_voice_client & | send_audio_raw (uint16_t *audio_data, const size_t length) |
Send raw audio to the voice channel. More... | |
discord_voice_client & | send_audio_opus (uint8_t *opus_packet, const size_t length, uint64_t duration) |
Send opus packets to the voice channel. More... | |
discord_voice_client & | send_audio_opus (uint8_t *opus_packet, const size_t length) |
Send opus packets to the voice channel. More... | |
discord_voice_client & | send_silence (const uint64_t duration) |
Send silence to the voice channel. More... | |
discord_voice_client & | set_send_audio_type (send_audio_type_t type) |
Sets the audio type that will be sent with send_audio_* methods. More... | |
discord_voice_client & | set_timescale (uint64_t new_timescale) |
Set the timescale in nanoseconds. More... | |
uint64_t | get_timescale () |
Get the current timescale, this will default to 1000000 which means 1 millisecond. More... | |
discord_voice_client & | speak () |
Mark the voice connection as 'speaking'. This sends a JSON message to the voice websocket which tells discord that the user is speaking. The library automatically calls this for you whenever you send audio. More... | |
discord_voice_client & | pause_audio (bool pause) |
Pause sending of audio. More... | |
discord_voice_client & | stop_audio () |
Immediately stop all audio. Clears the packet queue. More... | |
discord_voice_client & | set_iteration_interval (uint16_t interval) |
Change the iteration interval time. More... | |
uint16_t | get_iteration_interval () |
Get the iteration interval time (in milliseconds). More... | |
bool | is_playing () |
Returns true if we are playing audio. More... | |
float | get_secs_remaining () |
Get the number of seconds remaining of the audio output buffer. More... | |
uint32_t | get_tracks_remaining () |
Get the number of tracks remaining in the output buffer. This is calculated by the number of track markers plus one. More... | |
dpp::utility::uptime | get_remaining () |
Get the time remaining to send the audio output buffer in hours:minutes:seconds. More... | |
discord_voice_client & | insert_marker (const std::string &metadata="") |
Insert a track marker into the audio output buffer. A track marker is an arbitrary flag in the buffer contents that indicates the end of some block of audio of significance to the sender. This may be a song from a streaming site, or some voice audio/speech, a sound effect, or whatever you choose. You can later skip to the next marker using the dpp::discord_voice_client::skip_to_next_marker function. More... | |
discord_voice_client & | skip_to_next_marker () |
Skip tp the next track marker, previously inserted by using the dpp::discord_voice_client::insert_marker function. If there are no markers in the output buffer, then this skips to the end of the buffer and is equivalent to the dpp::discord_voice_client::stop_audio function. More... | |
const std::vector< std::string > | get_marker_metadata () |
Get the metadata string associated with each inserted marker. More... | |
bool | is_paused () |
Returns true if the audio is paused. You can unpause with dpp::discord_voice_client::pause_audio. More... | |
std::string | discover_ip () |
Discord external IP detection. More... | |
virtual void | write (const std::string &data) |
Write to websocket. Encapsulates data in frames if the status is CONNECTED. More... | |
virtual bool | handle_buffer (std::string &buffer) |
Processes incoming frames from the SSL socket input buffer. More... | |
virtual void | close () |
Close websocket. More... | |
void | send_close_packet () |
Send OP_CLOSE error code 1000 to the other side of the connection. This indicates graceful close. More... | |
uint64_t | get_bytes_out () |
Get the bytes out objectGet total bytes sent. More... | |
uint64_t | get_bytes_in () |
Get total bytes received. More... | |
std::string | get_cipher () |
Get SSL cipher name. More... | |
void | read_loop () |
Nonblocking I/O loop. More... | |
Public Attributes | |
class dpp::cluster * | creator |
Owning cluster. More... | |
bool | terminating |
True when the thread is shutting down. More... | |
float | end_gain |
The gain value for the end of the current voice iteration. More... | |
float | current_gain |
The gain value for the current voice iteration. More... | |
float | increment |
The amount to increment each successive sample for, for the current voice iteration. More... | |
uint32_t | heartbeat_interval |
Heartbeat interval for sending heartbeat keepalive. More... | |
time_t | last_heartbeat |
Last voice channel websocket heartbeat. More... | |
std::thread::native_handle_type | thread_id |
Thread ID. More... | |
std::string | token |
Discord voice session token. More... | |
std::string | sessionid |
Discord voice session id. More... | |
snowflake | server_id |
Server ID. More... | |
moving_averager | moving_average |
Moving averager. More... | |
snowflake | channel_id |
Channel ID. More... | |
enum dpp::discord_voice_client::send_audio_type_t | send_audio_type |
uint16_t | iteration_interval {500} |
The time (in milliseconds) between each interval when parsing audio. More... | |
socket_callback_t | custom_readable_fd |
Attaching an additional file descriptor to this function will send notifications when there is data to read. More... | |
socket_callback_t | custom_writeable_fd |
Attaching an additional file descriptor to this function will send notifications when you are able to write to the socket. More... | |
socket_notification_t | custom_readable_ready |
This event will be called when you can read from the custom fd. More... | |
socket_notification_t | custom_writeable_ready |
This event will be called when you can write to a custom fd. More... | |
bool | keepalive |
True if we are keeping the connection alive after it has finished. More... | |
Static Public Attributes | |
static bool | sodium_initialised |
This needs to be static, we only initialise libsodium once per program start, so initialising it on first use in a voice connection is best. More... | |
Protected Member Functions | |
virtual void | connect () |
(Re)connect More... | |
ws_state | get_state () |
Get websocket state. More... | |
Protected Attributes | |
std::string | buffer |
Input buffer received from socket. More... | |
std::string | obuffer |
Output buffer for sending to socket. More... | |
bool | nonblocking |
True if in nonblocking mode. The socket switches to nonblocking mode once ReadLoop is called. More... | |
dpp::socket | sfd |
Raw file descriptor of connection. More... | |
openssl_connection * | ssl |
Openssl opaque contexts. More... | |
std::string | cipher |
SSL cipher in use. More... | |
time_t | last_tick |
For timers. More... | |
std::string | hostname |
Hostname connected to. More... | |
uint64_t | bytes_out |
Bytes out. More... | |
uint64_t | bytes_in |
Bytes in. More... | |
bool | plaintext |
True for a plain text connection. More... | |
bool | make_new |
True if we are establishing a new connection, false if otherwise. More... | |
Implements a discord voice connection. Each discord_voice_client connects to one voice channel and derives from a websocket client.
The audio type to be sent.
If the audio is recorded, the sending of audio packets is throttled. Otherwise, if the audio is live, the sending is not throttled.
Discord voice engine is expecting audio data as if they were from some audio device, e.g. microphone, where the data become available as they get captured from the audio device.
In case of recorded audio, unlike from a device, the audio data are usually instantly available in large chunks. Throttling is needed to simulate audio data coming from an audio device. In case of live audio, the throttling is by nature, so no extra throttling is needed.
Using live audio mode for recorded audio can cause Discord to skip audio data because Discord does not expect to receive, say, 3 minutes' worth of audio data in 1 second.
There are some inaccuracies in the throttling method used by the recorded audio mode on some systems (mainly Windows) which causes gaps and stutters in the resulting audio stream. The overlap audio mode provides a different implementation that fixes the issue. This method is slightly more CPU intensive, and should only be used if you encounter issues with recorded audio on your system.
Use discord_voice_client::set_send_audio_type to change this value as it ensures thread safety.
Enumerator | |
---|---|
satype_recorded_audio | |
satype_live_audio | |
satype_overlap_audio |
dpp::discord_voice_client::discord_voice_client | ( | dpp::cluster * | _cluster, |
snowflake | _channel_id, | ||
snowflake | _server_id, | ||
const std::string & | _token, | ||
const std::string & | _session_id, | ||
const std::string & | _host | ||
) |
Constructor takes shard id, max shards and token.
_cluster | The cluster which owns this voice connection, for related logging, REST requests etc |
_channel_id | The channel id to identify the voice connection as |
_server_id | The server id (guild id) to identify the voice connection as |
_token | The voice session token to use for identifying to the websocket |
_session_id | The voice session id to identify with |
_host | The voice server hostname to connect to (hostname:port format) |
dpp::voice_exception | Sodium or Opus failed to initialise, or D++ is not compiled with voice support |
|
virtual |
Destroy the discord voice client object.
|
virtualinherited |
Close websocket.
Reimplemented from dpp::ssl_client.
|
protectedvirtualinherited |
(Re)connect
Reimplemented from dpp::ssl_client.
std::string dpp::discord_voice_client::discover_ip | ( | ) |
Discord external IP detection.
|
virtual |
Handle a websocket error.
errorcode | The error returned from the websocket |
Reimplemented from dpp::websocket_client.
|
inherited |
Get total bytes received.
|
inherited |
Get the bytes out objectGet total bytes sent.
|
inherited |
Get SSL cipher name.
uint16_t dpp::discord_voice_client::get_iteration_interval | ( | ) |
Get the iteration interval time (in milliseconds).
const std::vector<std::string> dpp::discord_voice_client::get_marker_metadata | ( | ) |
Get the metadata string associated with each inserted marker.
dpp::utility::uptime dpp::discord_voice_client::get_remaining | ( | ) |
Get the time remaining to send the audio output buffer in hours:minutes:seconds.
float dpp::discord_voice_client::get_secs_remaining | ( | ) |
Get the number of seconds remaining of the audio output buffer.
|
protectedinherited |
Get websocket state.
uint64_t dpp::discord_voice_client::get_timescale | ( | ) |
Get the current timescale, this will default to 1000000 which means 1 millisecond.
uint32_t dpp::discord_voice_client::get_tracks_remaining | ( | ) |
Get the number of tracks remaining in the output buffer. This is calculated by the number of track markers plus one.
dpp::utility::uptime dpp::discord_voice_client::get_uptime | ( | ) |
Returns the connection time of the voice client.
|
virtualinherited |
Processes incoming frames from the SSL socket input buffer.
buffer | The buffer contents. Can modify this value removing the head elements when processed. |
Reimplemented from dpp::ssl_client.
|
virtual |
Handle JSON from the websocket.
buffer | The entire buffer content from the websocket client |
dpp::exception | If there was an error processing the frame, or connection to UDP socket failed |
Reimplemented from dpp::websocket_client.
discord_voice_client& dpp::discord_voice_client::insert_marker | ( | const std::string & | metadata = "" | ) |
Insert a track marker into the audio output buffer. A track marker is an arbitrary flag in the buffer contents that indicates the end of some block of audio of significance to the sender. This may be a song from a streaming site, or some voice audio/speech, a sound effect, or whatever you choose. You can later skip to the next marker using the dpp::discord_voice_client::skip_to_next_marker function.
metadata | Arbitrary information related to this track |
bool dpp::discord_voice_client::is_connected | ( | ) |
Returns true if the voice client is connected to the websocket.
bool dpp::discord_voice_client::is_paused | ( | ) |
Returns true if the audio is paused. You can unpause with dpp::discord_voice_client::pause_audio.
bool dpp::discord_voice_client::is_playing | ( | ) |
Returns true if we are playing audio.
bool dpp::discord_voice_client::is_ready | ( | ) |
voice client is ready to stream audio. The voice client is considered ready if it has a secret key.
|
virtual |
Log a message to whatever log the user is using. The logged message is passed up the chain to the on_log event in user code which can then do whatever it wants to do with it.
severity | The log level from dpp::loglevel |
msg | The log message to output |
Reimplemented from dpp::ssl_client.
|
virtual |
Fires every second from the underlying socket I/O loop, used for sending heartbeats.
dpp::exception | if the socket needs to disconnect |
Reimplemented from dpp::websocket_client.
discord_voice_client& dpp::discord_voice_client::pause_audio | ( | bool | pause | ) |
Pause sending of audio.
pause | True to pause, false to resume |
|
inherited |
Nonblocking I/O loop.
std::exception | Any std::exception (or derivative) thrown from read_loop() causes reconnection of the shard |
void dpp::discord_voice_client::run | ( | ) |
Start and monitor I/O loop.
discord_voice_client& dpp::discord_voice_client::send_audio_opus | ( | uint8_t * | opus_packet, |
const size_t | length | ||
) |
Send opus packets to the voice channel.
Some containers such as .ogg may contain OPUS encoded data already. In this case, we don't need to encode the frames using opus here. We can bypass the codec, only applying libsodium to the stream.
Duration is calculated internally
opus_packet | Opus packets. Discord expects opus frames to be encoded at 48000Hz |
length | The length of the audio data. |
dpp::voice_exception | If data length is invalid or voice support not compiled into D++ |
discord_voice_client& dpp::discord_voice_client::send_audio_opus | ( | uint8_t * | opus_packet, |
const size_t | length, | ||
uint64_t | duration | ||
) |
Send opus packets to the voice channel.
Some containers such as .ogg may contain OPUS encoded data already. In this case, we don't need to encode the frames using opus here. We can bypass the codec, only applying libsodium to the stream.
opus_packet | Opus packets. Discord expects opus frames to be encoded at 48000Hz |
length | The length of the audio data. |
duration | Generally duration is 2.5, 5, 10, 20, 40 or 60 if the timescale is 1000000 (1ms) |
dpp::voice_exception | If data length is invalid or voice support not compiled into D++ |
discord_voice_client& dpp::discord_voice_client::send_audio_raw | ( | uint16_t * | audio_data, |
const size_t | length | ||
) |
Send raw audio to the voice channel.
You should send an audio packet of send_audio_raw_max_length
(11520) bytes. Note that this function can be costly as it has to opus encode the PCM audio on the fly, and also encrypt it with libsodium.
audio_data | Raw PCM audio data. Channels are interleaved, with each channel's amplitude being a 16 bit value. |
length | The length of the audio data. The length should be a multiple of 4 (2x 16 bit stereo channels) with a maximum length of send_audio_raw_max_length , which is a complete opus frame at highest quality. |
Generally when you're streaming and you know there will be more packet to come you should always provide packet data with length of send_audio_raw_max_length
. Silence packet will be appended if length is less than send_audio_raw_max_length
as discord expects to receive such specific packet size. This can cause gaps in your stream resulting in distorted audio if you have more packet to send later on.
dpp::voice_exception | If data length is invalid or voice support not compiled into D++ |
|
inherited |
Send OP_CLOSE error code 1000 to the other side of the connection. This indicates graceful close.
discord_voice_client& dpp::discord_voice_client::send_silence | ( | const uint64_t | duration | ) |
Send silence to the voice channel.
duration | How long to send silence for. With the standard timescale this is in milliseconds. Allowed values are 2.5, 5, 10, 20, 40 or 60 milliseconds. |
dpp::voice_exception | if voice support is not compiled into D++ |
discord_voice_client& dpp::discord_voice_client::set_iteration_interval | ( | uint16_t | interval | ) |
Change the iteration interval time.
interval | The time (in milliseconds) between each interval when parsing audio. |
discord_voice_client& dpp::discord_voice_client::set_send_audio_type | ( | send_audio_type_t | type | ) |
Sets the audio type that will be sent with send_audio_* methods.
discord_voice_client& dpp::discord_voice_client::set_timescale | ( | uint64_t | new_timescale | ) |
Set the timescale in nanoseconds.
new_timescale | Timescale to set. This defaults to 1000000, which means 1 millisecond. |
dpp::voice_exception | If data length is invalid or voice support not compiled into D++ |
void dpp::discord_voice_client::set_user_gain | ( | snowflake | user_id, |
float | factor | ||
) |
Sets the gain for the specified user.
Similar to the User Volume slider, controls the listening volume per user. Uses native Opus gain control, so clients don't have to perform extra audio processing.
The gain setting will affect the both individual and combined voice audio.
The gain value can also be set even before the user connects to the voice channel.
user_id | The ID of the user where the gain is to be controlled. |
factor | Nonnegative factor to scale the amplitude by, where 1.f reverts to the default volume. |
discord_voice_client& dpp::discord_voice_client::skip_to_next_marker | ( | ) |
Skip tp the next track marker, previously inserted by using the dpp::discord_voice_client::insert_marker function. If there are no markers in the output buffer, then this skips to the end of the buffer and is equivalent to the dpp::discord_voice_client::stop_audio function.
discord_voice_client& dpp::discord_voice_client::speak | ( | ) |
Mark the voice connection as 'speaking'. This sends a JSON message to the voice websocket which tells discord that the user is speaking. The library automatically calls this for you whenever you send audio.
discord_voice_client& dpp::discord_voice_client::stop_audio | ( | ) |
Immediately stop all audio. Clears the packet queue.
|
virtualinherited |
Write to websocket. Encapsulates data in frames if the status is CONNECTED.
data | The data to send. |
Reimplemented from dpp::ssl_client.
|
protectedinherited |
Input buffer received from socket.
|
protectedinherited |
Bytes in.
|
protectedinherited |
Bytes out.
snowflake dpp::discord_voice_client::channel_id |
Channel ID.
|
protectedinherited |
SSL cipher in use.
class dpp::cluster* dpp::discord_voice_client::creator |
Owning cluster.
float dpp::discord_voice_client::current_gain |
The gain value for the current voice iteration.
|
inherited |
Attaching an additional file descriptor to this function will send notifications when there is data to read.
NOTE: Only hook this if you NEED it as it can increase CPU usage of the thread! Returning -1 means that you don't want to be notified.
|
inherited |
This event will be called when you can read from the custom fd.
|
inherited |
Attaching an additional file descriptor to this function will send notifications when you are able to write to the socket.
NOTE: Only hook this if you NEED it as it can increase CPU usage of the thread! You should toggle this to -1 when you do not have anything to write otherwise it'll keep triggering repeatedly (it is level triggered).
|
inherited |
This event will be called when you can write to a custom fd.
float dpp::discord_voice_client::end_gain |
The gain value for the end of the current voice iteration.
uint32_t dpp::discord_voice_client::heartbeat_interval |
Heartbeat interval for sending heartbeat keepalive.
|
protectedinherited |
Hostname connected to.
float dpp::discord_voice_client::increment |
The amount to increment each successive sample for, for the current voice iteration.
uint16_t dpp::discord_voice_client::iteration_interval {500} |
The time (in milliseconds) between each interval when parsing audio.
|
inherited |
True if we are keeping the connection alive after it has finished.
time_t dpp::discord_voice_client::last_heartbeat |
Last voice channel websocket heartbeat.
|
protectedinherited |
For timers.
|
protectedinherited |
True if we are establishing a new connection, false if otherwise.
moving_averager dpp::discord_voice_client::moving_average |
Moving averager.
|
protectedinherited |
True if in nonblocking mode. The socket switches to nonblocking mode once ReadLoop is called.
|
protectedinherited |
Output buffer for sending to socket.
|
protectedinherited |
True for a plain text connection.
enum dpp::discord_voice_client::send_audio_type_t dpp::discord_voice_client::send_audio_type |
snowflake dpp::discord_voice_client::server_id |
Server ID.
std::string dpp::discord_voice_client::sessionid |
Discord voice session id.
|
protectedinherited |
Raw file descriptor of connection.
|
static |
This needs to be static, we only initialise libsodium once per program start, so initialising it on first use in a voice connection is best.
|
protectedinherited |
Openssl opaque contexts.
bool dpp::discord_voice_client::terminating |
True when the thread is shutting down.
std::thread::native_handle_type dpp::discord_voice_client::thread_id |
Thread ID.
std::string dpp::discord_voice_client::token |
Discord voice session token.