@node-webrtc-rust/bindings 0.1.5 → 0.3.2

package/README.md

@@ -50,15 +50,62 @@ This produces a `node-webrtc-rust.<platform>.node` file in the current directory
 
 Set `WEBRTC_DEBUG=1` (or pass `debug: true` in `JsRTCConfiguration`) to emit `[webrtc-debug]` lines from native bindings and the Rust core. See the root README for details.
 
-## How it works
+## How native loading works
 
-The `index.js` loader resolves the native binding in this order:
+The root `@node-webrtc-rust/bindings` package ships **no binary** — only `index.js`, `index.d.ts`, and loader logic. The compiled addon lives in separate platform packages listed as **`optionalDependencies`**.
 
-1. Try requiring the platform-specific npm package (e.g., `@node-webrtc-rust/bindings-darwin-arm64`)
-2. Try loading a local `.node` file matching the current platform (dev builds)
-3. Try loading `node-webrtc-rust.node` (generic local build)
+### At `npm install`
 
-If none succeed, an error is thrown with instructions.
+The matching platform package is **installed during `npm install`**, not downloaded when your app first runs. Runtime `require()` only loads what is already in `node_modules`.
+
+When you install `@node-webrtc-rust/bindings`, npm:
+
+1. Installs the root package (loader only — no `.node`).
+2. **Attempts each `optionalDependency`** (e.g. `bindings-darwin-arm64`, `bindings-linux-x64-gnu`, …).
+3. Keeps only packages whose `"os"` / `"cpu"` fields match your machine; others are skipped.
+4. Does **not** fail the install if a non-matching or unavailable optional package is skipped — that is what “optional” means.
+
+On macOS arm64 you typically get:
+
+```text
+node_modules/@node-webrtc-rust/bindings/          ← loader (index.js)
+node_modules/@node-webrtc-rust/bindings-darwin-arm64/
+  node-webrtc-rust.darwin-arm64.node              ← actual native addon
+```
+
+Each platform package is a thin wrapper: its `"main"` field points directly at the `.node` file, so `require('@node-webrtc-rust/bindings-darwin-arm64')` loads the native module.
+
+**When the binary might be missing after install:**
+
+| Situation | Result |
+| --- | --- |
+| Normal install on a supported platform | Matching optional package is present |
+| `npm install --omit=optional` | No platform package — runtime fails unless a local `.node` exists |
+| Unsupported OS/arch | No matching optional package |
+| Publish/version mismatch for the optional pkg | Install may succeed; `require()` fails at runtime |
+
+### At runtime (`require('@node-webrtc-rust/bindings')`)
+
+`index.js` (auto-generated by NAPI-RS) picks the binary for the current process:
+
+1. **Detect platform** — `process.platform`, `process.arch`, and on Linux whether the libc is musl or glibc (`isMusl()`).
+2. **Local dev fallback** — if `node-webrtc-rust.<platform>.node` sits next to `index.js` (from `npm run build:local`), `require` that file directly.
+3. **Published path** — otherwise `require` the matching optional package (e.g. `@node-webrtc-rust/bindings-linux-x64-gnu`).
+4. **Re-export** — bind NAPI exports (`JsPeerConnection`, `JsConferenceRoom`, …) onto `module.exports`.
+
+If both paths fail, Node throws with the underlying `loadError`.
+
+```mermaid
+flowchart TD
+  A["require('@node-webrtc-rust/bindings')"] --> B[index.js]
+  B --> C{platform + arch + libc?}
+  C --> D{local .node beside index.js?}
+  D -->|yes| E["require('./node-webrtc-rust.*.node')"]
+  D -->|no| F["require('@node-webrtc-rust/bindings-…')"]
+  F --> G["platform pkg main → *.node"]
+  E --> H[Re-export NAPI symbols]
+  G --> H
+```
 
 ### TypeScript note
 

package/index.d.ts

@@ -72,6 +72,17 @@ export interface JsRtcConfiguration {
   iceTransportPolicy?: string
   debug?: boolean
 }
