react-native-sherpa-onnx 0.3.6 → 0.3.7

package/src/download/registry.ts

@@ -0,0 +1,404 @@
+import {
+  exists,
+  readFile,
+  mkdir,
+  writeFile,
+} from '@dr.pogodin/react-native-fs';
+import { ModelCategory } from './types';
+import type {
+  ModelMetaBase,
+  ModelArchiveExt,
+  CachePayload,
+  CacheStatus,
+  TtsModelType,
+  Quantization,
+  SizeTier,
+  TtsModelMeta,
+} from './types';
+import {
+  CACHE_TTL_MINUTES,
+  MODEL_ARCHIVE_EXT,
+  MODEL_ONNX_EXT,
+} from './constants';
+import {
+  getCacheDir,
+  getCachePath,
+  getArchiveFilename,
+  getReleaseUrl,
+  CATEGORY_CONFIG,
+} from './paths';
+import { parseChecksumFile } from './validation';
+import { retryWithBackoff } from './retry';
+import { emitModelsListUpdated } from './downloadEvents';
+
+const memoryCacheByCategory: Partial<
+  Record<ModelCategory, CachePayload<ModelMetaBase>>
+> = {};
+
+const checksumCacheByCategory: Partial<
+  Record<ModelCategory, Map<string, string>>
+> = {};
+
+export async function fetchChecksumsFromRelease(
+  category: ModelCategory
+): Promise<Map<string, string>> {
+  if (category === ModelCategory.Qnn) {
+    return new Map<string, string>();
+  }
+  if (checksumCacheByCategory[category]) {
+    return checksumCacheByCategory[category]!;
+  }
+  try {
+    const checksums = await retryWithBackoff(
+      async () => {
+        const response = await fetch(
+          `https://github.com/k2-fsa/sherpa-onnx/releases/download/${CATEGORY_CONFIG[category].tag}/checksum.txt`
+        );
+        if (!response.ok) {
+          throw new Error(
+            `Failed to fetch checksum.txt for ${category}: ${response.status}`
+          );
+        }
+        const content = await response.text();
+        return parseChecksumFile(content);
+      },
+      { maxRetries: 3, initialDelayMs: 1000 }
+    );
+    checksumCacheByCategory[category] = checksums;
+    return checksums;
+  } catch (error) {
+    console.warn(
+      `SherpaOnnxChecksum: Error fetching checksums for ${category}:`,
+      error
+    );
+    return new Map();
+  }
+}
+
+function toTitleCase(value: string): string {
+  return value
+    .split(/[-_\s]+/g)
+    .filter(Boolean)
+    .map((token) => token[0]!.toUpperCase() + token.slice(1))
+    .join(' ');
+}
+
+function deriveDisplayName(id: string): string {
+  const cleaned = id.replace(/^sherpa-onnx-/, '');
+  return toTitleCase(cleaned);
+}
+
+function deriveType(id: string): TtsModelType {
+  const lower = id.toLowerCase();
+  if (lower.includes('vits')) return 'vits';
+  if (lower.includes('kokoro')) return 'kokoro';
+  if (lower.includes('matcha')) return 'matcha';
+  if (lower.includes('kitten')) return 'kitten';
+  if (lower.includes('pocket')) return 'pocket';
+  if (lower.includes('zipvoice')) return 'zipvoice';
+  return 'unknown';
+}
+
+function deriveQuantization(id: string): Quantization {
+  const lower = id.toLowerCase();
+  if (lower.includes('int8') && lower.includes('quant')) {
+    return 'int8-quantized';
+  }
+  if (lower.includes('int8')) return 'int8';
+  if (lower.includes('fp16')) return 'fp16';
+  return 'unknown';
+}
+
+function deriveSizeTier(id: string): SizeTier {
+  const lower = id.toLowerCase();
+  if (lower.includes('tiny')) return 'tiny';
+  if (lower.includes('small')) return 'small';
+  if (lower.includes('medium')) return 'medium';
+  if (lower.includes('large')) return 'large';
+  if (lower.includes('low')) return 'small';
+  return 'unknown';
+}
+
+function deriveLanguages(id: string): string[] {
+  const tokens = id.split(/[-_]+/g);
+  const languages = new Set<string>();
+  for (const token of tokens) {
+    if (/^[a-z]{2}$/.test(token)) {
+      languages.add(token);
+      continue;
+    }
+    if (/^[a-z]{2}[A-Z]{2}$/.test(token)) {
+      languages.add(token.slice(0, 2).toLowerCase());
+      continue;
+    }
+    if (/^[a-z]{2}-[A-Z]{2}$/.test(token)) {
+      languages.add(token.slice(0, 2).toLowerCase());
+    }
+  }
+  return Array.from(languages);
+}
+
+function getAssetExtension(name: string): ModelArchiveExt | null {
+  if (name.endsWith(MODEL_ARCHIVE_EXT)) return 'tar.bz2';
+  if (name.endsWith(MODEL_ONNX_EXT)) return 'onnx';
+  return null;
+}
+
+function stripAssetExtension(name: string, ext: ModelArchiveExt): string {
+  const suffix = `.${ext}`;
+  return name.endsWith(suffix) ? name.slice(0, -suffix.length) : name;
+}
+
+function isAssetSupportedForCategory(
+  category: ModelCategory,
+  name: string,
+  ext: ModelArchiveExt
+): boolean {
+  const lower = name.toLowerCase();
+  switch (category) {
+    case ModelCategory.Tts:
+      return ext === 'tar.bz2';
+    case ModelCategory.Stt:
+      return ext === 'tar.bz2' && !lower.includes('vad');
+    case ModelCategory.Vad:
+      return ext === 'onnx' && lower.includes('vad');
+    case ModelCategory.Diarization:
+      return ext === 'tar.bz2';
+    case ModelCategory.Enhancement:
+      return ext === 'onnx';
+    case ModelCategory.Separation:
+      return ext === 'tar.bz2' || ext === 'onnx';
+    case ModelCategory.Qnn:
+      return (
+        ext === 'tar.bz2' &&
+        lower.includes('sherpa-onnx-qnn') &&
+        lower.includes('binary') &&
+        lower.includes('seconds')
+      );
+    default:
+      return false;
+  }
+}
+
+function parseDigestSha256(value?: string | null): string | undefined {
+  if (!value) return undefined;
+  const match = value.match(/^sha256:([a-f0-9]{64})$/i);
+  return match?.[1]?.toLowerCase();
+}
+
+function toTtsModelMeta(
+  asset: {
+    name: string;
+    size: number;
+    browser_download_url: string;
+    digest?: string | null;
+  },
+  archiveExt: ModelArchiveExt
+): TtsModelMeta | null {
+  if (archiveExt !== 'tar.bz2') return null;
+  const id = stripAssetExtension(asset.name, archiveExt);
+  const type = deriveType(id);
+  if (type === 'unknown') {
+    console.warn('SherpaOnnxModelList: Unsupported model', id);
+  }
+  return {
+    id,
+    displayName: deriveDisplayName(id),
+    type,
+    languages: deriveLanguages(id),
+    quantization: deriveQuantization(id),
+    sizeTier: deriveSizeTier(id),
+    downloadUrl: asset.browser_download_url,
+    archiveExt,
+    bytes: asset.size,
+    sha256: parseDigestSha256(asset.digest),
+    category: ModelCategory.Tts,
+  };
+}
+
+function toGenericModelMeta(
+  category: ModelCategory,
+  asset: {
+    name: string;
+    size: number;
+    browser_download_url: string;
+    digest?: string | null;
+  },
+  archiveExt: ModelArchiveExt
+): ModelMetaBase | null {
+  const id = stripAssetExtension(asset.name, archiveExt);
+  return {
+    id,
+    displayName: deriveDisplayName(id),
+    downloadUrl: asset.browser_download_url,
+    archiveExt,
+    bytes: asset.size,
+    sha256: parseDigestSha256(asset.digest),
+    category,
+  };
+}
+
+function toModelMeta(
+  category: ModelCategory,
+  asset: {
+    name: string;
+    size: number;
+    browser_download_url: string;
+    digest?: string | null;
+  }
+): ModelMetaBase | null {
+  const archiveExt = getAssetExtension(asset.name);
+  if (!archiveExt) return null;
+  if (!isAssetSupportedForCategory(category, asset.name, archiveExt)) {
+    return null;
+  }
+  if (category === ModelCategory.Tts) {
+    return toTtsModelMeta(asset, archiveExt);
+  }
+  return toGenericModelMeta(category, asset, archiveExt);
+}
+
+async function loadCacheFromDisk<T extends ModelMetaBase>(
+  category: ModelCategory
+): Promise<CachePayload<T> | null> {
+  const memoryCache = memoryCacheByCategory[category] as
+    | CachePayload<T>
+    | undefined;
+  if (memoryCache) return memoryCache;
+  const cachePath = getCachePath(category);
+  const existsResult = await exists(cachePath);
+  if (!existsResult) return null;
+  const raw = await readFile(cachePath, 'utf8');
+  const parsed = JSON.parse(raw) as CachePayload<T>;
+  memoryCacheByCategory[category] = parsed as CachePayload<ModelMetaBase>;
+  return parsed;
+}
+
+async function saveCache<T extends ModelMetaBase>(
+  category: ModelCategory,
+  payload: CachePayload<T>
+): Promise<void> {
+  await mkdir(getCacheDir());
+  await writeFile(getCachePath(category), JSON.stringify(payload), 'utf8');
+  memoryCacheByCategory[category] = payload as CachePayload<ModelMetaBase>;
+}
+
+function isCacheFresh<T extends ModelMetaBase>(
+  payload: CachePayload<T>,
+  ttlMinutes: number
+): boolean {
+  const updated = new Date(payload.lastUpdated).getTime();
+  if (!updated) return false;
+  const ageMs = Date.now() - updated;
+  return ageMs < ttlMinutes * 60 * 1000;
+}
+
+export async function listModelsByCategory<T extends ModelMetaBase>(
+  category: ModelCategory
+): Promise<T[]> {
+  const cache = await loadCacheFromDisk<T>(category);
+  return cache?.models ?? [];
+}
+
+export async function refreshModelsByCategory<T extends ModelMetaBase>(
+  category: ModelCategory,
+  options?: {
+    forceRefresh?: boolean;
+    cacheTtlMinutes?: number;
+    maxRetries?: number;
+    signal?: AbortSignal;
+  }
+): Promise<T[]> {
+  const ttl = options?.cacheTtlMinutes ?? CACHE_TTL_MINUTES;
+  const cached = await loadCacheFromDisk<T>(category);
+
+  if (!options?.forceRefresh && cached && isCacheFresh(cached, ttl)) {
+    return cached.models;
+  }
+
+  try {
+    const body = await retryWithBackoff(
+      async () => {
+        const response = await fetch(getReleaseUrl(category));
+        if (!response.ok) {
+          throw new Error(`Failed to fetch models: ${response.status}`);
+        }
+        return response.json();
+      },
+      {
+        maxRetries: options?.maxRetries ?? 3,
+        initialDelayMs: 1000,
+        signal: options?.signal,
+      }
+    );
+
+    const assets = Array.isArray(body?.assets) ? body.assets : [];
+    const models: T[] = assets
+      .map(
+        (asset: {
+          name: string;
+          size: number;
+          browser_download_url: string;
+          digest?: string | null;
+        }) =>
+          toModelMeta(category, {
+            name: asset.name,
+            size: asset.size,
+            browser_download_url: asset.browser_download_url,
+            digest: asset.digest,
+          })
+      )
+      .filter((model: ModelMetaBase | null): model is T => Boolean(model));
+
+    const checksums = await fetchChecksumsFromRelease(category);
+    for (const model of models) {
+      const archiveFilename = getArchiveFilename(model.id, model.archiveExt);
+      const sha256 = checksums.get(archiveFilename);
+      if (sha256) {
+        model.sha256 = sha256;
+      } else if (model.sha256) {
+        model.sha256 = model.sha256.toLowerCase();
+      }
+    }
+
+    const payload: CachePayload<T> = {
+      lastUpdated: new Date().toISOString(),
+      models,
+    };
+    await saveCache(category, payload);
+    emitModelsListUpdated(category, models as ModelMetaBase[]);
+    return models;
+  } catch (error) {
+    if (cached) {
+      console.warn(
+        `Failed to refresh models for ${category}, using cached data:`,
+        error
+      );
+      return cached.models;
+    }
+    throw error;
+  }
+}
+
+export async function getModelsCacheStatusByCategory(
+  category: ModelCategory
+): Promise<CacheStatus> {
+  const cached = await loadCacheFromDisk(category);
+  if (!cached) {
+    return { lastUpdated: null, source: 'cache' };
+  }
+  return { lastUpdated: cached.lastUpdated, source: 'cache' };
+}
+
+export async function getModelByIdByCategory<T extends ModelMetaBase>(
+  category: ModelCategory,
+  id: string
+): Promise<T | null> {
+  const models = await listModelsByCategory<T>(category);
+  return models.find((model) => model.id === id) ?? null;
+}
+
+export function clearMemoryCacheForCategory(category: ModelCategory): void {
+  delete memoryCacheByCategory[category];
+  delete checksumCacheByCategory[category];
+}

