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

Supported Devices:

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.

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

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

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

  • 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 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(Media.ContentType)

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

    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:

    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 may be removed after System 9.

    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 Jun 6, 2024 10:31:53 AM