media/mojo/mojom/audio_output_stream.mojom

   1 // Copyright 2016 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 module media.mojom;
   6
   7 import "media/mojo/mojom/audio_data_pipe.mojom";
   8 import "media/mojo/mojom/audio_parameters.mojom";
   9 import "media/mojo/mojom/media_types.mojom";
  10
  11 // An interface for controlling an audio output stream.
  12 // To close the stream, just close the message pipe.
  13 // The AudioOutputStream may expire due to other reasons than actual errors,
  14 // such as user-initiated actions to close the stream. In this case, the
  15 // connection is closed without calling OnError.
  16 interface AudioOutputStream {
  17   // Starts rendering audio.
  18   Play();
  19
  20   // Stops rendering audio and sends a signal on the AudioDataPipe indicating
  21   // this.
  22   Pause();
  23
  24   // Flushes buffered audio.  This should not be called when playing.
  25   Flush();
  26
  27   // Sets volume. Volume must be in the range [0, 1].
  28   SetVolume(double volume);
  29 };
  30
  31 // An AudioOutputStreamObserver gets notifications about events related to an
  32 // AudioOutputStream. DidStartPlaying() is invoked when the stream starts
  33 // playing and it is eventually followed by a DidStopPlaying() call. A stream
  34 // may start playing again after being stopped.
  35 //
  36 // Note: It is possible that DidStopPlaying() is not called in shutdown
  37 // situations.
  38 interface AudioOutputStreamObserver {
  39   // These values are persisted to logs. Entries should not be renumbered and
  40   // numeric values should never be reused.
  41   enum DisconnectReason {
  42     // The Disconnect reason wasn't given explicitly. This probably means that
  43     // the audio service crashed.
  44     kDefault = 0,
  45     // This code is used as disconnect reason when stream ended or failed to
  46     // start due to an unrecoverable platform error, e.g. the hardware device is
  47     // busy or disconnected.
  48     kPlatformError = 1,
  49     kTerminatedByClient = 2,
  50     kStreamCreationFailed = 3,
  51     kDocumentDestroyed = 4,
  52   };
  53
  54   // This notification indicates that the stream started playing. The stream
  55   // should be considered non-audible until a DidChangeAudibleState() call says
  56   // otherwise.
  57   DidStartPlaying();
  58
  59   // This notification indicates that the stream stopped playing. The stream
  60   // should be considered no longer audible at this time; no further
  61   // audible-state change notifications will be issued.
  62   DidStopPlaying();
  63
  64   // This notification carries the latest value of the audible state of the
  65   // stream. Multiple instances of this notification may occur after
  66   // DidStartPlaying() and before DidStopPlaying().
  67   DidChangeAudibleState(bool is_audible);
  68 };
  69
  70 interface AudioOutputStreamProvider {
  71   // Creates a new AudioOutputStream using |params|. |client| is notified when
  72   // the stream is ready. The stream lifetime is bound by the lifetime of
  73   // |client|. |processing_id|, if provided, identifies the group of input and
  74   // output streams that are related during audio processing.
  75   // This method fails if it is called more than once.
  76   Acquire(AudioParameters params,
  77           pending_remote<AudioOutputStreamProviderClient> client);
  78 };
  79
  80 interface AudioOutputStreamProviderClient {
  81   // |stream| is used to pass commands to the stream, and |data_pipe| is used
  82   // to transfer the audio data.
  83   // TODO(https://crbug.com/787806): Currently, this will be called at most
  84   // once. In the future, it may be called several times.
  85   Created(pending_remote<AudioOutputStream> stream,
  86           ReadWriteAudioDataPipe data_pipe);
  87 };