electron-native-screenshare 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CilginSinek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# electron-native-screenshare
+
+Cross-platform native audio capture for Electron screen sharing with **process-level audio isolation**.
+
+Uses low-level OS APIs instead of web APIs for **lower latency, lower CPU usage, and true per-process audio control**.
+
+| Platform | API | Min Version | Include Mode | Exclude Mode |
+|----------|-----|-------------|:------------:|:------------:|
+| Windows  | WASAPI Process Loopback | Windows 10 2004 | ✅ Per-process | ✅ Per-process |
+| macOS    | ScreenCaptureKit | macOS 13 Ventura | ✅ Per-app | ✅ Per-app |
+| Linux    | PipeWire | 0.3.26+ | ✅ Per-process | ⚠️ System audio* |
+
+> \* Linux exclude mode captures all system audio from the default output. Per-process exclusion is an OS-level limitation of PipeWire.
+
+## Installation
+
+```bash
+npm install electron-native-screenshare
+```
+
+### Platform Prerequisites
+
+**Windows**: Visual Studio Build Tools with "Desktop development with C++" workload.
+
+**macOS**: Xcode Command Line Tools. macOS 13 (Ventura) or later required.
+
+**Linux**:
+```bash
+sudo apt install libpipewire-0.3-dev libx11-dev
+```
+
+> ⚠️ If PipeWire is not installed on Linux, the module will load but audio functions will throw a descriptive error at runtime. It will **not** crash your application.
+
+## Quick Start
+
+```javascript
+const {
+  startCapture,
+  stopCapture,
+  getPidFromWindowHandle,
+  isAvailable
+} = require('electron-native-screenshare');
+
+// Check if native module loaded successfully
+if (!isAvailable()) {
+  console.warn('Native audio capture is not available on this platform');
+}
+```
+
+## API
+
+### `startCapture(processId?, isIncludeMode?, onData?)`
+
+Starts audio capture with process-level isolation.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `processId` | `number` | `process.pid` | Target process ID |
+| `isIncludeMode` | `boolean` | `false` | `true` = capture only target, `false` = exclude target |
+| `onData` | `function` | `() => {}` | Callback `(data: Buffer, meta: AudioMetadata) => void` |
+
+**Returns:** `boolean` — `true` if started successfully.
+
+**Throws:** `Error` if native module unavailable or initialization fails.
+
+#### AudioMetadata
+
+```typescript
+interface AudioMetadata {
+  sampleRate: number;    // e.g., 48000
+  channels: number;      // e.g., 2 (stereo)
+  bitsPerSample: number; // e.g., 32
+  isFloat: boolean;      // true = IEEE float, false = integer PCM
+}
+```
+
+### `stopCapture()`
+
+Stops the active capture session. Safe to call even if nothing is capturing.
+
+**Returns:** `boolean`
+
+### `getPidFromWindowHandle(windowHandle)`
+
+Resolves a native window handle to its owning process ID.
+
+| Platform | Handle Type | Notes |
+|----------|-------------|-------|
+| Windows  | `HWND` | Auto-resolves UWP ApplicationFrameWindow → child process |
+| macOS    | `CGWindowID` | Uses CGWindowListCopyWindowInfo |
+| Linux    | X11 Window ID | Uses `_NET_WM_PID` atom |
+
+**Parameters:**
+| Name | Type | Description |
+|------|------|-------------|
+| `windowHandle` | `number` | Native window handle from Electron's `desktopCapturer` |
+
+**Returns:** `number` — Process ID, or `0` if not found.
+
+### `isAvailable()`
+
+Returns `true` if the native module loaded successfully.
+
+### `getPlatform()`
+
+Returns the current platform: `'win32'`, `'darwin'`, or `'linux'`.
+
+### `getLoadError()`
+
+Returns the load error message if the native module failed, or `null` on success.
+
+## Usage Examples
+
+### Screen Sharing (Exclude Mode)
+
+Capture all system audio **except** your Electron app:
+
+```javascript
+const { startCapture, stopCapture } = require('electron-native-screenshare');
+
+// Your app's audio will NOT go into the stream
+startCapture(process.pid, false, (audioData, meta) => {
+  // audioData: Buffer of raw PCM float32 samples
+  // meta: { sampleRate: 48000, channels: 2, bitsPerSample: 32, isFloat: true }
+
+  // Send to WebRTC, write to file, or process as needed
+  webrtcTrack.write(audioData);
+});
+
+// Later...
+stopCapture();
+```
+
+### Window Sharing (Include Mode)
+
+Capture **only** a specific window's audio:
+
+```javascript
+const {
+  startCapture,
+  stopCapture,
+  getPidFromWindowHandle
+} = require('electron-native-screenshare');
+
+// Get sources from Electron's desktopCapturer
+const sources = await desktopCapturer.getSources({ types: ['window'] });
+const target = sources.find(s => s.name === 'Spotify');
+
+// Extract window handle and resolve PID
+const hwnd = parseInt(target.id.split(':')[1]);
+const pid = getPidFromWindowHandle(hwnd);
+
+// Capture only Spotify's audio
+startCapture(pid, true, (audioData, meta) => {
+  // Only Spotify's audio is in the buffer
+  webrtcTrack.write(audioData);
+});
+```
+
+### Graceful Degradation
+
+```javascript
+const capture = require('electron-native-screenshare');
+
+if (!capture.isAvailable()) {
+  const error = capture.getLoadError();
+  console.warn(`Audio capture unavailable: ${error}`);
+  // Fall back to Electron's built-in audio capture
+  // or disable audio in your sharing feature
+} else {
+  capture.startCapture(process.pid, false, onAudioData);
+}
+```
+
+## How It Works
+
+### Windows — WASAPI Process Loopback
+Uses the Windows Audio Session API (WASAPI) with `AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK` (Windows 10 2004+). This provides true kernel-level process audio isolation with zero mixing overhead.
+
+### macOS — ScreenCaptureKit
+Uses Apple's `SCStream` with `SCContentFilter` (macOS 13+). Filters by `SCRunningApplication` to include/exclude specific apps. Audio is delivered via `SCStreamOutput` delegate as `CMSampleBuffer`.
+
+### Linux — PipeWire
+Uses PipeWire's `pw_stream` API for audio capture. Include mode connects directly to the target process's audio node via `PW_KEY_TARGET_OBJECT`. Exclude mode captures from the default sink monitor.
+
+## CI/CD
+
+| Workflow | Trigger | Description |
+|----------|---------|-------------|
+| `test.yml` | Push to `main`, PRs | Builds and tests on Windows, macOS, Linux × Node 18/20/22 |
+| `publish-npm.yml` | GitHub Release | Publishes to npm (requires passing tests) |
+| `publish-github.yml` | GitHub Release | Publishes to GitHub Packages as `@CilginSinek/electron-native-screenshare` |
+
+> Tests **must pass** before any publish. If the test pipeline fails, the package will not be published.
+
+## License
+
+[MIT](LICENSE)

