Audio

The Audio object plays back audio files that have been imported to the project. It must be inserted to each project that needs to use audio playback. Audio files can be imported to a project by right-clicking the Sounds or Music folders in the Project Bar and selecting Import..., which brings up the Import Audio dialog. See the relevant sections for more information on the steps involved to import audio files.

Categorise audio files correctly

It is important to organise audio files appropriately, because audio files in the Sounds project folder are downloaded completely before playing, but files in the Music folder are streamed. This means if a Music track is accidentally put in the Sounds folder, it would have to download completely (which could take a couple of minutes) before it started playing. However, audio in the Music folder can start playing immediately since it is streamed from the server.

Preloading sounds

The Preload sounds project property determines whether sounds (excluding music) are downloaded while the loading bar is showing. Preloading sounds means there is more to download before the game can start, but all sound effects can play immediately once it starts. If sounds are not preloaded, the game starts sooner since it did not need to download any sounds, but sounds will be downloaded on-demand during the game. In other words, nothing is downloaded until a Play action starts playing an audio file. Then it starts downloading and will play when finished downloading. This also helps minimise the bandwidth requirement on the server since unused audio is never downloaded. However, it can introduce a delay before audio plays for the first time. The delay on first play is a one-off, because after the first play the sound is already downloaded and can be played immediately if played a second time.

The Preload action can also be used to start downloading an audio file without actually playing it. This can be done on Start of layout to start downloading a few important sound effects so there is no delay when they are played for the first time when Preload sounds is off. Note that preloading sounds when Preload sounds is Yes has no effect, because by the time the event can run all sounds will have already been loaded.

Music is never preloaded, since music tracks often involve a large download size, and it is not usually important to have music play with as little latency as possible. Music will still stream from the server while playing, but if the latency is important, the Preload action can be used to load it in advance of playing.

Audio tags

Some actions affect audio parameters such as the volume for sounds which are already playing. However there can often be many sounds playing at once in a game. In order to identify which sounds you want to affect, sounds are played with an associated tag. This is any string that identifies the sound. For example, the player's weapon sound effect could be played with the tag "PlayerWeapon" and an enemy's weapon with the tag "EnemyWeapon". Then, the tag can be used in the Set Volume action to specify which sound to set the volume for. Tags are case insensitive.

Multiple sounds can also play at once using the same tag. In this case actions like Set Volume affect all the sounds playing with that tag.

A tag which is an empty string ("") has a special meaning: it refers only to the last sound played with the Play action. This is convenient for playing a sound and immediately setting its volume and other parameters.

MIME types

Make sure after exporting your server has the correct MIME types set up, otherwise audio may fail to play in some browsers.

Mobile limitations

Safari on iOS and Chrome for Android share a limitation in playing music. While sound effects can be played at any time, music is only allowed to start playing when the user touches the screen. This is a limitation in the browsers themselves. As a result, if you play music on the start of layout, you may find in these browsers it does not actually start until the next touch.

Safari on iOS has a further limitation that no audio can play at all until the first touch. In other words, audio starts off muted and the first touch unmutes audio playback.

Usually you do not need to handle this in your events. If you try to play sound or music on 'start of layout', the audio object will automatically queue it up for playback the next time the user touches the screen. However you should be aware of this when designing your game. If the first touch changes layout or stops the music, then the music may never be heard. You may want to start playback then encourage the user to touch the screen with a 'Play' icon or something similar.

Advanced audio

The Audio object supports some advanced features, such as positioned sounds and convolution effects. However these depend on the Web Audio API which is not supported in all browsers. You can detect if these features are available using the Advanced audio supported condition. If it is not supported, the advanced audio features will not change the sound in any way.

Positioned sounds are an advanced audio feature that allow you to play a sound at a position, or on an object, in the layout. Using a 3D audio engine, the pan and volume are adjusted according to their relative position to the listener. This is an easy way to enhance realism and further immerse the player in the game.

