@siteed/audio-studio 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.1] - 2026-05-08
+### Fixed
+- Trust Android final decoded PCM metadata for range extraction and trimming, including JS `Number` options bridged as Kotlin `Double`.
+- Keep default Android validation deterministic by replacing physical loopback assertions and gating long recorder benchmarks behind an opt-in flag.
+
+### Changed
+- Document the playground CDP regression-contract workflow and make optional VAD model loading cache-first.
+
 
 ## [3.1.0] - 2026-05-01
 ### Changed
@@ -357,7 +365,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Audio features extraction during recording
 - Consistent WAV PCM recording format across all platforms
 
-[unreleased]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.1.0...HEAD
+[unreleased]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.1.1...HEAD
+[3.1.1]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.1.0...@siteed/audio-studio@3.1.1
 [3.1.0]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.0.5...@siteed/audio-studio@3.1.0
 [3.0.5]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.0.4...@siteed/audio-studio@3.0.5
 [3.0.4]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.0.3...@siteed/audio-studio@3.0.4

package/README.md

@@ -54,20 +54,20 @@ yarn add @siteed/audio-studio
 ## Quick Start
 
 ```typescript
-import { useAudioRecorder } from '@siteed/audio-studio';
+import { useAudioRecorder } from '@siteed/audio-studio'
 
-const { startRecording, stopRecording, isRecording } = useAudioRecorder();
+const { startRecording, stopRecording, isRecording } = useAudioRecorder()
 
 // Record
 await startRecording({
-  sampleRate: 44100,
-  channels: 1,
-  encoding: 'pcm_16bit',
-});
+    sampleRate: 44100,
+    channels: 1,
+    encoding: 'pcm_16bit',
+})
 
 // ... later
-const result = await stopRecording();
-console.log('Saved to:', result.fileUri);
+const result = await stopRecording()
+console.log('Saved to:', result.fileUri)
 ```
 
 ### Zero-Latency Recording
@@ -75,12 +75,17 @@ console.log('Saved to:', result.fileUri);
 Pre-initialize to eliminate startup delay:
 
 ```typescript
-const { prepareRecording, startRecording, stopRecording } = useSharedAudioRecorder();
+const { prepareRecording, startRecording, stopRecording } =
+    useSharedAudioRecorder()
 
-await prepareRecording({ sampleRate: 44100, channels: 1, encoding: 'pcm_16bit' });
+await prepareRecording({
+    sampleRate: 44100,
+    channels: 1,
+    encoding: 'pcm_16bit',
+})
 
 // Later — starts instantly
-await startRecording();
+await startRecording()
 ```
 
 ### Shared State Across Components
@@ -100,15 +105,15 @@ Set `streamFormat: 'float32'` to get `Float32Array` on all platforms instead of
 
 ```typescript
 await startRecording({
-  sampleRate: 16000,
-  channels: 1,
-  encoding: 'pcm_32bit',
-  streamFormat: 'float32',
-  onAudioStream: async (event) => {
-    const samples = event.data as Float32Array;
-    await myModel.feed(samples);
-  },
-});
+    sampleRate: 16000,
+    channels: 1,
+    encoding: 'pcm_32bit',
+    streamFormat: 'float32',
+    onAudioStream: async (event) => {
+        const samples = event.data as Float32Array
+        await myModel.feed(samples)
+    },
+})
 ```
 
 ## Audio Analysis
