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

Since:

API Level 3.0.0

Name Value Since Description
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
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
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 Media.ContentRef) as Void

Delete an individual cached media item.

Parameters:

Since:

API Level 3.0.0

getCacheStatistics() as Media.CacheStatistics

Get the current size statistics of the media cache.

Returns:

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:

Returns:

Since:

API Level 3.0.0

Throws:

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:

Since:

API Level 3.0.0

Throws:

notifySyncComplete(errorMessage as Lang.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(Lang.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 Lang.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(Lang.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 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:

Since:

API Level 3.0.0

Throws:

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 Sep 25, 2023 12:31:46 PM