@audio/decode-caf 1.3.3 → 1.4.1

package/README.md

@@ -1,8 +1,6 @@
 # @audio/decode-caf
 
-Decode Core Audio Format (CAF) audio to PCM float samples.
-
-Part of [decode](https://github.com/audiojs/decode).
+Decode Core Audio Format audio to PCM float samples.
 
 ## Install
 
@@ -13,44 +11,40 @@ npm i @audio/decode-caf
 ## Usage
 
 ```js
-import decode from '@audio/decode-caf'
-
-let { channelData, sampleRate } = await decode(cafBuffer)
-```
-
-### Streaming
+import decode, { decoder } from '@audio/decode-caf'
 
-```js
-import { decoder } from '@audio/decode-caf'
+let { channelData, sampleRate } = decode(cafBytes)
 
-let dec = await decoder()
+let dec = decoder()
 let result = dec.decode(chunk)
 dec.free()
 ```
 
+`decode()` and `decoder()` are synchronous.
+
 ## API
 
-### `decode(src): Promise<AudioData>`
+### `decode(src): AudioData`
 
-Whole-file decode. Accepts `Uint8Array` or `ArrayBuffer`.
+Decode a complete `Uint8Array` or `ArrayBuffer`.
 
-### `decoder(): Promise<CAFDecoder>`
+### `decoder(): CAFDecoder`
 
-Creates a decoder instance.
+Create a decoder instance.
 
-- **`dec.decode(data)`** — decode chunk, returns `{ channelData, sampleRate }`
-- **`dec.flush()`** — flush (returns empty — CAF is stateless)
-- **`dec.free()`** — release resources
+- `dec.decode(data)`: decode a chunk.
+- `dec.flush()`: discard buffered partial data and return an empty result.
+- `dec.free()`: release resources.
 
 ## Formats
 
-- `lpcm` — 8, 16, 24, 32-bit signed integer (LE/BE), 32/64-bit float (LE/BE)
-- `alaw` — G.711 A-law
-- `ulaw` — G.711 mu-law
-- `ima4` — IMA/QuickTime ADPCM (iOS Voice Memos, GarageBand)
+- `lpcm`: 8, 16, 24, and 32-bit signed integer; 32 and 64-bit float; little-endian or big-endian.
+- `alaw`: G.711 A-law.
+- `ulaw`: G.711 µ-law.
+- `ima4`: IMA/QuickTime ADPCM.
 
-## License
+Other formats (AAC and ALAC packets, as in Apple Loops) throw `CAF: unsupported format '<id>'`.
 
-MIT
+## License
 
-<a href="https://github.com/krishnized/license/">ॐ</a>
+[ॐ](https://github.com/krishnized/license/) · [MIT](./LICENSE)

package/decode-caf.d.ts

@@ -1,16 +1,16 @@
-interface AudioData {
+export interface AudioData {
   channelData: Float32Array[];
   sampleRate: number;
 }
 
 interface CAFDecoder {
-  decode(data: Uint8Array): AudioData;
+  decode(data: Uint8Array | ArrayBuffer): AudioData;
   flush(): AudioData;
   free(): void;
 }
 
-/** Whole-file decode of CAF audio */
-export default function decode(src: ArrayBuffer | Uint8Array): Promise<AudioData>;
+/** Decode a complete CAF file synchronously. */
+export default function decode(src: ArrayBuffer | Uint8Array): AudioData;
 
-/** Create decoder instance */
-export function decoder(): Promise<CAFDecoder>;
+/** Create a synchronous decoder. */
+export function decoder(): CAFDecoder;

package/decode-caf.js

@@ -2,31 +2,25 @@
  * CAF (Core Audio Format) decoder
  * Decodes CAF containers with lpcm, alaw, ulaw audio to Float32 PCM
  *
- * let { channelData, sampleRate } = await decode(cafbuf)
+ * let { channelData, sampleRate } = decode(cafbuf)
  */
 
 const EMPTY = Object.freeze({ channelData: [], sampleRate: 0 })
+const FORMATS = new Set(['lpcm', 'alaw', 'ulaw', 'ima4'])
 
 // IMA/QuickTime ADPCM tables
 const IMA_STEP = new Int16Array([7,8,9,10,11,12,13,14,16,17,19,21,23,25,28,31,34,37,41,45,50,55,60,66,73,80,88,97,107,118,130,143,157,173,190,209,230,253,279,307,337,371,408,449,494,544,598,658,724,796,876,963,1060,1166,1282,1411,1552,1707,1878,2066,2272,2499,2749,3024,3327,3660,4026,4428,4871,5358,5894,6484,7132,7845,8630,9493,10442,11487,12635,13899,15289,16818,18500,20350,22385,24623,27086,29794,32767])
 const IMA_IDX = new Int8Array([-1,-1,-1,-1,2,4,6,8,-1,-1,-1,-1,2,4,6,8])
 
-/**
- * Whole-file decode
- * @param {Uint8Array|ArrayBuffer} src
- * @returns {Promise<{channelData: Float32Array[], sampleRate: number}>}
- */
-export default async function decode(src) {
-	let dec = await decoder()
+/** Decode a complete CAF file synchronously. */
+export default function decode(src) {
+	let dec = decoder()
 	try { return dec.decode(src) }
 	finally { dec.free() }
 }
 
-/**
- * Create decoder instance (streaming-aware)
- * @returns {Promise<{decode(chunk: Uint8Array): {channelData, sampleRate}, flush(), free()}>}
- */
-export async function decoder() {
+/** Create a synchronous streaming decoder. */
+export function decoder() {
 	let hdr = null, left = null, freed = false, dataLeft = Infinity
 	return {
 		decode(data) {
@@ -40,9 +34,9 @@ export async function decoder() {
 				dataLeft = hdr.dataSize
 				chunk = chunk.subarray(hdr.dataStart)
 			}
-			if (dataLeft <= 0) return EMPTY // past the data chunk — ignore trailing chunks
+			if (dataLeft <= 0) return EMPTY // Ignore chunks after the declared audio data.
 			let fb = hdr.frameBytes
-			let avail = Math.min(chunk.length, dataLeft) // don't read past the declared data size
+			let avail = Math.min(chunk.length, dataLeft) // Do not read past the declared data size.
 			let complete = Math.floor(avail / fb) * fb
 			if (!complete) { if (chunk.length && dataLeft > chunk.length) left = chunk.slice(); return EMPTY }
 			dataLeft -= complete
@@ -83,6 +77,8 @@ function scanCafHdr(buf) {
 				channelsPerFrame: dv.getUint32(off + 24, false),
 				bitsPerChannel: dv.getUint32(off + 28, false),
 			}
+			// compressed formats (aac, alac, ...) carry packets this decoder can't read: say so, don't wait forever
+			if (!FORMATS.has(desc.formatID)) throw Error(`CAF: unsupported format '${desc.formatID}'`)
 		} else if (type === 'data') {
 			if (!desc) return null
 			let dataStart = off + 4 // skip editCount
@@ -95,7 +91,7 @@ function scanCafHdr(buf) {
 			if (formatID === 'alaw' || formatID === 'ulaw') frameBytes = ch
 			else if (formatID === 'ima4') frameBytes = desc.bytesPerPacket || 34 * ch // packet = 34 bytes/channel
 			else frameBytes = ch * bytesPerSample
-			if (!frameBytes) return null
+			if (!frameBytes) throw Error(`CAF: invalid ${formatID} description (${ch} channels, ${bits} bits)`)
 			return { ...desc, dataStart, frameBytes, dataSize }
 		}
 		if (size < 0) break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audio/decode-caf",
-  "version": "1.3.3",
+  "version": "1.4.1",
   "description": "Decode CAF (Core Audio Format) audio to PCM samples",
   "type": "module",
   "main": "decode-caf.js",