@storyteller-platform/ghost-story 0.0.1

package/dist/api/APIOptions.d.ts

@@ -0,0 +1,18 @@
+import { RecognitionOptions } from './Recognition.js';
+import 'node:fs';
+import 'node:stream';
+import '../audio/AudioFormat.js';
+import '../audio/AudioSource.js';
+import '../config.js';
+import '../recognition/OpenAICloudSTT.js';
+import '../utilities/Timeline.js';
+import '../utilities/Timing.js';
+import '../recognition/WhisperCppSTT.js';
+import '../cli/config.js';
+import '../recognition/WhisperServerSTT.js';
+
+interface APIOptions {
+    RecognitionOptions: RecognitionOptions;
+}
+
+export type { APIOptions };

package/dist/api/Recognition.cjs

@@ -0,0 +1,263 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Recognition_exports = {};
+__export(Recognition_exports, {
+  recognitionEngines: () => recognitionEngines,
+  recognize: () => recognize
+});
+module.exports = __toCommonJS(Recognition_exports);
+var import_audio = require("../audio/index.cjs");
+var import_config = require("../config.cjs");
+var import_Locale = require("../utilities/Locale.cjs");
+var import_ObjectUtilities = require("../utilities/ObjectUtilities.cjs");
+var import_Timeline = require("../utilities/Timeline.cjs");
+var import_Timing = require("../utilities/Timing.cjs");
+async function recognize(input, options) {
+  const opts = (0, import_ObjectUtilities.extendDeep)(
+    defaultRecognitionOptions,
+    options
+  );
+  const timing = (0, import_Timing.createTiming)();
+  timing.setMetadata("engine", opts.engine);
+  timing.setMetadata(
+    "conversionMode",
+    opts.conversionMode ?? (0, import_config.getConversionMode)()
+  );
+  if (!opts.language) {
+    throw new Error("Language must be specified");
+  }
+  const languageCode = opts.language;
+  const shortLanguageCode = (0, import_Locale.getShortLanguageCode)(languageCode);
+  timing.setMetadata("language", languageCode);
+  const source = resolveAudioSource(input, opts);
+  timing.setMetadata("inputFormat", source.format);
+  let transcript = "";
+  let timeline;
+  switch (opts.engine) {
+    case "whisper.cpp": {
+      const WhisperCppSTT = await import("../recognition/WhisperCppSTT.cjs");
+      timing.setMetadata("model", opts.options.model);
+      timing.setMetadata("processors", opts.options.processors ?? 1);
+      timing.setMetadata("threads", opts.options.threads ?? 4);
+      const result = await WhisperCppSTT.recognize(source, {
+        ...opts.options,
+        language: shortLanguageCode,
+        timing
+      });
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "openai-cloud": {
+      const OpenAICloudSTT = await import("../recognition/OpenAICloudSTT.cjs");
+      timing.setMetadata("model", opts.options.model ?? "whisper-1");
+      const result = await OpenAICloudSTT.recognize(source, shortLanguageCode, {
+        ...opts.options,
+        timing
+      });
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "whisper-server": {
+      const WhisperServerSTT = await import("../recognition/WhisperServerSTT.cjs");
+      const result = await WhisperServerSTT.recognize(
+        source,
+        shortLanguageCode,
+        { ...opts.options, timing }
+      );
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "google-cloud": {
+      const GoogleCloudSTT = await import("../recognition/GoogleCloudSTT.cjs");
+      if (!opts.options.apiKey) {
+        throw new Error("Google Cloud API key is required");
+      }
+      const result = await GoogleCloudSTT.recognize(
+        source,
+        { ...opts.options, timing },
+        shortLanguageCode
+      );
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "microsoft-azure": {
+      const AzureCognitiveServicesSTT = await import("../recognition/AzureCognitiveServicesSTT.cjs");
+      if (!opts.options.subscriptionKey) {
+        throw new Error("Azure subscription key is required");
+      }
+      if (!opts.options.serviceRegion) {
+        throw new Error("Azure service region is required");
+      }
+      const result = await AzureCognitiveServicesSTT.recognize(
+        source,
+        {
+          subscriptionKey: opts.options.subscriptionKey,
+          serviceRegion: opts.options.serviceRegion,
+          inputFormat: opts.inputFormat,
+          timing
+        },
+        shortLanguageCode
+      );
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "amazon-transcribe": {
+      const AmazonTranscribeSTT = await import("../recognition/AmazonTranscribeSTT.cjs");
+      const result = await AmazonTranscribeSTT.recognize(source, languageCode, {
+        region: opts.options.region,
+        accessKeyId: opts.options.accessKeyId,
+        secretAccessKey: opts.options.secretAccessKey,
+        inputFormat: opts.inputFormat,
+        timing
+      });
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "deepgram": {
+      const DeepgramSTT = await import("../recognition/DeepgramSTT.cjs");
+      if (!opts.options.apiKey) {
+        throw new Error("Deepgram API key is required");
+      }
+      timing.setMetadata("model", opts.options.model);
+      const result = await DeepgramSTT.recognize(
+        source,
+        shortLanguageCode,
+        {
+          apiKey: opts.options.apiKey,
+          model: opts.options.model,
+          punctuate: opts.options.punctuate,
+          inputFormat: opts.inputFormat,
+          timing,
+          conversionMode: opts.conversionMode
+        },
+        opts.signal
+      );
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    default: {
+      const _engine = opts;
+      throw new Error(
+        `Unknown engine: ${_engine.engine}`
+      );
+    }
+  }
+  if (!timeline) {
+    throw new Error(`No timeline returned from engine ${opts.engine}`);
+  }
+  (0, import_Timeline.addWordTextOffsetsToTimelineInPlace)(timeline, transcript);
+  return {
+    transcript,
+    timeline,
+    language: languageCode,
+    timing: timing.summary()
+  };
+}
+function resolveAudioSource(input, opts) {
+  if ((0, import_audio.isAudioSource)(input)) {
+    return input;
+  }
+  return (0, import_audio.normalizeToAudioSource)(input, opts.inputFormat);
+}
+const defaultRecognitionOptions = {
+  engine: "whisper.cpp",
+  options: {
+    model: "tiny.en"
+  }
+};
+const recognitionEngines = [
+  {
+    id: "whisper.cpp",
+    name: "OpenAI Whisper (C++ port)",
+    description: "Local whisper.cpp binary. Accepts wav, flac, ogg, mp3.",
+    type: "local",
+    acceptsFormats: ["wav", "flac", "ogg", "mp3"],
+    preferredFormat: "wav"
+  },
+  {
+    id: "whisper-server",
+    name: "Whisper Server",
+    description: "whisper.cpp server API. Prefers wav format.",
+    type: "server",
+    acceptsFormats: ["wav", "flac", "ogg", "mp3"],
+    preferredFormat: "wav"
+  },
+  {
+    id: "openai-cloud",
+    name: "OpenAI Cloud",
+    description: "OpenAI cloud API. Accepts wav, flac, mp3, m4a, ogg, webm.",
+    type: "cloud",
+    acceptsFormats: ["wav", "flac", "mp3", "m4a", "ogg", "webm"],
+    preferredFormat: "mp3"
+  },
+  {
+    id: "google-cloud",
+    name: "Google Cloud",
+    description: "Google Cloud Speech-to-Text. Prefers flac format.",
+    type: "cloud",
+    acceptsFormats: ["wav", "flac", "mp3", "ogg", "opus", "webm"],
+    preferredFormat: "flac"
+  },
+  {
+    id: "microsoft-azure",
+    name: "Azure Cognitive Services",
+    description: "Microsoft Azure Speech-to-Text. Requires wav format.",
+    type: "cloud",
+    acceptsFormats: ["wav"],
+    preferredFormat: "wav"
+  },
+  {
+    id: "amazon-transcribe",
+    name: "Amazon Transcribe",
+    description: "Amazon Transcribe streaming. Accepts flac, opus, ogg.",
+    type: "cloud",
+    acceptsFormats: ["flac", "opus", "ogg"],
+    preferredFormat: "flac"
+  },
+  {
+    id: "deepgram",
+    name: "Deepgram",
+    description: "Deepgram API. Accepts most common formats.",
+    type: "cloud",
+    acceptsFormats: ["wav", "flac", "mp3", "opus", "ogg", "webm", "m4a"],
+    preferredFormat: "wav"
+  }
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  recognitionEngines,
+  recognize
+});

package/dist/api/Recognition.d.cts

@@ -0,0 +1,77 @@
+import { ReadStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { AudioFormat } from '../audio/AudioFormat.cjs';
+import { AudioSource } from '../audio/AudioSource.cjs';
+import { ConversionMode } from '../config.cjs';
+import { OpenAICloudSTTOptions } from '../recognition/OpenAICloudSTT.cjs';
+import { WhisperCppOptions } from '../recognition/WhisperCppSTT.cjs';
+import { WhisperServerOptions } from '../recognition/WhisperServerSTT.cjs';
+import { Timeline } from '../utilities/Timeline.cjs';
+import { TimingSummary } from '../utilities/Timing.cjs';
+import '../cli/config.cjs';
+
+type AudioInput = Readable | ReadStream | string | AudioSource;
+type Audio = AudioInput;
+declare function recognize(input: AudioInput, options: RecognitionOptions): Promise<RecognitionResult>;
+interface RecognitionResult {
+    transcript: string;
+    timeline: Timeline;
+    language: string;
+    timing: TimingSummary;
+}
+type RecognitionEngine = "whisper.cpp" | "whisper-server" | "google-cloud" | "microsoft-azure" | "amazon-transcribe" | "openai-cloud" | "deepgram";
+interface BaseRecognitionOptions {
+    language: string;
+    signal?: AbortSignal | null | undefined;
+    inputFormat?: AudioFormat;
+    conversionMode?: ConversionMode | undefined;
+}
+type RecognitionOptions = (BaseRecognitionOptions & {
+    engine: "whisper.cpp";
+    options: WhisperCppOptions;
+}) | (BaseRecognitionOptions & {
+    engine: "whisper-server";
+    options: WhisperServerOptions;
+}) | (BaseRecognitionOptions & {
+    engine: "openai-cloud";
+    options: OpenAICloudSTTOptions;
+}) | (BaseRecognitionOptions & {
+    engine: "google-cloud";
+    options: {
+        apiKey: string;
+        alternativeLanguageCodes?: string[];
+        profanityFilter?: boolean;
+        autoPunctuation?: boolean;
+        useEnhancedModel?: boolean;
+    };
+}) | (BaseRecognitionOptions & {
+    engine: "microsoft-azure";
+    options: {
+        subscriptionKey: string;
+        serviceRegion: string;
+    };
+}) | (BaseRecognitionOptions & {
+    engine: "amazon-transcribe";
+    options: {
+        region: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+}) | (BaseRecognitionOptions & {
+    engine: "deepgram";
+    options: {
+        apiKey: string;
+        model: string;
+        punctuate: boolean;
+    };
+});
+declare const recognitionEngines: {
+    id: RecognitionEngine;
+    name: string;
+    description: string;
+    type: "local" | "cloud" | "server";
+    acceptsFormats: AudioFormat[];
+    preferredFormat: AudioFormat;
+}[];
+
+export { type Audio, type AudioInput, type RecognitionEngine, type RecognitionOptions, type RecognitionResult, recognitionEngines, recognize };

package/dist/api/Recognition.d.ts

@@ -0,0 +1,77 @@
+import { ReadStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { AudioFormat } from '../audio/AudioFormat.js';
+import { AudioSource } from '../audio/AudioSource.js';
+import { ConversionMode } from '../config.js';
+import { OpenAICloudSTTOptions } from '../recognition/OpenAICloudSTT.js';
+import { WhisperCppOptions } from '../recognition/WhisperCppSTT.js';
+import { WhisperServerOptions } from '../recognition/WhisperServerSTT.js';
+import { Timeline } from '../utilities/Timeline.js';
+import { TimingSummary } from '../utilities/Timing.js';
+import '../cli/config.js';
+
+type AudioInput = Readable | ReadStream | string | AudioSource;
+type Audio = AudioInput;
+declare function recognize(input: AudioInput, options: RecognitionOptions): Promise<RecognitionResult>;
+interface RecognitionResult {
+    transcript: string;
+    timeline: Timeline;
+    language: string;
+    timing: TimingSummary;
+}
+type RecognitionEngine = "whisper.cpp" | "whisper-server" | "google-cloud" | "microsoft-azure" | "amazon-transcribe" | "openai-cloud" | "deepgram";
+interface BaseRecognitionOptions {
+    language: string;
+    signal?: AbortSignal | null | undefined;
+    inputFormat?: AudioFormat;
+    conversionMode?: ConversionMode | undefined;
+}
+type RecognitionOptions = (BaseRecognitionOptions & {
+    engine: "whisper.cpp";
+    options: WhisperCppOptions;
+}) | (BaseRecognitionOptions & {
+    engine: "whisper-server";
+    options: WhisperServerOptions;
+}) | (BaseRecognitionOptions & {
+    engine: "openai-cloud";
+    options: OpenAICloudSTTOptions;
+}) | (BaseRecognitionOptions & {
+    engine: "google-cloud";
+    options: {
+        apiKey: string;
+        alternativeLanguageCodes?: string[];
+        profanityFilter?: boolean;
+        autoPunctuation?: boolean;
+        useEnhancedModel?: boolean;
+    };
+}) | (BaseRecognitionOptions & {
+    engine: "microsoft-azure";
+    options: {
+        subscriptionKey: string;
+        serviceRegion: string;
+    };
+}) | (BaseRecognitionOptions & {
+    engine: "amazon-transcribe";
+    options: {
+        region: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+}) | (BaseRecognitionOptions & {
+    engine: "deepgram";
+    options: {
+        apiKey: string;
+        model: string;
+        punctuate: boolean;
+    };
+});
+declare const recognitionEngines: {
+    id: RecognitionEngine;
+    name: string;
+    description: string;
+    type: "local" | "cloud" | "server";
+    acceptsFormats: AudioFormat[];
+    preferredFormat: AudioFormat;
+}[];
+
+export { type Audio, type AudioInput, type RecognitionEngine, type RecognitionOptions, type RecognitionResult, recognitionEngines, recognize };

package/dist/api/Recognition.js

@@ -0,0 +1,233 @@
+import {
+  isAudioSource,
+  normalizeToAudioSource
+} from "../audio/index.js";
+import { getConversionMode } from "../config.js";
+import { getShortLanguageCode } from "../utilities/Locale.js";
+import { extendDeep } from "../utilities/ObjectUtilities.js";
+import {
+  addWordTextOffsetsToTimelineInPlace
+} from "../utilities/Timeline.js";
+import { createTiming } from "../utilities/Timing.js";
+async function recognize(input, options) {
+  const opts = extendDeep(
+    defaultRecognitionOptions,
+    options
+  );
+  const timing = createTiming();
+  timing.setMetadata("engine", opts.engine);
+  timing.setMetadata(
+    "conversionMode",
+    opts.conversionMode ?? getConversionMode()
+  );
+  if (!opts.language) {
+    throw new Error("Language must be specified");
+  }
+  const languageCode = opts.language;
+  const shortLanguageCode = getShortLanguageCode(languageCode);
+  timing.setMetadata("language", languageCode);
+  const source = resolveAudioSource(input, opts);
+  timing.setMetadata("inputFormat", source.format);
+  let transcript = "";
+  let timeline;
+  switch (opts.engine) {
+    case "whisper.cpp": {
+      const WhisperCppSTT = await import("../recognition/WhisperCppSTT.js");
+      timing.setMetadata("model", opts.options.model);
+      timing.setMetadata("processors", opts.options.processors ?? 1);
+      timing.setMetadata("threads", opts.options.threads ?? 4);
+      const result = await WhisperCppSTT.recognize(source, {
+        ...opts.options,
+        language: shortLanguageCode,
+        timing
+      });
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "openai-cloud": {
+      const OpenAICloudSTT = await import("../recognition/OpenAICloudSTT.js");
+      timing.setMetadata("model", opts.options.model ?? "whisper-1");
+      const result = await OpenAICloudSTT.recognize(source, shortLanguageCode, {
+        ...opts.options,
+        timing
+      });
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "whisper-server": {
+      const WhisperServerSTT = await import("../recognition/WhisperServerSTT.js");
+      const result = await WhisperServerSTT.recognize(
+        source,
+        shortLanguageCode,
+        { ...opts.options, timing }
+      );
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "google-cloud": {
+      const GoogleCloudSTT = await import("../recognition/GoogleCloudSTT.js");
+      if (!opts.options.apiKey) {
+        throw new Error("Google Cloud API key is required");
+      }
+      const result = await GoogleCloudSTT.recognize(
+        source,
+        { ...opts.options, timing },
+        shortLanguageCode
+      );
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "microsoft-azure": {
+      const AzureCognitiveServicesSTT = await import("../recognition/AzureCognitiveServicesSTT.js");
+      if (!opts.options.subscriptionKey) {
+        throw new Error("Azure subscription key is required");
+      }
+      if (!opts.options.serviceRegion) {
+        throw new Error("Azure service region is required");
+      }
+      const result = await AzureCognitiveServicesSTT.recognize(
+        source,
+        {
+          subscriptionKey: opts.options.subscriptionKey,
+          serviceRegion: opts.options.serviceRegion,
+          inputFormat: opts.inputFormat,
+          timing
+        },
+        shortLanguageCode
+      );
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "amazon-transcribe": {
+      const AmazonTranscribeSTT = await import("../recognition/AmazonTranscribeSTT.js");
+      const result = await AmazonTranscribeSTT.recognize(source, languageCode, {
+        region: opts.options.region,
+        accessKeyId: opts.options.accessKeyId,
+        secretAccessKey: opts.options.secretAccessKey,
+        inputFormat: opts.inputFormat,
+        timing
+      });
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    case "deepgram": {
+      const DeepgramSTT = await import("../recognition/DeepgramSTT.js");
+      if (!opts.options.apiKey) {
+        throw new Error("Deepgram API key is required");
+      }
+      timing.setMetadata("model", opts.options.model);
+      const result = await DeepgramSTT.recognize(
+        source,
+        shortLanguageCode,
+        {
+          apiKey: opts.options.apiKey,
+          model: opts.options.model,
+          punctuate: opts.options.punctuate,
+          inputFormat: opts.inputFormat,
+          timing,
+          conversionMode: opts.conversionMode
+        },
+        opts.signal
+      );
+      transcript = result.transcript;
+      timeline = result.timeline;
+      break;
+    }
+    default: {
+      const _engine = opts;
+      throw new Error(
+        `Unknown engine: ${_engine.engine}`
+      );
+    }
+  }
+  if (!timeline) {
+    throw new Error(`No timeline returned from engine ${opts.engine}`);
+  }
+  addWordTextOffsetsToTimelineInPlace(timeline, transcript);
+  return {
+    transcript,
+    timeline,
+    language: languageCode,
+    timing: timing.summary()
+  };
+}
+function resolveAudioSource(input, opts) {
+  if (isAudioSource(input)) {
+    return input;
+  }
+  return normalizeToAudioSource(input, opts.inputFormat);
+}
+const defaultRecognitionOptions = {
+  engine: "whisper.cpp",
+  options: {
+    model: "tiny.en"
+  }
+};
+const recognitionEngines = [
+  {
+    id: "whisper.cpp",
+    name: "OpenAI Whisper (C++ port)",
+    description: "Local whisper.cpp binary. Accepts wav, flac, ogg, mp3.",
+    type: "local",
+    acceptsFormats: ["wav", "flac", "ogg", "mp3"],
+    preferredFormat: "wav"
+  },
+  {
+    id: "whisper-server",
+    name: "Whisper Server",
+    description: "whisper.cpp server API. Prefers wav format.",
+    type: "server",
+    acceptsFormats: ["wav", "flac", "ogg", "mp3"],
+    preferredFormat: "wav"
+  },
+  {
+    id: "openai-cloud",
+    name: "OpenAI Cloud",
+    description: "OpenAI cloud API. Accepts wav, flac, mp3, m4a, ogg, webm.",
+    type: "cloud",
+    acceptsFormats: ["wav", "flac", "mp3", "m4a", "ogg", "webm"],
+    preferredFormat: "mp3"
+  },
+  {
+    id: "google-cloud",
+    name: "Google Cloud",
+    description: "Google Cloud Speech-to-Text. Prefers flac format.",
+    type: "cloud",
+    acceptsFormats: ["wav", "flac", "mp3", "ogg", "opus", "webm"],
+    preferredFormat: "flac"
+  },
+  {
+    id: "microsoft-azure",
+    name: "Azure Cognitive Services",
+    description: "Microsoft Azure Speech-to-Text. Requires wav format.",
+    type: "cloud",
+    acceptsFormats: ["wav"],
+    preferredFormat: "wav"
+  },
+  {
+    id: "amazon-transcribe",
+    name: "Amazon Transcribe",
+    description: "Amazon Transcribe streaming. Accepts flac, opus, ogg.",
+    type: "cloud",
+    acceptsFormats: ["flac", "opus", "ogg"],
+    preferredFormat: "flac"
+  },
+  {
+    id: "deepgram",
+    name: "Deepgram",
+    description: "Deepgram API. Accepts most common formats.",
+    type: "cloud",
+    acceptsFormats: ["wav", "flac", "mp3", "opus", "ogg", "webm", "m4a"],
+    preferredFormat: "wav"
+  }
+];
+export {
+  recognitionEngines,
+  recognize
+};