Module: Toybox.Media

Overview

The Media module provides objects and methods for implementing audio content provider apps.

This includes interfaces and methods for managing downloaded media content as well as interfaces used to provide required information to the system for playback.

Since:

API Level 3.0.0

App Types:

• Audio Content Provider

• Background

Classes Under Namespace

Classes: ActiveContent, AlbumArt, AudioFormat, CacheStatistics, Content, ContentDelegate, ContentIterator, ContentMetadata, ContentRef, ContentRefIterator, CustomButton, PlaybackProfile, PlayerColors, ProviderIconInfo, SyncDelegate, SystemButton

Constant Summary

PlaybackPosition

Since:

API Level 3.0.0

Name	Value	Since	Description	See Also
PLAYBACK_POSITION_START	0	API Level 3.0.0	The playback position when the song has begun to play

ContentType

Since:

API Level 3.0.0

Name	Value	Since	Description	See Also
CONTENT_TYPE_INVALID	0	API Level 3.0.0	Invalid content type
CONTENT_TYPE_AUDIO	1	API Level 3.0.0	Content type for Audio

Encoding

Since:

API Level 3.0.0

Name	Value	Since	Description	See Also
ENCODING_INVALID	0	API Level 3.0.0	Invalid encoding type
ENCODING_ADTS	1	API Level 3.0.0	ADTS audio encoding type
ENCODING_MP3	2	API Level 3.0.0	MP3 audio encoding type
ENCODING_M4A	3	API Level 3.0.0	M4A audio encoding type
ENCODING_WAV	4	API Level 3.0.0	WAV audio encoding type

ImageFormat

Since:

API Level 3.0.0

Name	Value	Since	Description	See Also
IMAGE_FORMAT_INVALID	0	API Level 3.0.0	Invalid media content image format
IMAGE_FORMAT_JPEG	1	API Level 3.0.0	JPEG media content image format
IMAGE_FORMAT_PNG	2	API Level 3.0.0	PNG media content image format

PlaybackControl

Since:

API Level 3.0.0

Name	Value	Since	Description	See Also
PLAYBACK_CONTROL_SHUFFLE	2	API Level 3.0.0	The "shuffle" operation is allowed
PLAYBACK_CONTROL_PREVIOUS	3	API Level 3.0.0	The "previous track" operation is allowed
PLAYBACK_CONTROL_NEXT	4	API Level 3.0.0	The "next track" operation is allowed
PLAYBACK_CONTROL_SKIP_FORWARD	5	API Level 3.0.0	The "skip forward x seconds" operation is allowed
PLAYBACK_CONTROL_SKIP_BACKWARD	6	API Level 3.0.0	The "skip backward x seconds" operation is allowed
PLAYBACK_CONTROL_REPEAT	7	API Level 3.0.0	The "repeat" operation is allowed
PLAYBACK_CONTROL_RATING	9	API Level 3.0.3	The track "rating" operation is allowed
PLAYBACK_CONTROL_PLAYBACK	10	API Level 3.0.3	The "play/pause" operation is allowed
PLAYBACK_CONTROL_VOLUME	11	API Level 3.0.3	The "volume" button - if not provided it will be added to the end of the playback controls
PLAYBACK_CONTROL_SOURCE	12	API Level 3.0.3	The "source" button - if not provided it will be added to the end of the playback controls
PLAYBACK_CONTROL_LIBRARY	13	API Level 3.0.3	The "library" button - If provided it will be used for the library button UI.

SongEvent

Since:

API Level 3.0.0

Name	Value	Since	Description	See Also
SONG_EVENT_START	0	API Level 3.0.0	Indicates that a song was started from the beginning.	ContentDelegate.onSong()
SONG_EVENT_SKIP_NEXT	1	API Level 3.0.0	Indicates that a song was skipped and the next song was requested.	ContentDelegate.onSong()
SONG_EVENT_SKIP_PREVIOUS	2	API Level 3.0.0	Indicates that a song was skipped and the previous song was requested.	ContentDelegate.onSong()
SONG_EVENT_PLAYBACK_NOTIFY	3	API Level 3.0.0	Indicates that a song was played for the duration set in PlaybackProfile.playbackNotificationThreshold.	ContentDelegate.onSong()
SONG_EVENT_COMPLETE	4	API Level 3.0.0	Indicates that a song was completed.	ContentDelegate.onSong()
SONG_EVENT_STOP	5	API Level 3.0.0	Indicates that a song was stopped in the middle of playback.	ContentDelegate.onSong()
SONG_EVENT_PAUSE	6	API Level 3.0.0	Indicates that a song was paused in the middle of playback.	ContentDelegate.onSong()
SONG_EVENT_RESUME	7	API Level 3.0.0	Indicates that a song was resumed after being paused.	ContentDelegate.onSong()
SONG_EVENT_SKIP_FORWARD	8	API Level 4.2.4	Indicates that a song was skipped forward by the number of seconds specified in PlaybackProfile.skipForwardTimeDelta.	ContentDelegate.onSong()
SONG_EVENT_SKIP_BACKWARD	9	API Level 4.2.4	Indicates that a song was skipped forward by the number of seconds specified in PlaybackProfile.skipBackwardTimeDelta.	ContentDelegate.onSong()

