// 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.playback;

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

/// Plays media.
@discoverable
protocol Player {
    compose SourceManager;

    /// Sets a file channel to read from.
    SetFileSource(resource struct {
        file_channel zx.handle:CHANNEL;
    });

    /// Sets a file channel to read from.
    SetFileSourceWithOptions(resource struct {
        file_channel zx.handle:CHANNEL;
        options PlayerOptions;
    });

    /// Starts playback.
    Play();

    /// Pauses playback.
    Pause();

    /// Provides current status immediately after binding and whenever status
    /// changes thereafter.
    -> OnStatusChanged(struct {
        player_status PlayerStatus;
    });

    /// Seeks to the specified position, specified in nanoseconds.
    Seek(struct {
        position int64;
    });

    /// Creates a video view.
    CreateView(resource struct {
        view_token fuchsia.ui.views.ViewToken;
    });

    /// Binds to the gain control for this player.
    BindGainControl(resource struct {
        gain_control_request server_end:fuchsia.media.audio.GainControl;
    });

    /// Adds a new binding to this player.
    AddBinding(resource struct {
        player_request server_end:Player;
    });

    /// Sets the rate to be used when the player is playing. `rate` must be positive. The
    /// `timeline_function` field of `PlayerStatus` indicates the actual rate when the player
    /// is playing.
    SetPlaybackRate(struct {
        playback_rate float32;
    });
};

/// Options used in `SetFileSourceWithOptions`.
type PlayerOptions = table {
    /// When set to true, suppresses audio rendering. Default value false.
    1: silent bool;
};

/// Player status information.
type PlayerStatus = struct {
    /// Duration of the content.
    duration zx.duration;

    /// Whether the player can pause.
    can_pause bool;

    /// Whether the player can seek.
    can_seek bool;

    /// Whether the source has an audio stream.
    has_audio bool;

    /// Whether the source has a video stream.
    has_video bool;

    /// Indicates whether the player is ready to play. After
    /// `SetFileSource` or `SourceManager.SetSource` is called, this value is
    /// false until the player is fully prepared to play the content from the
    /// source.
    ready bool;

    // Describes the media.
    metadata box<fuchsia.media.Metadata>;

    /// Indicates a problem preventing intended operation.
    problem box<Problem>;

    /// Indicates whether an audio stream is currently connected for rendering.
    /// This value will be false if `has_audio` is false or if the audio stream
    /// type isn't supported.
    audio_connected bool;

    /// Indicates whether a video stream is currently connected for rendering.
    /// This value will be false if `has_video` is false or if the video stream
    /// type isn't supported.
    video_connected bool;

    /// Size of the video currently being produced. This value will be null if
    /// the video size is currently unknown.
    video_size box<fuchsia.math.Size>;

    /// Relative dimensions of a video pixel. This value will be null if the
    /// pixel aspect ratio is currently unknown.
    pixel_aspect_ratio box<fuchsia.math.Size>;

    /// Function translating local time to presentation time. This value will be
    /// null if the timeline function is currently undefined.
    timeline_function box<fuchsia.media.TimelineFunction>;

    /// Indicates whether presentation for all streams has reached end-of-stream.
    end_of_stream bool;
};