Nostrum.Voice (Nostrum v0.4.6) View Source

Interface for playing audio through Discord's voice channels.

Using Discord Voice Channels

To play sound in Discord with Nostrum, you'll need ffmpeg to be installed. If you don't have the executable ffmpeg in the path, the absolute path may be configured through config keys :nostrum, :ffmpeg.

A bot may be connected to at most one voice channel per guild. For this reason, most of the functions in this module take a guild id, and the resulting action will be performed in the given guild's voice channel that the bot is connected to.

The primary Discord gateway responsible for all text based communication relies on one websocket connection per shard, where small bots typically only have one shard. The Discord voice gateways work by establishing a websocket connection per guild/channel. After some handshaking on this connection, audio data can be sent over UDP/RTP. Behind the scenes the voice websocket connections are implemented nearly the same way the main shard websocket connections are, and require no developer intervention.

Link to this section Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_channel_id(guild_id)

Gets the id of the voice channel that the bot is connected to.

join_channel(guild_id, channel_id, self_mute \\ false, self_deaf \\ false)

Joins or moves the bot to a voice channel.

leave_channel(guild_id)

Leaves the voice channel of the given guild id.

pause(guild_id)

Pauses the current sound being played in a voice channel.

play(guild_id, input, type \\ :url)

Plays sound in the voice channel the bot is in.

playing?(guild_id)

Checks if the bot is playing sound in a voice channel.

ready?(guild_id)

Checks if the connection is up and ready to play audio.

resume(guild_id)

Resumes playing the current paused sound in a voice channel.

stop(guild_id)

Stops the current sound being played in a voice channel.

Link to this section Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_channel_id(guild_id)

Specs

get_channel_id(Nostrum.Struct.Guild.id()) :: Nostrum.Struct.Channel.id()

Gets the id of the voice channel that the bot is connected to.

Parameters

guild_id - ID of guild that the resultant channel belongs to.

Returns the channel_id for the channel the bot is connected to, otherwise nil.

Examples

iex> Nostrum.Voice.join_channel(123456789, 420691337)

iex> Nostrum.Voice.get_channel(123456789)
420691337

iex> Nostrum.Voice.leave_channel(123456789)

iex> Nostrum.Voice.get_channel(123456789)
nil

join_channel(guild_id, channel_id, self_mute \\ false, self_deaf \\ false)

Specs

join_channel(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Channel.id(),
  boolean(),
  boolean()
) :: no_return() | :ok

Joins or moves the bot to a voice channel.

This function is equivalent to Nostrum.Api.update_voice_state/4.

leave_channel(guild_id)

Specs

leave_channel(Nostrum.Struct.Guild.id()) :: no_return() | :ok

Leaves the voice channel of the given guild id.

This function is equivalent to calling Nostrum.Api.update_voice_state(guild_id, nil).

pause(guild_id)

Specs

pause(Nostrum.Struct.Guild.id()) :: :ok | {:error, String.t()}

Pauses the current sound being played in a voice channel.

The bot must be connected to a voice channel in the guild specified.

Parameters

guild_id - ID of guild whose voice channel the sound will be paused in.

Returns {:error, reason} if unable to pause or no sound is playing, else :ok.

This function is similar to stop/1, except that the sound may be resumed after being paused.

Examples

iex> Nostrum.Voice.join_channel(123456789, 420691337)

iex> Nostrum.Voice.play(123456789, "~/files/twelve_hour_loop_of_waterfall_sounds.mp3")

iex> Nostrum.Voice.pause(123456789)

play(guild_id, input, type \\ :url)

Specs

play(
  Nostrum.Struct.Guild.id(),
  String.t() | binary() | iodata(),
  :url | :pipe | :ytdl
) :: :ok | {:error, String.t()}

Plays sound in the voice channel the bot is in.

The bot must be connected to a voice channel in the guild specified.

Parameters

guild_id - ID of guild whose voice channel the sound will be played in.
input - Audio to be played. Type of input determined by type parameter.
type - Type of input (defaults to :url).
- :url Input will be any url that ffmpeg can read.
- :pipe Input will be data that is piped to stdin of ffmpeg.
- :ytdl Input will be url for youtube-dl, which gets automatically piped to ffmpeg.

Returns {:error, reason} if unable to play or a sound is playing, else :ok.

Examples

iex> Nostrum.Voice.join_channel(123456789, 420691337)

iex> Nostrum.Voice.play(123456789, "~/music/FavoriteSong.mp3", :url)

iex> Nostrum.Voice.join_channel(123456789, 420691337)

iex> raw_data = File.read!("~/music/sound_effect.wav")

iex> Nostrum.Voice.play(123456789, raw_data, :pipe)

iex> Nostrum.Voice.join_channel(123456789, 420691337)

iex> Nostrum.Voice.play(123456789, "https://www.youtube.com/watch?v=b4RJ-QGOtw4", :ytdl)

playing?(guild_id)

Specs

playing?(Nostrum.Struct.Guild.id()) :: boolean()

Checks if the bot is playing sound in a voice channel.

Parameters

guild_id - ID of guild to check if audio being played.

Returns true if the bot is currently being played in a voice channel, otherwise false.

Examples

iex> Nostrum.Voice.join_channel(123456789, 420691337)

iex> Nostrum.Voice.play(123456789, "https://a-real-site.biz/RickRoll.m4a")

iex> Nostrum.Voice.playing?(123456789)
true

iex> Nostrum.Voice.pause(123456789)

iex> Nostrum.Voice.playing?(123456789)
false

ready?(guild_id)

Specs

ready?(Nostrum.Struct.Guild.id()) :: boolean()

Checks if the connection is up and ready to play audio.

Parameters

guild_id - ID of guild to check if voice connection is up.

Returns true if the bot is connected to a voice channel, otherwise false.

This function does not check if audio is already playing. For that, use playing?/1.

Examples

iex> Nostrum.Voice.join_channel(123456789, 420691337)

iex> Nostrum.Voice.ready?(123456789)
true

iex> Nostrum.Voice.leave_channel(123456789)

iex> Nostrum.Voice.ready?(123456789)
false

resume(guild_id)

Specs

resume(Nostrum.Struct.Guild.id()) :: :ok | {:error, String.t()}

Resumes playing the current paused sound in a voice channel.

The bot must be connected to a voice channel in the guild specified.

Parameters

guild_id - ID of guild whose voice channel the sound will be resumed in.

Returns {:error, reason} if unable to resume or no sound has been paused, otherwise returns :ok.

This function is used to resume a sound that had previously been paused.

Examples

iex> Nostrum.Voice.join_channel(123456789, 420691337)

iex> Nostrum.Voice.play(123456789, "~/stuff/Toto - Africa (Bass Boosted)")

iex> Nostrum.Voice.pause(123456789)

iex> Nostrum.Voice.resume(123456789)

stop(guild_id)

Specs

stop(Nostrum.Struct.Guild.id()) :: :ok | {:error, String.t()}

Stops the current sound being played in a voice channel.

The bot must be connected to a voice channel in the guild specified.

Parameters

guild_id - ID of guild whose voice channel the sound will be stopped in.

Returns {:error, reason} if unable to stop or no sound is playing, else :ok.

If a sound has finished playing, this function does not need to be called to start playing another sound.

Examples

iex> Nostrum.Voice.join_channel(123456789, 420691337)

iex> Nostrum.Voice.play(123456789, "http://brandthill.com/files/weird_dubstep_noises.mp3")

iex> Nostrum.Voice.stop(123456789)