package/binding.gyp

@@ -0,0 +1,67 @@
+{
+  "targets": [
+    {
+      "target_name": "topluyo_capture",
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "defines": [
+        "NAPI_DISABLE_CPP_EXCEPTIONS"
+      ],
+      "conditions": [
+        ["OS==\"win\"", {
+          "sources": [
+            "src/win/addon.cpp",
+            "src/win/wasapi_capture.cpp"
+          ],
+          "defines": [
+            "_WIN32_WINNT=0x0A00",
+            "NTDDI_VERSION=0x0A00000A"
+          ],
+          "libraries": [
+            "-lMmdevapi.lib",
+            "-lAvrt.lib"
+          ]
+        }],
+        ["OS==\"mac\"", {
+          "sources": [
+            "src/mac/addon.cpp",
+            "src/mac/coreaudio_capture.mm"
+          ],
+          "xcode_settings": {
+            "CLANG_ENABLE_OBJC_ARC": "YES",
+            "OTHER_CPLUSPLUSFLAGS": ["-std=c++17", "-ObjC++"],
+            "MACOSX_DEPLOYMENT_TARGET": "13.0"
+          },
+          "link_settings": {
+            "libraries": [
+              "-framework CoreAudio",
+              "-framework CoreMedia",
+              "-framework CoreGraphics",
+              "-framework ScreenCaptureKit",
+              "-framework Foundation"
+            ]
+          }
+        }],
+        ["OS==\"linux\"", {
+          "sources": [
+            "src/linux/addon.cpp",
+            "src/linux/pipewire_capture.cpp"
+          ],
+          "cflags_cc": [
+            "-std=c++17",
+            "<!@(pkg-config --cflags libpipewire-0.3 2>/dev/null || echo '')",
+            "<!@(pkg-config --cflags x11 2>/dev/null || echo '')"
+          ],
+          "libraries": [
+            "<!@(pkg-config --libs libpipewire-0.3 2>/dev/null || echo '-lpipewire-0.3')",
+            "<!@(pkg-config --libs x11 2>/dev/null || echo '-lX11')"
+          ]
+        }]
+      ]
+    }
+  ]
+}

