Reference | Audio

These are audio functions.

PS.AudioLoad ( file, path )

PS.AudioLoad() preloads an audio file without playing it. If you know you're going to use a sound in your game, loading it in advance can help to reduce network lag.

Parameters:

  1. file : string
  2. (optional) path : string

Returns: object

Default: null

The file parameter must be a string matching the filename of the audio to be played. If the default Perlenspiel library path is used, it must be the name of one of the sounds in the Audio Library. Be sure the filename is spelled correctly! Note that filenames are all lower-case, and that no file extension should be included.

The optional path parameter must be a string containing the complete, case-sensitive pathname of the directory containing the sound file specified in the id parameter. Sound files should be in 16-bit .wav format, 22.050 or 44.100kHz sampling rate, mono or stereo.

If no path parameter is passed, or the value undefined or PS.CURRENT is passed, the current audio path is used. If the value PS.DEFAULT is specified for path, the default Perlenspiel directory pathname is used.

The return value is true if no errors occur. If the load fails, or a parameter error occurs, the value PS.ERROR is returned.

Example:

PS.Init = function ( options )
{
    // set up a 10 x 10 grid

    PS.GridSize( 10, 10 );

    // preload a sound for later use

    PS.AudioLoad( "fx_click" );
};

PS.AudioPlay ( file, volume, func, path, data )

PS.AudioPlay() plays an library audio file (loading it first if necessary), and returns the channel number associated with that file.

Parameters:

  1. file : string
  2. (optional) volume : float
  3. (optional) func : function
  4. (optional) path : string
  5. (optional) data : anything

Returns: integer

Default: 0

The file parameter must be a string matching the filename of the audio to be played. If the default Perlenspiel library path is used, it must be the name of one of the sounds in the Audio Library. Be sure the filename is spelled correctly! Note that filenames are all lower-case, and that no file extension should be included.

The optional volume parameter controls the level at which the sound will be played. It must be a number between 0.0 (total silence) and 1.0 (full volume). Any value outside this range is clamped. If the value PS.DEFAULT is specified, or no volume parameter is provided, the default value (0.5, 50% volume) is used.

The optional func and data parameters let you specify a function that will be called when the playback of the sound is paused or concluded. The func parameter must be a valid Javascript function. The data parameter can be any Javascript data type. When the sound ends, the function specified in func is called with data as its sole parameter.

If PS.DEFAULT is specified for func, the default behavior (no on-end function) is applied. If a func parameter is supplied without a data parameter, the parameter passed to func will be the channel number associated with the sound file.

NOTE: The stop function is not called when a sound is paused with a call to PS.AudioPause(), or stopped with a call to PS.AudioStop(). However, it is called at the conclusion of a sound that was paused during playback one or more times with PS.AudioPause().

The optional path parameter must be a string containing the complete, case-sensitive pathname of the directory containing the sound file specified in the id parameter. Sound files should be in 16-bit .wav format, 22.050 or 44.100kHz sampling rate, mono or stereo.

If no path parameter is passed, or the value undefined or PS.CURRENT is passed, the current audio path is used. If the value PS.DEFAULT is specified for path, the default Perlenspiel directory pathname is used.

The return value is a number representing the channel associated with the sound file. This value can be used as a parameter to PS.AudioPause() and PS.AudioStop() to pause or stop a previously started sound. If you don't need to explicitly pause or stop a sound, this value can be ignored.

If a file loading or parameter error occurs, the value PS.ERROR is returned.

Example:

PS.Click = function ( x, y, data, options )
{
    // play a click when any bead is touched

    PS.AudioPlay( "fx_click" );
};

PS.AudioPause ( channel )

PS.AudioPause() lets you pause and/or resume an audio channel.

Parameters:

  1. channel : integer

Returns: integer

Default: 0

The channel parameter should be a number previously returned by a call to PS.AudioPlay().

If the specified channel is still playing, it will pause immediately.

If the specified channel is already paused as a result of a previous call from PS.AudioPause(), it will resume playing at the point from which it was paused.

If the specified channel is not playing, paused or stopped, or if the channel is invalid, nothing happens.

The return value is the channel number, or PS.ERROR if an error occurs.

PS.AudioStop ( channel )

PS.AudioStop() lets you stop an audio channel.

Parameters:

  1. channel : integer

Returns: integer

Default: 0

The channel parameter should be a number previously returned by a call to PS.AudioPlay().

If the specified channel is still playing, it will stop immediately.

If the specified channel is currently paused by a previous call from PS.AudioPause(), its status will change from “paused” to “stopped,” and subsequent calls from PS.AudioPause() will have no effect.

If the specified channel is not playing or paused, or if the channel is invalid, nothing happens.

The return value is the channel number, or PS.ERROR if an error occurs.

