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

Name Value Since Description
PLAYBACK_POSITION_START 0

API Level 3.0.0

The playback position when the song has begun to play

ContentType

Name Value Since Description
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

Name Value Since Description
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

Name Value Since Description
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

Name Value Since Description
PLAYBACK_CONTROL_SHUFFLE 0

API Level 3.0.0

The "shuffle" operation is allowed

PLAYBACK_CONTROL_PREVIOUS 1

API Level 3.0.0

The "previous track" operation is allowed

PLAYBACK_CONTROL_NEXT 2

API Level 3.0.0

The "next track" operation is allowed

PLAYBACK_CONTROL_SKIP_FORWARD 3

API Level 3.0.0

The "skip forward x seconds" operation is allowed

PLAYBACK_CONTROL_SKIP_BACKWARD 4

API Level 3.0.0

The "skip backward x seconds" operation is allowed

PLAYBACK_CONTROL_REPEAT 5

API Level 3.0.0

The "repeat" operation is allowed

PLAYBACK_CONTROL_RATING 6

API Level 3.0.3

The track "rating" operation is allowed

PLAYBACK_CONTROL_PLAYBACK 7

API Level 3.0.3

The "play/pause" operation is allowed

PLAYBACK_CONTROL_VOLUME 8

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 9

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 10

API Level 3.0.3

The "library" button - If provided it will be used for the library button UI.

SongEvent

Name Value Since Description
SONG_EVENT_START 0

API Level 3.0.0

Indicates that a song was started from the beginning.

SONG_EVENT_SKIP_NEXT 1

API Level 3.0.0

Indicates that a song was skipped and the next song was requested.

SONG_EVENT_SKIP_PREVIOUS 2

API Level 3.0.0

Indicates that a song was skipped and the previous song was requested.

SONG_EVENT_PLAYBACK_NOTIFY 3

API Level 3.0.0

Indicates that a song was played for the duration set in PlaybackProfile.playbackNotificationThreshold.

SONG_EVENT_COMPLETE 4

API Level 3.0.0

Indicates that a song was completed.

SONG_EVENT_STOP 5

API Level 3.0.0

Indicates that a song was stopped in the middle of playback.

SONG_EVENT_PAUSE 6

API Level 3.0.0

Indicates that a song was paused in the middle of playback.

SONG_EVENT_RESUME 7

API Level 3.0.0

Indicates that a song was resumed after being paused.

RepeatMode

Name Value Since Description
REPEAT_MODE_OFF 0

Repeat is off

REPEAT_MODE_ONE 1

Repeat the current track

REPEAT_MODE_ALL 2

Repeat all tracks

ButtonState

Name Value Since Description
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

Name Value Since Description
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 collapse

Instance Method Details

deleteCachedItem(contentRef as ContentRef) as Void

Delete an individual cached media item.

Parameters:

  • contentRef(ContentRef)

    The ContentRef for the Content object to be deleted

Since:

API Level 3.0.0

getCacheStatistics() as CacheStatistics

Get the current size statistics of the media cache.

Returns:

Since:

API Level 3.0.0

getCachedContentObj(contentRef as ContentRef) as Content

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

Parameters:

  • contentRef(ContentRef)

    The ContentRef object for the desired media Content

Returns:

  • Content

    The desired Content object

Since:

API Level 3.0.0

Throws:

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

Get a ContentRefIterator object.

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

Parameters:

  • options(Dictionary)

    A Dictionary of options

    • :contentType(Number)

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

    • :shuffle(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:

Since:

API Level 3.0.0

Throws:

notifySyncComplete(errorMessage as String or Null) as Void

This has been deprecated

This method will be removed in Connect IQ 6.0.0

Send a system notification to indicate that the sync completed.

Parameters:

  • errorMessage(String)

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

See Also:

Since:

API Level 3.0.0

notifySyncProgress(percentageComplete as Number) as Void

This has been deprecated

This method will be removed in Connect IQ 6.0.0

Send a system notification to indicate overall sync progress.

Parameters:

  • percentageComplete(Number)

    An integer from 0 to 100 indicating the completion percentage.

See Also:

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 BitmapType) 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(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 PersistableType) as Void

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

Parameters:

Since:

API Level 3.0.0

Throws:

  • (SerializationException)

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

startSync() as Void

This has been deprecated

This method will be removed in Connect IQ 6.0.0

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

See Also:

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


Generated Apr 22, 2021 10:10:32 AM