Module blitwizard.audio

The blitwizard audio namespace allows you to create sound objects to play sounds and music.

Use simpleSound objects for background music, pannedSound for a sound with left/right panning and positionedSound for a sound with positioning in 2d or 3d space inside the game world.

Please note blitwizard will NEVER preload any sounds into memory, so it is perfectly fine to create many sound objects from the same sound file, it won't cause the file to be loaded into memory many times.

Supported audio formats are .ogg and .flac, and, if a usable FFmpeg version is present on the system, many more like .mp3, .mp4 and others.

Info:

  • Copyright: 2012-2013
  • License: zlib
  • Author: Jonas Thiem (jonas.thiem@gmail.com)

Class simpleSound

simpleSound:new (filename) Create a new simple sound object.
simpleSound:play (volume, loop, fadein) Play the sound represented by the simple sound object.
simpleSound:stop (fadeout) Stop the sound represented by the simple sound object.
simpleSound:setPriority (priority) Set the sound priority of the simple sound object.
simpleSound:adjust (volume) Adjust the volume of a simple sound while it is playing (does nothing if it's not)

Class pannedSound

pannedSound:new (filename) Create a new panned sound object.
pannedSound:play (volume, panning, loop, fadein) Play the sound represented by the panned sound object
pannedSound:stop (fadeout) Stop the sound represented by the panned sound object.
pannedSound:setPriority (priority) Set the sound priority of the panned sound, see explanation of blitwizard.audio.simpleSound:setPriority.
pannedSound:adjust (volume, panning) Adjust the volume or panning of a panned sound (does nothing if the sound is not playing)

Class positionedSound

positionedSound:new (filename, object) Create a new positioned sound object.
positionedSound:stop (fadeout) Stop the sound represented by the positioned sound object.


Class simpleSound

Implements a simple sound which has no stereo left/right panning or room positioning features. This is the sound object suited best for background music. It deactivates some of the postprocessing which would allow positioning or stereo panning which results in slightly better and unaltered sound. The default sound priority for simple sound objects is 5.

Usage:

 -- play sound file "blubber.ogg"
 mysound = blitwizard.audio.simpleSound:new("blubber.ogg")
 mysound:play()
simpleSound:new (filename)
Create a new simple sound object.

Parameters:

  • filename string Filename of the audio file you want to play
simpleSound:play (volume, loop, fadein)
Play the sound represented by the simple sound object.

If the sound file doesn't exist or if it is in an unsupported format, an error will be thrown.

Does nothing if the sound object is already playing: to play a sound multiple times at once, use multiple sound objects.

Parameters:

  • volume number (optional) Volume at which the sound plays from 0 (quiet) to 1 (full volume). Defaults to 1
  • loop boolean (optional) If set to true, the sound will loop until explicitely stopped. If set to false or if not specified, it will play once
  • fadein number (optional) Fade in from silence to the specified volume in the given amount of seconds, instead of playing at full volume right from the start

Usage:

     -- play sound file "blubber.ogg" at 80% volume and
 -- fade in for 5 seconds
 mysound2 = blitwizard.audio.simpleSound:new("blubber.ogg")
 mysound2:play(0.8, 8)
simpleSound:stop (fadeout)
Stop the sound represented by the simple sound object. Does nothing if the sound doesn't currently play

Parameters:

  • fadeout number (optional) If specified, the sound will fade out for the specified amount in seconds. Otherwise it will stop instantly
simpleSound:setPriority (priority)
Set the sound priority of the simple sound object.

In blitwizard, only a fixed maximum number of sounds can play at a time. If you attempt to play a sound object when the maximum number of sounds simultaneously is reached, it will kill off playing sounds with lower priority. If no lower or same priority sound is available to kill, it won't start playing at all.

Changing the priority won't affect the sound object's current playing, it will only have an effect the next time you use play.

Background music should have a high priority, and short, frequent sounds like gun shots or footsteps should have a low priority.

Simple sound objects default to a priority of 5.

Parameters:

  • priority number Priority from 0 (lowest) to 20 (highest), values will be rounded down to have no decimal places (0.5 becomes 0, 1.7 becomes 1, etc)

Usage:

     -- play sound file "blubber.ogg" with lowest priotiy
 mysound = blitwizard.audio.simpleSound:new("blubber.ogg")
 mysound:setPriority(0)
 mysound:play()
simpleSound:adjust (volume)
Adjust the volume of a simple sound while it is playing (does nothing if it's not)

Parameters:

  • volume number New volume from 0 (quiet) to 1 (full volume)

Class pannedSound

Implements a sound with simple left/right stereo panning. If you want to make a sound emit from a specific location, you should probably use a positionedSound instead
pannedSound:new (filename)
Create a new panned sound object.

Parameters:

  • filename string Filename of the audio file you want to play
pannedSound:play (volume, panning, loop, fadein)
Play the sound represented by the panned sound object

Parameters:

  • volume number (optional) Volume at which the sound plays from 0 (quiet), through 1 (full volume) to 1.5 (over-amplified). Defaults to 1, values >1 can cause distortion
  • panning number (optional) Stereo panning which alters the left/right placement of the sound from 1 (left) through 0 (center) to -1 (right). Default is 0
  • loop boolean (optional) If set to true, the sound will loop until explicitely stopped. If set to false or if not specified, it will play once
  • fadein number (optional) Fade in from silence to the specified volume in the given amount of seconds, instead of playing at full volume right from the start

Usage:

     -- Play a sound at full volume, slightly panned to the left
 mysound = blitwizard.audio.pannedSound("song.ogg")
 mysound:play(1, 0.3)
pannedSound:stop (fadeout)
Stop the sound represented by the panned sound object. Does nothing if the sound doesn't currently play

Parameters:

  • fadeout number (optional) If specified, the sound will fade out for the specified amount in seconds. Otherwise it will stop instantly
pannedSound:setPriority (priority)
Set the sound priority of the panned sound, see explanation of blitwizard.audio.simpleSound:setPriority.

Panned sounds default to a priority of 2.

Parameters:

  • priority number Priority from 0 (lowest) to 20 (highest), values will be rounded down to have no decimal places (0.5 becomes 0, 1.7 becomes 1, etc)
pannedSound:adjust (volume, panning)
Adjust the volume or panning of a panned sound (does nothing if the sound is not playing)

Parameters:

  • volume number New volume from 0 to 1.5 (values higher than 1 can cause distortions)
  • panning number (optional) New panning from 1 (left) to 0 (center) to -1 (right)

Class positionedSound

Implements a positioned sound which can either follow a specific blitwizard object or which you can move to any position you like. It will alter volume based on distance and channels based on direction to simulate its room placement.
positionedSound:new (filename, object)
Create a new positioned sound object.

Parameters:

  • filename string Filename of the audio file you want to play
  • object userdata (optional) Specify a blitwizard object to which the sound should stick. If you don't specify an object to stick to, the sound can be freely placed with ???
positionedSound:stop (fadeout)
Stop the sound represented by the positioned sound object. Does nothing if the sound doesn't currently play

Parameters:

  • fadeout number (optional) If specified, the sound will fade out for the specified amount in seconds. Otherwise it will stop instantly
generated by LDoc 1.3.11