Audio APIs
Horizon’s AudioGizmo object enables creators to use TypeScript to add music and sound effects to their worlds. The AudioGizmo API provides control of the gizmo’s audio playback, volume, and pitch settings. This will make it possible to programmatically enhance your world’s audio capabilities.
NOTE: If a player is running a local script and they include just the local player in this array, the sound will only play locally, avoiding networking costs for playing/stopping/pausing the audio.
The AudioGizmo class includes the Audio Playback actions of play, pause, and stop.
For each Audio Playback function, an AudioOptions object can be provided. This will allow you to configure the fade-in and fade-out timing. It can also create an optional list of Players (users) that will be able to hear the audio.
- fade [number]: Specifies the number of seconds for the audio to fade-in or fade-out.
- players [(Optional) Array (Player)]: Specifies the list of players the AudioGizmo can be played to, paused, or stopped. If a list isn’t provided, this action applies to all players in the world.
The AudioGizmo plays sound from its original source.
- options [(Optional) AudioOptions] - an object to configure the audio settings when starting the audio clip.
Void
The AudioGizmo pauses the sound from its original source. When the play() function is called, the sound resumes from where it was paused, rather than starting from the beginning.
- options [(Optional) AudioOptions] - an object to configure the audio settings when pausing the audio clip.
Void
The AudioGizmo stops playing the sound from its original source. When the play() function is called, the sound starts from the beginning.
- options [(Optional) AudioOptions] - an object to configure the audio settings when stopping the audio clip.
Void
Example of audio playback const soundGizmo = this.props.sfx.as(AudioGizmo);
soundGizmo.play(); // Plays for all players immediately.
var pauseOptions: AudioOptions = {fade: 1};
soundGizmo.pause(pauseOptions); // Pauses for all players after fading out for 1 second.
soundGizmo.play();
var stopOptions: AudioOptions = {fade: 0.2, players: [this.props.mainPlayer]};
soundGizmo.stop(stopOptions); // Stops the audio for the specified player after 0.2 seconds.
Audio volume and pitch APIs
The AudioGizmo class includes the actions of volume and pitch.
Controls the volume level for the AudioGizmo, overriding the value set in the Object Property Panel.
- volume [Number] - The value of this parameter ranges from 0 to 1. Decimal fractions are allowed (for example, 0.3). Overrides the volume level set on the AudioGizmo’s Object Property Panel.
- options [ AudioOptions ] - An object to configure the audio settings when a volume change is performed.
Void
Controls the pitch for the AudioGizmo, overriding the value set in the Object Property Panel. When configuring the pitch of an AudioGizmo, the following pitch and speed calculations need to be considered:
- 12 semitones = 1 octave.
- An increase in 1 octave makes the audio 2x as fast.
- A decrease in 1 octave makes the audio ½ as fast.
- pitch [Number] - The value of this parameter ranges from -24 to 24. Overrides the pitch level set on the AudioGizmo’s Object Property Panel.
Void
Example of audio volume and pitch const soundGizmo = this.props.sfx.as(AudioGizmo);
const volOptions: AudioOptions = {fade: 0.5};
soundGizmo.volume.set(0.8, volOptions);
soundGizmo.pitch.set(12);
Audio clip completion APIs
If you have actions to perform once an audio source run has completed, you can listen for the
OnAudioCompleted CodeBlockEvent in your TypeScript code. For full details on listening for CodeBlockEvents, see the
Built-In Events section.
CodeBlockEvents.OnAudioCompletedThis event will trigger when the audio source has completed.
None
Example of triggering on audio clip completion this.connectCodeBlockEvent(
this.entity, // Make sure this Entity is an AudioGizmo.
() => {
// Perform an action upon completion of the audio clip.
});
