@gmessier/nitro-speech 0.4.1 → 0.4.2

package/README.md

@@ -155,7 +155,8 @@ Because of that, treat it as a **single session owner** setup hook: use it once
 import { useRecognizer } from '@gmessier/nitro-speech';
 
 function MyComponent() {
-  const { 
+  const {
+    prewarm,
     startListening, 
     stopListening, 
     resetAutoFinishTime, 
@@ -261,6 +262,7 @@ If you need to call recognizer methods from other components without prop drilli
 ```typescript
 import { RecognizerRef } from '@gmessier/nitro-speech';
 
+RecognizerRef.prewarm({ locale: 'en-US' });
 RecognizerRef.startListening({ locale: 'en-US' });
 RecognizerRef.addAutoFinishTime(5000);
 RecognizerRef.resetAutoFinishTime();
@@ -357,12 +359,20 @@ function MyComponent() {
 
 `SpeechRecognizer` is the hybrid object. It gives direct access to callbacks and control methods, but it is unsafe to orchestrate the full session directly from it.
 
+**Warning**: Since it reflects the original hybrid object, its API may change in the future.
+
 ```typescript
-import { SpeechRecognizer, speechRecognizerVolumeChangeHandler } from '@gmessier/nitro-speech';
+import { 
+  SpeechRecognizer, 
+  speechRecognizerVolumeChangeHandler,
+  speechRecognizerActiveStateHandler,
+} from '@gmessier/nitro-speech';
 
 // Set up callbacks
 SpeechRecognizer.onReadyForSpeech = () => {
   console.log('Listening...');
+  // Add speechRecognizerActiveStateHandler to enable useRecognizerIsActive hook manually
+  speechRecognizerActiveStateHandler(true);
 };
 
 SpeechRecognizer.onResult = (textBatches) => {
@@ -371,6 +381,8 @@ SpeechRecognizer.onResult = (textBatches) => {
 
 SpeechRecognizer.onRecordingStopped = () => {
   console.log('Stopped');
+  // Add speechRecognizerActiveStateHandler to enable useRecognizerIsActive hook manually
+  speechRecognizerActiveStateHandler(false);
 };
 
 SpeechRecognizer.onAutoFinishProgress = (timeLeftMs) => {
@@ -387,10 +399,27 @@ SpeechRecognizer.onPermissionDenied = () => {
 
 SpeechRecognizer.onVolumeChange = (volume) => {
   console.log('new volume: ', volume);
+  // Add speechRecognizerVolumeChangeHandler to enable useVoiceInputVolume hook manually
+  speechRecognizerVolumeChangeHandler(volume);
 };
-// OR use speechRecognizerVolumeChangeHandler to enable useVoiceInputVolume hook manually
-SpeechRecognizer.onVolumeChange = speechRecognizerVolumeChangeHandler
 
+// Prepare resources, download assets, confirms locale availability
+SpeechRecognizer.prewarm({
+  locale: 'en-US',
+  // ... your config to prepare
+});
+// OR `await` if you want to react to the success
+await SpeechRecognizer.prewarm({
+  locale: 'en-US',
+  // ... your config to prepare
+});
+// OR from worklet (only sync)
+scheduleOnRuntime(workletRuntime, () => {
+  SpeechRecognizer.prewarm({
+    locale: 'en-US',
+    // ... your config to prepare
+  });
+});
 
 // Start listening
 SpeechRecognizer.startListening({

package/lib/Recognizer/RecognizerRef.js

@@ -1,10 +1,11 @@
-import { recognizerAddAutoFinishTime, recognizerGetSupportedLocalesIOS, recognizerGetIsActive, recognizerResetAutoFinishTime, recognizerStartListening, recognizerStopListening, recognizerUpdateConfig, recognizerGetVoiceInputVolume, } from './methods';
+import { recognizerAddAutoFinishTime, recognizerGetSupportedLocalesIOS, recognizerGetIsActive, recognizerResetAutoFinishTime, recognizerStartListening, recognizerStopListening, recognizerUpdateConfig, recognizerGetVoiceInputVolume, recognizerPrewarm, } from './methods';
 /**
  * Safe cross-component reference to the Speech Recognizer methods.
  *
  * All methods support worklets and UI thread calls
  */
 export const RecognizerRef = {
+    prewarm: recognizerPrewarm,
     startListening: recognizerStartListening,
     stopListening: recognizerStopListening,
     resetAutoFinishTime: recognizerResetAutoFinishTime,

package/lib/Recognizer/SpeechRecognizer.d.ts

@@ -3,6 +3,7 @@
  *
  * Direct access to the all Speech Recognizer methods and callbacks.
  *
- * @note unsafe, might lead to race conditions
+ * @note Unsafe, might lead to race conditions
+ * @warning Since it reflects the original hybrid object, its API may change in the future.
  */
 export declare const SpeechRecognizer: import("./types").RecognizerSpec;

package/lib/Recognizer/SpeechRecognizer.js

@@ -4,6 +4,7 @@ import { NitroSpeech } from '../NitroSpeech';
  *
  * Direct access to the all Speech Recognizer methods and callbacks.
  *
- * @note unsafe, might lead to race conditions
+ * @note Unsafe, might lead to race conditions
+ * @warning Since it reflects the original hybrid object, its API may change in the future.
  */
 export const SpeechRecognizer = NitroSpeech.recognizer;

package/lib/Recognizer/methods.d.ts

@@ -1,9 +1,10 @@
-import type { SpeechRecognitionConfig } from './types';
-export declare const recognizerStartListening: (params: SpeechRecognitionConfig) => void;
+import type { MutableSpeechRecognitionConfig, SpeechRecognitionConfig } from './types';
+export declare const recognizerPrewarm: (params?: SpeechRecognitionConfig) => Promise<void>;
+export declare const recognizerStartListening: (params?: SpeechRecognitionConfig) => void;
 export declare const recognizerStopListening: () => void;
 export declare const recognizerResetAutoFinishTime: () => void;
 export declare const recognizerAddAutoFinishTime: (additionalTimeMs?: number) => void;
-export declare const recognizerUpdateConfig: (newConfig: SpeechRecognitionConfig, resetAutoFinishTime?: boolean) => void;
+export declare const recognizerUpdateConfig: (newConfig?: MutableSpeechRecognitionConfig, resetAutoFinishTime?: boolean) => void;
 export declare const recognizerGetIsActive: () => boolean;
 export declare const recognizerGetVoiceInputVolume: () => import("./types").VolumeChangeEvent;
 export declare const recognizerGetSupportedLocalesIOS: () => string[];

package/lib/Recognizer/methods.js

@@ -1,4 +1,8 @@
 import { SpeechRecognizer } from './SpeechRecognizer';
+export const recognizerPrewarm = (params) => {
+    'worklet';
+    return SpeechRecognizer.prewarm(params);
+};
 export const recognizerStartListening = (params) => {
     'worklet';
     SpeechRecognizer.startListening(params);

package/lib/Recognizer/types.d.ts

@@ -1,6 +1,6 @@
 import type { Recognizer as RecognizerSpec } from '../specs/Recognizer.nitro';
-import type { SpeechRecognitionConfig } from '../specs/SpeechRecognitionConfig';
+import type { MutableSpeechRecognitionConfig, SpeechRecognitionConfig } from '../specs/SpeechRecognitionConfig';
 import type { VolumeChangeEvent } from '../specs/VolumeChangeEvent';
 type RecognizerCallbacks = Pick<RecognizerSpec, 'onReadyForSpeech' | 'onRecordingStopped' | 'onResult' | 'onAutoFinishProgress' | 'onError' | 'onPermissionDenied' | 'onVolumeChange'>;
-type RecognizerMethods = Pick<RecognizerSpec, 'startListening' | 'stopListening' | 'resetAutoFinishTime' | 'addAutoFinishTime' | 'updateConfig' | 'getIsActive' | 'getVoiceInputVolume' | 'getSupportedLocalesIOS'>;
-export type { RecognizerSpec, SpeechRecognitionConfig, VolumeChangeEvent, RecognizerCallbacks, RecognizerMethods, };
+type RecognizerMethods = Pick<RecognizerSpec, 'prewarm' | 'startListening' | 'stopListening' | 'resetAutoFinishTime' | 'addAutoFinishTime' | 'updateConfig' | 'getIsActive' | 'getVoiceInputVolume' | 'getSupportedLocalesIOS'>;
+export type { RecognizerSpec, SpeechRecognitionConfig, MutableSpeechRecognitionConfig, VolumeChangeEvent, RecognizerCallbacks, RecognizerMethods, };

package/lib/Recognizer/useRecognizer.js

@@ -1,5 +1,5 @@
 import { useEffect } from 'react';
-import { recognizerResetAutoFinishTime, recognizerAddAutoFinishTime, recognizerUpdateConfig, recognizerGetIsActive, recognizerGetSupportedLocalesIOS, recognizerStartListening, recognizerStopListening, recognizerGetVoiceInputVolume, } from './methods';
+import { recognizerResetAutoFinishTime, recognizerAddAutoFinishTime, recognizerUpdateConfig, recognizerGetIsActive, recognizerGetSupportedLocalesIOS, recognizerStartListening, recognizerStopListening, recognizerGetVoiceInputVolume, recognizerPrewarm, } from './methods';
 import { SpeechRecognizer } from './SpeechRecognizer';
 import { speechRecognizerVolumeChangeHandler } from './useVoiceInputVolume';
 import { speechRecognizerActiveStateHandler } from './useRecognizerIsActive';
@@ -59,6 +59,7 @@ export const useRecognizer = (callbacks, destroyDeps = []) => {
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [...destroyDeps]);
     return {
+        prewarm: recognizerPrewarm,
         startListening: recognizerStartListening,
         stopListening: recognizerStopListening,
         resetAutoFinishTime: recognizerResetAutoFinishTime,

package/lib/index.d.ts

@@ -1,7 +1,7 @@
-export * from './Recognizer/types';
 export { useRecognizer } from './Recognizer/useRecognizer';
 export { useVoiceInputVolume, speechRecognizerVolumeChangeHandler, } from './Recognizer/useVoiceInputVolume';
 export { useRecognizerIsActive, speechRecognizerActiveStateHandler, } from './Recognizer/useRecognizerIsActive';
 export { SpeechRecognizer } from './Recognizer/SpeechRecognizer';
 export { RecognizerRef } from './Recognizer/RecognizerRef';
 export { NitroSpeech } from './NitroSpeech';
+export { type RecognizerSpec, type SpeechRecognitionConfig, type MutableSpeechRecognitionConfig, type VolumeChangeEvent, type RecognizerCallbacks, type RecognizerMethods, } from './Recognizer/types';

package/lib/index.js

@@ -1,7 +1,7 @@
-export * from './Recognizer/types';
 export { useRecognizer } from './Recognizer/useRecognizer';
 export { useVoiceInputVolume, speechRecognizerVolumeChangeHandler, } from './Recognizer/useVoiceInputVolume';
 export { useRecognizerIsActive, speechRecognizerActiveStateHandler, } from './Recognizer/useRecognizerIsActive';
 export { SpeechRecognizer } from './Recognizer/SpeechRecognizer';
 export { RecognizerRef } from './Recognizer/RecognizerRef';
 export { NitroSpeech } from './NitroSpeech';
+export {} from './Recognizer/types';

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

@@ -8,9 +8,24 @@ export interface Recognizer extends HybridObject<{
     /**
      * Prepare the speech recognition engine and the model for the given parameters.
      *
-     * Omit the {@linkcode Promise} result if want to run synchronously.
+     * @notes
+     * - Not required, {@linkcode startListening} will prewarm automatically.
+     *
+     * - Omit the {@linkcode Promise} result if you want to run synchronously.
      * {@linkcode startListening} will start and resolve it automatically.
-     * Only `await` if run beforehand and want to react on the success
+     *
+     * - Only `await` if run beforehand and you want to react to the success
+     *
+     * @worklet **Do not** use `await` on Worklet or UI runtimes. It will not work properly.
+     *
+     * You can run it synchronously:
+     * ```typescript
+     *  scheduleOnRuntime(workletRuntime, () => {
+     *    RecognizerRef.prewarm({
+     *      // your config to prepare
+     *    });
+     *  });
+     * ```
      */
     prewarm(defaultParams?: SpeechRecognitionConfig): Promise<void>;
     /**
@@ -24,9 +39,9 @@ export interface Recognizer extends HybridObject<{
      */
     startListening(params?: SpeechRecognitionConfig): void;
     /**
-     * Stops the speech recognition. if not started, does nothing.
+     * Stops the speech recognition. If not started, does nothing.
      *
-     * Not a sync operation for android, delay about 250ms to polish the result.
+     * Not a sync operation for Android, delay about 250ms to polish the result.
      *
      * Use {@linkcode onRecordingStopped} to handle the stop event.
      */
@@ -78,8 +93,6 @@ export interface Recognizer extends HybridObject<{
      * Fires every {@linkcode SpeechRecognitionConfig.autoFinishProgressIntervalMs} or 1000ms
      *
      * Time left in milliseconds until the timer stops.
-     *
-     * @note not implemented for Android yet.
      */
     onAutoFinishProgress?: (timeLeftMs: number) => void;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmessier/nitro-speech",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "React Native Real-time Speech Recognition Library powered by Nitro Modules",
   "main": "./lib/index.js",
   "module": "./lib/index.js",

package/src/Recognizer/RecognizerRef.ts

@@ -8,6 +8,7 @@ import {
   recognizerStopListening,
   recognizerUpdateConfig,
   recognizerGetVoiceInputVolume,
+  recognizerPrewarm,
 } from './methods'
 
 /**
@@ -16,6 +17,7 @@ import {
  * All methods support worklets and UI thread calls
  */
 export const RecognizerRef: RecognizerMethods = {
+  prewarm: recognizerPrewarm,
   startListening: recognizerStartListening,
   stopListening: recognizerStopListening,
   resetAutoFinishTime: recognizerResetAutoFinishTime,

package/src/Recognizer/SpeechRecognizer.ts

@@ -5,6 +5,7 @@ import { NitroSpeech } from '../NitroSpeech'
  *
  * Direct access to the all Speech Recognizer methods and callbacks.
  *
- * @note unsafe, might lead to race conditions
+ * @note Unsafe, might lead to race conditions
+ * @warning Since it reflects the original hybrid object, its API may change in the future.
  */
 export const SpeechRecognizer = NitroSpeech.recognizer

package/src/Recognizer/methods.ts

@@ -1,7 +1,15 @@
 import { SpeechRecognizer } from './SpeechRecognizer'
-import type { SpeechRecognitionConfig } from './types'
+import type {
+  MutableSpeechRecognitionConfig,
+  SpeechRecognitionConfig,
+} from './types'
 
-export const recognizerStartListening = (params: SpeechRecognitionConfig) => {
+export const recognizerPrewarm = (params?: SpeechRecognitionConfig) => {
+  'worklet'
+  return SpeechRecognizer.prewarm(params)
+}
+
+export const recognizerStartListening = (params?: SpeechRecognitionConfig) => {
   'worklet'
   SpeechRecognizer.startListening(params)
 }
@@ -22,7 +30,7 @@ export const recognizerAddAutoFinishTime = (additionalTimeMs?: number) => {
 }
 
 export const recognizerUpdateConfig = (
-  newConfig: SpeechRecognitionConfig,
+  newConfig?: MutableSpeechRecognitionConfig,
   resetAutoFinishTime?: boolean
 ) => {
   'worklet'

package/src/Recognizer/types.ts

@@ -1,5 +1,8 @@
 import type { Recognizer as RecognizerSpec } from '../specs/Recognizer.nitro'
-import type { SpeechRecognitionConfig } from '../specs/SpeechRecognitionConfig'
+import type {
+  MutableSpeechRecognitionConfig,
+  SpeechRecognitionConfig,
+} from '../specs/SpeechRecognitionConfig'
 import type { VolumeChangeEvent } from '../specs/VolumeChangeEvent'
 
 type RecognizerCallbacks = Pick<
@@ -15,6 +18,7 @@ type RecognizerCallbacks = Pick<
 
 type RecognizerMethods = Pick<
   RecognizerSpec,
+  | 'prewarm'
   | 'startListening'
   | 'stopListening'
   | 'resetAutoFinishTime'
@@ -28,6 +32,7 @@ type RecognizerMethods = Pick<
 export type {
   RecognizerSpec,
   SpeechRecognitionConfig,
+  MutableSpeechRecognitionConfig,
   VolumeChangeEvent,
   RecognizerCallbacks,
   RecognizerMethods,

package/src/Recognizer/useRecognizer.ts

@@ -8,6 +8,7 @@ import {
   recognizerStartListening,
   recognizerStopListening,
   recognizerGetVoiceInputVolume,
+  recognizerPrewarm,
 } from './methods'
 import type { RecognizerCallbacks, RecognizerMethods } from './types'
 import { SpeechRecognizer } from './SpeechRecognizer'
@@ -75,6 +76,7 @@ export const useRecognizer = (
   }, [...destroyDeps])
 
   return {
+    prewarm: recognizerPrewarm,
     startListening: recognizerStartListening,
     stopListening: recognizerStopListening,
     resetAutoFinishTime: recognizerResetAutoFinishTime,

package/src/index.ts

@@ -1,4 +1,3 @@
-export * from './Recognizer/types'
 export { useRecognizer } from './Recognizer/useRecognizer'
 export {
   useVoiceInputVolume,
@@ -11,3 +10,11 @@ export {
 export { SpeechRecognizer } from './Recognizer/SpeechRecognizer'
 export { RecognizerRef } from './Recognizer/RecognizerRef'
 export { NitroSpeech } from './NitroSpeech'
+export {
+  type RecognizerSpec,
+  type SpeechRecognitionConfig,
+  type MutableSpeechRecognitionConfig,
+  type VolumeChangeEvent,
+  type RecognizerCallbacks,
+  type RecognizerMethods,
+} from './Recognizer/types'

package/src/specs/Recognizer.nitro.ts

@@ -12,9 +12,24 @@ export interface Recognizer extends HybridObject<{
   /**
    * Prepare the speech recognition engine and the model for the given parameters.
    *
-   * Omit the {@linkcode Promise} result if want to run synchronously.
+   * @notes
+   * - Not required, {@linkcode startListening} will prewarm automatically.
+   *
+   * - Omit the {@linkcode Promise} result if you want to run synchronously.
    * {@linkcode startListening} will start and resolve it automatically.
-   * Only `await` if run beforehand and want to react on the success
+   *
+   * - Only `await` if run beforehand and you want to react to the success
+   *
+   * @worklet **Do not** use `await` on Worklet or UI runtimes. It will not work properly.
+   *
+   * You can run it synchronously:
+   * ```typescript
+   *  scheduleOnRuntime(workletRuntime, () => {
+   *    RecognizerRef.prewarm({
+   *      // your config to prepare
+   *    });
+   *  });
+   * ```
    */
   prewarm(defaultParams?: SpeechRecognitionConfig): Promise<void>
 
@@ -30,9 +45,9 @@ export interface Recognizer extends HybridObject<{
   startListening(params?: SpeechRecognitionConfig): void
 
   /**
-   * Stops the speech recognition. if not started, does nothing.
+   * Stops the speech recognition. If not started, does nothing.
    *
-   * Not a sync operation for android, delay about 250ms to polish the result.
+   * Not a sync operation for Android, delay about 250ms to polish the result.
    *
    * Use {@linkcode onRecordingStopped} to handle the stop event.
    */
@@ -94,8 +109,6 @@ export interface Recognizer extends HybridObject<{
    * Fires every {@linkcode SpeechRecognitionConfig.autoFinishProgressIntervalMs} or 1000ms
    *
    * Time left in milliseconds until the timer stops.
-   *
-   * @note not implemented for Android yet.
    */
   onAutoFinishProgress?: (timeLeftMs: number) => void
   /**