EDA.SoundboardSound (EDA v0.5.0-beta.2)

Copy Markdown View Source

A soundboard sound: one of Discord's defaults, available to everyone, or a guild's own.

{:ok, sounds} = EDA.SoundboardSound.list(guild_id)
sound = Enum.find(sounds, &(&1.name == "airhorn"))
EDA.SoundboardSound.play(sound, voice_channel_id)

guild_id is nil for a default sound. available goes false when a guild loses the Server Boost level that allowed the sound. Default sound ids are small integers ("1", "2", …) rather than snowflakes.

The audio is served as MP3 or Ogg at url/1. Playing a sound needs the bot in the voice channel — see play/3. Managing guild sounds is in EDA.API.Soundboard.

Over the gateway

A guild's sounds arrive in GUILD_CREATE (soundboard_sounds), and changes arrive as GUILD_SOUNDBOARD_SOUND_CREATE, _UPDATE, _DELETE and GUILD_SOUNDBOARD_SOUNDS_UPDATE, under the :guild_expressions intent. request/1 asks the gateway for the sounds of several guilds at once, answered by one SOUNDBOARD_SOUNDS event per guild. EDA does not cache soundboard sounds; the events carry them.

Summary

Types

t()

Functions

default?(soundboard_sound)

Whether this is one of Discord's default sounds rather than a guild's.

default_sounds()

Lists Discord's default sounds, as structs.

fetch_sound(guild_id, sound_id)

Fetches one of a guild's soundboard sounds.

from_raw(raw)

Converts a raw soundboard sound map into this struct.

list(guild_id)

Lists a guild's soundboard sounds, as structs.

play(sound, channel_id, opts \\ [])

Plays a sound into a voice channel the bot has joined.

request(guild_ids)

Asks the gateway for the soundboard sounds of several guilds (opcode 31).

url(soundboard_sound)

The URL of the sound's audio file, MP3 or Ogg.

Types

t()

@type t() :: %EDA.SoundboardSound{
  available: boolean() | nil,
  emoji_id: String.t() | nil,
  emoji_name: String.t() | nil,
  guild_id: String.t() | nil,
  name: String.t() | nil,
  sound_id: String.t() | nil,
  user: EDA.User.t() | nil,
  volume: float() | nil
}

Functions

default?(soundboard_sound)

@spec default?(t()) :: boolean()

Whether this is one of Discord's default sounds rather than a guild's.

iex> EDA.SoundboardSound.default?(%EDA.SoundboardSound{sound_id: "1", guild_id: nil})
true

default_sounds()

@spec default_sounds() :: {:ok, [t()]} | {:error, term()}

Lists Discord's default sounds, as structs.

fetch_sound(guild_id, sound_id)

@spec fetch_sound(String.t() | integer(), String.t() | integer()) ::
  {:ok, t()} | {:error, term()}

Fetches one of a guild's soundboard sounds.

from_raw(raw)

@spec from_raw(map()) :: t()

Converts a raw soundboard sound map into this struct.

iex> EDA.SoundboardSound.from_raw(%{"sound_id" => "1", "name" => "quack", "volume" => 1.0, "emoji_name" => "🦆", "available" => true})
%EDA.SoundboardSound{sound_id: "1", name: "quack", volume: 1.0, emoji_name: "🦆", available: true}

list(guild_id)

@spec list(String.t() | integer()) :: {:ok, [t()]} | {:error, term()}

Lists a guild's soundboard sounds, as structs.

play(sound, channel_id, opts \\ [])

@spec play(t() | String.t() | integer(), String.t() | integer(), keyword()) ::
  :ok | {:error, term()}

Plays a sound into a voice channel the bot has joined.

Takes a struct or a sound id. For a guild sound played in another guild's channel, the struct supplies the source guild; with a bare id, pass source_guild_id:. See EDA.API.Soundboard.send_sound/3 for the permissions and voice state Discord requires.

:ok = EDA.Voice.join(guild_id, channel_id)
EDA.SoundboardSound.play(sound, channel_id)

request(guild_ids)

@spec request([String.t() | integer()]) :: :ok

Asks the gateway for the soundboard sounds of several guilds (opcode 31).

Each guild is answered by a SOUNDBOARD_SOUNDS event — an EDA.Event.SoundboardSounds holding its sounds. Requests go out on the shard that owns each guild. Returns :ok once sent; it does not wait for the answers.

EDA.SoundboardSound.request(["613425648685547541", "81384788765712384"])

url(soundboard_sound)

@spec url(t()) :: String.t()

The URL of the sound's audio file, MP3 or Ogg.

iex> EDA.SoundboardSound.url(%EDA.SoundboardSound{sound_id: "1"})
"https://cdn.discordapp.com/soundboard-sounds/1"