native-recorder-nodejs 1.0.1

package/CMakeLists.txt

@@ -0,0 +1,110 @@
+cmake_minimum_required(VERSION 3.15)
+project(NativeAudioSDK)
+
+# --- Configuration ---
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# --- Dependencies ---
+include_directories(${CMAKE_JS_INC})
+
+# node-addon-api
+# execute_process(COMMAND node -p "require('node-addon-api').include"
+#        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+#        OUTPUT_VARIABLE NODE_ADDON_API_DIR
+#        OUTPUT_STRIP_TRAILING_WHITESPACE)
+
+set(NODE_ADDON_API_DIR "${CMAKE_SOURCE_DIR}/node_modules/node-addon-api")
+include_directories(${NODE_ADDON_API_DIR})
+
+# --- Source Files ---
+set(ENGINE_SOURCES
+    native/Factory.cpp
+)
+
+# Platform specific sources
+if(WIN32)
+    list(APPEND ENGINE_SOURCES 
+        native/win/WASAPIEngine.cpp
+    )
+    add_definitions(-DNAPI_CPP_EXCEPTIONS -DWIN32_LEAN_AND_MEAN)
+elseif(APPLE)
+    set(CMAKE_OBJCXX_FLAGS "${CMAKE_OBJCXX_FLAGS} -fobjc-arc")
+    list(APPEND ENGINE_SOURCES 
+        native/mac/AVFEngine.mm
+        native/mac/SCKAudioCapture.mm
+    )
+    add_definitions(-DNAPI_CPP_EXCEPTIONS)
+endif()
+
+set(SOURCE_FILES
+    native/main.cpp
+    native/AudioController.cpp
+    ${ENGINE_SOURCES}
+)
+
+# --- Main Target (Node Addon) ---
+add_library(${PROJECT_NAME} SHARED ${SOURCE_FILES})
+set_target_properties(${PROJECT_NAME} PROPERTIES PREFIX "" SUFFIX ".node")
+
+if(APPLE)
+    target_compile_options(${PROJECT_NAME} PRIVATE -fobjc-arc)
+endif()
+
+# Link libraries
+target_link_libraries(${PROJECT_NAME} PRIVATE ${CMAKE_JS_LIB})
+
+if(WIN32)
+    target_link_libraries(${PROJECT_NAME} PRIVATE Ole32) # Example for Windows
+elseif(APPLE)
+    find_library(AVFOUNDATION_FRAMEWORK AVFoundation)
+    find_library(COREAUDIO_FRAMEWORK CoreAudio)
+    find_library(COREMEDIA_FRAMEWORK CoreMedia)
+    find_library(SCREENCAPTUREKIT_FRAMEWORK ScreenCaptureKit)
+    find_library(AUDIOTOOLBOX_FRAMEWORK AudioToolbox)
+    find_library(FOUNDATION_FRAMEWORK Foundation)
+    target_link_libraries(${PROJECT_NAME} PRIVATE ${AVFOUNDATION_FRAMEWORK} ${COREAUDIO_FRAMEWORK} ${COREMEDIA_FRAMEWORK} ${SCREENCAPTUREKIT_FRAMEWORK} ${AUDIOTOOLBOX_FRAMEWORK} ${FOUNDATION_FRAMEWORK})
+endif()
+
+# --- Testing (Catch2) ---
+option(BUILD_TESTS "Build unit tests" OFF)
+
+if(BUILD_TESTS)
+    include(FetchContent)
+    FetchContent_Declare(
+        Catch2
+        GIT_REPOSITORY https://github.com/catchorg/Catch2.git
+        GIT_TAG        v3.4.0
+    )
+    FetchContent_MakeAvailable(Catch2)
+
+    # Define test sources (exclude main.cpp which has N-API exports)
+    set(TEST_SOURCES
+        test/native/test_factory.cpp
+        ${ENGINE_SOURCES}
+    )
+
+    if(WIN32)
+        list(APPEND TEST_SOURCES test/native/test_wasapi.cpp)
+    elseif(APPLE)
+        list(APPEND TEST_SOURCES test/native/test_avf.cpp)
+    endif()
+
+    add_executable(NativeTests ${TEST_SOURCES})
+    if(APPLE)
+        target_compile_options(NativeTests PRIVATE -fobjc-arc)
+    endif()
+    target_link_libraries(NativeTests PRIVATE Catch2::Catch2WithMain)
+    
+    # Link platform libs to tests as well
+    if(WIN32)
+        target_link_libraries(NativeTests PRIVATE Ole32)
+    elseif(APPLE)
+        target_link_libraries(NativeTests PRIVATE ${AVFOUNDATION_FRAMEWORK} ${COREAUDIO_FRAMEWORK} ${COREMEDIA_FRAMEWORK} ${SCREENCAPTUREKIT_FRAMEWORK} ${AUDIOTOOLBOX_FRAMEWORK} ${FOUNDATION_FRAMEWORK})
+    endif()
+
+    enable_testing()
+    include(CTest)
+    include(Catch)
+    catch_discover_tests(NativeTests)
+endif()

