Module audio

Types

PPlaylist = ref TPlaylist
TPlaylist = object of TObject
  tracks*: seq[tuple[file: string, title: string]]
  fCurrentMusic: PMusic
  fCurrentTrackIndex: int
  fCurrentTitle: string
  fFinished: bool
  shuffle*, repeat*, next*, playing*, paused*: bool

Procs

proc setChannels(num: int): int {.inline.}

Allocate num of channels.

Return number of channels allocated.

proc setAudioVolume(volume: int; channel: int = - 1) {.inline.}

Set volume of channel (0..128).

channel = -1 for all channels.

proc getAudioVolume(channel: int = - 1): int {.inline.}

Get volume of channel (0..128).

channel = -1 to get average volume of all channels.

proc getChunk(channel: int): PChunk

Get chunk playing on channel.

Nil is returned if the channel is not allocated, or if channel has not played any samples yet. 

proc free(obj: var PChunk) {.inline.}
Free chunk. 
proc load(obj: var PChunk; filename: string) {.inline.}
Load sample from file to given chunk (or nil on errors). 
proc play(obj: PChunk; channel: int = - 1; loops: int = 0; timed: int = 0; 
          fadein: int = 0) {.inline.}

Play chunk.

loops: number of loops.

timed: millisecond limit to play sample, at most.

fadein: milliseconds of time for fade-in effect.

proc channelFinished(callback: TChannel_finished) {.inline.}

Set callback to call when any channel finishes playback.

Note: NEVER call sld_mixer functions, nor sdl.lockAudio from a callback function.

proc pauseChannel(channel: int = - 1) {.inline.}

Pause channel.

channel = -1 to pause all channels.

proc resumeChannel(channel: int = - 1) {.inline.}

Resume playing of channel.

channel = -1 to resume playing of all channels.

proc toggleChannelPause(channel: int = - 1)
Pause channel when playing or resume playing when paused. 
proc channelPaused(channel: int = - 1): bool

Return true if channel is paused and false if not.

channel = -1 to check if any of channels is paused.

proc pausedChannelsCount(): int {.inline.}
Get number of paused channels. 
proc haltChannel(channel: int = - 1) {.inline.}

Halt channel.

channel = -1 to halt all channels.

proc expireChannel(channel, ms: int): int {.inline.}

Halt channel playback after ms milliseconds.

channel = -1 to halt all channels.

Return number of channels set to expire.

proc fadeOutChannel(channel, ms: int): int {.inline.}

Gradually fade out channel over ms milliseconds starting from now.

channel = -1 to fade out all channels.

Return number of channells set to fade out.

proc getChannelFading(channel: int): TFading {.inline.}
Get fadind status from channel:
  • MIX_NO_FADING
  • MIX_FADING_OUT
  • MIX_FADING_IN

Note: -1 is not valid, adn will probably crash the program.

proc channelPlaying(channel: int = - 1): bool

Check if channel playing or not.

channel = -1 to check if any channel is playing.

proc playingChannelsCount(): int {.inline.}
Get number of playing channels. 
proc volume(obj: PChunk): int {.inline.}
Get volume of the chunk (0..128). 
proc volume=(obj: PChunk; value: int) {.inline.}
Set volume of the chunk (0..128). 
proc reserveChannels(num: int): int {.inline.}

Reserve num channels from being used when playing samples when passing in -1 as a channel number to playback functions.

The channels are reserved starting from 0 to num-1.

Passing in 0 will unreserve all channels.

Normally sdl_mixer starts without any channels reserved.

Return number of channels reserved.

proc groupChannel(channel, tag: int): bool

Add channel to group tag, or reset it's group to the default group tag (-1).

Return true on success or false when the channel specified is invalid.

proc groupChannels(fromChannel, toChannel, tag: int): int {.inline.}

Add channels starting at from up through to to group tag, or reset it's group to the default group tag (-1).

Return number of tagged channels.

proc groupCount(tag: int): int {.inline.}

Return number of channels in group tag.

tag = -1 to count ALL channels.

proc groupAvailable(tag: int): int {.inline.}

Find the first available (not playing) channel in group tag.

tag = -1 to search ALL channels.

Return channel found on success, or -1 when no channels in the group are available.

proc groupOldest(tag: int): int {.inline.}

Find the oldest actively playing channel in group tag.

tag = -1 to search ALL channels.

