truehear-audio-library-node 1.0.0

package/README.md

@@ -0,0 +1,220 @@
+# truehear-audio-library-node
+
+Native Node.js audio library for listing audio devices and setting default audio devices.
+
+Author: @truehear team
+
+## Installation
+
+Install the package with npm:
+
+```bash
+npm install truehear-audio-library-node
+```
+
+## Platform support
+
+Currently supported platform:
+
+```text
+Windows
+```
+
+This package uses a native Node.js addon to access system audio devices.
+
+## Basic usage
+
+```ts
+import { listDevices } from 'truehear-audio-library-node';
+
+const devices = listDevices('playback');
+
+console.log(devices);
+```
+
+## List playback devices
+
+Playback devices are output devices such as speakers, headphones, HDMI output, or monitor audio.
+
+```ts
+import { listDevices } from 'truehear-audio-library-node';
+
+const playbackDevices = listDevices('playback');
+
+console.log(playbackDevices);
+```
+
+Example output:
+
+```ts
+[
+  {
+    default: true,
+    defaultCommunication: false,
+    type: 'playback',
+    name: 'Speakers (Realtek(R) Audio)',
+    id: '{0.0.0.00000000}.{37439da3-a6eb-4740-8405-6cfbae03dd57}'
+  }
+]
+```
+
+## List recording devices
+
+Recording devices are input devices such as microphones, headset microphones, or USB audio input devices.
+
+```ts
+import { listDevices } from 'truehear-audio-library-node';
+
+const recordingDevices = listDevices('recording');
+
+console.log(recordingDevices);
+```
+
+## Set the default playback device
+
+Use the device `id` returned from `listDevices`.
+
+```ts
+import {
+  listDevices,
+  setDefaultDevice,
+} from 'truehear-audio-library-node';
+
+const devices = listDevices('playback');
+
+const targetDevice = devices[0];
+
+setDefaultDevice('playback', targetDevice.id);
+```
+
+## Set the default recording device
+
+```ts
+import {
+  listDevices,
+  setDefaultDevice,
+} from 'truehear-audio-library-node';
+
+const devices = listDevices('recording');
+
+const targetDevice = devices[0];
+
+setDefaultDevice('recording', targetDevice.id);
+```
+
+## Set the default communication device
+
+Communication devices are used by calling and meeting applications.
+
+```ts
+import {
+  listDevices,
+  setDefaultCommunicationDevice,
+} from 'truehear-audio-library-node';
+
+const devices = listDevices('playback');
+
+const targetDevice = devices[0];
+
+setDefaultCommunicationDevice('playback', targetDevice.id);
+```
+
+## API
+
+### `listDevices(type)`
+
+Lists audio devices.
+
+```ts
+listDevices(type: AudioDeviceType): AudioDeviceInfo[]
+```
+
+Example:
+
+```ts
+const playbackDevices = listDevices('playback');
+const recordingDevices = listDevices('recording');
+```
+
+### `setDefaultDevice(type, deviceId)`
+
+Sets the normal default audio device.
+
+```ts
+setDefaultDevice(type: AudioDeviceType, deviceId: string): void
+```
+
+Example:
+
+```ts
+setDefaultDevice('playback', deviceId);
+```
+
+### `setDefaultCommunicationDevice(type, deviceId)`
+
+Sets the default communication audio device.
+
+```ts
+setDefaultCommunicationDevice(
+  type: AudioDeviceType,
+  deviceId: string
+): void
+```
+
+Example:
+
+```ts
+setDefaultCommunicationDevice('playback', deviceId);
+```
+
+## Types
+
+### `AudioDeviceType`
+
+```ts
+type AudioDeviceType = 'playback' | 'recording';
+```
+
+### `AudioDeviceInfo`
+
+```ts
+type AudioDeviceInfo = {
+  default: boolean;
+  defaultCommunication: boolean;
+  type: AudioDeviceType;
+  name: string;
+  id: string;
+};
+```
+
+## Device ID
+
+The `id` field is the native operating system device identifier.
+
+Use this value when calling:
+
+```ts
+setDefaultDevice(type, deviceId);
+setDefaultCommunicationDevice(type, deviceId);
+```
+
+## Error handling
+
+Invalid arguments throw `TypeError`.
+
+Native audio failures throw `Error`.
+
+```ts
+import { listDevices } from 'truehear-audio-library-node';
+
+try {
+  const devices = listDevices('playback');
+  console.log(devices);
+} catch (error) {
+  console.error(error);
+}
+```
+
+## License
+
+ISC

