Skip to main content

<pc-sound>

The <pc-sound> tag adds a sound component, which plays the sounds of its <pc-sound-slot> children at its entity. Its settings — volume, pitch, and how positional sounds fade with distance — apply to all of its slots.

Usage

Attributes​

AttributeTypeDefaultDescription
distance-modelEnum"linear"How a positional sound fades between ref-distance and max-distance: "exponential" | "inverse" | "linear". "linear" fades it evenly, to silence at max-distance with the default roll-off-factor. "inverse" and "exponential" fade it quickly near the sound and more slowly further away. See the note below
enabledBoolean"true"Enabled state of the component
max-distanceNumber"10000"Distance beyond which a positional sound gets no quieter. With the "linear" model, it is where the sound fades out, so set it to about the size of your scene
pitchNumber"1"Pitch multiplier for all sounds in this component, multiplying each slot's own pitch
positionalBoolean"true"Whether the sounds are positional: panned and faded by where they are relative to the listener. Set it to "false" for music and interface sounds, which play the same everywhere
ref-distanceNumber"1"Distance within which a positional sound plays at full volume
roll-off-factorNumber"1"How quickly a positional sound fades with distance: higher values fade it faster. The "linear" model limits it to 0 to 1
volumeNumber"1"Volume for all sounds in this component, multiplying each slot's own volume
Hearing distance

A positional sound is panned by its direction from the <pc-audio-listener>, and fades with its distance from it — or from the world origin, when the scene has no listener. With the defaults, the "linear" model fades a sound over 10,000 units, so a sound 10 units away is barely quieter than one beside the listener. Set max-distance to about the size of your scene, as the Positional Sound example does with max-distance="12", or use distance-model="inverse", which halves the volume each time the distance doubles past ref-distance.

Example​

One sound component holding two slots — looping footsteps and a one-shot. The component's volume and pitch apply to every slot it holds; try halving the volume, or setting pitch="1.5" and re-running:

Live Example
<pc-app>
    <pc-asset src="https://developer.playcanvas.com/assets/footsteps.mp3" id="footsteps"></pc-asset>
    <pc-asset src="https://developer.playcanvas.com/assets/drop.mp3" id="drop"></pc-asset>
    <pc-scene>
        <pc-entity name="camera">
            <pc-camera clear-color="#1d1f2b"></pc-camera>
        </pc-entity>
        <pc-entity name="speaker">
            <pc-sound volume="1" pitch="1" positional="false">
                <pc-sound-slot name="footsteps" asset="footsteps" loop="true"></pc-sound-slot>
                <pc-sound-slot name="drop" asset="drop"></pc-sound-slot>
            </pc-sound>
        </pc-entity>
    </pc-scene>
</pc-app>
<div class="controls">
    <button id="toggle">Toggle footsteps</button>
    <button id="play-drop">Play drop</button>
</div>
<style>
    .controls {
        position: absolute;
        top: 12px;
        left: 12px;
        display: flex;
        gap: 8px;
    }
</style>
<script type="module">
    import { whenReady } from '@playcanvas/web-components';

    const sounds = await whenReady('pc-sound');
    const footsteps = sounds.component.slot('footsteps');
    document.getElementById('toggle').onclick = () => {
        footsteps.isPlaying ? footsteps.stop() : footsteps.play();
    };
    document.getElementById('play-drop').onclick = () => sounds.component.slot('drop').play();
</script>

JavaScript Interface​

You can programmatically create and manipulate <pc-sound> elements using the SoundComponentElement API.

The component property is the engine SoundComponent the element adds — null until the element is ready — and everything the attributes do not expose is available on it.

See Also​

Examples: Basic Sound, Positional Sound, Falling Blocks and Clock Tower.