package/README.md

@@ -0,0 +1,380 @@
+# Native Recorder for Node.js
+
+[![Build and Release](https://github.com/Yidadaa/Native-Recorder-NodeJS/actions/workflows/build.yml/badge.svg)](https://github.com/Yidadaa/Native-Recorder-NodeJS/actions/workflows/build.yml)
+[![npm version](https://badge.fury.io/js/native-recorder-nodejs.svg)](https://www.npmjs.com/package/native-recorder-nodejs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+High-performance, low-latency native audio recording SDK for Node.js. Supports both **microphone input** and **system audio capture (loopback)** on Windows and macOS.
+
+## Features
+
+- **Microphone Recording** - Capture audio from any input device
+- **System Audio Capture** - Record what's playing on your computer (loopback)
+- **Cross-Platform** - Windows (WASAPI) and macOS (AVFoundation + ScreenCaptureKit)
+- **High Performance** - Native C++ implementation with minimal latency
+- **Prebuilt Binaries** - No compilation required for most platforms
+- **Type Safe** - Full TypeScript support
+
+## Platform Support
+
+| Platform      | Architecture | Input (Mic) | Output (System Audio)   |
+| ------------- | ------------ | ----------- | ----------------------- |
+| Windows 10/11 | x64          | Supported   | Supported (per-device)  |
+| Windows 10/11 | ia32         | Supported   | Supported (per-device)  |
+| macOS 12.3+   | arm64        | Supported   | Supported (system-wide) |
+| macOS 12.3+   | x64          | Supported   | Supported (system-wide) |
+
+### Platform Differences
+
+| Feature        | Windows               | macOS                          |
+| -------------- | --------------------- | ------------------------------ |
+| Input Devices  | Multiple (WASAPI)     | Multiple (AVFoundation)        |
+| Output Devices | Multiple (per-device) | Single "System Audio" device   |
+| Permissions    | None required         | Microphone + Screen Recording  |
+| Min OS Version | Windows 10+           | macOS 12.3+ (for system audio) |
+
+## Installation
+
+```bash
+npm install native-recorder-nodejs
+```
+
+Prebuilt binaries are available for most platforms. If a prebuild is not available, the package will compile from source (requires CMake and a C++ compiler).
+
+## Quick Start
+
+```typescript
+import { AudioRecorder, SYSTEM_AUDIO_DEVICE_ID } from 'native-recorder-nodejs';
+import * as fs from 'fs';
+
+const recorder = new AudioRecorder();
+
+// List available devices
+const inputs = AudioRecorder.getDevices('input');
+const outputs = AudioRecorder.getDevices('output');
+
+console.log('Microphones:', inputs);
+console.log('Output devices:', outputs);
+
+// Record from default microphone
+const mic = inputs.find(d => d.isDefault);
+if (mic) {
+  const output = fs.createWriteStream('recording.raw');
+  
+  recorder.on('data', (buffer) => {
+    output.write(buffer);
+  });
+  
+  recorder.on('error', (error) => {
+    console.error('Recording error:', error);
+  });
+  
+  await recorder.start({
+    deviceType: 'input',
+    deviceId: mic.id
+  });
+  
+  // Record for 5 seconds
+  setTimeout(async () => {
+    await recorder.stop();
+    output.end();
+    console.log('Recording saved!');
+  }, 5000);
+}
+```
+
+### Record System Audio
+
+```typescript
+// Get system audio device
+const outputs = AudioRecorder.getDevices('output');
+const systemAudio = outputs.find(d => d.id === SYSTEM_AUDIO_DEVICE_ID) 
+                 || outputs.find(d => d.isDefault);
+
+if (systemAudio) {
+  await recorder.start({
+    deviceType: 'output',
+    deviceId: systemAudio.id
+  });
+}
+```
+
+## API Reference
+
+### `AudioRecorder`
+
+The main class for controlling audio recording.
+
+#### Constructor
+
+```typescript
+const recorder = new AudioRecorder();
+```
+
+#### Instance Methods
+
+##### `start(config: RecordingConfig): Promise<void>`
+
+Starts recording from the specified device.
+
+```typescript
+interface RecordingConfig {
+  deviceType: 'input' | 'output';  // Required
+  deviceId: string;                 // Required
+}
+
+await recorder.start({
+  deviceType: 'input',
+  deviceId: 'device-uuid'
+});
+```
+
+##### `stop(): Promise<void>`
+
+Stops the recording session.
+
+```typescript
+await recorder.stop();
+```
+
+#### Static Methods
+
+##### `getDevices(type?: DeviceType): AudioDevice[]`
+
+Lists available audio devices.
+
+```typescript
+interface AudioDevice {
+  id: string;           // Unique identifier
+  name: string;         // Human-readable name
+  type: 'input' | 'output';
+  isDefault: boolean;
+}
+
+const allDevices = AudioRecorder.getDevices();
+const microphones = AudioRecorder.getDevices('input');
+const outputs = AudioRecorder.getDevices('output');
+```
+
+##### `getDeviceFormat(deviceId: string): AudioFormat`
+
+Gets the audio format of a device.
+
+```typescript
+interface AudioFormat {
+  sampleRate: number;   // e.g., 48000
+  channels: number;     // 1 (mono) or 2 (stereo)
+  bitDepth: number;     // Output bit depth (16)
+  rawBitDepth: number;  // Native device bit depth
+}
+
+const format = AudioRecorder.getDeviceFormat(device.id);
+```
+
+##### `checkPermission(): PermissionStatus`
+
+Checks current permission status.
+
+```typescript
+interface PermissionStatus {
+  mic: boolean;     // Microphone permission
+  system: boolean;  // System audio permission
+}
+
+const status = AudioRecorder.checkPermission();
+```
+
+##### `requestPermission(type: 'mic' | 'system'): boolean`
+
+Requests permission for recording.
+
+```typescript
+const granted = AudioRecorder.requestPermission('mic');
+const systemGranted = AudioRecorder.requestPermission('system');
+```
+
+#### Events
+
+##### `'data'`
+
+Emitted when audio data is available.
+
+```typescript
+recorder.on('data', (buffer: Buffer) => {
+  // Raw PCM 16-bit LE audio data
+});
+```
+
+##### `'error'`
+
+Emitted when an error occurs.
+
+```typescript
+recorder.on('error', (error: Error) => {
+  console.error(error.message);
+});
+```
+
+### Constants
+
+```typescript
+// Special device ID for system-wide audio capture on macOS
+export const SYSTEM_AUDIO_DEVICE_ID = 'system';
+```
+
+## Audio Format
+
+The output is always:
+- **Format**: Raw PCM
+- **Bit Depth**: 16-bit signed integer
+- **Endianness**: Little Endian
+- **Sample Rate**: 48kHz on macOS (fixed), native device rate on Windows (commonly 44.1kHz or 48kHz)
+- **Channels**: Stereo on macOS (fixed), preserved from source on Windows
+
+### Playing Raw Audio
+
+You can play the recorded raw audio using FFplay:
+
+```bash
+ffplay -f s16le -ar 48000 -ch_layout stereo recording.raw
+```
+
+Or convert to WAV using FFmpeg:
+
+```bash
+ffmpeg -f s16le -ar 48000 -ac 2 -i recording.raw output.wav
+```
+
+## Permissions (macOS)
+
+On macOS, you need to grant permissions:
+
+1. **Microphone** - Required for input device recording
+2. **Screen Recording** - Required for system audio capture
+
+The SDK will automatically prompt for permissions when needed, or you can request them programmatically:
+
+```typescript
+const permissions = AudioRecorder.checkPermission();
+
+if (!permissions.mic) {
+  AudioRecorder.requestPermission('mic');
+}
+
+if (!permissions.system) {
+  AudioRecorder.requestPermission('system');
+}
+```
+
+## Error Handling
+
+| Error Code             | Description                                |
+| ---------------------- | ------------------------------------------ |
+| `DEVICE_NOT_FOUND`     | Specified device ID does not exist         |
+| `DEVICE_TYPE_MISMATCH` | Device ID doesn't match the specified type |
+| `PERMISSION_DENIED`    | Missing required system permission         |
+| `ALREADY_RECORDING`    | Recording session already active           |
+| `DEVICE_DISCONNECTED`  | Device was disconnected during recording   |
+
+## Building from Source
+
+### Prerequisites
+
+- Node.js 16+
+- CMake 3.15+
+- C++17 compiler
+  - Windows: Visual Studio 2019+ or MSVC Build Tools
+  - macOS: Xcode Command Line Tools
+
+### Build Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build native module
+npm run build:native
+
+# Build TypeScript
+npm run build:ts
+
+# Build everything
+npm run build
+
+# Run tests
+npm test
+```
+
+### Publishing
+
+```bash
+# Build prebuilt binaries for current platform
+npm run prebuild
+
+# Upload prebuilts to GitHub Release (requires GITHUB_TOKEN)
+npm run prebuild:upload
+
+# Publish to npm (prebuilts should be uploaded first)
+npm publish
+```
+
+### CI/CD with GitHub Actions
+
+The project uses GitHub Actions for automated builds and releases. The workflow is triggered by:
+
+| Trigger                        | Action                                                 |
+| ------------------------------ | ------------------------------------------------------ |
+| Push to `main`                 | Build and test on all platforms                        |
+| Pull Request to `main`         | Build and test on all platforms                        |
+| Push tag `v*` (e.g., `v1.0.0`) | Build, test, publish to npm, and create GitHub Release |
+
+**To release a new version:**
+
+```bash
+# 1. Update version in package.json
+npm version patch  # or minor, major
+
+# 2. Push the tag to trigger the release workflow
+git push origin main --tags
+```
+
+The CI will automatically:
+1. Build native modules for all platforms (macOS arm64/x64, Windows x64/ia32)
+2. Run tests on each platform
+3. Publish the package to npm with prebuilt binaries
+4. Create a GitHub Release with the native binaries attached
+
+> **Note**: Ensure `NPM_TOKEN` is configured in repository secrets for npm publishing.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│              Node.js Application                 │
+├─────────────────────────────────────────────────┤
+│              TypeScript Wrapper                  │
+├─────────────────────────────────────────────────┤
+│              N-API Binding Layer                 │
+├────────────────────┬────────────────────────────┤
+│   Windows          │         macOS              │
+│   (WASAPI)         │   (AVFoundation +          │
+│                    │    ScreenCaptureKit)       │
+└────────────────────┴────────────────────────────┘
+```
+
+For detailed architecture documentation, see [docs/architecture.md](docs/architecture.md).
+
+For complete API documentation, see [docs/api.md](docs/api.md).
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- [node-addon-api](https://github.com/nodejs/node-addon-api) - N-API C++ wrapper
+- [cmake-js](https://github.com/nicknisi/cmake-js) - CMake build system for Node.js addons

package/dist/bindings.d.ts

@@ -0,0 +1,2 @@
+declare const bindings: any;
+export default bindings;

package/dist/bindings.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = require("path");
+const fs_1 = require("fs");
+function getBinding() {
+    const moduleName = "NativeAudioSDK.node";
+    // Try prebuild first (installed via npm)
+    const prebuildsDir = (0, path_1.join)(__dirname, "..", "prebuilds");
+    const platform = process.platform;
+    const arch = process.arch;
+    // prebuild-install stores binaries in: prebuilds/{platform}-{arch}/
+    const prebuildPath = (0, path_1.join)(prebuildsDir, `${platform}-${arch}`, moduleName);
+    if ((0, fs_1.existsSync)(prebuildPath)) {
+        return require(prebuildPath);
+    }
+    // Fallback to local build (development)
+    const localPath = (0, path_1.join)(__dirname, "..", "build", "Release", moduleName);
+    if ((0, fs_1.existsSync)(localPath)) {
+        return require(localPath);
+    }
+    // Final fallback for different build configurations
+    const debugPath = (0, path_1.join)(__dirname, "..", "build", "Debug", moduleName);
+    if ((0, fs_1.existsSync)(debugPath)) {
+        return require(debugPath);
+    }
+    throw new Error(`Could not find native module ${moduleName}. ` +
+        `Tried:\n  - ${prebuildPath}\n  - ${localPath}\n  - ${debugPath}\n` +
+        `Please run 'npm run build:native' or reinstall the package.`);
+}
+const bindings = getBinding();
+exports.default = bindings;

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+import { EventEmitter } from "events";
+/**
+ * Special device ID for system-wide audio capture (macOS)
+ */
+export declare const SYSTEM_AUDIO_DEVICE_ID = "system";
+/**
+ * Device type classification
+ */
+export type DeviceType = "input" | "output";
+/**
+ * Permission type for requesting access
+ */
+export type PermissionType = "mic" | "system";
+/**
+ * Permission status for audio recording
+ */
+export interface PermissionStatus {
+    /** Microphone permission granted */
+    mic: boolean;
+    /** System audio permission granted (screen recording permission on macOS) */
+    system: boolean;
+}
+/**
+ * Represents an audio device
+ */
+export interface AudioDevice {
+    /** Unique device identifier (always has a value) */
+    id: string;
+    /** Human-readable device name */
+    name: string;
+    /** Device type: 'input' for microphones, 'output' for system audio */
+    type: DeviceType;
+    /** Whether this is the default device for its type */
+    isDefault: boolean;
+}
+/**
+ * Audio format information
+ */
+export interface AudioFormat {
+    /** Sample rate in Hz (e.g., 44100, 48000) */
+    sampleRate: number;
+    /** Number of channels (1 = Mono, 2 = Stereo) */
+    channels: number;
+    /** Output bit depth (currently fixed at 16) */
+    bitDepth: number;
+    /** Native device bit depth */
+    rawBitDepth: number;
+}
+/**
+ * Recording configuration
+ * Both deviceType and deviceId are required for consistent cross-platform behavior
+ */
+export interface RecordingConfig {
+    /**
+     * Type of device to record from.
+     * - 'input': Record from microphone
+     * - 'output': Record system audio (loopback)
+     */
+    deviceType: DeviceType;
+    /**
+     * Device ID to record from (obtained from getDevices()).
+     * Every device has a valid ID - use the ID from the device list.
+     */
+    deviceId: string;
+}
+export declare class AudioRecorder extends EventEmitter {
+    private controller;
+    private isRecording;
+    constructor();
+    /**
+     * Starts the recording session.
+     * @param config Configuration object with deviceType and deviceId (both required)
+     */
+    start(config: RecordingConfig): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Lists available audio devices.
+     * @param type Optional filter by device type
+     * @returns Array of AudioDevice objects (all with valid id values)
+     */
+    static getDevices(type?: DeviceType): AudioDevice[];
+    /**
+     * Gets the audio format of a specific device.
+     * @param deviceId The device ID to query
+     * @returns AudioFormat object
+     */
+    static getDeviceFormat(deviceId: string): AudioFormat;
+    /**
+     * Checks the current permission status for audio recording.
+     * On Windows, always returns { mic: true, system: true } as no explicit permissions are required.
+     * On macOS, checks actual permission status for microphone and screen recording.
+     * @returns PermissionStatus object with mic and system boolean fields
+     */
+    static checkPermission(): PermissionStatus;
+    /**
+     * Requests permission for the specified type.
+     * On Windows, always returns true as no explicit permissions are required.
+     * On macOS, prompts the user to grant the requested permission.
+     * @param type The permission type to request: 'mic' for microphone, 'system' for system audio
+     * @returns true if permission was granted, false otherwise
+     */
+    static requestPermission(type: PermissionType): boolean;
+}
+export declare const nativeBindings: any;

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/typescript/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,QAAQ,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC"}