Skip to main content

<pc-audio-listener>

The <pc-audio-listener> tag makes its entity the point from which positional sounds are heard — usually the entity holding the <pc-camera>, so that sounds pan and fade as the view moves.

Only one listener is in use at a time: the one most recently enabled. Disabling it doesn't hand over to another, and sounds are heard from where it last was until a listener is enabled again. Without any listener, positional sounds are heard from the world origin, facing down the negative Z axis.

Usage

Attributes​

AttributeTypeDefaultDescription
enabledBoolean"true"Enabled state of the component

Example​

The listener sits on the camera, and a sphere emitting positional footsteps circles in front of it. Put headphones on: the sound pans left and right as the sphere crosses, and with distance-model="inverse" it grows louder as the sphere comes near. Browsers gate audio behind a user gesture, so click Play to start. Then try deleting the <pc-audio-listener>: the sound is heard from the world origin, in the middle of the orbit, and circles around you at a steady volume:

Live Example
<pc-app>
    <pc-asset src="https://developer.playcanvas.com/assets/footsteps.mp3" id="footsteps"></pc-asset>
    <pc-material id="floor" diffuse="#3a3f4b"></pc-material>
    <pc-scene>
        <pc-entity name="camera" position="0 2.5 6" rotation="-15 0 0">
            <pc-camera clear-color="#1d1f2b"></pc-camera>
            <!-- Positional sounds are heard from this entity -->
            <pc-audio-listener></pc-audio-listener>
        </pc-entity>
        <pc-entity name="light" rotation="45 30 0">
            <pc-light cast-shadows normal-offset-bias="0.05" shadow-bias="0.2"></pc-light>
        </pc-entity>
        <pc-entity name="ground" scale="14 14 14">
            <pc-render type="plane" material="floor"></pc-render>
        </pc-entity>
        <pc-entity name="pivot">
            <pc-script>
                <pc-script-instance name="orbit"></pc-script-instance>
            </pc-script>
            <pc-entity name="emitter" position="3 1 0" scale="0.4 0.4 0.4">
                <pc-render type="sphere"></pc-render>
                <pc-sound positional="true" distance-model="inverse" ref-distance="2" roll-off-factor="1">
                    <pc-sound-slot name="footsteps" asset="footsteps" loop="true"></pc-sound-slot>
                </pc-sound>
            </pc-entity>
        </pc-entity>
    </pc-scene>
</pc-app>
<button id="play" style="position: absolute; top: 12px; left: 12px;">Play</button>
<script type="module">
    import { registerScript, Script } from 'playcanvas';
    import { whenReady } from '@playcanvas/web-components';

    await whenReady('pc-app');

    class Orbit extends Script {
        update(dt) {
            this.entity.rotate(0, 45 * dt, 0);
        }
    }

    registerScript(Orbit, 'orbit');

    const sounds = await whenReady('pc-sound');
    document.getElementById('play').onclick = () => sounds.component.slot('footsteps').play();
</script>

JavaScript Interface​

You can programmatically create and manipulate <pc-audio-listener> elements using the AudioListenerComponentElement API.

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

See Also​

Examples: Positional Sound and Clock Tower.