Add streaming api

Author: dy

README.md

@@ -54,16 +54,20 @@ const c = await enc(null);        // end of stream — flush + free
 // explicit control: enc.flush(), enc.free()
 ```
 
-### TransformStream
+### Streaming
+
+Pass an async iterable as data — returns an async generator:
 
 ```js
-import encodeStream from 'encode-audio/stream';
+import encode from 'encode-audio'
 
-audioSource
-  .pipeThrough(encodeStream('mp3', { sampleRate: 44100, bitrate: 128 }))
-  .pipeTo(destination);
+for await (let buf of encode.mp3(audioSource, { sampleRate: 44100, bitrate: 128 })) {
+  // buf is Uint8Array
+}
 ```
 
+Works with any async iterable source.
+
 ### Options
 
 | Option | Description | Applies to |

audio-encode.d.ts

@@ -23,8 +23,6 @@ export interface StreamEncoder {
 	(channelData: AudioInput): Promise<Uint8Array>;
 	/** Flush remaining data, finalize, and free resources. */
 	(): Promise<Uint8Array>;
-	/** @deprecated Use enc() instead. */
-	encode(channelData?: AudioInput): Promise<Uint8Array>;
 	/** Flush without freeing. */
 	flush(): Promise<Uint8Array>;
 	/** Free resources without flushing. */
@@ -34,13 +32,20 @@ export interface StreamEncoder {
 export interface FormatEncoder {
 	/** Whole-file encode. */
 	(channelData: AudioInput, opts: EncodeOptions): Promise<Uint8Array>;
+	/** Chunked encode from async iterable. */
+	(source: AsyncIterable<AudioInput>, opts: EncodeOptions): AsyncGenerator<Uint8Array>;
 	/** Create streaming encoder. */
 	(opts: EncodeOptions): Promise<StreamEncoder>;
-	/** @deprecated Use encode.fmt(opts) instead. */
-	stream(opts: EncodeOptions): Promise<StreamEncoder>;
 }
 
 declare const encode: {
+	/** Whole-file encode. */
+	(format: string, channelData: AudioInput, opts: EncodeOptions): Promise<Uint8Array>;
+	/** Chunked encode from async iterable. */
+	(format: string, source: AsyncIterable<AudioInput>, opts: EncodeOptions): AsyncGenerator<Uint8Array>;
+	/** Create streaming encoder. */
+	(format: string, opts: EncodeOptions): Promise<StreamEncoder>;
+
 	wav: FormatEncoder;
 	aiff: FormatEncoder;
 	mp3: FormatEncoder;
@@ -52,6 +57,13 @@ declare const encode: {
 
 export default encode;
 
+/** Chunked encode from async iterable. */
+export function encodeChunked(
+	source: AsyncIterable<AudioInput>,
+	format: string,
+	opts: EncodeOptions
+): AsyncGenerator<Uint8Array>;
+
 /** Wrap codec callbacks into a StreamEncoder with lifecycle management. */
 export function streamEncoder(
 	onEncode: (channels: Float32Array[]) => Uint8Array | Promise<Uint8Array>,

audio-encode.js

@@ -1,23 +1,58 @@
 /**
- * Audio encoder: whole-file and streaming
+ * Audio encoder: whole-file and chunked
  * @module encode-audio
  *
  * let buf = await encode.wav(channelData, { sampleRate: 44100 })
  *
+ * for await (let bytes of encode.mp3(source, { sampleRate: 44100 })) { ... }
+ *
  * let enc = await encode.mp3({ sampleRate: 44100, bitrate: 128 })
  * let chunk = await enc(channelData)
  * let final = await enc() // flush + free
  */
 
 const EMPTY = new Uint8Array(0)
 
-const encode = {}
+/**
+ * Encode audio — delegates to format-specific encoder.
+ * encode('wav', channelData, { sampleRate })      → Promise<Uint8Array>
+ * encode('wav', source(), { sampleRate })          → AsyncGenerator<Uint8Array>
+ * encode('wav', { sampleRate })                    → Promise<StreamEncoder>
+ */
+function encode(format, data, opts) {
+	if (!encode[format]) throw Error('Unknown format: ' + format)
+	return encode[format](data, opts)
+}
 export default encode
 
+function isAudioData(d) {
+	return d instanceof Float32Array || Array.isArray(d) || (d?.getChannelData && d?.numberOfChannels)
+}
+
+/**
+ * Encode a stream of PCM chunks to the given format.
+ * @param {AsyncIterable<Float32Array[]|Float32Array>} source
+ * @param {string} format
+ * @param {object} opts - encoder options (sampleRate required)
+ * @returns {AsyncGenerator<Uint8Array>}
+ */
+async function* encodeChunked(source, format, opts) {
+	let enc = await encode[format](opts)
+	try {
+		for await (let chunk of source) {
+			let buf = await enc(chunk)
+			if (buf.length) yield buf
+		}
+		let final = await enc()
+		if (final.length) yield final
+	} catch (e) { enc.free(); throw e }
+}
+export { encodeChunked }
+
 // --- format registration ---
 
 function reg(name, load) {
-	encode[name] = fmt(async (opts) => {
+	encode[name] = fmt(name, async (opts) => {
 		let init = (await load()).default
 		let codec = await init(opts)
 		return streamEncoder(ch => codec.encode(ch), () => codec.flush(), () => codec.free())
@@ -36,26 +71,31 @@ reg('opus', () => import('@audio/encode-opus'))
  * 1 arg (opts) → streaming encoder function
  * 2 args (data, opts) → whole-file encode
  */
-function fmt(init) {
-	let fn = async (data, opts) => {
+function fmt(name, init) {
+	let fn = (data, opts) => {
 		// 1 arg = streaming: encode.mp3({ sampleRate })
 		if (!opts) return init(data)
+		// 2 args, async iterable = chunked: encode.mp3(source(), { sampleRate })
+		if (data && (typeof data[Symbol.asyncIterator] === 'function' || typeof data[Symbol.iterator] === 'function' && !isAudioData(data)))
+			return encodeChunked(data, name, opts)
 		// 2 args = whole-file: encode.mp3(channelData, { sampleRate })
-		if (!opts.sampleRate) throw Error('sampleRate is required')
-		let ch = channels(data)
-		if (!ch.length || !ch[0].length) return EMPTY
-		let enc = await init({ channels: ch.length, ...opts })
-		try {
-			let result = await enc(ch)
-			let flushed = await enc()
-			return merge(result, flushed)
-		} catch (e) { enc.free(); throw e }
+		return wholeFile(data, opts, init)
 	}
-	// TODO: remove .stream in next major
-	fn.stream = init
 	return fn
 }
 
+async function wholeFile(data, opts, init) {
+	if (!opts.sampleRate) throw Error('sampleRate is required')
+	let ch = channels(data)
+	if (!ch.length || !ch[0].length) return EMPTY
+	let enc = await init({ channels: ch.length, ...opts })
+	try {
+		let result = await enc(ch)
+		let flushed = await enc()
+		return merge(result, flushed)
+	} catch (e) { enc.free(); throw e }
+}
+
 // normalize input to Float32Array[]
 function channels(data) {
 	if (!data) return []
@@ -98,8 +138,6 @@ export function streamEncoder(onEncode, onFlush, onFree) {
 			return result
 		} catch (e) { onFree?.(); throw e }
 	}
-	// TODO: remove .encode in next major
-	fn.encode = fn
 	fn.flush = async () => {
 		if (done) return EMPTY
 		return onFlush ? norm(await onFlush()) : EMPTY

package-lock.json

@@ -1,11 +1 @@
-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>;
+export { encodeChunked as default, encodeChunked } from './audio-encode.js';

stream.d.ts

@@ -1,29 +1,7 @@
 /**
- * TransformStream for audio encoding
+ * Chunked encoder — re-exports encodeChunked from main module.
  * @module encode-audio/stream
  *
- * audioSource.pipeThrough(encodeStream('mp3', { sampleRate: 44100, bitrate: 128 }))
+ * for await (let bytes of encode.mp3(pcmSource, { sampleRate: 44100 })) { ... }
  */
-
-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)
-		}
-	})
-}
+export { encodeChunked as default, encodeChunked } from './audio-encode.js'

stream.js

@@ -1,6 +1,5 @@
 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'
 
@@ -89,26 +88,24 @@ t('streaming (callable)', async () => {
 	ok(c1.length > 0 || c2.length > 0 || final.length > 0)
 })
 
-t('streaming (deprecated .stream/.encode)', async () => {
-	let enc = await encode.wav.stream({ sampleRate: 44100 })
-	let c1 = await enc.encode(sine(44100, 440, 0.5))
-	let c2 = await enc.encode(sine(44100, 440, 0.5))
-	let final = await enc.encode()
-	ok(c1.length > 0 || c2.length > 0 || final.length > 0)
-})
-
-t('TransformStream', async () => {
+t('encode.wav(source, opts) chunked', 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() }
-	})
+	async function* source() { for (let c of chunks) yield c }
 	let out = []
-	let dest = new WritableStream({ write(chunk) { out.push(chunk) } })
-	await source.pipeThrough(encodeStream('wav', { sampleRate: 44100 })).pipeTo(dest)
+	for await (let buf of encode.wav(source(), { sampleRate: 44100 })) out.push(buf)
 	ok(out.length > 0, 'produced chunks')
 	ok(out.every(c => c instanceof Uint8Array), 'all Uint8Array')
 })
 
+t('encode(format, data) whole-file', async () => {
+	let { channelData, sampleRate } = await getLena()
+	let buf = await encode('wav', channelData, { sampleRate })
+	ok(buf.length > 44, 'has data')
+	let dec = await decode(buf)
+	is(dec.sampleRate, sampleRate)
+	almost(rms(dec.channelData[0]), rms(channelData[0]), 0.001, 'rms matches')
+})
+
 t('AudioBuffer input', async () => {
 	let ab = new AudioBuffer({ sampleRate: 44100, length: 44100 })
 	let ch = ab.getChannelData(0)