@@ -122,55 +127,61 @@ retention to avoid unbounded JS memory growth:
 
 ```typescript
 await startRecording({
-  sampleRate: 16000,
-  channels: 1,
-  enableProcessing: true,
-  keepFullAnalysis: false,
-  onAudioAnalysis: async (analysis) => {
-    // Consume each analysis chunk without retaining the full recording history.
-    updateVoiceActivity(analysis.dataPoints);
-  },
-});
+    sampleRate: 16000,
+    channels: 1,
+    enableProcessing: true,
+    keepFullAnalysis: false,
+    onAudioAnalysis: async (analysis) => {
+        // Consume each analysis chunk without retaining the full recording history.
+        updateVoiceActivity(analysis.dataPoints)
+    },
+})
 ```
 
 ```typescript
-import { extractAudioAnalysis, extractPreview, extractMelSpectrogram, trimAudio } from '@siteed/audio-studio';
+import {
+    extractAudioAnalysis,
+    extractPreview,
+    extractMelSpectrogram,
+    trimAudio,
+} from '@siteed/audio-studio'
 
 // Feature extraction
 const analysis = await extractAudioAnalysis({
-  fileUri: 'path/to/recording.wav',
-  features: { rms: true, zcr: true, mfcc: true, spectralCentroid: true }
-});
+    fileUri: 'path/to/recording.wav',
+    features: { rms: true, zcr: true, mfcc: true, spectralCentroid: true },
+})
 
 // Lightweight waveform for visualization
 const preview = await extractPreview({
-  fileUri: 'path/to/recording.wav',
-  pointsPerSecond: 50
-});
+    fileUri: 'path/to/recording.wav',
+    pointsPerSecond: 50,
+})
 
 // Mel spectrogram for ML
 const mel = await extractMelSpectrogram({
-  fileUri: 'path/to/recording.wav',
-  nMels: 40, hopLengthMs: 10
-});
+    fileUri: 'path/to/recording.wav',
+    nMels: 40,
+    hopLengthMs: 10,
+})
 
 // Trim audio
 const trimmed = await trimAudio({
-  fileUri: 'path/to/recording.wav',
-  ranges: [{ startTimeMs: 1000, endTimeMs: 5000 }],
-  mode: 'keep'
-});
+    fileUri: 'path/to/recording.wav',
+    ranges: [{ startTimeMs: 1000, endTimeMs: 5000 }],
+    mode: 'keep',
+})
 ```
 
 ### Which Method to Use
 
-| Method | Cost | Use case |
-|--------|------|----------|
-| `extractPreview` | Light | Waveform visualization |
-| `extractRawWavAnalysis` | Light | WAV metadata without decoding |
-| `extractAudioData` | Medium | Raw PCM for custom processing |
-| `extractAudioAnalysis` | Medium-Heavy | MFCC, spectral features, pitch, tempo |
-| `extractMelSpectrogram` | Heavy | Frequency-domain for ML |
+| Method                  | Cost         | Use case                              |
+| ----------------------- | ------------ | ------------------------------------- |
+| `extractPreview`        | Light        | Waveform visualization                |
+| `extractRawWavAnalysis` | Light        | WAV metadata without decoding         |
+| `extractAudioData`      | Medium       | Raw PCM for custom processing         |
+| `extractAudioAnalysis`  | Medium-Heavy | MFCC, spectral features, pitch, tempo |
+| `extractMelSpectrogram` | Heavy        | Frequency-domain for ML               |
 
 ## Docs
 
