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

Copy Markdown View Source

Builds the data URI a soundboard sound is uploaded as.

A guild soundboard sound is not uploaded as a file: POST /guilds/{id}/soundboard-sounds takes the audio as a base64 data URI in the JSON body, the way an avatar takes image data. Discord accepts MP3 and Ogg there, up to 512 KiB and 5.2 seconds.

EDA.SoundData.from_path("airhorn.mp3")
#=> "data:audio/mpeg;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2..."

EDA.API.Soundboard.create/2 takes a path or raw bytes for :sound and converts them itself, so this is only needed when building a payload by hand.

The format comes from the bytes, not the filename

As with EDA.ImageData, the media type is read from the audio's own header and the extension is ignored, so a WAV saved as sound.mp3 is refused here instead of by Discord:

iex> EDA.SoundData.type("ID3" <> <<4, 0, 0>>)
{:ok, :mp3}

iex> EDA.SoundData.type("OggS" <> <<0>>)
{:ok, :ogg}

iex> EDA.SoundData.type("RIFF" <> <<0, 0, 0, 0>> <> "WAVE")
{:error, :unknown}

The size limit is checked too. The 5.2-second limit is not: measuring it means decoding the audio, and Discord reports it clearly enough.

Summary

Types

format()

An audio format Discord accepts for a soundboard sound.

Functions

coerce(value)

Coerces what a caller passed for :sound into a data URI: a ready-made URI is returned as is, recognisable audio bytes are encoded, and anything else is read as a path.

data_uri?(arg1)

Returns true for a data URI Discord would take as a sound.

from_binary(data)

Encodes audio bytes as a data URI, identifying MP3 or Ogg from the header.

from_path(path)

Reads an audio file and returns its data URI.

max_bytes()

The largest sound Discord accepts, in bytes.

type(data)

Identifies MP3 or Ogg audio by its header.

Types

format()

@type format() :: :mp3 | :ogg

An audio format Discord accepts for a soundboard sound.

Functions

coerce(value)

@spec coerce(String.t() | binary()) :: String.t()

Coerces what a caller passed for :sound into a data URI: a ready-made URI is returned as is, recognisable audio bytes are encoded, and anything else is read as a path.

iex> EDA.SoundData.coerce("data:audio/mpeg;base64,SUQz")
"data:audio/mpeg;base64,SUQz"

iex> EDA.SoundData.coerce("OggS")
"data:audio/ogg;base64,T2dnUw=="

data_uri?(arg1)

@spec data_uri?(term()) :: boolean()

Returns true for a data URI Discord would take as a sound.

iex> EDA.SoundData.data_uri?("data:audio/ogg;base64,T2dnUw==")
true

iex> EDA.SoundData.data_uri?("data:image/png;base64,AQID")
false

from_binary(data)

@spec from_binary(binary()) :: String.t()

Encodes audio bytes as a data URI, identifying MP3 or Ogg from the header.

Raises if the format is not one Discord accepts or the sound is over the size limit.

from_path(path)

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

Reads an audio file and returns its data URI.

Raises if the file does not exist, is not MP3 or Ogg, or is over the size limit.

max_bytes()

@spec max_bytes() :: pos_integer()

The largest sound Discord accepts, in bytes.

type(data)

@spec type(binary()) :: {:ok, format()} | {:error, :unknown}

Identifies MP3 or Ogg audio by its header.

MP3 is recognised by an ID3v2 tag or, for an untagged file, by the MPEG frame sync that opens it.

iex> EDA.SoundData.type(<<0xFF, 0xFB, 0x90, 0x00>>)
{:ok, :mp3}