carta1 1.8.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,461 @@
1
+ /**
2
+ * Carta1 waterfill tuning, Pareto perceptual bit exchange, and scale refinement.
3
+ */
4
+
5
+ import {
6
+ MAX_WORD_LENGTH_INDEX,
7
+ MIN_SLACK_FILL_BITS,
8
+ PARETO_EXCHANGE_PASSES,
9
+ TUNE_BINARY_SEARCH_STEPS,
10
+ } from '../core/constants.js'
11
+ import { WORD_LENGTH_BITS } from '../core/tables.js'
12
+ import {
13
+ getCachedBfuDistortion,
14
+ measureBfuQuantizationError,
15
+ } from './distortion.js'
16
+
17
+ /**
18
+ * Tune a global waterfill offset so integer word lengths fit the frame budget.
19
+ *
20
+ * @param {i32} candidateBfuCount
21
+ * @param {i32} bitBudget
22
+ * @param {Array<number>} bfuSizes
23
+ * @param {Float64Array} energies
24
+ * @param {Float64Array} seedThresholds
25
+ * @param {Int32Array} candidateWordLengths
26
+ * @returns {i32} Total coded sample bits used.
27
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
28
+ */
29
+ export function tuneToBudget(
30
+ candidateBfuCount,
31
+ bitBudget,
32
+ bfuSizes,
33
+ energies,
34
+ seedThresholds,
35
+ candidateWordLengths
36
+ ) {
37
+ /** @type {f64} */
38
+ let minimumSeed = 1e9
39
+ /** @type {f64} */
40
+ let maximumSeed = -1e9
41
+ let hasActive = 0
42
+
43
+ for (let unit = 0; unit < candidateBfuCount; unit++) {
44
+ const size = bfuSizes[unit] | 0
45
+ if (energies[unit] > 0.0 && size > 0) {
46
+ const seed = seedThresholds[unit]
47
+ if (seed < minimumSeed) minimumSeed = seed
48
+ if (seed > maximumSeed) maximumSeed = seed
49
+ hasActive = 1
50
+ }
51
+ }
52
+
53
+ if (hasActive === 0 || bitBudget <= 0) {
54
+ for (let unit = 0; unit < candidateBfuCount; unit++) {
55
+ candidateWordLengths[unit] = 0
56
+ }
57
+ return 0
58
+ }
59
+
60
+ /** @type {f64} */
61
+ let lowerBound = minimumSeed - 16.0
62
+ /** @type {f64} */
63
+ let upperBound = maximumSeed + 2.0
64
+
65
+ for (let step = 0; step < TUNE_BINARY_SEARCH_STEPS; step++) {
66
+ const midpoint = 0.5 * (lowerBound + upperBound)
67
+ let bits = 0
68
+ for (let unit = 0; unit < candidateBfuCount; unit++) {
69
+ const size = bfuSizes[unit] | 0
70
+ if (energies[unit] <= 0.0 || size <= 0) continue
71
+ const rawWordLength = Math.floor(seedThresholds[unit] - midpoint + 0.5)
72
+ /** @type {i32} */
73
+ let wordLength = 0
74
+ if (rawWordLength >= MAX_WORD_LENGTH_INDEX) {
75
+ wordLength = MAX_WORD_LENGTH_INDEX
76
+ } else if (rawWordLength > 0.0) {
77
+ wordLength = rawWordLength | 0
78
+ }
79
+ bits += WORD_LENGTH_BITS[wordLength] * size
80
+ }
81
+ if (bits <= bitBudget) {
82
+ upperBound = midpoint
83
+ } else {
84
+ lowerBound = midpoint
85
+ }
86
+ }
87
+
88
+ let usedBits = 0
89
+ for (let unit = 0; unit < candidateBfuCount; unit++) {
90
+ const size = bfuSizes[unit] | 0
91
+ if (energies[unit] <= 0.0 || size <= 0) {
92
+ candidateWordLengths[unit] = 0
93
+ continue
94
+ }
95
+ const rawWordLength = Math.floor(seedThresholds[unit] - upperBound + 0.5)
96
+ /** @type {i32} */
97
+ let wordLength = 0
98
+ if (rawWordLength >= MAX_WORD_LENGTH_INDEX) {
99
+ wordLength = MAX_WORD_LENGTH_INDEX
100
+ } else if (rawWordLength > 0.0) {
101
+ wordLength = rawWordLength | 0
102
+ }
103
+ candidateWordLengths[unit] = wordLength
104
+ usedBits += WORD_LENGTH_BITS[wordLength] * size
105
+ }
106
+
107
+ return usedBits
108
+ }
109
+
110
+ /**
111
+ * Exchange bit steps from high-supply donors to perceptually under-allocated bands.
112
+ *
113
+ * @param {i32} candidateBfuCount
114
+ * @param {i32} bitBudget
115
+ * @param {i32} usedBits
116
+ * @param {Array<Float32Array>} bfuData
117
+ * @param {Array<number>} bfuSizes
118
+ * @param {Int32Array} initialScaleFactorIndices
119
+ * @param {Float64Array} maxAmplitudes
120
+ * @param {Float64Array} energies
121
+ * @param {Float64Array} perceptualWeights
122
+ * @param {Float64Array} distortionCache
123
+ * @param {Int32Array} candidateWordLengths
124
+ * @returns {i32} Updated coded sample bits used.
125
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
126
+ */
127
+ export function exchangePerceptualBits(
128
+ candidateBfuCount,
129
+ bitBudget,
130
+ usedBits,
131
+ bfuData,
132
+ bfuSizes,
133
+ initialScaleFactorIndices,
134
+ maxAmplitudes,
135
+ energies,
136
+ perceptualWeights,
137
+ distortionCache,
138
+ candidateWordLengths
139
+ ) {
140
+ for (let pass = 0; pass < PARETO_EXCHANGE_PASSES; pass++) {
141
+ /** @type {i32} */
142
+ let bestReceiver = -1
143
+ let bestReceiverNextWordLength = 0
144
+ let bestReceiverCost = 0
145
+ /** @type {f64} */
146
+ let bestReceiverBenefitPerBit = 0.0
147
+
148
+ for (let unit = 0; unit < candidateBfuCount; unit++) {
149
+ const size = bfuSizes[unit] | 0
150
+ const wordLength = candidateWordLengths[unit]
151
+ if (
152
+ energies[unit] <= 0.0 ||
153
+ size <= 0 ||
154
+ wordLength >= MAX_WORD_LENGTH_INDEX
155
+ )
156
+ continue
157
+
158
+ const weight = perceptualWeights[unit]
159
+ /** @type {f64} */
160
+ const currentDistortion = getCachedBfuDistortion(
161
+ unit,
162
+ wordLength,
163
+ bfuData,
164
+ bfuSizes,
165
+ initialScaleFactorIndices,
166
+ maxAmplitudes,
167
+ distortionCache
168
+ )
169
+ /** @type {i32} */
170
+ let maxJump = wordLength + 1
171
+ if (wordLength === 0) {
172
+ maxJump = 3
173
+ }
174
+ if (maxJump > MAX_WORD_LENGTH_INDEX) {
175
+ maxJump = MAX_WORD_LENGTH_INDEX
176
+ }
177
+
178
+ for (
179
+ let nextWordLength = wordLength + 1;
180
+ nextWordLength <= maxJump;
181
+ nextWordLength++
182
+ ) {
183
+ const cost =
184
+ (WORD_LENGTH_BITS[nextWordLength] - WORD_LENGTH_BITS[wordLength]) *
185
+ size
186
+ if (cost <= 0 || cost > bitBudget) continue
187
+ /** @type {f64} */
188
+ const nextDistortion = getCachedBfuDistortion(
189
+ unit,
190
+ nextWordLength,
191
+ bfuData,
192
+ bfuSizes,
193
+ initialScaleFactorIndices,
194
+ maxAmplitudes,
195
+ distortionCache
196
+ )
197
+ const gain = (currentDistortion - nextDistortion) * weight
198
+ const benefitPerBit = gain / cost
199
+ if (benefitPerBit > bestReceiverBenefitPerBit) {
200
+ bestReceiverBenefitPerBit = benefitPerBit
201
+ bestReceiver = unit
202
+ bestReceiverNextWordLength = nextWordLength
203
+ bestReceiverCost = cost
204
+ }
205
+ }
206
+ }
207
+
208
+ if (bestReceiver < 0) break
209
+
210
+ if (usedBits + bestReceiverCost <= bitBudget) {
211
+ candidateWordLengths[bestReceiver] = bestReceiverNextWordLength
212
+ usedBits += bestReceiverCost
213
+ continue
214
+ }
215
+
216
+ /** @type {i32} */
217
+ let bestDonor = -1
218
+ let bestDonorSaved = 0
219
+ /** @type {f64} */
220
+ let bestDonorDamagePerBit = 1e300
221
+
222
+ for (let unit = 0; unit < candidateBfuCount; unit++) {
223
+ if (unit === bestReceiver) continue
224
+ const wordLength = candidateWordLengths[unit]
225
+ const size = bfuSizes[unit] | 0
226
+ if (wordLength <= 0 || size <= 0) continue
227
+
228
+ const saved =
229
+ (WORD_LENGTH_BITS[wordLength] - WORD_LENGTH_BITS[wordLength - 1]) * size
230
+ if (saved <= 0 || usedBits - saved + bestReceiverCost > bitBudget)
231
+ continue
232
+
233
+ /** @type {f64} */
234
+ const currentDistortion = getCachedBfuDistortion(
235
+ unit,
236
+ wordLength,
237
+ bfuData,
238
+ bfuSizes,
239
+ initialScaleFactorIndices,
240
+ maxAmplitudes,
241
+ distortionCache
242
+ )
243
+ /** @type {f64} */
244
+ const lowerDistortion = getCachedBfuDistortion(
245
+ unit,
246
+ wordLength - 1,
247
+ bfuData,
248
+ bfuSizes,
249
+ initialScaleFactorIndices,
250
+ maxAmplitudes,
251
+ distortionCache
252
+ )
253
+ const loss =
254
+ (lowerDistortion - currentDistortion) * perceptualWeights[unit]
255
+ const damagePerBit = loss / saved
256
+ if (damagePerBit < bestDonorDamagePerBit) {
257
+ bestDonorDamagePerBit = damagePerBit
258
+ bestDonor = unit
259
+ bestDonorSaved = saved
260
+ }
261
+ }
262
+
263
+ if (
264
+ bestDonor >= 0 &&
265
+ bestReceiverBenefitPerBit > bestDonorDamagePerBit * 1.02
266
+ ) {
267
+ candidateWordLengths[bestDonor] = candidateWordLengths[bestDonor] - 1
268
+ candidateWordLengths[bestReceiver] = bestReceiverNextWordLength
269
+ usedBits = usedBits - bestDonorSaved + bestReceiverCost
270
+ } else {
271
+ break
272
+ }
273
+ }
274
+
275
+ return usedBits
276
+ }
277
+
278
+ /**
279
+ * Spend remaining budget slack by highest perceptual distortion drop per bit.
280
+ *
281
+ * @param {i32} candidateBfuCount
282
+ * @param {i32} remainingBits
283
+ * @param {Array<Float32Array>} bfuData
284
+ * @param {Array<number>} bfuSizes
285
+ * @param {Int32Array} initialScaleFactorIndices
286
+ * @param {Float64Array} maxAmplitudes
287
+ * @param {Float64Array} energies
288
+ * @param {Float64Array} perceptualWeights
289
+ * @param {Float64Array} distortionCache
290
+ * @param {Int32Array} candidateWordLengths
291
+ * @returns {i32} Remaining unused bits.
292
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
293
+ */
294
+ export function fillSlackBits(
295
+ candidateBfuCount,
296
+ remainingBits,
297
+ bfuData,
298
+ bfuSizes,
299
+ initialScaleFactorIndices,
300
+ maxAmplitudes,
301
+ energies,
302
+ perceptualWeights,
303
+ distortionCache,
304
+ candidateWordLengths
305
+ ) {
306
+ while (remainingBits >= MIN_SLACK_FILL_BITS) {
307
+ /** @type {i32} */
308
+ let bestUnit = -1
309
+ let bestNextWordLength = 0
310
+ let bestCost = 0
311
+ /** @type {f64} */
312
+ let bestScore = 0.0
313
+
314
+ for (let unit = 0; unit < candidateBfuCount; unit++) {
315
+ const size = bfuSizes[unit] | 0
316
+ const wordLength = candidateWordLengths[unit]
317
+ if (
318
+ energies[unit] <= 0.0 ||
319
+ size <= 0 ||
320
+ wordLength >= MAX_WORD_LENGTH_INDEX
321
+ )
322
+ continue
323
+
324
+ /** @type {f64} */
325
+ const currentDistortion = getCachedBfuDistortion(
326
+ unit,
327
+ wordLength,
328
+ bfuData,
329
+ bfuSizes,
330
+ initialScaleFactorIndices,
331
+ maxAmplitudes,
332
+ distortionCache
333
+ )
334
+ const weight = perceptualWeights[unit]
335
+ /** @type {i32} */
336
+ let maxJump = wordLength + 1
337
+ if (wordLength === 0) {
338
+ maxJump = 3
339
+ }
340
+ if (maxJump > MAX_WORD_LENGTH_INDEX) {
341
+ maxJump = MAX_WORD_LENGTH_INDEX
342
+ }
343
+
344
+ for (
345
+ let nextWordLength = wordLength + 1;
346
+ nextWordLength <= maxJump;
347
+ nextWordLength++
348
+ ) {
349
+ const cost =
350
+ (WORD_LENGTH_BITS[nextWordLength] - WORD_LENGTH_BITS[wordLength]) *
351
+ size
352
+ if (cost <= 0 || cost > remainingBits) continue
353
+
354
+ /** @type {f64} */
355
+ const nextDistortion = getCachedBfuDistortion(
356
+ unit,
357
+ nextWordLength,
358
+ bfuData,
359
+ bfuSizes,
360
+ initialScaleFactorIndices,
361
+ maxAmplitudes,
362
+ distortionCache
363
+ )
364
+ const gain = (currentDistortion - nextDistortion) * weight
365
+ if (gain > 0.0) {
366
+ const score = gain / cost
367
+ if (score > bestScore) {
368
+ bestScore = score
369
+ bestUnit = unit
370
+ bestNextWordLength = nextWordLength
371
+ bestCost = cost
372
+ }
373
+ }
374
+ }
375
+ }
376
+
377
+ if (bestUnit < 0) break
378
+ candidateWordLengths[bestUnit] = bestNextWordLength
379
+ remainingBits -= bestCost
380
+ }
381
+
382
+ return remainingBits
383
+ }
384
+
385
+ /**
386
+ * Verify whether lowering scale-factor index by 1 or 2 lowers reconstruction MSE.
387
+ *
388
+ * @param {i32} bestBfuCount
389
+ * @param {i32} maxBfuCount
390
+ * @param {Array<Float32Array>} bfuData
391
+ * @param {Array<number>} bfuSizes
392
+ * @param {Float64Array} energies
393
+ * @param {Int32Array} initialScaleFactorIndices
394
+ * @param {Int32Array} selectedWordLengths
395
+ * @param {Int32Array} refinedScaleFactorIndices
396
+ * @returns {void}
397
+ * @nativeUnchecked Native callers supply frame-bounded buffers and indices.
398
+ */
399
+ export function refineScaleFactors(
400
+ bestBfuCount,
401
+ maxBfuCount,
402
+ bfuData,
403
+ bfuSizes,
404
+ energies,
405
+ initialScaleFactorIndices,
406
+ selectedWordLengths,
407
+ refinedScaleFactorIndices
408
+ ) {
409
+ for (let unit = 0; unit < maxBfuCount; unit++) {
410
+ refinedScaleFactorIndices[unit] = initialScaleFactorIndices[unit]
411
+ }
412
+
413
+ for (let unit = 0; unit < bestBfuCount; unit++) {
414
+ const wordLength = selectedWordLengths[unit]
415
+ const initialIndex = initialScaleFactorIndices[unit]
416
+ const size = bfuSizes[unit] | 0
417
+ if (
418
+ wordLength <= 0 ||
419
+ initialIndex <= 0 ||
420
+ size <= 0 ||
421
+ energies[unit] <= 0.0
422
+ )
423
+ continue
424
+
425
+ /** @type {Float32Array} */
426
+ const bfu = bfuData[unit]
427
+ let bestIndex = initialIndex
428
+ /** @type {f64} */
429
+ let bestError = measureBfuQuantizationError(
430
+ bfu,
431
+ size,
432
+ initialIndex,
433
+ wordLength
434
+ )
435
+ /** @type {i32} */
436
+ let minimumCandidate = 0
437
+ if (initialIndex > 2) {
438
+ minimumCandidate = initialIndex - 2
439
+ }
440
+
441
+ for (
442
+ let candidate = minimumCandidate;
443
+ candidate < initialIndex;
444
+ candidate++
445
+ ) {
446
+ /** @type {f64} */
447
+ const error = measureBfuQuantizationError(
448
+ bfu,
449
+ size,
450
+ candidate,
451
+ wordLength
452
+ )
453
+ if (error < bestError) {
454
+ bestError = error
455
+ bestIndex = candidate
456
+ }
457
+ }
458
+
459
+ refinedScaleFactorIndices[unit] = bestIndex
460
+ }
461
+ }