truehear-audio-library-node 1.0.0

package/include/truehear_audio.h

@@ -0,0 +1,348 @@
+#ifndef TRUEHEAR_AUDIO_H
+#define TRUEHEAR_AUDIO_H
+
+#include "audio_device_types.h"
+
+/**
+ * @file truehear_audio.h
+ * @brief Public, platform-agnostic Truehear audio API.
+ *
+ * This header exposes a stable C interface for audio device discovery and
+ * default-device management across supported operating systems.
+ *
+ * Intended consumers:
+ *   - Node/NPM native addon layer
+ *   - integration tests
+ *   - CLI / application code that must remain platform-neutral
+ *
+ * ---------------------------------------------------------------------------
+ * Why this API exists
+ * ---------------------------------------------------------------------------
+ * Platform audio APIs are different (Windows COM, CoreAudio, PipeWire, etc.).
+ * This file hides those differences behind one portable interface.
+ *
+ * Keep this API clean:
+ *   - No COM/Windows-only types
+ *   - No IMMDevice/IPolicyConfig in public signatures
+ *   - No platform-specific structs in public contracts
+ *
+ * Layering:
+ *   App / Node addon / tests
+ *            ↓
+ *      truehear_audio.h   (this file)
+ *            ↓
+ *      platform implementation
+ *            ↓
+ *   Windows Core Audio | macOS CoreAudio | Linux PipeWire/Pulse/ALSA
+ *
+ * ---------------------------------------------------------------------------
+ * Error model
+ * ---------------------------------------------------------------------------
+ * Most functions return:
+ *   -  0 on success
+ *   - -1 on failure
+ *
+ * On failure, call truehear_audio_get_last_error() for a human-readable reason.
+ *
+ * ---------------------------------------------------------------------------
+ * Memory model
+ * ---------------------------------------------------------------------------
+ * truehear_audio_list_devices() allocates memory for the output list.
+ * Caller MUST free it using truehear_audio_free_device_list().
+ *
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ============================================================================================== */
+/* Quick Start                                                                                    */
+/* ============================================================================================== */
+/**
+ * Basic flow:
+ *
+ * 1) Enumerate devices:
+ *      truehear_audio_list_devices(type, &list)
+ * 2) Pick a device ID from list.items[i].id
+ * 3) Set default:
+ *      truehear_audio_set_default_device(type, device_id)
+ *    Optional (communication profile):
+ *      truehear_audio_set_default_communication_device(type, device_id)
+ * 4) Cleanup:
+ *      truehear_audio_free_device_list(&list)
+ *
+ * Typical type mapping:
+ *   - TRUEHEAR_AUDIO_DEVICE_TYPE_PLAYBACK  -> output devices (speakers/headphones)
+ *   - TRUEHEAR_AUDIO_DEVICE_TYPE_RECORDING -> input devices (microphones)
+ */
+
+/* ============================================================================================== */
+/* Device Enumeration                                                                             */
+/* ============================================================================================== */
+
+/**
+ * @brief Enumerate audio devices for a given device class.
+ *
+ * @param type
+ *   Device class to enumerate:
+ *   - TRUEHEAR_AUDIO_DEVICE_TYPE_PLAYBACK
+ *   - TRUEHEAR_AUDIO_DEVICE_TYPE_RECORDING
+ *
+ * @param[out] out_list
+ *   Receives an allocated device list on success.
+ *
+ * @return
+ *   -  0 on success
+ *   - -1 on failure (use truehear_audio_get_last_error())
+ *
+ * @pre
+ *   - out_list != NULL
+ *
+ * @post (on success)
+ *   - out_list is initialized and owns allocated memory
+ *   - caller must call truehear_audio_free_device_list(out_list)
+ *
+ * @post (on failure)
+ *   - out_list content is implementation-defined; caller should still treat
+ *     cleanup as safe via truehear_audio_free_device_list(out_list)
+ *
+ * @Example:
+ * @code
+ * #include <stdio.h>
+ * #include "truehear_audio.h"
+ *
+ * static void print_devices(TruehearAudioDeviceType type) {
+ *     TruehearAudioDeviceInfoList list;
+ *
+ *     if (truehear_audio_list_devices(type, &list) != 0) {
+ *         fprintf(stderr, "List failed: %s\n", truehear_audio_get_last_error());
+ *         return;
+ *     }
+ *
+ *     for (int i = 0; i < list.count; ++i) {
+ *         const TruehearAudioDeviceInfo *d = &list.items[i];
+ *         printf("[%d] name='%s' id='%s' is_default=%d\n",
+ *                i,
+ *                d->name ? d->name : "(null)",
+ *                d->id ? d->id : "(null)",
+ *                d->is_default);
+ *     }
+ *
+ *     truehear_audio_free_device_list(&list);
+ * }
+ * @endcode
+ */
+int truehear_audio_list_devices(
+    TruehearAudioDeviceType type,
+    TruehearAudioDeviceInfoList *out_list);
+
+/* ============================================================================================== */
+/* Default Device Management                                                                      */
+/* ============================================================================================== */
+
+/**
+ * @brief Set the system default audio device.
+ *
+ * Typical meaning:
+ *   - playback  => system default output
+ *   - recording => system default input
+ *
+ * @param type
+ *   Playback or recording device class.
+ *
+ * @param device_id
+ *   Non-NULL, non-empty device ID from truehear_audio_list_devices().
+ *
+ * @return
+ *   -  0 on success
+ *   - -1 on failure (use truehear_audio_get_last_error())
+ *
+ * @pre
+ *   - device_id != NULL
+ *   - device_id points to a valid, null-terminated string
+ *
+ * Example:
+ * @code
+ * // Set first playback device as system default (demo only).
+ * TruehearAudioDeviceInfoList list;
+ * if (truehear_audio_list_devices(TRUEHEAR_AUDIO_DEVICE_TYPE_PLAYBACK, &list) != 0) {
+ *     fprintf(stderr, "List failed: %s\n", truehear_audio_get_last_error());
+ *     return;
+ * }
+ *
+ * if (list.count > 0 && list.items[0].id) {
+ *     if (truehear_audio_set_default_device(
+ *             TRUEHEAR_AUDIO_DEVICE_TYPE_PLAYBACK,
+ *             list.items[0].id) != 0) {
+ *         fprintf(stderr, "Set default failed: %s\n", truehear_audio_get_last_error());
+ *     }
+ * }
+ *
+ * truehear_audio_free_device_list(&list);
+ * @endcode
+ */
+int truehear_audio_set_default_device(
+    TruehearAudioDeviceType type,
+    const char *device_id);
+
+/**
+ * @brief Set the default communication audio device.
+ *
+ * Some platforms (notably Windows) distinguish:
+ *   - regular multimedia default
+ *   - communication default (calls/conferencing apps)
+ *
+ * On platforms without a communication role, this may return failure with an
+ * "unsupported" style error message.
+ *
+ * @param type
+ *   Playback or recording device class.
+ *
+ * @param device_id
+ *   Non-NULL, non-empty device ID from truehear_audio_list_devices().
+ *
+ * @return
+ *   -  0 on success
+ *   - -1 on failure (use truehear_audio_get_last_error())
+ *
+ * Example:
+ * @code
+ * // Try to set communication default for microphones.
+ * TruehearAudioDeviceInfoList list;
+ * if (truehear_audio_list_devices(TRUEHEAR_AUDIO_DEVICE_TYPE_RECORDING, &list) != 0) {
+ *     fprintf(stderr, "List failed: %s\n", truehear_audio_get_last_error());
+ *     return;
+ * }
+ *
+ * // Pick a candidate by your own policy (name match, index, etc.)
+ * for (int i = 0; i < list.count; ++i) {
+ *     if (list.items[i].id) {
+ *         if (truehear_audio_set_default_communication_device(
+ *                 TRUEHEAR_AUDIO_DEVICE_TYPE_RECORDING,
+ *                 list.items[i].id) != 0) {
+ *             fprintf(stderr, "Set comm default failed: %s\n",
+ *                     truehear_audio_get_last_error());
+ *         }
+ *         break;
+ *     }
+ * }
+ *
+ * truehear_audio_free_device_list(&list);
+ * @endcode
+ */
+int truehear_audio_set_default_communication_device(
+    TruehearAudioDeviceType type,
+    const char *device_id);
+
+/* ============================================================================================== */
+/* Memory Management                                                                              */
+/* ============================================================================================== */
+
+/**
+ * @brief Free resources in a device list returned by truehear_audio_list_devices().
+ *
+ * Releases:
+ *   - list->items
+ *   - item.name
+ *   - item.id
+ *   - item.device
+ *
+ * Safe to call with:
+ *   - NULL
+ *   - list with count == 0
+ *   - list with items == NULL
+ *
+ * After return, callers should not read prior pointers from @p list.
+ *
+ * @param list
+ *   Pointer to a list previously used with truehear_audio_list_devices().
+ */
+void truehear_audio_free_device_list(
+    TruehearAudioDeviceInfoList *list);
+
+/* ============================================================================================== */
+/* Error Reporting                                                                                */
+/* ============================================================================================== */
+
+/**
+ * @brief Return a human-readable message for the most recent API failure.
+ *
+ * Use immediately after a function returns -1.
+ *
+ * @return
+ *   Library-owned const string pointer.
+ *   - Do NOT free
+ *   - Do NOT modify
+ *   - May be overwritten by subsequent API calls
+ *
+ * Example:
+ * @code
+ * if (truehear_audio_set_default_device(type, id) != 0) {
+ *     const char *err = truehear_audio_get_last_error();
+ *     fprintf(stderr, "truehear error: %s\n", err ? err : "(unknown)");
+ * }
+ * @endcode
+ */
+const char *truehear_audio_get_last_error(void);
+
+/* ============================================================================================== */
+/* End-to-End Example                                                                             */
+/* ============================================================================================== */
+/**
+ * @code
+ * #include <stdio.h>
+ * #include <string.h>
+ * #include "truehear_audio.h"
+ *
+ * // Demo: set playback default by substring match on device name.
+ * int set_playback_default_by_name(const char *needle) {
+ *     TruehearAudioDeviceInfoList list;
+ *     int rc = truehear_audio_list_devices(TRUEHEAR_AUDIO_DEVICE_TYPE_PLAYBACK, &list);
+ *     if (rc != 0) {
+ *         fprintf(stderr, "List failed: %s\n", truehear_audio_get_last_error());
+ *         return -1;
+ *     }
+ *
+ *     const char *selected_id = NULL;
+ *     for (int i = 0; i < list.count; ++i) {
+ *         const TruehearAudioDeviceInfo *d = &list.items[i];
+ *         if (d->name && strstr(d->name, needle) && d->id) {
+ *             selected_id = d->id;
+ *             break;
+ *         }
+ *     }
+ *
+ *     if (!selected_id) {
+ *         fprintf(stderr, "No matching playback device for '%s'\n", needle);
+ *         truehear_audio_free_device_list(&list);
+ *         return -1;
+ *     }
+ *
+ *     rc = truehear_audio_set_default_device(
+ *         TRUEHEAR_AUDIO_DEVICE_TYPE_PLAYBACK, selected_id);
+ *     if (rc != 0) {
+ *         fprintf(stderr, "Set default failed: %s\n", truehear_audio_get_last_error());
+ *         truehear_audio_free_device_list(&list);
+ *         return -1;
+ *     }
+ *
+ *     // Optional: also set communication default.
+ *     if (truehear_audio_set_default_communication_device(
+ *             TRUEHEAR_AUDIO_DEVICE_TYPE_PLAYBACK, selected_id) != 0) {
+ *         // Not fatal on platforms where unsupported.
+ *         fprintf(stderr, "Set communication default warning: %s\n",
+ *                 truehear_audio_get_last_error());
+ *     }
+ *
+ *     truehear_audio_free_device_list(&list);
+ *     return 0;
+ * }
+ * @endcode
+ */
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* TRUEHEAR_AUDIO_H */

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "truehear-audio-library-node",
+  "version": "1.0.0",
+  "description": "Native Node.js audio device listing and default-device switching library.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "prebuilds",
+    "include",
+    "src",
+    "binding.gyp",
+    "README.md",
+    "LICENSE"
+  ],
+  "gypfile": true,
+  "scripts": {
+    "install": "node-gyp-build",
+    "clean:dist": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "clean:prebuilds": "node -e \"require('fs').rmSync('prebuilds', { recursive: true, force: true })\"",
+    "clean:native": "node-gyp clean",
+    "build:native": "node-gyp rebuild",
+    "build:native:debug": "node-gyp rebuild --debug",
+    "build:ts": "npm run clean:dist && tsc -p tsconfig.lib.json",
+    "copy:prebuild": "node scripts/copy-prebuild.cjs",
+    "build:prebuild": "npm run clean:prebuilds && npm run build:native && npm run copy:prebuild",
+    "build": "npm run build:native && npm run build:ts",
+    "build:package": "npm run build:ts && npm run build:prebuild",
+    "prepack": "npm run build:package",
+    "typecheck": "tsc -b",
+    "test:native": "node node/tests/native.test.cjs",
+    "test:list": "tsx node/tests/list.devices.ts",
+    "test:set": "tsx node/tests/set.device.ts",
+    "test": "npm run test:native && npm run test:list",
+    "pack:check": "npm pack --dry-run",
+    "pack:local": "npm pack"
+  },
+  "keywords": [
+    "audio",
+    "device",
+    "windows",
+    "core-audio",
+    "wasapi",
+    "node-api",
+    "napi",
+    "native-addon",
+    "default-audio-device"
+  ],
+  "author": "@truehear team",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TrueHear/truehear-audio-library-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TrueHear/truehear-audio-library-node/issues"
+  },
+  "homepage": "https://github.com/TrueHear/truehear-audio-library-node#readme",
+  "dependencies": {
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "node-gyp": "^13.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.0.0"
+  }
+}