Add stream entry, simplify API

Author: dy

README.md

@@ -38,7 +38,7 @@ const flac = await encode.flac(channelData, { sampleRate: 44100 });
 const opus = await encode.opus(channelData, { sampleRate: 48000, bitrate: 96 });
 ```
 
-### Stream encoding
+### Chunked encoding
 
 Call with just options (no data) to create a streaming encoder:
 
@@ -49,11 +49,21 @@ const enc = await encode.mp3({ sampleRate: 44100, bitrate: 128 });
 
 const a = await enc(chunk1);  // Uint8Array
 const b = await enc(chunk2);
-const c = await enc();        // end of stream — flush + free
+const c = await enc(null);        // end of stream — flush + free
 
 // explicit control: enc.flush(), enc.free()
 ```
 
+### TransformStream
+
+```js
+import encodeStream from 'encode-audio/stream';
+
+audioSource
+  .pipeThrough(encodeStream('mp3', { sampleRate: 44100, bitrate: 128 }))
+  .pipeTo(destination);
+```
+
 ### Options
 
 | Option | Description | Applies to |
@@ -66,17 +76,6 @@ const c = await enc();        // end of stream — flush + free
 | `compression` | FLAC compression level 0–8 | flac |
 | `application` | `'audio'`, `'voip'`, or `'lowdelay'` | opus |
 
-### Custom encoders
-
-The `encode` registry is extensible:
-
-```js
-import encode from 'encode-audio';
-encode.myformat = Object.assign(
-  async (data, opts) => { /* ... */ },
-  { stream: async (opts) => ({ encode: chunk => ..., free() {} }) }
-);
-```
 
 ## See also
 

package.json

@@ -11,11 +11,14 @@
       "node": "./audio-encode.js",
       "default": "./audio-encode.js"
     },
+    "./stream": "./stream.js",
     "./package.json": "./package.json"
   },
   "files": [
     "audio-encode.js",
     "audio-encode.d.ts",
+    "stream.js",
+    "stream.d.ts",
     "LICENSE"
   ],
   "workspaces": [

stream.d.ts

@@ -0,0 +1,11 @@
+type AudioInput = Float32Array[] | Float32Array | { numberOfChannels: number; getChannelData(i: number): Float32Array };
+
+/**
+ * Create a TransformStream that encodes audio chunks to the given format.
+ * @param format - 'wav', 'mp3', 'ogg', 'opus', 'flac', 'aiff'
+ * @param opts - encoder options (sampleRate required)
+ */
+export default function encodeStream(
+	format: string,
+	opts: import('./audio-encode.js').EncodeOptions
+): TransformStream<AudioInput, Uint8Array>;

stream.js

@@ -0,0 +1,29 @@
+/**
+ * TransformStream for audio encoding
+ * @module encode-audio/stream
+ *
+ * audioSource.pipeThrough(encodeStream('mp3', { sampleRate: 44100, bitrate: 128 }))
+ */
+
+import encode from './audio-encode.js'
+
+/**
+ * @param {string} format - 'wav', 'mp3', 'ogg', 'opus', 'flac', 'aiff'
+ * @param {object} opts - encoder options (sampleRate required)
+ * @returns {TransformStream<Float32Array[]|Float32Array, Uint8Array>}
+ */
+export default function encodeStream(format, opts) {
+	if (!encode[format]) throw Error('Unknown format: ' + format)
+	let enc
+	return new TransformStream({
+		async start() { enc = await encode[format](opts) },
+		async transform(chunk, ctrl) {
+			let buf = await enc(chunk)
+			if (buf.length) ctrl.enqueue(buf)
+		},
+		async flush(ctrl) {
+			let buf = await enc()
+			if (buf.length) ctrl.enqueue(buf)
+		}
+	})
+}

test.js

@@ -1,5 +1,6 @@
 import t, { is, ok, almost } from 'tst'
 import encode from './audio-encode.js'
+import encodeStream from './stream.js'
 import decode from 'audio-decode'
 import AudioBuffer from 'audio-buffer'
 
@@ -96,6 +97,18 @@ t('streaming (deprecated .stream/.encode)', async () => {
 	ok(c1.length > 0 || c2.length > 0 || final.length > 0)
 })
 
+t('TransformStream', async () => {
+	let chunks = [sine(44100, 440, 0.5), sine(44100, 440, 0.5)]
+	let source = new ReadableStream({
+		pull(ctrl) { chunks.length ? ctrl.enqueue(chunks.shift()) : ctrl.close() }
+	})
+	let out = []
+	let dest = new WritableStream({ write(chunk) { out.push(chunk) } })
+	await source.pipeThrough(encodeStream('wav', { sampleRate: 44100 })).pipeTo(dest)
+	ok(out.length > 0, 'produced chunks')
+	ok(out.every(c => c instanceof Uint8Array), 'all Uint8Array')
+})
+
 t('AudioBuffer input', async () => {
 	let ab = new AudioBuffer({ sampleRate: 44100, length: 44100 })
 	let ch = ab.getChannelData(0)