audio

Module(s): vncanvas-base, vncanvas-media
Description: Play a sound or music.

  • The audio volume can be set in configuration file.
  • Audio can be muted in-game. Uses a reserved variable "_mute_audio".

audio, {param}
Play a sound or music.
Parameters are given as {param:value, param:value, ...}
Parameter Attributes and Description
bgm:"path_to_sound_file_no_extension"
bgs:"path_to_sound_file_no_extension"
se:"path_to_sound_file_no_extension"
Set the type of audio as one of the given types: background music (bgm), background sound (bgs) or sound effect (se).
Specify the full path on first time play. Can specify just filename on next actions as long as the filename is unique.
BGMs are looping and auto-replaced on new BGM.
BGS are also looping but multiple BGS can be played simultaneously.
SEs are non-looping and multiple SE can be played simultaneously.
Accepts a user variable as path to the sound files, still without extension.
format:[array_of_formats]
Optional
Engine autodetects which of the given formats is playable on the platform. For maximum compatibility with all browsers, provide multiple formats for the audio (typically, "ogg" and "mp3").
Default audio formats may be set in Config file and are used if format is not given.
action:"action_name"
Optional
Perform the given action on the audio file.
Valid actions are "play", "stop", "rewind", "pause", "remove".
Default action if not specified is "play".
"remove" is only applicable for "se" and "bgs". "bgm" is automatically removed on instantiation of next "bgm".
repeat:number
Optional
Number of times to repeat when playing SE. If not specified, default value is 0 or no repeat.
delay:number
Optional
Number of seconds to wait before an audio is played. If not specified, default value is 0 or no delay.
When used with repeat, it also acts as interval between plays.
adjust:number
Optional
NEW! Volume can now be adjusted per audio/sound.
An adust value<0 softens the audio. An adjust value>0 makes it louder.
A series of audio files will be played as given below. 
  
chapter = [

	...
	/* plays audio1 as BGM and chooses among the given which format is playable */
	audio, {bgm:"media/audio1", format:["ogg","mp3"]},
	...
	/* pauses the play of BGM, note format and full path are not required for
	subsequent actions */
	audio, {bgm:"audio1", action:"pause"},
	...
	/* replace BGM with a new one after a 2 second delay */
	audio, {bgm:"media/audio2", format:["ogg"], delay:2},
	...
	/* play 2 BGS simultaneously */
	audio, {bgs:"media/audio3", format:["mp3"]},
	audio, {bgs:"media/audio4", format:["wav"]},
	...
	/* stops audio3, note since multiple BGS can be played, need to
	identify which BGS on subsequent actions, also note that the
	full path no longer need to be specified */
	audio, {bgs:"audio3", action:"stop"},
	...
	/* play a SE 10 times with 1 second interval between play,
	note also that to play 10 times, repeat it 9 times */
	audio, {se:"media/audio5", format:["ogg"], repeat:9, delay:1},
	...
	/* remove audio3 from the list, this does not affect gameplay
	but is useful for memory management if the audio is no longer needed */
	audio, {bgs:"audio3", action:"remove"},
	...
	/* set a reserved user variable to mute sounds */
	set, {_mute_audio:true},	/* mutes all audio */
	set, {_mute_audio:false},	/* unmute all audio */
];