package/binding.gyp

@@ -0,0 +1,45 @@
+{
+  "targets": [
+    {
+      "target_name": "truehear_audio_native",
+      "sources": [
+        "src/addon.c",
+        "src/truehear_audio_win.c",
+        "src/policy_config_guids.c",
+        "src/mmdevice_guids.c"
+      ],
+      "include_dirs": [
+        "include"
+      ],
+      "defines": [
+        "NAPI_VERSION=8"
+      ],
+      "conditions": [
+        [
+          "OS==\"win\"",
+          {
+            "libraries": [
+              "ole32.lib",
+              "mmdevapi.lib",
+              "uuid.lib"
+            ],
+            "msvs_settings": {
+              "VCCLCompilerTool": {
+                "WarningLevel": 4,
+                "DebugInformationFormat": 3
+              }
+            }
+          }
+        ],
+        [
+          "OS!=\"win\"",
+          {
+            "sources!": [
+              "src/truehear_audio_win.c"
+            ]
+          }
+        ]
+      ]
+    }
+  ]
+}

package/dist/domain/audio-device.types.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Public audio device type definitions.
+ *
+ * This file is intentionally TypeScript-only.
+ *
+ * Design goals:
+ * - Describe the public API shape exposed to TypeScript consumers.
+ * - Stay independent from the native implementation details.
+ * - Mirror the object shape returned from the native addon.
+ * - Provide high-quality JSDoc for IDEs, IntelliSense, and generated docs.
+ */
+/**
+ * Represents the direction of an audio endpoint.
+ *
+ * Use this type to distinguish between:
+ * - `playback`: audio output devices such as speakers, headphones, or HDMI audio
+ * - `recording`: audio input devices such as microphones or headset mics
+ *
+ * @remarks
+ * This value is used by the native binding to query and update the correct
+ * class of device on the operating system.
+ *
+ * @example
+ * ```ts
+ * const deviceType: AudioDeviceType = "playback";
+ * ```
+ *
+ * @example
+ * ```ts
+ * function isInputDevice(type: AudioDeviceType) {
+ *   return type === "recording";
+ * }
+ * ```
+ */
+export type AudioDeviceType = "playback" | "recording";
+/**
+ * Describes a single audio device exposed by the operating system.
+ *
+ * This is the TypeScript representation of the native C structure returned
+ * by the addon.
+ *
+ * @remarks
+ * The native layer converts platform-specific endpoint metadata into this
+ * plain JavaScript object shape so that consumers can work with a stable,
+ * ergonomic API.
+ *
+ * @example
+ * ```ts
+ * const device: AudioDeviceInfo = {
+ *   default: true,
+ *   defaultCommunication: false,
+ *   type: "playback",
+ *   name: "Speakers (Realtek(R) Audio)",
+ *   id: "{0.0.0.00000000}.{37439da3-a6eb-4740-8405-6cfbae03dd57}",
+ * };
+ * ```
+ */
+export type AudioDeviceInfo = {
+    /**
+     * Indicates whether this device is the current system default for
+     * standard audio output or input.
+     *
+     * @remarks
+     * On Windows, this typically corresponds to the default multimedia endpoint
+     * used by normal desktop applications.
+     *
+     * - `true`  — the device is the current default device
+     * - `false` — the device is available, but not selected as default
+     */
+    default: boolean;
+    /**
+     * Indicates whether this device is the current system default for
+     * communication audio.
+     *
+     * @remarks
+     * Communication devices are typically used by:
+     * - Teams
+     * - Zoom
+     * - Discord
+     * - voice and calling applications
+     *
+     * This is separate from the normal default audio device.
+     */
+    defaultCommunication: boolean;
+    /**
+     * The direction of the device.
+     *
+     * @remarks
+     * - `playback` means an output device
+     * - `recording` means an input device
+     */
+    type: AudioDeviceType;
+    /**
+     * A human-readable device name presented by the operating system.
+     *
+     * @example
+     * ```ts
+     * "Speakers (Realtek(R) Audio)"
+     * "Microphone (USB PnP Audio Device)"
+     * ```
+     */
+    name: string;
+    /**
+     * The native operating-system identifier for the device.
+     *
+     * @remarks
+     * On Windows, this is typically the Core Audio endpoint ID. It is stable
+     * enough to be passed back into device selection APIs.
+     *
+     * @example
+     * ```ts
+     * "{0.0.0.00000000}.{37439da3-a6eb-4740-8405-6cfbae03dd57}"
+     * ```
+     */
+    id: string;
+};
+/**
+ * Shape of the native binding loaded from the compiled `.node` file.
+ *
+ * @remarks
+ * This type is internal to the TypeScript wrapper layer. It describes the
+ * JavaScript object exported by the native addon and consumed by the public
+ * API wrapper.
+ *
+ * The actual implementation is in native C/C++ and is loaded at runtime.
+ */
+export type NativeAudioBinding = {
+    /**
+     * Returns the list of available audio devices for the requested direction.
+     *
+     * @param type - The device direction to query.
+     * @returns An array of audio devices currently available on the system.
+     *
+     * @example
+     * ```ts
+     * const playbackDevices = binding.listDevices("playback");
+     * console.log(playbackDevices);
+     * ```
+     *
+     * @example
+     * ```ts
+     * const recordingDevices = binding.listDevices("recording");
+     * const defaultMic = recordingDevices.find((d) => d.default);
+     * console.log(defaultMic?.name);
+     * ```
+     *
+     * @example
+     * ```ts
+     * for (const device of binding.listDevices("playback")) {
+     *   console.log(`${device.default ? "[default] " : ""}${device.name}`);
+     * }
+     * ```
+     */
+    listDevices(type: AudioDeviceType): AudioDeviceInfo[];
+    /**
+     * Sets the current default normal audio device for the given direction.
+     *
+     * @remarks
+     * This changes the device used by standard applications for either:
+     * - audio playback, when `type` is `"playback"`
+     * - audio recording, when `type` is `"recording"`
+     *
+     * Use the `id` value returned by {@link listDevices}.
+     *
+     * @param type - The device direction to update.
+     * @param deviceId - The native device identifier returned by {@link listDevices}.
+     *
+     * @example
+     * ```ts
+     * const devices = binding.listDevices("playback");
+     * const speakers = devices.find((d) => d.name.includes("Speakers"));
+     *
+     * if (speakers) {
+     *   binding.setDefaultDevice("playback", speakers.id);
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * const mics = binding.listDevices("recording");
+     * const usbMic = mics.find((d) => d.name.includes("USB"));
+     *
+     * if (usbMic) {
+     *   binding.setDefaultDevice("recording", usbMic.id);
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Swap to the first available output device.
+     * const devices = binding.listDevices("playback");
+     * if (devices.length > 0) {
+     *   binding.setDefaultDevice("playback", devices[0].id);
+     * }
+     * ```
+     */
+    setDefaultDevice(type: AudioDeviceType, deviceId: string): void;
+    /**
+     * Sets the current default communication audio device for the given direction.
+     *
+     * @remarks
+     * Communication devices are typically used by apps that prioritize voice
+     * calling and conferencing.
+     *
+     * Use the `id` value returned by {@link listDevices}.
+     *
+     * @param type - The device direction to update.
+     * @param deviceId - The native device identifier returned by {@link listDevices}.
+     *
+     * @example
+     * ```ts
+     * const devices = binding.listDevices("recording");
+     * const headsetMic = devices.find((d) => d.name.includes("Headset"));
+     *
+     * if (headsetMic) {
+     *   binding.setDefaultCommunicationDevice("recording", headsetMic.id);
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * const speakers = binding.listDevices("playback").find((d) => d.default);
+     *
+     * if (speakers) {
+     *   binding.setDefaultCommunicationDevice("playback", speakers.id);
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Set the communication output device to the first available playback device.
+     * const playbackDevices = binding.listDevices("playback");
+     * if (playbackDevices[0]) {
+     *   binding.setDefaultCommunicationDevice("playback", playbackDevices[0].id);
+     * }
+     * ```
+     */
+    setDefaultCommunicationDevice(type: AudioDeviceType, deviceId: string): void;
+};
+//# sourceMappingURL=audio-device.types.d.ts.map

