// 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_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 to the |socket_descriptor|
  // indicating this.
  Pause();

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

interface AudioOutputStreamClient {
  // Called if the stream has an error such as failing to open/losing access to
  // a device. This renders the stream unusable.
  OnError();
};

interface AudioOutputStreamProvider {
  // Creates a new AudioOutputStream using |params|. |shared_buffer| and
  // |socket_descriptor| are used to write data to the stream as defined
  // in AudioDeviceThread. This means:
  // * |shared_buffer| will be a writable handle to memory of the size needed
  //   by AudioDeviceThread for the specified params.
  // * |socket_descriptor| is a descriptor from which a
  //   base::CancelableSyncSocket can be constructed.
  // Can only be called once.
  Acquire(AudioOutputStream& output_stream, AudioOutputStreamClient client, AudioParameters params)
  => (handle<shared_buffer> shared_buffer, handle socket_descriptor);
};