package/src/download/retry.ts

@@ -0,0 +1,76 @@
+/**
+ * Retry helper with exponential backoff
+ * @param fn - The async function to retry
+ * @param options - Retry configuration
+ * @returns The result of the function
+ * @throws The last error if all retries fail or AbortError if aborted
+ */
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffFactor?: number;
+    signal?: AbortSignal;
+  } = {}
+): Promise<T> {
+  const maxRetries = options.maxRetries ?? 3;
+  const initialDelayMs = options.initialDelayMs ?? 1000;
+  const maxDelayMs = options.maxDelayMs ?? 10000;
+  const backoffFactor = options.backoffFactor ?? 2;
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (options.signal?.aborted) {
+      const abortError = new Error('Operation aborted');
+      abortError.name = 'AbortError';
+      throw abortError;
+    }
+
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Don't retry on abort
+      if (lastError.name === 'AbortError' || options.signal?.aborted) {
+        throw lastError;
+      }
+
+      // If this was the last attempt, throw the error
+      if (attempt === maxRetries) {
+        throw lastError;
+      }
+
+      // Calculate delay with exponential backoff
+      const delayMs = Math.min(
+        initialDelayMs * Math.pow(backoffFactor, attempt),
+        maxDelayMs
+      );
+
+      console.warn(
+        `Retry attempt ${attempt + 1}/${maxRetries} after ${delayMs}ms due to:`,
+        lastError.message
+      );
+
+      // Wait before retrying (abort-aware: cancel the delay if signal fires)
+      await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(resolve, delayMs);
+        if (options.signal) {
+          const onAbort = () => {
+            clearTimeout(timer);
+            options.signal!.removeEventListener('abort', onAbort);
+            const abortErr = new Error('Operation aborted');
+            abortErr.name = 'AbortError';
+            reject(abortErr);
+          };
+          options.signal.addEventListener('abort', onAbort);
+        }
+      });
+    }
+  }
+
+  throw lastError ?? new Error('Retry failed with no error');
+}

