1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
  100
  101
  102
  103
  104
  105
  106
  107
  108
  109
  110
  111
  112
  113
  114
  115
  116
  117
  118


media / mojo / mojom / audio_stream_factory.mojom [blame]

// Copyright 2018 The Chromium Authors
// 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/mojom/audio_data_pipe.mojom";
import "media/mojo/mojom/audio_input_stream.mojom";
import "media/mojo/mojom/audio_logging.mojom";
import "media/mojo/mojom/audio_output_stream.mojom";
import "media/mojo/mojom/audio_parameters.mojom";
import "media/mojo/mojom/audio_processing.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "sandbox/policy/mojom/context.mojom";

// Mutes a group of AudioOutputStreams while at least one binding to an instance
// exists. Once the last binding is dropped, all streams in the group are
// un-muted.
interface LocalMuter {};

// This interface is exposed by the audio service to allow trusted clients
// (like the browser process) to create streams. Note that while the factory
// interface itself is only for trusted clients, the created streams and data
// pipes may be forwarded to untrusted clients.
//
// The client must keep the connection to the factory while streams are
// running.
// Note: requires kPrivilegedUtility (rather than kBrowser) as the speech
// recognition service & libassistant call these directly.
[RequireContext=sandbox.mojom.Context.kPrivilegedUtility]
interface AudioStreamFactory {
  // Creates an AudioInputStream and returns the AudioDataPipe it writes data to
  // and a bool indicating whether the stream is initially muted. |data_pipe| is
  // null, |initially_muted| is false and |stream_id| is empty in case stream
  // creation failed.
  // |device_id| is either the |unique_id| field from an AudioDeviceDescription
  // obtained from the audio.mojom.SystemInfo interface, or "default".
  // |shared_memory_count| indicates how many buffer segments can the input
  // stream client read at once, to avoid data overwriting. |enable_agc| is used
  // for enabling automatic gain control. When |processing_config| is passed,
  // audio processing is requested (described by |processing_config|), and the
  // audio service will apply it, on supported platforms (Win, Mac so far).
  //
  // TODO(crbug.com/380824693) : If the experiment to optimize audio input IPC
  // using shared memory verification fails, we should revert this API to return
  // ReadOnlyAudioDataPipe.
  CreateInputStream(
    pending_receiver<media.mojom.AudioInputStream> stream,
    pending_remote<media.mojom.AudioInputStreamClient> client,
    pending_remote<media.mojom.AudioInputStreamObserver>? observer,
    pending_remote<media.mojom.AudioLog>? log,
    string device_id, media.mojom.AudioParameters params,
    uint32 shared_memory_count, bool enable_agc,
    media.mojom.AudioProcessingConfig? processing_config)
      => (media.mojom.ReadWriteAudioDataPipe? data_pipe, bool initially_muted,
          mojo_base.mojom.UnguessableToken? stream_id);

  // Associates an output device with an input stream, so that the input knows
  // which output device to cancel echo from. |input_stream_id| is the id
  // returned when the stream was created. |output_device_id| is a raw device
  // id. In case either of the parameters are invalid, the operation will
  // silently fail.
  AssociateInputAndOutputForAec(
      mojo_base.mojom.UnguessableToken input_stream_id,
      string output_device_id);

  // Creates an AudioOutputStream and returns the AudioDataPipe it reads data
  // from. |data_pipe| is null in case stream creation failed. |device_id| is
  // either the |unique_id| field from an AudioDeviceDescription obtained from
  // the audio.mojom.SystemInfo interface, or "default". The stream |group_id|
  // is used for muting streams or capturing them for loopback.
  CreateOutputStream(
    pending_receiver<media.mojom.AudioOutputStream> stream,
    pending_associated_remote<media.mojom.AudioOutputStreamObserver>? observer,
    pending_remote<media.mojom.AudioLog>? log,
    string device_id, media.mojom.AudioParameters params,
    mojo_base.mojom.UnguessableToken group_id)
    => (media.mojom.ReadWriteAudioDataPipe? data_pipe);

  // Same as CreateOutputStream(), but the output device of the resulting
  // AudioOutputStream can be switched via DeviceSwitchInterface.
  CreateSwitchableOutputStream(
    pending_receiver<media.mojom.AudioOutputStream> stream,
    pending_receiver<media.mojom.DeviceSwitchInterface> device_switch_receiver,
    pending_associated_remote<media.mojom.AudioOutputStreamObserver>? observer,
    pending_remote<media.mojom.AudioLog>? log,
    string device_id, media.mojom.AudioParameters params,
    mojo_base.mojom.UnguessableToken group_id)
    => (media.mojom.ReadWriteAudioDataPipe? data_pipe);

  // Binds the request to the LocalMuter associated with the given |group_id|.
  // While one or more bindings to a group's LocalMuter exists, all local audio
  // playout for the streams in that group is muted.
  //
  // It is the responsibility of the client to bind to a muter before creating
  // any output streams that should be started muted. Likewise, if existing
  // output streams must remain muted until they are shut down, the binding to
  // the muter must not be closed until after all other streams' binding. (This
  // is the reason for the associated request argument.)
  BindMuter(pending_associated_receiver<LocalMuter> receiver,
            mojo_base.mojom.UnguessableToken group_id);

  // Creates an AudioInputStream that provides the result of looping-back and
  // mixing-together all current and future AudioOutputStreams tagged with the
  // given |group_id|. The loopback re-mixes audio, if necessary, so that the
  // resulting data stream format matches the specified |params|. All other args
  // and the result are as described in CreateInputStream() above, except for
  // |stream_id|. Loopback streams have no ID, since they cannot be used in
  // echo cancellation.
  CreateLoopbackStream(
      pending_receiver<media.mojom.AudioInputStream> receiver,
      pending_remote<media.mojom.AudioInputStreamClient> client,
      pending_remote<media.mojom.AudioInputStreamObserver> observer,
      media.mojom.AudioParameters params,
      uint32 shared_memory_count,
      mojo_base.mojom.UnguessableToken group_id)
    => (media.mojom.ReadWriteAudioDataPipe? data_pipe);
};