Audio properties

Timescale audio

The game timescale can be used to speed up or slow down playback of the game, for effects like slow-motion. See Delta-time and framerate independence for more information. This property controls whether or not audio is affected by the game's timescale. Off will play back audio the same regardless of the timescale. On (sounds only) will play back audio from the Sounds project folder at a different rate depending on the timescale, but will always play back audio from the Music project folder at the same rate. On (sounds and music) will play back all audio at a different rate depending on the timescale. Some browsers may not support audio timescaling at all; test on multiple browsers to establish support. Also, different browsers may use different time-stretching algortihms for audio. Browsers can either alter pitch, going to lower pitch for lower time scales like a tape machine playing at a different speed; alternatively they can change the playback speed without affecting the pitch. Test on multiple browsers to establish the exact effect achieved.

Save/load

When using savegames, what audio state should be saved and restored. If All, all sound and music is saved and restored upon loading a game, so that music and sound effects keep rewinding to the same point they were at upon saving. Sounds only will only restore the sound effects playing at the time of the save, and allow music to keep playing through unaffected when loading a game. Music only conversely only restores the music playing at the time of the save, and allows sound effects to keep playing through unaffected when loading a game. None does not save or load any audio state at all. Audio will be completely unaffected when loading a game, and any playing music and sound effects will continue to play out to their end.

Play in background

If No, then switching browser tab, minimising the browser window, switching to a different mobile app, or otherwise hiding the window will pause all audio and resume it when switching back. This is intended to avoid annoying the user with continued music playback when deciding to do something else, and also helps save battery on mobile. However for some types of app such as music players it may be desirable to keep music playing in these cases, in which case setting to Yes allows continued audio playback even when in the background.

Panning model

How positioned sounds are panned. HRTF uses a realistic model of human hearing, whereas equal power is a simple method that preserves the overall power in a stereo channel.

Distance model

The formula to determine volume reduction of positioned sounds relative to the distance to the listener. The options are: Linear, using the equation 1 - rolloffFactor [] (distance - refDistance) / (maxDistance - refDistance)* Inverse, using the equation refDistance / (refDistance + rolloffFactor [] (distance - refDistance))* Exponential, using the equation pow(distance / refDistance, -rolloffFactor).

Listener Z height

The height of the listener above the layout, in layout pixels, used to determine relative volume and panning of positioned sounds. A low Z height will have intense changes over small distances, whereas a high Z height will have smaller changes over larger distances.

Reference distance

The distance at which the volume of positioned sounds begins to reduce. For best results this should be at least as much as the Listener Z height.

Maximum distance

The maximum distance in pixels beyond which positioned sounds no longer reduce their volume.

Roll-off factor

How quickly the volume reduces as positioned sounds move away from the listener. A high roll-off factor means sounds get quieter quickly, whereas a low roll-off factor means sounds will not lose much volume.

Speed of sound

The speed of sound, in layout pixels per second, used for determining the doppler shift of positioned sounds.

Doppler factor

How much pitch shift occurs due to the doppler effect. A value of 0 will disable doppler effects completely, and values greater than 1 will exaggerate the doppler effect.

Audio conditions

Advanced audio supported

If true, the current browser supports all the features in the Advanced categories of the Audio object. If false, none of these features will have any effect on playback.

Is any playing

True if any audio is currently playing.

Is silent

True if the object has been set in to silent mode using the Set silent action.

Is tag playing

True if any audio with a given tag is currently playing.

On ended

Triggered when a sound with a given tag finishes playing. This is not triggered for looping sounds.

Preloads complete

True when all audio preloaded with one of the preload actions has finished loading.

Audio actions: General

Play

Play (by name)

