meeting-record 0.2.1 → 0.3.1

package/README.md

@@ -1,17 +1,17 @@
 # meeting-record for Node.js
 
-System-audio and microphone capture with meeting detection for macOS and Windows.
+[![npm](https://img.shields.io/npm/v/meeting-record)](https://www.npmjs.com/package/meeting-record)
 
-## Install
+System-audio and microphone capture with meeting detection for macOS, Windows, and Linux.
+See the [project README](https://github.com/hoangvvo/meeting-record#readme) for requirements, permissions, and supported apps.
 
 ```sh
 npm install meeting-record
 ```
 
-- Requires Node.js 22.13+ (22.x) or 24+.
-- See the [platform requirements and permissions](https://github.com/hoangvvo/meeting-record#requirements) for app configuration.
+## Usage
 
-## Capture
+Capture system audio for ten seconds.
 
 ```ts
 import { setTimeout as delay } from "node:timers/promises";
@@ -19,131 +19,54 @@ import { capture, permissions, Permission } from "meeting-record";
 
 await permissions.request(Permission.SystemAudio);
 const recording = await capture.start({ type: "system" });
-
-// Stop after ten seconds; keep reading until the stream ends.
 const stopped = delay(10_000).then(() => recording.stopRecording());
+
 for await (const chunk of recording.systemAudio) {
-  // Raw float32 PCM, with the format and capture time of this packet.
   console.log(chunk.pcm, chunk.hostTimeNs, chunk.sampleRate, chunk.channels);
 }
 await stopped;
 ```
 
-| Target                        | Value passed to `capture.start()` |
-| ----------------------------- | --------------------------------- |
-| System audio                  | `{ type: "system" }`              |
-| One app and its audio helpers | `{ type: "process", pid }`        |
-
-- **App picker:** `meetings.audioApps()` lists available apps. Use the selected entry's `pid`; no meeting scan is required.
-- **Meeting capture:** a detected meeting's `pid` is also a process target.
-- **Permissions:** `permissions.request()` returns a `PermissionStatus`; `permissions.status()` checks the current status without prompting.
-- **Sessions:** one recording at a time per process.
-
-### Add a microphone
-
-Request microphone permission, then pass `microphone` in the capture options:
+Select an app and include its microphone and a 24 kHz mix.
 
 ```ts
-import { MicrophoneSource } from "meeting-record";
+import { meetings, MicrophoneSource } from "meeting-record";
 
 await permissions.request(Permission.Microphone);
-const recording = await capture.start(
-  { type: "system" },
-  {
-    mono: false, // Stereo system audio; defaults to mono. The mic stays mono.
-    microphone: MicrophoneSource.Default,
-  },
-);
-```
-
-- `MicrophoneSource.Default` follows the OS input device.
-- `MicrophoneSource.Auto` prefers the captured app's mic on Windows, then the communications default. On macOS, it uses the default input.
-- Without `microphone`, only system audio is captured.
-
-## Audio output
-
-| Output       | Access                  | Data                                                                         |
-| ------------ | ----------------------- | ---------------------------------------------------------------------------- |
-| System audio | `recording.systemAudio` | Object-mode stream of `AudioChunk` packets                                   |
-| Microphone   | `recording.microphone`  | Same packet type; present when requested                                     |
-| Mixed audio  | `recording.mixedAudio`  | Byte stream of mono signed 16-bit little-endian PCM; present when configured |
-
-- **Raw samples:** `chunk.pcm` contains interleaved float32 PCM.
-- **Packet metadata:** `hostTimeNs`, `frameCount`, `sampleRate`, `channels`, and `droppedSamples`.
-- **Reading:** use `data` listeners or `for await...of` on each raw track. Use each packet's format; it can change during capture.
-- **Slow readers:** raw tracks report discarded samples through `drop` events and `droppedSamples`.
-- See [capture formats and channels](https://github.com/hoangvvo/meeting-record#capture) for sample rates and platform behavior.
+const [app] = meetings.audioApps();
+if (!app) throw new Error("No audio apps");
 
-### Mixed audio
-
-After requesting the audio and microphone permissions, start with `mix` to add a combined stream:
-
-```ts
-const recording = await capture.start(
-  { type: "system" },
-  {
-    microphone: MicrophoneSource.Default,
-    mix: { sampleRate: 24_000 }, // Combined mono s16le at 24 kHz.
-  },
+const appRecording = await capture.start(
+  { type: "process", pid: app.pid },
+  { microphone: MicrophoneSource.Auto, mix: { sampleRate: 24_000 } },
 );
-
-recording.mixedAudio.on("data", (pcm) => console.log(pcm.byteLength));
-recording.mixedAudio.setMicrophoneMuted(true); // Affects the mix only.
 ```
 
-- Mixed audio is a standard byte stream: it can also be piped to a writable.
-- Raw tracks remain available alongside the mix.
-
-## Controls and events
-
-| Action                    | API                                                            |
-| ------------------------- | -------------------------------------------------------------- |
-| Pause / resume            | `recording.pauseRecording()` / `recording.resumeRecording()`   |
-| Stop                      | `await recording.stopRecording()`; safe to call more than once |
-| Check recording state     | `recording.state`                                              |
-| Check source availability | `track.availability`                                           |
-| Cancel start or recording | Pass an `AbortSignal` as `CaptureOptions.signal`               |
-
-- **Pause:** affects the whole recording; paused time is omitted.
-- **Stop:** keep reading each output until `end` to drain queued audio.
-- **Source loss:** the session stays alive. Track availability is `live`, `degraded`, or `interrupted`.
-- **App exit:** system audio stops when all captured apps exit; the microphone and session stay alive. Start a new session for a relaunched app.
-
-Attach source-event listeners immediately after awaiting `capture.start()`:
+Read the mix and pause, resume, or stop the recording.
 
 ```ts
-recording.systemAudio.on("interrupted", (reason, message) => console.log(reason, message));
-recording.systemAudio.on("degraded", (reason, message) => console.log(reason, message));
-recording.systemAudio.on("resumed", () => console.log("System audio resumed"));
-recording.microphone?.on("devicechange", (name) => console.log("Microphone:", name));
+appRecording.mixedAudio.on("data", (pcm) => console.log(pcm.byteLength));
+appRecording.pauseRecording();
+appRecording.resumeRecording();
+await delay(10_000);
+await appRecording.stopRecording();
 ```
 
-## Meetings
+Scan for meetings or watch for changes.
 
 ```ts
-import { meetings } from "meeting-record";
-
 const active = (await meetings.scan()).filter((meeting) => meeting.shouldRecord);
 
 meetings.on("started", (meeting) => console.log("Started:", meeting));
 meetings.on("updated", (meeting) => console.log("Updated:", meeting));
-meetings.on("ended", (meeting) => console.log("Ended:", meeting));
+meetings.on("ended", ({ platform, pid }) => console.log("Ended:", platform, pid));
 meetings.watch();
 
-// Later: meetings.unwatch();
+await delay(10_000);
+meetings.unwatch();
 ```
 
-- Use `shouldRecord` to decide whether a meeting is ready to record.
-- Request `Permission.Accessibility` on macOS for titles and URLs; relaunch after granting it.
-- See [supported services and detection behavior](https://github.com/hoangvvo/meeting-record#detection).
-
-## Types and errors
-
-- **Constants:** `Platform`, `Permission`, `PermissionStatus`, `MicrophoneSource`, `CaptureState`, `TrackAvailability`, and `TrackInterruptionReason` have matching union types.
-- **Events:** names and callback arguments are checked by TypeScript, including chained `on`, `once`, and `off` calls.
-- **Library failures:** capture, permissions, and enumeration use `MeetingRecordError` subclasses, with a numeric `code`.
-- **Invalid arguments:** throw `TypeError`.
-- **Cancellation:** aborting rejects pending work with the signal's reason and stops an active recording.
+On `ended`, use `platform` and `pid` to remove the meeting. Other payload fields, including `shouldRecord`, may contain the last active observation. Meeting events do not stop capture; call `stopRecording()` and drain the tracks when you want the recording to end.
 
 ## License
 

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,265 @@
+SpeexDSP 1.2.1 and bundled KISS FFT
+
+Copyright 2002-2008 	Xiph.org Foundation
+Copyright 2002-2008 	Jean-Marc Valin
+Copyright 2005-2007	Analog Devices Inc.
+Copyright 2005-2008	Commonwealth Scientific and Industrial Research
+                        Organisation (CSIRO)
+Copyright 1993, 2002, 2006 David Rowe
+Copyright 2003 		EpicGames
+Copyright 1992-1994	Jutta Degener, Carsten Bormann
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+- Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+- Neither the name of the Xiph.org Foundation nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+Additional source notices
+
+/* Copyright (C) Jean-Marc Valin */
+
+/* Copyright (C) 2003 Epic Games
+   Written by Jean-Marc Valin */
+
+/********************************************************************
+ *                                                                  *
+ * THIS FILE IS PART OF THE OggVorbis SOFTWARE CODEC SOURCE CODE.   *
+ * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
+ * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
+ * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
+ *                                                                  *
+ * THE OggVorbis SOURCE CODE IS (C) COPYRIGHT 1994-2002             *
+ * by the Xiph.Org Foundation http://www.xiph.org/                  *
+ *                                                                  *
+ ********************************************************************
+
+ function: #ifdef jail to whip a few platforms into the UNIX ideal.
+ last mod: $Id: os_types.h 7524 2004-08-11 04:20:36Z conrad $
+
+ ********************************************************************/
+
+/*
+Copyright (c) 2003-2004, Mark Borgerding
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+    * Neither the author nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/* Copyright (C) 2003 Jean-Marc Valin */
+
+/* Copyright (C) 2005-2006 Jean-Marc Valin
+   File: fftwrap.c
+
+   Wrapper for various FFTs
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions
+   are met:
+
+   - Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+   - Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+   - Neither the name of the Xiph.org Foundation nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+   A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
+   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+*/
+
+/* Copyright (C) 2005 Jean-Marc Valin
+   File: fftwrap.h
+
+   Wrapper for various FFTs
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions
+   are met:
+
+   - Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+   - Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+   - Neither the name of the Xiph.org Foundation nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+   A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
+   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+*/
+
+/* Copyright (C) 2006 Jean-Marc Valin */
+
+/*
+Copyright (c) 2003-2004, Mark Borgerding
+Copyright (c) 2005-2007, Jean-Marc Valin
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+    * Neither the author nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/* Copyright (C) 2002 Jean-Marc Valin */
+
+/* Copyright (C) 2003-2008 Jean-Marc Valin
+
+   File: mdf.c
+   Echo canceller based on the MDF algorithm (see below)
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions are
+   met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+   3. The name of the author may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+   DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+   INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+   STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+   ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+   POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/* Copyright (C) 2007 Jean-Marc Valin
+
+   File: os_support.h
+   This is the (tiny) OS abstraction layer. Aside from math.h, this is the
+   only place where system headers are allowed.
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions are
+   met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+   3. The name of the author may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+   DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+   INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+   STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+   ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+   POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/* Copyright (C) 2003 Epic Games (written by Jean-Marc Valin)
+   Copyright (C) 2004-2006 Epic Games
+
+   File: preprocess.c
+   Preprocessor with denoising based on the algorithm by Ephraim and Malah
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions are
+   met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+   3. The name of the author may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+   DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+   INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+   STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+   ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+   POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/* Copyright (C) 2005 Jean-Marc Valin */

package/dist/index.d.ts

@@ -29,6 +29,32 @@ export declare const Platform: {
     readonly Discord: "discord";
     /** A browser tab on a recognised call URL. */
     readonly Browser: "browser";
+    readonly GoTo: "goto";
+    readonly Dialpad: "dialpad";
+    readonly WhatsApp: "whatsapp";
+    readonly Aircall: "aircall";
+    readonly RingCentral: "ringcentral";
+    readonly EightByEight: "8x8";
+    readonly VooV: "voov";
+    readonly Tuple: "tuple";
+    readonly Gather: "gather";
+    readonly Lark: "lark";
+    readonly Roam: "roam";
+    readonly ClickUp: "clickup";
+    readonly Telemost: "telemost";
+    readonly Telegram: "telegram";
+    readonly Signal: "signal";
+    readonly Viber: "viber";
+    readonly Line: "line";
+    readonly WeChat: "wechat";
+    readonly Zalo: "zalo";
+    readonly Jitsi: "jitsi";
+    readonly Element: "element";
+    readonly Mattermost: "mattermost";
+    readonly NextcloudTalk: "nextcloud-talk";
+    readonly Jami: "jami";
+    readonly TencentMeeting: "tencent-meeting";
+    readonly WeCom: "wecom";
     readonly Unknown: "unknown";
 };
 export type Platform = (typeof Platform)[keyof typeof Platform];
@@ -69,41 +95,70 @@ export type CaptureTarget = {
 export declare const MicrophoneSource: {
     /** Follow the OS default input device. */
     readonly Default: "default";
-    /** Prefer the captured app's mic on Windows, then its communications default. Use the OS default on macOS. */
+    /** Prefer the captured app's mic, then the default (communications default on Windows). Ambiguous app inputs use the default on macOS. */
     readonly Auto: "auto";
 };
 export type MicrophoneSource = (typeof MicrophoneSource)[keyof typeof MicrophoneSource];
+/** Optional microphone effects for input rates from 8 to 192 kHz. All default off. */
+export interface MicrophoneProcessing {
+    /** Cancel echo using the captured system track as the playback reference. */
+    echoCancellation?: boolean;
+    /** Suppress background noise in the microphone track. */
+    noiseSuppression?: boolean;
+    /** Adjust microphone gain automatically. */
+    autoGainControl?: boolean;
+}
 export interface CaptureOptions {
     /** Mono mixdown for system audio only; the microphone keeps its format. Default true. */
     mono?: boolean;
-    /** Capture a microphone as a separate track. Default off. */
+    /** Capture a separate microphone track. Default off; unavailable devices recover while system capture continues. */
     microphone?: MicrophoneSource;
+    /** Optional microphone effects. All default off; requires microphone. */
+    microphoneProcessing?: MicrophoneProcessing;
     /** Additional mono s16le output, aligned and resampled to the requested rate. */
     mix?: MixedAudioOptions;
     /** Aborting stops capture, including a pending start. */
     signal?: AbortSignal;
 }
+/** Base class for library errors with a native status code. */
 export declare class MeetingRecordError extends Error {
+    /** Native status code. */
     readonly code: number;
-    constructor(message: string, code: number);
+    constructor(message: string, 
+    /** Native status code. */
+    code: number);
 }
+/** The OS, architecture, or OS version is unsupported. */
 export declare class UnsupportedOsError extends MeetingRecordError {
 }
+/** Required system-audio or microphone access has not been granted. */
 export declare class PermissionError extends MeetingRecordError {
 }
+/** A process-wide recording or watcher is already active. */
 export declare class AlreadyRunningError extends MeetingRecordError {
 }
+/** An audio capture operation failed. */
 export declare class CaptureError extends MeetingRecordError {
 }
+/** Native initialization or another internal operation failed. */
 export declare class InternalError extends MeetingRecordError {
 }
 export declare const permissions: {
+    /**
+     * Check the current permission without prompting.
+     * @throws {TypeError} If the permission is unknown.
+     * @throws {UnsupportedOsError} If the platform is unsupported.
+     */
     status(permission: Permission): PermissionStatus;
     /**
      * Show the permission prompt and resolve once the user answers.
      *
      * Accessibility opens System Settings and needs an app relaunch, so it resolves
      * as soon as Settings is open.
+     * Returns the current status if the timeout expires.
+     * @throws {TypeError} If the permission is unknown.
+     * @throws {MeetingRecordError} If the platform cannot start the permission request.
+     * @throws If the request is aborted.
      */
     request(permission: Permission, { timeoutMs, signal }?: {
         timeoutMs?: number;
@@ -113,22 +168,35 @@ export declare const permissions: {
 export interface MeetingEvents extends EmitterEvents {
     started: (meeting: Meeting) => void;
     updated: (meeting: Meeting) => void;
+    /** Only platform and pid identify the ended meeting; other fields may be stale. Does not stop capture. */
     ended: (meeting: Meeting) => void;
 }
 declare class Meetings extends EventEmitter<{
     [Event in keyof MeetingEvents]: Parameters<MeetingEvents[Event]>;
 }> {
-    /** Point-in-time scan, highest confidence first. */
+    /**
+     * Point-in-time scan, highest confidence first. Use `shouldRecord` to select calls.
+     * @throws {MeetingRecordError} If the platform or audio service cannot be queried.
+     */
     scan(): Promise<Meeting[]>;
-    /** Begin emitting `started` / `updated` / `ended`. */
+    /**
+     * Begin emitting `started` / `updated` / `ended`. Repeated calls are harmless.
+     * @throws {MeetingRecordError} If the watcher cannot start.
+     */
     watch(): void;
+    /** Stop meeting events; safe to call when already stopped. */
     unwatch(): void;
+    /** Whether meeting events are currently being watched. */
     get watching(): boolean;
-    /** Every process doing audio IO. */
+    /**
+     * Every process doing audio IO.
+     * @throws {MeetingRecordError} If audio processes cannot be enumerated.
+     */
     audioProcesses(): AudioProcess[];
     /**
      * Applications doing audio IO, grouped by owning PID, including helpers.
      * Pass `pid` as a process target; no meeting scan or Accessibility grant is needed.
+     * @throws {MeetingRecordError} If audio applications cannot be enumerated.
      */
     audioApps(): AudioProcess[];
 }
@@ -150,6 +218,7 @@ export declare const TrackInterruptionReason: {
 };
 export type TrackInterruptionReason = (typeof TrackInterruptionReason)[keyof typeof TrackInterruptionReason];
 export interface AudioFormat {
+    /** May be zero while the requested microphone has no available device. */
     readonly sampleRate: number;
     readonly channels: number;
 }
@@ -157,10 +226,14 @@ export interface AudioFormat {
 export interface AudioChunk {
     /** Interleaved float32 PCM. Packet boundaries and metadata survive iteration. */
     readonly pcm: Buffer;
+    /** First frame's monotonic timestamp in nanoseconds, shared across tracks. */
     readonly hostTimeNs: bigint;
+    /** Number of frames per channel in this packet. */
     readonly frameCount: number;
+    /** This packet's rate; it may change after device recovery. */
     readonly sampleRate: number;
     readonly channels: number;
+    /** Interleaved samples lost before this packet because the input queue was full. */
     readonly droppedSamples: number;
 }
 export declare const TrackAvailability: {
@@ -201,20 +274,47 @@ export interface CaptureSession {
     readonly microphone?: AudioTrack;
     readonly mixedAudio?: MixedAudio;
     readonly state: CaptureState;
+    /** Pause all tracks. Paused time is omitted from mixed output. */
     pauseRecording(): void;
+    /** Resume all tracks after a pause. */
     resumeRecording(): void;
+    /**
+     * Stop once, then read outputs until `end` to drain their final audio.
+     * Repeated calls share the same promise.
+     * @throws {Error} If native capture teardown fails.
+     */
     stopRecording(): Promise<void>;
 }
 export interface MixedCaptureSession extends CaptureSession {
     readonly mixedAudio: MixedAudio;
 }
-/** Attach source-event listeners immediately after awaiting start; startup notifications are delivered on the next turn. */
+/**
+ * Start a process-wide recording. Attach source-event listeners after awaiting startup.
+ * @throws {TypeError} If the target or capture options are invalid.
+ * @throws {AlreadyRunningError} If another recording is active or starting.
+ * @throws {PermissionError} If required capture permissions are missing.
+ * @throws {CaptureError} If the target or system audio cannot be opened.
+ * @throws {UnsupportedOsError} If the platform is unsupported.
+ * @throws {InternalError} If native initialization fails.
+ * @throws The signal's reason if startup is aborted.
+ */
 declare function startCapture(target: CaptureTarget, options: CaptureOptions & {
     mix: MixedAudioOptions;
 }): Promise<MixedCaptureSession>;
+/**
+ * Start a process-wide recording. Attach source-event listeners after awaiting startup.
+ * @throws {TypeError} If the target or capture options are invalid.
+ * @throws {AlreadyRunningError} If another recording is active or starting.
+ * @throws {PermissionError} If required capture permissions are missing.
+ * @throws {CaptureError} If the target or system audio cannot be opened.
+ * @throws {UnsupportedOsError} If the platform is unsupported.
+ * @throws {InternalError} If native initialization fails.
+ * @throws The signal's reason if startup is aborted.
+ */
 declare function startCapture(target: CaptureTarget, options?: CaptureOptions): Promise<CaptureSession>;
 export declare const capture: {
     start: typeof startCapture;
+    /** Whether a recording is starting or active, including while paused. */
     readonly running: boolean;
 };
 //# sourceMappingURL=index.d.ts.map