@mikrojs/native 0.15.0-pr-243.20260613121220 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.15.0-pr-243.20260613121220",
+  "version": "0.15.0",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -56,6 +56,7 @@
     "./runtime/http/server-impl": "./runtime/http/server-impl.ts",
     "./runtime/fs/types": "./runtime/fs/types.ts",
     "./runtime/i2c/types": "./runtime/i2c/types.ts",
+    "./runtime/i2s/types": "./runtime/i2s/types.ts",
     "./runtime/inspect/types": "./runtime/inspect/types.ts",
     "./runtime/kv/shared": "./runtime/kv/shared.ts",
     "./runtime/kv/types": "./runtime/kv/types.ts",
@@ -83,7 +84,7 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.15.0-pr-243.20260613121220+eb4e93b"
+    "@mikrojs/quickjs": "0.15.0"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",

package/runtime/i2s/i2s.ts

@@ -0,0 +1,46 @@
+import * as native from 'native:mikro/i2s'
+
+import type {Result} from '../result/types.js'
+import type {
+  I2sBase,
+  I2sError,
+  I2sPdmRxOptions,
+  I2sSamples,
+  I2sStdRxOptions,
+  I2sStdTxOptions,
+  I2sStdTxRxOptions,
+} from './types.js'
+
+/**
+ * @public
+ */
+export class I2s implements I2sBase {
+  #native: native.I2s
+
+  constructor(port: number, options: I2sStdTxRxOptions)
+  constructor(port: number, options: I2sStdTxOptions)
+  constructor(port: number, options: I2sStdRxOptions)
+  constructor(port: number, options: I2sPdmRxOptions)
+  constructor(
+    port: number,
+    options: I2sStdTxRxOptions | I2sStdTxOptions | I2sStdRxOptions | I2sPdmRxOptions,
+  ) {
+    this.#native = new native.I2s(port, options)
+  }
+
+  begin(): Result<void, I2sError> {
+    return this.#native.begin()
+  }
+
+  end(): Result<void, I2sError> {
+    return this.#native.end()
+  }
+
+  write(data: I2sSamples | Uint8Array): Promise<Result<void, I2sError>> {
+    return this.#native.write(data)
+  }
+
+  capture(frames: number, options?: {gainBits?: number}): Result<Int16Array, I2sError> {
+    return this.#native.capture(frames, options)
+  }
+}

package/runtime/i2s/types.ts

