メインコンテンツへ飛ぶ

desktopCapturer

navigator.mediaDevices.getUserMedia APIを使用して、デスクトップからの音声と映像のキャプチャに利用できるメディアソース関連の情報にアクセスします。

プロセス: メイン

以下の例では、タイトルが Electron であるデスクトップウインドウからビデオをキャプチャする方法を示します。

// main.js
const { app, BrowserWindow, desktopCapturer, session } = require('electron')

app.whenReady().then(() => {
  const mainWindow = new BrowserWindow()

  session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
    desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
      // 最初に見つけた画面へのアクセスを認可します。
      callback({ video: sources[0], audio: 'loopback' })
    })
    // true ならば、利用可能な場合にシステムのピッカーを使用します。
    // 注: 現在これは実験的なものです。 システムピッカーが
    // 利用可能な場合はそれが使用され、メディアのリクエストハンドラ
    // は呼び出されません。
  }, { useSystemPicker: true })

  mainWindow.loadFile('index.html')
})
// renderer.js
const startButton = document.getElementById('startButton')
const stopButton = document.getElementById('stopButton')
const video = document.querySelector('video')

startButton.addEventListener('click', () => {
  navigator.mediaDevices.getDisplayMedia({
    audio: true,
    video: {
      width: 320,
      height: 240,
      frameRate: 30
    }
  }).then(stream => {
    video.srcObject = stream
    video.onloadedmetadata = (e) => video.play()
  }).catch(e => console.log(e))
})

stopButton.addEventListener('click', () => {
  video.pause()
})
<!-- index.html -->
<html>
<meta http-equiv="content-security-policy" content="script-src 'self' 'unsafe-inline'" />
  <body>
    <button id="startButton" class="button">Start</button>
    <button id="stopButton" class="button">Stop</button>
    <video width="320" height="240" autoplay></video>
    <script src="renderer.js"></script>
  </body>
</html>

詳しくは navigator.mediaDevices.getDisplayMedia を参照してください。

note

navigator.mediaDevices.getDisplayMedia はソースの選択に deviceId を使用できません。このことについては 仕様 を参照してください。

メソッド​

desktopCapturer モジュールには以下のメソッドがあります。

desktopCapturer.getSources(options)​

History
  • options Object
    • types string[] - キャプチャされるデスクトップソースの種別を列挙した文字列の配列。指定できる種別は、screen と window です。
    • thumbnailSize Size (任意) - メディアソースのサムネイルをスケーリングするサイズ。 省略値は 150 x 150 です。 サムネイルが不要な場合は、幅または高さを 0 に設定してください。 これにより、各ウィンドウおよび画面のコンテンツをキャプチャするために必要な処理時間が節約されます。
    • fetchWindowIcons boolean (任意) - ウインドウアイコンの取得を有効にするには true に設定します。 デフォルト値は false です。 false の場合、ソースの appIcon プロパティは null を返します。 ソースが screen 型の場合も同様です。

戻り値 Promise<DesktopCapturerSource[]> - DesktopCapturerSource オブジェクトの配列で解決します。各 DesktopCapturerSource は、キャプチャできる画面または個々のウィンドウを表します。

note
  • macOS 14.2 以降では、音声のキャプチャに NSAudioCaptureUsageDescription の Info.plist キーが必要になります – 詳細。 * macOS 10.15 以降では、画面のコンテンツをキャプチャするにはユーザーの同意が必須となります。これは、systemPreferences.getMediaAccessStatus で検出できます。

Caveats​

Linux​

Linux では、Pipewire を使用する場合 desktopCapturer.getSources(options) は単一のソースのみを返します。

PipeWire は、スクリーンとウインドウの両方に対して一つのキャプチャをサポートしています。 ウインドウとスクリーンのタイプを要求すると、選択したソースがウインドウキャプチャとして返されます。

macOS v14.2 以降​

desktopCapturer が音声をキャプチャするためには、NSAudioCaptureUsageDescription の Info.plist キーが必要になります。 一方、ターミナルや IDE などの別のプログラムから Electron を実行している場合は、 その親プログラムに Info.plist キーが含まれている必要があります。

これは、Chromium が Apple の新しいCoreAudio Tap API を容易に利用できるようにするためです。

警告

NSAudioCaptureUsageDescription 権限が提供されていないことによって desktopCapturer が起動に失敗すると、 空のオーディオストリームを生成し、警告やエラーは表示されません。

Electron v39.0.0-beta.4 時点では、Chromium はデスクトップ音声のキャプチャで Apple の新しい CoreAudio Tap API をデフォルト としています。 CoreAudio Tap API ストリームの作成に失敗した場合でも、画面収録とシステムオーディオ録音 権限システムへのフォールバックは提供されていません。

macOS v14.2 以降で desktopCapturer のために 画面収録とシステムオーディオ録音 権限を使い続けるには、下記の Chromium 機能フラグを適用して以前の権限システムを強制してください。

// main.js （require/import 文のすぐ下）
app.commandLine.appendSwitch('disable-features', 'MacCatapLoopbackAudioForScreenShare')

macOS v12.7.6 以前​

システムのオーディオにアクセスしようとするアプリには、 署名付きカーネル拡張が必要となるという根本的な制約があります。これにより、macOS v12.7.6 またはそれ以前では、音声キャプチャのために navigator.mediaDevices.getUserMedia は動作しません。 Chrome、ひいては Electron はこれを提供していません。 macOS 13 以降でのみ、Apple は、署名付きカーネル拡張機能を必要とせずにデスクトップオーディオをキャプチャする API を提供します。

この制限を回避するには、 BlackHole や Soundflower といった別の macOS アプリでシステムオーディオをキャプチャし、 仮想オーディオ入力デバイス経由で出力するように設定します。 この仮想デバイスは、 navigator.mediaDevices.getUserMedia を使用して照会できます。