sdk/fidl/fuchsia.media.sessions/session.fidl

// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.media.sessions;

using zx;
using fuchsia.media;
using fuchsia.media.audio;
using fuchsia.math;

/// `ReadOnlySession` is a handle for media playback, allowing clients to observe
/// a playback session.
[FragileBase]
protocol ReadOnlySession {
    /// Sent on first connection and when playback
    /// status changes.
    -> OnPlaybackStatusChanged(PlaybackStatus playback_status);
    /// Sent on first connection and when metadata
    /// changes.
    -> OnMetadataChanged(fuchsia.media.Metadata media_metadata);
    /// Sent on first connection if there are images, and when media images
    /// change. Sends only the image type that has changed: if album
    /// art changes but not source icon, the source icon is not re-sent.
    -> OnMediaImagesChanged(vector<MediaImage> media_images);

    /// Returns the bitmap for a given image url. This url is expected to be a
    /// url the session gave the client in an `OnMediaImagesChanged` event. If
    /// the minimum size is not available or the url is not recognized, the
    /// session may return a null image.
    GetMediaImageBitmap(string url,
                        fuchsia.math.Size minimum_size,
                        fuchsia.math.Size desired_size) -> (MediaImageBitmap? media_image_bitmap);
};

/// `Session` is a handle for media playback, allowing clients to observe
/// and control a media playback session. Unsupported commands are no-ops.
/// Consult `PlaybackCapabilities`, sent by `OnPlaybackCapabilities`, to learn
/// which commands are supported.
protocol Session {
    compose ReadOnlySession;

    /// Sent on first connection and when supported
    /// playback capabilities change.
    -> OnPlaybackCapabilitiesChanged(PlaybackCapabilities playback_capabilities);

    /// Plays media.
    Play();
    /// Pauses playback and retains position in media
    Pause();
    /// Stops playback. There is no position or associated media in the stopped
    /// state.
    Stop();
    /// Seeks to a specific position in media. Implementations are free to
    /// to treat this as a no-op or enter an error state if the position
    /// is out of bounds. `position` is an offset from the beginning of the media.
    SeekToPosition(zx.duration position);
    /// Skips forward in media. Uses the default skip interval if `skip_amount`
    /// is 0.
    SkipForward(zx.duration skip_amount);
    /// Skips in reverse in media. Uses the default skip interval if `skip_amount`
    /// is 0.
    SkipReverse(zx.duration skip_amount);
    /// Changes media to the next item (e.g. next song in playlist).
    NextItem();
    /// Changes media to the previous item.
    PrevItem();
    /// Sets the playback rate of the media. This may imply a change of
    /// playback mode.
    SetPlaybackRate(float32 playback_rate);
    /// Sets repeat mode to any of the supported repeat modes.
    SetRepeatMode(RepeatMode repeat_mode);
    /// Sets shuffle mode.
    SetShuffleMode(bool shuffle_on);
    /// Binds to the session's gain control for control and notifications.
    BindGainControl(request<fuchsia.media.audio.GainControl> gain_control_request);

    // Connects a channel to a custom extension. This is for clients
    // privy to the underlying implementation.
    ConnectToExtension(string extension, handle<channel> channel);
};