frames: the exact length upfront makes the streamed header exact (canonical WAV, pipes get true totals); WAV pads odd data

Author: dy

README.md

@@ -116,6 +116,7 @@ await file.close()
 | `chapters` | `[{ time, title }]` (seconds): ID3 CHAP/CTOC, iTunes chpl | mp3, m4a |
 | `profile` | `'lc'`, `'he'` (HE-AAC), `'hev2'` (HE-AACv2, stereo) | aac, m4a |
 | `stream` | Emit as it encodes; `head()` after (see above) | all |
+| `frames` | With `stream`: the exact length, when known upfront, so the header goes out exact (a canonical WAV; a pipe gets true totals) | wav, aiff, caf, qoa, flac, mp3 |
 
 
 ### Metadata

audio-encode.d.ts

@@ -41,6 +41,9 @@ export interface EncodeOptions {
 	 *  totals the header can't know yet read "unknown" (WAV/AIFF 0xFFFFFFFF, CAF -1, QOA 0,
 	 *  FLAC STREAMINFO 0) until `head()`; m4a/mp4 become fragmented. */
 	stream?: boolean;
+	/** With stream: the exact length in sample frames, when known upfront. The header goes out exact
+	 *  (a canonical WAV, no RF64 reserve under 4 GB): a pipe gets the true totals, head() has less to do. */
+	frames?: number;
 	[key: string]: any;
 }
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@audio/encode",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Encode audio data in node or browser",
   "type": "module",
   "sideEffects": false,