PS.AudioPath ( path )

PS.AudioPath() lets you change the current path used to load audio files.

Parameters:

  1. path : string
  2. PS.CURRENT
  3. PS.DEFAULT

Returns: string

The optional path parameter must be a string containing the complete, case-sensitive path of a directory containing the required sound files. This path will be used for all subsequent calls to PS.AudioLoad() and PS.AudioPlay() that do not include an explicit path parameter.

If no parameter is passed, or the value undefined or PS.CURRENT is passed, the current audio path is maintained.

If the value PS.DEFAULT is passed, the current audio path reverts to the Perlenspiel system library.

The return value is the new current audio path, or PS.ERROR if an error occurs.

PS.Piano ( note, flag )

PS.Piano() returns the filename of an indexed piano note in the Audio Library.

Parameters:

  1. note : integer
  2. (optional) flag : boolean

Returns: string

The 88 notes on Perlenspiel's piano range from A0 to C8.

PS.Piano() takes a note parameter between 1 and 88 inclusive, and returns a string representing the filename of the associated piano sound. Values outside this range are clamped.

There are two versions of each piano note, short (about 1 second in duration) and long (about 4 seconds). The optional flag parameter determines which version's filename is returned. If flag is false or not supplied, the short version is returned. If flag is true, the long version is returned.

If a parameter error occurs, the value PS.ERROR is returned.

Examples:

PS.Click = function ( x, y, data, options )
{
    // play SHORT version of piano note 44
    // when any bead is clicked

    PS.AudioPlay( PS.Piano(44) );
};

PS.KeyDown = function ( key, shift, ctrl, options )
{
    // play LONG version of piano note 32
    // when any key is pressed

    PS.AudioPlay( PS.Piano( 32, true ) );
};

PS.Harpsichord ( note, flag )

PS.Harpsichord() returns the filename of an indexed harpsichord note in the Audio Library.

Parameters:

  1. note : integer
  2. (optional) flag : boolean

Returns: string

The 57 notes on Perlenspiel's harpsichord range from A2 to F7.

PS.Harpsichord() takes an index value between 1 and 57 inclusive, and returns a string representing the filename of the associated harpsichord sound. Values outside this range are clamped.

There are two versions of each harpsichord note, short (about 1 second in duration) and long (about 4 seconds). The optional flag parameter determines which version's filename is returned. If flag is false or not supplied, the short version is returned. If flag is true, the long version is returned.

If a parameter error occurs, the value PS.ERROR is returned.

PS.Xylophone ( note )

PS.Xylophone() returns the filename of an indexed xylophone note in the Audio Library.

Parameters:

  1. note : integer

Returns: string

The 39 notes on Perlenspiel's xylophone range from A4 to B7.

PS.Xylophone() takes an index value between 1 and 39 inclusive, and returns a string representing the filename of the associated xylophone sound. Values outside this range are clamped.

If a parameter error occurs, null is returned.

Audio Library

The Perlenspiel audio library contains nearly 400 sounds that you can use in your games, including a full range of piano, harpsichord and xylophone notes, dozens of percussion instruments, and sound effects ranging from simple to silly.

To use these sounds, pass the filenames below as a string to the PS.AudioPlay() command. Be sure the filename is spelled correctly! Note that filenames are all lower-case.

Example:

PS.Click = function ( x, y, data, options )
{
    // play a click when a bead is touched

    PS.AudioPlay( "fx_click" );
};

If you prefer a local copy of the audio files for development, right-click here and choose Save Link As to download a .zip archive containing all of the sounds. Unzip the archived /audio/ directory to a convenient location and use PS.AudioPath() to point Perlenspiel's default audio path to your local directory.

Click on any filename to hear what it sounds like.

Sound effects

All sound effect filenames begin with an “fx_” prefix.

Percussion instruments

All percussion filenames begin with a “perc_” prefix.

Xylophone notes

Taps on a 39-note xylophone (notes A4 to B7) are available.

You can translate a xylophone note number (1-39) to its associated filename with the PS.Xylophone() function.

Piano notes

All 88 keys on a standard concert piano (notes A0 to C8) are available in two versions, short (about 1 second) and long (about 4 seconds).

You can translate a note number (1-88) to its associated filename with the PS.Piano() function.

Short version filenames begin with a “piano_” prefix.

Long version filenames begin with a “l_piano_” prefix.

Harpshicord notes

A 57-key harpsichord manual (notes A2 to F7) is available in two versions, short (about 1 second) and long (about 4 seconds).

You can translate a harpsichord note number (1-57) to its associated filename with the PS.Harpsichord() function.

Short version filenames begin with a “hchord_” prefix.

Long version filenames begin with a “l_hchord_” prefix.