Audio
Extends Node
The Audio node class plays streaming audio.
The Audio node class 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.
Fields
| Field | Type | Default | Access Permission | Description | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| content | ContentNode | NULL | READ_WRITE | The ContentNode with the Content Meta-Data for the audio or audio playlist (a sequence of audios) to be played. If a audio playlist is to be played, the ContentNode must include complete child ContentNodes for each audio in the playlist, with all attributes required to play that audio. | ||||||||||||||||||||||||||||||||||||||
| contentIsPlaylist | Boolean | false | READ_WRITE | If set to true, enables audio playlists (a sequence of audios to be played). To enable audio playlists, the ContentNode set in the content field must have children ContentNodes for each audio in the playlist. When audio playback is started, all of the audios in the playlist will be played in sequence. | ||||||||||||||||||||||||||||||||||||||
| nextContentIndex | integer | -1 | READ_WRITE | If the contentIsPlaylist field is set to true to enable audio playlists, sets the index of the next audio in the playlist to be played. Setting this field does not immediately change the audio being played, but takes effect when the current audio is completed or skipped. By default, this value is -1, which performs the default index increment operation. After the audio specified by the index in this field begins playing, the field is set to the default -1 again, so the next audio played will be set by the default index increment operation, unless the field is set again to a different index. | ||||||||||||||||||||||||||||||||||||||
| loop | Boolean | false | READ_WRITE | If set to true, the audio or audio playlist (if the contentIsPlaylist field is set to true to enable audio playlists) will be restarted from the beginning after the end is reached. | ||||||||||||||||||||||||||||||||||||||
| bufferingStatus | associative array | invalid | READ_ONLY | Contains information about stream buffering progress and status. This field is valid only while buffering is in progress, both at stream startup or when re-buffering is required. Observers will be notified when any element of the array changes, and also when buffering is complete and the field itself becomes invalid. The array contains the following name - value pairs.
| ||||||||||||||||||||||||||||||||||||||
| Value | Meaning | |||||||||||||||||||||||||||||||||||||||||
| percentage | Percent buffering complete as an integer. | |||||||||||||||||||||||||||||||||||||||||
| isUnderrun | Boolean value indicating if a stream underrun occurred. | |||||||||||||||||||||||||||||||||||||||||
| control | option string | none | READ_WRITE | Sets the desired play state for the audio, such as starting or stopping the audio play. Getting the value of this field returns the most recent value set, or none if no value has been set. In order to dynamically monitor the actual state of the audio, see the state field.
| ||||||||||||||||||||||||||||||||||||||
| Option | Effect | |||||||||||||||||||||||||||||||||||||||||
| none | No play state set | |||||||||||||||||||||||||||||||||||||||||
| play | Start audio play | |||||||||||||||||||||||||||||||||||||||||
| start | Start audio play | |||||||||||||||||||||||||||||||||||||||||
| stop | Stop audio play | |||||||||||||||||||||||||||||||||||||||||
| pause | Pause audio play | |||||||||||||||||||||||||||||||||||||||||
| resume | Resume audio play after a pause | |||||||||||||||||||||||||||||||||||||||||
| replay | Replay audio | |||||||||||||||||||||||||||||||||||||||||
| prebuffer | Starts buffering the audio stream before the Audio node actually begins playback. Only one audio stream can be buffering in the application at any time. Setting the control field to prebuffer for another audio stream after setting prebuffer for a previous audio stream stops the buffering of the previous audio stream. | |||||||||||||||||||||||||||||||||||||||||
| skipcontent | Skip the currently-playing content, and begin playing the next content in the playlist. If the content is not a playlist, or if the current content is the end of the playlist, this will end playback. | |||||||||||||||||||||||||||||||||||||||||
| notificationInterval | time | 0.5 | READ_WRITE | The interval between notifications to observers of the position field, specified as the number of seconds. If the value is 0, no notifications are delivered. This value may be read or modified at any time. | ||||||||||||||||||||||||||||||||||||||
| timedMetaDataSelectionKeys | array of strings | [ ] | READ_WRITE | If the audio stream contains timed meta data such as ID3 tags, any meta data with a key matching an entry in this array will be set into the timedMetaData field. If any entry in this array is "*", then all timed meta data will be selected. | ||||||||||||||||||||||||||||||||||||||
| seek | time | invalid | WRITE_ONLY | Sets the current position in the audio. The value is the number seconds from the beginning of the stream, specified as a double. | ||||||||||||||||||||||||||||||||||||||
| contentIndex | integer | -1 | READ_ONLY | The index of the audio in the audio playlist that is currently playing. Generally, you would only want to check this field if audio playlists are enabled (by setting the contentIsPlaylist field to true), but it is set to 0 when a single audio is playing and audio playlists are not enabled. | ||||||||||||||||||||||||||||||||||||||
| timedMetaData | associative array | READ_ONLY | The most recent timed meta data that has been decoded from the audio stream. Only meta data with a key that matches an entry in timedMetaDataSelectionKeys will be set into this field. The value of this field is an associative array which contains arbitrary keys and values, as found in the audio stream. As of Roku OS 10.5, this field can be used to read ID3 tags embedded in an audio stream. | |||||||||||||||||||||||||||||||||||||||
| state | value string | none | READ_ONLY | Describes the current audio play state, such as if the audio play has been paused.
| ||||||||||||||||||||||||||||||||||||||
| Value | Meaning | |||||||||||||||||||||||||||||||||||||||||
| none | No current play state | |||||||||||||||||||||||||||||||||||||||||
| buffering | Audio stream is currently buffering | |||||||||||||||||||||||||||||||||||||||||
| playing | Audio is currently playing | |||||||||||||||||||||||||||||||||||||||||
| paused | Audio is currently paused | |||||||||||||||||||||||||||||||||||||||||
| stopped | Audio is currently stopped | |||||||||||||||||||||||||||||||||||||||||
| finished | Audio has completed play | |||||||||||||||||||||||||||||||||||||||||
| error | An error has occurred in the audio play. The error code and error message can be found in the errorCode and errorMsg fields respectively. | |||||||||||||||||||||||||||||||||||||||||
| position | time | invalid | READ_ONLY | The current position in the audio play, as the number of seconds. | ||||||||||||||||||||||||||||||||||||||
| duration | time | 0 | READ_ONLY | The duration of the audio being played, specified in seconds. This becomes valid when playback begins and may change if the audio is dynamic content, such as a live event. | ||||||||||||||||||||||||||||||||||||||
| errorCode | integer | 0 | READ_ONLY | The error code associated with the audio play error set in the state field | ||||||||||||||||||||||||||||||||||||||
| errorMsg | string | READ_ONLY | An error message describing the audio play error set in the state field. | |||||||||||||||||||||||||||||||||||||||
| audioFormat | string | READ_ONLY | Contains the format of the currently playing audio.
| |||||||||||||||||||||||||||||||||||||||
| Value | Meaning | |||||||||||||||||||||||||||||||||||||||||
| "" | No stream playing | |||||||||||||||||||||||||||||||||||||||||
| aac | ISO/IEC 14496-3, Advanced Audio Coding | |||||||||||||||||||||||||||||||||||||||||
| aac_adif | ISO/IEC 14496-3, Advanced Audio Coding, ADIF container | |||||||||||||||||||||||||||||||||||||||||
| aac_adts | ISO/IEC 14496-3, Advanced Audio Coding, ADTS container | |||||||||||||||||||||||||||||||||||||||||
| aac_latm | ISO/IEC 14496-3, Advanced Audio Coding, LATM container | |||||||||||||||||||||||||||||||||||||||||
| ac3 | Dolby Digital | |||||||||||||||||||||||||||||||||||||||||
| alac | Apple Lossless | |||||||||||||||||||||||||||||||||||||||||
| dts | DTS Coherent Acoustics | |||||||||||||||||||||||||||||||||||||||||
| eac3 | Dolby Digital Plus | |||||||||||||||||||||||||||||||||||||||||
| flac | Free Lossless Audio Codec | |||||||||||||||||||||||||||||||||||||||||
| mp2 | ISO/IEC 11172-3, MPEG Audio Layer II | |||||||||||||||||||||||||||||||||||||||||
| mp3 | ISO/IEC 11172-3, MPEG Audio Layer III | |||||||||||||||||||||||||||||||||||||||||
| none | Stream contains no playable audio | |||||||||||||||||||||||||||||||||||||||||
| pcm | linear PCM | |||||||||||||||||||||||||||||||||||||||||
| unknown | Stream contains unknown audio | |||||||||||||||||||||||||||||||||||||||||
| vorbis | Ogg Vorbis | |||||||||||||||||||||||||||||||||||||||||
| wma sunset as of Roku OS 12.5 | Microsoft Windows Media Audio. As of Roku OS 10.5, the Roku platform no longer supports this audio format. As part of the Roku OS 12.5 release, this format was officially sunset. | |||||||||||||||||||||||||||||||||||||||||
| wmapro sunset as of Roku OS 12.5 | Microsoft Windows Media Pro Audio. As of Roku OS 10.5, the Roku platform no longer supports this audio format. As part of the Roku OS 12.5 release, this format was officially sunset. | |||||||||||||||||||||||||||||||||||||||||
| streamingSegment | associative array | READ_ONLY | Information about the audio segment that is currently streaming. This is only meaningful for segmented audio transports, such as DASH and HLS. The associative array has the following entries:
| |||||||||||||||||||||||||||||||||||||||
| Key | Type | Value | ||||||||||||||||||||||||||||||||||||||||
| segBitrateBps | integer | Bitrate of the segment in bits per second | ||||||||||||||||||||||||||||||||||||||||
| segSequence | integer | The sequence number of the segment in the audio | ||||||||||||||||||||||||||||||||||||||||
| segStart | time | The start time of the segment from the start of the audio, specified in seconds | ||||||||||||||||||||||||||||||||||||||||
| segUrl | string | URL of the segment | ||||||||||||||||||||||||||||||||||||||||
| segTypeStr | string | The type of data in the segment: "unknown", "mux", "audio", "video", or "captions". | ||||||||||||||||||||||||||||||||||||||||
| hdrModeStr | string | The HDR format of the content, which may be one of the following values:
| ||||||||||||||||||||||||||||||||||||||||
| focusedChild | N/A | N/A | READ_WRITE | When a node or one of its children gains or loses the keyboard focus, the focusedChild field will be set and call its observer functions. In the observer function, typically, you use ifSGNodeFocus functions to query whether this node or some other node has the key focus or is in the key focus chain. Accessing the value of the field will result in script errors. | ||||||||||||||||||||||||||||||||||||||
| autoplayAfterSeek | boolean | true | READ_WRITE | Enables audio content to automatically play after rebuffering. Setting this flag to false disables this default behavior. | ||||||||||||||||||||||||||||||||||||||
| mute | boolean | false | READ_WRITE | Set to true to mute the audio currently playing in the Audio node. Set to false to restore audio. | ||||||||||||||||||||||||||||||||||||||
| streamInfo | associative array | invalid | READ_ONLY | Information about the audio stream that is currently playing or buffering.
| ||||||||||||||||||||||||||||||||||||||
| Key | Type | Value | ||||||||||||||||||||||||||||||||||||||||
| isUnderrun | Boolean | If true, the stream was downloaded due to an underrun | ||||||||||||||||||||||||||||||||||||||||
| isResumed | Boolean | If true, playback was resumed after trickplay | ||||||||||||||||||||||||||||||||||||||||
| measuredBItrate | Integer | The measured bitrate (bps) of the network when the stream was selected | ||||||||||||||||||||||||||||||||||||||||
| streamBitrate | Integer | The bitrate of the stream | ||||||||||||||||||||||||||||||||||||||||
| streamUrl | URI | The URL of the stream | ||||||||||||||||||||||||||||||||||||||||
| timeToStartStreaming | time | 0 | READ_ONLY | The time in seconds from playback being started until the audio actually began playing. The minimum valid value is 1 millisecond, and this is only valid if the current value of the state field is playing. When the state field value is not playing, the value will be 0. This field is updated prior to the state field changing, so state field observer callback functions can assume this field is valid after the state field value changes to playing. | ||||||||||||||||||||||||||||||||||||||
Data bindings
See Content Meta-Data for the required and optional play parameters, and descriptive information for audio playback. Set these parameters in a ContentNode node, and assign the ContentNode to the content field of the Audio node to apply the parameters to a particular audio content item.
For HTTPS access, note the following Content Meta-Data attributes:
HttpCertificatesFileHttpCookiesHttpHeadersHttpSendClientCertificates
These attributes must be set to handle secure HTTP transfers of audio files. Note that this is a different HTTPS mechanism than used for other SceneGraph nodes as described in roHttpAgent.
Prior to Roku OS 7.2, each Audio and Video node created and configured an
HttpAgentonly when the first content was played in a given Audio or Video node instance. This sometimes meant that additional content would fail to play in the same node because headers, cookies, and certificates were not updated or correctly replaced from the new content record. Apps that are dependent upon this behavior will need to be updated to set the required data into the Content Meta-Data for each piece of content, or to programmatically set those values into theHttpAgentbefore playing each piece of content.
Example
Example application: AudioExample
AudioExample uses a LabelList node to select from several spoken audio examples. The Content Meta-Data for the example is found in the pkg:/server/audiocontent.xml file, read into a ContentNode node by the Task node audiocontentreader.xml component file.
Sample app
AudioExample is a sample app demonstrating Audio in action.
Updated 2 months ago