node-web-audio-api 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+## v0.4.0
+
+- Implement offline audio context
+- Update web-audio-api-rs to v0.24.0 
+- Implement `audio_node.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

@@ -30,37 +30,87 @@ setInterval(() => {
   osc.connect(env);
   osc.start(now);
   osc.stop(now + 1);
-}, 50);
+}, 80);
 ```
 
+or using with old fashionned commonjs syntax
 
+```js
+const { AudioContext, OscillatorNode, GainNode } = require('node-web-audio-api');
+
+const audioContext = new AudioContext();
+//...
+```
 
-## Build manually
+## Caveats
 
-If prebuilt binaries are not shippped for your platform, you will need to install 
-the rust toolchain and install and build the package from github.
+- 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.
 
-1. Install rust toolchain
+### 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.
 
+```js
+const audioContext = new AudioContext({ latencyHint: 'playback' });
 ```
+
+The 'playback' latency hint, 1024 samples / ~21ms at 48000Hz, has been found 
+a good value.
+
+## Supported Platforms
+
+|                            | 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
+
+```sh
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
 
-2. Install from github
+2. Install and build from github
 
-```
+```sh
 npm install --save git+https://github.com/b-ma/node-web-audio-api.git
+cd node_modules/node-web-audio-api
+npm run build
 ```
 
-Note that the package will be built on your machine, so the install process might be a bit long
+The package will then be built on your machine, which might take some time
 
-## Roadmap
+## Known limitation / caveats
 
-- Make a few nodes work properly with clean and predictable code
-- Generate bindings from IDL [https://webaudio.github.io/web-audio-api/#idl-index](https://webaudio.github.io/web-audio-api/#idl-index)
-- Publish on `npm` with binaries
-- Implement prototype chain (?)
-- Follow developments of `web-audio-api-rs`
+- 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`
+
+## 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
+
+```
+cargo install cargo-bump
+```
 
 ## License
 

package/{index.js → index.cjs}

@@ -1,6 +1,5 @@
 const { existsSync, readFileSync } = require('fs');
 const { join } = require('path');
-const { patchAudioContext } = require('./monkey-patch.js');
 
 const { platform, arch } = process;
 
@@ -87,7 +86,15 @@ 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;
 
 module.exports = nativeBinding;
 

package/index.mjs

@@ -0,0 +1,39 @@
+// ---------------------------------------------------------- //
+// ---------------------------------------------------------- //
+//    - WARNING - DO NOT EDIT                               - //
+//    - This file has been generated                        - //
+// ---------------------------------------------------------- //
+// ---------------------------------------------------------- //
+
+// re-export index.js to support clean esm syntax
+// see https://github.com/nodejs/node/issues/40541#issuecomment-951609570
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+const nativeModule = require('./index.cjs');
+export const {
+  AudioContext,
+  OfflineAudioContext,
+  AudioBuffer,
+  PeriodicWave,
+  // generated supported nodes
+  AudioBufferSourceNode,
+  BiquadFilterNode,
+  ChannelMergerNode,
+  ChannelSplitterNode,
+  ConstantSourceNode,
+  DelayNode,
+  DynamicsCompressorNode,
+  GainNode,
+  IIRFilterNode,
+  OscillatorNode,
+  StereoPannerNode,
+  WaveShaperNode,
+  // helper methods
+  load
+} = nativeModule;
+
+export default nativeModule;
+
+  

package/monkey-patch.js

@@ -1,38 +1,144 @@
+const fs = require('fs');
 
+const isPlainObject = function(obj) {
+  return Object.prototype.toString.call(obj) === '[object Object]';
+};
+
+const { platform, arch } = process;
 let contextId = 0;
 
-module.exports.patchAudioContext = function(NativeAudioContext) {
+function patchAudioContext(NativeAudioContext) {
   class AudioContext extends NativeAudioContext {
-    constructor(...args) {
-      super(...args);
+    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)
+      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`);
+        }
+
+        // fallback latencyHint to "playback" on RPi if not explicitely defined
+        if (arch === 'arm') {
+          if (!('latencyHint' in options)) {
+            options.latencyHint = 'playback';
+          }
+        }
+      }
+
+      super(options);
       // prevent garbage collection
       const processId = `__AudioContext_${contextId}`;
       process[processId] = this;
-      this.__processId = processId;
+
+      Object.defineProperty(this, '__processId', {
+        value: processId,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+      });
 
       contextId += 1;
       // keep process awake
