@codearcade/subtitle-generator 1.0.0

package/README.md

@@ -0,0 +1,291 @@
+# Subtitle Generator
+
+Generate subtitle files (SRT, VTT, TXT) from audio files using OpenAI's Whisper model. Automatically downloads the binary and model files for your operating system.
+
+## Features
+
+- 🎬 Supports multiple subtitle formats (SRT, VTT, TXT)
+- 🤖 Uses OpenAI's Whisper for accurate transcription
+- 🔧 Multiple model sizes (small, medium, large)
+- 🖥️ Cross-platform support (Windows, macOS, Linux)
+- ⚡ Configurable thread count for performance tuning
+- 🌍 Multi-language support with auto-detection
+
+## Installation
+
+```bash
+npm install @codearcade/subtitle-generator
+```
+
+## Quick Start
+
+### 1. Initialize the Package
+
+Run the initialization command to download the Whisper binary and model:
+
+```bash
+npx subtitle-generator init
+```
+
+The init command will:
+
+- Detect your operating system
+- Download the appropriate Whisper binary
+- Prompt you to choose a model size:
+  - **small** - Fast transcription with good accuracy
+  - **medium** - Balanced performance and accuracy
+  - **large** - Highest accuracy (requires more resources)
+
+### 2. Use in Your Code
+
+Create a Node.js script to transcribe audio files:
+
+```javascript
+import path from "path";
+import { Whisper } from "@codearcade/subtitle-generator";
+
+const whisper = new Whisper({
+  modelPath: path.join(process.cwd(), "models", "ggml-small.bin"),
+  threads: 8,
+  outputFormat: "srt", // "srt" | "txt" | "vtt"
+  srtLang: "English",
+  // audioLang: "English" // leave undefined for auto-detection
+});
+
+const inputFile = path.join(process.cwd(), "input", "audio.mp3");
+const outputFile = path.join(process.cwd(), "output", "audio.srt");
+
+async function main() {
+  await whisper.transcribe(inputFile, outputFile);
+  console.log("Transcription finished!");
+}
+
+main();
+```
+
+## API Reference
+
+### Whisper Constructor
+
+Create a new Whisper instance with configuration options:
+
+```javascript
+const whisper = new Whisper(options);
+```
+
+#### Options
+
+| Option         | Type   | Default   | Description                                                                      |
+| -------------- | ------ | --------- | -------------------------------------------------------------------------------- |
+| `modelPath`    | string | required  | Absolute path to the Whisper model binary file                                   |
+| `threads`      | number | 4         | Number of threads to use for transcription                                       |
+| `outputFormat` | string | "srt"     | Output subtitle format: `"srt"`, `"vtt"`, or `"txt"`                             |
+| `srtLang`      | string | "English" | Language for SRT metadata                                                        |
+| `audioLang`    | string | undefined | Audio language code (e.g., "en", "es", "fr"). Leave undefined for auto-detection |
+
+### Methods
+
+#### `transcribe(inputPath, outputPath)`
+
+Transcribe an audio file and save the output to a subtitle file.
+
+**Parameters:**
+
+- `inputPath` (string): Path to the audio file (supports mp3, wav, m4a, flac, etc.)
+- `outputPath` (string): Path where the subtitle file will be saved
+
+**Returns:** Promise<void>
+
+**Example:**
+
+```javascript
+await whisper.transcribe("./audio/interview.mp3", "./subtitles/interview.srt");
+```
+
+## Supported Audio Formats
+
+- MP3
+- WAV
+- M4A
+- FLAC
+- OGG
+- WEBM
+- And other common audio formats
+
+## Supported Output Formats
+
+### SRT (SubRip)
+
+Standard subtitle format with timecodes and subtitle index:
+
+```
+1
+00:00:00,000 --> 00:00:05,000
+First subtitle line
+
+2
+00:00:05,000 --> 00:00:10,000
+Second subtitle line
+```
+
+### VTT (WebVTT)
+
+Web video text track format:
+
+```
+WEBVTT
+
+00:00:00.000 --> 00:00:05.000
+First subtitle line
+
+00:00:05.000 --> 00:00:10.000
+Second subtitle line
+```
+
+### TXT (Plain Text)
+
+Simple text transcription with timestamps:
+
+```
+[00:00:00] First subtitle line
+[00:00:05] Second subtitle line
+```
+
+## Configuration
+
+### Model Selection
+
+Models are stored in a `models` directory. After running `init`, choose your model size:
+
+- **small** (~140MB) - Good for fast transcription with reasonable accuracy
+- **medium** (~380MB) - Better accuracy with moderate performance impact
+- **large** (~1.4GB) - Highest accuracy, requires more RAM and processing time
+
+### Thread Count
+
+Adjust the `threads` option based on your CPU:
+
+```javascript
+const whisper = new Whisper({
+  modelPath: "./models/ggml-small.bin",
+  threads: 16, // Use more threads on high-core-count CPUs
+  outputFormat: "srt",
+});
+```
+
+## Examples
+
+### Batch Processing Multiple Files
+
+```javascript
+import path from "path";
+import { Whisper } from "@codearcade/subtitle-generator";
+import fs from "fs";
+
+const whisper = new Whisper({
+  modelPath: path.join(process.cwd(), "models", "ggml-small.bin"),
+  threads: 8,
+  outputFormat: "srt",
+});
+
+async function processAudioFiles() {
+  const inputDir = "./input";
+  const outputDir = "./output";
+
+  const files = fs.readdirSync(inputDir);
+
+  for (const file of files) {
+    if (!file.endsWith(".mp3")) continue;
+
+    const inputPath = path.join(inputDir, file);
+    const outputPath = path.join(outputDir, file.replace(".mp3", ".srt"));
+
+    console.log(`Processing ${file}...`);
+    await whisper.transcribe(inputPath, outputPath);
+    console.log(`Completed: ${file}`);
+  }
+}
+
+processAudioFiles();
+```
+
+### Auto-Detect Language
+
+```javascript
+const whisper = new Whisper({
+  modelPath: "./models/ggml-small.bin",
+  threads: 8,
+  outputFormat: "srt",
+  // audioLang is undefined - language will be auto-detected
+});
+
+await whisper.transcribe("./audio/unknown-language.mp3", "./output/result.srt");
+```
+
+### Specify Language
+
+```javascript
+const whisper = new Whisper({
+  modelPath: "./models/ggml-small.bin",
+  threads: 8,
+  outputFormat: "srt",
+  audioLang: "es", // Spanish
+});
+
+await whisper.transcribe("./audio/spanish.mp3", "./output/spanish.srt");
+```
+
+## Project Structure
+
+After using the package, your project structure might look like:
+
+```
+project/
+├── models/
+│   └── ggml-small.bin        # Downloaded Whisper model
+├── input/
+│   ├── audio1.mp3
+│   └── audio2.mp3
+├── output/
+│   ├── audio1.srt
+│   └── audio2.srt
+├── transcribe.js             # Your transcription script
+└── package.json
+```
+
+## Troubleshooting
+
+### "Model file not found"
+
+Make sure you ran `npx subtitle-generator init` first to download the model.
+
+### "Binary not found for your OS"
+
+The package only supports Windows, macOS, and Linux. Check that you're on a supported operating system.
+
+### Slow transcription
+
+- Increase the `threads` option (if your CPU has more cores)
+- Use a smaller model (small instead of large)
+- Ensure your system has adequate RAM available
+
+### Out of memory errors
+
+- Use a smaller model size
+- Reduce the `threads` count
+- Process files one at a time instead of in parallel
+
+## Performance Tips
+
+1. **Model Size**: Start with `small` model for speed, upgrade to `medium` or `large` if accuracy isn't sufficient
+2. **Thread Count**: Set to number of CPU cores for optimal performance
+3. **Batch Processing**: Process multiple files sequentially to avoid memory issues
+4. **Audio Quality**: Clear audio produces better results than noisy recordings
+
+## License
+
+MIT © [CodeArcade](https://github.com/codearcade-io)
+
+## Support
+
+For issues, questions, or contributions, visit the [GitHub repository](https://github.com/codearcade-io/subtitle-generator).

package/cli/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+
+if (args[0] === 'init') {
+  import('../init/index.js').then(mod => mod.default());
+} else {
+  console.log('Usage: npx @codearcade/ai-subtitle-generator init');
+}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+declare const audioLang: {
+    readonly English: "en";
+    readonly Spanish: "es";
+    readonly French: "fr";
+    readonly German: "de";
+    readonly Chinese: "zh";
+    readonly Japanese: "ja";
+    readonly Korean: "ko";
+    readonly Russian: "ru";
+    readonly Portuguese: "pt";
+    readonly Italian: "it";
+    readonly Dutch: "nl";
+    readonly Arabic: "ar";
+    readonly Hindi: "hi";
+    readonly Turkish: "tr";
+};
+type AudioLangKey = keyof typeof audioLang;
+interface WhisperOptions {
+    modelPath: string;
+    threads?: number;
+    outputFormat?: "srt" | "txt" | "vtt";
+    audioLang?: AudioLangKey;
+    srtLang?: AudioLangKey;
+}
+export declare class Whisper {
+    private modelPath;
+    private threads;
+    private outputFormat;
+    private audioLang?;
+    private srtLang?;
+    constructor(options: WhisperOptions);
+    /**
+     * Transcribe a single audio file
+     * @param inputFile - path to input audio
+     * @param outputFile - path to output (without extension)
+     */
+    transcribe(inputFile: string, outputFile: string): Promise<void>;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,95 @@
+// src/index.ts
+import { spawn } from "child_process";
+import os from "os";
+import path from "path";
+var __dirname2 = process.cwd();
+var isWindows = os.platform() === "win32";
+var isMac = os.platform() === "darwin";
+var binaryName = isWindows ? "whisper-cli.exe" : isMac ? "whisper" : "whisper";
+var audioLang = {
+  English: "en",
+  Spanish: "es",
+  French: "fr",
+  German: "de",
+  Chinese: "zh",
+  Japanese: "ja",
+  Korean: "ko",
+  Russian: "ru",
+  Portuguese: "pt",
+  Italian: "it",
+  Dutch: "nl",
+  Arabic: "ar",
+  Hindi: "hi",
+  Turkish: "tr"
+};
+
+class Whisper {
+  modelPath;
+  threads;
+  outputFormat;
+  audioLang;
+  srtLang;
+  constructor(options) {
+    this.modelPath = options.modelPath;
+    this.threads = options.threads || 8;
+    this.outputFormat = options.outputFormat || "srt";
+    this.audioLang = options.audioLang ? audioLang[options.audioLang] : undefined;
+    this.srtLang = options.srtLang ? audioLang[options.srtLang] : undefined;
+  }
+  transcribe(inputFile, outputFile) {
+    return new Promise((resolve, reject) => {
+      const outputFlag = this.outputFormat === "srt" ? "-osrt" : this.outputFormat === "txt" ? "-otxt" : this.outputFormat === "vtt" ? "-ovtt" : "-osrt";
+      const args = [
+        "-m",
+        this.modelPath,
+        "-f",
+        inputFile,
+        outputFlag,
+        "-of",
+        outputFile,
+        "-t",
+        String(this.threads),
+        "-bs",
+        "5",
+        "-bo",
+        "1",
+        "-ml",
+        "30",
+        "-sow",
+        "false",
+        "-nt",
+        "-et",
+        "2.4",
+        "-lpt",
+        "-1.0"
+      ];
+      if (this.audioLang) {
+        args.push("-l", this.audioLang);
+      }
+      if (this.srtLang === "en" && this.audioLang !== "en") {
+        args.push("-tr");
+      }
+      const binaryPath = path.join(__dirname2, "whisper", binaryName);
+      console.log("Running:", binaryPath, args.join(" "));
+      const process2 = spawn(binaryPath, args);
+      process2.stdout.on("data", (data) => {
+        console.log(`[stdout]: ${data}`);
+      });
+      process2.stderr.on("data", (data) => {
+        console.log(`[stderr]: ${data}`);
+      });
+      process2.on("close", (code) => {
+        if (code !== 0) {
+          return reject(new Error(`Process exited with code ${code}`));
+        }
+        resolve();
+      });
+      process2.on("error", (err) => {
+        reject(err);
+      });
+    });
+  }
+}
+export {
+  Whisper
+};

package/init/index.js

@@ -0,0 +1,179 @@
+import inquirer from "inquirer";
+import path from "path";
+import fs from "fs";
+import os from "os";
+import { execSync } from "child_process";
+
+const init = async () => {
+  const { modelSize } = await inquirer.prompt([
+    {
+      type: "list",
+      name: "modelSize",
+      message: "Which Whisper model do you want to download?",
+      choices: [
+        { name: "Small  — fast, lower accuracy", value: "small" },
+        { name: "Medium — balanced", value: "medium" },
+        { name: "Large  — slow, highest accuracy", value: "large" },
+      ],
+      default: "small",
+    },
+  ]);
+
+  const modelUrls = {
+    small:
+      "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin",
+    medium:
+      "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin",
+    large:
+      "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin",
+  };
+
+  const modelUrl = modelUrls[modelSize];
+
+  // Helper function to download both models and zip files
+  async function downloadFile(url, dest, label) {
+    if (fs.existsSync(dest)) {
+      console.log(`${label} already exists at ${dest}`);
+      return;
+    }
+
+    console.log(`Downloading ${label}...`);
+    const res = await fetch(url);
+
+    if (!res.ok) throw new Error(`Failed to download: ${res.statusText}`);
+
+    const total = Number(res.headers.get("content-length")) || 0;
+    let downloaded = 0;
+
+    const file = fs.createWriteStream(dest);
+
+    await res.body.pipeTo(
+      new WritableStream({
+        write(chunk) {
+          downloaded += chunk.length;
+          if (total) {
+            const percent = ((downloaded / total) * 100).toFixed(2);
+            process.stdout.write(`Downloading ${label}... ${percent}%\r`);
+          } else {
+            process.stdout.write(`Downloaded ${downloaded} bytes\r`);
+          }
+          file.write(chunk);
+        },
+        close() {
+          file.end();
+          console.log(`\n${label} download complete.`);
+        },
+        abort(err) {
+          file.destroy(err);
+        },
+      }),
+    );
+  }
+
+  // 1. Download the AI Model
+  const modelsDir = path.join(process.cwd(), "models");
+  if (!fs.existsSync(modelsDir)) {
+    fs.mkdirSync(modelsDir, { recursive: true });
+  }
+  const destModelPath = path.join(modelsDir, path.basename(modelUrl));
+  await downloadFile(modelUrl, destModelPath, `${modelSize} model`);
+
+  // 2. Setup the Binary based on OS
+  console.log("\nSetting up whisper.cpp binary...");
+  const platform = os.platform();
+  const whisperDir = path.join(process.cwd(), "whisper");
+  const isWindows = platform === "win32";
+
+  if (!fs.existsSync(whisperDir)) {
+    fs.mkdirSync(whisperDir, { recursive: true });
+  }
+
+  if (isWindows) {
+    // Windows Setup
+    const binaryDest = path.join(whisperDir, "whisper-cli.exe");
+    if (!fs.existsSync(binaryDest)) {
+      // Using latest pre-built x64 binaries from ggml-org
+      const zipUrl =
+        "https://github.com/ggerganov/whisper.cpp/releases/latest/download/whisper-bin-x64.zip";
+      const zipPath = path.join(whisperDir, "whisper.zip");
+
+      await downloadFile(zipUrl, zipPath, "Whisper Windows Binary");
+
+      console.log("Extracting binary...");
+      // Windows 10+ has native tar for unzipping
+      execSync(`tar -xf "${zipPath}" -C "${whisperDir}"`);
+
+      // 1. Move everything out of the "Release" folder (or any other subfolder the zip might use)
+      const possibleReleaseDir = path.join(whisperDir, "Release");
+
+      if (fs.existsSync(possibleReleaseDir)) {
+        // Read all files inside the Release folder
+        const files = fs.readdirSync(possibleReleaseDir);
+
+        // Move them up one level into the main whisperDir
+        for (const file of files) {
+          fs.renameSync(
+            path.join(possibleReleaseDir, file),
+            path.join(whisperDir, file),
+          );
+        }
+        // Delete the now-empty Release folder
+        fs.rmdirSync(possibleReleaseDir);
+      }
+
+      // 2. Rename extracted main.exe to match our wrapper expectations
+      const extractedMain = path.join(whisperDir, "main.exe");
+      if (fs.existsSync(extractedMain)) {
+        fs.renameSync(extractedMain, binaryDest);
+      } else {
+        console.error("Warning: Could not find main.exe after extraction.");
+      }
+
+      // 3. Clean up the zip file so it doesn't clutter the folder
+      if (fs.existsSync(zipPath)) {
+        fs.unlinkSync(zipPath);
+      }
+
+      console.log("Whisper binary setup complete for Windows.");
+    } else {
+      console.log("Whisper binary already exists for Windows.");
+    }
+  } else {
+    // Mac / Linux Setup
+    const binaryDest = path.join(whisperDir, "whisper");
+    if (!fs.existsSync(binaryDest)) {
+      console.log("Mac/Linux detected. Building whisper.cpp from source...");
+      console.log(
+        "Note: This requires 'git', 'make', and a C/C++ compiler (gcc/clang).",
+      );
+
+      const repoDir = path.join(whisperDir, "source");
+      if (!fs.existsSync(repoDir)) {
+        // Shallow clone to save time and bandwidth
+        execSync(
+          `git clone --depth 1 https://github.com/ggerganov/whisper.cpp.git "${repoDir}"`,
+          { stdio: "inherit" },
+        );
+      }
+
+      console.log("Compiling... This might take a minute.");
+      // Compile only the main CLI tool
+      execSync(`cd "${repoDir}" && make main`, { stdio: "inherit" });
+
+      const compiledPath = path.join(repoDir, "main");
+      if (fs.existsSync(compiledPath)) {
+        fs.copyFileSync(compiledPath, binaryDest);
+        execSync(`chmod +x "${binaryDest}"`);
+        console.log("Whisper binary compiled and configured successfully.");
+      } else {
+        console.error(
+          "Error: Could not find the compiled binary. Compilation might have failed.",
+        );
+      }
+    } else {
+      console.log("Whisper binary already exists.");
+    }
+  }
+};
+
+export default init;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@codearcade/subtitle-generator",
+  "version": "1.0.0",
+  "main": "index.js",
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun ./builder.ts && bun run generate-types",
+    "prepublishOnly": "bun run build",
+    "generate-types": "bunx tsc --emitDeclarationOnly --declaration --outDir dist",
+    "clear": "rm -rf dist"
+  },
+  "bin": {
+    "subtitle-generator": "./cli/index.js"
+  },
+  "files": [
+    "dist",
+    "cli",
+    "init"
+  ],
+  "homepage": "https://github.com/codearcade-io/subtitle-generator.git#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codearcade-io/subtitle-generator.git"
+  },
+  "bugs": "https://github.com/codearcade-io/subtitle-generator/issues",
+  "author": "Abhishek Singh <official.6packprogrammer@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Generate subtitles from audio files using OpenAI Whisper with support for SRT, VTT, and TXT formats. Automatically downloads required binaries and models, with cross-platform support and configurable performance options.",
+  "keywords": [
+    "whisper",
+    "subtitle",
+    "subtitles",
+    "speech-to-text",
+    "transcription",
+    "audio",
+    "srt",
+    "vtt",
+    "nodejs",
+    "npm",
+    "openai",
+    "ai",
+    "speech-recognition",
+    "cli",
+    "cross-platform"
+  ],
+  "devDependencies": {
+    "@types/bun": "^1.3.11"
+  },
+  "dependencies": {
+    "inquirer": "^13.3.2"
+  }
+}