node-web-audio-api 0.2.1 → 0.3.0

package/README.md

@@ -11,7 +11,7 @@ npm install [--save] node-web-audio-api
 ## Example
 
 ```js
-import { AudioContext, OscillatorNode, GainNode } from 'node-web-audio-api';
+const { AudioContext, OscillatorNode, GainNode } = require('node-web-audio-api');
 
 const audioContext = new AudioContext();
 
@@ -33,34 +33,81 @@ setInterval(() => {
 }, 50);
 ```
 
+or using with EcmaScript module syntax
 
+```js
+import wabaudioapi from 'node-web-audio-api';
+const { AudioContext, OscillatorNode, GainNode } = webaudioapi;
+
+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, 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 you should provide a latency hint when building
+an audio context:
 
+```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

@@ -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,10 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding for OS: ${platform}, architecture: ${arch}`);
 }
 
+const { patchAudioContext, load } = require('./monkey-patch.js');
+
 nativeBinding.AudioContext = patchAudioContext(nativeBinding.AudioContext);
+nativeBinding.load = load;
 
 module.exports = nativeBinding;
 

package/monkey-patch.js

@@ -1,6 +1,11 @@
+const fs = require('fs');
 
 let contextId = 0;
 
+const isPlainObject = function(obj) {
+  return Object.prototype.toString.call(obj) === '[object Object]';
+};
+
 module.exports.patchAudioContext = function(NativeAudioContext) {
   class AudioContext extends NativeAudioContext {
     constructor(...args) {
@@ -8,31 +13,65 @@ module.exports.patchAudioContext = function(NativeAudioContext) {
       // 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);
+      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());
     }
 
-    // @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();
-    // }
+    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;
 }
+
+// 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,10 @@
 {
   "name": "node-web-audio-api",
-  "version": "0.2.1",
+  "version": "0.3.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",
+  "repository": "https://github.com/ircam-ismm/node-web-audio-api",
   "license": "BSD-3-Clause",
   "keywords": [
     "audio",
@@ -24,18 +24,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",