Audio

Audio plays streaming audio content

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

Audio(props: IAudioProps): JSX.Element

Description

Audio plays streaming audio content. It has no built-in visual UI, but you can build your own UI including trick play, album art, or any graphical elements for user interaction.

Audio playlists are supported by setting contentIsPlaylist to true and providing a ContentNode with child ContentNodes for each audio in the playlist.

Parameters

Name	Type	Description
`props`	IAudioProps

Example

<Audio
    content={<contentNode url="https://example.com/song.mp3" streamFormat="mp3" />}
    control="play"
    onState={(state) => console.log("Audio state:", state)}
    onPosition={(pos) => console.log("Position:", pos)}
/>

// Audio playlist
<Audio
    content={playlist}
    contentIsPlaylist={true}
    loop={true}
    control="play"
    onContentIndex={(idx) => console.log("Now playing track:", idx)}
/>

Types

IAudioProps

Properties for the Audio node.

The Audio node plays streaming audio. It has no built-in visual UI, but you can build your own UI for the node, including trick play, or showing an album cover or similar graphical image for each song selected by a user.

Name	Type	Description
`autoplayAfterSeek?`	`boolean`	When false, disables auto-play after rebuffering following a seek.
`content?`	`Element`	The ContentNode with the content metadata for the audio or audio playlist to be played. If an audio playlist is to be played, the ContentNode must include complete child ContentNodes for each audio in the playlist.
`contentIsPlaylist?`	`boolean`	When true, enables audio playlists. The ContentNode set in `content` must have children ContentNodes for each audio in the playlist. All audios will be played in sequence.
`control?`	`MediaControl`	Sets the desired play state for the audio (e.g. "play", "pause", "stop", "prebuffer"). To dynamically monitor the actual state, observe the `onState` event.
`loop?`	`boolean`	When true, the audio or audio playlist will be restarted from the beginning after the end is reached.
`mute?`	`boolean`	Set to true to mute the audio currently playing. Set to false to restore audio.
`nextContentIndex?`	`number`	Sets the index of the next audio in the playlist to be played. Takes effect when the current audio is completed or skipped. Resets to -1 after the specified audio begins.
`notificationInterval?`	`number`	The interval between position event notifications, in seconds. If 0, no notifications are delivered.
`onAudioFormat?`	`EventHandler<AudioFormat>`	Fired when the format of the currently playing audio changes.
`onBufferingStatus?`	`EventHandler<IAudioBufferingStatus>`	Fired when buffering progress or status changes. Valid only while buffering is in progress, both at stream startup or when re-buffering is required.
`onContentIndex?`	`EventHandler<number>`	Fired when the current playlist content index changes. Set to 0 for single audio when playlists are not enabled.
`onDuration?`	`EventHandler<number>`	Fired when the audio duration is known or changes. Value is in seconds; becomes valid when playback begins.
`onErrorCode?`	`EventHandler<number>`	Fired when an error code is set after the state changes to "error".
`onErrorMsg?`	`EventHandler<string>`	Fired when an error message is set describing an audio play error.
`onPosition?`	`EventHandler<number>`	Fired on position updates at the interval specified by `IAudioProps.notificationInterval`.
`onState?`	`EventHandler<MediaState>`	Fired when the audio play state changes. Possible values: "none", "buffering", "playing", "paused", "stopped", "finished", "error".
`onStreamInfo?`	`EventHandler<IAudioStreamInfo>`	Fired when stream info for the currently playing or buffering audio is updated.
`onStreamingSegment?`	`EventHandler<IAudioStreamingSegment>`	Fired with information about the audio segment currently streaming. Only meaningful for segmented transports (DASH, HLS).
`onTimedMetaData?`	`EventHandler<object>`	Fired when timed metadata (e.g. ID3 tags) matching `IAudioProps.timedMetaDataSelectionKeys` is decoded from the audio stream.
`onTimeToStartStreaming?`	`EventHandler<number>`	Fired when the time-to-start-streaming value is available. Value is the time in seconds from playback being started until audio actually began playing (minimum 0.001s). Only valid when state is "playing".
`seek?`	`number`	Sets the current position in the audio in seconds from the beginning of the stream (write-only).
`timedMetaDataSelectionKeys?`	`string[]`	If the audio stream contains timed metadata such as ID3 tags, any metadata with a key matching an entry in this array will be reported via `onTimedMetaData`. If any entry is "*", all timed metadata will be selected.

Extends IGroupProps.

AudioFormat

Audio codec format reported by the Audio node audioFormat field.

type AudioFormat = "" | "aac" | "aac_adif" | "aac_adts" | "aac_latm" | "ac3" | "alac" | "dts" | "eac3" | "flac" | "mp2" | "mp3" | "none" | "pcm" | "unknown" | "vorbis" | "wma" | "wmapro";

IAudioBufferingStatus

Buffering progress information from the Audio node.

Valid only while buffering is in progress, both at stream startup or when re-buffering is required.

Name	Type	Description
`buffering`	`number`	Percent buffering complete as an integer.
`percent`	`number`	Percent buffering complete as an integer.

IAudioStreamInfo

Information about the audio stream currently playing or buffering.

Name	Type	Description
`isResumed`	`boolean`	If true, playback was resumed after trickplay.
`isUnderrun`	`boolean`	If true, the stream was downloaded due to an underrun.
`measuredBitrate`	`number`	The measured bitrate (bps) of the network when the stream was selected.
`streamBitrate`	`number`	The bitrate of the stream.
`streamUrl`	`string`	The URL of the stream.

IAudioStreamingSegment

Information about the audio segment currently streaming (HLS/DASH).

Name	Type	Description
`hdrModeStr`	`HDRmode`	The HDR format of the content.
`segBitrateBps`	`number`	Bitrate of the segment in bits per second.
`segSequence`	`number`	The sequence number of the segment in the audio.
`segStart`	`number`	The start time of the segment from the start of the audio, in seconds.
`segTypeStr`	`string`	The type of data in the segment: "unknown", "mux", "audio", "video", or "captions".
`segUrl`	`string`	URL of the segment.

HDRmode

HDR mode reported in streamingSegment data.

type HDRmode = "invalid" | "unknown" | "none" | "hdr10" | "dolby_vision" | "hlg10" | "sl-hdr2";

Updated about 5 hours ago

What’s Next

BifDisplay

Did this page help you?