RepeatMode

Since:

API Level 3.0.0

Name	Value	Since	Description	See Also
REPEAT_MODE_OFF	0	API Level 3.0.0	Repeat is off
REPEAT_MODE_ONE	1	API Level 3.0.0	Repeat the current track
REPEAT_MODE_ALL	2	API Level 3.0.0	Repeat all tracks

ButtonState

Since:

API Level 3.0.0

Name	Value	Since	Description	See Also
BUTTON_STATE_DEFAULT	0	API Level 3.0.3	The default state for a button. This is a valid state for all buttons.
BUTTON_STATE_DISABLED	1	API Level 3.0.3	The button is shown but not selectable. This is a valid state for all buttons.
BUTTON_STATE_ON	2	API Level 3.0.3	The button is considered "on". This is a valid state for the PLAYBACK_CONTROL_PLAYBACK, PLAYBACK_CONTROL_SHUFFLE, and PLAYBACK_CONTROL_REPEAT buttons.
BUTTON_STATE_OFF	3	API Level 3.0.3	The button is considered "off". This is a valid state for the PLAYBACK_CONTROL_PLAYBACK, PLAYBACK_CONTROL_SHUFFLE, and PLAYBACK_CONTROL_REPEAT buttons.
BUTTON_STATE_ALL	4	API Level 3.0.3	The button is considered in the "on" and "all" states. This is a valid state the for the PLAYBACK_CONTROL_SHUFFLE (shuffle all) and PLAYBACK_CONTROL_REPEAT (repeat all) buttons.
BUTTON_STATE_POSITIVE	5	API Level 3.0.3	The button is considered in the "positive" state. This is a valid state the for the PLAYBACK_CONTROL_RATING button.
BUTTON_STATE_NEGATIVE	6	API Level 3.0.3	The button is considered in the "negative" state. This is a valid state the for the PLAYBACK_CONTROL_RATING button.
BUTTON_STATE_NEUTRAL	7	API Level 3.0.3	The button is considered in the "neutral" state. This is a valid state the for the PLAYBACK_CONTROL_RATING button.

ButtonImage

Since:

API Level 3.0.0

Name	Value	Since	Description	See Also
BUTTON_IMAGE_ICON	0	API Level 3.0.3	The normal sized button image
BUTTON_IMAGE_DETAIL	1	API Level 3.0.3	The larger image for when the icon is highlighted

Instance Method Summary

• deleteCachedItem(contentRef as Media.ContentRef) as Void

  Delete an individual cached media item.

• getCacheStatistics() as Media.CacheStatistics

  Get the current size statistics of the media cache.

• getCachedContentObj(contentRef as Media.ContentRef) as Media.Content

  Get a Content object by ID from what has been persisted on the system.

• getContentRefIter(options as { :contentType as Media.ContentType, :shuffle as Lang.Boolean }) as Media.ContentRefIterator

  Get a ContentRefIterator object.

• notifySyncComplete(errorMessage as Lang.String or Null) as Void deprecated

  Send a system notification to indicate that the sync completed.

• notifySyncProgress(percentageComplete as Lang.Number) as Void deprecated

  Send a system notification to indicate overall sync progress.

• requestPlaybackProfileUpdate() as Void

  Request that the media player call ContentIterator.getPlaybackProfile().

• resetContentCache() as Void

  Delete the cached media content and reset the encryption key for the app.

• setAlbumArt(albumArt as Graphics.BitmapType or Null) as Void

  Set the album art for the currently playing song.

• startPlayback(args as Application.PersistableType) as Void

  Exit the AudioContentProviderApp in its current mode and launch it in playback mode.

