@revizly/node-av 5.2.2-beta.1

package/dist/api/utilities/timestamp.js

@@ -0,0 +1,206 @@
+import { bindings } from '../../lib/binding.js';
+/**
+ * Timestamp and time base utilities.
+ *
+ * Provides static methods for converting, rescaling, and comparing timestamps.
+ * These utilities are essential for working with different time bases in
+ * multimedia streams.
+ *
+ * @example
+ * ```typescript
+ * import { TimestampUtils } from 'node-av';
+ * import { AV_ROUND_NEAR_INF } from 'node-av/constants';
+ *
+ * // Convert timestamp to string representations
+ * const pts = 450000n;
+ * console.log(TimestampUtils.toString(pts));                    // "450000"
+ *
+ * const timebase = { num: 1, den: 90000 };
+ * console.log(TimestampUtils.toTimeString(pts, timebase));      // "5.000000"
+ *
+ * // Rescale between time bases
+ * const srcTb = { num: 1, den: 90000 };
+ * const dstTb = { num: 1, den: 1000 };
+ * const rescaled = TimestampUtils.rescale(pts, srcTb, dstTb);
+ * console.log(rescaled);                                         // 5000n
+ * ```
+ */
+export class TimestampUtils {
+    // Private constructor to prevent instantiation
+    constructor() { }
+    /**
+     * Convert timestamp to string.
+     *
+     * Converts a timestamp value to its string representation.
+     * Handles special values like AV_NOPTS_VALUE.
+     * Direct mapping to av_ts2str()
+     *
+     * @param ts - Timestamp value (bigint or number), or null
+     *
+     * @returns String representation
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     * import { AV_NOPTS_VALUE } from 'node-av/constants';
+     *
+     * console.log(TimestampUtils.toString(12345n));        // "12345"
+     * console.log(TimestampUtils.toString(AV_NOPTS_VALUE)); // "NOPTS"
+     * console.log(TimestampUtils.toString(null));          // "NOPTS"
+     * ```
+     */
+    static toString(ts) {
+        return bindings.avTs2Str(ts);
+    }
+    /**
+     * Convert timestamp to time string.
+     *
+     * Converts a timestamp to a time string in seconds using the provided time base.
+     * Direct mapping to av_ts2timestr()
+     *
+     * @param ts - Timestamp value
+     *
+     * @param timeBase - Time base for conversion
+     *
+     * @returns Time string in seconds with decimal places
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * const pts = 450000n;
+     * const timebase = { num: 1, den: 90000 }; // 90kHz
+     *
+     * console.log(TimestampUtils.toTimeString(pts, timebase));     // "5.000000"
+     * console.log(TimestampUtils.toTimeString(90000n, timebase));  // "1.000000"
+     * ```
+     */
+    static toTimeString(ts, timeBase) {
+        return bindings.avTs2TimeStr(ts, timeBase);
+    }
+    /**
+     * Compare timestamps from different time bases.
+     *
+     * Compares two timestamps that may have different time bases.
+     * Direct mapping to av_compare_ts()
+     *
+     * @param tsA - First timestamp
+     *
+     * @param tbA - Time base of first timestamp
+     *
+     * @param tsB - Second timestamp
+     *
+     * @param tbB - Time base of second timestamp
+     *
+     * @returns -1 if tsA < tsB, 0 if equal, 1 if tsA > tsB
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * // Compare timestamps from different time bases
+     * const pts1 = 90000n;
+     * const tb1 = { num: 1, den: 90000 };  // 1 second in 90kHz
+     *
+     * const pts2 = 1000n;
+     * const tb2 = { num: 1, den: 1000 };   // 1 second in 1kHz
+     *
+     * const result = TimestampUtils.compare(pts1, tb1, pts2, tb2);
+     * console.log(result); // 0 (equal - both represent 1 second)
+     * ```
+     */
+    static compare(tsA, tbA, tsB, tbB) {
+        return bindings.avCompareTs(tsA, tbA, tsB, tbB);
+    }
+    /**
+     * Rescale timestamp from one time base to another.
+     *
+     * Converts a timestamp from source time base to destination time base.
+     * Uses AV_ROUND_NEAR_INF rounding.
+     * Direct mapping to av_rescale_q()
+     *
+     * @param a - Timestamp to rescale
+     *
+     * @param bq - Source time base
+     *
+     * @param cq - Destination time base
+     *
+     * @returns Rescaled timestamp
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * // Convert from 90kHz to milliseconds
+     * const pts = 450000n;
+     * const srcTb = { num: 1, den: 90000 };
+     * const dstTb = { num: 1, den: 1000 };
+     *
+     * const rescaled = TimestampUtils.rescale(pts, srcTb, dstTb);
+     * console.log(rescaled); // 5000n (5000 milliseconds = 5 seconds)
+     * ```
+     */
+    static rescale(a, bq, cq) {
+        return bindings.avRescaleQ(a, bq, cq);
+    }
+    /**
+     * Rescale with specified rounding.
+     *
+     * Rescales a value with explicit rounding mode.
+     * More general than rescale() as it doesn't use time bases.
+     * Direct mapping to av_rescale_rnd()
+     *
+     * @param a - Value to rescale
+     *
+     * @param b - Multiplier
+     *
+     * @param c - Divisor
+     *
+     * @param rnd - Rounding mode
+     *
+     * @returns Rescaled value: a * b / c
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     * import { AV_ROUND_UP, AV_ROUND_DOWN } from 'node-av/constants';
+     *
+     * // Scale with different rounding modes
+     * const value = 100n;
+     * const mul = 3n;
+     * const div = 7n;
+     *
+     * const roundUp = TimestampUtils.rescaleRounded(value, mul, div, AV_ROUND_UP);
+     * const roundDown = TimestampUtils.rescaleRounded(value, mul, div, AV_ROUND_DOWN);
+     *
+     * console.log(roundUp);   // 43n (rounds up)
+     * console.log(roundDown); // 42n (rounds down)
+     * ```
+     */
+    static rescaleRounded(a, b, c, rnd) {
+        return bindings.avRescaleRnd(a, b, c, rnd);
+    }
+    /**
+     * Sleep for specified microseconds.
+     *
+     * Sleeps for the specified number of microseconds.
+     * Direct mapping to av_usleep()
+     *
+     * @param usec - Microseconds to sleep
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * // Sleep for 100 milliseconds
+     * TimestampUtils.sleep(100000);
+     *
+     * // Sleep for 1 second
+     * TimestampUtils.sleep(1000000);
+     * ```
+     */
+    static sleep(usec) {
+        bindings.avUsleep(usec);
+    }
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/api/utilities/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.js","sourceRoot":"","sources":["../../../src/api/utilities/timestamp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAKhD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,cAAc;IACzB,+CAA+C;IAC/C,gBAAuB,CAAC;IAExB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,QAAQ,CAAC,EAA0B;QACxC,OAAO,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,YAAY,CAAC,EAA0B,EAAE,QAAmB;QACjE,OAAO,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,OAAO,CAAC,GAA2B,EAAE,GAAc,EAAE,GAA2B,EAAE,GAAc;QACrG,OAAO,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,OAAO,CAAC,CAAyB,EAAE,EAAa,EAAE,EAAa;QACpE,OAAO,QAAQ,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,MAAM,CAAC,cAAc,CAAC,CAAkB,EAAE,CAAkB,EAAE,CAAkB,EAAE,GAAe;QAC/F,OAAO,QAAQ,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,KAAK,CAAC,IAAY;QACvB,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/api/utilities/whisper-model.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Model type for Whisper downloads
+ */
+export type WhisperModelType = 'ggml' | 'vad';
+/**
+ * Options for downloading a Whisper model
+ */
+export interface DownloadOptions {
+    model: WhisperModelName | WhisperVADModelName;
+    outputPath?: string;
+    type?: WhisperModelType;
+}
+/**
+ * Standard GGML Whisper models
+ */
+export declare const WHISPER_MODELS: readonly ["tiny", "tiny.en", "tiny-q5_1", "tiny.en-q5_1", "tiny-q8_0", "base", "base.en", "base-q5_1", "base.en-q5_1", "base-q8_0", "small", "small.en", "small.en-tdrz", "small-q5_1", "small.en-q5_1", "small-q8_0", "medium", "medium.en", "medium-q5_0", "medium.en-q5_0", "medium-q8_0", "large-v1", "large-v2", "large-v2-q5_0", "large-v2-q8_0", "large-v3", "large-v3-q5_0", "large-v3-turbo", "large-v3-turbo-q5_0", "large-v3-turbo-q8_0"];
+/**
+ * Whisper VAD (Voice Activity Detection) models
+ */
+export declare const WHISPER_VAD_MODELS: readonly ["silero-v5.1.2", "silero-v6.2.0"];
+export type WhisperModelName = (typeof WHISPER_MODELS)[number];
+export type WhisperVADModelName = (typeof WHISPER_VAD_MODELS)[number];
+/**
+ * Whisper.cpp model downloader utilities.
+ *
+ * Provides static methods for downloading GGML and VAD models from HuggingFace,
+ * validating model names, and checking model availability. Supports automatic
+ * model type detection and prevents concurrent downloads of the same model.
+ *
+ * @example
+ * ```typescript
+ * import { WhisperDownloader } from 'node-av';
+ *
+ * // Download a GGML model
+ * const modelPath = await WhisperDownloader.downloadModel({
+ *   model: 'base',
+ *   outputPath: './models'
+ * });
+ *
+ * // Download a VAD model
+ * const vadPath = await WhisperDownloader.downloadVADModel('silero-v5.1.2', './models');
+ *
+ * // Check available models
+ * const categories = WhisperDownloader.getModelsByCategory();
+ * console.log(categories); // Map { 'tiny' => ['tiny', 'tiny.en', ...], ... }
+ * ```
+ */
+export declare class WhisperDownloader {
+    static readonly DEFAULT_MODEL_PATH: string;
+    private static readonly DEFAULT_SRC;
+    private static readonly DEFAULT_PFX;
+    private static readonly TDRZ_SRC;
+    private static readonly TDRZ_PFX;
+    private static readonly VAD_SRC;
+    private static readonly VAD_PFX;
+    private static readonly activeDownloads;
+    private constructor();
+    /**
+     * Check if a model name is a valid GGML model.
+     *
+     * Validates whether the provided string matches one of the available
+     * GGML Whisper model names.
+     *
+     * @param model - Model name to validate
+     *
+     * @returns True if the model is a valid GGML model name
+     *
+     * @example
+     * ```typescript
+     * import { WhisperDownloader } from 'node-av';
+     *
+     * console.log(WhisperDownloader.isValidModel('base'));      // true
+     * console.log(WhisperDownloader.isValidModel('large-v3'));  // true
+     * console.log(WhisperDownloader.isValidModel('invalid'));   // false
+     * ```
+     */
+    static isValidModel(model: string): model is WhisperModelName;
+    /**
+     * Check if a model name is a valid VAD model.
+     *
+     * Validates whether the provided string matches one of the available
+     * Silero VAD model names.
+     *
+     * @param model - Model name to validate
+     *
+     * @returns True if the model is a valid VAD model name
+     *
+     * @example
+     * ```typescript
+     * import { WhisperDownloader } from 'node-av';
+     *
+     * console.log(WhisperDownloader.isValidVADModel('silero-v5.1.2')); // true
+     * console.log(WhisperDownloader.isValidVADModel('invalid'));       // false
+     * ```
+     */
+    static isValidVADModel(model: string): model is WhisperVADModelName;
+    /**
+     * Get all available GGML models grouped by category.
+     *
+     * Returns a map of model categories (tiny, base, small, medium, large)
+     * with their corresponding model variants.
+     *
+     * @returns Map of category names to model name arrays
+     *
+     * @example
+     * ```typescript
+     * import { WhisperDownloader } from 'node-av';
+     *
+     * const categories = WhisperDownloader.getModelsByCategory();
+     * console.log(categories.get('base'));
+     * // ['base', 'base.en', 'base-q5_1', 'base.en-q5_1', 'base-q8_0']
+     *
+     * // List all categories
+     * for (const [category, models] of categories) {
+     *   console.log(`${category}: ${models.length} variants`);
+     * }
+     * ```
+     */
+    static getModelsByCategory(): Map<string, string[]>;
+    /**
+     * Get the download URL for a model.
+     *
+     * Constructs the HuggingFace download URL for a given model name.
+     * Automatically detects whether it's a GGML or VAD model if type is not specified.
+     * Handles special models like tinydiarize variants.
+     *
+     * @param model - Model name
+     *
+     * @param type - Model type (auto-detected if not provided)
+     *
+     * @returns Full download URL for the model
+     *
+     * @example
+     * ```typescript
+     * import { WhisperDownloader } from 'node-av';
+     *
+     * // GGML model URL
+     * const url = WhisperDownloader.getModelUrl('base');
+     * console.log(url);
+     * // 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin'
+     *
+     * // VAD model URL
+     * const vadUrl = WhisperDownloader.getModelUrl('silero-v5.1.2');
+     * console.log(vadUrl);
+     * // 'https://huggingface.co/ggml-org/whisper-vad/resolve/main/ggml-silero-v5.1.2.bin'
+     * ```
+     */
+    static getModelUrl(model: string, type?: WhisperModelType): string;
+    /**
+     * Check if a model file already exists.
+     *
+     * Checks whether a model file has already been downloaded to the specified path.
+     * Useful for skipping redundant downloads.
+     *
+     * @param model - Model name
+     *
+     * @param outputPath - Directory path to check
+     *
+     * @returns True if the model file exists
+     *
+     * @example
+     * ```typescript
+     * import { WhisperDownloader } from 'node-av';
+     *
+     * if (WhisperDownloader.modelExists('base', './models')) {
+     *   console.log('Model already downloaded');
+     * } else {
+     *   await WhisperDownloader.downloadModel({
+     *     model: 'base',
+     *     outputPath: './models'
+     *   });
+     * }
+     * ```
+     */
+    static modelExists(model: string, outputPath: string): boolean;
+    /**
+     * Find whisper-cli executable in system PATH.
+     *
+     * Searches for whisper-cli binary in system PATH and local build directory.
+     * Returns the path to the executable if found.
+     *
+     * @returns Path to whisper-cli executable, or null if not found
+     *
+     * @example
+     * ```typescript
+     * import { WhisperDownloader } from 'node-av';
+     *
+     * const cliPath = await WhisperDownloader.findWhisperCli();
+     * if (cliPath) {
+     *   console.log(`Found whisper-cli at: ${cliPath}`);
+     * } else {
+     *   console.log('whisper-cli not found');
+     * }
+     * ```
+     */
+    static findWhisperCli(): Promise<string | null>;
+    /**
+     * Download a Whisper model file.
+     *
+     * Downloads a GGML or VAD model from HuggingFace to the specified directory.
+     * Automatically detects model type based on model name if not specified.
+     * Prevents race conditions when the same model is downloaded concurrently.
+     * Returns immediately if the model file already exists.
+     *
+     * @param options - Download configuration options
+     *
+     * @returns Path to the downloaded model file
+     *
+     * @example
+     * ```typescript
+     * import { WhisperDownloader } from 'node-av';
+     *
+     * // Download GGML model (auto-detected)
+     * const path = await WhisperDownloader.downloadModel({
+     *   model: 'base',
+     *   outputPath: './models'
+     * });
+     * console.log(`Downloaded to: ${path}`);
+     *
+     * // Download VAD model (auto-detected)
+     * const vadPath = await WhisperDownloader.downloadModel({
+     *   model: 'silero-v5.1.2',
+     *   outputPath: './models'
+     * });
+     *
+     * // Explicit type specification
+     * const explicitPath = await WhisperDownloader.downloadModel({
+     *   model: 'base',
+     *   outputPath: './models',
+     *   type: 'ggml'
+     * });
+     * ```
+     */
+    static downloadModel(options: DownloadOptions): Promise<string>;
+    /**
+     * Download a VAD model (convenience method).
+     *
+     * Convenience wrapper for downloading VAD models without specifying type.
+     * Equivalent to calling downloadModel() with type: 'vad'.
+     *
+     * @param model - VAD model name
+     *
+     * @param outputPath - Directory path for download (default: current directory)
+     *
+     * @returns Path to the downloaded VAD model file
+     *
+     * @example
+     * ```typescript
+     * import { WhisperDownloader } from 'node-av';
+     *
+     * const vadPath = await WhisperDownloader.downloadVADModel(
+     *   'silero-v5.1.2',
+     *   './models'
+     * );
+     * console.log(`VAD model downloaded to: ${vadPath}`);
+     * ```
+     */
+    static downloadVADModel(model: WhisperVADModelName, outputPath?: string): Promise<string>;
+    /**
+     * Download multiple Whisper models.
+     *
+     * Downloads multiple models sequentially to avoid overwhelming the network.
+     * Each model is validated and downloaded using the same logic as downloadModel().
+     *
+     * @param models - Array of model names to download
+     *
+     * @param outputPath - Directory path for downloads (default: current directory)
+     *
+     * @param type - Model type for all models (auto-detected if not provided)
+     *
+     * @returns Array of paths to downloaded model files
+     *
+     * @example
+     * ```typescript
+     * import { WhisperDownloader } from 'node-av';
+     *
+     * // Download multiple GGML models
+     * const paths = await WhisperDownloader.downloadModels(
+     *   ['tiny', 'base', 'small'],
+     *   './models'
+     * );
+     * console.log(`Downloaded ${paths.length} models`);
+     *
+     * // Download multiple VAD models
+     * const vadPaths = await WhisperDownloader.downloadModels(
+     *   ['silero-v5.1.2', 'silero-v6.2.0'],
+     *   './models',
+     *   'vad'
+     * );
+     * ```
+     */
+    static downloadModels(models: (WhisperModelName | WhisperVADModelName)[], outputPath?: string, type?: WhisperModelType): Promise<string[]>;
+    /**
+     * Follow HTTP redirects recursively to download a file.
+     *
+     * Handles HTTP redirects (301, 302, 307, 308) up to a maximum of 5 redirects.
+     * Downloads the file to the specified output path.
+     *
+     * @param url - URL to download
+     *
+     * @param outputPath - Local file path to save the download
+     *
+     * @param redirectCount - Current redirect count (used internally)
+     *
+     * @returns Promise that resolves when the download is complete
+     *
+     * @internal
+     */
+    private static followRedirect;
+}