sdl2-mixer-1.2.0.0: Haskell bindings to SDL2_mixer

License | BSD3
Stability | experimental
Safe Haskell | None
Language | Haskell2010

SDL.Mixer

Contents

- Audio setup
  - Alternative
- Loading audio data
- Chunks
  - Playing chunks
  - Grouping channels
  - Controlling playback
  - Setting the volume
  - Querying for status
  - Fading out
  - Reacting to finish
- Music
  - Playing music
  - Controlling playback
  - Setting the volume
  - Querying for status
  - Fading out
  - Reacting to finish
- Effects
  - In-built effects
- Other

Description

Bindings to the `SDL2_mixer` library.

Synopsis

- withAudio :: (MonadBaseControl IO m, MonadIO m) => Audio -> ChunkSize -> m a -> m a
- data Audio = Audio {
  - audioFrequency :: Int
  - audioFormat :: Format
  - audioOutput :: Output
  }
- data Format
  - = FormatU8
  - | FormatS8
  - | FormatU16_LSB
  - | FormatS16_LSB
  - | FormatU16_MSB
  - | FormatS16_MSB
  - | FormatU16_Sys
  - | FormatS16_Sys
- data Output
  - = Mono
  - | Stereo
- defaultAudio :: Audio
- type ChunkSize = Int
- queryAudio :: MonadIO m => m Audio
- openAudio :: MonadIO m => Audio -> ChunkSize -> m ()
- closeAudio :: MonadIO m => m ()
- class Loadable a where
  - decode :: MonadIO m => ByteString -> m a
  - load :: MonadIO m => FilePath -> m a
  - free :: MonadIO m => a -> m ()
- newtype Chunk = Chunk (Ptr Chunk)
- chunkDecoders :: MonadIO m => m [String]
- newtype Music = Music (Ptr Music)
- musicDecoders :: MonadIO m => m [String]
- data Channel
- pattern AllChannels :: Channel
- setChannels :: MonadIO m => Int -> m ()
- getChannels :: MonadIO m => m Int
- play :: MonadIO m => Chunk -> m ()
- playForever :: MonadIO m => Chunk -> m ()
- data Times
- pattern Once :: Times
- pattern Forever :: Times
- playOn :: MonadIO m => Channel -> Times -> Chunk -> m Channel
- type Milliseconds = Int
- type Limit = Milliseconds
- pattern NoLimit :: Limit
- playLimit :: MonadIO m => Limit -> Channel -> Times -> Chunk -> m Channel
- fadeIn :: MonadIO m => Milliseconds -> Chunk -> m ()
- fadeInOn :: MonadIO m => Channel -> Times -> Milliseconds -> Chunk -> m Channel
- fadeInLimit :: MonadIO m => Limit -> Channel -> Times -> Milliseconds -> Chunk -> m Channel
- reserveChannels :: MonadIO m => Int -> m Int
- data Group
- pattern DefaultGroup :: Group
- group :: MonadIO m => Group -> Channel -> m Bool
- groupSpan :: MonadIO m => Group -> Channel -> Channel -> m Int
- groupCount :: MonadIO m => Group -> m Int
- getAvailable :: MonadIO m => Group -> m (Maybe Channel)
- getOldest :: MonadIO m => Group -> m (Maybe Channel)
- getNewest :: MonadIO m => Group -> m (Maybe Channel)
- pause :: MonadIO m => Channel -> m ()
- resume :: MonadIO m => Channel -> m ()
- halt :: MonadIO m => Channel -> m ()
- haltAfter :: MonadIO m => Milliseconds -> Channel -> m ()
- haltGroup :: MonadIO m => Group -> m ()
- type Volume = Int
- class HasVolume a where
  - getVolume :: MonadIO m => a -> m Volume
  - setVolume :: MonadIO m => Volume -> a -> m ()
- playing :: MonadIO m => Channel -> m Bool
- playingCount :: MonadIO m => m Int
- paused :: MonadIO m => Channel -> m Bool
- pausedCount :: MonadIO m => m Int
- playedLast :: MonadIO m => Channel -> m (Maybe Chunk)
- data Fading
- fading :: MonadIO m => Channel -> m Fading
- fadeOut :: MonadIO m => Milliseconds -> Channel -> m ()
- fadeOutGroup :: MonadIO m => Milliseconds -> Group -> m ()
- whenChannelFinished :: MonadIO m => (Channel -> IO ()) -> m ()
- playMusic :: MonadIO m => Times -> Music -> m ()
- type Position = Milliseconds
- fadeInMusic :: MonadIO m => Milliseconds -> Times -> Music -> m ()
- fadeInMusicAt :: MonadIO m => Position -> Milliseconds -> Times -> Music -> m ()
- fadeInMusicAtMOD :: MonadIO m => Int -> Milliseconds -> Times -> Music -> m ()
- pauseMusic :: MonadIO m => m ()
- haltMusic :: MonadIO m => m ()
- resumeMusic :: MonadIO m => m ()
- rewindMusic :: MonadIO m => m ()
- setMusicPosition :: MonadIO m => Position -> m ()
- setMusicPositionMOD :: MonadIO m => Int -> m ()
- setMusicVolume :: MonadIO m => Volume -> m ()
- getMusicVolume :: MonadIO m => m Volume
- playingMusic :: MonadIO m => m Bool
- pausedMusic :: MonadIO m => m Bool
- fadingMusic :: MonadIO m => m Fading
- data MusicType
  - = CMD
  - | WAV
  - | MOD
  - | MID
  - | OGG
  - | MP3
  - | FLAC