• startSync() as Void deprecated

  Exit the AudioContentProviderApp in its current mode and launch it in sync mode.

• stopPlayback() as Void

  Stops playback if it was initiated by the app.

Instance Method Details

deleteCachedItem(contentRef as Media.ContentRef) as Void

Delete an individual cached media item.

Parameters:

• contentRef — (Media.ContentRef) —

  The ContentRef for the Content object to be deleted

Since:

API Level 3.0.0

getCacheStatistics() as Media.CacheStatistics

Get the current size statistics of the media cache.

Returns:

• Media.CacheStatistics —

  The current CacheStatistics object

Since:

API Level 3.0.0

getCachedContentObj(contentRef as Media.ContentRef) as Media.Content

Get a Content object by ID from what has been persisted on the system.

Parameters:

• contentRef — (Media.ContentRef) —

  The ContentRef object for the desired media Content

Returns:

• Media.Content —

  The desired Content object

Since:

API Level 3.0.0

Throws:

• (Lang.UnexpectedTypeException) —

  Thrown if contentRef parameter is not a valid Toybox::Media::ContentRef object Thrown if ID field of provided Toybox::Media::ContentRef object is not a string but content type is set to CONTENT_TYPE_AUDIO

• (Lang.InvalidOptionsException) —

  Thrown if provided Toybox::Media::ContentRef has an invalid content type

getContentRefIter(options as { :contentType as Media.ContentType, :shuffle as Lang.Boolean }) as Media.ContentRefIterator

Get a ContentRefIterator object.

The ContentRefIterator is used to iterate over all cached media on the system for the calling app.

Parameters:

• options — (Lang.Dictionary) —

  A Dictionary of options

  • :contentType — (Lang.Number) —

    One of the CONTENT_TYPE_* values that indicates the type of cached content.

  • :shuffle — (Lang.Boolean) —

    • When true, the ContentRef objects will be returned in a random order

    • When false, the ContentRef objects will be returned in a consistent order that is system dependent

Returns:

• Media.ContentRefIterator

Since:

API Level 3.0.0

Throws:

• (Lang.InvalidOptionsException) —

  Thrown if :contentType value is invalid

notifySyncComplete(errorMessage as Lang.String or Null) as Void

This has been deprecated

This method may be removed after System 9.

Send a system notification to indicate that the sync completed.

Parameters:

• errorMessage — (Lang.String) —

  A descriptive error message if a failure occurred. If the sync completes successfully, null should be passed to this method.

See Also:

• Communications.notifySyncComplete()

Since:

API Level 3.0.0

notifySyncProgress(percentageComplete as Lang.Number) as Void

This has been deprecated

This method may be removed after System 9.

Send a system notification to indicate overall sync progress.

Parameters:

• percentageComplete — (Lang.Number) —

  An integer from 0 to 100 indicating the completion percentage.

See Also:

• Communications.notifySyncProgress()

Since:

API Level 3.0.0

requestPlaybackProfileUpdate() as Void

Request that the media player call ContentIterator.getPlaybackProfile()

Since:

API Level 3.0.3

resetContentCache() as Void

Delete the cached media content and reset the encryption key for the app.

Since:

API Level 3.0.0

setAlbumArt(albumArt as Graphics.BitmapType or Null) as Void

Set the album art for the currently playing song

Note:

BitmapReference is only supported in CIQ 4.0.0 and later

Parameters:

• albumArt — (WatchUi.BitmapResource, BitmapReference) —

  The album art to display. If null then the system's default album art will be displayed.

Since:

API Level 3.0.10

startPlayback(args as Application.PersistableType) as Void

Exit the AudioContentProviderApp in its current mode and launch it in playback mode.

Parameters:

• args — (Lang.Object) —

  A serializable object to pass to AudioContentProviderApp.getContentDelegate() when the app starts in playback mode.

Since:

API Level 3.0.0

Throws:

• (Lang.SerializationException) —

  Thrown when the given argument cannot be serialized or is too large for serialization.

startSync() as Void

This has been deprecated

This method may be removed after System 9.

Exit the AudioContentProviderApp in its current mode and launch it in sync mode.

See Also:

• Communications.startSync()

Since:

API Level 3.0.0

stopPlayback() as Void

Stops playback if it was initiated by the app. If playback was not initiated by the app, calling stopPlayback() will do nothing.

Since:

API Level 3.1.8