Improve streamable API

Author: dy

audio-decode.d.ts

@@ -17,12 +17,15 @@ type Format = 'mp3' | 'flac' | 'opus' | 'oga' | 'm4a' | 'wav' | 'qoa' | 'aac' |
 interface FormatDecoder {
   /** Create a decoder instance. */
   (): Promise<StreamDecoder>;
-  /** @deprecated Use decode.mp3() instead. */
-  stream(): Promise<StreamDecoder>;
 }
 
 /** Whole-file decode: auto-detects format. */
 declare function decode(buf: ArrayBuffer | Uint8Array): Promise<AudioData>;
+/** Chunked decode from stream or async iterable. */
+declare function decode(
+  source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>,
+  format: Format
+): AsyncGenerator<AudioData>;
 
 declare namespace decode {
   export const mp3: FormatDecoder;
@@ -42,11 +45,8 @@ declare namespace decode {
 
 export default decode;
 
-/** @deprecated Use audio-decode/stream */
-export function decodeStream(
-  stream: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>,
+/** Chunked decode from stream or async iterable. */
+export function decodeChunked(
+  source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>,
   format: Format
 ): AsyncGenerator<AudioData>;
-
-/** @deprecated Use decode.mp3, decode.flac, etc. */
-export declare const decoders: typeof decode;

audio-decode.js

@@ -1,9 +1,11 @@
 /**
- * Audio decoder: whole-file and streaming
+ * Audio decoder: whole-file and chunked
  * @module audio-decode
  *
  * let { channelData, sampleRate } = await decode(buf)
  *
+ * for await (let pcm of decode(source, 'mp3')) { ... }
+ *
  * let dec = await decode.mp3()
  * let { channelData, sampleRate } = await dec(chunk)
  * await dec() // close
@@ -14,11 +16,16 @@ import getType from 'audio-type';
 const EMPTY = Object.freeze({ channelData: Object.freeze([]), sampleRate: 0 })
 
 /**
- * Whole-file decode: auto-detects format
- * @param {ArrayBuffer|Uint8Array} src - encoded audio data
- * @returns {Promise<{channelData: Float32Array[], sampleRate: number}>}
+ * Decode audio.
+ * 1 arg:  whole-file — auto-detects format, returns Promise<AudioData>
+ * 2 args: chunked — streams from ReadableStream/AsyncIterable, returns AsyncGenerator<AudioData>
  */
-export default async function decode(src) {
+export default function decode(src, format) {
+	if (format) return decodeChunked(src, format)
+	return decodeWhole(src)
+}
+
+async function decodeWhole(src) {
 	if (!src || typeof src === 'string' || !(src.buffer || src.byteLength || src.length))
 		throw TypeError('Expected ArrayBuffer or Uint8Array')
 	let buf = new Uint8Array(src)
@@ -36,26 +43,25 @@ export default async function decode(src) {
 }
 
 /**
- * Decode a ReadableStream or async iterable of audio chunks
- * @param {ReadableStream|AsyncIterable} stream
+ * Decode a ReadableStream or async iterable of encoded audio chunks.
+ * @param {ReadableStream|AsyncIterable} source
  * @param {string} format - codec name
  * @returns {AsyncGenerator<{channelData: Float32Array[], sampleRate: number}>}
  */
-export async function* decodeStream(stream, format) {
+export async function* decodeChunked(source, format) {
 	if (!decode[format]) throw Error('No decoder for ' + format)
 	let dec = await decode[format]()
 	try {
-		// Safari ReadableStream doesn't support for-await, use getReader() if available
-		if (stream.getReader) {
-			let reader = stream.getReader()
+		if (source.getReader) {
+			let reader = source.getReader()
 			while (true) {
 				let { done, value } = await reader.read()
 				if (done) break
 				let result = await dec(value instanceof Uint8Array ? value : new Uint8Array(value))
 				if (result.channelData.length) yield result
 			}
 		} else {
-			for await (let chunk of stream) {
+			for await (let chunk of source) {
 				let result = await dec(chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk))
 				if (result.channelData.length) yield result
 			}
@@ -93,7 +99,6 @@ function reg(name, load) {
 	})
 }
 
-// TODO: remove backward compat (src arg, .stream) in next major
 function fmt(name, init) {
 	let fn = async (src) => {
 		if (!src) return init()
@@ -105,7 +110,6 @@ function fmt(name, init) {
 			return merge(result, flushed)
 		} catch (e) { dec.free(); throw e }
 	}
-	fn.stream = init
 	return fn
 }
 
@@ -128,9 +132,6 @@ reg('webm', () => import('@audio/decode-webm'))
 reg('amr', () => import('@audio/decode-amr'))
 reg('wma', () => import('@audio/decode-wma'))
 
-// TODO: remove in next major
-export const decoders = decode
-
 /**
  * StreamDecoder — a callable function:
  * dec(chunk)  — decode data, returns { channelData, sampleRate }
@@ -155,7 +156,6 @@ function streamDecoder(onDecode, onFlush, onFree) {
 			return result
 		} catch (e) { onFree?.(); throw e }
 	}
-	fn.decode = fn // TODO: remove in next major
 	fn.flush = async () => {
 		if (done) return EMPTY
 		return onFlush ? norm(await onFlush()) : EMPTY

package-lock.json

@@ -48,18 +48,20 @@ let b = await dec(chunk2)
 await dec()                  // close
 ```
 
-## Streaming
+### Streaming
 
-With `ReadableStream`, `fetch`, or Node stream:
+Pass an async iterable source and format string — returns an async generator:
 
 ```js
-import decodeStream from 'audio-decode/stream'
+import decode from 'audio-decode'
 
-for await (let { channelData, sampleRate } of decodeStream(response.body, 'mp3')) {
+for await (let { channelData, sampleRate } of decode(response.body, 'mp3')) {
   // process chunks
 }
 ```
 
+Works with `ReadableStream`, `fetch` body, Node stream, or any async iterable.
+
 Formats: `mp3`, `flac`, `opus`, `oga`, `m4a`, `wav`, `qoa`, `aac`, `aiff`, `caf`, `webm`, `amr`, `wma`.
 
 ## See also

readme.md

@@ -2,11 +2,14 @@ import type { AudioData } from './audio-decode.js';
 
 type Format = 'mp3' | 'flac' | 'opus' | 'oga' | 'm4a' | 'wav' | 'qoa' | 'aac' | 'aiff' | 'caf' | 'webm' | 'amr' | 'wma';
 
-/** Decode a stream of audio chunks */
-declare function decodeStream(
-  stream: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>,
+/** Chunked decode from stream or async iterable. */
+declare function decodeChunked(
+  source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>,
   format: Format
 ): AsyncGenerator<AudioData>;
 
+export default decodeChunked;
+export { decodeChunked };
+
 export default decodeStream;
 export { decodeStream };

stream.d.ts

@@ -1 +1 @@
-export { decodeStream as default, decodeStream } from './audio-decode.js'
+export { decodeChunked as default, decodeChunked } from './audio-decode.js'

stream.js

@@ -1,4 +1,4 @@
-import decode, { decodeStream } from './audio-decode.js';
+import decode from './audio-decode.js';
 import wav from 'audio-lena/wav';
 import mp3 from 'audio-lena/mp3';
 import ogg from 'audio-lena/ogg';
@@ -294,7 +294,7 @@ t('concurrent decoding', async () => {
 })
 
 t('concurrent stream decoders', async () => {
-	let [d1, d2] = await Promise.all([decode.mp3.stream(), decode.flac.stream()])
+	let [d1, d2] = await Promise.all([decode.mp3(), decode.flac()])
 	let [r1, r2] = await Promise.all([
 		d1(new Uint8Array(mp3)),
 		d2(new Uint8Array(flac)),
@@ -318,60 +318,60 @@ t('minimal invalid buffer', async () => {
 	is(threw, true)
 })
 
-// -- decodeStream --
+// -- chunked decode --
 
-t('decodeStream mp3', async () => {
+t('decode mp3', async () => {
 	let chunks = [new Uint8Array(mp3)]
 	async function* gen() { for (let c of chunks) yield c }
 	let total = 0
-	for await (let r of decodeStream(gen(), 'mp3')) {
+	for await (let r of decode(gen(), 'mp3')) {
 		is(r.sampleRate > 0, true)
 		total += r.channelData[0].length
 	}
 	is(total > 0, true, 'decoded samples')
 })
 
-t('decodeStream ReadableStream', async () => {
+t('decode ReadableStream', async () => {
 	let data = new Uint8Array(wav)
 	let stream = new ReadableStream({
 		start(ctrl) { ctrl.enqueue(data); ctrl.close() }
 	})
 	let total = 0
-	for await (let r of decodeStream(stream, 'wav')) {
+	for await (let r of decode(stream, 'wav')) {
 		is(r.sampleRate, 44100)
 		total += r.channelData[0].length
 	}
 	is(total > 0, true)
 })
 
-t('decodeStream m4a', async () => {
+t('decode m4a', async () => {
 	async function* gen() { yield new Uint8Array(m4a) }
 	let total = 0
-	for await (let r of decodeStream(gen(), 'm4a')) {
+	for await (let r of decode(gen(), 'm4a')) {
 		is(r.sampleRate, 44100)
 		total += r.channelData[0].length
 	}
 	is(total > 0, true)
 })
 
-t('decodeStream m4a chunked', async () => {
+t('decode m4a chunked', async () => {
 	// M4A needs full file (moov atom), so chunked streaming must buffer until flush
 	let buf = new Uint8Array(m4a), chunkSize = 16384
 	async function* gen() {
 		for (let off = 0; off < buf.length; off += chunkSize)
 			yield buf.subarray(off, Math.min(off + chunkSize, buf.length))
 	}
 	let total = 0
-	for await (let r of decodeStream(gen(), 'm4a')) {
+	for await (let r of decode(gen(), 'm4a')) {
 		total += r.channelData[0].length
 	}
 	let ref = await decode(m4a)
 	is(total, ref.channelData[0].length, 'chunked M4A matches one-shot')
 })
 
-t('decodeStream unknown format', async () => {
+t('decode unknown format', async () => {
 	let threw = false
-	try { for await (let _ of decodeStream([], 'xyz')) {} } catch { threw = true }
+	try { for await (let _ of decode([], 'xyz')) {} } catch { threw = true }
 	is(threw, true)
 })
 
@@ -432,7 +432,7 @@ async function* chunked(buf, size = 4096) {
 function streamTotal(gen, fmt) {
 	return (async () => {
 		let total = 0, sr = 0
-		for await (let r of decodeStream(gen, fmt)) {
+		for await (let r of decode(gen, fmt)) {
 			sr = r.sampleRate; total += r.channelData[0].length
 		}
 		return { total, sr }
@@ -533,6 +533,6 @@ t('chunked stream tiny chunks wav', async () => {
 t('chunked stream yields multiple results', async () => {
 	// verify streaming actually yields multiple chunks (not one big blob)
 	let count = 0
-	for await (let r of decodeStream(chunked(wav, 4096), 'wav')) count++
+	for await (let r of decode(chunked(wav, 4096), 'wav')) count++
 	is(count > 1, true, 'multiple yields from stream')
 })