- musicType :: Music -> Maybe MusicType
- playingMusicType :: MonadIO m => m (Maybe MusicType)
- fadeOutMusic :: MonadIO m => Milliseconds -> m Bool
- whenMusicFinished :: MonadIO m => IO () -> m ()
- type Effect = Channel -> IOVector Word8 -> IO ()
- type EffectFinished = Channel -> IO ()
- pattern PostProcessing :: Channel
- effect :: MonadIO m => Channel -> EffectFinished -> Effect -> m (m ())
- effectPan :: MonadIO m => Channel -> Volume -> Volume -> m (m ())
- effectDistance :: MonadIO m => Channel -> Word8 -> m (m ())
- effectPosition :: MonadIO m => Channel -> Int16 -> Word8 -> m (m ())
- effectReverseStereo :: MonadIO m => Channel -> Bool -> m (m ())
- initialize :: (Foldable f, MonadIO m) => f InitFlag -> m ()
- data InitFlag
  - = InitFLAC
  - | InitMOD
  - | InitMP3
  - | InitOGG
- quit :: MonadIO m => m ()
- version :: (Integral a, MonadIO m) => m (a, a, a)

# Audio setup

In order to use the rest of the library, you need to supply `withAudio` or `openAudio` with an `Audio` configuration.

withAudio :: (MonadBaseControl IO m, MonadIO m) => Audio -> ChunkSize -> m a -> m a Source #

Initializes the `SDL2_mixer` API.

This should be the first function you call after initializing `SDL` itself with `InitAudio`.

Automatically cleans up the API when the inner computation finishes.

data Audio Source #

An audio configuration. Use this with `withAudio`.

Constructors

Audio |

Fields

- audioFrequency :: Int

  A sampling frequency.

- audioFormat :: Format

  An output sample format.

- audioOutput :: Output

  `Mono` or `Stereo` output.

#### Instances

Instances details

Default Audio Source # |
Instance details Defined in SDL.Mixer Methods def :: Audio #
Read Audio Source # |
Instance details Defined in SDL.Mixer Methods readsPrec :: Int -> ReadS Audio Source # readList :: ReadS [Audio] Source # readPrec :: ReadPrec Audio Source # readListPrec :: ReadPrec [Audio] Source #
Show Audio Source # |
Instance details Defined in SDL.Mixer Methods showsPrec :: Int -> Audio -> ShowS Source # show :: Audio -> String Source # showList :: [Audio] -> ShowS Source #
Eq Audio Source # |
Instance details Defined in SDL.Mixer Methods (==) :: Audio -> Audio -> Bool Source # (/=) :: Audio -> Audio -> Bool Source #

data Format Source #

A sample format.

Constructors

FormatU8 | Unsigned 8-bit samples.
FormatS8 | Signed 8-bit samples.
FormatU16_LSB | Unsigned 16-bit samples, in little-endian byte order.
FormatS16_LSB | Signed 16-bit samples, in little-endian byte order.
FormatU16_MSB | Unsigned 16-bit samples, in big-endian byte order.
FormatS16_MSB | signed 16-bit samples, in big-endian byte order.
FormatU16_Sys | Unsigned 16-bit samples, in system byte order.
FormatS16_Sys | Signed 16-bit samples, in system byte order.

#### Instances

Instances details

