@siteed/audio-studio 3.2.0-beta.1 → 3.2.0

package/src/streamAudioData.ts

@@ -39,6 +39,11 @@ export interface StreamAudioDataOptions {
     maxChunkBytes?: number
     /** Max chunks queued in native before JS ack pauses decode (default: 4). */
     maxBufferedChunks?: number
+    /**
+     * Optional timeout for a chunk acknowledgement while backpressure is active.
+     * Undefined/0 disables timeout so long transcription callbacks can run.
+     */
+    backpressureTimeoutMs?: number
     /** Output PCM format; only `'float32'` supported today. */
     streamFormat?: 'float32'
     /** Abort the in-flight request. Resolves promise with `cancelled: true`. */
@@ -151,15 +156,15 @@ function toFloat32(samples: unknown): Float32Array {
     }
     if (typeof samples === 'string') {
         const bytes = base64ToBytes(samples)
-        const aligned =
-            bytes.byteOffset % 4 === 0
-                ? new Float32Array(
-                      bytes.buffer,
-                      bytes.byteOffset,
-                      bytes.byteLength / 4
-                  )
-                : new Float32Array(bytes.buffer.slice(bytes.byteOffset))
-        return new Float32Array(aligned)
+        const floatLength = Math.floor(bytes.byteLength / 4)
+        if (bytes.byteOffset % 4 === 0) {
+            return new Float32Array(bytes.buffer, bytes.byteOffset, floatLength)
+        }
+        const sliced = bytes.buffer.slice(
+            bytes.byteOffset,
+            bytes.byteOffset + bytes.byteLength
+        )
+        return new Float32Array(sliced, 0, Math.floor(sliced.byteLength / 4))
     }
     if (samples && typeof samples === 'object' && 'length' in samples) {
         // ArrayLike fallback
@@ -178,7 +183,13 @@ function base64ToBytes(input: string): Uint8Array {
     const g = globalThis as { atob?: (s: string) => string }
     if (typeof g.atob !== 'function') {
         // Buffer path for environments without atob; React Native has atob.
-        const Buf = (globalThis as { Buffer?: { from: Function } }).Buffer
+        const Buf = (
+            globalThis as {
+                Buffer?: {
+                    from: (input: string, encoding: string) => Uint8Array
+                }
+            }
+        ).Buffer
         if (Buf) return new Uint8Array(Buf.from(input, 'base64'))
         return new Uint8Array(0)
     }
@@ -188,35 +199,70 @@ function base64ToBytes(input: string): Uint8Array {
     return out
 }
 
+function rejectInvalidRange(message: string): never {
+    throw new AudioStreamError({
+        code: 'ERR_AUDIO_STREAM_INVALID_RANGE',
+        message,
+        recoverable: false,
+    })
+}
+
+function assertPositiveFiniteOption(
+    value: number | undefined,
+    name: string,
+    integer = false
+): void {
+    if (value === undefined) return
+    if (
+        !Number.isFinite(value) ||
+        value <= 0 ||
+        (integer && !Number.isInteger(value))
+    ) {
+        rejectInvalidRange(
+            `${name} must be a positive${integer ? ' integer' : ''}`
+        )
+    }
+}
+
 function validateOptions(options: StreamAudioDataOptions): void {
     if (!options.fileUri) {
-        throw new AudioStreamError({
-            code: 'ERR_AUDIO_STREAM_INVALID_RANGE',
-            message: 'fileUri is required',
-            recoverable: false,
-        })
+        rejectInvalidRange('fileUri is required')
     }
     if (
         options.startTimeMs !== undefined &&
         options.endTimeMs !== undefined &&
         options.startTimeMs >= options.endTimeMs
     ) {
-        throw new AudioStreamError({
-            code: 'ERR_AUDIO_STREAM_INVALID_RANGE',
-            message: 'startTimeMs must be < endTimeMs',
-            recoverable: false,
-        })
+        rejectInvalidRange('startTimeMs must be < endTimeMs')
+    }
+    if (options.endTimeMs !== undefined && options.endTimeMs <= 0) {
+        rejectInvalidRange('endTimeMs must be > 0')
+    }
+    if (options.startTimeMs !== undefined && options.startTimeMs < 0) {
+        rejectInvalidRange('startTimeMs must be >= 0')
     }
     if (
         options.chunkDurationMs !== undefined &&
         (options.chunkDurationMs < 10 || options.chunkDurationMs > 60000)
     ) {
-        throw new AudioStreamError({
-            code: 'ERR_AUDIO_STREAM_INVALID_RANGE',
-            message: 'chunkDurationMs must be in [10, 60000]',
-            recoverable: false,
-        })
+        rejectInvalidRange('chunkDurationMs must be in [10, 60000]')
     }
+    if (
+        options.backpressureTimeoutMs !== undefined &&
+        options.backpressureTimeoutMs < 0
+    ) {
+        rejectInvalidRange('backpressureTimeoutMs must be >= 0')
+    }
+    assertPositiveFiniteOption(options.targetSampleRate, 'targetSampleRate')
+    assertPositiveFiniteOption(options.sampleRate, 'sampleRate')
+    assertPositiveFiniteOption(options.channels, 'channels', true)
+    assertPositiveFiniteOption(
+        options.maxBufferedChunks,
+        'maxBufferedChunks',
+        true
+    )
+    assertPositiveFiniteOption(options.maxChunkBytes, 'maxChunkBytes', true)
+
     if (
         options.streamFormat !== undefined &&
         options.streamFormat !== 'float32'
@@ -315,6 +361,7 @@ async function streamAudioDataNative(
     let processingChain: Promise<void> = Promise.resolve()
     let settled = false
     let abortListener: (() => void) | null = null
+    let lastProgress: StreamAudioDataProgress | null = null
 
     const finalize = () => {
         for (const sub of subs) {
@@ -413,6 +460,7 @@ async function streamAudioDataNative(
                 emitter.addListener(PROGRESS_EVENT, (raw: unknown) => {
                     const evt = raw as StreamAudioDataProgress
                     if (evt.requestId !== requestId) return
+                    lastProgress = evt
                     callbacks.onProgress!(evt)
                 })
             )
@@ -435,7 +483,10 @@ async function streamAudioDataNative(
                     .then(() => {
                         settle(() => {}, 'resolve', {
                             requestId,
-                            durationMs: evt.durationMs,
+                            durationMs:
+                                evt.durationMs > 0
+                                    ? evt.durationMs
+                                    : (lastProgress?.durationMs ?? 0),
                             sampleRate: evt.sampleRate,
                             channels: evt.channels,
                             chunks: evt.chunks ?? chunkCount,
@@ -462,7 +513,7 @@ async function streamAudioDataNative(
                         .then(() => {
                             settle(() => {}, 'resolve', {
                                 requestId,
-                                durationMs: 0,
+                                durationMs: lastProgress?.durationMs ?? 0,
                                 sampleRate:
                                     options.targetSampleRate ??
                                     options.sampleRate ??
@@ -494,7 +545,7 @@ async function streamAudioDataNative(
             if (options.signal.aborted) {
                 settle(() => {}, 'resolve', {
                     requestId,
-                    durationMs: 0,
+                    durationMs: lastProgress?.durationMs ?? 0,
                     sampleRate:
                         options.targetSampleRate ?? options.sampleRate ?? 0,
                     channels: options.channels ?? 1,
@@ -547,8 +598,8 @@ async function streamAudioDataWeb(
     try {
         const processed = await processAudioBuffer({
             fileUri: options.fileUri,
-            targetSampleRate: options.targetSampleRate ?? 16000,
-            targetChannels: options.channels ?? 1,
+            targetSampleRate: options.targetSampleRate,
+            targetChannels: options.channels,
             normalizeAudio: options.normalizeAudio ?? true,
             startTimeMs: options.startTimeMs,
             endTimeMs: options.endTimeMs,
@@ -559,16 +610,34 @@ async function streamAudioDataWeb(
         const durationMs = processed.durationMs
         const chunkDurationMs = options.chunkDurationMs ?? 1000
         let samplesPerChunk = Math.max(
-            1,
+            channels,
             Math.floor((chunkDurationMs / 1000) * sampleRate) * channels
         )
         if (options.maxChunkBytes) {
-            const maxSamples = Math.floor(options.maxChunkBytes / 4)
-            samplesPerChunk = Math.min(samplesPerChunk, maxSamples)
+            // Round down to a multiple of `channels` so we never split an
+            // interleaved frame across two chunks (that would produce a
+            // fractional `startSample` for the next chunk).
+            const rawMax = Math.floor(options.maxChunkBytes / 4)
+            const maxSamples = Math.max(
+                channels,
+                Math.floor(rawMax / channels) * channels
+            )
+            samplesPerChunk = Math.max(
+                channels,
+                Math.min(samplesPerChunk, maxSamples)
+            )
         }
 
-        const all = sanitizeFloat32(processed.channelData, options.normalizeAudio ?? true)
+        const all = sanitizeFloat32(
+            interleaveBuffer(processed.buffer, channels),
+            options.normalizeAudio ?? true
+        )
 
+        // Chunk timestamps are absolute (range start + offset) on every
+        // platform; progress is *elapsed within the range* so the
+        // `processedMs / durationMs` fraction stays in [0, 1] regardless of
+        // `startTimeMs`. The native decoders use the same split.
+        const rangeStartMs = options.startTimeMs ?? 0
         let chunkIndex = 0
         let emittedSamples = 0
         for (let off = 0; off < all.length; off += samplesPerChunk) {
@@ -587,11 +656,15 @@ async function streamAudioDataWeb(
             const slice = all.slice(off, end)
             const startSample = off / channels
             const endSample = end / channels
+            const startMs =
+                Math.round((startSample / sampleRate) * 1000) + rangeStartMs
+            const endMs =
+                Math.round((endSample / sampleRate) * 1000) + rangeStartMs
             const chunk: StreamAudioDataChunk = {
                 requestId,
                 chunkIndex,
-                startTimeMs: Math.round((startSample / sampleRate) * 1000),
-                endTimeMs: Math.round((endSample / sampleRate) * 1000),
+                startTimeMs: startMs,
+                endTimeMs: endMs,
                 durationMs: Math.round(
                     ((endSample - startSample) / sampleRate) * 1000
                 ),
@@ -603,11 +676,24 @@ async function streamAudioDataWeb(
                 isFinal: end >= all.length,
             }
             await callbacks.onChunk(chunk)
+            // Resample rounding (Math.ceil in processAudioBuffer) can push
+            // elapsed past the source-rate-derived range duration on the tail
+            // chunk. Cap so onProgress consumers always see a [0, 1] ratio,
+            // matching the native `coerceIn(0, 1)` / `min(1, max(0, …))`
+            // clamp.
+            const rawElapsedMs = Math.round((endSample / sampleRate) * 1000)
+            const elapsedMs =
+                durationMs > 0
+                    ? Math.min(rawElapsedMs, durationMs)
+                    : rawElapsedMs
             callbacks.onProgress?.({
                 requestId,
-                processedMs: chunk.endTimeMs,
+                processedMs: elapsedMs,
                 durationMs,
-                progress: durationMs > 0 ? chunk.endTimeMs / durationMs : 1,
+                progress:
+                    durationMs > 0
+                        ? Math.min(1, Math.max(0, elapsedMs / durationMs))
+                        : 1,
                 emittedChunks: chunkIndex + 1,
             })
             chunkIndex += 1
@@ -628,10 +714,28 @@ async function streamAudioDataWeb(
     }
 }
 
-function sanitizeFloat32(
-    input: Float32Array,
-    clamp: boolean
-): Float32Array {
+function interleaveBuffer(buffer: AudioBuffer, channels: number): Float32Array {
+    const numCh = Math.max(1, Math.min(channels, buffer.numberOfChannels))
+    const framesPerCh = buffer.length
+    if (numCh === 1) {
+        // Cheap path: clone channel 0 so downstream mutation doesn't touch the
+        // underlying AudioBuffer storage.
+        return new Float32Array(buffer.getChannelData(0))
+    }
+    const out = new Float32Array(framesPerCh * numCh)
+    const channelData: Float32Array[] = []
+    for (let c = 0; c < numCh; c++) {
+        channelData.push(buffer.getChannelData(c))
+    }
+    for (let f = 0; f < framesPerCh; f++) {
+        for (let c = 0; c < numCh; c++) {
+            out[f * numCh + c] = channelData[c][f]
+        }
+    }
+    return out
+}
+
+function sanitizeFloat32(input: Float32Array, clamp: boolean): Float32Array {
     if (!clamp) {
         // still need NaN/Inf sanitation
         for (let i = 0; i < input.length; i++) {

package/src/utils/audioProcessing.ts

@@ -6,8 +6,8 @@ import { ConsoleLike } from '../AudioStudio.types'
 export interface ProcessAudioBufferOptions {
     arrayBuffer?: ArrayBuffer
     fileUri?: string
-    targetSampleRate: number
-    targetChannels: number
+    targetSampleRate?: number
+    targetChannels?: number
     normalizeAudio: boolean
     startTimeMs?: number
     endTimeMs?: number
@@ -84,9 +84,17 @@ export async function processAudioBuffer({
         // Create context at original sample rate first
         ctx =
             audioContext ||
-            new (window.AudioContext || (window as any).webkitAudioContext)()
+            new (window.AudioContext ||
+                (
+                    window as unknown as {
+                        webkitAudioContext?: typeof AudioContext
+                    }
+                ).webkitAudioContext)()
         buffer = await ctx.decodeAudioData(audioData)
 
+        const effectiveTargetSampleRate = targetSampleRate ?? buffer.sampleRate
+        const effectiveTargetChannels = targetChannels ?? buffer.numberOfChannels
+
         logger?.debug('Decoded audio buffer:', {
             originalChannels: buffer.numberOfChannels,
             originalSampleRate: buffer.sampleRate,
@@ -109,7 +117,7 @@ export async function processAudioBuffer({
             position !== undefined
                 ? Math.floor(
                       (position / bytesPerSample) *
-                          (buffer.sampleRate / targetSampleRate)
+                          (buffer.sampleRate / effectiveTargetSampleRate)
                   )
                 : startSample
 
@@ -117,11 +125,12 @@ export async function processAudioBuffer({
             length !== undefined
                 ? Math.floor(
                       (length / bytesPerSample) *
-                          (buffer.sampleRate / targetSampleRate)
+                          (buffer.sampleRate / effectiveTargetSampleRate)
                   )
-                : endTimeMs !== undefined && startTimeMs !== undefined
+                : endTimeMs !== undefined
                   ? Math.floor(
-                        ((endTimeMs - startTimeMs) / 1000) * buffer.sampleRate
+                        ((endTimeMs - (startTimeMs ?? 0)) / 1000) *
+                            buffer.sampleRate
                     )
                   : buffer.length - adjustedStartSample
 
@@ -130,8 +139,8 @@ export async function processAudioBuffer({
             adjustedStartSample,
             samplesNeeded,
             originalSampleRate: buffer.sampleRate,
-            targetSampleRate,
-            conversionRatio: buffer.sampleRate / targetSampleRate,
+            targetSampleRate: effectiveTargetSampleRate,
+            conversionRatio: buffer.sampleRate / effectiveTargetSampleRate,
             expectedDurationMs: (samplesNeeded / buffer.sampleRate) * 1000,
         })
 
@@ -153,9 +162,11 @@ export async function processAudioBuffer({
 
         // Create offline context for resampling
         const offlineCtx = new OfflineAudioContext(
-            targetChannels,
-            Math.ceil((samplesNeeded * targetSampleRate) / buffer.sampleRate),
-            targetSampleRate
+            effectiveTargetChannels,
+            Math.ceil(
+                (samplesNeeded * effectiveTargetSampleRate) / buffer.sampleRate
+            ),
+            effectiveTargetSampleRate
         )
 
         // Create source and connect
@@ -175,7 +186,7 @@ export async function processAudioBuffer({
 
         logger?.debug('Final processed audio:', {
             outputSamples: channelData.length,
-            outputSampleRate: targetSampleRate,
+            outputSampleRate: effectiveTargetSampleRate,
             durationMs,
         })
 
@@ -184,7 +195,7 @@ export async function processAudioBuffer({
             channelData,
             samples: channelData.length,
             durationMs,
-            sampleRate: targetSampleRate,
+            sampleRate: effectiveTargetSampleRate,
             channels: processedBuffer.numberOfChannels,
         }
     } catch (error) {

package/android/src/androidTest/java/net/siteed/audiostudio/AudioFinalMetadataContractInstrumentedTest.kt

@@ -1,190 +0,0 @@
-package net.siteed.audiostudio
-
-import android.content.Context
-import android.net.Uri
-import androidx.test.ext.junit.runners.AndroidJUnit4
-import androidx.test.platform.app.InstrumentationRegistry
-import org.junit.After
-import org.junit.Assert.assertEquals
-import org.junit.Assert.assertTrue
-import org.junit.Before
-import org.junit.Test
-import org.junit.runner.RunWith
-import java.io.File
-import java.nio.ByteBuffer
-import java.nio.ByteOrder
-
-/**
- * Regression coverage for Android range processing where the final PCM bytes,
- * returned metadata, and WAV headers must all describe the post-conversion data.
- */
-@RunWith(AndroidJUnit4::class)
-class AudioFinalMetadataContractInstrumentedTest {
-    private lateinit var context: Context
-    private lateinit var filesDir: File
-    private lateinit var audioProcessor: AudioProcessor
-
-    @Before
-    fun setUp() {
-        context = InstrumentationRegistry.getInstrumentation().targetContext
-        filesDir = context.filesDir
-        audioProcessor = AudioProcessor(filesDir)
-        copyAssetToFilesDir("chorus.wav")
-    }
-
-    @After
-    fun tearDown() {
-        filesDir.listFiles()?.forEach { file ->
-            if (file.name.startsWith("final_metadata_contract_") || file.name == "chorus.wav") {
-                file.delete()
-            }
-        }
-    }
-
-    @Test
-    fun loadAudioRange_returnsMetadataFromFinalConvertedWavBytes() {
-        val audioData = audioProcessor.loadAudioRange(
-            fileUri = File(filesDir, "chorus.wav").absolutePath,
-            startTimeMs = 0,
-            endTimeMs = ONE_SECOND_MS,
-            config = DecodingConfig(
-                targetSampleRate = TARGET_SAMPLE_RATE,
-                targetChannels = TARGET_CHANNELS,
-                targetBitDepth = TARGET_BIT_DEPTH,
-                normalizeAudio = false
-            )
-        )
-
-        val converted = requireNotNull(audioData) { "Audio range should load" }
-        val bytesPerTargetFrame = TARGET_CHANNELS * BYTES_PER_TARGET_SAMPLE
-        val finalFrameCount = converted.data.size / bytesPerTargetFrame
-        val durationFromFinalBytes = finalFrameCount * 1_000L / TARGET_SAMPLE_RATE
-
-        assertEquals("sampleRate should describe final converted bytes", TARGET_SAMPLE_RATE, converted.sampleRate)
-        assertEquals("channels should describe final converted bytes", TARGET_CHANNELS, converted.channels)
-        assertEquals("bitDepth should describe final converted bytes", TARGET_BIT_DEPTH, converted.bitDepth)
-        assertEquals("final PCM data must end on a target frame boundary", 0, converted.data.size % bytesPerTargetFrame)
-        assertEquals(
-            "duration should be derived from actual final PCM bytes",
-            durationFromFinalBytes,
-            converted.durationMs
-        )
-        assertTrue(
-            "duration should remain close to requested range: ${converted.durationMs}ms",
-            kotlin.math.abs(converted.durationMs - ONE_SECOND_MS) <= 25
-        )
-    }
-
-    @Test
-    fun loadAudioRange_alignsConvertedWavBytesToTargetFrameSize() {
-        val audioData = audioProcessor.loadAudioRange(
-            fileUri = File(filesDir, "chorus.wav").absolutePath,
-            startTimeMs = 0,
-            endTimeMs = ONE_SECOND_MS,
-            config = DecodingConfig(
-                targetSampleRate = TARGET_SAMPLE_RATE,
-                targetChannels = TARGET_CHANNELS,
-                targetBitDepth = TARGET_BIT_DEPTH,
-                normalizeAudio = false
-            )
-        )
-
-        val converted = requireNotNull(audioData) { "Audio range should load" }
-        val bytesPerTargetFrame = TARGET_CHANNELS * BYTES_PER_TARGET_SAMPLE
-
-        assertEquals("final PCM data must end on a target frame boundary", 0, converted.data.size % bytesPerTargetFrame)
-    }
-
-    @Test
-    fun trimAudio_writesWavHeaderFromFinalConvertedBytes() {
-        val outputFileName = "final_metadata_contract_processor_trim.wav"
-        val trimmed = audioProcessor.trimAudio(
-            fileUri = File(filesDir, "chorus.wav").absolutePath,
-            startTimeMs = 0,
-            endTimeMs = ONE_SECOND_MS,
-            config = DecodingConfig(
-                targetSampleRate = TARGET_SAMPLE_RATE,
-                targetChannels = TARGET_CHANNELS,
-                targetBitDepth = TARGET_BIT_DEPTH,
-                normalizeAudio = false
-            ),
-            outputFileName = outputFileName
-        )
-
-        requireNotNull(trimmed) { "Trimmed audio should be returned" }
-        val header = readWavHeader(File(filesDir, outputFileName))
-
-        assertEquals("WAV header sample rate should be target sample rate", TARGET_SAMPLE_RATE, header.sampleRate)
-        assertEquals("WAV header channels should be target channels", TARGET_CHANNELS, header.channels)
-        assertEquals("WAV header bit depth should be target bit depth", TARGET_BIT_DEPTH, header.bitDepth)
-        assertEquals("WAV data chunk should match returned final PCM bytes", trimmed.data.size, header.dataSize)
-    }
-
-    @Test
-    fun audioTrimmer_honorsJsNumberOutputFormatWhenWritingWavHeader() {
-        val trimmer = AudioTrimmer(context, AudioFileHandler(filesDir))
-        val result = trimmer.trimAudio(
-            fileUri = Uri.fromFile(File(filesDir, "chorus.wav")).toString(),
-            startTimeMs = 0,
-            endTimeMs = ONE_SECOND_MS,
-            outputFileName = "final_metadata_contract_audio_trimmer",
-            outputFormat = mapOf(
-                "format" to "wav",
-                "sampleRate" to TARGET_SAMPLE_RATE.toDouble(),
-                "channels" to TARGET_CHANNELS.toDouble(),
-                "bitDepth" to TARGET_BIT_DEPTH.toDouble()
-            )
-        )
-
-        val outputPath = result["uri"] as String
-        val header = readWavHeader(File(outputPath))
-
-        assertEquals("Double sampleRate option should drive WAV header", TARGET_SAMPLE_RATE, header.sampleRate)
-        assertEquals("Double channels option should drive WAV header", TARGET_CHANNELS, header.channels)
-        assertEquals("Double bitDepth option should drive WAV header", TARGET_BIT_DEPTH, header.bitDepth)
-    }
-
-    private fun copyAssetToFilesDir(fileName: String) {
-        context.assets.open(fileName).use { input ->
-            File(filesDir, fileName).outputStream().use { output ->
-                input.copyTo(output)
-            }
-        }
-    }
-
-    private fun readWavHeader(file: File): WavHeader {
-        assertTrue("WAV file should exist: ${file.absolutePath}", file.exists())
-        val bytes = file.inputStream().use { it.readNBytes(44) }
-        assertEquals("RIFF", String(bytes.sliceArray(0..3)))
-        assertEquals("WAVE", String(bytes.sliceArray(8..11)))
-        assertEquals("data", String(bytes.sliceArray(36..39)))
-
-        return WavHeader(
-            channels = bytes.shortAt(22),
-            sampleRate = bytes.intAt(24),
-            bitDepth = bytes.shortAt(34),
-            dataSize = bytes.intAt(40)
-        )
-    }
-
-    private fun ByteArray.shortAt(offset: Int): Int =
-        ByteBuffer.wrap(this, offset, 2).order(ByteOrder.LITTLE_ENDIAN).short.toInt()
-
-    private fun ByteArray.intAt(offset: Int): Int =
-        ByteBuffer.wrap(this, offset, 4).order(ByteOrder.LITTLE_ENDIAN).int
-
-    private data class WavHeader(
-        val channels: Int,
-        val sampleRate: Int,
-        val bitDepth: Int,
-        val dataSize: Int
-    )
-
-    companion object {
-        private const val ONE_SECOND_MS = 1_000L
-        private const val TARGET_SAMPLE_RATE = 16_000
-        private const val TARGET_CHANNELS = 2
-        private const val TARGET_BIT_DEPTH = 16
-        private const val BYTES_PER_TARGET_SAMPLE = TARGET_BIT_DEPTH / 8
-    }
-}