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

module blink.mojom;

import "media/capture/mojom/video_capture_types.mojom";
import "media/mojo/mojom/audio_parameters.mojom";
import "media/mojo/mojom/media_types.mojom";
import "mojo/public/mojom/base/time.mojom";
import "third_party/blink/public/mojom/media/capture_handle_config.mojom";

enum MediaDeviceType {
  kMediaAudioInput,
  kMediaVideoInput,
  kMediaAudioOutput,
  kNumMediaDeviceTypes,
};

// The values for this enum match the ones defined in
// https://w3c.github.io/mediacapture-main/#def-constraint-facingMode
// with the addition of kNone, which would map to the empty string in
// JavaScript.
enum FacingMode {
  kNone,
  kUser,
  kEnvironment,
  kLeft,
  kRight,
};

struct MediaDeviceInfo {
  string device_id;
  string label;
  string group_id;
  media.mojom.VideoCaptureControlSupport control_support;
  FacingMode facing_mode;
  media.mojom.CameraAvailability? availability;
};

struct VideoInputDeviceCapabilities {
  string device_id;
  string group_id;
  media.mojom.VideoCaptureControlSupport control_support;
  array<media.mojom.VideoCaptureFormat> formats;
  FacingMode facing_mode;
  media.mojom.CameraAvailability? availability;
};

enum AudioOutputStatus {
  kSuccess,
  kNoPermission,
  kNoDevices,
  kUnknown,
  kDeviceNotFound,
  kErrorOtherRequestInProgress,
  kNotSupported,
  kNoUserActivation,
};

struct SelectAudioOutputResult {
  AudioOutputStatus status;
  MediaDeviceInfo device_info;
};

struct AudioInputDeviceCapabilities {
  string device_id;
  string group_id;
  media.mojom.AudioParameters parameters;
  // Values copied from the device parameters (Blink-use only).
  // TODO(crbug.com/787252): remove the copies below in favour of |parameters|
  // when it becomes visible in Blink.
  bool is_valid;
  int32 channels;
  int32 sample_rate;
  mojo_base.mojom.TimeDelta latency;
};

// This object lives in the browser and is responsible for processing device
// enumeration requests and managing subscriptions for device-change
// notifications.
interface MediaDevicesDispatcherHost {
  // Enumerates media devices and capabilities. The reply contains the
  // |enumeration|, |video_input_device_capabilities|, and
  // |audio_input_device_capabilities| arrays. The |enumeration| array always
  // has kNumMediaDeviceTypes elements indexed by device type as defined in
  // MediaDeviceType. Each element of |enumeration| is an array with as many
  // elements as devices of the corresponding type exist in the system, or zero
  // if the device types was not requested. Similarly, the number of elements in
  // |audio_input_device_capabilities| and |video_input_device_capabilities| is
  // equal to respectively the number of video and audio input devices in the
  // system, or zero if not requested.
  EnumerateDevices(bool request_audio_input,
                   bool request_video_input,
                   bool request_audio_output,
                   bool request_video_input_capabilities,
                   bool request_audio_input_capabilities)
      => (array<array<MediaDeviceInfo>> enumeration,
          array<VideoInputDeviceCapabilities> video_input_device_capabilities,
          array<AudioInputDeviceCapabilities> audio_input_device_capabilities);

  // Returns a list of video devices and their capabilities.
  // If there is a user-preferred device, it is the first in the result.
  // The result of this function is intended for the implementation details
  // of algorithms such as settings selection for getUserMedia.
  // Do not expose the data contained in the result of this function to
  // JavaScript.
  GetVideoInputCapabilities()
      => (array<VideoInputDeviceCapabilities> video_input_device_capabilities);

  // Returns a list of all video formats supported by a given device, regardless
  // of whether the device is being used or not. If the given |device_id| is
  // invalid, the result is empty.
  GetAllVideoInputDeviceFormats(string device_id)
      => (array<media.mojom.VideoCaptureFormat> formats);

  // Returns a list of video formats currently available for a given device.
  // When the device is in use, it is expected that the result will contain only
  // one entry. When the device is not in use, the result should be the same as
  // for GetAllVideoInputDeviceFormats. If the given |device_id| is not valid,
  // the result is empty.
  GetAvailableVideoInputDeviceFormats(string device_id)
      => (array<media.mojom.VideoCaptureFormat> formats);

  // Returns a list of audio input devices and their capabilities.
  // If there is a user-preferred device, it is the first in the result.
  // Otherwise, the system-default device is the first in the result.
  // The result of this function is intended for the implementation details
  // of algorithms such as settings selection for getUserMedia.
  // Do not expose the data contained in the result of this function to
  // JavaScript.
  GetAudioInputCapabilities()
      => (array<AudioInputDeviceCapabilities> audio_input_device_capabilities);

  // Subscribes |listener| to device-change notifications for the calling
  // frame/security origin. |listener| will receive notifications only for
  // device types decided by the boolean fields. Closing the pipe will cancel
  // the subscription.
  AddMediaDevicesListener(bool subscribe_audio_input,
                          bool subscribe_video_input,
                          bool subscribe_audio_output,
                          pending_remote<MediaDevicesListener> listener);

  // Allows an application APP to opt-in to exposing certain information to
  // applications which end up capturing APP.
  SetCaptureHandleConfig(CaptureHandleConfig config);

  // When starting to capture a focusable display-surface (tab/window),
  // identified by the MediaStream ID of |label|, the browser has a decision
  // to make - whether to focus the surface, or whether to keep the focus on
  // the Chrome tab that initiated the capture.
  // There exists a short window of opportunity where the application
  // is allowed to influence that decision. This message closes this window
  // of opportunity from the render side.
  // (Note that a timer exists on the browser-side, too. This message serves
  // to close the window early.)
  CloseFocusWindowOfOpportunity(string label);

  // Mints a new ID backing a SubCaptureTarget.
  // * CropTargetIds back a CropTarget, which is the input type
  //   for BrowserCaptureMediaStreamTrack.cropTo().
  // * RestrictionTargetIds back a RestrictionTarget, which is the input type
  //   for BrowserCaptureMediaStreamTrack.restrictTo().
  ProduceSubCaptureTargetId(media.mojom.SubCaptureTargetType type)
      => (string id);

  // Sets preferred audio output sink id for the top frame and its subframes.
  SetPreferredSinkId(string sink_id) => (media.mojom.OutputDeviceStatus status);

  // SelectAudioOutput prompts the user to select an audio
  // output device, returning information about the chosen device.
  // The |device_id| argument can be used to pre-select a specific device, if
  // desired.
  SelectAudioOutput(string device_id) => (SelectAudioOutputResult result);
};

// This object lives in the renderer process and is used by the browser process
// to pass device-change notifications to the renderer.
interface MediaDevicesListener {
  // Called to notify a change in the set of devices of type |type|.
  // |device_infos| contains the new list of devices of type |type|, with
  // device and group IDs obfuscated according to the subscription's security
  // origin.
  OnDevicesChanged(
      MediaDeviceType type, array<MediaDeviceInfo> device_infos);
};