package/lib/index.js

@@ -0,0 +1,198 @@
+/**
+ * electron-native-screenshare
+ *
+ * Cross-platform native audio capture for Electron screen sharing
+ * with process-level audio isolation.
+ *
+ * Unified API — platform detection is automatic. The consumer never
+ * needs to import OS-specific modules.
+ *
+ * Supported platforms:
+ *   - Windows 10 2004+ (WASAPI Process Loopback)
+ *   - macOS 13 Ventura+ (ScreenCaptureKit)
+ *   - Linux (PipeWire 0.3.26+)
+ *
+ * @module electron-native-screenshare
+ */
+
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+const platform = os.platform();
+const SUPPORTED_PLATFORMS = ['win32', 'darwin', 'linux'];
+
+/** @type {import('./types').NativeCapture | null} */
+let capture = null;
+
+/** @type {string | null} */
+let loadError = null;
+
+// --- Native module loading with graceful degradation ---
+
+if (!SUPPORTED_PLATFORMS.includes(platform)) {
+    loadError = `[electron-native-screenshare] Unsupported platform: "${platform}". ` +
+                `Supported: ${SUPPORTED_PLATFORMS.join(', ')}. ` +
+                `Audio capture functions will throw when called.`;
+    console.warn(loadError);
+} else {
+    try {
+        capture = require('../build/Release/topluyo_capture.node');
+    } catch (e) {
+        const platformHints = {
+            win32: 'Ensure Visual Studio Build Tools and Windows 10 SDK are installed.',
+            darwin: 'Ensure Xcode Command Line Tools are installed. Requires macOS 13+.',
+            linux: 'Ensure libpipewire-0.3-dev and libx11-dev are installed. ' +
+                   'Run: sudo apt install libpipewire-0.3-dev libx11-dev'
+        };
+
+        loadError = `[electron-native-screenshare] Failed to load native module on ${platform}.\n` +
+                    `  Error: ${e.message}\n` +
+                    `  Hint: ${platformHints[platform] || 'Check native build dependencies.'}`;
+        console.warn(loadError);
+    }
+}
+
+/**
+ * Throws a descriptive error if the native module isn't loaded.
+ * @private
+ */
+function ensureLoaded() {
+    if (!capture) {
+        throw new Error(
+            loadError ||
+            `[electron-native-screenshare] Native module is not available on ${platform}.`
+        );
+    }
+}
+
+/**
+ * Starts audio capture with process-level isolation.
+ *
+ * Behavior depends on `isIncludeMode`:
+ *   - `false` (default): Captures ALL system audio EXCEPT the specified process.
+ *     Use for screen sharing — your app's audio won't leak into the stream.
+ *   - `true`: Captures ONLY the specified process's audio.
+ *     Use for window sharing — only that window's audio goes to the stream.
+ *
+ * @param {number} [processId] - Target process ID. Defaults to `process.pid` (current process).
+ * @param {boolean} [isIncludeMode=false] - `true` to include only the target, `false` to exclude it.
+ * @param {function(Buffer, AudioMetadata): void} [onData] - Callback receiving raw PCM audio chunks.
+ *   - `data` {Buffer} — Raw PCM audio (float32, stereo, 48kHz by default)
+ *   - `meta` {AudioMetadata} — `{ sampleRate, channels, bitsPerSample, isFloat }`
+ * @returns {boolean} `true` if capture started successfully.
+ * @throws {Error} If the native module failed to load or initialization fails.
+ *
+ * @example
+ * const { startCapture, stopCapture } = require('electron-native-screenshare');
+ *
+ * // Screen share: exclude your app's audio
+ * startCapture(process.pid, false, (data, meta) => {
+ *   console.log(`Got ${data.length} bytes, ${meta.sampleRate}Hz ${meta.channels}ch`);
+ * });
+ *
+ * // Window share: include only a specific window's audio
+ * startCapture(targetPid, true, (data, meta) => { ... });
+ */
+function startCapture(processId, isIncludeMode, onData) {
+    ensureLoaded();
+
+    if (processId === undefined || processId === null) {
+        processId = process.pid;
+    }
+    if (typeof processId !== 'number' || !Number.isInteger(processId) || processId < 0) {
+        throw new Error('[electron-native-screenshare] processId must be a non-negative integer.');
+    }
+    if (typeof isIncludeMode !== 'boolean') {
+        isIncludeMode = false;
+    }
+    if (typeof onData !== 'function') {
+        onData = () => {};
+    }
+
+    return capture.startCapture(processId, isIncludeMode, (data, meta) => onData(data, meta));
+}
+
+/**
+ * Stops the active audio capture session.
+ *
+ * Safe to call even if no capture is running.
+ *
+ * @returns {boolean} `true` if stopped successfully.
+ * @throws {Error} If the native module failed to load.
+ */
+function stopCapture() {
+    ensureLoaded();
+    return capture.stopCapture();
+}
+
+/**
+ * Resolves a native window handle to its owning process ID.
+ *
+ * Platform-specific handle types:
+ *   - Windows: HWND (from Electron's `desktopCapturer` source ID)
+ *   - macOS: CGWindowID
+ *   - Linux: X11 Window ID
+ *
+ * On Windows, this also handles UWP ApplicationFrameWindow → actual child process resolution.
+ *
+ * @param {number} windowHandle - The native window handle (HWND / CGWindowID / X11 Window).
+ * @returns {number} Process ID owning the window, or `0` if not found.
+ * @throws {Error} If the native module failed to load or argument is invalid.
+ *
+ * @example
+ * const { getPidFromWindowHandle } = require('electron-native-screenshare');
+ *
+ * // From Electron desktopCapturer source:
+ * // source.id = "window:12345:0" → extract 12345
+ * const hwnd = parseInt(source.id.split(':')[1]);
+ * const pid = getPidFromWindowHandle(hwnd);
+ */
+function getPidFromWindowHandle(windowHandle) {
+    ensureLoaded();
+
+    if (typeof windowHandle !== 'number') {
+        throw new Error('[electron-native-screenshare] windowHandle must be a number.');
+    }
+
+    return capture.getPidFromHwnd(windowHandle);
+}
+
+/**
+ * Returns whether the native module loaded successfully on this platform.
+ *
+ * Use this to gracefully check availability before calling capture functions,
+ * instead of wrapping everything in try/catch.
+ *
+ * @returns {boolean} `true` if capture functions are available.
+ */
+function isAvailable() {
+    return capture !== null;
+}
+
+/**
+ * Returns the current platform name.
+ * @returns {string} 'win32', 'darwin', 'linux', or the raw os.platform() string.
+ */
+function getPlatform() {
+    return platform;
+}
+
+/**
+ * If the native module failed to load, returns the error message.
+ * Returns `null` if the module loaded successfully.
+ * @returns {string | null}
+ */
+function getLoadError() {
+    return loadError;
+}
+
+module.exports = {
+    startCapture,
+    stopCapture,
+    getPidFromWindowHandle,
+    isAvailable,
+    getPlatform,
+    getLoadError,
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "electron-native-screenshare",
+  "version": "1.0.0",
+  "description": "Cross-platform native audio capture for Electron screen sharing with process-level isolation. WASAPI (Windows), ScreenCaptureKit (macOS), PipeWire (Linux).",
+  "main": "lib/index.js",
+  "files": [
+    "lib/",
+    "src/",
+    "binding.gyp",
+    "README.md",
+    "LICENSE"
+  ],
+  "os": [
+    "win32",
+    "linux",
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "gypfile": true,
+  "scripts": {
+    "build": "node-gyp rebuild",
+    "clean": "node-gyp clean",
+    "test": "jest --verbose --forceExit",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "electron",
+    "screen-share",
+    "audio-capture",
+    "wasapi",
+    "coreaudio",
+    "screencapturekit",
+    "pipewire",
+    "native",
+    "process-isolation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CilginSinek/electron-native-screenshare.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CilginSinek/electron-native-screenshare/issues"
+  },
+  "homepage": "https://github.com/CilginSinek/electron-native-screenshare#readme",
+  "author": "CilginSinek",
+  "license": "MIT",
+  "dependencies": {
+    "node-addon-api": "^7.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/linux/addon.cpp

@@ -0,0 +1,107 @@
+/**
+ * Linux N-API addon — mirrors the Windows addon.cpp interface exactly.
+ *
+ * Exports:
+ *   startCapture(processId, isIncludeMode, callback) → boolean
+ *   stopCapture() → boolean
+ *   getPidFromHwnd(windowId) → number
+ */
+
+#include <napi.h>
+#include "pipewire_capture.h"
+
+static PipewireCapture capture;
+static Napi::ThreadSafeFunction tsfn;
+
+Napi::Value StartCapture(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+
+    uint32_t processId = 0;
+    if (info.Length() > 0 && info[0].IsNumber()) {
+        processId = info[0].As<Napi::Number>().Uint32Value();
+    }
+
+    bool isIncludeMode = false;
+    if (info.Length() > 1 && info[1].IsBoolean()) {
+        isIncludeMode = info[1].As<Napi::Boolean>().Value();
+    }
+
+    if (info.Length() < 3 || !info[2].IsFunction()) {
+        Napi::TypeError::New(env, "Callback function expected as third argument").ThrowAsJavaScriptException();
+        return env.Null();
+    }
+
+    std::string errorMsg;
+    int result = capture.Initialize(processId, isIncludeMode, errorMsg);
+    if (result != 0 || !errorMsg.empty()) {
+        char buf[512];
+        snprintf(buf, sizeof(buf), "PipeWire Init Failed: %s (code: %d)", errorMsg.c_str(), result);
+        Napi::TypeError::New(env, buf).ThrowAsJavaScriptException();
+        return env.Null();
+    }
+
+    tsfn = Napi::ThreadSafeFunction::New(
+        env,
+        info[2].As<Napi::Function>(),
+        "PipeWireCaptureCallback",
+        0,
+        1
+    );
+
+    auto callback = [](const uint8_t* data, size_t length, PipewireCapture::AudioMetadata metadata) {
+        if (!tsfn) return;
+
+        struct Payload {
+            std::vector<uint8_t> buffer;
+            PipewireCapture::AudioMetadata meta;
+        };
+        auto* payload = new Payload{ std::vector<uint8_t>(data, data + length), metadata };
+
+        auto napiCallback = [](Napi::Env env, Napi::Function jsCallback, Payload* p) {
+            Napi::Object metaObj = Napi::Object::New(env);
+            metaObj.Set("sampleRate", p->meta.sampleRate);
+            metaObj.Set("channels", p->meta.channels);
+            metaObj.Set("bitsPerSample", p->meta.bitsPerSample);
+            metaObj.Set("isFloat", p->meta.isFloat);
+
+            Napi::Buffer<uint8_t> buffer = Napi::Buffer<uint8_t>::Copy(env, p->buffer.data(), p->buffer.size());
+            jsCallback.Call({ buffer, metaObj });
+            delete p;
+        };
+
+        tsfn.NonBlockingCall(payload, napiCallback);
+    };
+
+    capture.Start(callback);
+    return Napi::Boolean::New(env, true);
+}
+
+Napi::Value StopCapture(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    capture.Stop();
+    if (tsfn) {
+        tsfn.Release();
+        tsfn = nullptr;
+    }
+    return Napi::Boolean::New(env, true);
+}
+
+Napi::Value GetPidFromHwnd(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    if (info.Length() < 1 || !info[0].IsNumber()) {
+        Napi::TypeError::New(env, "Number expected").ThrowAsJavaScriptException();
+        return env.Null();
+    }
+    uint32_t windowId = info[0].As<Napi::Number>().Uint32Value();
+    uint32_t pid = getPidFromWindowId(windowId);
+    return Napi::Number::New(env, pid);
+}
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    exports.Set(Napi::String::New(env, "startCapture"), Napi::Function::New(env, StartCapture));
+    exports.Set(Napi::String::New(env, "stopCapture"), Napi::Function::New(env, StopCapture));
+    exports.Set(Napi::String::New(env, "getPidFromHwnd"), Napi::Function::New(env, GetPidFromHwnd));
+    return exports;
+}
+
+NODE_API_MODULE(topluyo_capture, Init)