Bounded Format Source # |
Instance details Defined in SDL.Mixer Methods minBound :: Format Source # maxBound :: Format Source #
Read Format Source # |
Instance details Defined in SDL.Mixer Methods readsPrec :: Int -> ReadS Format Source # readList :: ReadS [Format] Source # readPrec :: ReadPrec Format Source # readListPrec :: ReadPrec [Format] Source #
Show Format Source # |
Instance details Defined in SDL.Mixer Methods showsPrec :: Int -> Format -> ShowS Source # show :: Format -> String Source # showList :: [Format] -> ShowS Source #
Eq Format Source # |
Instance details Defined in SDL.Mixer Methods (==) :: Format -> Format -> Bool Source # (/=) :: Format -> Format -> Bool Source #
Ord Format Source # |
Instance details Defined in SDL.Mixer Methods compare :: Format -> Format -> Ordering Source # (<) :: Format -> Format -> Bool Source # (<=) :: Format -> Format -> Bool Source # (>) :: Format -> Format -> Bool Source # (>=) :: Format -> Format -> Bool Source # max :: Format -> Format -> Format Source # min :: Format -> Format -> Format Source #

data Output Source #

The number of sound channels in output.

Constructors

Mono |
Stereo |

#### Instances

Instances details

Bounded Output Source # |
Instance details Defined in SDL.Mixer Methods minBound :: Output Source # maxBound :: Output Source #
Read Output Source # |
Instance details Defined in SDL.Mixer Methods readsPrec :: Int -> ReadS Output Source # readList :: ReadS [Output] Source # readPrec :: ReadPrec Output Source # readListPrec :: ReadPrec [Output] Source #
Show Output Source # |
Instance details Defined in SDL.Mixer Methods showsPrec :: Int -> Output -> ShowS Source # show :: Output -> String Source # showList :: [Output] -> ShowS Source #
Eq Output Source # |
Instance details Defined in SDL.Mixer Methods (==) :: Output -> Output -> Bool Source # (/=) :: Output -> Output -> Bool Source #
Ord Output Source # |
Instance details Defined in SDL.Mixer Methods compare :: Output -> Output -> Ordering Source # (<) :: Output -> Output -> Bool Source # (<=) :: Output -> Output -> Bool Source # (>) :: Output -> Output -> Bool Source # (>=) :: Output -> Output -> Bool Source # max :: Output -> Output -> Output Source # min :: Output -> Output -> Output Source #

defaultAudio :: Audio Source #

A default `Audio` configuration.

Same as `def`.

Uses 22050 as the `audioFrequency`, `FormatS16_Sys` as the `audioFormat` and `Stereo` as the `audioOutput`.

type ChunkSize = Int Source #

The size of each mixed sample.

The smaller this is, the more often callbacks will be invoked. If this is made too small on a slow system, the sounds may skip. If made too large, sound effects could lag.

queryAudio :: MonadIO m => m Audio Source #

Get the audio format in use by the opened audio device.

This may or may not match the `Audio` you asked for when calling `withAudio`.

## Alternative

openAudio :: MonadIO m => Audio -> ChunkSize -> m () Source #

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.

