SDL.Audio

SDL.Audio provides a high-level API to SDL's audio device capabilities.

Managing AudioDevices

data AudioDevice

An open audio device. These can be created via openAudioDevice and should be closed with closeAudioDevice

Instances

Eq AudioDevice

Opening and Closing AudioDevices

openAudioDevice :: MonadIO m => OpenDeviceSpec -> m (AudioDevice, AudioSpec)

Attempt to open the closest matching AudioDevice, as specified by the given OpenDeviceSpec.

See SDL_OpenAudioDevice for C documentation.

closeAudioDevice :: MonadIO m => AudioDevice -> m ()

See SDL_CloseAudioDevice for C documentation.

data OpenDeviceSpec

A specification to openAudioDevice, indicating the desired output format. Note that many of these properties are Changeable, meaning that you can choose whether or not SDL should interpret your specification as an unbreakable request (Mandate), or as an approximation Desire.

Constructors

forall sampleType . OpenDeviceSpec

Fields

openDeviceFreq :: !(Changeable CInt)

The output audio frequency in herts.

openDeviceFormat :: !(Changeable (AudioFormat sampleType))

The format of audio that will be sampled from the output buffer.

openDeviceChannels :: !(Changeable Channels)

The amount of audio channels.

openDeviceSamples :: !Word16

Output audio buffer size in samples. This should be a power of 2.

openDeviceCallback :: forall actualSampleType. AudioFormat actualSampleType -> IOVector actualSampleType -> IO ()

A callback to invoke whenever new sample data is required. The callback will be passed a single MVector that must be filled with audio data.

openDeviceUsage :: !AudioDeviceUsage

How you intend to use the opened AudioDevice - either for outputting or capturing audio.

openDeviceName :: !(Maybe Text)

The name of the AudioDevice that should be opened. If Nothing, any suitable AudioDevice will be used.

data AudioDeviceUsage

How you intend to use an AudioDevice

Constructors

ForPlayback

The device will be used for sample playback.

ForCapture

The device will be used for sample capture.

Instances

Bounded AudioDeviceUsage

Enum AudioDeviceUsage

Eq AudioDeviceUsage

Data AudioDeviceUsage

Ord AudioDeviceUsage

Read AudioDeviceUsage

Show AudioDeviceUsage

Generic AudioDeviceUsage

type Rep AudioDeviceUsage

data Channels

How many channels audio should be played on

Constructors

Mono

A single speaker configuration

Stereo

A traditional left/right stereo system

Quad

FivePointOne

1. 1 surround sound

Instances

Bounded Channels

Enum Channels

Eq Channels

Data Channels

Ord Channels

Read Channels

Show Channels

Generic Channels

type Rep Channels

data Changeable a

Used to indicate to SDL whether it is allowed to open other audio devices (if a property is marked as a Desire) or if it should fail if the device is unavailable (Mandate).

Constructors

Mandate !a

Mandate this exact property value, and fail if a matching audio device cannot be found.

Desire !a

Desire this property value, but allow other audio devices to be opened.

Instances

Functor Changeable

Foldable Changeable

Traversable Changeable

Eq a => Eq (Changeable a)

Data a => Data (Changeable a)

Read a => Read (Changeable a)

Show a => Show (Changeable a)

Generic (Changeable a)

type Rep (Changeable a)

Working with Opened Devices

Locking AudioDevices

setAudioDeviceLocked :: MonadIO m => AudioDevice -> LockState -> m ()

Lock an AudioDevice such that its associated callback will not be called until the device is unlocked.

data LockState

Whether a device should be locked or unlocked.

Constructors

Locked

Lock the device, preventing the callback from producing data.

Unlocked

Unlock the device, resuming calls to the callback.

Instances

Bounded LockState

Enum LockState

Eq LockState

Data LockState

Ord LockState

Read LockState

Show LockState

Generic LockState

type Rep LockState

Switching Playback States

data PlaybackState

Whether to allow an AudioDevice to play sound or remain paused.

Constructors

Pause

Pause the AudioDevice, which will stop producing/capturing audio.

Play

Resume the AudioDevice.

Instances

Bounded PlaybackState

Enum PlaybackState

Eq PlaybackState

Data PlaybackState

Ord PlaybackState

Read PlaybackState

