API | Audio

These functions control the playback of audio files.

 

PS.audioLoad ( filename, options )

PS.audioLoad() preloads an audio file, and optionally plays it.

Parameters:

  1. filename : string
  2. (optional) options : object or PS.DEFAULT

Returns: string or PS.ERROR

The filename parameter should be a case-sensitive string matching the filename of the audio to be played, without a path specifier or file extension (example: "click"). By default, the file is assumed to reside in the Perlenspiel Audio Library. Note that library filenames are all lower-case.

The options parameter, if provided, should by a Javascript object containing one or more of the following properties:

.autoplay

If .autoplay is true or a non-zero number, the audio file specified by filename is played immediately upon loading. Any playback behaviors specified by other parameters in the options object (such as volume and loop) will be in effect. If .autoplay is false, zero (0), null, PS.DEFAULT or not supplied, the default behavior (no autoplay) is used.

.volume

The .volume property specifies the volume assigned to subsequent playback of the audio file specified by filename. It should be a float in the range 0 (muted) to 1.0 (maximum) inclusive. Values outside this range are clamped. If .volume is null, PS.DEFAULT or not supplied, the default volume (0.5, 50% maximum) is used.

.loop

If .loop is true or a non-zero number, the audio file specified by filename loops continuously on subsequent playback. If .loop is false, zero (0), null, PS.DEFAULT or not supplied, the default behavior (no looping) is used.

.lock

If .lock is true or a non-zero number, the audio file specified by filename is marked for long-term retention by the file system. Such files are less likely to be discarded when the engine needs more space. If .lock is false, zero (0), null, PS.DEFAULT or not supplied, the default behavior (no file lock) is used.

.onLoad

The .onLoad property specifies a Javascript function that is called when the audio file specified by filename is actually loaded. It should be a reference to a valid Javascript function expecting one parameter.

The parameter passed to the .onLoad function is an object with the following properties:

The .channel property is the id of the channel assigned to the file.

The .name property is the same as the filename parameter.

The .path property is the complete pathname of the file, including its file extension.

The .duration property is the duration of the file in milliseconds.

The .data property is the value specified in the .data property of the params object. If no .data property was specified, this property is set to filename.

If .onLoad is null, PS.DEFAULT or not supplied, no function is called.

.onEnd

The .onEnd property specifies a Javascript function that is called each time the audio file specified by filename completes playback (including the end of each loop, if enabled). It should be a reference to a valid Javascript function expecting one parameter.

The parameter passed to the .onEnd function is an object with the same properties as those sent to the .onLoad function (see above).

If .onEnd is null, PS.DEFAULT or not supplied, no function is called.

.data

If an .onLoad and/or onEnd property is provided, the .data property specifies the value that is passed to those functions when they are called. It can be any Javascript value. If .data is null, PS.DEFAULT or not supplied, the filename parameter is passed to the function(s).

.path

The .path property should be the complete, case-sensitive path of the directory containing the file specified by filename. If .path is an empty string (""), null, PS.DEFAULT or not supplied, the path of the Perlenspiel Audio Library is used.

IMPORTANT: Webkit-based browsers, such as Chrome and Safari, are picky about security. By default, they will not load resources (including audio and image files) that (1) do not reside on an actual HTTP server, and (2) do not share the root filepath of any script that tries to access them. This means that you have to install all of your scripts, audio and image files on a live server, in the same root filepath, before you can test or deploy an application using these browsers. (It's possible to reconfigure the browser to avoid this necessity, but I don't recommend it.)

A basic application directory might look like this:

/audio/ (a folder for your audio files)
/images/ (a folder for your image files, if any)
game.html (the Perlenspiel web page)
*.js (your game scripts)

Firefox is currently more lenient about security. Resource files don't need to be on a server, or share the same root filepath. This may change when Firefox switches to Web Audio in the near future.

.fileTypes

The .fileTypes property should be an array of strings indicating the audio filetypes available for the file specified by filepath. The strings should be provided in priority order. Legal strings are:

You should provide an uncompressed 16-bit .wav file (44.1 kHz or 22.05 kHz, mono or stereo) for every sound used by your application, together with .ogg and .mp3 versions of the sound, all stored in the same directory. The three matching files should share the same case-sensitive filename, each with an appropriate lower-case extension (.wav, .ogg or .mp3).

Most browsers can handle either .ogg or .mp3 files, which load much faster.

Encode the compressed formats at whatever bitrate you feel is adequate. For stereo music, I recommend at least 192 kbps for .mp3 files, and 128 kbps for .ogg files. Lower rates may be adequate for voices and sound effects.

You may also want to provide an .opus file, as this will soon become the standard for all browsers.

If .fileTypes is PS.DEFAULT or not supplied, the default filetypes array is used:

If options is PS.DEFAULT or not supplied, default values are used for all properties.

Return value

PS.audioLoad() returns a string uniquely identifying the channel assigned to the sound. This identifier can be used for subsequent calls to PS.audioPause() and PS.audioStop().

// EXAMPLE:
// Preload and lock a library sound on startup for future use