Start playing an audio file with a given tag. The latter action gives you the opportunity to use an expression for the audio file name. The sound can optionally be set to looping when it starts playing. A volume can also be set, given in decibels (dB). A volume of 0 dB is original volume, and below 0 dB attenuates the sound. Note amplification is not supported. For example, entering a value of -10 plays the audio back 10 dB quieter (about half as loud). Prefer setting the intended volume in the Play action; even if followed immediately by a Set volume action, some platforms will momentarily play the audio at the volume given in the Play action.

Preload

Preload (by name)

Start downloading an audio file so it has no delay before playing. See the section Preloading sounds above for more information. Audio does not have to be preloaded before playing - it is optional and only serves to possibly reduce the delay before audio plays for the first time. Once all audio preloaded with this action finishes loading, the On preloads complete trigger fires. Note if the project Preload sounds property is Yes, there is no point preloading any sounds, since they will always be loaded before the game starts - in this case it only makes sense to preload music.

Seek to

Seek a currently playing sound to a different location in the audio file. The time to seek to is given in seconds.

Set looping

Set a sound either looping (repeating when it finishes) or not looping (stopping when it finishes). Not all browsers currently support this feature; test on multiple browsers to identify support.

Set master volume

Set the overall volume that is applied to all audio playback.

Set muted

Set a sound either muted (silent) or unmuted (audible).

Set paused

Pause or resume some audio by its tag.

Set playback rate

Change the rate a sound plays back at. Different browsers may use different time-stretching algorithms (either pitch preserving or pitch altering) or not support the option at all; test in multiple browsers to identify the actual affect achieved. If the Timescale audio property is enabled, it combines with the playback rate set by this action.

Set silent

Enable, disable or toggle Silent mode. In silent mode all currently playing sounds are muted and no new sounds will play. This is useful for quickly creating an audio toggle on a title screen.

Set volume

Change the volume of a sound. The volume is given in decibels (dB). A volume of 0 dB is original volume, and below 0 dB attenuates the sound. Note amplification is not supported. For example, entering a value of -10 plays the audio back 10 dB quieter (about half as loud). Note it is best to set the initial volume in the Play action instead of setting it with this action immediately after playing, since that can sometimes cause a moment of playback at the wrong volume.

Stop

Stop a sound playing immediately.

Stop all

Stop all currently playing sounds.

Audio actions: Positioned sound

Play at object

Play at object (by name)

As per the ordinary Play actions, but the sound is positioned at an object. If the object moves or rotates during playback, the sound follows with it. The velocity of the object is used to determine doppler shifts. A cone can be specified to create directional sounds, which follows the object's angle.

Play at position

Play at position (by name)

As per the Play at object action, but the sound does not move. It is simply played at a position and angle in the layout. Doppler effects can still occur based on the listener's velocity relative to the sound.

Set listener Z

Set the Listener Z property of the audio object.

Audio actions: Effects

A selection of well-known audio effects can be added using the "Add effect" actions. Each tag has its own effect chain, and multiple effects can be added to a tag. All audio played with the given tag is then processed by the effect chain. This can be used to create environmental effects and other creative audio features. Audio signal processing is a complex topic and somewhat out of the scope of this manual, so it will not be detailed exhaustively here. Anyone with light experience in audio recording or production should already be familiar with all the effects available. For interactive examples, search for Audio in Construct 2's Start dialog. A brief summary of each effect is provided below:

• Analyser: doesn't change the audio, but can report back frequency domain data
• Compressor: automatically boost or reduce volume to even out the overall volume level
• Convolution: an advanced effect using another sound as an impulse response to process the audio. This allows for real-world locations to be recorded and the environmental reverb applied to games
• Delay: a feedback loop with a delay, making a sort of simple echo effect.
• Distortion: a guitar-amplifier style signal distortion
• Filter: boost or reduce certain frequencies, such as a low-pass filter (which cuts out high frequencies). Useful for simple atmospherics, treble/bass adjustment, etc.
• Flanger: delays the sound by a few milliseconds then mixes it back in with itself. By oscillating the delay time a sweeping effect is created
• Gain: a simple volume control, which might be useful in longer effect chains. The Mute effect is also simply a zero gain effect, which can be useful to add after analysers (so the audio is analysed, but not heard).
• Phaser: phase-shifts the sound then mixes it back in with itself. By oscillating the phase shift another sweeping effect is created
• Tremolo: automatically oscillates the volume up and down, also known as amplitude modulation. Some interesting amplitude modulation effects can be created by moving the modulation frequency in to the audible range (above 20 Hz).
• Ring modulator: like tremolo, but oscillates all the way through to a full phase inversion