@@ -0,0 +1,139 @@
+import type {Result} from '../result/types.js'
+
+/**
+ * Samples crossing the I2S boundary. `Int16Array` when configured 16-bit,
+ * `Int32Array` when 32-bit. Stereo data is interleaved `L,R,L,R…`.
+ *
+ * @public
+ */
+export type I2sSamples = Int16Array | Int32Array
+
+/**
+ * @public
+ */
+export interface I2sStdBaseOptions {
+  mode?: 'std'
+  /** Sample rate in Hz (e.g. 16000, 44100). */
+  sampleRate: number
+  /** Bits per sample. Default 16. */
+  bitsPerSample?: 16 | 32
+  /** Slot mode. Default 'stereo'. */
+  channels?: 'mono' | 'stereo'
+  /** Bit clock (SCK) pin. */
+  bclk: number
+  /** Word select / LR clock pin. */
+  ws: number
+  /** Frames per DMA buffer. Audio-tuned default; raise for fewer wakeups, lower for less latency. */
+  dmaFrames?: number
+  /** Number of DMA buffers. Audio-tuned default. */
+  dmaBuffers?: number
+}
+
+/**
+ * @public
+ */
+export interface I2sStdTxOptions extends I2sStdBaseOptions {
+  /** Data-out pin (to an amp/DAC). */
+  dout: number
+  din?: undefined
+}
+
+/**
+ * @public
+ */
+export interface I2sStdRxOptions extends I2sStdBaseOptions {
+  /** Data-in pin (from a mic/codec). */
+  din: number
+  dout?: undefined
+}
+
+/**
+ * @public
+ */
+export interface I2sStdTxRxOptions extends I2sStdBaseOptions {
+  dout: number
+  din: number
+}
+
+/**
+ * PDM is receive-only and chip-dependent (classic ESP32 and S3 support it; some
+ * C/H-series targets do not). On unsupported chips `begin()` returns
+ * `ChannelInitFailed`.
+ *
+ * @public
+ */
+export interface I2sPdmRxOptions {
+  mode: 'pdm'
+  sampleRate: number
+  bitsPerSample?: 16 | 32
+  /** Default 'mono'. */
+  channels?: 'mono' | 'stereo'
+  /** PDM clock pin. */
+  clk: number
+  /** PDM data-in pin. */
+  din: number
+  dmaFrames?: number
+  dmaBuffers?: number
+}
+
+/**
+ * @public
+ */
+export type I2sError =
+  | {name: 'ChannelInitFailed'; message: string}
+  | {name: 'InvalidParam'; message: string}
+  | {name: 'WriteFailed'; message: string}
+  | {name: 'ReadFailed'; message: string}
+  | {name: 'NotStarted'}
+  | {name: 'QueueFull'}
+  | {name: 'NoRxPin'}
+  | {name: 'NoTxPin'}
+
+/**
+ * @public
+ */
+export interface I2sTx {
+  /**
+   * Queue samples for transmission. Resolves once the chunk has been handed to
+   * DMA. A small bounded queue double-buffers for gapless playback; producing
+   * faster than realtime resolves `err(QueueFull)`. Element width must match
+   * `bitsPerSample` (or be a raw `Uint8Array`); a mismatch is `err(InvalidParam)`.
+   */
+  write(data: I2sSamples | Uint8Array): Promise<Result<void, I2sError>>
+}
+
+/**
+ * @public
+ */
+export interface I2sRx {
+  /**
+   * Blocking bulk capture: read exactly `frames` mono samples (from a 32-bit
+   * mono channel), converted to 16-bit PCM in C and returned as one packed
+   * `Int16Array`. `gainBits` left-shifts each sample by that many bits (clamped)
+   * for a louder result. No per-chunk allocation or async machinery, so it can
+   * sustain high sample rates. It BLOCKS the event loop for ~`frames`/sample-rate
+   * while it drains the DMA; size `frames` to trade throughput against how often
+   * the loop runs between captures, and use it only in a dedicated capture/stream
+   * loop, not where timers and other async must stay responsive.
+   */
+  capture(frames: number, options?: {gainBits?: number}): Result<Int16Array, I2sError>
+}
+
+/**
+ * @public
+ */
+export interface I2sBase {
+  begin(): Result<void, I2sError>
+  end(): Result<void, I2sError>
+}
+
+/**
+ * @public
+ */
+export declare const I2s: {
+  prototype: I2sBase
+  new (port: number, options: I2sStdTxRxOptions): I2sBase & I2sTx & I2sRx
+  new (port: number, options: I2sStdTxOptions): I2sBase & I2sTx
+  new (port: number, options: I2sStdRxOptions): I2sBase & I2sRx
+  new (port: number, options: I2sPdmRxOptions): I2sBase & I2sRx
+}

package/runtime/internal.d.ts

@@ -518,3 +518,37 @@ declare module 'native:mikro/udp' {
 
   export function bind(opts: BindOptions): Promise<Result<NativeUdpSocket, UdpError>>
 }
+
+declare module 'native:mikro/i2s' {
+  import type {I2sError, I2sSamples} from '@mikrojs/native/runtime/i2s/types'
+  import type {Result} from 'mikro/result'
+
+  export interface I2sNativeOptions {
+    mode?: 'std' | 'pdm'
+    sampleRate: number
+    bitsPerSample?: 16 | 32
+    channels?: 'mono' | 'stereo'
+    bclk?: number
+    ws?: number
+    clk?: number
+    dout?: number
+    din?: number
+    dmaFrames?: number
+    dmaBuffers?: number
+  }
+
+  export declare const I2s: {
+    prototype: I2s
+    new (port: number, options: I2sNativeOptions): I2s
+  }
+
+  export interface I2s {
+    begin(): Result<void, I2sError>
+
+    end(): Result<void, I2sError>
+
+    write(data: I2sSamples | Uint8Array): Promise<Result<void, I2sError>>
+
+    capture(frames: number, options?: {gainBits?: number}): Result<Int16Array, I2sError>
+  }
+}