closeAudio :: MonadIO m => m () Source #

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`.

# Loading audio data

Use `load` or `decode` to get both `Chunk` and `Music` values.

class Loadable a where Source #

A class of all values that can be loaded from some source. You can load both `Chunk`s and `Music` this way.

Note that you must call `withAudio` before using these, since they have to know the audio configuration to properly convert the data for playback.

Minimal complete definition

decode, free

Methods

decode :: MonadIO m => ByteString -> m a Source #

Load the value from a `ByteString`.

load :: MonadIO m => FilePath -> m a Source #

Same as `decode`, but loads from a file instead.

free :: MonadIO m => a -> m () Source #

Frees the value's memory. It should no longer be used.

Note that you shouldn't free those values that are currently playing.

#### Instances

Instances details

Loadable Chunk Source # |
Instance details Defined in SDL.Mixer Methods decode :: MonadIO m => ByteString -> m Chunk Source # load :: MonadIO m => FilePath -> m Chunk Source # free :: MonadIO m => Chunk -> m () Source #
Loadable Music Source # |
Instance details Defined in SDL.Mixer Methods decode :: MonadIO m => ByteString -> m Music Source # load :: MonadIO m => FilePath -> m Music Source # free :: MonadIO m => Music -> m () Source #

newtype Chunk Source #

A loaded audio chunk.

Constructors

Chunk (Ptr Chunk) |

#### Instances

Instances details

Show Chunk Source # |
Instance details Defined in SDL.Mixer Methods showsPrec :: Int -> Chunk -> ShowS Source # show :: Chunk -> String Source # showList :: [Chunk] -> ShowS Source #
Eq Chunk Source # |
Instance details Defined in SDL.Mixer Methods (==) :: Chunk -> Chunk -> Bool Source # (/=) :: Chunk -> Chunk -> Bool Source #
HasVolume Chunk Source # |
Instance details Defined in SDL.Mixer Methods getVolume :: MonadIO m => Chunk -> m Volume Source # setVolume :: MonadIO m => Volume -> Chunk -> m () Source #
Loadable Chunk Source # |
Instance details Defined in SDL.Mixer Methods decode :: MonadIO m => ByteString -> m Chunk Source # load :: MonadIO m => FilePath -> m Chunk Source # free :: MonadIO m => Chunk -> m () Source #

chunkDecoders :: MonadIO m => m [String] Source #

Returns the names of all chunk decoders currently available.

These depend on the availability of shared libraries for each of the formats. The list may contain any of the following, and possibly others: `WAVE`, `AIFF`, `VOC`, `OFF`, `FLAC`, `MP3`.

newtype Music Source #

A loaded music file.

`Music` is played on a separate channel different from the normal mixing `Channel`s.

To manipulate `Music` outside of post-processing callbacks, use the music variant functions listed below.

Constructors

Music (Ptr Music) |

#### Instances

Instances details

Show Music Source # |
Instance details Defined in SDL.Mixer Methods showsPrec :: Int -> Music -> ShowS Source # show :: Music -> String Source # showList :: [Music] -> ShowS Source #
Eq Music Source # |
Instance details Defined in SDL.Mixer Methods (==) :: Music -> Music -> Bool Source # (/=) :: Music -> Music -> Bool Source #
Loadable Music Source # |
Instance details Defined in SDL.Mixer Methods decode :: MonadIO m => ByteString -> m Music Source # load :: MonadIO m => FilePath -> m Music Source # free :: MonadIO m => Music -> m () Source #

musicDecoders :: MonadIO m => m [String] Source #

Returns the names of all music decoders currently available.

These depend on the availability of shared libraries for each of the formats. The list may contain any of the following, and possibly others: `WAVE`, `MODPLUG`, `MIKMOD`, `TIMIDITY`, `FLUIDSYNTH`, `NATIVEMIDI`, `OGG`, `FLAC`, `MP3`.

# Chunks

`Chunk`s are played on `Channel`s, which can be combined into `Group`s.

## Playing chunks

data Channel Source #

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 `Channel`s 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.

#### Instances

Instances details

Enum Channel Source # |

Instance details

Defined in SDL.Mixer

Methods

succ :: Channel -> Channel Source #

pred :: Channel -> Channel Source #

toEnum :: Int -> Channel Source #

fromEnum :: Channel -> Int Source #

enumFrom :: Channel -> [Channel] Source #

enumFromThen :: Channel -> Channel -> [Channel] Source #

enumFromTo :: Channel -> Channel -> [Channel] Source #

enumFromThenTo :: Channel -> Channel -> Channel -> [Channel] Source #

Num Channel Source # |
Instance details Defined in SDL.Mixer Methods (+) :: Channel -> Channel -> Channel Source # (-) :: Channel -> Channel -> Channel Source # (*) :: Channel -> Channel -> Channel Source # negate :: Channel -> Channel Source # abs :: Channel -> Channel Source # signum :: Channel -> Channel Source # fromInteger :: Integer -> Channel Source #
Integral Channel Source # |
Instance details Defined in SDL.Mixer Methods quot :: Channel -> Channel -> Channel Source # rem :: Channel -> Channel -> Channel Source # div :: Channel -> Channel -> Channel Source # mod :: Channel -> Channel -> Channel Source # quotRem :: Channel -> Channel -> (Channel, Channel) Source # divMod :: Channel -> Channel -> (Channel, Channel) Source # toInteger :: Channel -> Integer Source #
Real Channel Source # |
Instance details Defined in SDL.Mixer Methods toRational :: Channel -> Rational Source #
Show Channel Source # |
Instance details Defined in SDL.Mixer Methods showsPrec :: Int -> Channel -> ShowS Source # show :: Channel -> String Source # showList :: [Channel] -> ShowS Source #
Eq Channel Source # |
Instance details Defined in SDL.Mixer Methods (==) :: Channel -> Channel -> Bool Source # (/=) :: Channel -> Channel -> Bool Source #
Ord Channel Source # |
Instance details Defined in SDL.Mixer Methods compare :: Channel -> Channel -> Ordering Source # (<) :: Channel -> Channel -> Bool Source # (<=) :: Channel -> Channel -> Bool Source # (>) :: Channel -> Channel -> Bool Source # (>=) :: Channel -> Channel -> Bool Source # max :: Channel -> Channel -> Channel Source # min :: Channel -> Channel -> Channel Source #
HasVolume Channel Source # |
Instance details Defined in SDL.Mixer Methods getVolume :: MonadIO m => Channel -> m Volume Source # setVolume :: MonadIO m => Volume -> Channel -> m () Source #

pattern AllChannels :: Channel Source #

Use this value when you wish to perform an operation on all `Channel`s.

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

setChannels :: MonadIO m => Int -> m () Source #

Prepares a given number of `Channel`s for use.

There are 8 such `Channel`s already prepared for use after `withAudio` is called.

You may call this multiple times, even with sounds playing. If setting a lesser number of `Channel`s than are currently in use, the higher `Channel`s 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.

getChannels :: MonadIO m => m Int Source #

Gets the number of `Channel`s currently in use.

play :: MonadIO m => Chunk -> m () Source #

Play a `Chunk` once, using the first available `Channel`.

playForever :: MonadIO m => Chunk -> m () Source #

Same as `play`, but keeps playing the `Chunk` forever.

data Times Source #

How many times should a certain `Chunk` be played?

#### Instances

Instances details

Enum Times Source # |
Instance details Defined in SDL.Mixer Methods succ :: Times -> Times Source # pred :: Times -> Times Source # toEnum :: Int -> Times Source # fromEnum :: Times -> Int Source # enumFrom :: Times -> [Times] Source # enumFromThen :: Times -> Times -> [Times] Source # enumFromTo :: Times -> Times -> [Times] Source # enumFromThenTo :: Times -> Times -> Times -> [Times] Source #
Num Times Source # |
Instance details Defined in SDL.Mixer Methods (+) :: Times -> Times -> Times Source # (-) :: Times -> Times -> Times Source # (*) :: Times -> Times -> Times Source # negate :: Times -> Times Source # abs :: Times -> Times Source # signum :: Times -> Times Source # fromInteger :: Integer -> Times Source #
Integral Times Source # |
Instance details Defined in SDL.Mixer Methods quot :: Times -> Times -> Times Source # rem :: Times -> Times -> Times Source # div :: Times -> Times -> Times Source # mod :: Times -> Times -> Times Source # quotRem :: Times -> Times -> (Times, Times) Source # divMod :: Times -> Times -> (Times, Times) Source # toInteger :: Times -> Integer Source #
Real Times Source # |
Instance details Defined in SDL.Mixer Methods toRational :: Times -> Rational Source #
Eq Times Source # |
Instance details Defined in SDL.Mixer Methods (==) :: Times -> Times -> Bool Source # (/=) :: Times -> Times -> Bool Source #
Ord Times Source # |
Instance details Defined in SDL.Mixer Methods compare :: Times -> Times -> Ordering Source # (<) :: Times -> Times -> Bool Source # (<=) :: Times -> Times -> Bool Source # (>) :: Times -> Times -> Bool Source # (>=) :: Times -> Times -> Bool Source # max :: Times -> Times -> Times Source # min :: Times -> Times -> Times Source #

pattern Once :: Times Source #

A shorthand for playing once.

pattern Forever :: Times Source #

A shorthand for looping a `Chunk` forever.

playOn :: MonadIO m => Channel -> Times -> Chunk -> m Channel Source #

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.

type Milliseconds = Int Source #

A time in milliseconds.

type Limit = Milliseconds Source #

An upper limit of time, in milliseconds.

pattern NoLimit :: Limit Source #

A lack of an upper limit.

playLimit :: MonadIO m => Limit -> Channel -> Times -> Chunk -> m Channel Source #

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.

fadeIn :: MonadIO m => Milliseconds -> Chunk -> m () Source #

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.

fadeInOn :: MonadIO m => Channel -> Times -> Milliseconds -> Chunk -> m Channel Source #

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.

fadeInLimit :: MonadIO m => Limit -> Channel -> Times -> Milliseconds -> Chunk -> m Channel Source #

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.

## Grouping channels

reserveChannels :: MonadIO m => Int -> m Int Source #

Reserve a given number of `Channel`s, 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 `Mixer` pick the first available `Channel` itself, these reserved `Channel`s will not be considered.

data Group Source #

A group of `Channel`s.

Grouping `Channel`s together allows you to perform some operations on all of them at once.

By default, all `Channel`s are members of the `DefaultGroup`.

#### Instances

Instances details

Enum Group Source # |
Instance details Defined in SDL.Mixer Methods succ :: Group -> Group Source # pred :: Group -> Group Source # toEnum :: Int -> Group Source # fromEnum :: Group -> Int Source # enumFrom :: Group -> [Group] Source # enumFromThen :: Group -> Group -> [Group] Source # enumFromTo :: Group -> Group -> [Group] Source # enumFromThenTo :: Group -> Group -> Group -> [Group] Source #
Num Group Source # |
Instance details Defined in SDL.Mixer Methods (+) :: Group -> Group -> Group Source # (-) :: Group -> Group -> Group Source # (*) :: Group -> Group -> Group Source # negate :: Group -> Group Source # abs :: Group -> Group Source # signum :: Group -> Group Source # fromInteger :: Integer -> Group Source #
Integral Group Source # |
Instance details Defined in SDL.Mixer Methods quot :: Group -> Group -> Group Source # rem :: Group -> Group -> Group Source # div :: Group -> Group -> Group Source # mod :: Group -> Group -> Group Source # quotRem :: Group -> Group -> (Group, Group) Source # divMod :: Group -> Group -> (Group, Group) Source # toInteger :: Group -> Integer Source #
Real Group Source # |
Instance details Defined in SDL.Mixer Methods toRational :: Group -> Rational Source #
Eq Group Source # |
Instance details Defined in SDL.Mixer Methods (==) :: Group -> Group -> Bool Source # (/=) :: Group -> Group -> Bool Source #
Ord Group Source # |
Instance details Defined in SDL.Mixer Methods compare :: Group -> Group -> Ordering Source # (<) :: Group -> Group -> Bool Source # (<=) :: Group -> Group -> Bool Source # (>) :: Group -> Group -> Bool Source # (>=) :: Group -> Group -> Bool Source # max :: Group -> Group -> Group Source # min :: Group -> Group -> Group Source #

pattern DefaultGroup :: Group Source #

The default `Group` all `Channel`s are in the moment they are created.

group :: MonadIO m => Group -> Channel -> m Bool Source #

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 `Channel`s to the given `Group`.

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

groupSpan :: MonadIO m => Group -> Channel -> Channel -> m Int Source #

Same as `groupChannel`, but groups all `Channel`s 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 `Channel`s successfully grouped. This number may be less than the number of `Channel`s given, for instance if some of them do not exist.

groupCount :: MonadIO m => Group -> m Int Source #

Returns the number of `Channels` within a `Group`.

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

getAvailable :: MonadIO m => Group -> m (Maybe Channel) Source #

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.

getOldest :: MonadIO m => Group -> m (Maybe Channel) Source #

Gets the oldest actively playing `Channel` within a given `Group`.

Returns `Nothing` when the `Group` is empty or no `Channel`s within it are playing.

getNewest :: MonadIO m => Group -> m (Maybe Channel) Source #

Gets the newest actively playing `Channel` within a given `Group`.

Returns `Nothing` when the `Group` is empty or no `Channel`s within it are playing.

## Controlling playback

pause :: MonadIO m => Channel -> m () Source #

Pauses the given `Channel`, if it is actively playing.

If `AllChannels` is used, will pause all actively playing `Channel`s instead.

Note that `pause`d `Channel`s may still be `halt`ed.

resume :: MonadIO m => Channel -> m () Source #

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

halt :: MonadIO m => Channel -> m () Source #

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

haltAfter :: MonadIO m => Milliseconds -> Channel -> m () Source #

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

If `AllChannels` is used, it will halt all the `Channel`s after the given time instead.

haltGroup :: MonadIO m => Group -> m () Source #

Same as `halt`, but halts an entire `Group` instead.

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

## Setting the volume

type Volume = Int Source #

A volume, where 0 is silent and 128 loudest.

`Volume`s lesser than 0 or greater than 128 function as if they are 0 and 128, respectively.

class HasVolume a where Source #

A class of all values that have a `Volume`.

Methods

getVolume :: MonadIO m => a -> m Volume Source #

Gets the value's currently set `Volume`.

If the value is a `Channel` and `AllChannels` is used, gets the average `Volume` of all `Channel`s.

setVolume :: MonadIO m => Volume -> a -> m () Source #

Sets a value's `Volume`.

If the value is a `Chunk`, the volume setting only takes effect when the `Chunk` is used on a `Channel`, being mixed into the output.

In case of being used on a `Channel`, the volume setting takes effect during the final mix, along with the `Chunk` volume. For instance, setting the `Volume` of a certain `Channel` to 64 will halve the volume of all `Chunk`s played on that `Channel`. If `AllChannels` is used, sets all `Channel`s to the given `Volume` instead.

#### Instances

Instances details

HasVolume Channel Source # |
Instance details Defined in SDL.Mixer Methods getVolume :: MonadIO m => Channel -> m Volume Source # setVolume :: MonadIO m => Volume -> Channel -> m () Source #
HasVolume Chunk Source # |
Instance details Defined in SDL.Mixer Methods getVolume :: MonadIO m => Chunk -> m Volume Source # setVolume :: MonadIO m => Volume -> Chunk -> m () Source #

## Querying for status

playing :: MonadIO m => Channel -> m Bool Source #

Returns whether the given `Channel` is playing or not.

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

playingCount :: MonadIO m => m Int Source #

Returns how many `Channel`s are currently playing.

paused :: MonadIO m => Channel -> m Bool Source #

Returns whether the given `Channel` is paused or not.

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

pausedCount :: MonadIO m => m Int Source #

Returns how many `Channel`s are currently paused.

playedLast :: MonadIO m => Channel -> m (Maybe Chunk) Source #

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 `free`d.

data Fading Source #

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

#### Instances

Instances details

Read Fading Source # |
Instance details Defined in SDL.Mixer Methods readsPrec :: Int -> ReadS Fading Source # readList :: ReadS [Fading] Source # readPrec :: ReadPrec Fading Source # readListPrec :: ReadPrec [Fading] Source #
Show Fading Source # |
Instance details Defined in SDL.Mixer Methods showsPrec :: Int -> Fading -> ShowS Source # show :: Fading -> String Source # showList :: [Fading] -> ShowS Source #
Eq Fading Source # |
Instance details Defined in SDL.Mixer Methods (==) :: Fading -> Fading -> Bool Source # (/=) :: Fading -> Fading -> Bool Source #
Ord Fading Source # |
Instance details Defined in SDL.Mixer Methods compare :: Fading -> Fading -> Ordering Source # (<) :: Fading -> Fading -> Bool Source # (<=) :: Fading -> Fading -> Bool Source # (>) :: Fading -> Fading -> Bool Source # (>=) :: Fading -> Fading -> Bool Source # max :: Fading -> Fading -> Fading Source # min :: Fading -> Fading -> Fading Source #

fading :: MonadIO m => Channel -> m Fading Source #

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.

## Fading out

fadeOut :: MonadIO m => Milliseconds -> Channel -> m () Source #

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

If `AllChannels` is used, fades out all the playing `Channel`s instead.

fadeOutGroup :: MonadIO m => Milliseconds -> Group -> m () Source #

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

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

## Reacting to finish

whenChannelFinished :: MonadIO m => (Channel -> IO ()) -> m () Source #

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 `halt`ed (also possibly via `setChannels`).

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

# Music

`Chunk`s and `Music` differ by the way they are played. While multiple `Chunk`s can be played on different desired `Channel`s at the same time, there can only be one `Music` playing at the same time.

Therefore, the functions used for `Music` are separate.

## Playing music

playMusic :: MonadIO m => Times -> Music -> m () Source #

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.

type Position = Milliseconds Source #

A position in milliseconds within a piece of `Music`.

fadeInMusic :: MonadIO m => Milliseconds -> Times -> Music -> m () Source #

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.

fadeInMusicAt :: MonadIO m => Position -> Milliseconds -> Times -> Music -> m () Source #

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

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

fadeInMusicAtMOD :: MonadIO m => Int -> Milliseconds -> Times -> Music -> m () Source #

Same as `fadeInMusicAt`, but works with `MOD` `Music`.

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

## Controlling playback

pauseMusic :: MonadIO m => m () Source #

Pauses `Music` playback, if it is actively playing.

You may still `haltMusic` paused `Music`.

haltMusic :: MonadIO m => m () Source #

Halts `Music` playback.

resumeMusic :: MonadIO m => m () Source #

Resumes `Music` playback.

This works on both paused and halted `Music`.

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

rewindMusic :: MonadIO m => m () Source #

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.

setMusicPosition :: MonadIO m => Position -> m () Source #

Set the `Position` for currently playing `Music`.

Note: this only works for `OGG` and `MP3` `Music`.

setMusicPositionMOD :: MonadIO m => Int -> m () Source #

Similar to `setMusicPosition`, but works only with `MOD` `Music`.

Pass in the pattern number.

## Setting the volume

setMusicVolume :: MonadIO m => Volume -> m () Source #

Sets the `Volume` for `Music`.

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

getMusicVolume :: MonadIO m => m Volume Source #

Gets the current `Volume` setting for `Music`.

## Querying for status

playingMusic :: MonadIO m => m Bool Source #

Returns whether a `Music` is currently playing or not.

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

pausedMusic :: MonadIO m => m Bool Source #

Returns whether a `Music` is currently paused or not.

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

fadingMusic :: MonadIO m => m Fading Source #

Returns the `Music`'s `Fading` status.

data MusicType Source #

A `Music`'s type.

Constructors

CMD |
WAV |
MOD |
MID |
OGG |
MP3 |
FLAC |

#### Instances

Instances details

Bounded MusicType Source # |
Instance details Defined in SDL.Mixer Methods minBound :: MusicType Source # maxBound :: MusicType Source #
Read MusicType Source # |
Instance details Defined in SDL.Mixer Methods readsPrec :: Int -> ReadS MusicType Source # readList :: ReadS [MusicType] Source # readPrec :: ReadPrec MusicType Source # readListPrec :: ReadPrec [MusicType] Source #
Show MusicType Source # |
Instance details Defined in SDL.Mixer Methods showsPrec :: Int -> MusicType -> ShowS Source # show :: MusicType -> String Source # showList :: [MusicType] -> ShowS Source #
Eq MusicType Source # |
Instance details Defined in SDL.Mixer Methods (==) :: MusicType -> MusicType -> Bool Source # (/=) :: MusicType -> MusicType -> Bool Source #
Ord MusicType Source # |
Instance details Defined in SDL.Mixer Methods compare :: MusicType -> MusicType -> Ordering Source # (<) :: MusicType -> MusicType -> Bool Source # (<=) :: MusicType -> MusicType -> Bool Source # (>) :: MusicType -> MusicType -> Bool Source # (>=) :: MusicType -> MusicType -> Bool Source # max :: MusicType -> MusicType -> MusicType Source # min :: MusicType -> MusicType -> MusicType Source #

musicType :: Music -> Maybe MusicType Source #

Gets the `MusicType` of a given `Music`.

playingMusicType :: MonadIO m => m (Maybe MusicType) Source #

Gets the `MusicType` of currently playing `Music`, if any.

## Fading out

fadeOutMusic :: MonadIO m => Milliseconds -> m Bool Source #

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.

## Reacting to finish

whenMusicFinished :: MonadIO m => IO () -> m () Source #

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

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

# Effects

type Effect = Channel -> IOVector Word8 -> IO () Source #

A post-processing effect as a function operating on a mutable stream.

Note that, at the moment, this is a stream of bytes. Depending on the `Audio` `Format` you're using, you're probably going to want to treat is as a stream of 16-bit values instead.

type EffectFinished = Channel -> IO () Source #

A function called when a processor is finished being used.

This allows you to clean up any state you might have had.

pattern PostProcessing :: Channel Source #

A way to refer to the special `Channel` used for post-processing effects.

You can only use this value with `effect` and the other in-built effect functions such as `effectPan` and `effectDistance`.

effect :: MonadIO m => Channel -> EffectFinished -> Effect -> m (m ()) Source #

Adds a post-processing `Effect` to a certain `Channel`.

A `Channel`'s `Effect`s are called in the order they were added.

Returns an action that, when executed, removes this `Effect`. Note: do execute this returned action more than once.

## In-built effects

effectPan :: MonadIO m => Channel -> Volume -> Volume -> m (m ()) Source #

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.

effectDistance :: MonadIO m => Channel -> Word8 -> m (m ()) Source #

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.

effectPosition :: MonadIO m => Channel -> Int16 -> Word8 -> m (m ()) Source #

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.

effectReverseStereo :: MonadIO m => Channel -> Bool -> m (m ()) Source #

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`.

