chromium/chrome/common/extensions/api/desktop_capture.json

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

[
  {
    "namespace": "desktopCapture",
    "description": "The Desktop Capture API captures the content of the screen, individual windows, or individual tabs.",
    "types": [
      {
        "id": "DesktopCaptureSourceType",
        "type": "string",
        "enum": ["screen", "window", "tab", "audio"],
        "description": "Enum used to define set of desktop media sources used in chooseDesktopMedia()."
      },
      {
        "id": "SystemAudioPreferenceEnum",
        "type": "string",
        "enum": ["include", "exclude"],
        "description": "Mirrors <a href=\"https://w3c.github.io/mediacapture-screen-share/#dom-systemaudiopreferenceenum\">SystemAudioPreferenceEnum</a>."
      },
      {
        "id": "SelfCapturePreferenceEnum",
        "type": "string",
        "enum": ["include", "exclude"],
        "description": "Mirrors <a href=\"https://w3c.github.io/mediacapture-screen-share/#dom-selfcapturepreferenceenum\">SelfCapturePreferenceEnum</a>."
      }
    ],
    "functions": [
      {
        "name": "chooseDesktopMedia",
        "type": "function",
        "description": "Shows desktop media picker UI with the specified set of sources.",
        "parameters": [
          {
            "type": "array",
            "items": { "$ref": "DesktopCaptureSourceType" },
            "name": "sources",
            "description": "Set of sources that should be shown to the user. The sources order in the set decides the tab order in the picker."
          },
          {
            "$ref": "tabs.Tab",
            "name": "targetTab",
            "optional": true,
            "description": "Optional tab for which the stream is created. If not specified then the resulting stream can be used only by the calling extension. The stream can only be used by frames in the given tab whose security origin matches <code>tab.url</code>. The tab's origin must be a secure origin, e.g. HTTPS."
          },
          {
            "type": "object",
            "name": "options",
            "optional": true,
            "nodoc": true,
            "properties": {
              "systemAudio": {
                "$ref": "SystemAudioPreferenceEnum",
                "optional": true,
                "description": "Mirrors <a href=\"https://w3c.github.io/mediacapture-screen-share/#dom-displaymediastreamconstraints-systemaudio\">systemAudio</a>."
              },
              "selfBrowserSurface": {
                "$ref": "SelfCapturePreferenceEnum",
                "optional": true,
                "description": "Mirrors <a href=\"https://w3c.github.io/mediacapture-screen-share/#dom-displaymediastreamconstraints-selfbrowsersurface\">selfBrowserSurface</a>."
              },
              "suppressLocalAudioPlaybackIntended": {
                "type": "boolean",
                "optional": true,
                "description": "Indicates that the caller intends to perform local audio suppression, and that the media picker shown to the user should therefore reflect that with the appropriate warnings, as it does when getDisplayMedia() is invoked."
              }
            },
            "description": "Mirrors members of <a href=\"https://w3c.github.io/mediacapture-screen-share/#dom-displaymediastreamconstraints\">DisplayMediaStreamConstraints</a> which need to be applied before the user makes their selection, and must therefore be provided to chooseDesktopMedia() rather than be deferred to getUserMedia()."
          }
        ],
        "returns_async": {
          "name": "callback",
          "parameters": [
            {
              "name": "streamId",
              "type": "string",
              "description": "An opaque string that can be passed to <code>getUserMedia()</code> API to generate media stream that corresponds to the source selected by the user. If user didn't select any source (i.e. canceled the prompt) then the callback is called with an empty <code>streamId</code>. The created <code>streamId</code> can be used only once and expires after a few seconds when it is not used."
            },
            {
              "name": "options",
              "type": "object",
              "description": "Contains properties that describe the stream.",
              "properties": {
                 "canRequestAudioTrack": {
                   "type": "boolean",
                   "description": "True if \"audio\" is included in parameter sources, and the end user does not uncheck the \"Share audio\" checkbox. Otherwise false, and in this case, one should not ask for audio stream through getUserMedia call."
                 }
              }
            }
          ],
          "does_not_support_promises": "Synchronous return and callback crbug.com/1143032, Multi-parameter callback crbug.com/1313625"
        },
        "returns": {
          "type": "integer",
          "description": "An id that can be passed to cancelChooseDesktopMedia() in case the prompt need to be canceled."
        }
      },
      {
        "name": "cancelChooseDesktopMedia",
        "type": "function",
        "description": "Hides desktop media picker dialog shown by chooseDesktopMedia().",
        "parameters": [
          {
            "name": "desktopMediaRequestId",
            "type": "integer",
            "description": "Id returned by chooseDesktopMedia()"
          }
        ]
      }
    ]
  }
]