SDL.Mixer

An alternative to withAudio, also initializes the SDL2_mixer API.

However, openAudio does not take care of automatically calling closeAudio after a computation ends, so you have to take care to do so manually.

Shut down and clean up the SDL2_mixer API.

After calling this, all audio stops.

You don't have to call this if you're using withAudio.

A mixing channel.

Use the Integral instance to define these: the first channel is 0, the second 1 and so on.

The default number of Channels available at startup is 8, so note that you cannot usemore than these starting 8 if you haven't created more with setChannels.

The starting Volume of each Channel is the maximum: 128.

Use this value when you wish to perform an operation on all Channels.

For more information, see each of the functions accepting a Channel.

Prepares a given number of Channels for use.

There are 8 such Channels already prepared for use after withAudio is called.

You may call this multiple times, even with sounds playing. If setting a lesser number of Channels than are currently in use, the higher Channels will be stopped, their finish callbacks invoked, and their memory freed. Passing in 0 or less will therefore stop and free all mixing channels.

Any Music playing is not affected by this function.

Gets the number of Channels currently in use.

Play a Chunk once, using the first available Channel.

Same as play, but keeps playing the Chunk forever.

How many times should a certain Chunk be played?

A shorthand for playing once.

A shorthand for looping a Chunk forever.

Same as play, but plays the Chunk using a given Channel a certain number of Times.

If AllChannels is used, then plays the Chunk using the first available Channel instead.

Returns the Channel that was used.

A time in milliseconds.

An upper limit of time, in milliseconds.

A lack of an upper limit.

Same as playOn, but imposes an upper limit in Milliseconds to how long the Chunk can play.

The playing may still stop before the limit is reached.

This is the most generic play function variant.

Same as play, but fades in the Chunk by making the Channel Volume start at 0 and rise to a full 128 over the course of a given number of Milliseconds.

The Chunk may end playing before the fade-in is complete, if it doesn't last as long as the given fade-in time.

Same as fadeIn, but allows you to specify the Channel to play on and how many Times to play it, similar to playOn.

If AllChannels is used, will play the Chunk on the first available Channel.

Returns the Channel that was used.

Same as fadeInOn, but imposes an upper Limit to how long the Chunk can play, similar to playLimit.

This is the most generic fade-in function variant.

Reserve a given number of Channels, starting from Channel 0.

A reserved Channel is considered not to be available for playing samples when using any play or fadeIn function variant with AllChannels. In other words, whenever you let SDL.Mixer pick the first available Channel itself, these reserved Channels will not be considered.

A group of Channels.

Grouping Channels together allows you to perform some operations on all of them at once.

By default, all Channels are members of the DefaultGroup.

The default Group all Channels are in the moment they are created.

Assigns a given Channel to a certain Group.

If DefaultGroup is used, assigns the Channel the the default starting Group (essentially ungrouping them).

If AllChannels is used, assigns all Channels to the given Group.

Returns whether the Channel was successfully grouped or not. Failure is poosible if the Channel does not exist, for instance.

Same as groupChannel, but groups all Channels between the first and last given, inclusive.

If DefaultGroup is used, assigns the entire Channel span to the default starting Group (essentially ungrouping them).

Using AllChannels is invalid.

Returns the number of Channels successfully grouped. This number may be less than the number of Channels given, for instance if some of them do not exist.

Returns the number of Channels within a Group.

If DefaultGroup is used, will return the number of all Channels, since all of them are within the default Group.

Gets the first inactive (not playing) Channel within a given Group, if any.

Using DefaultGroup will give you the first inactive Channel out of all that exist.

Gets the oldest actively playing Channel within a given Group.

Returns Nothing when the Group is empty or no Channels within it are playing.

Gets the newest actively playing Channel within a given Group.

Returns Nothing when the Group is empty or no Channels within it are playing.

Pauses the given Channel, if it is actively playing.

If AllChannels is used, will pause all actively playing Channels instead.

Note that paused Channels may still be halted.

Resumes playing a Channel, or all Channels if AllChannels is used.

Halts playback on a Channel, or all Channels if AllChannels is used.

Same as halt, but only does so after a certain number of Milliseconds.

If AllChannels is used, it will halt all the Channels after the given time instead.