package/dist/domain/audio-device.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-device.types.d.ts","sourceRoot":"","sources":["../../node/domain/audio-device.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,WAAW,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;;;;;;OAUG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;;;OAYG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAE9B;;;;;;OAMG;IACH,IAAI,EAAE,eAAe,CAAC;IAEtB;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;;OAWG;IACH,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,gBAAgB,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,6BAA6B,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9E,CAAC"}

package/dist/domain/audio-device.types.js

@@ -0,0 +1,13 @@
+/**
+ * Public audio device type definitions.
+ *
+ * This file is intentionally TypeScript-only.
+ *
+ * Design goals:
+ * - Describe the public API shape exposed to TypeScript consumers.
+ * - Stay independent from the native implementation details.
+ * - Mirror the object shape returned from the native addon.
+ * - Provide high-quality JSDoc for IDEs, IntelliSense, and generated docs.
+ */
+export {};
+//# sourceMappingURL=audio-device.types.js.map

package/dist/domain/audio-device.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-device.types.js","sourceRoot":"","sources":["../../node/domain/audio-device.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import type { AudioDeviceInfo, AudioDeviceType } from "./domain/audio-device.types.js";
+/**
+ * Public types re-exported from the package root.
+ *
+ * Consumers can import these directly from the package entrypoint:
+ *
+ * ```ts
+ * import type { AudioDeviceInfo, AudioDeviceType } from 'truehear-audio-library-node';
+ * ```
+ */
+export type { AudioDeviceInfo, AudioDeviceType };
+/**
+ * List available audio devices for a given direction.
+ *
+ * @param type - The device direction to query.
+ * @returns The list of devices exposed by the operating system.
+ *
+ * @example
+ * ```ts
+ * import { listDevices } from 'truehear-audio-library-node';
+ *
+ * const playbackDevices = listDevices('playback');
+ * console.log(playbackDevices);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const recordingDevices = listDevices('recording');
+ * const defaultMic = recordingDevices.find((device) => device.default);
+ *
+ * if (defaultMic) {
+ *   console.log(`Default microphone: ${defaultMic.name}`);
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * for (const device of listDevices('playback')) {
+ *   console.log(`${device.default ? '[default] ' : ''}${device.name}`);
+ * }
+ * ```
+ */
+export declare const listDevices: (type: AudioDeviceType) => AudioDeviceInfo[];
+/**
+ * Set the system's default normal audio device.
+ *
+ * @remarks
+ * Use this function to switch the primary device used by standard applications.
+ *
+ * @param type - The device direction to update.
+ * @param deviceId - The native device identifier returned by {@link listDevices}.
+ *
+ * @example
+ * ```ts
+ * const devices = listDevices('playback');
+ * const speakers = devices.find((device) => device.name.includes('Speakers'));
+ *
+ * if (speakers) {
+ *   setDefaultDevice('playback', speakers.id);
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const mics = listDevices('recording');
+ * const usbMic = mics.find((device) => device.name.includes('USB'));
+ *
+ * if (usbMic) {
+ *   setDefaultDevice('recording', usbMic.id);
+ * }
+ * ```
+ */
+export declare const setDefaultDevice: (type: AudioDeviceType, deviceId: string) => void;
+/**
+ * Set the system's default communication audio device.
+ *
+ * @remarks
+ * Communication devices are typically used by calling and conferencing apps
+ * such as Teams, Zoom, Discord, and similar voice-capable software.
+ *
+ * @param type - The device direction to update.
+ * @param deviceId - The native device identifier returned by {@link listDevices}.
+ *
+ * @example
+ * ```ts
+ * const devices = listDevices('playback');
+ * const defaultPlayback = devices.find((device) => device.default);
+ *
+ * if (defaultPlayback) {
+ *   setDefaultCommunicationDevice('playback', defaultPlayback.id);
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const recordingDevices = listDevices('recording');
+ * const headsetMic = recordingDevices.find((device) =>
+ *   device.name.toLowerCase().includes('headset'),
+ * );
+ *
+ * if (headsetMic) {
+ *   setDefaultCommunicationDevice('recording', headsetMic.id);
+ * }
+ * ```
+ */
+export declare const setDefaultCommunicationDevice: (type: AudioDeviceType, deviceId: string) => void;
+/**
+ * Default package export for consumers who prefer object-style access.
+ *
+ * @example
+ * ```ts
+ * import truehearAudio from 'truehear-audio-library-node';
+ *
+ * const devices = truehearAudio.listDevices('playback');
+ * ```
+ */
+declare const truehearAudio: {
+    listDevices: (type: AudioDeviceType) => AudioDeviceInfo[];
+    setDefaultDevice: (type: AudioDeviceType, deviceId: string) => void;
+    setDefaultCommunicationDevice: (type: AudioDeviceType, deviceId: string) => void;
+};
+export default truehearAudio;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../node/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEhB,MAAM,gCAAgC,CAAC;AAExC;;;;;;;;GAQG;AACH,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,CAAC;AA+CjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,WAAW,8CAAqB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB,mDAA0B,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,6BAA6B,mDACJ,CAAC;AAEvC;;;;;;;;;GASG;AACH,QAAA,MAAM,aAAa;;;;CAIlB,CAAC;AAEF,eAAe,aAAa,CAAC"}