yt2text 0.1.0

package/dist/system-asr.js

@@ -0,0 +1,152 @@
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { runCommand } from "./process.js";
+import { ensureMacosSwiftc } from "./deps.js";
+import { splitWav } from "./media.js";
+import { mergeWordSegments } from "./segments.js";
+import { ProgressBar } from "./progress.js";
+import { Yt2TextError } from "./errors.js";
+const sourceDir = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(sourceDir, "..");
+const macosHelperVersion = "2";
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isNoSpeechError(message) {
+    return /No speech detected|kAFAssistantErrorDomain Code=1110|Speech recognition produced no result/i.test(message);
+}
+function timeoutMs(seconds) {
+    return seconds > 0 ? seconds * 1000 : undefined;
+}
+function offsetSegments(segments, offset) {
+    return segments.map((segment) => ({
+        ...segment,
+        start: segment.start + offset,
+        end: segment.end + offset,
+    }));
+}
+async function transcribeChunks(wavPath, paths, options, runChunk) {
+    const chunkDir = join(paths.workDir, "system-chunks");
+    await mkdir(chunkDir, { recursive: true });
+    const chunks = await splitWav(wavPath, chunkDir, options.chunkSeconds, options.convertTimeoutSeconds);
+    const all = [];
+    let engine = "system";
+    const progress = new ProgressBar("Transcribing audio");
+    try {
+        progress.update(0, `0/${chunks.length} chunks`);
+        for (let index = 0; index < chunks.length; index += 1) {
+            const result = await runChunk(chunks[index]);
+            engine = result.engine ?? engine;
+            all.push(...offsetSegments(result.segments ?? [], index * options.chunkSeconds));
+            progress.update((index + 1) / chunks.length, `${index + 1}/${chunks.length} chunks`);
+        }
+        progress.finish();
+    }
+    catch (error) {
+        progress.fail();
+        throw error;
+    }
+    return { engine, segments: mergeWordSegments(all) };
+}
+export async function transcribeWithSystem(wavPath, paths, options) {
+    if (process.platform === "darwin") {
+        const helperApp = await ensureMacosSpeechHelper(paths, options);
+        return transcribeChunks(wavPath, paths, options, async (chunkPath) => {
+            const mode = options.systemMode;
+            const outputPath = join(paths.workDir, `macos-speech-${Date.now()}-${Math.random().toString(16).slice(2)}.json`);
+            await rm(outputPath, { force: true });
+            try {
+                await runCommand("open", ["-n", "-j", "-g", "-W", helperApp, "--args", chunkPath, options.language, mode, outputPath], {
+                    quiet: true,
+                    timeoutMs: timeoutMs(options.asrChunkTimeoutSeconds),
+                });
+            }
+            catch (error) {
+                if (!(await exists(outputPath)))
+                    throw error;
+            }
+            if (!(await exists(outputPath))) {
+                throw new Yt2TextError("macOS Speech helper did not write an output file", "SYSTEM_ASR_FAILED");
+            }
+            const body = await readFile(outputPath, "utf8");
+            const parsed = JSON.parse(body);
+            if (parsed.error) {
+                if (isNoSpeechError(parsed.error)) {
+                    return {
+                        engine: mode === "offline" ? "macos-speech-on-device" : "macos-speech-system",
+                        language: options.language,
+                        segments: [],
+                    };
+                }
+                throw new Yt2TextError(parsed.error, "SYSTEM_ASR_FAILED");
+            }
+            return {
+                engine: parsed.engine ?? "macos-speech-system",
+                language: parsed.language ?? options.language,
+                segments: parsed.segments ?? [],
+            };
+        });
+    }
+    if (process.platform === "win32") {
+        if (options.systemMode === "online") {
+            throw new Yt2TextError("Windows system online file transcription is not available; use --system-mode offline, --system-mode auto, or --asr local.", "UNSUPPORTED_PROVIDER");
+        }
+        const helper = join(projectRoot, "helpers", "windows-transcribe.ps1");
+        return transcribeChunks(wavPath, paths, options, async (chunkPath) => {
+            const result = await runCommand("powershell.exe", [
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                helper,
+                "-AudioPath",
+                chunkPath,
+                "-Language",
+                options.language,
+            ], { quiet: true, timeoutMs: timeoutMs(options.asrChunkTimeoutSeconds) });
+            return JSON.parse(result.stdout);
+        });
+    }
+    throw new Yt2TextError("No cross-distro system ASR exists on Linux; use --asr local.", "UNSUPPORTED_PROVIDER");
+}
+async function ensureMacosSpeechHelper(paths, options) {
+    const app = join(paths.toolsDir, "macos-transcribe.app");
+    const binary = join(app, "Contents", "MacOS", "macos-transcribe");
+    const infoPlist = join(app, "Contents", "Info.plist");
+    const versionFile = join(app, "Contents", "Resources", "yt2text-helper-version");
+    if ((await exists(binary)) && (await exists(infoPlist)) && (await exists(versionFile))) {
+        const version = (await readFile(versionFile, "utf8")).trim();
+        if (version === macosHelperVersion)
+            return app;
+    }
+    const source = join(projectRoot, "helpers", "macos-transcribe.swift");
+    const plist = join(projectRoot, "helpers", "macos-speech-info.plist");
+    await ensureMacosSwiftc(options);
+    await rm(app, { recursive: true, force: true });
+    await mkdir(join(app, "Contents", "MacOS"), { recursive: true });
+    await mkdir(join(app, "Contents", "Resources"), { recursive: true });
+    await runCommand("swiftc", [
+        source,
+        "-o",
+        binary,
+        "-Xlinker",
+        "-sectcreate",
+        "-Xlinker",
+        "__TEXT",
+        "-Xlinker",
+        "__info_plist",
+        "-Xlinker",
+        plist,
+    ], { quiet: true });
+    const { copyFile } = await import("node:fs/promises");
+    await copyFile(plist, infoPlist);
+    await writeFile(versionFile, `${macosHelperVersion}\n`);
+    return app;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/helpers/macos-speech-info.plist

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleIdentifier</key>
+  <string>dev.yt2text.macos-transcribe</string>
+  <key>CFBundleName</key>
+  <string>yt2text macOS Speech Helper</string>
+  <key>CFBundleExecutable</key>
+  <string>macos-transcribe</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>LSUIElement</key>
+  <true/>
+  <key>NSSpeechRecognitionUsageDescription</key>
+  <string>yt2text uses macOS Speech Recognition to transcribe audio files locally when requested.</string>
+  <key>NSMicrophoneUsageDescription</key>
+  <string>yt2text does not record microphone audio, but macOS Speech may require this usage string.</string>
+</dict>
+</plist>

package/helpers/macos-transcribe.swift

@@ -0,0 +1,130 @@
+import Foundation
+import Speech
+
+struct Segment: Encodable {
+    let start: Double
+    let end: Double
+    let text: String
+    let confidence: Float?
+}
+
+struct Output: Encodable {
+    let engine: String
+    let language: String
+    let segments: [Segment]
+}
+
+enum HelperError: Error, CustomStringConvertible {
+    case badArguments
+    case authorizationDenied
+    case recognizerUnavailable
+    case noResult
+
+    var description: String {
+        switch self {
+        case .badArguments:
+            return "Usage: macos-transcribe <audio.wav> <locale> <online|offline|auto> [output.json]"
+        case .authorizationDenied:
+            return "Speech recognition authorization was denied"
+        case .recognizerUnavailable:
+            return "SFSpeechRecognizer is unavailable for the requested locale"
+        case .noResult:
+            return "Speech recognition produced no result"
+        }
+    }
+}
+
+func requestAuthorization() async -> Bool {
+    await withCheckedContinuation { continuation in
+        SFSpeechRecognizer.requestAuthorization { status in
+            continuation.resume(returning: status == .authorized)
+        }
+    }
+}
+
+func recognize(path: String, localeID: String, mode: String) async throws -> Output {
+    guard await requestAuthorization() else {
+        throw HelperError.authorizationDenied
+    }
+
+    let locale = Locale(identifier: localeID)
+    guard let recognizer = SFSpeechRecognizer(locale: locale), recognizer.isAvailable else {
+        throw HelperError.recognizerUnavailable
+    }
+
+    let request = SFSpeechURLRecognitionRequest(url: URL(fileURLWithPath: path))
+    request.shouldReportPartialResults = false
+    if mode == "offline" {
+        request.requiresOnDeviceRecognition = true
+    }
+
+    let result = try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<SFSpeechRecognitionResult, Error>) in
+        var didFinish = false
+        recognizer.recognitionTask(with: request) { result, error in
+            if didFinish {
+                return
+            }
+
+            if let error = error {
+                didFinish = true
+                continuation.resume(throwing: error)
+                return
+            }
+
+            if let result = result, result.isFinal {
+                didFinish = true
+                continuation.resume(returning: result)
+            }
+        }
+    }
+
+    let segments = result.bestTranscription.segments.map { segment in
+        Segment(
+            start: segment.timestamp,
+            end: segment.timestamp + segment.duration,
+            text: segment.substring,
+            confidence: segment.confidence
+        )
+    }
+
+    if segments.isEmpty {
+        throw HelperError.noResult
+    }
+
+    let engine = mode == "offline" ? "macos-speech-on-device" : "macos-speech-system"
+    return Output(engine: engine, language: localeID, segments: segments)
+}
+
+do {
+    guard CommandLine.arguments.count >= 4 else {
+        throw HelperError.badArguments
+    }
+
+    let output = try await recognize(
+        path: CommandLine.arguments[1],
+        localeID: CommandLine.arguments[2],
+        mode: CommandLine.arguments[3]
+    )
+
+    let encoder = JSONEncoder()
+    let data = try encoder.encode(output)
+    if CommandLine.arguments.count >= 5 {
+        try data.write(to: URL(fileURLWithPath: CommandLine.arguments[4]))
+    } else {
+        FileHandle.standardOutput.write(data)
+        FileHandle.standardOutput.write(Data("\n".utf8))
+    }
+} catch {
+    if CommandLine.arguments.count >= 5 {
+        let message = String(describing: error)
+        let escaped = message
+            .replacingOccurrences(of: "\\", with: "\\\\")
+            .replacingOccurrences(of: "\"", with: "\\\"")
+            .replacingOccurrences(of: "\n", with: "\\n")
+        let data = Data("{\"error\":\"\(escaped)\"}\n".utf8)
+        try? data.write(to: URL(fileURLWithPath: CommandLine.arguments[4]))
+    }
+    FileHandle.standardError.write(Data(String(describing: error).utf8))
+    FileHandle.standardError.write(Data("\n".utf8))
+    exit(1)
+}

