Skip to end of metadata
Go to start of metadata

Table of Contents


Extends: Node

Description

The Audio node class plays streaming audio. It only can play mp3 files.

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

FieldTypeDefaultUse
contentContentNodeNULLThe ContentNode node 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 node must include complete child ContentNode nodes for each audio in the playlist, with all attributes required to play that audio.
contentIsPlaylistBooleanfalse

If set to true, enables audio playlists (a sequence of audios to be played). To enable audio playlists, the ContentNode node set in the content field must have children ContentNode nodes for each audio in the playlist. When audio playback is started, all of the audios in the playlist will be played in sequence.
Available since firmware version 7.2

nextContentIndexinteger-1

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.
Available since firmware version 7.2

loopBooleanfalseIf 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.
Available since firmware version 7.2
bufferingStatusassociative arrayinvalid

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.

ValueMeaning
percentagePercent buffering complete as an integer.
isUnderrunBoolean value indicating if a stream underrun occurred.

Available since firmware version 7.2

controloption string"none"

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.

OptionEffect
noneNo play state set 
playStart audio play
startStart audio play
stopStop audio play
pausePause audio play
resumeResume audio play after a pause
replayReplay audio
prebufferStarts 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.
Available since firmware version 7.2

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.
Available since firmware version 7.2

notificationIntervaltime0.5The 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[ ]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.
Available since firmware version 7.2
seektimeinvalid

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.

contentIndexinteger-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.
Available since firmware version 7.2

timedMetaDataassociative 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.
Available since firmware version 7.2

statevalue string"none"

Read-Only
Describes the current audio play state, such as if the audio play has been paused.

ValueMeaning
noneNo current play state
bufferingAudio stream is currently buffering 
playingAudio is currently playing
pausedAudio is currently paused
stoppedAudio is currently stopped
finishedAudio 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.
positiontimeinvalid 

Read-Only
The current position in the audio play, as the number of seconds.

durationtime0Read-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.
errorCodeinteger

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.

audioFormatstring"" 

Read-Only
Contains the format of the currently playing audio.

ValueMeaning

mp3 

ISO/IEC 11172-3, MPEG Audio Layer III
streamingSegmentassociative 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:

KeyTypeValue
segBitrateBpsintegerBitrate of the segment in bits per second
segSequenceintegerThe sequence number of the segment in the audio
segStartTimetimeThe start time of the segment from the start of the audio, specified in seconds
segUrlstringURL of the segment

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 node 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:

  • HttpCertificatesFile
  • HttpCookies
  • HttpHeaders
  • HttpSendClientCertificates

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.

In firmware versions prior to 7.2, each Audio and Video node created and configured an HttpAgent only 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. Channels 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 the HttpAgent before playing each piece of content.

Example

Example application: AudioExample.zip

AudioExample.zip 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.

 

  • No labels