package/src/download/types.ts

@@ -0,0 +1,120 @@
+import type { TTSModelType } from '../tts/types';
+
+export enum ModelCategory {
+  Tts = 'tts',
+  Stt = 'stt',
+  Vad = 'vad',
+  Diarization = 'diarization',
+  Enhancement = 'enhancement',
+  Separation = 'separation',
+  Qnn = 'qnn',
+}
+
+/** TTS model type for meta; 'unknown' when id could not be classified. */
+export type TtsModelType = TTSModelType | 'unknown';
+
+export type Quantization = 'fp16' | 'int8' | 'int8-quantized' | 'unknown';
+
+export type SizeTier = 'tiny' | 'small' | 'medium' | 'large' | 'unknown';
+
+export type ModelArchiveExt = 'tar.bz2' | 'onnx';
+
+export type ModelMetaBase = {
+  id: string;
+  displayName: string;
+  downloadUrl: string;
+  archiveExt: ModelArchiveExt;
+  bytes: number;
+  sha256?: string;
+  category: ModelCategory;
+};
+
+export type TtsModelMeta = ModelMetaBase & {
+  type: TtsModelType;
+  languages: string[];
+  quantization: Quantization;
+  sizeTier: SizeTier;
+  category: ModelCategory.Tts;
+};
+
+export type DownloadProgress = {
+  bytesDownloaded: number;
+  totalBytes: number;
+  percent: number;
+  phase?: 'downloading' | 'extracting';
+  speed?: number;
+  eta?: number;
+};
+
+export type DownloadResult = {
+  modelId: string;
+  localPath: string;
+};
+
+export type DownloadState = {
+  modelId: string;
+  category: ModelCategory;
+  phase: 'downloading' | 'extracting';
+  startedAt: string;
+  archivePath: string;
+  model: ModelMetaBase;
+  bytesDownloaded?: number;
+  totalBytes?: number;
+};
+
+/** State for an in-progress or interrupted model extraction (archive --> model dir). */
+export type ExtractionState = {
+  modelId: string;
+  category: ModelCategory;
+  phase: 'extracting';
+  startedAt: string;
+  archivePath: string;
+  modelDir: string;
+  model: ModelMetaBase;
+};
+
+export type DownloadProgressListener = (
+  category: ModelCategory,
+  modelId: string,
+  progress: DownloadProgress
+) => void;
+
+export type ModelsListUpdatedListener = (
+  category: ModelCategory,
+  models: ModelMetaBase[]
+) => void;
+
+export type ModelManifest<T extends ModelMetaBase = ModelMetaBase> = {
+  downloadedAt: string;
+  lastUsed?: string;
+  model: T;
+  sizeOnDisk?: number;
+};
+
+export type ModelWithMetadata<T extends ModelMetaBase = ModelMetaBase> = {
+  model: T;
+  downloadedAt: string;
+  lastUsed: string | null;
+  sizeOnDisk?: number;
+  status: 'ready' | 'downloading' | 'extracting' | 'failed';
+  progress?: number;
+};
+
+export type ChecksumIssue = {
+  category: ModelCategory;
+  id: string;
+  archivePath: string;
+  expected?: string;
+  message: string;
+  reason: 'CHECKSUM_FAILED' | 'CHECKSUM_MISMATCH';
+};
+
+export type CachePayload<T extends ModelMetaBase> = {
+  lastUpdated: string;
+  models: T[];
+};
+
+export type CacheStatus = {
+  lastUpdated: string | null;
+  source: 'cache' | 'remote';
+};