opus-decoder - npm Package Compare versions

Comparing version 0.0.2 to 0.1.0

package.json

 {
   "name": "opus-decoder",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Web Assembly streaming Opus decoder",
@@ -22,3 +22,4 @@ "main": "dist/opus-decoder.min.js",
     "WebAssembly",
-    "Wasm"
+    "Wasm",
+    "WebWorker"
   ],
@@ -25,0 +26,0 @@ "author": "Ethan Halsall",

README.md

@@ -1,4 +0,4 @@
-# opus-decoder
+# `opus-decoder`
 
-`opus-decoder` is a Web Assembly Opus audio decoder.
+`opus-decoder` is a Web Assembly Opus audio decoder based on [`libopus`](https://github.com/xiph/opus).
 
@@ -8,13 +8,31 @@ See the [homepage](https://github.com/eshaz/wasm-audio-decoders) of this repository for more Web Assembly audio decoders like this one.
 ## Installing
-Install via [NPM](https://www.npmjs.com/package/opus-decoder).
+* Install from [NPM](https://www.npmjs.com/package/opus-decoder).
+  ```
+  npm i opus-decoder
+  ```
 
+  ```javascript
+  import { OpusDecoder } from 'opus-decoder';
+
+  const decoder = new OpusDecoder();
+  ```
+ 
+* Or download the [build](https://github.com/eshaz/wasm-audio-decoders/tree/master/src/opus-decoder/dist) and include it as a script.
+  ```html
+  <script src="opus-decoder.min.js"></script>
+  <script>
+    const decoder = new OpusDecoder();
+  </script>
+  ```
+
 ## Usage
 
-1. Create a new instance and wait for the WASM to finish compiling. 
+1. Create a new instance and wait for the WASM to finish compiling. Decoding can be done on the main thread synchronously, or in a webworker asynchronously.
 
+   **Main thread synchronous decoding**
    ```javascript
-   import {OpusDecoder} from 'opus-decoder';
-   
+   import { OpusDecoder } from 'opus-decoder';
+
    const decoder = new OpusDecoder();
-   
+
    // wait for the WASM to be compiled
@@ -24,2 +42,12 @@ await decoder.ready;
 
+   **Web Worker asynchronous decoding**
+   ```javascript
+   import { OpusDecoderWebWorker } from 'opus-decoder';
+
+   const decoder = new OpusDecoderWebWorker();
+
+   // wait for the WASM to be compiled
+   await decoder.ready;
+   ```
+
 1. Begin decoding Opus frames.
@@ -35,5 +63,9 @@
 
-1. When done decoding, free up the memory being used by the WASM module. You will need to create a new instance to start decoding again.
+1. When done decoding, reset the decoder to decode a new stream, or free up the memory being used by the WASM module if you have no more audio to decode. 
 
    ```javascript
+   // `reset()` clears the decoder state and allows you do decode a new stream of Opus frames.
+   decoder.reset();
+
+   // `free()` de-allocates the memory used by the decoder. You will need to create a new instance after calling `free()` to start decoding again.
    decoder.free();
@@ -44,24 +76,59 @@ ```
 
-### Getters
-* `decoder.ready`
-  * Returns a promise that is resolved when the WASM is compiled and ready to use.
+Decoded audio is always returned in the below structure.
 
-### Methods
-
-Each method returns an object containing the decoded audio, number of samples decoded, and sample rate of the decoded audio.
-
-The `channelData` contains the raw decoded PCM for each channel (left, and right). Each Float32Array can be used directly in the WebAudio api. 
-
 ```javascript
-// decoded audio return value
 {
-    channelData: [leftAudio, rightAudio],
-    samplesDecoded: 1234,
-    sampleRate: 48000
+    channelData: [
+      leftAudio, // Float32Array of PCM samples for the left channel
+      rightAudio // Float32Array of PCM samples for the right channel
+    ],
+    samplesDecoded: 1234, // number of PCM samples that were decoded
+    sampleRate: 48000 // sample rate of the decoded PCM
 }
 ```
 
+Each Float32Array within `channelData` can be used directly in the WebAudio API for playback.
+
+## `OpusDecoder`
+
+Class that decodes Opus frames synchronously on the main thread.
+
+### Getters
+* `decoder.ready` *async*
+  * Returns a promise that is resolved when the WASM is compiled and ready to use.
+
+### Methods
+
 * `decoder.decodeFrame(opusFrame)`
   * `opusFrame` Uint8Array containing a single Opus frame.
+  * Returns decoded audio.
 * `decoder.decodeFrames(opusFrames)`
   * `opusFrames` Array of Uint8Arrays containing Opus frames.
+  * Returns decoded audio.
+* `decoder.reset()` *async*
+  * Resets the decoder so that a new stream of Opus frames can be decoded.
+* `decoder.free()`
+  * De-allocates the memory used by the decoder.
+  * After calling `free()`, the current instance is made unusable, and a new instance will need to be created to decode additional Opus frames.
+
+## `OpusDecoderWebWorker`
+
+Class that decodes Opus frames asynchronously within a WebWorker. Decoding is performed in a separate, non-blocking thread. Each new instance spawns a new worker allowing you to run multiple workers for concurrent decoding of multiple streams.
+
+### Getters
+* `decoder.ready` *async*
+  * Returns a promise that is resolved when the WASM is compiled and ready to use.
+
+### Methods
+
+* `decoder.decodeFrame(opusFrame)` *async*
+  * `opusFrame` Uint8Array containing a single Opus frame.
+  * Returns a promise that resolves with the decoded audio.
+* `decoder.decodeFrames(opusFrames)` *async*
+  * `opusFrames` Array of Uint8Arrays containing Opus frames.
+  * Returns a promise that resolves with the decoded audio.
+* `decoder.reset()` *async*
+  * Resets the decoder so that a new stream of Opus frames can be decoded.
+* `decoder.free()`
+  * De-allocates the memory used by the decoder and terminates the WebWorker.
+  * After calling `free()`, the current instance is made unusable, and a new instance will need to be created to decode additional Opus frames.

No alert changes

Improved metrics

Total package byte prevSize

106517

increased by7.65%

Lines of code

341

increased by2.71%

Number of lines in readme file

131

increased by104.69%

No dependency changes