Show PlaybackState

Generic PlaybackState

type Rep PlaybackState

setAudioDevicePlaybackState :: MonadIO m => AudioDevice -> PlaybackState -> m ()

Change the playback state of an AudioDevice.

Querying an AudioDevices Status.

data AudioDeviceStatus

Opened devices are always Playing or Paused in normal circumstances. A failing device may change its status to Stopped at any time, and closing a device will progress to Stopped too.

Constructors

Playing

The AudioDevice is playing.

Paused

The AudioDevice is paused.

Stopped

The AudioDevice is stopped.

Instances

Bounded AudioDeviceStatus

Enum AudioDeviceStatus

Eq AudioDeviceStatus

Data AudioDeviceStatus

Ord AudioDeviceStatus

Read AudioDeviceStatus

Show AudioDeviceStatus

Generic AudioDeviceStatus

type Rep AudioDeviceStatus

audioDeviceStatus :: MonadIO m => AudioDevice -> m AudioDeviceStatus

Query the state of an AudioDevice.

AudioFormat

data AudioFormat sampleType where

Information about what format an audio bytestream is. The type variable t indicates the type used for audio buffer samples. It is determined by the choice of the provided SampleBitSize. For example:

AudioFormat UnsignedInteger Sample8Bit Native :: AudioFormat Word8

Indicating that an 8-bit audio format in the platforms native endianness uses a buffer of Word8 values.

Constructors

Signed8BitAudio :: AudioFormat Int8

Unsigned8BitAudio :: AudioFormat Word8

Signed16BitLEAudio :: AudioFormat Int16

Signed16BitBEAudio :: AudioFormat Int16

Signed16BitNativeAudio :: AudioFormat Int16

Unsigned16BitLEAudio :: AudioFormat Word16

Unsigned16BitBEAudio :: AudioFormat Word16

Unsigned16BitNativeAudio :: AudioFormat Word16

Signed32BitLEAudio :: AudioFormat Int32

Signed32BitBEAudio :: AudioFormat Int32

Signed32BitNativeAudio :: AudioFormat Int32

FloatingLEAudio :: AudioFormat Float

FloatingBEAudio :: AudioFormat Float

FloatingNativeAudio :: AudioFormat Float

Instances

Eq (AudioFormat sampleType)

Ord (AudioFormat sampleType)

Show (AudioFormat sampleType)

Enumerating AudioDevices

getAudioDeviceNames :: MonadIO m => AudioDeviceUsage -> m (Maybe (Vector Text))

Enumerate all AudioDevices attached to this system, that can be used as specified by the given AudioDeviceUsage. SDL cannot always guarantee that this list can be produced, in which case Nothing will be returned.

AudioSpec

data AudioSpec

AudioSpec is the concrete specification of how an AudioDevice was sucessfully opened. Unlike OpenDeviceSpec, which specifies what you want, AudioSpec specifies what you have.

audioSpecFreq :: AudioSpec -> CInt

DSP frequency (samples per second)

audioSpecFormat :: AudioSpec -> AudioFormat sampleType

Audio data format

audioSpecChannels :: AudioSpec -> Channels

Number of separate sound channels

audioSpecSilence :: AudioSpec -> Word8

Calculated udio buffer silence value

audioSpecSize :: AudioSpec -> Word32

Calculated audio buffer size in bytes

audioSpecCallback :: AudioSpec -> AudioFormat sampleType -> IOVector sampleType -> IO ()

The function to call when the audio device needs more data

Audio Drivers

getAudioDrivers :: MonadIO m => m (Vector AudioDriver)

Obtain a list of all possible audio drivers for this system. These drivers can be used to specificially initialize the audio system.

currentAudioDriver :: MonadIO m => m (Maybe Text)

Query SDL for the name of the currently initialized audio driver, if possible. This will return Nothing if no driver has been initialized.

data AudioDriver

An abstract description of an audio driver on the host machine.

Instances

Eq AudioDriver

Show AudioDriver

audioDriverName :: AudioDriver -> Text

Get the human readable name of an AudioDriver

Explicit Initialization

audioInit :: MonadIO m => AudioDriver -> m ()

Explicitly initialize the audio system against a specific AudioDriver. Note that most users will not need to do this, as the normal initialization routines will already take care of this for you.