# Other

initialize :: (Foldable f, MonadIO m) => f InitFlag -> m () Source #

Initialize the library by loading support for a certain set of sample/music formats.

Note that calling this is not strictly necessary: support for a certain format will be loaded automatically when attempting to load data in that format. Using `initialize` allows you to decide when to load support.

You may call this function multiple times.

data InitFlag Source #

Used with `initialize` to designate loading support for a particular sample/music format.

Constructors

InitFLAC |
InitMOD |
InitMP3 |
InitOGG |

#### Instances

Instances details

Bounded InitFlag Source # |
Instance details Defined in SDL.Mixer Methods minBound :: InitFlag Source # maxBound :: InitFlag Source #
Read InitFlag Source # |
Instance details Defined in SDL.Mixer Methods readsPrec :: Int -> ReadS InitFlag Source # readList :: ReadS [InitFlag] Source # readPrec :: ReadPrec InitFlag Source # readListPrec :: ReadPrec [InitFlag] Source #
Show InitFlag Source # |
Instance details Defined in SDL.Mixer Methods showsPrec :: Int -> InitFlag -> ShowS Source # show :: InitFlag -> String Source # showList :: [InitFlag] -> ShowS Source #
Eq InitFlag Source # |
Instance details Defined in SDL.Mixer Methods (==) :: InitFlag -> InitFlag -> Bool Source # (/=) :: InitFlag -> InitFlag -> Bool Source #
Ord InitFlag Source # |
Instance details Defined in SDL.Mixer Methods compare :: InitFlag -> InitFlag -> Ordering Source # (<) :: InitFlag -> InitFlag -> Bool Source # (<=) :: InitFlag -> InitFlag -> Bool Source # (>) :: InitFlag -> InitFlag -> Bool Source # (>=) :: InitFlag -> InitFlag -> Bool Source # max :: InitFlag -> InitFlag -> InitFlag Source # min :: InitFlag -> InitFlag -> InitFlag Source #

quit :: MonadIO m => m () Source #

Cleans up any loaded libraries, freeing memory.

version :: (Integral a, MonadIO m) => m (a, a, a) Source #

Gets the major, minor, patch versions of the linked `SDL2_mixer` library.