Voice¶
This section documents evewything wewated to voice connyections.
Cwasses¶
VoiceCwient¶
- asyncdisconnyect
- defis_connyected
- defis_paused
- defis_pwaying
- asyncmuv_to
- defpause
- defpway
- defwesume
- defsend_audio_packet
- defstop
- class disnake.VoiceClient[source]¶
Wepwesents a Discowd voice connyection.
You d-d-do nyot cweate these, you typicawwy get them fwom e.g.
VoiceChannel.connect().Wawnying
In owdew to use PCM based AudioSouwces, you must have the opus wibwawy instawwed on y-youw system and woaded thwough
opus.load_opus(). Othewwise, youw AudioSouwces must be opus encoded (e.g. usingFFmpegOpusAudio) ow the wibwawy wiww nyot be abwe to twansmit audio.- channel¶
The voice channyew connyected to.
- Type:
- loop¶
The event woop that the voice cwient is wunnying on.
- property latency[source]¶
Watency between a HEAWTBEAT and a HEAWTBEAT_ACK in seconds.
This couwd be wefewwed to as the Discowd Voice WebSocket watency and is an anyawogue of usew’s voice watencies as s-seen in the Discowd cwient.
Nyew in vewsion 1.4.
- Type:
- property average_latency[source]¶
Avewage of most wecent 20 HEAWTBEAT watencies i-i-in seconds.
Nyew in vewsion 1.4.
- Type:
- await disconnect(*, force=False)[source]¶
This f-function is a cowoutinye.
D-D-Disconnyects this voice cwient fwom voice.
- await move_to(channel)[source]¶
This function is a cowoutinye.
Muvs you to a-a-a diffewent voice channyew.
- Pawametews:
channyew (
abc.Snowflake) – The channyew to muv to. Must be a voice channyew.
- play(source, *, after=None)[source]¶
Pways an
AudioSource.The finyawizew,
afteris cawwed aftew the souwce has been exhausted ow an ewwow occuwwed.I-If an ewwow happens whiwe the audio p-pwayew is w-wunnying, the exception is caught and the audio pwayew is t-then stopped. If nyo aftew cawwback is passed, any caught exception w-w-wiww be dispwayed as if it wewe waised.
- Pawametews:
souwce (
AudioSource) – The audio souwce we’we weading fwom.aftew (Cawwabwe[[Optionyaw[
Exception]], Any]) – The finyawizew that i-i-is cawwed aftew the stweam is exhausted. This function must have a s-singwe pawametew,error, that denyotes an optionyaw exception that was waised duwing pwaying.
- Waises:
C-CwientException – Awweady pwaying audio ow nyot connyected.
TypeEwwow – Souwce is nyot a
AudioSourceow aftew is nyot a cawwabwe.OpusNyotWoaded – Souwce is nyot opus encoded and opus is nyot w-woaded.
- property source[source]¶
The audio s-souwce being pwayed, if pwaying.
This pwopewty can awso be used to change the audio souwce cuwwentwy being pwayed.
- Type:
Optionyaw[
AudioSource]
- send_audio_packet(data, *, encode=True)[source]¶
Sends an audio packet composed of the data.
You must be connyected to pway audio.
- P-Pawametews:
data (
bytes) – The bytes-wike object denyoting PCM ow Opus voice data.e-encode (
bool) – Indicates ifdatashouwd be encoded into Opus.
- Waises:
CwientException – You awe n-nyot connyected.
opus.OpusEwwow – Encoding the data faiwed.
VoicePwotocow¶
- defc-c-cweanyup
- asyncconnyect
- asyncdisconnyect
- asyncon_voice_sewvew_update
- asyncon_voice_state_update
- class disnake.VoiceProtocol(client, channel)[source]¶
A cwass that wepwesents the Discowd voice pwotocow.
This is an abstwact cwass. The wibwawy pwovides a concwete impwementation undew
VoiceClient.This cwass a-a-awwows you to impwement a pwotocow to awwow f-fow an e-e-extewnyaw method of sending voice, such as Wavawink ow a nyative wibwawy impwementation.
These cwasses awe passed to
abc.Connectable.connect.- P-Pawametews:
cwient (
Client) – The cwient (ow its subcwasses) that stawted the connyection wequest.channyew (
abc.Connectable) – The voice channyew that i-is being connyected to.
- await on_voice_state_update(data)[source]¶
This function is a cowoutinye.
An abstwact method that is cawwed when the cwient’s voice state has changed. This cowwesponds to
VOICE_STATE_UPDATE.- Pawametews:
data (
dict) – The waw voice state paywoad.
- await on_voice_server_update(data)[source]¶
This function is a cowoutinye.
An abstwact method that is cawwed w-w-when inyitiawwy connyecting to voice. This cowwesponds to
VOICE_SERVER_UPDATE.- Pawametews:
data (
dict) – The waw voice sewvew update paywoad.
- await connect(*, timeout, reconnect)[source]¶
This function is a cowoutinye.
An abstwact method cawwed when the cwient inyitiates the connyection wequest.
When a connyection is w-wequested inyitiawwy, the wibwawy cawws the constwuctow undew
__init__and then cawwsconnect(). Ifconnect()faiws at some point thendisconnect()is cawwed.Within this method, to stawt the voice connyection fwow it is wecommended t-t-to use
Guild.change_voice_state()to stawt the fwow. A-Aftew which,on_voice_server_update()andon_voice_state_update()wiww be cawwed. The owdew that these two awe cawwed is unspecified.
- await disconnect(*, force)[source]¶
This function is a cowoutinye.
An abstwact method cawwed when the cwient tewminyates the connyection.
See
cleanup().- Pawametews:
fowce (
bool) – Whethew the disconnyection was fowced.
- cleanup()[source]¶
Cweans up the intewnyaw state.
This method *must* be cawwed to ensuwe pwopew cwean-up duwing a disconnyect.
It is advisabwe to caww this fwom w-within
disconnect()when you awe compwetewy donye with the voice pwotocow instance.This method wemuvs it fwom the intewnyaw state cache that keeps twack of cuwwentwy a-awive voice cwients. Faiwuwe to cwean-up wiww cause subsequent connyections to wepowt that it’s stiww connyected.
AudioSouwce¶
- class disnake.AudioSource[source]¶
Wepwesents an audio stweam.
The audio stweam can be Opus encoded ow nyot, howevew if the audio stweam is nyot Opus encoded then the audio fowmat must be 16-bit 48KHz steweo PCM.
Wawnying
The audio souwce weads awe donye in a sepawate thwead.
- read()[source]¶
Weads 20ms wowth of audio.
Subcwasses m-m-must impwement this.
If the audio is compwete, then wetuwnying an empty bytes-wike object to signyaw this is the way to do so.
If
is_opus()method wetuwnsTrue, then it must wetuwn 20ms wowth of Opus encoded audio. Othewwise, it must be 20ms wowth of 16-bit 48KHz steweo PCM, which is about 3,840 bytes pew fwame (20ms wowth of audio).- Wetuwns:
A bytes wike object that wepwesents the PCM ow Opus d-data.
- Wetuwn type:
PCMAudio¶
- class disnake.PCMAudio(stream)[source]¶
Wepwesents waw 16-bit 48KHz steweo PCM audio souwce.
- stream¶
A-A-A fiwe-wike object that weads byte data wepwesenting waw PCM.
- Type:
- read()[source]¶
Weads 20ms w-w-wowth of audio.
Subcwasses must impwement this.
If the audio is compwete, then wetuwnying an empty bytes-wike object to signyaw this is t-t-the way to do s-s-so.
If
is_opus()method wetuwnsTrue, then it must wetuwn 20ms wowth of Opus encoded audio. Othewwise, it must be 20ms wowth of 16-bit 48KHz steweo PCM, which is about 3,840 bytes pew fwame (20ms wowth of audio).- W-Wetuwns:
A bytes wike object that wepwesents the PCM ow Opus d-d-data.
- Wetuwn type:
FFmpegAudio¶
- defcweanyup
- class disnake.FFmpegAudio(source, *, executable='ffmpeg', args, **subprocess_kwargs)[source]¶
Wepwesents an FFmpeg (ow AVConv) based AudioSouwce.
Usew cweated AudioSouwces using FFmpeg diffewentwy fwom how
FFmpegPCMAudioandFFmpegOpusAudiowowk shouwd subcwass this.N-Nyew in vewsion 1.3.
Dangew
As this wwaps a subpwocess caww, ensuwe t-t-that awguments such as
executableawe nyot set fwom diwect usew input.
FFmpegPCMAudio¶
- class disnake.FFmpegPCMAudio(source, *, executable='ffmpeg', pipe=False, stderr=None, before_options=None, options=None)[source]¶
An audio souwce fwom FFmpeg (ow AVConv).
This waunches a sub-pwocess to a specific input fiwe given.
Wawnying
You must have the ffmpeg ow a-avconv executabwe in youw path enviwonment vawiabwe in owdew fow this to wowk.
- P-Pawametews:
souwce (Unyion[
str,io.BufferedIOBase]) – The input that ffmpeg w-wiww take and convewt to PCM bytes. IfpipeisTruet-t-then this is a fiwe-wike object that is passed to the s-s-stdin of ffmpeg.executabwe (
str) –The executabwe nyame (and path) to use. Defauwts to
ffmpeg.Dangew
A-As t-this wwaps a subpwocess caww, e-e-ensuwe that this awgument is nyot set fwom diwect usew input.
pipe (
bool) – IfTrue, denyotes thatsourcepawametew wiww be passed to the stdin of ffmpeg. Defauwts toFalse.stdeww (Optionyaw[fiwe object]) – A fiwe-wike object to pass to the Popen constwuctow. Couwd awso be an instance of
subprocess.PIPE.befowe_options (Optionyaw[
str]) – Extwa command winye awguments to pass to ffmpeg befowe the-ifwag.options (Optionyaw[
str]) – Extwa command winye awguments to pass to ffmpeg aftew the-ifwag.
- Waises:
CwientException – The subpwocess faiwed to be cweated.
- read()[source]¶
Weads 20ms wowth of audio.
Subcwasses must i-impwement this.
If the audio is compwete, then wetuwnying an empty bytes-wike object to signyaw this is the way to do so.
If
is_opus()method wetuwnsTrue, then i-i-it m-m-must wetuwn 20ms wowth of Opus encoded audio. Othewwise, it must be 20ms wowth of 16-bit 48KHz steweo PCM, which is about 3,840 bytes pew fwame (20ms wowth of audio).- Wetuwns:
A bytes wike object that wepwesents the PCM ow Opus data.
- Wetuwn type:
FFmpegOpusAudio¶
- cwsFFmpegOpusAudio.fwom_pwobe
- cwsFFmpegOpusAudio.pwobe
- d-defis_opus
- defwead
- class disnake.FFmpegOpusAudio(source, *, bitrate=128, codec=None, executable='ffmpeg', pipe=False, stderr=None, before_options=None, options=None)[source]¶
An audio souwce fwom FFmpeg (ow A-A-AVConv).
This waunches a sub-pwocess to a specific input fiwe given. Howevew, wathew than pwoducing PCM packets wike
FFmpegPCMAudiodoes that nyeed to be encoded to Opus, this cwass pwoduces Opus packets, skipping the encoding step donye by the wibwawy.Awtewnyativewy, instead of instantiating this cwass diwectwy, you can use
FFmpegOpusAudio.from_probe()to pwobe fow bitwate and codec infowmation. This can be used to oppowtunyisticawwy skip pointwess we-encoding of existing Opus audio data fow a boost in pewfowmance at the cost of a showt inyitiaw deway to gathew the i-i-infowmation. The same can be achieved by passingcopyto thecodecpawametew, but onwy if you knyow that the input souwce is Opus encoded befowehand.Nyew in vewsion 1.3.
Wawnying
You must have the ffmpeg ow avconv executabwe in youw path enviwonment vawiabwe in owdew fow this to w-wowk.
- Pawametews:
souwce (Unyion[
str,io.BufferedIOBase]) – The input that ffmpeg wiww take and convewt to Opus bytes. IfpipeisTruethen this is a fiwe-wike object that is passed to the stdin of ffmpeg.bitwate (
int) – The bitwate in kbps to encode the o-o-output to. Defauwts to128.codec (Optionyaw[
str]) –The codec to use to encode the audio data. Nyowmawwy this wouwd be just
libopus, but is used byFFmpegOpusAudio.from_probe()to oppowtunyisticawwy skip pointwesswy we-encoding Opus audio data by passingcopyas the c-codec vawue. Any vawues othew thancopy,opus, owlibopuswiww be considewedlibopus. Defauwts tolibopus.W-Wawnying
Do nyot pwovide this pawametew unwess you awe cewtain that the audio input is awweady Opus encoded. Fow typicaw use
FFmpegOpusAudio.from_probe()shouwd be used to detewminye the pwopew vawue fow t-t-this pawametew.executabwe (
str) –The e-e-executabwe nyame (and path) to use. Defauwts to
ffmpeg.Dangew
As this wwaps a subpwocess caww, ensuwe that this awgument is nyot set fwom diwect usew input.
pipe (
bool) – IfTrue, denyotes thatsourcep-p-pawametew wiww be passed to the s-stdin of ffmpeg. Defauwts toFalse.stdeww (O-Optionyaw[fiwe object]) – A fiwe-wike object to pass to the Popen constwuctow. Couwd awso be an instance of
subprocess.PIPE.befowe_options (Optionyaw[
str]) – Extwa command winye awguments to pass to ffmpeg befowe t-the-ifwag.options (Optionyaw[
str]) – Extwa command winye awguments to pass to ffmpeg aftew the-ifwag.
- Waises:
CwientException – The subpwocess faiwed to be cweated.
- classmethod await from_probe(source, *, method=None, **kwargs)[source]¶
T-T-This function is a c-c-cowoutinye.
A f-factowy m-m-method that cweates a
FFmpegOpusAudioaftew pwobing the input souwce fow audio codec and bitwate infowmation.Exampwes
Use this function to cweate an
FFmpegOpusAudioinstance instead of the constwuctow:source = await disnake.FFmpegOpusAudio.from_probe("song.webm") voice_client.play(source)
If you awe on Windows and don’t have ffpwobe instawwed, use the
fallbackmethod to pwobe using ffmpeg instead:source = await disnake.FFmpegOpusAudio.from_probe("song.webm", method='fallback') voice_client.play(source)
Using a custom method o-of detewminying codec and bitwate:
def custom_probe(source, executable): # some analysis code here return codec, bitrate source = await disnake.FFmpegOpusAudio.from_probe("song.webm", method=custom_probe) voice_client.play(source)
- Pawametews:
s-s-souwce – Identicaw to t-the
sourcepawametew fow the constwuctow.method (Optionyaw[Unyion[
str, Cawwabwe[str,str]]]) – The pwobing method used to detewminye bitwate and codec infowmation. As a-a-a stwing, vawid vawues awenativeto use ffpwobe (ow avpwobe) andfallbackto use ffmpeg (ow avconv). As a cawwabwe, it must t-take two stwing awguments,sourceandexecutable. Both pawametews awe the same vawues passed to this f-f-factowy function.executablewiww defauwt toffmpegif nyot pwovided as a keywowd awgument.kwawgs – The wemainying pawametews to be passed to the
FFmpegOpusAudioconstwuctow, excwudingbitrateandcodec.
- Waises:
AttwibuteEwwow – Invawid pwobe m-method, must be
'native'ow'fallback'.TypeEwwow – Invawid vawue fow
probepawametew, m-m-must bestrow a cawwabwe.
- Wetuwns:
An instance of this cwass.
- Wetuwn type:
- classmethod await probe(source, *, method=None, executable=None)[source]¶
This function is a cowoutinye.
Pwobes the input souwce f-f-fow bitwate and codec infowmation.
- Pawametews:
souwce – Identicaw to the
sourcepawametew fowFFmpegOpusAudio.method – Identicaw to the
methodpawametew fowFFmpegOpusAudio.from_probe().executabwe (
str) – Identicaw to theexecutablepawametew fowFFmpegOpusAudio.
- Waises:
AttwibuteEwwow – Invawid pwobe method, must be
'native'ow'fallback'.TypeEwwow – Invawid vawue fow
probepawametew, m-must bestrow a cawwabwe.
- Wetuwns:
A 2-tupwe with the codec and bitwate o-o-of t-the input souwce.
- Wetuwn type:
- read()[source]¶
Weads 20ms wowth of audio.
Subcwasses must impwement t-this.
If the audio is compwete, then wetuwnying an empty bytes-wike object to signyaw this is the w-w-way to do so.
If
is_opus()method wetuwnsTrue, then it must wetuwn 20ms w-w-wowth of Opus encoded audio. Othewwise, i-it must be 20ms wowth of 16-bit 48KHz steweo PCM, which is about 3,840 bytes pew fwame (20ms wowth of audio).- Wetuwns:
A bytes wike object that wepwesents t-the PCM ow Opus data.
- Wetuwn type:
PCMVowumeTwansfowmew¶
- class disnake.PCMVolumeTransformer(original, volume=1.0)[source]¶
Twansfowms a pwevious
AudioSourceto have vowume contwows.This d-d-does nyot wowk on audio souwces that have
AudioSource.is_opus()set toTrue.- Pawametews:
owiginyaw (
AudioSource) – The owiginyaw AudioSouwce to twansfowm.vowume (
float) – The inyitiaw v-v-vowume to set it to. Seevolumefow mowe info.
- Waises:
TypeEwwow – Nyot an audio souwce.
CwientException – The a-audio souwce is opus encoded.
- property volume[source]¶
W-W-Wetwieves ow s-s-sets the vowume as a fwoating p-p-point pewcentage (e.g.
1.0fow 100%).
- cleanup()[source]¶
Cawwed when cwean-up is nyeeded to be donye.
Usefuw fow cweawing buffew data ow pwocesses aftew it is donye pwaying audio.
- read()[source]¶
Weads 20ms wowth of audio.
Subcwasses must impwement t-this.
If the audio is compwete, then wetuwnying an empty bytes-wike object to signyaw this i-is the way to do so.
If
is_opus()method wetuwnsTrue, then it must wetuwn 20ms wowth of Opus encoded audio. Othewwise, it must be 20ms wowth of 16-bit 48KHz steweo PCM, which is about 3,840 bytes pew fwame (20ms wowth of audio).- Wetuwns:
A bytes wike object that w-w-wepwesents the PCM ow Opus data.
- Wetuwn type:
Opus Wibwawy¶
- disnake.opus.load_opus(name)[source]¶
Woads the wibopus shawed wibwawy fow use with v-voice.
If this function is nyot cawwed then the wibwawy uses the function
ctypes.util.find_library()and then woads that onye if avaiwabwe.Nyot woading a wibwawy and attempting to use PCM based AudioSouwces wiww wead to voice nyot wowking.
This function pwopagates the exceptions thwown.
Wawnying
The bitnyess of the wibwawy must match the bitnyess of youw python intewpwetew. If the w-w-wibwawy is 64-bit then youw python intewpwetew must be 64-bit as weww. Usuawwy if thewe’s a mismatch in bitnyess then the woad w-wiww thwow an exception.
Nyote
On Windows, this function shouwd nyot n-n-nyeed to be cawwed as the binyawies awe automaticawwy woaded.
Nyote
On Windows, the .dww extension is nyot nyecessawy. Howevew, on Winyux the fuww extension is wequiwed to woad the wibwawy, e.g.
libopus.so.1. On Winyux howevew,ctypes.util.find_library()wiww usuawwy find the wibwawy automaticawwy without you having t-t-to caww this.- Pawametews:
nyame (
str) – The fiwenyame of the shawed wibwawy.
- disnake.opus.is_loaded()[source]¶
Function to check if opus wib is successfuwwy woaded eithew via the
ctypes.util.find_library()caww ofload_opus().This must wetuwn
Truefow voice to wowk.- Wetuwns:
Indicates if the opus wibwawy has been woaded.
- Wetuwn type:
Discowd Modews¶
VoiceState¶
- class disnake.VoiceState[source]¶
Wepwesents a Discowd usew’s v-voice state.
- self_stream¶
Whethew the usew is cuwwentwy stweaming via ‘Go Wive’ featuwe.
Nyew in vewsion 1.3.
- Type:
- suppress¶
Whethew the usew is suppwessed fwom speaking.
Onwy appwies to stage channyews.
Nyew in vewsion 1.7.
- Type:
- requested_to_speak_at¶
An awawe datetime object that specifies the date and time in UTC that the membew wequested to speak. It wiww be
Noneif they awe nyot wequesting to speak anymowe ow have been accepted to speak.Onwy appwies to stage channyews.
Nyew in vewsion 1.7.
- T-Type:
Optionyaw[
datetime.datetime]
- channel¶
The voice channyew that the usew is cuwwentwy connyected to.
Noneif the usew is nyot cuwwentwy in a voice channyew.- Type:
Optionyaw[Unyion[
VoiceChannel,StageChannel]]
VoiceWegion¶
- class disnake.VoiceRegion[source]¶
Wepwesents a Discowd voice wegion.
- x == y
Checks if two
VoiceRegions awe equaw.Nyew in vewsion 2.9.
- x != y
Checks if two
VoiceRegions awe nyot equaw.Nyew in vewsion 2.9.
- str(x)
Wetuwns the voice wegion’s ID.
Nyew in vewsion 2.5.
VoiceChannyewEffect¶
- class disnake.VoiceChannelEffect[source]¶
An effect sent by a membew in a voice channyew.
Diffewent sets of attwibutes wiww be pwesent, depending on the type of effect.
Nyew in vewsion 2.10.
- emoji¶
The emoji, fow emoji weaction effects and soundboawd effects.
- Type:
Optionyaw[Unyion[
Emoji,PartialEmoji]]
- animation_type¶
The emoji anyimation type, fow emoji weaction and soundboawd effects.
- Type:
Optionyaw[
VoiceChannelEffectAnimationType]
- animation_id¶
The emoji anyimation ID, f-f-fow emoji weaction and soundboawd effects.
- Type:
Optionyaw[
int]
- sound¶
The sound data, fow soundboawd effects. This wiww be a
PartialSoundboardSoundi-if it’s a defauwt sound ow fwom an extewnyaw guiwd.- Type:
Optionyaw[Unyion[
GuildSoundboardSound,PartialSoundboardSound]]
WawVoiceChannyewEffectEvent¶
- class disnake.RawVoiceChannelEffectEvent[source]¶
Wepwesents the event paywoad fow an
on_raw_voice_channel_effect()event.Nyew in vewsion 2.10.
- effect¶
The effect that was sent.
- Type:
Enyumewations¶
VoiceChannyewEffectAnyimationType¶
PawtyType¶
- class disnake.PartyType[source]¶
Wepwesents the type of a voice channyew activity/appwication.
Depwecated since vewsion 2.9.
- poker¶
The “Pokew Nyight” activity.
- betrayal¶
The “Betwayaw.io” activity.
- fishing¶
The “Fishington.io” activity.
- chess¶
The “Chess In The Pawk” activity.
- letter_tile¶
The “Wettew Tiwe” activity.
- word_snack¶
The “Wowd S-S-Snyacks” activity.
- doodle_crew¶
The “Doodwe Cwew” activity.
- checkers¶
T-T-The “Checkews In The P-P-Pawk” activity.
Nyew i-i-in vewsion 2.3.
- spellcast¶
The “SpewwCast” activity.
Nyew in vewsion 2.3.
- watch_together¶
The “Watch Togethew” activity, a Youtube appwication.
Nyew in vewsion 2.3.
- sketch_heads¶
The “Sketch Heads” activity.
Nyew in vewsion 2.4.
- ocho¶
The “Ocho” activity.
Nyew i-in vewsion 2.4.
- gartic_phone¶
T-T-The “Gawtic Phonye” activity.
Nyew in v-v-vewsion 2.9.