Skip to content

migration.md

Latest commit

 

History

History
193 lines (143 loc) · 7.24 KB

migration.md

File metadata and controls

193 lines (143 loc) · 7.24 KB

Migration Guides

Breaking changes (upgrading to 0.3.0)

If you are upgrading from an earlier version to 0.3.0, plan for the following migration steps.

Instance-based API (TTS + STT)

TTS and STT now use an instance-based factory pattern instead of module-level singletons. Each call to createTTS() / createSTT() returns an independent engine instance. You must call .destroy() when done to free native resources.

TTS Before:

initializeTTS({ modelPath: { type: 'asset', path: 'models/vits' } });
const audio = await generateSpeech('Hello');
await unloadTTS();

TTS After:

const tts = await createTTS({ modelPath: { type: 'asset', path: 'models/vits' } });
const audio = await tts.generateSpeech('Hello');
await tts.destroy();

STT Before:

await initializeSTT({ modelPath: { type: 'asset', path: 'models/whisper' } });
const result = await transcribeFile('/audio.wav');
await unloadSTT();

STT After:

const stt = await createSTT({ modelPath: { type: 'asset', path: 'models/whisper' } });
const result = await stt.transcribeFile('/audio.wav');
await stt.destroy();

Speech-to-Text (STT)

  • transcribeFile now returns Promise<SttRecognitionResult> (an object with text, tokens, timestamps, lang, emotion, event, durations) instead of Promise<string>. For text only, use (await transcribeFile(path)).text.
  • initializeSTT supports two additional optional options: hotwordsFile and hotwordsScore. The native TurboModule methods were renamed from initializeSherpaOnnx / unloadSherpaOnnx to initializeStt / unloadStt.
  • Removed deprecated type: TranscriptionResult has been removed. Use SttRecognitionResult instead (same shape).

Text-to-Speech (TTS)

  • Instance-based API: Use createTTS() to get a TtsEngine; call tts.generateSpeech(), tts.generateSpeechStream(), etc., then tts.destroy(). See Instance-based API (TTS + STT) above. If you call the TurboModule directly, all instance-bound methods now take instanceId as the first parameter (see docs/tts.md – Mapping to Native API).
  • TTS model-specific options (breaking for versions < 0.3.0):
    Init and update no longer use flat noiseScale, noiseScaleW, and lengthScale on the options object. Use modelOptions instead, with one block per model type (aligned with the STT modelOptions design):
    • createTTS (init): Replace flat noiseScale, noiseScaleW, lengthScale with modelOptions. Only the block for the loaded model type is applied.
      Before (old API): initializeTTS({ modelPath, modelType: 'vits', noiseScale: 0.667, noiseScaleW: 0.8, lengthScale: 1.0 })
      After: createTTS({ modelPath, modelType: 'vits', modelOptions: { vits: { noiseScale: 0.667, noiseScaleW: 0.8, lengthScale: 1.0 } } })
    • tts.updateParams: Replace flat noiseScale / noiseScaleW / lengthScale with modelOptions (and optionally modelType). When modelType is omitted, the engine uses the type from createTTS().
      Before (old API): updateTtsParams({ noiseScale: 0.7, lengthScale: 1.2 })
      After: tts.updateParams({ modelOptions: { vits: { noiseScale: 0.7, lengthScale: 1.2 } } }) or tts.updateParams({ modelType: 'vits', modelOptions: { vits: { ... } } })
    • Types: TtsModelOptions, TtsVitsModelOptions, TtsMatchaModelOptions, TtsKokoroModelOptions, TtsKittenModelOptions, TtsPocketModelOptions are exported from the TTS module. See docs/tts.md for details.
  • Removed deprecated type: SynthesisOptions has been removed. Use TtsGenerationOptions instead (same shape).

Download Manager API (upgrading to 0.4.0)

This release redesigns the public download manager API for SDK consumers.

Renamed Functions

Before After Notes
ensureModelByCategory ensureModel High-level flow unchanged
refreshModelsByCategory refreshModels
listModelsByCategory listModels
getModelByIdByCategory getModelById
getModelsCacheStatusByCategory getModelsCacheStatus
clearModelCacheByCategory clearModelsCache
downloadModelByCategory downloadModel
extractModelByCategory extractModel
isModelDownloadedByCategory isModelDownloaded
getLocalModelPathByCategory getModelPath
listDownloadedModelsByCategory listDownloadedModels
deleteModelByCategory deleteModel
getDownloadStorageBase getStorageBasePath
subscribeDownloadProgress onProgress Returns unsubscribe
subscribeModelsListUpdated onModelsListUpdated Returns unsubscribe
configureModelDownloadBackgroundDownloader configureBackgroundDownloader
getProtectedModelKeysForBulkDelete getProtectedKeys
purgeDownloadedModelArtifacts purgeAll

Added Functions

New Purpose
pauseDownload(category, modelId) Explicitly pause an active download
pauseExtraction(category, modelId) Explicitly pause an active extraction

Removed Exports

The following exports were removed from the public download manager surface:

  • extractTarBz2
  • extractTarZst
  • validateChecksum
  • validateExtractedFiles
  • resolveActualModelDir
  • parseChecksumFile
  • calculateFileChecksum
  • setExpectedFilesForCategory
  • getExpectedFilesForCategory

Type Changes

Before After
ModelMetaBase + TtsModelMeta ModelMeta (single unified type, TTS fields optional)
DownloadProgress Progress
bytesDownloaded bytesProcessed
ChecksumIssue ChecksumMismatchInfo
onChecksumIssue onChecksumMismatch

New Pause / Resume Style

Pause no longer requires using AbortController as a pause mechanism.

Before (pause via abort):

const controller = new AbortController();

const run = downloadModelByCategory(ModelCategory.Stt, 'sherpa-onnx-whisper-tiny', {
  signal: controller.signal,
});

controller.abort();
await run;

After (explicit pause API):

import { ModelCategory, PauseError, downloadModel, pauseDownload, resumeDownload } from 'react-native-sherpa-onnx/download';

const run = downloadModel(ModelCategory.Stt, 'sherpa-onnx-whisper-tiny');

await pauseDownload(ModelCategory.Stt, 'sherpa-onnx-whisper-tiny');

try {
  await run;
} catch (error) {
  if (!(error instanceof PauseError)) {
    throw error;
  }
}

await resumeDownload(ModelCategory.Stt, 'sherpa-onnx-whisper-tiny');

Before / After Examples

Ensure model

// Before
await ensureModelByCategory(ModelCategory.Tts, 'vits-piper-en_US-lessac-medium');

// After
await ensureModel(ModelCategory.Tts, 'vits-piper-en_US-lessac-medium');

List downloaded models

// Before
const installed = await listDownloadedModelsByCategory(ModelCategory.Alignment);

// After
const installed = await listDownloadedModels(ModelCategory.Alignment);

Progress subscription

// Before
const unsubscribe = subscribeDownloadProgress((category, modelId, progress) => {
  console.log(progress.bytesDownloaded);
});

// After
const unsubscribe = onProgress((category, modelId, progress) => {
  console.log(progress.bytesProcessed);
});