Bixby Developer Center

Guides

AudioPlayer (bixby.audioPlayer)

The bixby.audioPlayer library capsule allows your capsule to play audio streams on mobile from within the Bixby client. Bixby currently supports the following audio file formats: AAC/MP4, MP3, and HLS, with Bitrates ranging from 16 kbps to 384 kbps.

For an example of using bixby.audioPlayer, read about the example.audio sample capsule.

Concepts

Types are always in the bixby.* namespace, and in the bixby.audioPlayer.* namespace unless another namespace is specified. All properties have a cardinality of min (Optional), max (One) unless otherwise specified.

AudioInfo

The AudioInfo structure concept is a wrapper for the inputs necessary to play audio on Bixby. To play an audio file or stream, your capsule must create an AudioInfo concept that will be passed to the PlayAudio action.

AudioInfo is a higher-level structure that holds metadata about how Bixby should present the audio to the user, as well as one or more AudioItem structures, which contain the actual data for audio streams/files.

PropertyTypeKindNotes
categoryCategoryenummin (Required)
displayNameDisplayNametextmin (Required)
repeatModeRepeatModeenum
startAudioItemIndexStartAudioItemIndexinteger
audioItemAudioItemstructuremin (Required), max(Many)
doNotWaitForTTSDoNotWaitForTTSboolean 

By default, Bixby will wait for text-to-speech (dialog) to complete before playing audio. If doNotWaitForTTS is set to true, Bixby will immediately play audio provided without waiting for TTS to complete. In this case, you should suppress TTS for the action by providing empty dialog. If you do not, Bixby will talk over the audio, causing the audio to stop.

The displayName is the display name of the capsule.

If more than one audioItem is supplied, you can supply a value for startAudioItemIndex to indicate which audioItem should be played first.

Category

The Category enum in AudioInfo tells the notification bar on mobile which types of media controls to show during playback.

Category only supports one setting on mobile devices, MUSIC. It should always be set to this value.

RepeatMode

The RepeatMode enum in AudioInfo lets you choose between repeating playback of only the current AudioItem, all items (from start to end and then back to the beginning, like a playlist), or not repeating (playing each AudioItem in order and then stopping).

SymbolDescription
OFFdo not repeat
ALLrepeat all of the entire playlist
ONErepeat the currently-playing item

AudioItem

The AudioItem structure concept defines a single audio stream that Bixby will play. At least one AudioItem should be included in the AudioInfo concept passed to PlayAudio.

PropertyTypeKindNotes
idIDtextmin (Required)
streamStreamstructuremin (Required), max (Many)
titleTitletextmin (Required)
subtitleSubtitletext
artistArtisttextmin (Required)
albumArtUrlHreftextmin (Required)
durationDurationintegerduration in seconds
albumNameAlbumNametext 

The title will be shown as the title for the AudioPlayer system notification while the audio file is playing. If provided, the subtitle might also be shown, depending on the playback device.

Stream

PropertyTypeKindNotes
urlHreftextmin(Required)
formatFormattextmin(Required); see below
tokenTokentext
offsetInMillisecondsOffsetInMillisecondsinteger 

The format should be a MIME type for the kind of audio stream being played, such as audio/mp4.

The offsetInMilliseconds indicates where in the stream the client should start playback when playing this stream.

The token field is not currently used.

Playing Audio

The heart of bixby.AudioPlayer is the PlayAudio action. It takes an AudioInfo concept as input and starts the audio player. While PlayAudio outputs a Result concept, it is not intended to be consumed.

To use PlayAudio, your capsule should implement its own play action that calls PlayAudio by creating a computed-input.

action (PlaySound) {
type (Search)
collect {
input (soundToPlay) {
type (audioPlayer.AudioInfo)
min (Required) max (One)
hidden
}
computed-input (sound) {
type (audioPlayer.Result)
compute {
intent {
goal: audioPlayer.PlayAudio
value: $expr(soundToPlay)
}
}
hidden
}
}
output (Result)
}

The Result model output by PlaySound is, like audioPlayer.Result, an empty model. This is not required, however; your capsule could return any value here.

text (Result) {
}

The local-endpoint JavaScript file for PlaySound can also return any value without affecting functionality, as the actual work of playing sound is being performed by audioPlayer.PlayAudio.

module.exports.function = function playSound () {
return 'played';
}

Your capsule's play action could also build the AudioInfo object in its first input step. See the example.audio sample capsule for an illustration of this: the PlayMeow action takes an empty AudioInfo object and populates it by using BuildMeowAudioInfo.

Note

You do not have to create commands for media control such as Stop, Pause, and Next. These are supported by the system itself.