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

module media.mojom;

import "media/mojo/interfaces/audio_data_pipe.mojom";
import "media/mojo/interfaces/audio_parameters.mojom";
import "media/mojo/interfaces/media_types.mojom";

// An interface for controlling an audio output stream.
// To close the stream, just close the message pipe.
// The AudioOutputStream may expire due to other reasons than actual errors,
// such as user-initiated actions to close the stream. In this case, the
// connection is closed without calling OnError.
interface AudioOutputStream {
  // Starts rendering audio.
  Play();

  // Stops rendering audio and sends a signal on the AudioDataPipe indicating
  // this.
  Pause();

  // Sets volume. Volume must be in the range [0, 1].
  SetVolume(double volume);
};

// An AudioOutputStreamObserver gets notifications about events related to an
// AudioOutputStream. DidStartPlaying() is invoked when the stream starts
// playing and it is eventually followed by a DidStopPlaying() call. A stream
// may start playing again after being stopped.
//
// Note: It is possible that DidStopPlaying() is not called in shutdown
// situations.
interface AudioOutputStreamObserver {
  // These values are persisted to logs. Entries should not be renumbered and
  // numeric values should never be reused.
  enum DisconnectReason {
    // The Disconnect reason wasn't given explicitly. This probably means that
    // the audio service crashed.
    kDefault = 0,
    // This code is used as disconnect reason when stream ended or failed to
    // start due to an unrecoverable platform error, e.g. the hardware device is
    // busy or disconnected.
    kPlatformError = 1,
    kTerminatedByClient = 2,
    kStreamCreationFailed = 3,
    kDocumentDestroyed = 4,
  };

  // This notification indicates that the stream started playing. The stream
  // should be considered non-audible until a DidChangeAudibleState() call says
  // otherwise.
  DidStartPlaying();

  // This notification indicates that the stream stopped playing. The stream
  // should be considered no longer audible at this time; no further
  // audible-state change notifications will be issued.
  DidStopPlaying();

  // This notification carries the latest value of the audible state of the
  // stream. Multiple instances of this notification may occur after
  // DidStartPlaying() and before DidStopPlaying().
  DidChangeAudibleState(bool is_audible);
};

interface AudioOutputStreamProvider {
  // Creates a new AudioOutputStream using |params|. |client| is notified when
  // the stream is ready. The stream lifetime is bound by the lifetime of
  // |client|. On error, the |client| will have a disconnect reason among the
  // specified ones in AudioOutputStreamProviderClient.
  // Can only be called once.
  Acquire(AudioParameters params, AudioOutputStreamProviderClient client);
};

interface AudioOutputStreamProviderClient {
  // |stream| is used to pass commands to the stream, and |data_pipe| is used
  // to transfer the audio data.
  // TODO(https://crbug.com/787806): Currently, this will be called at most
  // once. In the future, it may be called several times.
  Created(AudioOutputStream stream, AudioDataPipe data_pipe);
};