Return channel found on success, or -1 when no channels in the group are playing or the group is empty.

proc groupNewer(tag: int): int {.inline.}

Find the newest, most recently started, actively playing channel in group tag.

tag = -1 to search ALL channels.

Return channel found on success, or -1 when no channels in the group are playing or the group is empty.

proc fadeOutGroup(tag, ms: int): int {.inline.}

Gradually fade out channels in group tag over ms milliseconds starting from now.

Note: -1 will NOT fade all channels out. Use fadeOutChannel(-1) for that instead.

Return number of channels to fade out.

proc haltGroup(tag: int) {.inline.}
Halt playback on all channels in group tag. 
proc free(obj: var PMusic) {.inline.}
Free loaded music. 
proc load(obj: var PMusic; filename: string) {.inline.}
proc play(obj: PMusic; loops: int = 0; fadein: int = 0)
Play loaded music. loops: number of loops. fadein: milliseconds of time for fade-in effect. 
proc hookMusic(func: TMixFunction; arg: pointer) {.inline.}

Setup a custom music player function.

func: function pointer to a music player mixer function.

arg: pointer passed as func's udata parameter.

See SDL_mixer documentation for details.

proc musicVolume(): int {.inline.}
Get music volume (0..128). 
proc musicVolume=(value: int) {.inline.}
Set music volume (0..128) 
proc pauseMusic() {.inline.}
Pause music playback. 
proc resumeMusic() {.inline.}
Resume music playback. 
proc toggleMusicPause()
Pause music when playing or resume playing when paused. 
proc rewindMusic() {.inline.}

Rewind music to the start.

Note: only works for MOD, OGG, MP3, Native MIDI.

proc setMusicPos(position: float): bool

Set position to play from.

Note: only works for:

  • MOD: position is cast to Uint16 and used for a pattern number in the module.
  • OGG: jumps to position seconds from the beginning of the song.
  • MP3: jumps to position seconds from the current position in the stream. Negative values do nothing.

Return true on success, or false if the codec doesn't support this function.

proc haltMusic() {.inline.}
Halt music playback. 
proc fadeOutMusic(ms: int) {.inline.}
Gradually fade out music over ms milliseconds starting from now. 
proc getMusicType(obj: PMusic = nil): TMusicType {.inline.}
Get file format encoding of the music as TMusicType. Nil for currently playing music type. 
proc getMusicTypeStr(obj: PMusic = nil): string
Get file format encoding of the music as string. Nil for currently playing music type. 
proc musicPlaying(): bool
Check if music playing or not. 
proc musicPaused(): bool
Check if music paused or not. 
proc getMusicFading(): TFading {.inline.}
Get fadind status of music:
  • MIX_NO_FADING
  • MIX_FADING_OUT
  • MIX_FADING_IN
proc setMusicFinishedCallback(callback: TCallback = nil; 
                              callbackObject: PObject = nil)

Setup a callback to be called when music playback is halted.

This proc is frontend to hookMusicFinished.

callback: callback function.

callbackObject: object to call.

Note: NEVER call sld_mixer functions, nor sdl.lockAudio from a callback function.

proc init(obj: PPlaylist; shuffle, repeat, next: bool)
proc newPlaylist(shuffle: bool = true; repeat: bool = false; next: bool = true; 
                 defaultPlaylist: bool = true): PPlaylist

shuffle: set random selection of the next track.

next: set auto-play next track.

defaultPlaylist: setup callback to play next track.

Methods

method currentMusic(obj: PPlaylist): PMusic {.inline.}
Get reference to the currently playing music. 
method currentTrackIndex(obj: PPlaylist): int {.inline.}
Get current track index in tracks list. 
method currentTitle(obj: PPlaylist): string {.inline.}
Get title of the current music. 
method loadFromPath(obj: PPlaylist; path: string)
Load tracks from given path (directory). 
method loadFromFile(obj: PPlaylist; filename: string)
Load track from list in given file. 
method play(obj: PPlaylist; index: int = - 1)

Play specific track.

index = -1 to play next track (indexNext).

method playNext(obj: PPlaylist) {.inline.}
Play next track. 
method playTrack(obj: PPlaylist; title: string = nil)

Play track with given title.

title = nil to play next track (indexNext).

method update(obj: PPlaylist)
method free(obj: PPlaylist)
Generated: 2012-11-11 20:09:27 UTC