PS.init = function( system, options ) {
   "use strict";

   // set up a 10 x 10 grid

   PS.gridSize( 10, 10 );

   // load and lock the sound

   PS.audioLoad( "fx_click", { lock : true } );
};

 

PS.audioPlay ( filename, options )

PS.audioPlay() plays an audio file, automatically loading it first if necessary.

Parameters:

  1. filename : string
  2. (optional) options : object or PS.DEFAULT

Returns: string or PS.ERROR

The filename parameter should be a case-sensitive string matching the filename of the audio to be played, without a file extension. By default, the file is assumed to reside in the Perlenspiel Audio Library. Note that library filenames are all lower-case.

The options parameter, if provided, should by a Javascript object containing one or more of the following properties:

See the documentation for PS.audioLoad() above for a detailed description of these properties.

If options is PS.DEFAULT or not supplied, default values are used for all properties.

Return value

PS.audioPlay() returns a string uniquely identifying the channel assigned to the sound. This identifier can be used for subsequent calls to PS.audioPause() and PS.audioStop().

If an error occurs, PS.audioPlay() returns PS.ERROR.

// EXAMPLES:

// Play a pop when any bead is clicked/touched

PS.touch = function( x, y, data, options ) {
   "use strict";

   PS.audioPlay( "fx_pop" );
};

// Play triangle at 75% volume
// when any key is pressed

PS.keyDown = function( key, shift, ctrl, options ) {
   "use strict";

   PS.audioPlay( "perc_triangle", { volume: 0.75 } );
};

 

PS.audioPause ( channel )

PS.audioPause() lets you pause and/or resume a previously played audio channel.

Parameters:

  1. channel : string

Returns: string or PS.ERROR

The channel parameter should be a channel identifier previously returned by a call to PS.audioPlay() or PS.audioPause().

If channel is playing, it will pause immediately. If channel is already paused as a result of a previous call to PS.audioPause(), it resumes playing at the point from which it was paused.

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

Return value

PS.audioPause() returns a string uniquely identifying the channel that was paused. This identifier can be used for subsequent calls to PS.audioPause() and PS.audioStop().

IMPORTANT: The channel identifier returned by PS.audioPause() may not be the same as the one passed in the channel parameter! Be sure to save this identifier for subsequent audio calls, as the original channel may no longer be valid.

PS.ERROR is returned if an error occurs.

 

PS.audioStop ( channel )

PS.audioStop() lets you stop a previously started audio channel.

Parameters:

  1. channel : string

Returns: PS.DONE or PS.ERROR

The channel parameter should be a channel identifier previously returned by a call to PS.audioPlay() or PS.audioPause().

If channel is playing, it stops immediately.

If channel is not playing, paused, already stopped or invalid, nothing happens.

Return value

PS.audioStop() returns PS.DONE on successful completion, otherwise PS.ERROR.

 

PS.piano ( note, long )

PS.piano() returns the filename of an indexed piano note.

Parameters:

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

Returns: string or PS.ERROR

The Perlenspiel Audio Library includes a piano with 88 keys, ranging from A0 to C8 inclusive.

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 long parameter determines which version's filename is returned. If long is true, the long version is returned. If long is false or not supplied, the short version is returned.

Return value

PS.piano() returns a string representing the filename of the piano sound specified by note and long.

PS.ERROR is returned if an error occurs.

// EXAMPLES:

// Play SHORT version of piano note 44
// when any bead is clicked/touched

PS.touch = function( x, y, data, options ) {
   "use strict";

   PS.audioPlay( PS.piano(44) );
};

// Play LONG version of piano note 32
// when any key is pressed

PS.keyDown = function( key, shift, ctrl, options ) {
   "use strict";

   PS.audioPlay( PS.piano( 32, true ) );
};

 

PS.harpsichord ( note, long )

PS.harpsichord() returns the filename of an indexed harpsichord note.

Parameters:

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

Returns: string or PS.ERROR

The Perlenspiel Audio Library includes a harpsichord with 57 keys, ranging from A2 to F7 inclusive.

PS.harpsichord() takes a note parameter 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 long parameter determines which version's filename is returned. If long is true, the long version is returned. If long is false or not supplied, the short version is returned.

Return value

PS.harpsichord() returns a string representing the filename of the harpsichord sound specified by note and long.

PS.ERROR is returned if an error occurs.

 

PS.xylophone ( note )

PS.xylophone() returns the filename of an indexed xylophone note.

Parameters:

  1. note : integer

Returns: string or PS.ERROR

The Perlenspiel Audio Library includes a xylophone with 39 notes, ranging from A4 to B7 inclusive.

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

Return value

PS.xylophone() returns a string representing the filename of the xylophone sound specified by note.

PS.ERROR is returned if an error occurs.

 

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.audioLoad() and PS.audioPlay() commands. Be sure the filename is spelled correctly! Note that filenames are all lower-case.

// EXAMPLE:
// Play a click when a bead is touched

PS.click = function ( x, y, data, options ) {
   "use strict";

   PS.AudioPlay( "fx_click" );
};

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.

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.

Harpsichord 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.

Xylophone notes

Taps on a 39-note xylophone (notes A4 to B7) are available. Each begins with a xylo_ prefix.

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