-      this.__keepAwakeId = setInterval(() => {}, 10000);
-    }
-
-    // @todo
-    // resume() {
-    //   this.__keepAwakeId = setInterval(() => {}, 2000);
-    //   return super.resume();
-    // }
-
-    // suspend() {
-    //   // not sure to be confirmed
-    //   clearTimeout(this.__keepAwakeId);
-    //   return super.suspend();
-    // }
-
-    // close() {
-    //    delete process[this.__processId];
-    //    clearTimeout(this.__keepAwakeId);
-    //    return super.close();
-    // }
+      const keepAwakeId = setInterval(() => {}, 10000);
+      Object.defineProperty(this, '__keepAwakeId', {
+        value: keepAwakeId,
+        enumerable: false,
+        writable: true,
+        configurable: false,
+      });
+    }
+
+    // promisify sync APIs
+    resume() {
+      clearTimeout(this.__keepAwakeId);
+      this.__keepAwakeId = setInterval(() => {}, 2000);
+      return Promise.resolve(super.resume());
+    }
+
+    suspend() {
+      return Promise.resolve(super.suspend());
+    }
+
+    close() {
+      delete process[this.__processId];
+      clearTimeout(this.__keepAwakeId);
+      return Promise.resolve(super.close());
+    }
+
+    decodeAudioData(audioData) {
+      if (!isPlainObject(audioData) || !('path' in audioData)) {
+        throw new Error(`Invalid argument, please consider using the load helper`);
+      }
+
+      try {
+        const audioBuffer = super.decodeAudioData(audioData);
+        return Promise.resolve(audioBuffer);
+      } catch (err) {
+        return Promise.reject(err);
+      }
+    }
   }
 
   return AudioContext;
 }
+
+function patchOfflineAudioContext(NativeOfflineAudioContext) {
+  class OfflineAudioContext extends NativeOfflineAudioContext {
+    constructor(...args) {
+      super(...args);
+      console.log(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
+    startRendering() {
+      try {
+        const audioBuffer = super.startRendering();
+
+        clearTimeout(this.__keepAwakeId);
+        return Promise.resolve(audioBuffer);
+      } catch (err) {
+        return Promise.reject(err);
+      }
+    }
+
+    decodeAudioData(audioData) {
+      if (!isPlainObject(audioData) || !('path' in audioData)) {
+        throw new Error(`Invalid argument, please consider using the load helper`);
+      }
+
+      try {
+        const audioBuffer = super.decodeAudioData(audioData);
+        return Promise.resolve(audioBuffer);
+      } catch (err) {
+        return Promise.reject(err);
+      }
+    }
+  }
+
+  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) {
+  if (!fs.existsSync(path)) {
+    throw new Error(`File not found: "${path}"`);
+  }
+
+  return { path };
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "node-web-audio-api",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "author": "Benjamin Matuszewski",
   "description": "Node.js bindings for web-audio-api-rs using napi-rs",
-  "main": "index.js",
-  "repository": "git@github.com:b-ma/node-web-audio-api.git",
+  "exports": {
+    "import": "./index.mjs",
+    "require": "./index.cjs"
+  },
+  "repository": "https://github.com/ircam-ismm/node-web-audio-api",
   "license": "BSD-3-Clause",
   "keywords": [
     "audio",
@@ -24,18 +27,24 @@
   },
   "scripts": {
     "artifacts": "napi artifacts",
-    "build": "napi build --platform --release",
-    "build:debug": "napi build --platform",
+    "build": "npm run generate && napi build --platform --release",
+    "build:debug": "npm run generate && napi build --platform",
     "check": "cargo fmt && cargo clippy",
-    "generate": "node generator/index.js",
-    "preversion": "npm run generate"
+    "generate": "node generator/index.mjs && cargo fmt",
+    "preversion": "yarn install && npm run generate",
+    "postversion": "cargo bump $npm_package_version && git commit -am \"v$npm_package_version\""
   },
   "devDependencies": {
+    "@sindresorhus/slugify": "^2.1.0",
     "chalk": "^5.0.1",
+    "camelcase": "^6.3.0",
     "dotenv": "^16.0.2",
     "node-ssh": "^13.0.0",
     "octokit": "^2.0.7",
-    "ping": "^0.4.2"
+    "ping": "^0.4.2",
+    "template-literal": "^1.0.4",
+    "waves-masters": "^2.3.1",
+    "webidl2": "^24.2.0"
   },
   "dependencies": {
     "@napi-rs/cli": "^2.10.0",

package/simple-test.mjs

@@ -1,7 +1,6 @@
-import webaudio from './index.js';
+import { AudioContext } from './index.mjs';
 
-const audioContext = new webaudio.AudioContext();
-// process.audioContext = audioContext;
+const audioContext = new AudioContext();
 
 setInterval(() => {
   const now = audioContext.currentTime;