SoundEffect

SoundEffect plays short audio sound effects that can be triggered from UI events

import { SoundEffect } from "@roku-sdk/components";

SoundEffect(props: ISoundEffectProps): JSX.Element

Description

SoundEffect plays short audio sound effects that can be triggered from UI events. Files can be installed locally as part of the package or dynamically downloaded from the network. All files must be WAV (PCM) format. Up to four simultaneous sounds can play at any time.

For local files, the convention is to include WAV files in a directory named sounds. For downloaded files, a least-recently-used (LRU) mechanism keeps the most recently played sounds in temporary storage on the device.

Playback can be controlled declaratively via the control prop or imperatively via a SoundEffectRef obtained through the ref prop.

Parameters

Example

// Declarative control via the control prop
<soundEffect
    uri="pkg:/sounds/click.wav"
    control={SoundEffectControl.Play}
    volume={50}
    onState={(state) => console.log("SoundEffect state:", state)}
/>

// Imperative control via ref
let sfxRef!: SoundEffectRef;
<soundEffect ref={sfxRef} uri="pkg:/sounds/click.wav" volume={50} />
// Then trigger playback: sfxRef.play()

// Network-hosted sound with load status monitoring
<soundEffect
    uri="https://example.com/sounds/alert.wav"
    onLoadStatus={(status) => {
        if (status === SoundEffectLoadStatus.Ready) console.log("Sound ready to play");
    }}
/>

Types

ISoundEffectProps

Properties for the SoundEffect node.

The SoundEffect node plays short audio sound effects triggered from UI events. Up to four simultaneous sounds can play at any time, in addition to audio from streaming content and TextToSpeech audio. All files must be WAV (PCM) format.

Extends INodeProps.

ISoundEffectProps.control

Controls the audio playback. Getting the value returns the most recent value set, or "none" if no value has been set.

• "none" -- No effect.
• "play" -- Start playing the audio. Restarts if already playing. If loadStatus
  is not "ready", the sound will not play and state becomes "notready".
• "stop" -- Stop playing the audio if it is currently playing.

ISoundEffectProps.onLoadStatus

Fired when the load status of the sound file changes.

Possible values: "none", "loading", "ready", "failed", "flushed".

ISoundEffectProps.onState

Fired when the playback state changes.

Possible values: "none", "playing", "stopped", "finished", "toomanysounds", "notready".

SoundEffectControl

Control values for the SoundEffect control field.

SoundEffectLoadStatus

Load status values reported by the SoundEffect loadStatus field.

SoundEffectState

Playback state values reported by the SoundEffect state field.