ctrµLua

• Index

Contents

• Functions
• audio object
• audio object (ogg-only)
• Tables return

Modules

• ctr.apt
• ctr.audio
• ctr.cam
• ctr.cfgu
• ctr.gfx.color
• ctr
• ctr.gfx.font
• ctr.fs
• ctr.gfx
• ctr.hid
• ctr.httpc
• ctr.ir
• ctr.fs.lzlib
• ctr.gfx.map
• ctr.mic
• ctr.news
• ctr.ptm
• ctr.qtm
• ctr.socket
• ctr.swkbd
• ctr.gfx.texture
• ctr.thread
• ctr.thread.pool
• ctr.uds

Topics

• README
• filepicker

Examples

• audio.lua
• cfgu.lua
• example.lua
• httpc.lua
• map.lua
• ptm.lua
• qtm.lua

Module ctr.audio

The audio module.

An audio channel can play only one audio object at a time. There are 24 audio channels available, numbered from 0 to 23.

Usage:

local audio = require("ctr.audio")

Functions

audio object

audio object (ogg-only)

Tables return

Functions

load (path[, chunkDuration=0.1[, type=detect]])

Load an audio file. OGG Vorbis and PCM WAV file format are currently supported. (Most WAV files use the PCM encoding). NOTE: audio streaming doesn't use threading for now, this means that the decoding will be done on the main thread. It should work fine with WAVs, but with OGG files you may suffer slowdowns when a new chunk of data is decoded. To avoid that, you can either reduce the chunkDuration or disable streaming, but be careful if you do so, audio files can fill the memory really quickly.

Parameters:

• path string path to the file or the data if type is raw
• chunkDuration number if set to -1, streaming will be disabled (all data is loaded in memory at once) Other values are the stream chunk duration in seconds (ctrµLua will load the audio per chunk of x seconds). Note that you need to call audio.update() each frame in order for ctµLua to load new data from audio streams. Two chunks of data will be loaded at the same time at most (one playing, the other ready to be played). (default 0.1)
• type string file type, "ogg" or "wav". If set to "detect", will try to deduce the type from the filename. (default detect)

Returns:

audio the loaded audio object

Or

1. nil if a error happened
2. string error message

loadRaw (data, rate, encoding[, channels=1])

Load raw audio data from a string. No streaming.

Parameters:

• data string raw audio data
• rate number sampling rate
• encoding string audio encoding, can be "PCM8", "PCM16" or "ADPCM"
• channels number audio channels count (default 1)

Returns:

audio the loaded audio object

Or

1. nil if a error happened
2. string error message

playing ([channel])

Check if audio is currently playing on a channel.

Parameters:

• channel integer number; if nil will search the first channel playing an audio (optional)

Returns:

boolean true if the channel is currently playing the audio, false otherwise. If channel is not set, false means no audio is playing at all.

mix ([channel[, frontLeft=1[, frontRight=frontLeft[, backLeft=frontLeft[, backRight=frontRight]]]]])

Set the mix parameters (volumes) of a channel. Volumes go from 0 (0%) to 1 (100%). Note that when a new audio object will play on this channel, theses parameters will be reset with the new audio object defaults (set in audio:mix()).

Parameters:

• channel integer the channel number, if nil will change the mix parmaters of all channels (optional)
• frontLeft number front left volume (default 1)
• frontRight number front right volume (default frontLeft)
• backLeft number back left volume (default frontLeft)
• backRight number back right volume (default frontRight)

interpolation ([channel[, none=linear]])

Set the interpolation type of a channel. Note that when a new audio object will play on this channel, this parameter will be reset with the new audio object default (set in audio:interpolation()).

Parameters:

• channel integer stop playing audio on this channel; if nil will change interpolation type on all channels (optional)
• none string ", "linear" or "polyphase" (default linear)

speed ([channel[, speed=1]])

Set the speed of the audio playing in a channel. Speed is expressed as a percentage of the normal playing speed. 1 is 100% speed and 2 is 200%, etc. Note that when a new audio object will play on this channel, this parameter will be reset with the new audio object default (set in audio:speed()).

Parameters:

• channel integer stop playing audio on this channel; if nil will change interpolation type on all channels (optional)
• speed number percentage (default 1)

stop ([channel])

Stop playing all audio on all channels or a specific channel.

Parameters:

• channel integer stop playing audio on this channel; if nil will stop audio on all channels (optional)

Returns:

integer number of channels where audio was stopped

update ()

Update all the currently playing audio streams. Must be called every frame if you want to use audio with streaming.

audio object

:duration ()

Returns the audio object duration.

Returns:

number duration in seconds

:time ([channel])

Returns the current playing position.

Parameters:

• channel integer number; if nil will use the first channel found which played this audio (optional)

Returns:

number time in seconds

:playing ([channel])

Check if the audio is currently playing.

Parameters:

• channel integer channel number; if nil will search the first channel playing this audio (optional)

Returns:

boolean true if the channel is currently playing the audio, false otherwise

:mix ([frontLeft=1[, frontRight=frontLeft[, backLeft=frontLeft[, backRight=frontRight]]]])

Set the mix parameters (volumes) of the audio. Volumes go from 0 (0%) to 1 (100%).

Parameters:

• frontLeft number front left volume (default 1)
• frontRight number front right volume (default frontLeft)
• backLeft number back left volume (default frontLeft)
• backRight number back right volume (default frontRight)

:interpolation ([none=linear])

Set the interpolation type of the audio.

Parameters:

• none string ", "linear" or "polyphase" (default linear)

:speed ([speed=1])

Set the speed of the audio. Speed is expressed as a percentage of the normal playing speed. 1 is 100% speed and 2 is 200%, etc.

Parameters:

• speed number percentage (default 1)

:play ([loop=false[, channel]])

Plays the audio file.

Parameters:

• loop boolean if the audio should loop or not (default false)
• channel integer the channel to play the audio on (0-23); if nil will use the first available channel. If the channel was playing another audio, it will be stopped and replaced by this audio. If not set and no channel is available, will return nil plus an error message. (optional)

Returns:

integer channel number the audio is playing on

Or

1. nil an error happened and the audio was not played
2. error the error message

:stop ([channel])

Stop playing an audio object.

Parameters:

• channel integer stop playing the audio on this channel; if nil will stop all channels playing this audio. If the channel is playing another audio object, this function will do nothing. (optional)

Returns:

integer number of channels where this audio was stopped

:type ()

Returns the audio object type.

Returns:

string "ogg", "wav" or "raw"

:unload ()

Unload an audio object.

audio object (ogg-only)

:info ()

Returns basic information about the audio in a vorbis bitstream.

Returns:

infoTable information table

:comment ()

Returns the Ogg Vorbis bitstream comment.

Returns:

commentTable comment table

Tables return

infoTable

Vorbis bitstream information, returned by audio:info(). If bitrateLower == bitrateNominal == bitrateUpper, the stream is fixed bitrate.

Fields:

• version integer Vorbis encoder version used to create this bitstream
• channels integer number of channels in bitstream
• rate integer sampling rate of the bitstream
• bitrateUpper integer the upper limit in a VBR bitstream; may be unset if no limit exists
• bitrateNominal integer the average bitrate for a VBR bitstream; may be unset
• bitrateLower integer the lower limit in a VBR bitstream; may be unset if no limit exists

commentTable

Vorbis bitstream comment, returned by audio:comment().

Fields:

• userComments table list of all the user comment
• vendor string information about the Vorbis implementation that encoded the file