carta1 1.7.0 → 1.9.0

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.
@@ -0,0 +1,371 @@
1
+ /**
2
+ * Carta1 perceptual masking and reconstruction distortion measurement.
3
+ */
4
+
5
+ import {
6
+ BFU_DISTORTION_CACHE_STRIDE,
7
+ HEARING_THRESHOLD_ENERGY_GATE,
8
+ MASK_EXPONENT_LONG,
9
+ MASK_EXPONENT_SHORT,
10
+ MASK_MIN_FLOOR,
11
+ MASK_RELATIVE_FLOOR,
12
+ MAX_BFU_SIZE,
13
+ } from '../core/constants.js'
14
+ import {
15
+ EAR_WEIGHT_LONG,
16
+ EAR_WEIGHT_SHORT,
17
+ INVERSE_LOG_BFU_SIZES,
18
+ QUANTIZER_RANGES,
19
+ SCALE_FACTORS,
20
+ SCALE_FACTOR_TRIM_RATIOS,
21
+ SPREAD_DOWN,
22
+ SPREAD_UP,
23
+ } from '../core/tables.js'
24
+
25
+ /**
26
+ * Measure exact mid-tread ATRAC1 quantization squared error for one BFU.
27
+ *
28
+ * @param {Float32Array} bfu
29
+ * @param {i32} size
30
+ * @param {i32} scaleFactorIndex
31
+ * @param {i32} wordLength
32
+ * @returns {f64}
33
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
34
+ */
35
+ export function measureBfuQuantizationError(
36
+ bfu,
37
+ size,
38
+ scaleFactorIndex,
39
+ wordLength
40
+ ) {
41
+ if (wordLength <= 0) {
42
+ /** @type {f64} */
43
+ let energy = 0.0
44
+ for (let i = 0; i < size; i++) {
45
+ const value = bfu[i]
46
+ energy += value * value
47
+ }
48
+ return energy
49
+ }
50
+
51
+ const quantizerRange = QUANTIZER_RANGES[wordLength]
52
+ const scaleFactor = SCALE_FACTORS[scaleFactorIndex]
53
+ const normalizationFactor = quantizerRange / scaleFactor
54
+ const inverseQuantizerRange = 1.0 / quantizerRange
55
+ /** @type {f64} */
56
+ let error = 0.0
57
+
58
+ for (let i = 0; i < size; i++) {
59
+ const coefficient = bfu[i]
60
+ const scaled = coefficient * normalizationFactor
61
+ /** @type {i32} */
62
+ let quantizedCode = 0
63
+ if (scaled >= quantizerRange) {
64
+ quantizedCode = quantizerRange
65
+ } else if (scaled <= -quantizerRange) {
66
+ quantizedCode = -quantizerRange
67
+ } else {
68
+ quantizedCode = (scaled + (scaled >= 0.0 ? 0.5 : -0.5)) | 0
69
+ }
70
+ const dequantizedValue = quantizedCode * scaleFactor * inverseQuantizerRange
71
+ const difference = coefficient - dequantizedValue
72
+ error += difference * difference
73
+ }
74
+
75
+ return error
76
+ }
77
+
78
+ /**
79
+ * Look up or compute the lazily cached BFU distortion for a candidate word length.
80
+ *
81
+ * @param {i32} bfuIndex
82
+ * @param {i32} wordLength
83
+ * @param {Array<Float32Array>} bfuData
84
+ * @param {Array<number>} bfuSizes
85
+ * @param {Int32Array} initialScaleFactorIndices
86
+ * @param {Float64Array} maxAmplitudes
87
+ * @param {Float64Array} distortionCache
88
+ * @returns {f64}
89
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
90
+ */
91
+ export function getCachedBfuDistortion(
92
+ bfuIndex,
93
+ wordLength,
94
+ bfuData,
95
+ bfuSizes,
96
+ initialScaleFactorIndices,
97
+ maxAmplitudes,
98
+ distortionCache
99
+ ) {
100
+ const slot = bfuIndex * BFU_DISTORTION_CACHE_STRIDE + wordLength
101
+ const cached = distortionCache[slot]
102
+ if (cached >= 0.0) return cached
103
+
104
+ let scaleFactorIndex = initialScaleFactorIndices[bfuIndex]
105
+ if (
106
+ wordLength > 0 &&
107
+ scaleFactorIndex > 0 &&
108
+ SCALE_FACTORS[scaleFactorIndex - 1] >=
109
+ maxAmplitudes[bfuIndex] * SCALE_FACTOR_TRIM_RATIOS[wordLength]
110
+ ) {
111
+ scaleFactorIndex = scaleFactorIndex - 1
112
+ }
113
+
114
+ /** @type {Float32Array} */
115
+ const bfu = bfuData[bfuIndex]
116
+ const size = bfuSizes[bfuIndex] | 0
117
+ const distortion = measureBfuQuantizationError(
118
+ bfu,
119
+ size,
120
+ scaleFactorIndex,
121
+ wordLength
122
+ )
123
+ distortionCache[slot] = distortion
124
+ return distortion
125
+ }
126
+
127
+ /**
128
+ * Build per-BFU simultaneous masking thresholds with short-block time-slice isolation.
129
+ *
130
+ * @param {Float64Array} energies
131
+ * @param {Float64Array} maxAmplitudes
132
+ * @param {Array<number>} bfuSizes
133
+ * @param {i32} maxBfuCount
134
+ * @param {f64} totalEnergy
135
+ * @param {i32} lowBandMode
136
+ * @param {i32} midBandMode
137
+ * @param {i32} highBandMode
138
+ * @param {Float64Array} maskThresholds
139
+ * @returns {void}
140
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
141
+ */
142
+ export function buildPerceptualMask(
143
+ energies,
144
+ maxAmplitudes,
145
+ bfuSizes,
146
+ maxBfuCount,
147
+ totalEnergy,
148
+ lowBandMode,
149
+ midBandMode,
150
+ highBandMode,
151
+ maskThresholds
152
+ ) {
153
+ for (let unit = 0; unit < maxBfuCount; unit++) {
154
+ maskThresholds[unit] = 0.0
155
+ }
156
+
157
+ const downSpan = SPREAD_DOWN.length - 1
158
+ const upLength = SPREAD_UP.length
159
+
160
+ for (let sourceUnit = 0; sourceUnit < maxBfuCount; sourceUnit++) {
161
+ const energy = energies[sourceUnit]
162
+ if (energy <= 0.0) continue
163
+
164
+ const size = bfuSizes[sourceUnit] | 0
165
+ if (size <= 0) continue
166
+
167
+ const peak = maxAmplitudes[sourceUnit]
168
+ const peakEnergy = peak * peak
169
+ const rawConcentration = (peakEnergy * size) / energy
170
+ const concentration = rawConcentration < 1.0 ? 1.0 : rawConcentration
171
+ /** @type {f64} */
172
+ let inverseLogSize = 0.0
173
+ if (size <= MAX_BFU_SIZE) {
174
+ inverseLogSize = INVERSE_LOG_BFU_SIZES[size]
175
+ } else {
176
+ inverseLogSize = 1.0 / Math.log(size)
177
+ }
178
+ const shape =
179
+ size > 1 ? Math.min(1.0, Math.log(concentration) * inverseLogSize) : 0.0
180
+
181
+ let isShort = false
182
+ let frequencyPosition = sourceUnit
183
+ if (sourceUnit < 20) {
184
+ isShort = lowBandMode !== 0
185
+ if (isShort) frequencyPosition = (sourceUnit >> 2) * 4
186
+ } else if (sourceUnit < 36) {
187
+ isShort = midBandMode !== 0
188
+ if (isShort) frequencyPosition = 20 + ((sourceUnit - 20) >> 2) * 4
189
+ } else {
190
+ isShort = highBandMode !== 0
191
+ if (isShort) frequencyPosition = 36 + ((sourceUnit - 36) >> 3) * 8
192
+ }
193
+
194
+ const tonal = 14.5 + frequencyPosition * 0.3
195
+ const offset = shape * tonal + (1.0 - shape) * 5.5
196
+ const level = energy * Math.pow(10.0, -offset * 0.1)
197
+ if (level <= 0.0) continue
198
+
199
+ if (!isShort) {
200
+ let lowerLimit = 0
201
+ if (sourceUnit >= 36) {
202
+ lowerLimit = midBandMode !== 0 ? 36 : 0
203
+ } else if (sourceUnit >= 20) {
204
+ lowerLimit = lowBandMode !== 0 ? 20 : 0
205
+ }
206
+
207
+ let upperLimit = maxBfuCount
208
+ if (sourceUnit < 20) {
209
+ if (midBandMode !== 0 && 20 < maxBfuCount) upperLimit = 20
210
+ } else if (sourceUnit < 36) {
211
+ if (highBandMode !== 0 && 36 < maxBfuCount) upperLimit = 36
212
+ }
213
+
214
+ /** @type {i32} */
215
+ const candidateLower = sourceUnit - downSpan
216
+ /** @type {i32} */
217
+ const firstLower =
218
+ candidateLower > lowerLimit ? candidateLower : lowerLimit
219
+ for (let target = firstLower; target < sourceUnit; target++) {
220
+ maskThresholds[target] =
221
+ maskThresholds[target] + level * SPREAD_DOWN[sourceUnit - target]
222
+ }
223
+
224
+ /** @type {i32} */
225
+ const candidateUpper = sourceUnit + upLength
226
+ /** @type {i32} */
227
+ const upperEnd = candidateUpper < upperLimit ? candidateUpper : upperLimit
228
+ for (let target = sourceUnit; target < upperEnd; target++) {
229
+ maskThresholds[target] =
230
+ maskThresholds[target] + level * SPREAD_UP[target - sourceUnit]
231
+ }
232
+ } else {
233
+ let bandBase = 0
234
+ let strideShift = 2
235
+ let timeSlice = 0
236
+ let frequencyGroup = 0
237
+ let frequencyGroupCount = 5
238
+ if (sourceUnit < 20) {
239
+ bandBase = 0
240
+ strideShift = 2
241
+ timeSlice = sourceUnit & 3
242
+ frequencyGroup = sourceUnit >> 2
243
+ frequencyGroupCount = 5
244
+ } else if (sourceUnit < 36) {
245
+ bandBase = 20
246
+ strideShift = 2
247
+ timeSlice = (sourceUnit - 20) & 3
248
+ frequencyGroup = (sourceUnit - 20) >> 2
249
+ frequencyGroupCount = 4
250
+ } else {
251
+ bandBase = 36
252
+ strideShift = 3
253
+ timeSlice = (sourceUnit - 36) & 7
254
+ frequencyGroup = (sourceUnit - 36) >> 3
255
+ frequencyGroupCount = 2
256
+ }
257
+
258
+ for (let downOffset = 1; downOffset <= downSpan; downOffset++) {
259
+ const targetGroup = frequencyGroup - downOffset
260
+ if (targetGroup >= 0) {
261
+ const target = bandBase + (targetGroup << strideShift) + timeSlice
262
+ if (target < maxBfuCount) {
263
+ maskThresholds[target] =
264
+ maskThresholds[target] + level * SPREAD_DOWN[downOffset]
265
+ }
266
+ }
267
+ }
268
+
269
+ for (let upOffset = 0; upOffset < upLength; upOffset++) {
270
+ const targetGroup = frequencyGroup + upOffset
271
+ if (targetGroup < frequencyGroupCount) {
272
+ const target = bandBase + (targetGroup << strideShift) + timeSlice
273
+ if (target < maxBfuCount) {
274
+ maskThresholds[target] =
275
+ maskThresholds[target] + level * SPREAD_UP[upOffset]
276
+ }
277
+ }
278
+ }
279
+ }
280
+ }
281
+
282
+ const maskFloor =
283
+ (totalEnergy / maxBfuCount) * MASK_RELATIVE_FLOOR + MASK_MIN_FLOOR
284
+ for (let unit = 0; unit < maxBfuCount; unit++) {
285
+ maskThresholds[unit] = maskThresholds[unit] + maskFloor
286
+ }
287
+ }
288
+
289
+ /**
290
+ * Derive perceptual error weights and continuous waterfill seed thresholds.
291
+ *
292
+ * @param {Float64Array} energies
293
+ * @param {Float64Array} maxAmplitudes
294
+ * @param {Int32Array} initialScaleFactorIndices
295
+ * @param {Array<number>} bfuSizes
296
+ * @param {i32} maxBfuCount
297
+ * @param {f64} allocationBias
298
+ * @param {i32} lowBandMode
299
+ * @param {i32} midBandMode
300
+ * @param {i32} highBandMode
301
+ * @param {Float64Array} maskThresholds
302
+ * @param {Float64Array} perceptualWeights
303
+ * @param {Float64Array} seedThresholds
304
+ * @returns {void}
305
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
306
+ */
307
+ export function buildPerceptualWeights(
308
+ energies,
309
+ maxAmplitudes,
310
+ initialScaleFactorIndices,
311
+ bfuSizes,
312
+ maxBfuCount,
313
+ allocationBias,
314
+ lowBandMode,
315
+ midBandMode,
316
+ highBandMode,
317
+ maskThresholds,
318
+ perceptualWeights,
319
+ seedThresholds
320
+ ) {
321
+ const biasExponent = (allocationBias - 1.0) * 0.5
322
+
323
+ for (let unit = 0; unit < maxBfuCount; unit++) {
324
+ const energy = energies[unit]
325
+ const size = bfuSizes[unit] | 0
326
+ if (energy <= 0.0 || size <= 0) {
327
+ perceptualWeights[unit] = 0.0
328
+ seedThresholds[unit] = -1e9
329
+ continue
330
+ }
331
+
332
+ const isShort =
333
+ unit < 20
334
+ ? lowBandMode !== 0
335
+ : unit < 36
336
+ ? midBandMode !== 0
337
+ : highBandMode !== 0
338
+ /** @type {f64} */
339
+ let earWeight = EAR_WEIGHT_LONG[unit]
340
+ /** @type {f64} */
341
+ let maskExponent = MASK_EXPONENT_LONG
342
+ if (isShort) {
343
+ earWeight = EAR_WEIGHT_SHORT[unit]
344
+ maskExponent = MASK_EXPONENT_SHORT
345
+ }
346
+ const effectiveMask =
347
+ maskThresholds[unit] +
348
+ HEARING_THRESHOLD_ENERGY_GATE / Math.max(earWeight, 1e-6)
349
+ /** @type {f64} */
350
+ let weight = earWeight / Math.pow(effectiveMask, maskExponent)
351
+
352
+ if (biasExponent !== 0.0) {
353
+ const scaleFactorIndex = initialScaleFactorIndices[unit]
354
+ /** @type {f64} */
355
+ let referenceScaleFactor = SCALE_FACTORS[scaleFactorIndex]
356
+ if (scaleFactorIndex === 0) {
357
+ referenceScaleFactor = Math.max(maxAmplitudes[unit], 1e-12)
358
+ }
359
+ weight *= Math.pow(
360
+ referenceScaleFactor * referenceScaleFactor,
361
+ biasExponent
362
+ )
363
+ }
364
+
365
+ perceptualWeights[unit] = weight
366
+ const maxAmplitude = maxAmplitudes[unit]
367
+ const effectiveVariance =
368
+ 0.5 * (energy / size) + 0.5 * maxAmplitude * maxAmplitude
369
+ seedThresholds[unit] = 0.5 * Math.log2(effectiveVariance * weight)
370
+ }
371
+ }