+/** Offer options (W3C `RTCOfferOptions` subset). */
+export interface JsRtcOfferOptions {
+  iceRestart?: boolean
+  voiceActivityDetection?: boolean
+  offerToReceiveAudio?: boolean
+  offerToReceiveVideo?: boolean
+}
+/** Answer options (W3C `RTCAnswerOptions` subset). */
+export interface JsRtcAnswerOptions {
+  voiceActivityDetection?: boolean
+}
 /** Session description exposed to JavaScript. */
 export interface JsRtcSessionDescription {
   type: string
@@ -92,6 +103,91 @@ export interface JsRtcDataChannelInit {
   protocol?: string
   negotiated?: number
 }
+/** Init options for {@link RTCPeerConnection.addTransceiver}. */
+export interface JsRtcRtpTransceiverInit {
+  direction?: string
+}
+export const enum JsEventDeliveryMode {
+  Callback = 'callback',
+  Stream = 'stream',
+  Both = 'both'
+}
+export interface JsEventsConfig {
+  mode?: JsEventDeliveryMode
+}
+export interface JsBargeInConfig {
+  enabled?: boolean
+  useVad?: boolean
+  flushTts?: boolean
+}
+export const enum JsVadSampleRate {
+  Hz8000 = '8000',
+  Hz16000 = '16000'
+}
+export interface JsVadConfig {
+  enabled?: boolean
+  provider?: string
+  threshold?: number
+  minSpeechDurationMs?: number
+  minSilenceDurationMs?: number
+  speechPadMs?: number
+  sampleRate?: JsVadSampleRate
+  bargeIn?: JsBargeInConfig
+  gateStt?: boolean
+  gateSttOpenOnPending?: boolean
+  sttGateHoldMs?: number
+}
+export const enum JsSttVendor {
+  Openai = 'openai',
+  Deepgram = 'deepgram',
+  Google = 'google',
+  Assemblyai = 'assemblyai',
+  LocalSherpa = 'local-sherpa',
+  Mock = 'mock'
+}
+export const enum JsTtsVendor {
+  Openai = 'openai',
+  Elevenlabs = 'elevenlabs',
+  Google = 'google',
+  Cartesia = 'cartesia',
+  LocalSherpa = 'local-sherpa',
+  Mock = 'mock'
+}
+export interface JsSttConfig {
+  provider: JsSttVendor
+  model?: string
+  modelPath?: string
+  language?: string
+  apiKey?: string
+}
+export interface JsTtsConfig {
+  provider: JsTtsVendor
+  model?: string
+  modelPath?: string
+  voice?: string
+  apiKey?: string
+}
+export interface JsVoiceAgentConfig {
+  vad?: JsVadConfig
+  events?: JsEventsConfig
+  stt?: JsSttConfig
+  tts?: JsTtsConfig
+}
+export const enum JsSpeechEventType {
+  UserSpeakingStart = 'user_speaking_start',
+  UserSpeakingEnd = 'user_speaking_end',
+  UserSpeechPartial = 'user_speech_partial',
+  UserSpeechFinal = 'user_speech_final',
+  AgentSpeakingStart = 'agent_speaking_start',
+  AgentSpeakingEnd = 'agent_speaking_end',
+  BargeIn = 'barge_in',
+  Error = 'error'
+}
+export interface JsSpeechEvent {
+  eventType: JsSpeechEventType
+  text?: string
+  error?: string
+}
 export declare function version(): string
 /** One conference room with participant and mixing controls. */
 export declare class JsConferenceRoom {
@@ -146,18 +242,22 @@ export declare class JsRtcDataChannel {
   bufferedAmount(): Promise<number>
   send(data: string | Buffer): Promise<void>
   close(): Promise<void>
+  setBufferedAmountLowThreshold(threshold: number): void
+  setOnBufferedAmountLow(callback: (...args: any[]) => any): void
   setOnOpen(callback: (...args: any[]) => any): void
   setOnMessage(callback: (...args: any[]) => any): void
   setOnClose(callback: (...args: any[]) => any): void
   setOnError(callback: (...args: any[]) => any): void
 }
-/** Media stream track exposed to JavaScript (stub). */
+/** Media stream track exposed to JavaScript. */
 export declare class JsMediaStreamTrack {
   get id(): string
   get kind(): string
   get streamId(): string
   get enabled(): boolean
   set enabled(enabled: boolean)
+  /** Decodes the next inbound Opus RTP packet to stereo PCM (remote audio only). */
+  readSample(): Promise<Buffer>
 }
 /** Media stream exposed to JavaScript (stub). */
 export declare class JsMediaStream {
@@ -172,7 +272,7 @@ export declare class JsLocalAudioTrack {
   get streamId(): string
   get enabled(): boolean
   set enabled(enabled: boolean)
-  /** Writes a PCM audio frame to the track. */
+  /** Writes interleaved stereo PCM; encoded to the negotiated RTP codec before send. */
   writeSample(data: Buffer, durationMs: number): Promise<void>
 }
 /** WebRTC peer connection exposed to JavaScript. */
@@ -182,15 +282,24 @@ export declare class JsPeerConnection {
   get iceConnectionState(): string
   get iceGatheringState(): string
   get signalingState(): string
-  createOffer(): Promise<JsRtcSessionDescription>
-  createAnswer(): Promise<JsRtcSessionDescription>
+  createOffer(options?: JsRtcOfferOptions | undefined | null): Promise<JsRtcSessionDescription>
+  createAnswer(options?: JsRtcAnswerOptions | undefined | null): Promise<JsRtcSessionDescription>
   setLocalDescription(desc: JsRtcSessionDescription): Promise<void>
   setRemoteDescription(desc: JsRtcSessionDescription): Promise<void>
   addIceCandidate(candidate: JsRtcIceCandidate): Promise<void>
-  addTrack(track: JsLocalAudioTrack): Promise<void>
+  addTrack(track: JsLocalAudioTrack): Promise<JsRtpSender>
+  removeTrack(sender: JsRtpSender): Promise<void>
+  addTransceiver(kind?: string | undefined | null, track?: JsLocalAudioTrack | undefined | null, init?: JsRTCRtpTransceiverInit | undefined | null): Promise<JsRtpTransceiver>
+  getTransceivers(): Promise<Array<JsRtpTransceiver>>
+  getSenders(): Promise<Array<JsRtpSender>>
+  getReceivers(): Promise<Array<JsRtpReceiver>>
   createDataChannel(label: string, options?: JsRtcDataChannelInit | undefined | null): Promise<JsRtcDataChannel>
   close(): Promise<void>
   gatheringComplete(): Promise<void>
+  setConfiguration(config: JsRtcConfiguration): Promise<void>
+  getConfiguration(): Promise<JsRtcConfiguration>
+  restartIce(): Promise<void>
+  getStats(): Promise<string>
   localDescription(): Promise<JsRtcSessionDescription | null>
   remoteDescription(): Promise<JsRtcSessionDescription | null>
   setOnIceCandidate(callback: (...args: any[]) => any): void
@@ -198,5 +307,45 @@ export declare class JsPeerConnection {
   setOnDataChannel(callback: (...args: any[]) => any): void
   setOnConnectionStateChange(callback: (...args: any[]) => any): void
   setOnIceConnectionStateChange(callback: (...args: any[]) => any): void
+  setOnIceGatheringStateChange(callback: (...args: any[]) => any): void
+  setOnSignalingStateChange(callback: (...args: any[]) => any): void
   setOnNegotiationNeeded(callback: (...args: any[]) => any): void
 }
+/** RTP receiver leg of an {@link RTCRtpTransceiver}. */
+export declare class JsRtpReceiver {
+  get id(): string
+  get kind(): string
+}
+/** RTP sender returned from {@link RTCPeerConnection.addTrack}. */
+export declare class JsRtpSender {
+  get id(): string
+  /** Replaces the outbound audio track without renegotiation. */
+  replaceTrack(track?: JsLocalAudioTrack | undefined | null): Promise<void>
+}
+/** Unified Plan transceiver (sender + receiver pair). */
+export declare class JsRtpTransceiver {
+  get mid(): string | null
+  get direction(): string
+  get currentDirection(): string | null
+  get kind(): string
+  get stopped(): boolean
+  get sender(): JsRtpSender
+  get receiver(): JsRtpReceiver
+  setDirection(direction: string): Promise<void>
+  stop(): Promise<void>
+}
+/** Voice agent with VAD, STT/TTS orchestration for one peer connection session. */
+export declare class JsVoiceAgent {
+  constructor(config?: JsVoiceAgentConfig | undefined | null)
+  /** Attaches outbound local audio track for TTS injection. */
+  attach(outboundTrack: JsLocalAudioTrack): Promise<void>
+  start(): Promise<void>
+  stop(): Promise<void>
+  sendTextToTts(text: string): Promise<void>
+  flushTts(): Promise<void>
+  /** Pull the next speech event for async stream consumption. */
+  pullSpeechEvent(): Promise<JsSpeechEvent | null>
+  setOnSpeechEvent(callback: (...args: any[]) => any): void
+  /** Processes one inbound PCM frame (48 kHz stereo) through VAD/STT. */
+  processInboundPcm(data: Buffer, durationMs: number): Promise<void>
+}

package/index.js

@@ -310,14 +310,42 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { JsConferenceRoom, JsConferenceServer, JsMuteScope, JsRtcDataChannel, JsMediaStreamTrack, JsMediaStream, JsLocalAudioTrack, JsPeerConnection, version } = nativeBinding
+const {
+  JsConferenceRoom,
+  JsConferenceServer,
+  JsEventDeliveryMode,
+  JsLocalAudioTrack,
+  JsMediaStream,
+  JsMediaStreamTrack,
+  JsMuteScope,
+  JsPeerConnection,
+  JsRtcDataChannel,
+  JsRtpReceiver,
+  JsRtpSender,
+  JsRtpTransceiver,
+  JsSpeechEventType,
+  JsSttVendor,
+  JsTtsVendor,
+  JsVadSampleRate,
+  JsVoiceAgent,
+  version,
+} = nativeBinding
 
 module.exports.JsConferenceRoom = JsConferenceRoom
 module.exports.JsConferenceServer = JsConferenceServer
-module.exports.JsMuteScope = JsMuteScope
-module.exports.JsRtcDataChannel = JsRtcDataChannel
-module.exports.JsMediaStreamTrack = JsMediaStreamTrack
-module.exports.JsMediaStream = JsMediaStream
+module.exports.JsEventDeliveryMode = JsEventDeliveryMode
 module.exports.JsLocalAudioTrack = JsLocalAudioTrack
+module.exports.JsMediaStream = JsMediaStream
+module.exports.JsMediaStreamTrack = JsMediaStreamTrack
+module.exports.JsMuteScope = JsMuteScope
 module.exports.JsPeerConnection = JsPeerConnection
+module.exports.JsRtcDataChannel = JsRtcDataChannel
+module.exports.JsRtpReceiver = JsRtpReceiver
+module.exports.JsRtpSender = JsRtpSender
+module.exports.JsRtpTransceiver = JsRtpTransceiver
+module.exports.JsSpeechEventType = JsSpeechEventType
+module.exports.JsSttVendor = JsSttVendor
+module.exports.JsTtsVendor = JsTtsVendor
+module.exports.JsVadSampleRate = JsVadSampleRate
+module.exports.JsVoiceAgent = JsVoiceAgent
 module.exports.version = version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node-webrtc-rust/bindings",
-  "version": "0.1.5",
+  "version": "0.3.2",
   "description": "NAPI-RS native bindings for node-webrtc-rust — WebRTC peer connections, data channels, and conference audio mixing",
   "keywords": [
     "webrtc",
@@ -58,13 +58,12 @@
     "@napi-rs/cli": "^2.18.0"
   },
   "optionalDependencies": {
-    "@node-webrtc-rust/bindings-win32-x64-msvc": "0.1.5",
-    "@node-webrtc-rust/bindings-darwin-x64": "0.1.5",
-    "@node-webrtc-rust/bindings-linux-x64-gnu": "0.1.5",
-    "@node-webrtc-rust/bindings-darwin-arm64": "0.1.5",
-    "@node-webrtc-rust/bindings-linux-arm64-gnu": "0.1.5",
-    "@node-webrtc-rust/bindings-linux-arm64-musl": "0.1.4",
-    "@node-webrtc-rust/bindings-linux-x64-musl": "0.1.5"
+    "@node-webrtc-rust/bindings-win32-x64-msvc": "0.3.2",
+    "@node-webrtc-rust/bindings-darwin-x64": "0.3.2",
+    "@node-webrtc-rust/bindings-linux-x64-gnu": "0.3.2",
+    "@node-webrtc-rust/bindings-darwin-arm64": "0.3.2",
+    "@node-webrtc-rust/bindings-linux-arm64-gnu": "0.3.2",
+    "@node-webrtc-rust/bindings-linux-x64-musl": "0.3.2"
   },
   "engines": {
     "node": ">=18"