Same as halt, but halts an entire Group instead.

Note that using DefaultGroup here is the same as calling halt AllChannels.

A volume, where 0 is silent and 128 loudest.

Volumes lesser than 0 or greater than 128 function as if they are 0 and 128, respectively.

A class of all values that have a Volume.

Returns whether the given Channel is playing or not.

If AllChannels is used, this returns whether any of the channels is currently playing.

Returns how many Channels are currently playing.

Returns whether the given Channel is paused or not.

If AllChannels is used, this returns whether any of the channels is currently paused.

Returns how many Channels are currently paused.

Gets the most recent Chunk played on a Channel, if any.

Using AllChannels is not valid here, and will return Nothing.

Note that the returned Chunk might be invalid if it was already freed.

Describes whether a Channel is fading in, out, or not at all.

Returns a Channel's Fading status.

Note that using AllChannels here is not valid, and will simply return the Fading status of the first Channel instead.

Gradually fade out a given playing Channel during the next Milliseconds, even if it is paused.

If AllChannels is used, fades out all the playing Channels instead.

Same as fadeOut, but fades out an entire Group instead.

Using DefaultGroup here is the same as calling fadeOut with AllChannels.

Sets a callback that gets invoked each time a Channel finishes playing.

A Channel finishes playing both when playback ends normally and when it is halted (also possibly via setChannels).

Note: don't call other SDL.Mixer functions within this callback.

Plays a given Music a certain number of Times.

The previously playing Music will be halted, unless it is fading out in which case a blocking wait occurs until it fades out completely.

A position in milliseconds within a piece of Music.

Plays a given Music a number of Times, but fading it in during a certain number of Milliseconds.

The fading only occurs during the first time the Music is played.

Same as fadeInMusic, but with a custom starting Music's Position.

Note that this only works on Music that setMusicPosition works on.

Same as fadeInMusicAt, but works with MOD Music.

Instead of milliseconds, specify the position with a pattern number.

Pauses Music playback, if it is actively playing.

You may still haltMusic paused Music.

Halts Music playback.

Resumes Music playback.

This works on both paused and halted Music.

If Music is currently actively playing, this has no effect.

Rewinds the Music to the beginning.

When playing new Music, it starts at the beginning by default.

This function only works with MOD, OGG, MP3 and NATIVEMIDI streams.

Set the Position for currently playing Music.

Note: this only works for OGG and MP3 Music.

Similar to setMusicPosition, but works only with MOD Music.

Pass in the pattern number.

Sets the Volume for Music.

Note that this won't work if any Music is currently fading.

Gets the current Volume setting for Music.

Returns whether a Music is currently playing or not.

Note that this returns True even if the Music is currently paused.

Returns whether a Music is currently paused or not.

Note that this returns False if the Music is currently halted.

Returns the Music's Fading status.

A Music's type.

Gets the MusicType of a given Music.

Gets the MusicType of currently playing Music, if any.

Gradually fade out the Music over a given number of Milliseconds.

The Music is set to fade out only when it is playing and not fading already.

Returns whether the Music was successfully set to fade out.

Sets a callback that gets invoked each time a Music finishes playing.

Note: don't call other SDL.Mixer functions within this callback.

Applies an in-built effect implementing panning.

Sets the left-channel and right-channel Volume to the given values.

This only works when Audio's Output is Stereo, which is the default.

Returns an action that, when executed, removes this effect. That action simply calls effectPan with Volumes 128 and 128.

Applies a different volume based on the distance (as Word8) specified.

The volume is loudest at distance 0, quietest at distance 255.

Returns an action that, when executed, removes this effect. That action simply calls effectDistance with a distance of 0.

Simulates a simple 3D audio effect.

Accepts the angle in degrees (as Int16) in relation to the source of the sound (0 is directly in front, 90 directly to the right, and so on) and a distance (as Word8) from the source of the sound (where 255 is very far away, and 0 extremely close).

Returns an action that, when executed, removes this effect. That action simply calls effectPosition with both angle and distance set to 0.

Swaps the left and right channel sound.

If given True, will swap the sound channels.

Returns an action that, when executed, removes this effect. That action simply calls effectReverseStereo with False.