The Remove all effects action clears a tag's effects chain, allowing you to add a different selection of effects. The Set effect parameter also allows effect parameters to by dynamically set or faded during playback. Each effect also has a wet/dry mix which can be used to fade in and fade out effects.

Audio actions: Other

Schedule next play

This action causes the next Play action (all variants) to be delayed until the specified time. The delayed playback is sample-accurate. Typically events are only run every 16ms making it difficult to schedule sounds more accurately than that, but this action allows for perfectly scheduled playback, even in between ticks. If the specified time is in the past, it will play immediately. The time given must be relative to the audio hardware clock, which is returned by the CurrentTime expression, so typically sounds will be scheduled a short time ahead using an expression of the form Audio.CurrentTime + N. See the Audio scheduling example in Construct 2 for a demonstration.

Audio expressions

AnalyserFreqBinAt(Tag, Index, Bin)

Get the magnitude of energy in an analyser's frequency bin. Advanced audio must be supported, and an analyser effect already added to a tag. Index must be the index of the effect (for example, 0 if the analyser is the first added effect for that tag, 1 if the second added effect, and so on). Bin is the frequency bin number to retrieve from, up to AnalyserFreqBinCount.

AnalyserFreqBinCount(Tag, Index)

Get the number of frequency bins returned by an analyser. Advanced audio must be supported, and an analyser effect already added to a tag. Index must be the index of the effect (for example, 0 if the analyser is the first added effect for that tag, 1 if the second added effect, and so on).

AnalyserPeakLevel(Tag, Index)

Get the peak level of audio in the last FFT window from an analyser. Index must be the index of the effect (for example, 0 if the analyser is the first added effect for that tag, 1 if the second added effect, and so on). The value is returned in dBFS (0 dB for peak level, and negative values for lower). If you intend to use this value it is recommended to use an FFT size of 1024, because at a system sample rate of 44.1 KHz the value will update about 43 times a second. Games usually run at 60 FPS, and smaller FFT sizes may cause FFT windows to be missed since they change faster than the framerate.

AnalyserRMSLevel(Tag, Index)

Get the RMS level of audio in the last FFT window from an analyser (the square root of the average of the squared sample values). Index must be the index of the effect (for example, 0 if the analyser is the first added effect for that tag, 1 if the second added effect, and so on). The value is returned in dBFS (0 dB for peak level, and negative values for lower). If you intend to use this value it is recommended to use an FFT size of 1024, because at a system sample rate of 44.1 KHz the value will update about 43 times a second. Games usually run at 60 FPS, and smaller FFT sizes may cause FFT windows to be missed since they change faster than the framerate.

EffectCount(Tag)

Get the number of effects in the effect chain for a tag.

CurrentTime

Get the audio clock time in seconds. Where supported, this is returned from the audio hardware, providing the correct time against which to schedule audio playback. It is important to use this value to calculate playback times in the Schedule next play action.

Duration(Tag)

Get the duration in seconds of an audio sample with a tag.

MasterVolume

Return the current master volume set using the Set master volume action.

PlaybackTime(Tag)

Get the current playback time in seconds of a sound with a tag. This starts at 0 and counts up to the duration, except for looping sounds which keep counting up past the duration.

SampleRate

Return the audio output sample rate in Hz, typically 44100 or 48000.

Volume(Tag)

Get the volume set for a sound with a tag.