package/helpers/windows-transcribe.ps1

@@ -0,0 +1,45 @@
+param(
+  [Parameter(Mandatory = $true)]
+  [string]$AudioPath,
+
+  [string]$Language = "zh-CN"
+)
+
+$ErrorActionPreference = "Stop"
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+
+Add-Type -AssemblyName System.Speech
+
+$cultureName = if ([string]::IsNullOrWhiteSpace($Language) -or $Language -eq "auto") { [System.Globalization.CultureInfo]::CurrentCulture.Name } else { $Language }
+$culture = [System.Globalization.CultureInfo]::GetCultureInfo($cultureName)
+$engine = New-Object System.Speech.Recognition.SpeechRecognitionEngine($culture)
+
+try {
+  $engine.LoadGrammar((New-Object System.Speech.Recognition.DictationGrammar))
+  $engine.SetInputToWaveFile($AudioPath)
+  $segments = New-Object System.Collections.Generic.List[object]
+
+  while ($true) {
+    $result = $engine.Recognize()
+    if ($null -eq $result) {
+      break
+    }
+
+    foreach ($word in $result.Words) {
+      $segments.Add([pscustomobject]@{
+        start = $word.AudioPosition.TotalSeconds
+        end = ($word.AudioPosition + $word.AudioDuration).TotalSeconds
+        text = $word.Text
+        confidence = $word.Confidence
+      })
+    }
+  }
+
+  [pscustomobject]@{
+    engine = "windows-sapi"
+    language = $culture.Name
+    segments = $segments
+  } | ConvertTo-Json -Depth 6 -Compress
+} finally {
+  $engine.Dispose()
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "yt2text",
+  "version": "0.1.0",
+  "description": "Download audio from YouTube and transcribe it with system or local ASR.",
+  "type": "module",
+  "homepage": "https://github.com/lopleec/yt2text#readme",
+  "bugs": {
+    "url": "https://github.com/lopleec/yt2text/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lopleec/yt2text.git"
+  },
+  "keywords": [
+    "youtube",
+    "transcript",
+    "speech-to-text",
+    "asr",
+    "yt-dlp",
+    "cli"
+  ],
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "bin": {
+    "yt2text": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "helpers",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run check",
+    "prepack": "npm run build",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "commander": "^12.1.0"
+  },
+  "optionalDependencies": {
+    "sherpa-onnx-node": "^1.13.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "license": "MIT"
+}