node-web-audio-api 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,8 +1,29 @@
-## v0.4.0
+## v0.8.0
+
+- Implement MediaDevices enumerateDeviaces and getUserMedia
+- Use jack as default output if exists on linux
+
+## v0.7.0
+
+- Improve readme & doc
+- Fix AudioParam method names
+
+## v0.6.0 - Feb 2023
+
+- Basic support for mediaDevices & MediaStreamAudioSourceNode
+- Add bindings to ConvolverNode, AnalyserNode & Panner nodes
+- Update upstream crate to v0.26
+
+## v0.5.0 - Dec 2022
+
+- Implement AudioParam#setValueCurveAtTime
+- Offline context constructor 
+
+## v0.4.0 - Nov 2022
 
 - Implement offline audio context
-- Update web-audio-api-rs to v0.24.0 
-- Implement `audio_node.disconnect()`
+- Update upstream crate to v0.24 
+- Implement AudioNode#disconnect
 - Properly support ESM
 - Limit number of online contexts to 1 on Linux
 - Force latencyHint to 'playback' if not manually set on RPi

package/README.md

@@ -1,6 +1,13 @@
-# `node-web-audio-api`
+# Node Web Audio API
 
-> Nodejs bindings for [`orottier/web-audio-api-rs`](https://github.com/orottier/web-audio-api-rs/) using [`napi-rs`](https://github.com/napi-rs/napi-rs/)
+[![npm version](https://badge.fury.io/js/node-web-audio-api.svg)](https://badge.fury.io/js/node-web-audio-api)
+
+Node.js bindings for the Rust implementation of the Web Audio API Specification
+
+The goal of this library is to provide an implementation that is both efficient and _exactly_ matches the browsers' API.
+
+- see [`orottier/web-audio-api-rs`](https://github.com/orottier/web-audio-api-rs/) for the "real" audio guts
+- use [`napi-rs`](https://github.com/napi-rs/napi-rs/) for the Node.js bindings
 
 ## Install
 
@@ -8,10 +15,12 @@
 npm install [--save] node-web-audio-api
 ```
 
-## Example
+## Example Use
 
 ```js
 import { AudioContext, OscillatorNode, GainNode } from 'node-web-audio-api';
+// or using old fashionned commonjs syntax:
+// const { AudioContext, OscillatorNode, GainNode } = require('node-web-audio-api');
 
 const audioContext = new AudioContext();
 
@@ -33,54 +42,52 @@ setInterval(() => {
 }, 80);
 ```
 
-or using with old fashionned commonjs syntax
+### Running the Examples
 
-```js
-const { AudioContext, OscillatorNode, GainNode } = require('node-web-audio-api');
+To run all examples locally on your machine you will need to:
 
-const audioContext = new AudioContext();
-//...
+1. Install Rust toolchain
+```sh
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
 
-## Caveats
-
-- Currently the library does not provide any way of chosing the output interface, system default interface will be used. As the spec and web-audio-api evolve evolve, thus should change in the future see [https://github.com/orottier/web-audio-api-rs/issues/216](https://github.com/orottier/web-audio-api-rs/issues/216)
-- On Linux systems, the audio backend is Alsa, which limits the number of online
-AudioContext to 1. This is subject to change in the future.
-
-### Raspberry Pi
-
-On Raspberry Pi, the default render quantum size (128) is too small and underruns 
-occurs frequently. To prevent that, if you do not explicitely provide a latency hint
-in the AudioContext options, the value is automatically set to 'playback' which uses
-a buffer of 1024 samples. While this is not per se spec compliant, it allow usage
-of the library in a more user friendly manner. In the future, this might change according
-to the support of other audio backend, which is now alsa.
+2. Clone the repo and build the binary on your machine
+```sh
+git clone https://github.com/ircam-ismm/node-web-audio-api.git
+cd node-web-audio-api
+npm install
+npm run build
+```
 
-```js
-const audioContext = new AudioContext({ latencyHint: 'playback' });
+3. Run the examples from the project's root directory
+```sh
+node examples/granular-scrub.mjs
 ```
 
-The 'playback' latency hint, 1024 samples / ~21ms at 48000Hz, has been found 
-a good value.
+## Caveats
+
+- The async methods are not trully async for now and are just patched on the JS side. This will evolve once the "trully" async version of the methods are implemented in the upstream library.
+- On Linux systems, the audio backend is currently Alsa, which limits the number of online `AudioContext` to 1. This is subject to change in the future.
+- On Raspberry Pi, the default render quantum size (128) is too small and underruns occurs frequently. To prevent that, if you do not explicitely provide a latency hint in the AudioContext options, the value is automatically set to 'playback' which uses a buffer of 1024 samples (~21ms at 48000Hz). While this is not per se spec compliant, it allows usage of the library in a more user friendly manner. In the future, this might change according to the support of other audio backend.
+- On Raspberry Pi, the `Linux arm gnueabihf` binary provided only works on 32bit OS. We will provide a version for the 64 bit OS in the future.
 
 ## Supported Platforms
 
-|                            | binaries | tested |
-| ---------------------------| ------   | ------ |
-| Windows x64                | ✓        |        |
-| Windows arm64              | ✓        |        |
-| macOS x64                  | ✓        | ✓      |
-| macOS aarch64              | ✓        |        |
-| Linux x64 gnu              | ✓        |        |
-| Linux arm gnueabihf (RPi)  | ✓        | ✓      |
+|                              | binaries | tested |
+| ---------------------------  | ------   | ------ |
+| Windows x64                  | ✓        |        |
+| Windows arm64                | ✓        |        |
+| macOS x64                    | ✓        | ✓      |
+| macOS aarch64                | ✓        |        |
+| Linux x64 gnu                | ✓        |        |
+| Linux arm gnueabihf (RPi)    | ✓        | ✓      |
 
 
 ### Manual Build
 
 If prebuilt binaries are not shippped for your platform, you will need to:
 
-1. Install rust toolchain
+1. Install the Rust toolchain
 
 ```sh
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
@@ -89,24 +96,17 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 2. Install and build from github
 
 ```sh
-npm install --save git+https://github.com/b-ma/node-web-audio-api.git
+npm install --save git+https://github.com/ircam-ismm/node-web-audio-api.git
 cd node_modules/node-web-audio-api
+npm install
 npm run build
 ```
 
-The package will then be built on your machine, which might take some time
-
-## Known limitation / caveats
-
-- async function are not trully async but only monkey patched on the JS side, this will
-be updated once `web-audio-api-rs` provide async version of the methods.
-- see `web-audio-api-rs`
+The package will be built on your machine, which might take some time
 
 ## Development notes
 
-The npm script rely on [`cargo-bump`](https://crates.io/crates/cargo-bump) to maintain version synced between
-the `package.json` and the `Cargo.toml` files. Therefore, you will need to install 
-`cargo-bump` on your machine
+The npm `postversion` script rely on [`cargo-bump`](https://crates.io/crates/cargo-bump) to maintain versions synced between the `package.json` and the `Cargo.toml` files. Therefore, you will need to install `cargo-bump` on your machine
 
 ```
 cargo install cargo-bump
@@ -114,4 +114,4 @@ cargo install cargo-bump
 
 ## License
 
-This project is licensed under the [BSD-3-Clause license](./LICENSE).
+[BSD-3-Clause](./LICENSE)

package/index.cjs

@@ -83,33 +83,8 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding for OS: ${platform}, architecture: ${arch}`);
 }
 
-const {
-  patchAudioContext,
-  patchOfflineAudioContext,
-  load,
-} = require('./monkey-patch.js');
-
-nativeBinding.AudioContext = patchAudioContext(nativeBinding.AudioContext);
-nativeBinding.OfflineAudioContext = patchOfflineAudioContext(nativeBinding.OfflineAudioContext);
-nativeBinding.load = load;
-
-// ------------------------------------------------------------------
-// monkey patch proto media devices API
-// @todo - review
-// ------------------------------------------------------------------
-class MediaStream extends nativeBinding.Microphone {};
-// const Microphone = nativeBinding.Microphone;
-nativeBinding.Microphone = null;
-
-nativeBinding.mediaDevices = {}
-nativeBinding.mediaDevices.getUserMedia = function getUserMedia(options) {
-    if (options && options.audio === true) {
-        const mic = new MediaStream();
-        return Promise.resolve(mic);
-    } else {
-        throw new NotSupportedError(`Only { audio: true } is currently supported`);
-    }
-}
+const monkeyPatch = require('./monkey-patch.js');
+nativeBinding = monkeyPatch(nativeBinding);
 
 module.exports = nativeBinding;
 

package/monkey-patch.js

@@ -20,32 +20,58 @@ class NotSupportedError extends Error {
 }
 
 const { platform, arch } = process;
-let contextId = 0;
 
-function patchAudioContext(NativeAudioContext) {
-  class AudioContext extends NativeAudioContext {
-    constructor(options = {}) {
+let contextIds = {
+  audioinput: 0,
+  audiooutput: 0,
+};
 
-      // special handling of options on linux, these are not spec compliant but are
-      // ment to be more user-friendly than what we have now (is subject to change)
-      if (platform === 'linux') {
-        // throw meaningfull error if several contexts are created on linux,
-        // because of alsa backend we currently use
-        if (contextId === 1) {
-          throw new Error(`[node-web-audio-api] node-web-audio-api currently uses alsa as backend, therefore only one context can be safely created`);
-        }
+let enumerateDevicesSync = null;
+
+function handleDefaultOptions(options, kind) {
+  if (platform === 'linux') {
+    const list = enumerateDevicesSync();
+    const jackDevice = list.find(device => device.kind === kind && device.label === 'jack');
 
-        // fallback latencyHint to "playback" on RPi if not explicitely defined
-        if (arch === 'arm') {
-          if (!('latencyHint' in options)) {
-            options.latencyHint = 'playback';
-          }
+    if (jackDevice === undefined) {
+      // throw meaningfull error if several contexts are created on linux,
+      // because of alsa backend we currently use
+      if (contextIds[kind] === 1) {
+        throw new Error(`[node-web-audio-api] node-web-audio-api uses alsa as backend, therefore only one context or audio input stream can be safely created`);
+      }
+
+      // force latencyHint to "playback" on RPi if not explicitely defined
+      if (arch === 'arm') {
+        if (kind === 'audiooutput' && !('latencyHint' in options)) {
+          options.latencyHint = 'playback';
         }
       }
+    } else {
+      // default to jack if jack source or sink is found
+      const deviceKey = kind === 'audioinput' ? 'deviceId' : 'sinkId';
 
+      if (!(deviceKey in options)) {
+        console.log(`> JACK ${kind} device found, use as default`);
+        options[deviceKey] = jackDevice.deviceId;
+      }
+    }
+  }
+
+  // increment contextIds as they are used to keep the process awake
+  contextIds[kind] += 1;
+
+  return options;
+}
+
+function patchAudioContext(nativeBinding) {
+  class AudioContext extends nativeBinding.AudioContext {
+    constructor(options = {}) {
+      // special handling of options on linux, these are not spec compliant but are
+      // ment to be more user-friendly than what we have now (is subject to change)
+      options = handleDefaultOptions(options, 'audiooutput');
       super(options);
       // prevent garbage collection
-      const processId = `__AudioContext_${contextId}`;
+      const processId = `__AudioContext_${contextIds['audiooutput']}`;
       process[processId] = this;
 
       Object.defineProperty(this, '__processId', {
@@ -55,7 +81,6 @@ function patchAudioContext(NativeAudioContext) {
         configurable: false,
       });
 
-      contextId += 1;
       // keep process awake
       const keepAwakeId = setInterval(() => {}, 10000);
       Object.defineProperty(this, '__keepAwakeId', {
@@ -83,6 +108,15 @@ function patchAudioContext(NativeAudioContext) {
       return Promise.resolve(super.close());
     }
 
+    setSinkId(sinkId) {
+      try {
+        super.setSinkId(sinkId);
+        Promise.resolve(undefined);
+      } catch (err) {
+        Promise.reject(err);
+      }
+    }
+
     decodeAudioData(audioData) {
       if (!isPlainObject(audioData) || !('path' in audioData)) {
         throw new Error(`Invalid argument, please consider using the load helper`);
@@ -100,8 +134,8 @@ function patchAudioContext(NativeAudioContext) {
   return AudioContext;
 }
 
-function patchOfflineAudioContext(NativeOfflineAudioContext) {
-  class OfflineAudioContext extends NativeOfflineAudioContext {
+function patchOfflineAudioContext(nativeBinding) {
+  class OfflineAudioContext extends nativeBinding.OfflineAudioContext {
     constructor(...args) {
       // handle initialisation with either an options object or a sequence of parameters
       // https://webaudio.github.io/web-audio-api/#dom-offlineaudiocontext-constructor-contextoptions-contextoptions
@@ -121,15 +155,6 @@ function patchOfflineAudioContext(NativeOfflineAudioContext) {
       }
 
       super(...args);
-
-      // not sure this is usefull, to be tested
-      const keepAwakeId = setInterval(() => {}, 10000);
-      Object.defineProperty(this, '__keepAwakeId', {
-        value: keepAwakeId,
-        enumerable: false,
-        writable: true,
-        configurable: false,
-      });
     }
 
     // promisify sync APIs
@@ -161,15 +186,40 @@ function patchOfflineAudioContext(NativeOfflineAudioContext) {
   return OfflineAudioContext;
 }
 
-module.exports.patchAudioContext = patchAudioContext;
-module.exports.patchOfflineAudioContext = patchOfflineAudioContext;
-
 // dumb method provided to mock an xhr call and mimick browser's API
 // see also `AudioContext.decodeAudioData`
-module.exports.load = function(path) {
+function load(path) {
   if (!fs.existsSync(path)) {
     throw new Error(`File not found: "${path}"`);
   }
 
   return { path };
 };
+
+module.exports = function monkeyPatch(nativeBinding) {
+  nativeBinding.AudioContext = patchAudioContext(nativeBinding);
+  nativeBinding.OfflineAudioContext = patchOfflineAudioContext(nativeBinding);
+
+  // Promisify MediaDevices API
+  enumerateDevicesSync = nativeBinding.mediaDevices.enumerateDevices;
+  nativeBinding.mediaDevices.enumerateDevices = async function enumerateDevices(options) {
+    const list = enumerateDevicesSync();
+    return Promise.resolve(list);
+  }
+
+  const getUserMediaSync = nativeBinding.mediaDevices.getUserMedia;
+  nativeBinding.mediaDevices.getUserMedia = async function getUserMedia(options) {
+    if (options === undefined) {
+      throw new TypeError("Failed to execute 'getUserMedia' on 'MediaDevices': audio must be requested")
+    }
+
+    options = handleDefaultOptions(options, 'audioinput');
+    const stream = getUserMediaSync(options);
+    return Promise.resolve(stream);
+  }
+
+  // utils
+  nativeBinding.load = load;
+
+  return nativeBinding;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-web-audio-api",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "author": "Benjamin Matuszewski",
   "description": "Node.js bindings for web-audio-api-rs using napi-rs",
   "exports": {
@@ -12,6 +12,10 @@
   "keywords": [
     "audio",
     "web audio api",
+    "webaudio",
+    "sound",
+    "music",
+    "dsp",
     "rust",
     "n-api"
   ],
@@ -28,20 +32,26 @@
   "scripts": {
     "artifacts": "napi artifacts",
     "build": "npm run generate && napi build --platform --release",
+    "build:jack": "npm run generate && napi build --platform --features 'web-audio-api/cpal-jack' --release",
     "build:debug": "npm run generate && napi build --platform",
     "check": "cargo fmt && cargo clippy",
     "generate": "node generator/index.mjs && cargo fmt",
     "lint": "eslint monkey-patch.js index.cjs index.mjs && eslint examples/*.mjs",
     "preversion": "yarn install && npm run generate",
-    "postversion": "cargo bump $npm_package_version && git commit -am \"v$npm_package_version\""
+    "postversion": "cargo bump $npm_package_version && git commit -am \"v$npm_package_version\" && node bin/check-changelog.mjs",
+    "test": "mocha"
   },
   "devDependencies": {
     "@ircam/eslint-config": "^1.3.0",
+    "@ircam/sc-gettime": "^1.0.0",
     "@sindresorhus/slugify": "^2.1.1",
     "camelcase": "^7.0.1",
+    "chai": "^4.3.7",
     "chalk": "^5.2.0",
+    "cli-table": "^0.3.11",
     "dotenv": "^16.0.3",
     "eslint": "^8.32.0",
+    "mocha": "^10.2.0",
     "node-ssh": "^13.0.0",
     "octokit": "^2.0.11",
     "ping": "^0.4.2",

package/simple-test.cjs

@@ -1,7 +1,6 @@
-const { AudioContext } = require('./index.js');
+const { AudioContext, mediaDevices } = require('./index.cjs');
 
 const audioContext = new AudioContext();
-process.audioContext = audioContext;
 
 setInterval(() => {
   const now = audioContext.currentTime;

package/simple-test.mjs

@@ -1,25 +1,20 @@
-// import { AudioContext } from './index.mjs';
+import { AudioContext, mediaDevices } from './index.mjs';
 
-// const audioContext = new AudioContext();
+const audioContext = new AudioContext();
 
-// setInterval(() => {
-//   const now = audioContext.currentTime;
+setInterval(() => {
+  const now = audioContext.currentTime;
 
-//   const env = audioContext.createGain();
-//   env.connect(audioContext.destination);
-//   env.gain.value = 0;
-//   env.gain.setValueAtTime(0, now);
-//   env.gain.linearRampToValueAtTime(0.1, now + 0.02);
-//   env.gain.exponentialRampToValueAtTime(0.0001, now + 1);
+  const env = audioContext.createGain();
+  env.connect(audioContext.destination);
+  env.gain.value = 0;
+  env.gain.setValueAtTime(0, now);
+  env.gain.linearRampToValueAtTime(0.1, now + 0.02);
+  env.gain.exponentialRampToValueAtTime(0.0001, now + 1);
 
-//   const osc = audioContext.createOscillator();
-//   osc.frequency.value = 200 + Math.random() * 2800;
-//   osc.connect(env);
-//   osc.start(now);
-//   osc.stop(now + 1);
-// }, 100);
-
-
-import { mediaDevices } from './index.mjs';
-
-console.log(mediaDevices);
+  const osc = audioContext.createOscillator();
+  osc.frequency.value = 200 + Math.random() * 2800;
+  osc.connect(env);
+  osc.start(now);
+  osc.stop(now + 1);
+}, 100);

package/tests/AudioBuffer.spec.mjs

@@ -0,0 +1,60 @@
+import { assert } from 'chai';
+import { AudioBuffer, AudioContext } from '../index.mjs';
+
+describe('# AudioBuffer', () => {
+  let audioContext;
+
+  before(() => {
+    audioContext = new AudioContext();
+  });
+
+  after(() => {
+    audioContext.close();
+  });
+
+  describe(`## audioContext.createBuffer`, () => {
+    it('should properly create audio buffer', () => {
+      const audioBuffer = audioContext.createBuffer(1, 100, audioContext.sampleRate);
+
+      assert.equal(audioBuffer.numberOfChannels, 1);
+      assert.equal(audioBuffer.length, 100);
+      assert.equal(audioBuffer.sampleRate, audioContext.sampleRate);
+    });
+
+    it('should properly fail if missing argument', () => {
+      assert.throws(() => {
+        const audioBuffer = audioContext.createBuffer(1, 100);
+      });
+    });
+  });
+
+  describe(`## new AudioBuffer(options)`, () => {
+    it('should properly create audio buffer', () => {
+      const audioBuffer = new AudioBuffer({
+        length: 100,
+        sampleRate: audioContext.sampleRate,
+      });
+
+      assert.equal(audioBuffer.numberOfChannels, 1);
+      assert.equal(audioBuffer.length, 100);
+      assert.equal(audioBuffer.sampleRate, audioContext.sampleRate);
+    });
+
+    it('should properly fail if missing argument', () => {
+      assert.throws(() => {
+        const audioBuffer = new AudioBuffer({ length: 100 });
+      });
+    });
+
+    it(`should have type error`, () => {
+      try {
+        new AudioBuffer(Date, 42);
+      } catch (err) {
+        console.log(err.type);
+        console.log(err.name);
+        console.log(err.message);
+        assert.fail('should be TypeError');
+      }
+    });
+  });
+});

package/tests/getUserMedia.spec.mjs

@@ -0,0 +1,58 @@
+import { assert } from 'chai';
+
+import { mediaDevices } from '../index.mjs';
+
+describe('# mediaDevices.getUserMedia(options)', () => {
+  it('should fail if no argument given', async () => {
+    let failed = false;
+    try {
+      await mediaDevices.getUserMedia();
+    } catch (err) {
+      console.log(err.message);
+      failed = true;
+    }
+
+    if (!failed) { assert.fail(); }
+  });
+
+  // @todo - clean error message
+  it('should fail if argument is not an object', async () => {
+    let failed = false;
+    try {
+      await mediaDevices.getUserMedia(true);
+    } catch (err) {
+      console.log(err.message);
+      failed = true;
+    }
+
+    if (!failed) { assert.fail(); }
+  });
+
+  it('should fail if options.video', async () => {
+    let failed = false;
+    try {
+      await mediaDevices.getUserMedia({ video: true });
+    } catch (err) {
+      console.log(err.message);
+      failed = true;
+    }
+
+    if (!failed) { assert.fail(); }
+  });
+
+  it.only('should not fail if options.audio = true', async () => {
+    let failed = false;
+
+    try {
+      const stream = await mediaDevices.getUserMedia({ audio: true });
+      // console.log(stream instanceof mediaDevices.MediaStream);
+    } catch (err) {
+      console.log(err);
+      failed = true;
+    }
+
+    console.log(failed);
+
+    if (failed) { assert.fail('should not have failed'); }
+  });
+});