carta1 1.5.0 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -65,10 +65,10 @@ function buildBiasedScaleFactorTable(bias) {
65
65
  /**
66
66
  * Evaluate one legal active-BFU count.
67
67
  *
68
- * @param {number} activeBfuCount
69
- * @param {number} maxBfuCount
70
- * @param {Int32Array} bfuSizes
71
- * @param {number} remainingBits
68
+ * @param {i32} activeBfuCount
69
+ * @param {i32} maxBfuCount
70
+ * @param {Array<number>} bfuSizes
71
+ * @param {i32} remainingBits
72
72
  * @param {Float64Array} biasedScaleFactors
73
73
  * @param {Int32Array} allScaleFactorIndices
74
74
  * @param {Float32Array} zeroBitDistortions
@@ -106,14 +106,15 @@ function search(
106
106
  * Calculates the total distortion for a given allocation.
107
107
  * This includes quantization distortion for coded bands and truncation
108
108
  * distortion for uncoded bands.
109
- * @param {number} activeBfuCount
110
- * @param {number} maxBfuCount
111
- * @param {Int32Array} bfuSizes
109
+ * @param {i32} activeBfuCount
110
+ * @param {i32} maxBfuCount
111
+ * @param {Array<number>} bfuSizes
112
112
  * @param {Int32Array} wordLengths
113
113
  * @param {Int32Array} scaleFactorIndices
114
- * @param {number} biasedScaleFactors
114
+ * @param {Float64Array} biasedScaleFactors
115
115
  * @param {Float32Array} zeroBitDistortions
116
116
  * @returns {number}
117
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
117
118
  */
118
119
  function measureDistortion(
119
120
  activeBfuCount,
@@ -154,12 +155,13 @@ function measureDistortion(
154
155
  * Distributes available bits across Band Frequency Units (BFUs) using Rate-Distortion Optimization.
155
156
  * (Modified to accept pre-calculated scale factors)
156
157
  *
157
- * @param {number} activeBfuCount
158
- * @param {Int32Array} bfuSizes
159
- * @param {number} remainingBits
158
+ * @param {i32} activeBfuCount
159
+ * @param {Array<number>} bfuSizes
160
+ * @param {i32} remainingBits
160
161
  * @param {Float64Array} biasedScaleFactors
161
162
  * @param {Int32Array} allScaleFactorIndices
162
163
  * @returns {object} Retained allocation decisions.
164
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
163
165
  */
164
166
  function distributeBits(
165
167
  activeBfuCount,
@@ -251,8 +253,9 @@ function distributeBits(
251
253
  *
252
254
  * @param {Int32Array} heapIndices
253
255
  * @param {Float32Array} heapPriorities
254
- * @param {number} startIndex
255
- * @param {number} heapSize
256
+ * @param {i32} startIndex
257
+ * @param {i32} heapSize
258
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
256
259
  */
257
260
  function siftDown(heapIndices, heapPriorities, startIndex, heapSize) {
258
261
  let i = startIndex
@@ -289,8 +292,8 @@ function siftDown(heapIndices, heapPriorities, startIndex, heapSize) {
289
292
  * minimizes the total perceptual distortion.
290
293
  *
291
294
  * @param {Array<Float32Array>} bfuData
292
- * @param {Int32Array} bfuSizes
293
- * @param {number} maxBfuCount
295
+ * @param {Array<number>} bfuSizes
296
+ * @param {i32} maxBfuCount
294
297
  * @param {number} allocationBias
295
298
  * @returns {{bfuCount:number, allocation:Int32Array, scaleFactorIndices:Int32Array}}
296
299
  */
@@ -360,7 +363,7 @@ export function solve(bfuData, bfuSizes, maxBfuCount, allocationBias) {
360
363
  * Find the optimal scale factor index for a set of coefficients.
361
364
  * Same semantics as the original.
362
365
  * @param {Float32Array} coefficients
363
- * @param {number} length
366
+ * @param {i32} length
364
367
  * @returns {number}
365
368
  */
366
369
  export function findScaleFactor(coefficients, length) {
@@ -44,6 +44,9 @@ function calculateSpectralFeatures(currentCoeffs, prevCoeffs) {
44
44
  /**
45
45
  * Calculate normalized spectral flux (positive spectral differences)
46
46
  * High values indicate sudden onset of new spectral components
47
+ * @param {Float32Array} currentCoeffs - Current frame coefficients
48
+ * @param {Float32Array} prevCoeffs - Previous frame coefficients
49
+ * @returns {number} Spectral flux normalized by current frame energy
47
50
  */
48
51
  function calculateSpectralFlux(currentCoeffs, prevCoeffs) {
49
52
  let flux = 0
@@ -184,7 +187,7 @@ function calculateTransientScore(features) {
184
187
  /**
185
188
  * Perform FFT on time-domain samples and return magnitude spectrum
186
189
  * @param {Float32Array} samples - Time-domain samples
187
- * @param {number} fftSize - FFT size (must be power of 2)
190
+ * @param {i32} fftSize - FFT size (must be power of 2)
188
191
  * @returns {Float32Array} Magnitude spectrum (positive frequencies only)
189
192
  */
190
193
  export function performFFT(samples, fftSize) {
@@ -35,8 +35,8 @@ export function transformSpectrum(context) {
35
35
 
36
36
  /**
37
37
  * @param {Float32Array} samples
38
- * @param {number} bandIndex
39
- * @param {number} blockMode
38
+ * @param {i32} bandIndex
39
+ * @param {i32} blockMode
40
40
  * @param {Float32Array} overlapBuffer
41
41
  * @returns {Float32Array}
42
42
  */
@@ -58,7 +58,7 @@ export function transformSpectrum(context) {
58
58
 
59
59
  /**
60
60
  * @param {Float32Array} samples
61
- * @param {number} bandIndex
61
+ * @param {i32} bandIndex
62
62
  * @param {Object} config
63
63
  * @param {Object} transformFunction
64
64
  * @param {Float32Array} overlapBuffer
@@ -91,7 +91,7 @@ export function transformSpectrum(context) {
91
91
 
92
92
  /**
93
93
  * @param {Float32Array} samples
94
- * @param {number} bandIndex
94
+ * @param {i32} bandIndex
95
95
  * @param {Object} config
96
96
  * @param {Float32Array} overlapBuffer
97
97
  * @returns {Float32Array}
@@ -126,7 +126,7 @@ export function transformSpectrum(context) {
126
126
  /**
127
127
  * @param {Float32Array} samples
128
128
  * @param {Float32Array} overlapBuffer
129
- * @param {number} blockSize
129
+ * @param {i32} blockSize
130
130
  */
131
131
  function applyTailWindowing(samples, overlapBuffer, blockSize) {
132
132
  const tailStart = blockSize - MDCT_OVERLAP_SIZE
@@ -46,7 +46,7 @@ export class AeaFile {
46
46
  *
47
47
  * @param {string} [title='']
48
48
  * @param {number} [frameCount=0]
49
- * @param {number} [channelCount=1]
49
+ * @param {i32} [channelCount=1]
50
50
  * @param {number} [sampleCount=0]
51
51
  * @param {number} [primingSampleCount=STREAM_PRIMING_SAMPLES]
52
52
  * @returns {Uint8Array}
@@ -17,7 +17,7 @@ import {
17
17
  * Write a four-character code.
18
18
  *
19
19
  * @param {DataView} output
20
- * @param {number} offset
20
+ * @param {i32} offset
21
21
  * @param {string} value
22
22
  */
23
23
  function writeFourCc(output, offset, value) {
@@ -48,7 +48,7 @@ export function joinChannelFrames(frames) {
48
48
  * Split planar PCM buffers into complete zero-padded codec frames.
49
49
  *
50
50
  * @param {Float32Array[]} buffers
51
- * @param {number} [frameSize=SAMPLES_PER_FRAME]
51
+ * @param {i32} [frameSize=SAMPLES_PER_FRAME]
52
52
  * @returns {Generator<Float32Array>|Generator<[Float32Array, Float32Array]>}
53
53
  * @throws {Error} If the channel count is unsupported
54
54
  */
@@ -65,7 +65,7 @@ export class AudioProcessor {
65
65
 
66
66
  /**
67
67
  * @param {Float32Array[]} buffers
68
- * @param {number} [frameSize]
68
+ * @param {i32} [frameSize]
69
69
  * @returns {Generator<Float32Array>|Generator<[Float32Array, Float32Array]>}
70
70
  */
71
71
  static *frameBufferToFrames(buffers, frameSize) {
@@ -144,7 +144,7 @@ export class AudioProcessor {
144
144
 
145
145
  /**
146
146
  * @param {Float32Array[]|[Float32Array, Float32Array][]} pcmFrames
147
- * @param {number} [channelCount=1]
147
+ * @param {i32} [channelCount=1]
148
148
  * @param {number} [sampleRate=SAMPLE_RATE]
149
149
  * @returns {Blob}
150
150
  */
@@ -173,7 +173,7 @@ export class AudioProcessor {
173
173
  * Preserve the supported WAVE facade name.
174
174
  *
175
175
  * @param {Float32Array[]|[Float32Array, Float32Array][]} pcmFrames
176
- * @param {number} [channelCount=1]
176
+ * @param {i32} [channelCount=1]
177
177
  * @param {number} [sampleRate=SAMPLE_RATE]
178
178
  * @returns {Blob}
179
179
  */
@@ -185,7 +185,7 @@ export class AudioProcessor {
185
185
  * Assemble PCM frames using the supported interleaved result shape.
186
186
  *
187
187
  * @param {Float32Array[]|[Float32Array, Float32Array][]} pcmFrames
188
- * @param {number} channelCount
188
+ * @param {i32} channelCount
189
189
  * @returns {Float32Array}
190
190
  */
191
191
  static assemblePcmFrames(pcmFrames, channelCount) {
@@ -48,8 +48,8 @@ export class AeaReader {
48
48
  for await (const chunk of stream) {
49
49
  buffer = Buffer.concat([buffer, chunk])
50
50
  while (buffer.length >= SOUND_UNIT_SIZE) {
51
- const frameData = buffer.slice(0, SOUND_UNIT_SIZE)
52
- buffer = buffer.slice(SOUND_UNIT_SIZE)
51
+ const frameData = buffer.subarray(0, SOUND_UNIT_SIZE)
52
+ buffer = buffer.subarray(SOUND_UNIT_SIZE)
53
53
  yield deserializeFrame(frameData)
54
54
  }
55
55
  }
@@ -19,7 +19,7 @@ import { frameBufferToFrames, joinChannelFrames } from './pcm.js'
19
19
  /**
20
20
  * Validate a supported channel mode.
21
21
  *
22
- * @param {number} channelCount
22
+ * @param {i32} channelCount
23
23
  * @throws {Error} If the channel count is unsupported
24
24
  */
25
25
  function validateChannels(channelCount) {
@@ -32,7 +32,7 @@ function validateChannels(channelCount) {
32
32
  * Validate one PCM frame in the selected channel mode.
33
33
  *
34
34
  * @param {object} frame
35
- * @param {number} channelCount
35
+ * @param {i32} channelCount
36
36
  * @throws {TypeError} If the frame does not match the selected mode
37
37
  * @throws {RangeError} If a selected channel is not one complete frame
38
38
  */
@@ -5,7 +5,7 @@
5
5
  /**
6
6
  * Calculate a band's offset in the 512-coefficient spectrum.
7
7
  *
8
- * @param {number} bandIndex
8
+ * @param {i32} bandIndex
9
9
  * @returns {number}
10
10
  */
11
11
  export function calculateBandOffset(bandIndex) {
@@ -16,7 +16,7 @@ export function calculateBandOffset(bandIndex) {
16
16
  * Extract one band from the full coefficient spectrum.
17
17
  *
18
18
  * @param {Float32Array} coefficients
19
- * @param {number} bandIndex
19
+ * @param {i32} bandIndex
20
20
  * @returns {Float32Array}
21
21
  */
22
22
  export function extractBandCoefficients(coefficients, bandIndex) {
@@ -16,8 +16,8 @@ import { SCALE_FACTORS } from '../core/tables.js'
16
16
  /**
17
17
  * Quantize coefficients.
18
18
  * @param {Float32Array} coefficients
19
- * @param {number} scaleFactorIndex
20
- * @param {number} bitsPerSample
19
+ * @param {i32} scaleFactorIndex
20
+ * @param {i32} bitsPerSample
21
21
  * @returns {Int32Array} out
22
22
  */
23
23
  export function quantize(coefficients, scaleFactorIndex, bitsPerSample) {
@@ -47,8 +47,8 @@ export function quantize(coefficients, scaleFactorIndex, bitsPerSample) {
47
47
  /**
48
48
  * Dequantize coefficients.
49
49
  * @param {Int32Array} quantized
50
- * @param {number} scaleFactorIndex
51
- * @param {number} bitsPerSample
50
+ * @param {i32} scaleFactorIndex
51
+ * @param {i32} bitsPerSample
52
52
  * @returns {Float32Array}
53
53
  */
54
54
  export function dequantize(quantized, scaleFactorIndex, bitsPerSample) {
@@ -6,6 +6,7 @@ export class FFT {
6
6
  *
7
7
  * @param {Float32Array} real Real input and output components.
8
8
  * @param {Float32Array} imaginary Imaginary input and output components.
9
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
9
10
  */
10
11
  static transform(real, imaginary) {
11
12
  const size = real.length
@@ -13,6 +13,10 @@ import { throwError } from '../utils.js'
13
13
  * Base class for MDCT and IMDCT transforms
14
14
  */
15
15
  class MdctBase {
16
+ /**
17
+ * @param {number} size - Transform size in samples
18
+ * @param {number} scale - Transform normalization factor
19
+ */
16
20
  constructor(size, scale) {
17
21
  this.size = size
18
22
  this.halfSize = size >> 1
@@ -43,8 +47,12 @@ export class MDCT extends MdctBase {
43
47
  /**
44
48
  * Perform forward MDCT transform
45
49
  * @param {Float32Array} input - Time-domain input samples
46
- * @param {Object} mdctBuffers - Optional work buffers for FFT
50
+ * @param {Object} mdctBuffers - Required work buffers keyed by FFT size
51
+ * @param {Float32Array|null} [destination=null] - Optional output buffer
52
+ * @param {i32} [destinationOffset=0] - First output index in destination
47
53
  * @returns {Float32Array} Frequency-domain MDCT coefficients
54
+ * @throws {Error} If the required FFT work buffers are missing
55
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
48
56
  */
49
57
  transform(
50
58
  input,
@@ -52,21 +60,20 @@ export class MDCT extends MdctBase {
52
60
  destination = null,
53
61
  destinationOffset = 0
54
62
  ) {
63
+ const { halfSize, quarterSize, fftSize, sinCosTable } = this
55
64
  const buffers =
56
- mdctBuffers?.[this.fftSize] ??
57
- throwError(`MDCT.transform: mdctBuffers[${this.fftSize}] is required`)
65
+ mdctBuffers?.[fftSize] ??
66
+ throwError(`MDCT.transform: mdctBuffers[${fftSize}] is required`)
58
67
  const real =
59
68
  buffers?.real ??
60
- throwError(
61
- `MDCT.transform: mdctBuffers[${this.fftSize}].real is required`
62
- )
69
+ throwError(`MDCT.transform: mdctBuffers[${fftSize}].real is required`)
63
70
  const imag =
64
71
  buffers?.imaginary ??
65
72
  throwError(
66
- `MDCT.transform: mdctBuffers[${this.fftSize}].imaginary is required`
73
+ `MDCT.transform: mdctBuffers[${fftSize}].imaginary is required`
67
74
  )
68
75
 
69
- const n4 = this.quarterSize
76
+ const n4 = quarterSize
70
77
  const n34 = 3 * n4
71
78
 
72
79
  real.fill(0)
@@ -81,14 +88,14 @@ export class MDCT extends MdctBase {
81
88
 
82
89
  const r = input[i1] + input[i2]
83
90
  const im = input[i3] - input[i4]
84
- const c = this.sinCosTable[i]
85
- const s = this.sinCosTable[i + 1]
91
+ const c = sinCosTable[i]
92
+ const s = sinCosTable[i + 1]
86
93
 
87
94
  real[i >> 1] = r * c + im * s
88
95
  imag[i >> 1] = im * c - r * s
89
96
  }
90
97
 
91
- for (let i = n4; i < this.halfSize; i += 2) {
98
+ for (let i = n4; i < halfSize; i += 2) {
92
99
  const idx = i >> 1
93
100
  const i1 = n34 - 1 - i
94
101
  const i2 = i - n4
@@ -97,8 +104,8 @@ export class MDCT extends MdctBase {
97
104
 
98
105
  const r = input[i1] - input[i2]
99
106
  const im = input[i3] + input[i4]
100
- const c = this.sinCosTable[i]
101
- const s = this.sinCosTable[i + 1]
107
+ const c = sinCosTable[i]
108
+ const s = sinCosTable[i + 1]
102
109
 
103
110
  real[idx] = r * c + im * s
104
111
  imag[idx] = im * c - r * s
@@ -107,15 +114,15 @@ export class MDCT extends MdctBase {
107
114
  FFT.transform(real, imag)
108
115
 
109
116
  // Post-FFT processing
110
- const output = destination ?? new Float32Array(this.halfSize)
111
- for (let i = 0; i < this.fftSize; i++) {
112
- const c = this.sinCosTable[i * 2]
113
- const s = this.sinCosTable[i * 2 + 1]
117
+ const output = destination ?? new Float32Array(halfSize)
118
+ for (let i = 0; i < fftSize; i++) {
119
+ const c = sinCosTable[i * 2]
120
+ const s = sinCosTable[i * 2 + 1]
114
121
  const re = real[i]
115
122
  const im = imag[i]
116
123
 
117
124
  output[destinationOffset + i * 2] = -re * c - im * s
118
- output[destinationOffset + this.halfSize - 1 - i * 2] = -re * s + im * c
125
+ output[destinationOffset + halfSize - 1 - i * 2] = -re * s + im * c
119
126
  }
120
127
 
121
128
  return output
@@ -133,8 +140,12 @@ export class IMDCT extends MdctBase {
133
140
  /**
134
141
  * Perform inverse MDCT transform
135
142
  * @param {Float32Array} input - Frequency-domain MDCT coefficients
136
- * @param {Object} mdctBuffers - Optional work buffers for FFT
143
+ * @param {Object} mdctBuffers - Required work buffers keyed by FFT size
144
+ * @param {Float32Array|null} [destination=null] - Optional output buffer
145
+ * @param {i32} [destinationOffset=0] - First output index in destination
137
146
  * @returns {Float32Array} Time-domain output samples
147
+ * @throws {Error} If the required FFT work buffers are missing
148
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
138
149
  */
139
150
  transform(
140
151
  input,
@@ -142,33 +153,32 @@ export class IMDCT extends MdctBase {
142
153
  destination = null,
143
154
  destinationOffset = 0
144
155
  ) {
156
+ const { size, halfSize, quarterSize, fftSize, sinCosTable } = this
145
157
  const buffers =
146
- mdctBuffers?.[this.fftSize] ??
147
- throwError(`IMDCT.transform: mdctBuffers[${this.fftSize}] is required`)
158
+ mdctBuffers?.[fftSize] ??
159
+ throwError(`IMDCT.transform: mdctBuffers[${fftSize}] is required`)
148
160
  const real =
149
161
  buffers?.real ??
150
- throwError(
151
- `IMDCT.transform: mdctBuffers[${this.fftSize}].real is required`
152
- )
162
+ throwError(`IMDCT.transform: mdctBuffers[${fftSize}].real is required`)
153
163
  const imag =
154
164
  buffers?.imaginary ??
155
165
  throwError(
156
- `IMDCT.transform: mdctBuffers[${this.fftSize}].imaginary is required`
166
+ `IMDCT.transform: mdctBuffers[${fftSize}].imaginary is required`
157
167
  )
158
168
 
159
- const n4 = this.quarterSize
169
+ const n4 = quarterSize
160
170
  const n34 = 3 * n4
161
171
 
162
172
  real.fill(0)
163
173
  imag.fill(0)
164
174
 
165
175
  // Pre-FFT processing
166
- for (let i = 0; i < this.fftSize; i++) {
176
+ for (let i = 0; i < fftSize; i++) {
167
177
  const i2 = i * 2
168
178
  const r = -input[i2]
169
- const im = -input[this.halfSize - 1 - i2]
170
- const c = this.sinCosTable[i2]
171
- const s = this.sinCosTable[i2 + 1]
179
+ const im = -input[halfSize - 1 - i2]
180
+ const c = sinCosTable[i2]
181
+ const s = sinCosTable[i2 + 1]
172
182
 
173
183
  real[i] = im * s + r * c
174
184
  imag[i] = im * c - r * s
@@ -177,12 +187,12 @@ export class IMDCT extends MdctBase {
177
187
  FFT.transform(real, imag)
178
188
 
179
189
  // Post-FFT butterfly
180
- const output = destination ?? new Float32Array(this.size)
190
+ const output = destination ?? new Float32Array(size)
181
191
 
182
- for (let i = 0; i < this.fftSize / 2; i++) {
192
+ for (let i = 0; i < fftSize / 2; i++) {
183
193
  const i2 = i * 2
184
- const c = this.sinCosTable[i2]
185
- const s = this.sinCosTable[i2 + 1]
194
+ const c = sinCosTable[i2]
195
+ const s = sinCosTable[i2 + 1]
186
196
  const re = real[i]
187
197
  const im = imag[i]
188
198
 
@@ -195,11 +205,11 @@ export class IMDCT extends MdctBase {
195
205
  output[destinationOffset + n4 - 1 - i2] = -i1
196
206
  }
197
207
 
198
- for (let i = this.fftSize / 2; i < this.fftSize; i++) {
199
- const idx = (i - this.fftSize / 2) * 2 + n4
208
+ for (let i = fftSize / 2; i < fftSize; i++) {
209
+ const idx = (i - fftSize / 2) * 2 + n4
200
210
  const i2 = i * 2
201
- const c = this.sinCosTable[i2]
202
- const s = this.sinCosTable[i2 + 1]
211
+ const c = sinCosTable[i2]
212
+ const s = sinCosTable[i2 + 1]
203
213
  const re = real[i]
204
214
  const im = imag[i]
205
215