@@ -64,17 +64,17 @@
   "homepage": "https://github.com/audiojs/encode#readme",
   "dependencies": {
     "@audio/encode-aac": "^1.2.0",
-    "@audio/encode-aiff": "^1.3.0",
-    "@audio/encode-caf": "^1.2.0",
-    "@audio/encode-flac": "^1.3.0",
-    "@audio/encode-mp3": "^1.3.0",
+    "@audio/encode-aiff": "^1.4.0",
+    "@audio/encode-caf": "^1.3.0",
+    "@audio/encode-flac": "^1.4.0",
+    "@audio/encode-mp3": "^1.4.0",
     "@audio/encode-ogg": "^1.3.0",
     "@audio/encode-opus": "^1.3.0",
-    "@audio/encode-qoa": "^1.2.0",
-    "@audio/encode-wav": "^1.4.0",
+    "@audio/encode-qoa": "^1.3.0",
+    "@audio/encode-wav": "^1.5.0",
     "@audio/encode-webm": "^1.3.0",
     "@audio/encode-wavpack": "^1.0.0",
-    "@audio/encode-mp4": "^1.1.0",
+    "@audio/encode-mp4": "^1.1.1",
     "@audio/encode-alac": "^1.0.1"
   },
   "devDependencies": {

package.json

@@ -34,7 +34,7 @@ Input is `Float32Array[]` — one array per channel. Big-endian interleaving han
 
 ### Streaming output
 
-`stream: true`: the header goes out with the first samples, sizes `0xFFFFFFFF` (read to the end), `meta` as an ID3 chunk before SSND. After `flush()`, `head()` returns the exact header to write over the start of a file.
+`stream: true`: the header goes out with the first samples, sizes `0xFFFFFFFF` (read to the end), `meta` as an ID3 chunk before SSND. After `flush()`, `head()` returns the exact header to write over the start of a file. With `frames` (the exact length, known upfront) the header goes out exact and `head()` has nothing to add.
 
 ## License
 

packages/encode-aiff/README.md

@@ -1,6 +1,8 @@
 export interface AiffEncodeOptions {
 	/** Emit bytes as they encode (metadata in the header); head() gives the final header. */
 	stream?: boolean;
+	/** The exact length in sample frames, when known upfront: the streamed header goes out exact. */
+	frames?: number;
 	sampleRate: number;
 	bitDepth?: 16 | 24;
 }

packages/encode-aiff/aiff-encode.d.ts

@@ -5,6 +5,7 @@
  * @param {number} [opts.bitDepth=16] - 16 or 24
  * @param {boolean} [opts.stream] - emit the header and samples as they are encoded, sizes unknown
  *   (0xFFFFFFFF, read to the end) until head() gives the exact header; `meta` rides in an ID3 chunk
+ * @param {number} [opts.frames] - with stream: the exact length, when known upfront: the header goes out exact
  * @returns {{ encode, flush, free, head }}
  */
 export default async function aiff(opts) {
@@ -53,28 +54,28 @@ export default async function aiff(opts) {
 		if (stream) {
 			if (sent) return buf
 			sent = true
-			let h = header(false), out = new Uint8Array(h.length + buf.length)
+			let h = header(opts.frames), out = new Uint8Array(h.length + buf.length)
 			out.set(h); out.set(buf, h.length)
 			return out
 		}
 		chunks.push(buf)
 		return new Uint8Array(0)
 	}
 
-	// FORM, COMM, [ID3], SSND header. `known`: exact sizes, else 0xFFFFFFFF (unknown, read to the end)
-	function header(known) {
-		let ch = nCh || opts.channels || 1, x = id3?.length || 0
+	// FORM, COMM, [ID3], SSND header for `frames` sample frames; null: sizes 0xFFFFFFFF (unknown, read to the end)
+	function header(frames) {
+		let ch = nCh || opts.channels || 1, x = id3?.length || 0, bytes = (frames ?? 0) * ch * bytesPerSample
 		let hdr = new Uint8Array(12 + 26 + x + 16), dv = new DataView(hdr.buffer), p = 0
-		let ssndSize = totalBytes + 8, formSize = 4 + 26 + x + 8 + ssndSize + (totalBytes & 1)
-		let fit = known && formSize <= 0xFFFFFFFF
+		let ssndSize = bytes + 8, formSize = 4 + 26 + x + 8 + ssndSize + (bytes & 1)
+		let fit = frames != null && formSize <= 0xFFFFFFFF
 
 		// FORM
 		str('FORM'); dv.setUint32(p, fit ? formSize : 0xFFFFFFFF, false); p += 4; str('AIFF')
 
 		// COMM
 		str('COMM'); dv.setUint32(p, 18, false); p += 4
 		dv.setInt16(p, ch, false); p += 2
-		dv.setUint32(p, fit ? numFrames : 0xFFFFFFFF, false); p += 4
+		dv.setUint32(p, fit ? frames : 0xFFFFFFFF, false); p += 4
 		dv.setInt16(p, depth, false); p += 2
 		writeF80(dv, p, rate); p += 10
 
@@ -94,13 +95,13 @@ export default async function aiff(opts) {
 	function flush() {
 		if (!nCh) nCh = opts.channels || 1
 		if (stream) {
-			exact = header(true)
-			let h = sent ? null : (sent = true, header(false)), pad = totalBytes & 1 ? new Uint8Array(1) : null
+			let h = sent ? null : (sent = true, header(opts.frames)), pad = totalBytes & 1 ? new Uint8Array(1) : null
+			exact = opts.frames === numFrames ? null : header(numFrames)  // the declared length held: nothing to patch
 			if (!h) return pad || new Uint8Array(0)
 			let out = new Uint8Array(h.length + (pad ? 1 : 0)); out.set(h); return out
 		}
 
-		let hdr = header(true)
+		let hdr = header(numFrames)
 		let file = new Uint8Array(hdr.length + totalBytes + (totalBytes & 1))  // chunks pad to even
 		file.set(hdr)
 		let off = hdr.length

packages/encode-aiff/aiff-encode.js

@@ -1,6 +1,6 @@
 {
   "name": "@audio/encode-aiff",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Encode PCM audio samples to AIFF format",
   "type": "module",
   "main": "aiff-encode.js",

packages/encode-aiff/package.json

@@ -36,7 +36,7 @@ Input is `Float32Array[]` — one array per channel. Big-endian interleaving han
 
 ### Streaming output
 
-`stream: true`: the header goes out with the first samples, the data chunk size `-1` (the CAF spec's "unknown, runs to the end"). After `flush()`, `head()` returns the exact header to write over the start of a file.
+`stream: true`: the header goes out with the first samples, the data chunk size `-1` (the CAF spec's "unknown, runs to the end"). After `flush()`, `head()` returns the exact header to write over the start of a file. With `frames` (the exact length, known upfront) the header goes out exact and `head()` has nothing to add.
 
 ## License
 

packages/encode-caf/README.md

@@ -1,6 +1,8 @@
 export interface CafEncodeOptions {
 	/** Emit bytes as they encode (metadata in the header); head() gives the final header. */
 	stream?: boolean;
+	/** The exact length in sample frames, when known upfront: the streamed header goes out exact. */
+	frames?: number;
 	sampleRate: number;
 	bitDepth?: 16 | 32;
 }