Specs

play(
  Nostrum.Struct.Guild.id(),
  String.t() | binary() | iodata() | Enum.t(),
  :url | :pipe | :ytdl | :raw | :raw_s,
  keyword()
) :: :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.
  • :raw Input will be an enumarable of raw opus frames. This bypasses ffmpeg and all options.
  • :raw_s Same as :raw but input must be stateful, i.e. calling Enum.take/2 on input is not idempotent.
• options - See options section below.

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

Options

• :start_pos (string) - The start position of the audio to be played. Defaults to beginning.
• :duration (string) - The duration to of the audio to be played . Defaults to entire duration.
• :realtime (boolean) - Make ffmpeg process the input in realtime instead of as fast as possible. Defaults to true.
• :volume (number) - The output volume of the audio. Default volume is 1.0.
• :filter (string) - Filter(s) to be applied to the audio. No filters applied by default.

The values of :start_pos and :duration can be any time duration that ffmpeg can read. The :filter can be used multiple times in a single call (see examples). The values of :filter can be any audio filters that ffmpeg can read. Filters will be applied in order and can be as complex as you want. The world is your oyster!

Note that using the :volume option is shortcut for the "volume" filter, and will be added to the end of the filter chain, acting as a master volume. Volume values between 0.0 and 1.0 act as standard oparating range where 0 is off and 1 is max. Values greater than 1.0 will add saturation and distortion to the audio. Negative values act the same as their position but reverse the polarity of the waveform.

Having all the ffmpeg audio filters available is extremely powerful so it may be worth learning some of them for your use cases. If you use any filters to increase the playback speed of your audio, it's recommended to set the :realtime option to false because realtime processing is relative to the original playback speed.

Examples

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

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

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

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

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,
...>   realtime: true, start_pos: "0:17", duration: "30")

iex> Nostrum.Voice.play(123456789, "https://www.youtube.com/watch?v=0ngcL_5ekXo", :ytdl,
...>   filter: "lowpass=f=1200", filter: "highpass=f=300", filter: "asetrate=44100*0.5")