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

Creates a guild soundboard sound. Requires CREATE_GUILD_EXPRESSIONS.

Options

• :name — required, 2–32 characters
• :sound — required: a path, raw MP3 or Ogg bytes, or a data URI; see EDA.SoundData. At most 512 KiB and 5.2 seconds
• :volume — 0 to 1, defaults to 1
• :emoji_id — a custom emoji for the sound
• :emoji_name — or a standard emoji, as its unicode character
• :reason — audit log reason

Example

EDA.API.Soundboard.create(guild_id, name: "airhorn", sound: "priv/airhorn.mp3", emoji_name: "📯")

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

Lists the default soundboard sounds, available to every user.

GET /soundboard-default-sounds

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

Deletes a guild soundboard sound. Same permissions as modify/3.

Options

• :reason — audit log reason

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

Gets one of a guild's soundboard sounds.

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

Lists a guild's soundboard sounds.

GET /guilds/{guild_id}/soundboard-sounds. Discord wraps the list as %{"items" => [...]}; this returns the list itself. Each sound carries its creator in "user" only when the bot has CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS.

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

Modifies a guild soundboard sound.

A sound the bot created needs CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS; any other needs MANAGE_GUILD_EXPRESSIONS. The audio itself cannot be changed.

Options

:name, :volume, :emoji_id, :emoji_name and :reason, as for create/2. A nil volume or emoji clears it.

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

Plays a soundboard sound into a voice channel.

POST /channels/{channel_id}/send-soundboard-sound. Discord only accepts it from a user in that channel, and neither muted, deafened nor suppressed — so the bot must have joined it with EDA.Voice.join/2 first. Requires SPEAK and USE_SOUNDBOARD, plus USE_EXTERNAL_SOUNDS for a sound from another guild. Everyone connected receives a VOICE_CHANNEL_EFFECT_SEND event.

Options

• :source_guild_id — the guild the sound belongs to, required to play one from another guild. Not needed for a default sound or one from this channel's guild

Example

EDA.API.Soundboard.send_sound(channel_id, "1")   # a default sound