0.6.0

arseneyr · Nov 5, 2020 · 738acf2 · 738acf2
1 parent 519ca11
commit 738acf2
Show file tree

Hide file tree

Showing 3 changed files with 91 additions and 20 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.0] - 2020-11-04
+
+### Added
+
+- Can now supply a callback to `createEncoder()` to get the compiled `WebAssembly.Module`
+- Support for ESM modules in Node
+
+### Changed
+
+- Reduced JS size by about 40%
+- Reduced LAME WASM size by about 4%
+- Reduced OGG WASM size by about 3%
+
+### Fixed
+
+- Fixed an issue where encoding large buffers would return a detached `ArrayBuffer`.
+- Bundling with webpack v4 no longer pulls in a `Buffer` polyfill.
diff --git a/README.md b/README.md
@@ -1,6 +1,17 @@
 # wasm-media-encoders
 
-The LAME MP3 and Ogg Vorbis audio encoders, compiled to WebAssembly and ready for use in the browser or Node.
+The LAME MP3 and Ogg Vorbis audio encoders, compiled to lean, mean WebAssembly and ready for use in the browser or Node.
+
+## Why?
+
+While some browsers have native encoding using the [`MediaRecorder` API](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder), it only supports a [small number of codecs](https://stackoverflow.com/questions/41739837/all-mime-types-supported-by-mediarecorder-in-firefox-and-chrome).
+
+This package aims to fill the gap by compiling the reference LAME and Ogg Vorbis encoders to WebAssembly. The resulting package is tiny and fast:
+
+| Encoder    | JS      | WASM    | Combined + Gzipped |
+| ---------- | ------- | ------- | ------------------ |
+| MP3        | 3.5 KiB | 130 KiB | **66 KiB**         |
+| Ogg Vorbis | 3.5 KiB | 440 KiB | **158 KiB**        |
 
 ## Installation
 
@@ -52,19 +63,6 @@ createMp3Encoder().then((encoder) => {
 });
 ```
 
-### Reducing bundle size
-
-By default, this package inlines the WASM binary as a base64-encoded data URL. This make importing the encoder easy, but also increases the bundle size by about 30%. With webpack, you can use file-loader and load the WASM directly (found in `wasm-media-encoders/wasm/(mp3|ogg).wasm`), passing the URL as the second parameter to `createEncoder()`:
-
-```js
-import { createEncoder } from "wasm-media-encoders";
-import wasm from "file-loader!wasm-media-encoders/wasm/mp3.wasm";
-
-createEncoder("audio/mpeg", wasm).then((encoder) => {
-  /* Now mp3.wasm will be copied to output dir by webpack and fetch()ed at runtime*/
-});
-```
-
 ## Example usage
 
 ```js
@@ -116,6 +114,54 @@ createMp3Encoder().then((encoder) => {
 });
 ```
 
+## Reducing bundle size
+
+By default, this package inlines the WASM binary as a base64-encoded data URL. This make importing the encoder easy, but also increases the bundle size by about 30%. With webpack, you can load the WASM directly (found in `wasm-media-encoders/wasm/(mp3|ogg).wasm`), passing the URL as the second parameter to `createEncoder()`.
+
+### Webpack v4
+
+Besides using `file-loader`, you also need to disable WASM parsing in the webpack config:
+
+```js
+import { createEncoder } from "wasm-media-encoders";
+import wasm from "file-loader!wasm-media-encoders/wasm/mp3.wasm";
+
+createEncoder("audio/mpeg", wasm).then((encoder) => {
+  /* Now mp3.wasm will be copied to output dir by webpack and fetch()ed at runtime*/
+});
+```
+
+```js
+//webpack.config.js
+
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /\.wasm$/,
+        type: "javascript/auto",
+      },
+    ],
+  },
+};
+```
+
+### Webpack v5
+
+Using asset modules and [URL assets](https://webpack.js.org/guides/asset-modules/#url-assets) is very easy in webpack v5:
+
+```js
+import { createEncoder } from "wasm-media-encoders";
+
+createEncoder(
+  "audio/mpeg",
+  new URL("wasm-media-encoder/wasm/mp3", import.meta.url)
+).then((encoder) => {
+  /* Now mp3.wasm will be copied to output dir by webpack and fetch()ed at runtime*/
+});
+```
+
 ## API
 
 ### Named exports:
@@ -124,14 +170,15 @@ createMp3Encoder().then((encoder) => {
 
 ### **`createOggEncoder(): Promise<WasmMediaEncoder>`**
 
-### **`createEncoder(mimeType, wasm): Promise<WasmMediaEncoder>`**
+### **`createEncoder(mimeType, wasm, moduleCallback?): Promise<WasmMediaEncoder>`**
 
 The first two named exports use inline base-64 encoded WASM binaries (or `fetch()` from unpkg.com in the case of UMD). Tree-shaking on webpack should prevent unused encoders from being included in the final bundle.
 
-| Parameter  | Type                                                        | Description                                                                                                                                                                                                                                                                                              |
-| ---------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mimeType` | `String`                                                    | The MIME type of the encoder to create. Supported values are `'audio/mpeg'` (MP3) or `'audio/ogg'` (Ogg Vorbis)                                                                                                                                                                                          |
-| `wasm`     | `String \| ArrayBuffer \| Uint8Array \| WebAssembly.Module` | A URL, [base64 data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs), buffer, or compiled `WebAssembly.Module` representing the WASM binary for the specific `mimeType`. The WASM binaries are included in the package under `wasm-media-encoders/wasm/(mp3\|ogg).wasm`. |
+| Parameter         | Type                                                        | Description                                                                                                                                                                                                                                                                                              |
+| ----------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mimeType`        | `String`                                                    | The MIME type of the encoder to create. Supported values are `'audio/mpeg'` (MP3) or `'audio/ogg'` (Ogg Vorbis)                                                                                                                                                                                          |
+| `wasm`            | `String \| ArrayBuffer \| Uint8Array \| WebAssembly.Module` | A URL, [base64 data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs), buffer, or compiled `WebAssembly.Module` representing the WASM binary for the specific `mimeType`. The WASM binaries are included in the package under `wasm-media-encoders/wasm/(mp3\|ogg).wasm`. |
+| `moduleCallback?` | `((module: WebAssembly.Module) => void) \| undefined`       | Optionally, a callback that will be called with the compiled WebAssembly module. You can cache this module client-side and pass it as the `wasm` parameter to avoid fetching and compiling it every time.                                                                                                |
 
 ## `WasmMediaEncoder`
 

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "wasm-media-encoders",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "main": "dist/index.js",
   "module": "dist/es/index.js",
   "browser": "dist/browser/index.js",