@iternio/react-native-auto-play 0.5.4 → 0.5.6

package/README.md

@@ -14,7 +14,7 @@
 ## Features
 
 -   **Cross-Platform:** Write once, run on both Apple CarPlay and Android Auto.
--  **Both Architectures:** Supports both the legacy and the new React Native architecture.
+-   **New Architecture:** Supports React Native new architecture only.
 -   **Template-Based UI:** Utilize a rich set of templates like `MapTemplate`, `ListTemplate`, `GridTemplate`, and more to build UIs that comply with automotive design guidelines.
 -   **Navigation APIs:** Build full-featured navigation experiences with APIs for trip management, maneuvers, and route guidance.
 -   **Dashboard & Cluster Support:** Extend your app's presence to the CarPlay Dashboard (CarPlay only) and instrument cluster displays (CarPlay & Android Auto).
@@ -837,36 +837,95 @@ new ListTemplate({
 
 ### Voice Input
 
-The library provides a cross-platform in-app voice recording API built on top of the car microphone (when connected) or the device microphone (when no car is connected).
+The library provides a cross-platform in-app voice recording API built on top of the car microphone (when connected) or the device microphone (when no car is connected). The voice API lives in `HybridVoice`.
 
 #### Permission
 
 ```ts
-// Check whether permission is already granted
-const granted = HybridAutoPlay.hasVoiceInputPermission();
+import { HybridVoice } from '@iternio/react-native-auto-play';
+
+// Check whether permission is already granted (synchronous)
+const granted = HybridVoice.hasVoiceInputPermission();
 
 // Request permission if not yet granted
-const granted = await HybridAutoPlay.requestVoiceInputPermission();
+const granted = await HybridVoice.requestVoiceInputPermission();
 ```
 
+On **iOS**: checks/requests both microphone and speech recognition authorization.
+On **Android**: checks/requests `RECORD_AUDIO` via the car context when connected, otherwise via the RN application context.
+
 #### Recording
 
 ```ts
-// Start recording — resolves with a raw PCM ArrayBuffer (16 kHz, 16-bit, mono)
-// Recording stops automatically on silence or when maxDurationMs is reached
-const pcmBuffer = await HybridAutoPlay.startVoiceInput(
-  1500,       // silenceThresholdMs (default 1500)
-  10_000,     // maxDurationMs (default 10 000)
-  'Listening...' // text shown on the car screen while recording (iOS CarPlay)
-);
+import { HybridVoice, ErrorUtil } from '@iternio/react-native-auto-play';
+
+try {
+  const result = await HybridVoice.startVoiceInput({
+    silenceThresholdMs: 1500,      // ms of silence before auto-stop (default 1500)
+    maxDurationMs: 10_000,         // hard cap on recording duration (default 10 000)
+    listeningText: 'Listening…',   // iOS CarPlay: text shown on CPVoiceControlTemplate
+    preferSpeechToText: false,     // true → STT transcription; false → raw PCM (default)
+    startSound: require('./beep_start.mp3'), // played just before recording starts
+    endSound: require('./beep_end.mp3'),     // played just after recording stops
+    onChunk: (chunk) => {
+      // chunk.audio — raw PCM ArrayBuffer chunk (PCM mode)
+      // chunk.partial — partial transcription string (STT mode)
+    },
+  });
+
+  if (result.transcription) {
+    console.log('Transcription:', result.transcription);
+  } else if (result.audio) {
+    console.log(`PCM audio: ${result.audio.byteLength} bytes`);
+  }
+} catch (e) {
+  if (ErrorUtil.isVoiceInputCanceledError(e)) {
+    // User pressed the cancel button on the car screen
+    console.log('Voice input cancelled');
+  } else {
+    console.error(e);
+  }
+}
 
-// Stop recording early — resolves startVoiceInput with the audio captured so far
-HybridAutoPlay.stopVoiceInput();
+// Stop recording early — resolves startVoiceInput with audio captured so far
+HybridVoice.stopVoiceInput();
 ```
 
-On **Android**: uses `CarAudioRecord` when Android Auto is connected, otherwise falls back to standard `AudioRecord`.
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `silenceThresholdMs` | `number` | `1500` | Auto-stop after this many ms of silence |
+| `maxDurationMs` | `number` | `10000` | Hard recording time limit |
+| `listeningText` | `string` | — | iOS only — text shown on `CPVoiceControlTemplate` |
+| `listeningImage` | `VoiceInputImage` | — | iOS only — animated image in the CarPlay overlay |
+| `preferSpeechToText` | `boolean` | `false` | `true` → resolve with `{ transcription }`; `false` → resolve with `{ audio }` |
+| `startSound` | `number` | — | Metro asset (`require('./beep.mp3')`) played before recording. Takes audio focus so other apps pause. |
+| `endSound` | `number` | — | Metro asset played after recording stops |
+| `onChunk` | `(chunk) => void` | — | Streaming callback: `chunk.audio` (PCM) or `chunk.partial` (STT) |
+| `language` | `string` | system | BCP-47 language tag for the STT recognizer |
+
+**PCM result** (`preferSpeechToText: false`, default): resolves with `{ audio: ArrayBuffer }` — raw 16 kHz, 16-bit, mono PCM.
+
+**STT result** (`preferSpeechToText: true`): resolves with `{ transcription: string }` on success, or falls back to `{ audio }` if recognition is unavailable.
 
-On **iOS**: presents `CPVoiceControlTemplate` on the car screen when CarPlay is connected, and captures audio via `AVAudioEngine`.
+On **Android**: uses `CarAudioRecord` when Android Auto is connected, otherwise falls back to standard `AudioRecord`. STT uses `SpeechRecognizer`.
+
+On **iOS**: presents `CPVoiceControlTemplate` on the car screen when CarPlay is connected, and captures audio via `AVAudioEngine`. STT uses `SFSpeechRecognizer`.
+
+#### Cancel detection
+
+When the user presses the cancel button on the car screen, `startVoiceInput` rejects with a `voiceInputCancelled` error on both platforms. Use `ErrorUtil.isVoiceInputCanceledError` to distinguish it from other errors:
+
+```ts
+import { ErrorUtil } from '@iternio/react-native-auto-play';
+
+HybridVoice.startVoiceInput().catch((e) => {
+  if (ErrorUtil.isVoiceInputCanceledError(e)) {
+    // user dismissed — no action needed
+  } else {
+    throw e;
+  }
+});
+```
 
 #### OS-triggered voice input (Android only)
 
@@ -1015,7 +1074,8 @@ CarPlayDashboard.setButtons([
 
 -   **Broken exceptions with `react-native-skia`**: When using `react-native-skia` exceptions on iOS are not reported correctly. This is fixed since version `2.4.19` of `react-native-skia`. For more details, see this [pull request](https://github.com/Shopify/react-native-skia/pull/3595) and [issue](https://github.com/Shopify/react-native-skia/issues/3635).
 -   **AppState on iOS**: The `AppState` module from React Native does not work correctly on iOS because this library uses scenes, which are not supported by the stock `AppState` module. This library provides a custom state listener that works for both Android and iOS. Use `HybridAutoPlay.addListenerRenderState` instead of `AppState`.
--   **Timers stop on screen lock**: iOS stops all timers when the device's main screen is turned off. To ensure timers continue to run (which is often necessary for background tasks related to autoplay), a patch for `react-native` is required. A patch is included in the root `patches/` directory and can be applied using `patch-package`.
+-   **Timers stop on screen lock**: iOS stops all timers when the device main screen is turned off. To ensure timers continue to run (which is often necessary for background tasks related to autoplay), a patch for `react-native` is required. A patch is included in the root `patches/` directory and can be applied using `patch-package`.
+In case you are using Expo SDK >= 56 make sure to set `buildReactNativeFromSource` to `true` in your app config for [expo-build-properties](https://docs.expo.dev/versions/latest/sdk/build-properties/#sharedbuildconfigfields), otherwise the patch can't be applied.
 -   **expo-splash-screen stuck on iOS**: The `expo-splash-screen` module is broken on iOS because it does not support scenes, which are used by this library. This can cause the splash screen to be stuck on either the mobile device or on CarPlay. To fix this, a patch for `expo-splash-screen` is included in the root `patches/` directory and can be applied using `patch-package`. After applying the patch, you can hide the splash screen for a specific scene by passing the module name to the `hide` or `hideAsync` function. The module name can be one of the values from the `AutoPlayModules` enum or the UUID of a cluster screen.
     ```tsx
     import { hideAsync } from 'expo-splash-screen';

package/android/src/main/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/AutoPlayError.kt

@@ -1,5 +1,10 @@
 package com.margelo.nitro.swe.iternio.reactnativeautoplay
 
-class TemplateNotFoundException(private val templateId: String): Exception("templateNotFound(\"$templateId\")") {
+class TemplateNotFoundException(private val templateId: String) :
+    Exception("templateNotFound(\"$templateId\")") {
     override fun toString(): String = "templateNotFound(\"$templateId\")"
 }
+
+class VoiceInputCancelledException : Exception("voiceInputCancelled") {
+    override fun toString(): String = "voiceInputCancelled"
+}

package/android/src/main/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/HybridVoice.kt

@@ -50,7 +50,7 @@ class HybridVoice : HybridVoiceSpec() {
                             }
                             cont.resume(
                                 grantResults.isNotEmpty() &&
-                                    grantResults.first() == PackageManager.PERMISSION_GRANTED
+                                        grantResults.first() == PackageManager.PERMISSION_GRANTED
                             )
                             true
                         }
@@ -68,7 +68,9 @@ class HybridVoice : HybridVoiceSpec() {
         listeningImageRepeats: Boolean?,
         preferSpeechToText: Boolean?,
         onChunk: ((chunk: VoiceInputChunk) -> Unit)?,
-        language: String?
+        language: String?,
+        startSoundUri: String?,
+        endSoundUri: String?
     ): Promise<VoiceInputResult> {
         return Promise.async {
             if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
@@ -84,7 +86,9 @@ class HybridVoice : HybridVoiceSpec() {
                     maxDurationMs = maxDurationMs?.toLong() ?: 10_000L,
                     preferSpeechToText = preferSpeechToText ?: false,
                     onChunk = onChunk,
-                    language = language
+                    language = language,
+                    startSoundUri = startSoundUri,
+                    endSoundUri = endSoundUri,
                 )
             } finally {
                 voiceInputManager = null

package/android/src/main/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/VoiceInputManager.kt

@@ -10,7 +10,9 @@ import android.media.AudioFocusRequest
 import android.media.AudioFormat
 import android.media.AudioManager
 import android.media.AudioRecord
+import android.media.MediaPlayer
 import android.media.MediaRecorder
+import android.net.Uri
 import android.os.Build
 import android.os.Bundle
 import android.os.ParcelFileDescriptor
@@ -62,6 +64,9 @@ class VoiceInputManager(
     @Volatile
     private var isRecording = false
 
+    @Volatile
+    private var cancelledByUser = false
+
     // STT state — only set when SpeechRecognizer owns the mic
     @Volatile
     private var activeSpeechRecognizer: SpeechRecognizer? = null
@@ -72,22 +77,42 @@ class VoiceInputManager(
         maxDurationMs: Long = 10_000,
         preferSpeechToText: Boolean = false,
         onChunk: ((chunk: VoiceInputChunk) -> Unit)? = null,
-        language: String? = null
+        language: String? = null,
+        startSoundUri: String? = null,
+        endSoundUri: String? = null,
     ): VoiceInputResult {
-        if (preferSpeechToText) {
-            val context = NitroModules.applicationContext ?: throw IllegalArgumentException()
-            if (SpeechRecognizer.isRecognitionAvailable(context)) {
-                if (carContext != null) {
-                    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
-                        return startSTTFromCarAudio(silenceThresholdMs, maxDurationMs, onChunk, language)
+        cancelledByUser = false
+        if (!requestAudioFocus()) {
+            throw IllegalStateException("Audio focus request denied")
+        }
+        try {
+            val startSoundJob = startSoundUri?.let { uri -> scope.launch { playSound(uri) } }
+            val result = if (preferSpeechToText) {
+                val context = NitroModules.applicationContext ?: throw IllegalArgumentException()
+                if (SpeechRecognizer.isRecognitionAvailable(context)) {
+                    if (carContext != null) {
+                        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                            startSTTFromCarAudio(silenceThresholdMs, maxDurationMs, onChunk, language)
+                        } else {
+                            // Car connected but API < 33: EXTRA_AUDIO_SOURCE unavailable, fall back to PCM
+                            startPCM(silenceThresholdMs, maxDurationMs, onChunk)
+                        }
+                    } else {
+                        ThreadUtil.postOnUiAndAwait { startSTT(context, onChunk, language) }.getOrThrow()
                     }
-                    // Car connected but API < 33: EXTRA_AUDIO_SOURCE unavailable, fall back to PCM
-                    return startPCM(silenceThresholdMs, maxDurationMs, onChunk)
+                } else {
+                    startPCM(silenceThresholdMs, maxDurationMs, onChunk)
                 }
-                return ThreadUtil.postOnUiAndAwait { startSTT(context, onChunk, language) }.getOrThrow()
+            } else {
+                startPCM(silenceThresholdMs, maxDurationMs, onChunk)
             }
+            startSoundJob?.join()
+            if (cancelledByUser) throw VoiceInputCancelledException()
+            endSoundUri?.let { playSound(it) }
+            return result
+        } finally {
+            abandonAudioFocus()
         }
-        return startPCM(silenceThresholdMs, maxDurationMs, onChunk)
     }
 
     // MARK: - STT path (SpeechRecognizer owns the mic)
@@ -309,35 +334,8 @@ class VoiceInputManager(
             return@suspendCancellableCoroutine
         }
 
-        val appContext = NitroModules.applicationContext ?: run {
-            cont.resumeWithException(SecurityException("Missing application context"))
-            return@suspendCancellableCoroutine
-        }
-
         pcmContinuation = cont
 
-        val audioManager = appContext.getSystemService(AudioManager::class.java)
-
-        val audioAttributes =
-            AudioAttributes.Builder().setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
-                .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE).build()
-
-        val focusRequest =
-            AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
-                .setAudioAttributes(audioAttributes).setOnAudioFocusChangeListener { state ->
-                    if (state == AudioManager.AUDIOFOCUS_LOSS) {
-                        stop()
-                    }
-                }.build()
-
-        if (audioManager.requestAudioFocus(focusRequest) != AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
-            pcmContinuation = null
-            cont.resumeWithException(IllegalStateException("Audio focus request denied"))
-            return@suspendCancellableCoroutine
-        }
-
-        audioFocusRequest = focusRequest
-
         val bufferSize: Int
 
         if (carContext != null) {
@@ -381,6 +379,8 @@ class VoiceInputManager(
                     ) ?: -1
 
                     if (read < 0) {
+                        // Whenever the user dismisses the microphone on the car screen, the next call to read will return -1
+                        cancelledByUser = carAudioRecord != null && read == -1
                         break
                     }
 
@@ -450,6 +450,72 @@ class VoiceInputManager(
         audioRecord?.stop()
     }
 
+    @RequiresApi(Build.VERSION_CODES.O)
+    private fun requestAudioFocus(): Boolean {
+        val appContext = NitroModules.applicationContext ?: return false
+        val audioManager = appContext.getSystemService(AudioManager::class.java)
+        val audioAttributes = AudioAttributes.Builder()
+            .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+            .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
+            .build()
+        val focusRequest = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
+            .setAudioAttributes(audioAttributes)
+            .setOnAudioFocusChangeListener { state ->
+                if (state == AudioManager.AUDIOFOCUS_LOSS) { stop() }
+            }
+            .build()
+        return if (audioManager.requestAudioFocus(focusRequest) == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
+            audioFocusRequest = focusRequest
+            true
+        } else {
+            false
+        }
+    }
+
+    @RequiresApi(Build.VERSION_CODES.O)
+    private fun abandonAudioFocus() {
+        audioFocusRequest?.let {
+            val audioManager = (NitroModules.applicationContext ?: carContext)
+                ?.getSystemService(AudioManager::class.java)
+            audioManager?.abandonAudioFocusRequest(it)
+        }
+        audioFocusRequest = null
+    }
+
+    private suspend fun playSound(uri: String) = suspendCancellableCoroutine<Unit> { cont ->
+        val context = NitroModules.applicationContext ?: run {
+            cont.resume(Unit)
+            return@suspendCancellableCoroutine
+        }
+        val player = MediaPlayer()
+        try {
+            player.setAudioAttributes(
+                AudioAttributes.Builder()
+                    .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
+                    .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
+                    .build()
+            )
+            player.setDataSource(context, Uri.parse(uri))
+            player.setOnCompletionListener {
+                it.release()
+                if (cont.isActive) { cont.resume(Unit) }
+            }
+            player.setOnErrorListener { mp, _, _ ->
+                mp.release()
+                if (cont.isActive) { cont.resume(Unit) }
+                true
+            }
+            player.prepare()
+            player.start()
+        } catch (_: Exception) {
+            try { player.release() } catch (_: Exception) {}
+            if (cont.isActive) { cont.resume(Unit) }
+        }
+        cont.invokeOnCancellation {
+            try { player.release() } catch (_: Exception) {}
+        }
+    }
+
     @RequiresApi(Build.VERSION_CODES.O)
     private fun releaseResources() {
         carAudioRecord?.stopRecording()
@@ -458,13 +524,6 @@ class VoiceInputManager(
         audioRecord?.release()
         audioRecord = null
         recordingJob = null
-        audioFocusRequest?.let {
-            val audioManager = (NitroModules.applicationContext ?: carContext)?.getSystemService(
-                AudioManager::class.java,
-            )
-            audioManager?.abandonAudioFocusRequest(it)
-        }
-        audioFocusRequest = null
     }
 
     fun dispose() {

package/ios/Types.swift

@@ -10,7 +10,7 @@ struct TemplateEventPayload {
     let state: VisibilityState
 }
 
-enum AutoPlayError: Error {
+enum AutoPlayError: LocalizedError {
     case templateNotFound(String)
     case interfaceControllerNotFound(String)
     case invalidTemplateError(String)
@@ -19,4 +19,5 @@ enum AutoPlayError: Error {
     case invalidTemplateType(String)
     case noUiWindow(String)
     case initReactRootViewFailed(String)
+    case voiceInputCancelled
 }

package/ios/extensions/CarPlayTemplateExtensions.swift

@@ -85,3 +85,10 @@ extension CPAlertTemplate {
         initTemplate(template: self, id: id)
     }
 }
+
+extension CPVoiceControlTemplate {
+    convenience init(voiceControlStates: [CPVoiceControlState], id: String) {
+        self.init(voiceControlStates: voiceControlStates)
+        initTemplate(template: self, id: id)
+    }
+}

package/ios/hybrid/HybridVoice.swift

@@ -36,7 +36,9 @@ class HybridVoice: HybridVoiceSpec {
         listeningImageRepeats: Bool?,
         preferSpeechToText: Bool?,
         onChunk: ((_ chunk: VoiceInputChunk) -> Void)?,
-        language: String?
+        language: String?,
+        startSoundUri: String?,
+        endSoundUri: String?
     ) throws -> Promise<VoiceInputResult> {
         return Promise.async {
             let interfaceController = try? await RootModule.withInterfaceController { $0 }
@@ -55,7 +57,9 @@ class HybridVoice: HybridVoiceSpec {
                 listeningImageRepeats: listeningImageRepeats,
                 preferSpeechToText: preferSpeechToText ?? false,
                 onChunk: onChunk,
-                language: language
+                language: language,
+                startSoundUri: startSoundUri,
+                endSoundUri: endSoundUri
             )
         }
     }

package/ios/templates/VoiceInputTemplate.swift

@@ -0,0 +1,33 @@
+import CarPlay
+
+class VoiceInputTemplate: AutoPlayTemplate {
+    let template: CPVoiceControlTemplate
+    private let onDidDisappearCallback: () -> Void
+
+    override func getTemplate() -> CPTemplate {
+        return template
+    }
+
+    init(
+        voiceControlStates: [CPVoiceControlState],
+        id: String,
+        onDidDisappear: @escaping () -> Void
+    ) {
+        self.template = CPVoiceControlTemplate(voiceControlStates: voiceControlStates, id: id)
+        self.onDidDisappearCallback = onDidDisappear
+
+        super.init()
+
+        try? RootModule.withTemplateStore { templateStore in
+            templateStore.addTemplate(template: self, templateId: id)
+        }
+    }
+
+    override func onDidDisappear(animated: Bool) {
+        onDidDisappearCallback()
+
+        try? RootModule.withTemplateStore { templateStore in
+            templateStore.removeTemplate(templateId: self.template.id)
+        }
+    }
+}

package/ios/utils/VoiceInputManager.swift

@@ -3,8 +3,30 @@ import CarPlay
 import NitroModules
 import Speech
 
-/// Wraps CheckedContinuation so it can only be resumed once even when
-/// shared between a stop() call and an async recognition task callback.
+/// Retains the player and itself until playback finishes — AVAudioPlayer.delegate is weak.
+private final class AudioPlayerDelegate: NSObject, AVAudioPlayerDelegate, @unchecked Sendable {
+    private let onFinish: () -> Void
+    private var keepAlive: AudioPlayerDelegate?
+    private var player: AVAudioPlayer?
+
+    init(player: AVAudioPlayer, _ onFinish: @escaping () -> Void) {
+        self.onFinish = onFinish
+        self.player = player
+        super.init()
+        keepAlive = self
+    }
+
+    private func finish() {
+        player = nil
+        keepAlive = nil
+        onFinish()
+    }
+
+    func audioPlayerDidFinishPlaying(_: AVAudioPlayer, successfully _: Bool) { finish() }
+    func audioPlayerDecodeErrorDidOccur(_: AVAudioPlayer, error _: Error?) { finish() }
+}
+
+/// CheckedContinuation wrapper that can only be resumed once, safe across concurrent stop() and recognition callbacks.
 private final class ResultBox: @unchecked Sendable {
     private var continuation: CheckedContinuation<VoiceInputResult, Error>?
     private let lock = NSLock()
@@ -28,14 +50,14 @@ private final class ResultBox: @unchecked Sendable {
     }
 }
 
-/// Captures audio from the car microphone and buffers raw 16 kHz / 16-bit / mono PCM,
-/// or transcribes it via SFSpeechRecognizer when preferSpeechToText is true.
+/// Records 16 kHz / 16-bit mono PCM from the car mic, or transcribes via SFSpeechRecognizer.
 class VoiceInputManager {
     private var audioEngine: AVAudioEngine?
     private var voiceControlTemplate: CPVoiceControlTemplate?
     private var resultBox: ResultBox?
     private var samples: [Int16] = []
     private var isStopping = false
+    private var cancelledByUser = false
     private let stopLock = NSLock()
 
     // STT
@@ -45,6 +67,7 @@ class VoiceInputManager {
     // Timing
     private var recordingStart: Date?
     private var silenceStart: Date?
+    private var firstBufferContinuation: CheckedContinuation<Void, Never>?
 
     private static let sampleRate: Double = 16_000
     private static let tapBufferSize: AVAudioFrameCount = 4_096
@@ -69,9 +92,22 @@ class VoiceInputManager {
         listeningImageRepeats: Bool?,
         preferSpeechToText: Bool,
         onChunk: ((_ chunk: VoiceInputChunk) -> Void)?,
-        language: String?
+        language: String?,
+        startSoundUri: String?,
+        endSoundUri: String?
     ) async throws -> VoiceInputResult {
-        return try await withCheckedThrowingContinuation { cont in
+        stopLock.withLock {
+            cancelledByUser = false
+        }
+        // Single session for the full flow (start sound + recording + end sound); defer deactivates once at the end.
+        let session = AVAudioSession.sharedInstance()
+        try session.setCategory(.playAndRecord, mode: .measurement, options: [])
+        try session.setActive(true)
+        defer {
+            try? session.setActive(false, options: .notifyOthersOnDeactivation)
+        }
+
+        let result = try await withCheckedThrowingContinuation { cont in
             let box = ResultBox(cont)
             self.resultBox = box
             self.samples = []
@@ -83,9 +119,6 @@ class VoiceInputManager {
                     interfaceController: interfaceController,
                     silenceThresholdMs: silenceThresholdMs,
                     maxDurationMs: maxDurationMs,
-                    listeningText: listeningText,
-                    listeningImage: listeningImage,
-                    listeningImageRepeats: listeningImageRepeats,
                     preferSpeechToText: preferSpeechToText,
                     onChunk: onChunk,
                     box: box,
@@ -95,8 +128,61 @@ class VoiceInputManager {
             catch {
                 self.cleanup(interfaceController: interfaceController)
                 box.resume(throwing: error)
+                return
+            }
+
+            // Start sound fires immediately; template is deferred until the first tap buffer so the mic indicator is already on.
+            if let uri = startSoundUri {
+                Task { await self.playSound(uri: uri) }
+            }
+            if let interfaceController = interfaceController {
+                Task {
+                    await withCheckedContinuation { (cont: CheckedContinuation<Void, Never>) in
+                        self.stopLock.withLock { self.firstBufferContinuation = cont }
+                    }
+                    // Skip if stop() fired before the first buffer — cleanup already dismissed.
+                    guard !self.stopLock.withLock({ self.isStopping }) else { return }
+                    await self.presentVoiceTemplate(
+                        interfaceController: interfaceController,
+                        listeningText: listeningText,
+                        listeningImage: listeningImage,
+                        listeningImageRepeats: listeningImageRepeats
+                    )
+                }
+            }
+        }
+
+        if let uri = endSoundUri {
+            await playSound(uri: uri)
+        }
+
+        return result
+    }
+
+    private func playSound(uri: String) async {
+        guard let url = URL(string: uri) else { return }
+        do {
+            // URLSession handles both http:// (Metro dev server) and file:// (release bundle)
+            let (data, _) = try await URLSession.shared.data(from: url)
+            await withCheckedContinuation { (cont: CheckedContinuation<Void, Never>) in
+                DispatchQueue.main.async {
+                    do {
+                        let player = try AVAudioPlayer(data: data)
+                        let delegate = AudioPlayerDelegate(player: player) { cont.resume() }
+                        player.delegate = delegate
+                        player.prepareToPlay()
+                        player.play()
+                    }
+                    catch {
+                        cont.resume()
+                    }
+                }
             }
         }
+        catch {
+            print(error)
+            // fail silently — a broken sound file must not block voice input
+        }
     }
 
     func stop(interfaceController: AutoPlayInterfaceController? = nil) {
@@ -106,6 +192,7 @@ class VoiceInputManager {
             return
         }
         isStopping = true
+        let wasCancelled = cancelledByUser
         let wasSTTMode = isSTTMode
         let capturedRequest = recognitionRequest
         let box = resultBox
@@ -115,13 +202,17 @@ class VoiceInputManager {
         stopLock.unlock()
 
         if wasSTTMode {
-            // endAudio() causes the recognition task to fire its final result,
-            // which resumes the box. Engine teardown happens there too.
+            // endAudio() triggers the final recognition result, which resumes the box and tears down the engine.
             capturedRequest?.endAudio()
         }
         else {
             cleanup(interfaceController: interfaceController)
-            box?.resume(returning: makePCMResult(from: capturedSamples))
+            if wasCancelled {
+                box?.resume(throwing: AutoPlayError.voiceInputCancelled)
+            }
+            else {
+                box?.resume(returning: makePCMResult(from: capturedSamples))
+            }
         }
     }
 
@@ -131,9 +222,6 @@ class VoiceInputManager {
         interfaceController: AutoPlayInterfaceController?,
         silenceThresholdMs: Double,
         maxDurationMs: Double,
-        listeningText: String,
-        listeningImage: Variant_GlyphImage_AssetImage_RemoteImage?,
-        listeningImageRepeats: Bool?,
         preferSpeechToText: Bool,
         onChunk: ((_ chunk: VoiceInputChunk) -> Void)?,
         box: ResultBox,
@@ -143,19 +231,6 @@ class VoiceInputManager {
             throw VoiceInputError.microphonePermissionDenied
         }
 
-        let session = AVAudioSession.sharedInstance()
-        try session.setCategory(.playAndRecord, mode: .measurement, options: [])
-        try session.setActive(true)
-
-        if let interfaceController {
-            presentVoiceTemplate(
-                interfaceController: interfaceController,
-                listeningText: listeningText,
-                listeningImage: listeningImage,
-                listeningImageRepeats: listeningImageRepeats
-            )
-        }
-
         var activeRecognitionRequest: SFSpeechAudioBufferRecognitionRequest? = nil
 
         if preferSpeechToText, SFSpeechRecognizer.authorizationStatus() == .authorized,
@@ -176,12 +251,18 @@ class VoiceInputManager {
                     // STT failed — fall back to whatever PCM was accumulated
                     self.stopLock.lock()
                     self.isStopping = true
+                    let wasCancelled = self.cancelledByUser
                     let capturedSamples = self.samples
                     self.samples = []
                     self.stopLock.unlock()
 
                     self.cleanup(interfaceController: interfaceController)
-                    box.resume(returning: self.makePCMResult(from: capturedSamples))
+                    if wasCancelled {
+                        box.resume(throwing: AutoPlayError.voiceInputCancelled)
+                    }
+                    else {
+                        box.resume(returning: self.makePCMResult(from: capturedSamples))
+                    }
                     return
                 }
 
@@ -190,16 +271,22 @@ class VoiceInputManager {
                 if result.isFinal {
                     self.stopLock.lock()
                     self.isStopping = true
+                    let wasCancelled = self.cancelledByUser
                     self.samples = []
                     self.stopLock.unlock()
 
                     self.cleanup(interfaceController: interfaceController)
-                    box.resume(
-                        returning: VoiceInputResult(
-                            transcription: result.bestTranscription.formattedString,
-                            audio: nil
+                    if wasCancelled {
+                        box.resume(throwing: AutoPlayError.voiceInputCancelled)
+                    }
+                    else {
+                        box.resume(
+                            returning: VoiceInputResult(
+                                transcription: result.bestTranscription.formattedString,
+                                audio: nil
+                            )
                         )
-                    )
+                    }
                 }
                 else {
                     onChunk?(VoiceInputChunk(partial: result.bestTranscription.formattedString, audio: nil))
@@ -217,13 +304,25 @@ class VoiceInputManager {
 
         recordingStart = Date()
         silenceStart = nil
+        firstBufferContinuation = nil
 
         inputNode.installTap(
             onBus: 0,
             bufferSize: VoiceInputManager.tapBufferSize,
             format: nativeFormat
         ) { [weak self] buffer, _ in
-            guard let self, !self.isStopping else { return }
+            guard let self else { return }
+
+            self.stopLock.lock()
+            let stopping = self.isStopping
+            let recordingStartSnapshot = self.recordingStart
+            let firstBufferCont = self.firstBufferContinuation
+            self.firstBufferContinuation = nil
+            self.stopLock.unlock()
+
+            firstBufferCont?.resume()
+
+            guard !stopping else { return }
 
             // Feed STT if active
             activeRecognitionRequest?.append(buffer)
@@ -266,16 +365,15 @@ class VoiceInputManager {
             let now = Date()
 
             // Max duration — applies in both modes
-            if let start = self.recordingStart,
+            if let start = recordingStartSnapshot,
                 now.timeIntervalSince(start) * 1000 >= maxDurationMs
             {
                 self.triggerAutoStop(interfaceController: interfaceController)
                 return
             }
 
-            // Silence detection — skip during warm-up so the pipeline has time
-            // to stabilise before we start measuring amplitude
-            if let start = self.recordingStart,
+            // Silence detection — skip during warm-up to let the pipeline stabilise.
+            if let start = recordingStartSnapshot,
                 now.timeIntervalSince(start) * 1000 >= VoiceInputManager.warmupMs
             {
                 let peak = newSamples.reduce(0) { max($0, abs(Int($1))) }
@@ -312,7 +410,13 @@ class VoiceInputManager {
         recognitionRequest = nil
         recordingStart = nil
         silenceStart = nil
-        try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+        // Drain firstBufferContinuation so the template Task doesn't hang if stop() fired before the first buffer.
+        let pendingCont = stopLock.withLock { () -> CheckedContinuation<Void, Never>? in
+            let c = firstBufferContinuation
+            firstBufferContinuation = nil
+            return c
+        }
+        pendingCont?.resume()
         if let interfaceController {
             dismissVoiceTemplate(interfaceController: interfaceController)
         }
@@ -327,15 +431,10 @@ class VoiceInputManager {
     // CPVoiceControlState enforces a maximum image size of 150x150 points.
     private static let voiceImageMaxSize = CGSize(width: 150, height: 150)
 
-    // CPVoiceControlState also enforces a 0.3s–5s animation cycle; the 0.3s floor is applied
-    // by the system regardless of what we pass, so we only need to clamp our own ceiling.
+    // CPVoiceControlState enforces a 0.3s–5s animation cycle; the 0.3s floor is system-applied, clamp only the ceiling.
     private static let maxVoiceImageCycleDuration: TimeInterval = 5.0
 
-    // Bypasses RCTConvert for asset images: it collapses animated UIImages to a single frame
-    // via CGImage during scale adjustment. Parser.decodeImage preserves animation frames by
-    // walking every frame in the source via ImageIO — UIImage(data:) never builds a multi-frame
-    // .images array itself, for GIF, APNG, or WebP. Tinting is skipped for animated images since
-    // frames cannot be tinted individually.
+    // Uses Parser.decodeImage instead of RCTConvert to preserve animation frames for GIF/APNG/WebP.
     private func loadVoiceImage(image: Variant_GlyphImage_AssetImage_RemoteImage?, traitCollection: UITraitCollection)
         -> UIImage?
     {
@@ -381,12 +480,13 @@ class VoiceInputManager {
         return nil
     }
 
+    @MainActor
     private func presentVoiceTemplate(
         interfaceController: AutoPlayInterfaceController,
         listeningText: String,
         listeningImage: Variant_GlyphImage_AssetImage_RemoteImage?,
         listeningImageRepeats: Bool?
-    ) {
+    ) async {
         let traitCollection = SceneStore.getRootTraitCollection() ?? UITraitCollection.current
         let image = loadVoiceImage(
             image: listeningImage,
@@ -400,14 +500,21 @@ class VoiceInputManager {
             image: image,
             repeats: repeats
         )
-        let template = CPVoiceControlTemplate(voiceControlStates: [listeningState])
-        initTemplate(template: template, id: "voice-input")
-        voiceControlTemplate = template
 
-        Task { @MainActor in
-            try? await interfaceController.presentTemplate(template, animated: true)
-            template.activateVoiceControlState(withIdentifier: "listening")
+        let voiceTemplate = VoiceInputTemplate(
+            voiceControlStates: [listeningState],
+            id: "voice-input"
+        ) { [weak self] in
+            guard let self else { return }
+            self.stopLock.withLock {
+                if !self.isStopping { self.cancelledByUser = true }
+            }
+            self.stop()
         }
+
+        voiceControlTemplate = voiceTemplate.template
+        try? await interfaceController.presentTemplate(voiceTemplate.template, animated: true)
+        voiceTemplate.template.activateVoiceControlState(withIdentifier: "listening")
     }
 
     private func dismissVoiceTemplate(interfaceController: AutoPlayInterfaceController) {

package/lib/hybrid/HybridVoice.js

@@ -1,10 +1,13 @@
+import { Image } from 'react-native';
 import { NitroModules } from 'react-native-nitro-modules';
 import { NitroImageUtil } from '../utils/NitroImage';
 const _native = NitroModules.createHybridObject('Voice');
 const startVoiceInput = async (options) => {
-    const { onChunk, silenceThresholdMs, maxDurationMs, listeningText, listeningImage, preferSpeechToText, language, } = options ?? {};
+    const { onChunk, silenceThresholdMs, maxDurationMs, listeningText, listeningImage, preferSpeechToText, language, startSound, endSound, } = options ?? {};
     const listeningImageRepeats = listeningImage?.type === 'asset' ? listeningImage.repeats : undefined;
-    return await _native.startVoiceInput(silenceThresholdMs, maxDurationMs, listeningText, NitroImageUtil.convert(listeningImage), listeningImageRepeats, preferSpeechToText, onChunk, language);
+    const startSoundUri = startSound != null ? Image.resolveAssetSource(startSound).uri : undefined;
+    const endSoundUri = endSound != null ? Image.resolveAssetSource(endSound).uri : undefined;
+    return await _native.startVoiceInput(silenceThresholdMs, maxDurationMs, listeningText, NitroImageUtil.convert(listeningImage), listeningImageRepeats, preferSpeechToText, onChunk, language, startSoundUri, endSoundUri);
 };
 export const HybridVoice = {
     /**

package/lib/specs/Voice.nitro.d.ts

@@ -7,6 +7,6 @@ export interface Voice extends HybridObject<{
 }> {
     hasVoiceInputPermission(): boolean;
     requestVoiceInputPermission(): Promise<boolean>;
-    startVoiceInput(silenceThresholdMs?: number, maxDurationMs?: number, listeningText?: string, listeningImage?: NitroImage, listeningImageRepeats?: boolean, preferSpeechToText?: boolean, onChunk?: (chunk: VoiceInputChunk) => void, language?: string): Promise<VoiceInputResult>;
+    startVoiceInput(silenceThresholdMs?: number, maxDurationMs?: number, listeningText?: string, listeningImage?: NitroImage, listeningImageRepeats?: boolean, preferSpeechToText?: boolean, onChunk?: (chunk: VoiceInputChunk) => void, language?: string, startSoundUri?: string, endSoundUri?: string): Promise<VoiceInputResult>;
     stopVoiceInput(): void;
 }

package/lib/types/Voice.d.ts

@@ -18,4 +18,8 @@ export interface VoiceInputOptions {
     preferSpeechToText?: boolean;
     onChunk?: (chunk: VoiceInputChunk) => void;
     language?: string;
+    /** Sound played just before recording starts. Pass a Metro asset: `require('./beep_start.wav')`. */
+    startSound?: number;
+    /** Sound played just after recording stops. Pass a Metro asset: `require('./beep_end.wav')`. */
+    endSound?: number;
 }

package/lib/utils/ErrorUtil.d.ts

@@ -1,3 +1,4 @@
 export declare const ErrorUtil: {
     isTemplateNotFoundError: (error: unknown) => error is Error;
+    isVoiceInputCanceledError: (error: unknown) => error is Error;
 };

package/lib/utils/ErrorUtil.js

@@ -1,4 +1,4 @@
-const isTemplateNotFoundError = (error) => {
+const isError = (error) => {
     if (error == null) {
         return false;
     }
@@ -14,6 +14,18 @@ const isTemplateNotFoundError = (error) => {
     if (typeof error.message !== 'string') {
         return false;
     }
-    return error.message.startsWith('templateNotFound');
+    return true;
+};
+const isTemplateNotFoundError = (error) => {
+    if (isError(error)) {
+        return error.message.startsWith('templateNotFound');
+    }
+    return false;
+};
+const isVoiceInputCanceledError = (error) => {
+    if (isError(error)) {
+        return error.message.startsWith('voiceInputCancelled');
+    }
+    return false;
 };
-export const ErrorUtil = { isTemplateNotFoundError };
+export const ErrorUtil = { isTemplateNotFoundError, isVoiceInputCanceledError };

package/nitrogen/generated/android/c++/JHybridVoiceSpec.cpp

@@ -98,9 +98,9 @@ namespace margelo::nitro::swe::iternio::reactnativeautoplay {
       return __promise;
     }();
   }
-  std::shared_ptr<Promise<VoiceInputResult>> JHybridVoiceSpec::startVoiceInput(std::optional<double> silenceThresholdMs, std::optional<double> maxDurationMs, const std::optional<std::string>& listeningText, const std::optional<std::variant<GlyphImage, AssetImage, RemoteImage>>& listeningImage, std::optional<bool> listeningImageRepeats, std::optional<bool> preferSpeechToText, const std::optional<std::function<void(const VoiceInputChunk& /* chunk */)>>& onChunk, const std::optional<std::string>& language) {
-    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>(jni::alias_ref<jni::JDouble> /* silenceThresholdMs */, jni::alias_ref<jni::JDouble> /* maxDurationMs */, jni::alias_ref<jni::JString> /* listeningText */, jni::alias_ref<JVariant_GlyphImage_AssetImage_RemoteImage> /* listeningImage */, jni::alias_ref<jni::JBoolean> /* listeningImageRepeats */, jni::alias_ref<jni::JBoolean> /* preferSpeechToText */, jni::alias_ref<JFunc_void_VoiceInputChunk::javaobject> /* onChunk */, jni::alias_ref<jni::JString> /* language */)>("startVoiceInput_cxx");
-    auto __result = method(_javaPart, silenceThresholdMs.has_value() ? jni::JDouble::valueOf(silenceThresholdMs.value()) : nullptr, maxDurationMs.has_value() ? jni::JDouble::valueOf(maxDurationMs.value()) : nullptr, listeningText.has_value() ? jni::make_jstring(listeningText.value()) : nullptr, listeningImage.has_value() ? JVariant_GlyphImage_AssetImage_RemoteImage::fromCpp(listeningImage.value()) : nullptr, listeningImageRepeats.has_value() ? jni::JBoolean::valueOf(listeningImageRepeats.value()) : nullptr, preferSpeechToText.has_value() ? jni::JBoolean::valueOf(preferSpeechToText.value()) : nullptr, onChunk.has_value() ? JFunc_void_VoiceInputChunk_cxx::fromCpp(onChunk.value()) : nullptr, language.has_value() ? jni::make_jstring(language.value()) : nullptr);
+  std::shared_ptr<Promise<VoiceInputResult>> JHybridVoiceSpec::startVoiceInput(std::optional<double> silenceThresholdMs, std::optional<double> maxDurationMs, const std::optional<std::string>& listeningText, const std::optional<std::variant<GlyphImage, AssetImage, RemoteImage>>& listeningImage, std::optional<bool> listeningImageRepeats, std::optional<bool> preferSpeechToText, const std::optional<std::function<void(const VoiceInputChunk& /* chunk */)>>& onChunk, const std::optional<std::string>& language, const std::optional<std::string>& startSoundUri, const std::optional<std::string>& endSoundUri) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>(jni::alias_ref<jni::JDouble> /* silenceThresholdMs */, jni::alias_ref<jni::JDouble> /* maxDurationMs */, jni::alias_ref<jni::JString> /* listeningText */, jni::alias_ref<JVariant_GlyphImage_AssetImage_RemoteImage> /* listeningImage */, jni::alias_ref<jni::JBoolean> /* listeningImageRepeats */, jni::alias_ref<jni::JBoolean> /* preferSpeechToText */, jni::alias_ref<JFunc_void_VoiceInputChunk::javaobject> /* onChunk */, jni::alias_ref<jni::JString> /* language */, jni::alias_ref<jni::JString> /* startSoundUri */, jni::alias_ref<jni::JString> /* endSoundUri */)>("startVoiceInput_cxx");
+    auto __result = method(_javaPart, silenceThresholdMs.has_value() ? jni::JDouble::valueOf(silenceThresholdMs.value()) : nullptr, maxDurationMs.has_value() ? jni::JDouble::valueOf(maxDurationMs.value()) : nullptr, listeningText.has_value() ? jni::make_jstring(listeningText.value()) : nullptr, listeningImage.has_value() ? JVariant_GlyphImage_AssetImage_RemoteImage::fromCpp(listeningImage.value()) : nullptr, listeningImageRepeats.has_value() ? jni::JBoolean::valueOf(listeningImageRepeats.value()) : nullptr, preferSpeechToText.has_value() ? jni::JBoolean::valueOf(preferSpeechToText.value()) : nullptr, onChunk.has_value() ? JFunc_void_VoiceInputChunk_cxx::fromCpp(onChunk.value()) : nullptr, language.has_value() ? jni::make_jstring(language.value()) : nullptr, startSoundUri.has_value() ? jni::make_jstring(startSoundUri.value()) : nullptr, endSoundUri.has_value() ? jni::make_jstring(endSoundUri.value()) : nullptr);
     return [&]() {
       auto __promise = Promise<VoiceInputResult>::create();
       __result->cthis()->addOnResolvedListener([=](const jni::alias_ref<jni::JObject>& __boxedResult) {

package/nitrogen/generated/android/c++/JHybridVoiceSpec.hpp

@@ -56,7 +56,7 @@ namespace margelo::nitro::swe::iternio::reactnativeautoplay {
     // Methods
     bool hasVoiceInputPermission() override;
     std::shared_ptr<Promise<bool>> requestVoiceInputPermission() override;
-    std::shared_ptr<Promise<VoiceInputResult>> startVoiceInput(std::optional<double> silenceThresholdMs, std::optional<double> maxDurationMs, const std::optional<std::string>& listeningText, const std::optional<std::variant<GlyphImage, AssetImage, RemoteImage>>& listeningImage, std::optional<bool> listeningImageRepeats, std::optional<bool> preferSpeechToText, const std::optional<std::function<void(const VoiceInputChunk& /* chunk */)>>& onChunk, const std::optional<std::string>& language) override;
+    std::shared_ptr<Promise<VoiceInputResult>> startVoiceInput(std::optional<double> silenceThresholdMs, std::optional<double> maxDurationMs, const std::optional<std::string>& listeningText, const std::optional<std::variant<GlyphImage, AssetImage, RemoteImage>>& listeningImage, std::optional<bool> listeningImageRepeats, std::optional<bool> preferSpeechToText, const std::optional<std::function<void(const VoiceInputChunk& /* chunk */)>>& onChunk, const std::optional<std::string>& language, const std::optional<std::string>& startSoundUri, const std::optional<std::string>& endSoundUri) override;
     void stopVoiceInput() override;
 
   private:

package/nitrogen/generated/android/kotlin/com/margelo/nitro/swe/iternio/reactnativeautoplay/HybridVoiceSpec.kt

@@ -37,12 +37,12 @@ abstract class HybridVoiceSpec: HybridObject() {
   @Keep
   abstract fun requestVoiceInputPermission(): Promise<Boolean>
   
-  abstract fun startVoiceInput(silenceThresholdMs: Double?, maxDurationMs: Double?, listeningText: String?, listeningImage: Variant_GlyphImage_AssetImage_RemoteImage?, listeningImageRepeats: Boolean?, preferSpeechToText: Boolean?, onChunk: ((chunk: VoiceInputChunk) -> Unit)?, language: String?): Promise<VoiceInputResult>
+  abstract fun startVoiceInput(silenceThresholdMs: Double?, maxDurationMs: Double?, listeningText: String?, listeningImage: Variant_GlyphImage_AssetImage_RemoteImage?, listeningImageRepeats: Boolean?, preferSpeechToText: Boolean?, onChunk: ((chunk: VoiceInputChunk) -> Unit)?, language: String?, startSoundUri: String?, endSoundUri: String?): Promise<VoiceInputResult>
   
   @DoNotStrip
   @Keep
-  private fun startVoiceInput_cxx(silenceThresholdMs: Double?, maxDurationMs: Double?, listeningText: String?, listeningImage: Variant_GlyphImage_AssetImage_RemoteImage?, listeningImageRepeats: Boolean?, preferSpeechToText: Boolean?, onChunk: Func_void_VoiceInputChunk?, language: String?): Promise<VoiceInputResult> {
-    val __result = startVoiceInput(silenceThresholdMs, maxDurationMs, listeningText, listeningImage, listeningImageRepeats, preferSpeechToText, onChunk?.let { it }, language)
+  private fun startVoiceInput_cxx(silenceThresholdMs: Double?, maxDurationMs: Double?, listeningText: String?, listeningImage: Variant_GlyphImage_AssetImage_RemoteImage?, listeningImageRepeats: Boolean?, preferSpeechToText: Boolean?, onChunk: Func_void_VoiceInputChunk?, language: String?, startSoundUri: String?, endSoundUri: String?): Promise<VoiceInputResult> {
+    val __result = startVoiceInput(silenceThresholdMs, maxDurationMs, listeningText, listeningImage, listeningImageRepeats, preferSpeechToText, onChunk?.let { it }, language, startSoundUri, endSoundUri)
     return __result
   }
   

package/nitrogen/generated/ios/c++/HybridVoiceSpecSwift.hpp

@@ -107,8 +107,8 @@ namespace margelo::nitro::swe::iternio::reactnativeautoplay {
       auto __value = std::move(__result.value());
       return __value;
     }
-    inline std::shared_ptr<Promise<VoiceInputResult>> startVoiceInput(std::optional<double> silenceThresholdMs, std::optional<double> maxDurationMs, const std::optional<std::string>& listeningText, const std::optional<std::variant<GlyphImage, AssetImage, RemoteImage>>& listeningImage, std::optional<bool> listeningImageRepeats, std::optional<bool> preferSpeechToText, const std::optional<std::function<void(const VoiceInputChunk& /* chunk */)>>& onChunk, const std::optional<std::string>& language) override {
-      auto __result = _swiftPart.startVoiceInput(silenceThresholdMs, maxDurationMs, listeningText, listeningImage, listeningImageRepeats, preferSpeechToText, onChunk, language);
+    inline std::shared_ptr<Promise<VoiceInputResult>> startVoiceInput(std::optional<double> silenceThresholdMs, std::optional<double> maxDurationMs, const std::optional<std::string>& listeningText, const std::optional<std::variant<GlyphImage, AssetImage, RemoteImage>>& listeningImage, std::optional<bool> listeningImageRepeats, std::optional<bool> preferSpeechToText, const std::optional<std::function<void(const VoiceInputChunk& /* chunk */)>>& onChunk, const std::optional<std::string>& language, const std::optional<std::string>& startSoundUri, const std::optional<std::string>& endSoundUri) override {
+      auto __result = _swiftPart.startVoiceInput(silenceThresholdMs, maxDurationMs, listeningText, listeningImage, listeningImageRepeats, preferSpeechToText, onChunk, language, startSoundUri, endSoundUri);
       if (__result.hasError()) [[unlikely]] {
         std::rethrow_exception(__result.error());
       }

package/nitrogen/generated/ios/swift/HybridVoiceSpec.swift

@@ -15,7 +15,7 @@ public protocol HybridVoiceSpec_protocol: HybridObject {
   // Methods
   func hasVoiceInputPermission() throws -> Bool
   func requestVoiceInputPermission() throws -> Promise<Bool>
-  func startVoiceInput(silenceThresholdMs: Double?, maxDurationMs: Double?, listeningText: String?, listeningImage: Variant_GlyphImage_AssetImage_RemoteImage?, listeningImageRepeats: Bool?, preferSpeechToText: Bool?, onChunk: ((_ chunk: VoiceInputChunk) -> Void)?, language: String?) throws -> Promise<VoiceInputResult>
+  func startVoiceInput(silenceThresholdMs: Double?, maxDurationMs: Double?, listeningText: String?, listeningImage: Variant_GlyphImage_AssetImage_RemoteImage?, listeningImageRepeats: Bool?, preferSpeechToText: Bool?, onChunk: ((_ chunk: VoiceInputChunk) -> Void)?, language: String?, startSoundUri: String?, endSoundUri: String?) throws -> Promise<VoiceInputResult>
   func stopVoiceInput() throws -> Void
 }
 

package/nitrogen/generated/ios/swift/HybridVoiceSpec_cxx.swift

@@ -156,7 +156,7 @@ open class HybridVoiceSpec_cxx {
   }
   
   @inline(__always)
-  public final func startVoiceInput(silenceThresholdMs: bridge.std__optional_double_, maxDurationMs: bridge.std__optional_double_, listeningText: bridge.std__optional_std__string_, listeningImage: bridge.std__optional_std__variant_GlyphImage__AssetImage__RemoteImage__, listeningImageRepeats: bridge.std__optional_bool_, preferSpeechToText: bridge.std__optional_bool_, onChunk: bridge.std__optional_std__function_void_const_VoiceInputChunk_____chunk______, language: bridge.std__optional_std__string_) -> bridge.Result_std__shared_ptr_Promise_VoiceInputResult___ {
+  public final func startVoiceInput(silenceThresholdMs: bridge.std__optional_double_, maxDurationMs: bridge.std__optional_double_, listeningText: bridge.std__optional_std__string_, listeningImage: bridge.std__optional_std__variant_GlyphImage__AssetImage__RemoteImage__, listeningImageRepeats: bridge.std__optional_bool_, preferSpeechToText: bridge.std__optional_bool_, onChunk: bridge.std__optional_std__function_void_const_VoiceInputChunk_____chunk______, language: bridge.std__optional_std__string_, startSoundUri: bridge.std__optional_std__string_, endSoundUri: bridge.std__optional_std__string_) -> bridge.Result_std__shared_ptr_Promise_VoiceInputResult___ {
     do {
       let __result = try self.__implementation.startVoiceInput(silenceThresholdMs: { () -> Double? in
         if bridge.has_value_std__optional_double_(silenceThresholdMs) {
@@ -234,6 +234,20 @@ open class HybridVoiceSpec_cxx {
         } else {
           return nil
         }
+      }(), startSoundUri: { () -> String? in
+        if bridge.has_value_std__optional_std__string_(startSoundUri) {
+          let __unwrapped = bridge.get_std__optional_std__string_(startSoundUri)
+          return String(__unwrapped)
+        } else {
+          return nil
+        }
+      }(), endSoundUri: { () -> String? in
+        if bridge.has_value_std__optional_std__string_(endSoundUri) {
+          let __unwrapped = bridge.get_std__optional_std__string_(endSoundUri)
+          return String(__unwrapped)
+        } else {
+          return nil
+        }
       }())
       let __resultCpp = { () -> bridge.std__shared_ptr_Promise_VoiceInputResult__ in
         let __promise = bridge.create_std__shared_ptr_Promise_VoiceInputResult__()

package/nitrogen/generated/shared/c++/HybridVoiceSpec.hpp

@@ -68,7 +68,7 @@ namespace margelo::nitro::swe::iternio::reactnativeautoplay {
       // Methods
       virtual bool hasVoiceInputPermission() = 0;
       virtual std::shared_ptr<Promise<bool>> requestVoiceInputPermission() = 0;
-      virtual std::shared_ptr<Promise<VoiceInputResult>> startVoiceInput(std::optional<double> silenceThresholdMs, std::optional<double> maxDurationMs, const std::optional<std::string>& listeningText, const std::optional<std::variant<GlyphImage, AssetImage, RemoteImage>>& listeningImage, std::optional<bool> listeningImageRepeats, std::optional<bool> preferSpeechToText, const std::optional<std::function<void(const VoiceInputChunk& /* chunk */)>>& onChunk, const std::optional<std::string>& language) = 0;
+      virtual std::shared_ptr<Promise<VoiceInputResult>> startVoiceInput(std::optional<double> silenceThresholdMs, std::optional<double> maxDurationMs, const std::optional<std::string>& listeningText, const std::optional<std::variant<GlyphImage, AssetImage, RemoteImage>>& listeningImage, std::optional<bool> listeningImageRepeats, std::optional<bool> preferSpeechToText, const std::optional<std::function<void(const VoiceInputChunk& /* chunk */)>>& onChunk, const std::optional<std::string>& language, const std::optional<std::string>& startSoundUri, const std::optional<std::string>& endSoundUri) = 0;
       virtual void stopVoiceInput() = 0;
 
     protected:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iternio/react-native-auto-play",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Android Auto and Apple CarPlay for react-native",
   "main": "lib/index",
   "module": "lib/index",

package/src/hybrid/HybridVoice.ts

@@ -1,3 +1,4 @@
+import { Image } from 'react-native';
 import { NitroModules } from 'react-native-nitro-modules';
 import type { Voice } from '../specs/Voice.nitro';
 import type { VoiceInputOptions, VoiceInputResult } from '../types/Voice';
@@ -21,11 +22,16 @@ const startVoiceInput: StartVoiceInput = async (options?: VoiceInputOptions) =>
     listeningImage,
     preferSpeechToText,
     language,
+    startSound,
+    endSound,
   } = options ?? {};
 
   const listeningImageRepeats =
     listeningImage?.type === 'asset' ? listeningImage.repeats : undefined;
 
+  const startSoundUri = startSound != null ? Image.resolveAssetSource(startSound).uri : undefined;
+  const endSoundUri = endSound != null ? Image.resolveAssetSource(endSound).uri : undefined;
+
   return await _native.startVoiceInput(
     silenceThresholdMs,
     maxDurationMs,
@@ -34,7 +40,9 @@ const startVoiceInput: StartVoiceInput = async (options?: VoiceInputOptions) =>
     listeningImageRepeats,
     preferSpeechToText,
     onChunk,
-    language
+    language,
+    startSoundUri,
+    endSoundUri
   );
 };
 

package/src/specs/Voice.nitro.ts

@@ -13,7 +13,9 @@ export interface Voice extends HybridObject<{ android: 'kotlin'; ios: 'swift' }>
     listeningImageRepeats?: boolean,
     preferSpeechToText?: boolean,
     onChunk?: (chunk: VoiceInputChunk) => void,
-    language?: string
+    language?: string,
+    startSoundUri?: string,
+    endSoundUri?: string
   ): Promise<VoiceInputResult>;
   stopVoiceInput(): void;
 }

package/src/types/Voice.ts

@@ -21,4 +21,8 @@ export interface VoiceInputOptions {
   preferSpeechToText?: boolean;
   onChunk?: (chunk: VoiceInputChunk) => void;
   language?: string;
+  /** Sound played just before recording starts. Pass a Metro asset: `require('./beep_start.wav')`. */
+  startSound?: number;
+  /** Sound played just after recording stops. Pass a Metro asset: `require('./beep_end.wav')`. */
+  endSound?: number;
 }

package/src/utils/ErrorUtil.ts

@@ -1,4 +1,4 @@
-const isTemplateNotFoundError = (error: unknown): error is Error => {
+const isError = (error: unknown): error is { message: string } => {
   if (error == null) {
     return false;
   }
@@ -19,7 +19,23 @@ const isTemplateNotFoundError = (error: unknown): error is Error => {
     return false;
   }
 
-  return error.message.startsWith('templateNotFound');
+  return true;
+};
+
+const isTemplateNotFoundError = (error: unknown): error is Error => {
+  if (isError(error)) {
+    return error.message.startsWith('templateNotFound');
+  }
+
+  return false;
+};
+
+const isVoiceInputCanceledError = (error: unknown): error is Error => {
+  if (isError(error)) {
+    return error.message.startsWith('voiceInputCancelled');
+  }
+
+  return false;
 };
 
-export const ErrorUtil = { isTemplateNotFoundError };
+export const ErrorUtil = { isTemplateNotFoundError, isVoiceInputCanceledError };