Version: latest

Audio

Description

The Audio component allows you to play audio resources and 3D sound effects. It supports spatialization and basic controls - such as stop and start - using WAV, MP3, and OGG format files. Loaded file and Streamed file audio components require an audio resource, which is the audio file you want to play.

Example

โš ๏ธ Don't forget to include the resources in your app.package file!
import React from "react";
import { View, Audio,Scene, Prism } from "magic-script-components";
export default class MyApp extends React.Component {
render() {
return (
<Prism size={[1.0, 1.0, 1.0]} >
<Scene>
<View name="main-view">
<Audio
fileName="resources/your-audio-file.mp3"
loadFile={true}
action="start"
/>
</View>
</Scene>
</Prism>
);
}
}

Common Events

Common Properties

Create Properties

NameTypeDefault ValueRequiredDescriptionLuminAndroidIOS
fileNamestringn/aYFile name of the resource to load. By default this is assumed to be a relative path from the executable file.๐Ÿ‘๐Ÿ‘๐Ÿ‘
loadFilebooleanfalseNLoads the entire audio file in the memory. For large files sizes you may use the createStreamedFileAudioResource method instead.๐Ÿ‘
absolutePathbooleanfalseNFlags that fileName as an absolute path name instead of a relative path.๐Ÿ‘
descriptornumber-1NOptional file descriptor that points to a resource.๐Ÿ‘
basePathstringnullNIf you are loading a resource from an absolute path, and that path is not the current process path, set this field to the equivalent base path in the other client directory. This allows path relative dependencies to solve a fully qualified (absolute) path outside of the current process. This value defaults to the currently executing process root.๐Ÿ‘
autoDestroybooleanfalseNIf true, play the sound once and delete the node. If false the audio node will stay until the scenegraph is destroyed.๐Ÿ‘
dynamicDecodebooleanfalseNIf true, the file resource is compressed and is decoded when playing. If false, the file resource is uncompressed PCM data.๐Ÿ‘

Element Properties

NameTypeDefault ValueDescriptionLuminAndroidIOS
actionstringn/aSets the current operation: start, stop, pause, resume๐Ÿ‘๐Ÿ‘๐Ÿ‘
soundLoopingbooleanfalseSets audio playback to repeat mode. If enabled, audio plays from the start after reaching the end until disabled. When audio is created this is disabled by default.๐Ÿ‘๐Ÿ‘๐Ÿ‘
soundMutebooleanfalseMutes or unmutes the sound.๐Ÿ‘๐Ÿ‘๐Ÿ‘
soundPitchnumber1.0Sets the sound pitch. The range of the pitch is 0.5 to 2.0, with 0.5 being one octave down and 2.0 being one octave up.๐Ÿ‘
soundVolumeLinearnumbern/aSets the audio volume. The range of the volume is 0 to 8, with 0 for silence, 1 for unity gain, and 8 for 8x gain.๐Ÿ‘๐Ÿ‘๐Ÿ‘
spatialSoundEnablebooleanfalseEnables or disables the capability for spatial sound. If enabled, spatialSoundPosition must have a value for positional sound to be effective.๐Ÿ‘๐Ÿ‘๐Ÿ‘
streamedFileOffsetnumbern/aSets the starting point for playback of a streamed-file sound.๐Ÿ‘
spatialSoundDirectionobjectn/aSets the sound direction of a given audio channel. This is effective only if spatial sound is enabled (spatialSoundEnable) for an audio node. The direction is relative to the node's local orientation. By default the direction is the same as the parent node's orientation. If the audio file is already playing, the direction changes during playback when the sound direction is set.๐Ÿ‘๐Ÿ‘๐Ÿ‘
spatialSoundDirectSendLevelsobjectn/aSets the direct send levels for one channel of a sound output. When 3D audio processing is enabled for a sound output (spatialSoundEnabled) this property sets the send levels for the direct component of the sound, i.e., the audio mix for the part of the sound not affected by room acoustics. Multi-channel sounds require the direct send levels to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.๐Ÿ‘
spatialSoundDistanceobjectn/aSets spatial sound distance parameters for a given channel.๐Ÿ‘๐Ÿ‘๐Ÿ‘
spatialSoundPositionobjectn/aSets the position of a given audio channel relative to the node's local position. This is effective only if spatial sound is enabled (spatialSoundEnable) for an audio node. This changes the position even if the audio clip is already playing.๐Ÿ‘๐Ÿ‘๐Ÿ‘
spatialSoundRadiationobjectn/aSets spatial sound radiation parameters for a given channel.๐Ÿ‘
spatialSoundRoomSendLevelsobjectn/aSets the room send levels for one channel of a sound output. When 3D audio processing is enabled for a sound output (spatialSoundEnabled) this function sets the send levels for the room component of the sound, i.e., the audio mix for the part of the sound that is affected by room acoustics. Multi-channel sounds require the room send levels to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.๐Ÿ‘

spatialSoundDirection

{
channel: number,
channelDirection: quat
}

spatialSoundDirectSendLevels

{
channel: number,
gain: number,
gainHf: number,
gainLf: number,
gainMf: number
}

spatialSoundDistance

{
channel: number,
minDistance: number,
maxDistance: number,
rolloffFactor: number
}

spatialSoundPosition

{
channel: number,
channelPosition: vec3
}

spatialSoundRadiation

{
channel: number,
innerAngle: number,
outerAngle: number,
outerGain: number,
outerGainHf: number
}

spatialSoundRoomSendLevels

{
channel: number,
gain: number,
gainHf: number,
gainLf: number,
gainMf: number
}