@@ -184,4 +195,40 @@ const trimmed = await trimAudio({
 MIT — see [LICENSE](LICENSE).
 
 ---
+
 <sub>Created by [Arthur Breton](https://siteed.net)</sub>
+
+### Compact waveform preview bars
+
+For UI waveform previews, prefer `extractPreviewBars` over adapting a full
+`AudioAnalysis` when detailed features are not needed:
+
+```typescript
+import { extractPreviewBars } from '@siteed/audio-studio'
+
+const preview = await extractPreviewBars({
+    fileUri,
+    numberOfBars: 120,
+    startTimeMs: 0,
+    endTimeMs: 30_000,
+})
+
+console.log(preview.bars, preview.durationMs, preview.amplitudeRange)
+```
+
+`extractPreviewBars` returns compact `PreviewBar[]` data plus duration, sample
+rate, channel count, bit depth, amplitude/RMS ranges, and extraction timing. The
+existing `extractPreview` API remains available for compatibility with callers
+that expect `AudioAnalysis` / `DataPoint[]`.
+
+Native Android and iOS expose an `extractPreviewBars` bridge for compact
+bars-out results. JS also keeps a compatibility fallback through `extractPreview`
+for older native runtimes that do not yet provide the compact bridge.
+
+#### C++ scope note
+
+Waveform preview bar extraction intentionally keeps file decode in platform
+code. A future C++ `WaveformBarsProcessor` should be considered only as a pure
+PCM-in/bars-out processor if Kotlin/Swift/Web implementations become a real
+maintenance problem or if waveform bars are bundled into a broader shared
+processor/VAD effort. This is not a formal benchmark claim.

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

@@ -0,0 +1,190 @@
+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
+    }
+}

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

@@ -2,9 +2,6 @@ package net.siteed.audiostudio
 
 import android.Manifest
 import android.content.Context
-import android.media.AudioFormat
-import android.media.AudioManager
-import android.media.AudioTrack
 import android.os.Bundle
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import androidx.test.platform.app.InstrumentationRegistry
@@ -17,6 +14,8 @@ import org.junit.Rule
 import org.junit.Test
 import org.junit.runner.RunWith
 import java.io.File
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
 import java.util.concurrent.CountDownLatch
 import java.util.concurrent.TimeUnit
 import kotlin.math.sin
@@ -363,44 +362,23 @@ class AudioRecorderInstrumentedTest {
     }
     
     @Test
-    fun testRecordingWithToneGeneration_verifiesAudioContent() {
-        // This test generates a tone and plays it while recording to verify
-        // that actual audio is being captured
-        
-        // Given
-        val recordingOptions = mapOf(
-            "sampleRate" to 44100,
-            "channels" to 1,
-            "encoding" to "pcm_16bit",
-            "interval" to 100,
-            "showNotification" to false
+    fun testGeneratedToneAnalysis_verifiesAudioContentFeatures() {
+        // Speaker-to-microphone loopback is device/environment dependent and flaky:
+        // volume, routing, echo cancellation, and physical placement can all turn a
+        // valid recorder run into near-silence. Keep recorder coverage in the
+        // lifecycle/file tests above, validate the physical mic path via the
+        // playground CDP/manual recorder flow, and verify tone analysis here
+        // with deterministic PCM.
+        val sampleRate = 44100
+        val tonePcm = generateTonePcm(
+            frequency = 1000.0,
+            durationMs = 1000,
+            sampleRate = sampleRate
         )
-        
-        // Start recording
-        startRecordingSync(recordingOptions)
-        
-        // Play a 1kHz tone for 1 second
-        playTone(1000.0, 1000)
-        
-        // Stop recording
-        val result = stopRecordingSync()
-        
-        // Load and analyze the recorded file
-        val fileUri = result["fileUri"] as String
-        val audioFile = when {
-            fileUri.startsWith("file://") -> File(java.net.URI(fileUri))
-            fileUri.startsWith("file:") -> File(java.net.URI(fileUri))
-            else -> File(fileUri)
-        }
-        
+
         val audioProcessor = AudioProcessor(filesDir)
-        val audioData = audioProcessor.loadAudioFromAnyFormat(audioFile.absolutePath, null)
-        
-        assertNotNull("Should load audio data", audioData)
-        
-        // Analyze the audio to verify it contains the tone
         val config = RecordingConfig(
-            sampleRate = 44100,
+            sampleRate = sampleRate,
             channels = 1,
             encoding = "pcm_16bit",
             features = mapOf(
@@ -410,22 +388,18 @@ class AudioRecorderInstrumentedTest {
             )
         )
         
-        val analysis = audioProcessor.processAudioData(audioData!!.data, config)
+        val analysis = audioProcessor.processAudioData(tonePcm, config)
         
-        // Verify we captured audio with energy (not silence)
         val dataPoints = analysis.dataPoints
         assertTrue("Should have data points", dataPoints.isNotEmpty())
         
-        // Check that we have non-zero RMS values indicating captured audio
         val avgRms = dataPoints.map { it.rms }.average()
-        assertTrue("Average RMS should indicate captured audio", avgRms > 0.01)
+        assertTrue("Average RMS should indicate deterministic tone energy", avgRms > 0.01)
         
-        // Check that features were extracted
         val firstPointWithFeatures = dataPoints.firstOrNull { it.features != null }
         assertNotNull("Should have at least one data point with features", firstPointWithFeatures)
         
         // The spectral centroid of a 1kHz tone should be around 1000Hz
-        // Note: spectral centroid can be affected by recording quality and background noise
         val spectralCentroids = dataPoints.mapNotNull { it.features?.spectralCentroid }.filter { it > 0 }
         assertTrue("Should have spectral centroid values", spectralCentroids.isNotEmpty())
         val avgSpectralCentroid = spectralCentroids.average()
@@ -433,10 +407,10 @@ class AudioRecorderInstrumentedTest {
         // Log the actual value for debugging
         println("Average spectral centroid: $avgSpectralCentroid Hz")
         
-        // Be more lenient with the range as real device recording can have variations
-        // Just verify it's not silence (very low) or noise (very high)
-        assertTrue("Spectral centroid should indicate tonal content (was $avgSpectralCentroid Hz)", 
-            avgSpectralCentroid > 100 && avgSpectralCentroid < 20000)
+        assertTrue(
+            "Spectral centroid should indicate tonal content (was $avgSpectralCentroid Hz)",
+            avgSpectralCentroid > 700 && avgSpectralCentroid < 1300
+        )
     }
     
     // ========== Helper Methods ==========
@@ -499,43 +473,15 @@ class AudioRecorderInstrumentedTest {
         return map
     }
     
-    private fun playTone(frequency: Double, durationMs: Int) {
-        val sampleRate = 44100
+    private fun generateTonePcm(frequency: Double, durationMs: Int, sampleRate: Int): ByteArray {
         val numSamples = (sampleRate * durationMs / 1000.0).toInt()
-        val samples = ShortArray(numSamples)
-        
-        // Generate sine wave
+        val buffer = ByteBuffer.allocate(numSamples * 2).order(ByteOrder.LITTLE_ENDIAN)
+
         for (i in 0 until numSamples) {
             val angle = 2.0 * Math.PI * i * frequency / sampleRate
-            samples[i] = (sin(angle) * Short.MAX_VALUE * 0.5).toInt().toShort()
+            buffer.putShort((sin(angle) * Short.MAX_VALUE * 0.5).toInt().toShort())
         }
-        
-        // Play the tone
-        val audioTrack = AudioTrack.Builder()
-            .setAudioAttributes(
-                android.media.AudioAttributes.Builder()
-                    .setUsage(android.media.AudioAttributes.USAGE_MEDIA)
-                    .setContentType(android.media.AudioAttributes.CONTENT_TYPE_MUSIC)
-                    .build()
-            )
-            .setAudioFormat(
-                AudioFormat.Builder()
-                    .setSampleRate(sampleRate)
-                    .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
-                    .setChannelMask(AudioFormat.CHANNEL_OUT_MONO)
-                    .build()
-            )
-            .setBufferSizeInBytes(samples.size * 2)
-            .setTransferMode(AudioTrack.MODE_STATIC)
-            .build()
-        
-        audioTrack.write(samples, 0, samples.size)
-        audioTrack.play()
-        
-        // Wait for playback to complete
-        Thread.sleep(durationMs.toLong())
-        
-        audioTrack.stop()
-        audioTrack.release()
+
+        return buffer.array()
     }
-} 
+}

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

@@ -9,6 +9,7 @@ import androidx.test.rule.GrantPermissionRule
 import expo.modules.kotlin.Promise
 import org.junit.After
 import org.junit.Assert.*
+import org.junit.Assume.assumeTrue
 import org.junit.Before
 import org.junit.Rule
 import org.junit.Test
@@ -116,18 +117,33 @@ class AudioRecorderPerformanceInstrumentedTest {
     
     @Test
     fun measureStopTime_5minutes() {
+        assumeLongPerformanceTestsEnabled()
         runPerformanceTest(300_000L, "5 minute recording")
     }
     
     @Test
     fun measureStopTime_10minutes() {
+        assumeLongPerformanceTestsEnabled()
         runPerformanceTest(600_000L, "10 minute recording")
     }
     
     @Test
     fun measureStopTime_15minutes() {
+        assumeLongPerformanceTestsEnabled()
         runPerformanceTest(900_000L, "15 minute recording")
     }
+
+    private fun assumeLongPerformanceTestsEnabled() {
+        val enabled = InstrumentationRegistry.getArguments()
+            .getString("runLongPerformanceTests")
+            ?.equals("true", ignoreCase = true) == true
+
+        assumeTrue(
+            "Long physical-device performance benchmarks are opt-in. " +
+                "Run with -Pandroid.testInstrumentationRunnerArguments.runLongPerformanceTests=true",
+            enabled
+        )
+    }
     
     private fun runPerformanceTest(recordingDurationMs: Long, testName: String) {
         val recordingOptions = mapOf(
@@ -231,4 +247,4 @@ class AudioRecorderPerformanceInstrumentedTest {
         }
         return map
     }
-}
+}