@pls-compile-owo/fisheye 0.3.0 → 0.7.1

package/lib/stages.mjs

@@ -5,11 +5,17 @@ import path from 'node:path'
 import crypto from 'node:crypto'
 import { execFileSync, spawnSync } from 'node:child_process'
 import { spamReason, filterDanmaku } from '../danmaku-filter.mjs'
-import { PKG_DIR, WS, CACHE, OUT, CFG_FILE, LOCAL_CFG, onPath, resolveTool, FFMPEG, PYTHON, CRED } from './env.mjs'
+import { PKG_DIR, WS, CACHE, OUT, CFG_FILE, LOCAL_CFG, onPath, resolveTool, FFMPEG, PYTHON, PYTHON_RES, CRED } from './env.mjs'
 import { fmt, fsec, jpegSize, fail, num, gridStr, parseTime, pageNum } from './util.mjs'
 import { UA, cred, H, getView, MIXIN_TAB, keyOf, clean, getOfficialSubs, looksLikeMp4, ensureMp4, getDanmaku } from './bili.mjs'
 import { detectScenes, subtractAds, pickTimes, snapSubsTimes, detectBand, grabFrame, runCapture } from './frame.mjs'
+import { audioCaps, transcribeAudio } from './audio.mjs'
+import { ocrCaps, ocrImage } from './ocr.mjs'
+import { ytdlpCaps, downloadVideo } from './ytdlp.mjs'
+import { parseBatchList, runBatch, formatBatchReport } from './batch.mjs'
+import { loadManifestState, canResume, recordStage } from './resume.mjs'
 import { AD_SEGMENT_SIGNAL, detectAdSegments, summarizeDanmaku } from './danmaku.mjs'
+import { estimateTokens, tokensPerUnit, modelFactor, COST } from './budget.mjs'
 
 export async function stageGrid(bvid, chunkSec, grid, pre = {}) {
   const pageNo = pre.page ?? 1
@@ -276,7 +282,11 @@ export async function stageSubs(bvid, count, bandArg, pre = {}) {
 // 平衡原则：先保「看懂所需的最低帧密度」，再在剩余预算里加张数；
 // 预算不够时诚实降级并报告，而不是悄悄变稀。
 
-export const COST = { grid: 1200, subs: 1000, fine: 1300 } // 单张成本估算（token）
+// 单张成本不再写死：统一走 lib/budget.mjs 的 estimateTokens(kind, count)。
+// 默认基准仍是 grid 1200 / subs 1000 / fine 1300（与旧版完全一致），
+// 但支持 FISHEYE_TOKENS_PER_* 覆盖与 FISHEYE_TOKEN_MODEL 模型系数。
+// COST 保留导出只为兼容旧的外部引用，内部不再直接乘它（它看不到环境变量）。
+export { COST }
 
 export const MAX_GRIDS = 12                                  // 拼图张数硬上限，防长视频失控
 
@@ -312,7 +322,7 @@ export async function stageSelftest(opts = {}) {
   else {
     const r = runCapture(PYTHON, ['--version'], 10000)
     if (r.ok) rec('OK', 'python', r.out.trim())
-    else rec('!!', 'python', `无法执行（来源 ${PYTHON_RES?.from ?? '?'}）：${r.err.slice(0, 50)}`)
+    else rec('--', 'python', `无法执行（${PYTHON_RES?.from ?? '?'}，可能是 Windows 商店占位符）——字幕带功能降级`)
   }
 
   // 4) analyze_subs.py
@@ -356,6 +366,18 @@ export async function stageSelftest(opts = {}) {
       const subs = await getOfficialSubs(testBv, cid, null)
       rec(subs ? 'OK' : '--', '官方字幕 API', subs ? `${subs.quality} / ${subs.lines} 行 / ${subs.chars} 字` : '这条视频无字幕轨（不影响，会用字幕带或画面）')
     } catch (e) { rec('!!', '官方字幕 API', String(e.message).slice(0, 50)) }
+  try {
+    const audio = audioCaps()
+    rec(audio.available ? 'OK' : '--', '音频转写', audio.summary)
+  } catch (e) { rec('!!', '音频转写', String(e.message).slice(0, 50)) }
+  try {
+    const ocr = ocrCaps()
+    rec(ocr.available ? 'OK' : '--', 'OCR', ocr.summary)
+  } catch (e) { rec('!!', 'OCR', String(e.message).slice(0, 50)) }
+  try {
+    const yt = ytdlpCaps()
+    rec(yt.available ? 'OK' : '--', 'yt-dlp', yt.summary)
+  } catch (e) { rec('!!', 'yt-dlp', String(e.message).slice(0, 50)) }
   } else {
     rec('--', '弹幕/字幕 API', '视频 API 不可用，跳过')
   }
@@ -425,6 +447,21 @@ export async function stageSelftest(opts = {}) {
 }
 
 export async function stageAuto(bvid, budget, opts = {}) {
+  // 断点：out/<BV>-manifest.json 存在且计划参数一致时可复用
+  // --resume 跳过已完成的抽帧阶段；--force 强制重跑；默认只提示
+  let prevManifest = null
+  let resumeInfo = null
+  try {
+    const prev = loadManifestState(OUT, bvid)
+    if (prev && !opts.force) {
+      resumeInfo = canResume(prev, { plan: { budget, density: opts.density ?? null, from: opts.from ?? null, to: opts.to ?? null } })
+      if (resumeInfo.resumable) {
+        prevManifest = prev
+        console.log('[断点] 检测到可复用产物：' + resumeInfo.reason +
+          (opts.resume === true ? '（--resume：跳过抽帧）' : '（加 --resume 跳过抽帧 / --force 强制重跑）'))
+      }
+    }
+  } catch {}
   const pageNo = opts.page ?? 1
   const mp4 = await ensureMp4(bvid, pageNo)
   const view = await getView(bvid)
@@ -452,16 +489,21 @@ export async function stageAuto(bvid, budget, opts = {}) {
   if (range) console.log(`[区间] 只处理 ${fmt(range.from)}-${fmt(range.to)}（${duration.toFixed(0)}s / 全片 ${fullDuration}s）`)
   if (pageCount > 1 && pageNo === 1) console.log(`[提示] 多P 视频，本次只处理 P1；要处理别的分P 用 --p N`)
 
-  // 拼图 token 按实际画面比例修正：COST.grid 以 1920x1080 拼图为基准，
+  // 拼图 token 按实际画面比例修正：estimateTokens('grid', 1) 以 16:9（约 1920x1080）拼图为基准，
   // 方形/竖屏视频的拼图面积大得多（1920x1920 贵 78%，竖屏贵 3 倍+），不算清楚会误导预算决策
   const dim = view.dimension ?? {}
   const vw = Number(dim.width) || 1280
   const vh = Number(dim.height) || 720
   const cellH = Math.round((640 * vh) / Math.max(vw, 1))
   const sheetPx = 640 * 3 * (cellH * 3)
-  const gridCost = Math.max(300, Math.round((COST.grid * sheetPx) / (1920 * 1080)))
+  const gridBase = estimateTokens('grid', 1)
+  const gridCost = Math.max(300, Math.round((gridBase * sheetPx) / (1920 * 1080)))
+  const factor = modelFactor()
+  if (factor !== 1) {
+    console.log(`[预算] 模型系数 ×${factor}（FISHEYE_TOKEN_MODEL，按该 tokenizer 的图像成本修正）`)
+  }
   if (Math.abs(sheetPx / (1920 * 1080) - 1) > 0.25) {
-    console.log(`[比例] 画面 ${vw}x${vh} → 拼图 ${640 * 3}x${cellH * 3}，单张约 ${gridCost} token（基准 1200 已按面积修正）`)
+    console.log(`[比例] 画面 ${vw}x${vh} → 拼图 ${640 * 3}x${cellH * 3}，单张约 ${gridCost} token（基准 ${gridBase} 已按面积修正）`)
   }
 
   // 1. 内容变化率：只统计所处理区间内的显著变化（score≥0.3）
@@ -477,6 +519,7 @@ export async function stageAuto(bvid, budget, opts = {}) {
   const official = officialRaw?.quality === 'ok' ? officialRaw : null
   let bandResult = null
   let hasSubs = false
+  let transcript = '' // --audio 转写出的台词文本（有它就不再烧字幕带）
   if (official) {
     console.log(`[字幕] 官方${official.lanDoc ?? ''} ${official.lines} 行 / ${official.chars} 字 ≈ ${official.chars} token → 跳过字幕带`)
     console.log(`       文本: ${official.txt}`)
@@ -484,27 +527,52 @@ export async function stageAuto(bvid, budget, opts = {}) {
       console.log(`       ⚠️ 字幕较长（${official.chars} 字 ≈ ${official.chars} token），建议只读关心的时段而不是全文`)
     }
     for (const line of official.head.slice(0, 3)) console.log(`       ${line}`)
+    if (official.translated) {
+      console.log(`[字幕] 中文翻译 ${official.translated.lines} 行 / ${official.translated.chars} 字`)
+    }
   } else {
     if (officialRaw) {
       console.log(`[字幕] 官方字幕质量差（平均有效 ${officialRaw.avgEff} 字/行、去重率 ${officialRaw.uniqueRatio}）——疑为音乐/音效噪声，不采用`)
     }
-    // 传 fullDuration 而不是区间长度：字幕位置是视频级属性，采样必须跨全片
-    bandResult = detectBand(mp4, fullDuration)
-    // 置信度门槛：抖音式动态字幕（位置漂移 / 不是每帧都有）检测出来的「带」其实是画面内容，
-    // 拼出来一堆非字幕行。低于 0.5 就不用字幕带，只靠画面拼图。
-    const conf = bandResult?.confidence
-    const confOk = conf === undefined || conf >= 0.5
-    hasSubs = !!(bandResult?.ok && bandResult.bandRatio >= 0.015 && bandResult.bandRatio <= 0.35 && confOk)
-    if (bandResult?.ok && !confOk) {
-      console.log(`[字幕] 检出疑似字幕带（${(bandResult.topRatio * 100).toFixed(0)}%-${(bandResult.botRatio * 100).toFixed(0)}%）但置信度仅 ${Number(conf).toFixed(2)}`)
-      console.log(`       —— 字幕位置漂移或不是每帧都有（抖音式动态字幕常见），跳过字幕带，只靠画面`)
-    } else {
-      console.log(`[字幕] ${hasSubs
-        ? `无可用官方字幕，检出烧录字幕带（${(bandResult.topRatio * 100).toFixed(0)}%-${(bandResult.botRatio * 100).toFixed(0)}%，置信度 ${Number(conf).toFixed(2)}）→ 字幕带 1 张`
-        : '无可用字幕 → 只靠画面'}`)
+    if (opts.audio === true) {
+      const caps = audioCaps()
+      console.log(`[音频] ${caps.summary}`)
+      if (!caps.available) {
+        if (caps.hint) console.log(`       ${caps.hint}`)
+        console.log('[音频] 不可用 → 继续原逻辑（字幕带兜底）')
+      } else {
+        const tr = await transcribeAudio(mp4, OUT, { lang: opts.audioLang ?? 'zh', quiet: false })
+        const text = String(tr?.text ?? '').trim()
+        if (text) {
+          transcript = text
+          const txtFile = path.join(OUT, `${bvid}-audio-transcript.txt`)
+          fs.writeFileSync(txtFile, text, 'utf8')
+          console.log(`[音频] 转写成功：${text.length} 字（≈ ${text.length} token）→ ${txtFile}`)
+          console.log(`       文本: ${text.slice(0, 300)}`)
+          hasSubs = true // 台词文本已在手，不必再烧字幕带
+        } else {
+          console.log('[音频] 转写失败或结果为空 → 继续原逻辑（字幕带兜底）')
+        }
+      }
+    }
+    if (!transcript) {
+      // 传 fullDuration 而不是区间长度：字幕位置是视频级属性，采样必须跨全片
+      bandResult = detectBand(mp4, fullDuration)
+      // 置信度门槛：抖音式动态字幕（位置漂移 / 不是每帧都有）检测出来的「带」其实是画面内容，
+      // 拼出来一堆非字幕行。低于 0.5 就不用字幕带，只靠画面拼图。
+      const conf = bandResult?.confidence
+      const confOk = conf === undefined || conf >= 0.5
+      hasSubs = !!(bandResult?.ok && bandResult.bandRatio >= 0.015 && bandResult.bandRatio <= 0.35 && confOk)
+      if (bandResult?.ok && !confOk) {
+        console.log(`[字幕] 检出疑似字幕带（${(bandResult.topRatio * 100).toFixed(0)}%-${(bandResult.botRatio * 100).toFixed(0)}%）但置信度仅 ${Number(conf).toFixed(2)}`)
+        console.log(`       —— 字幕位置漂移或不是每帧都有（抖音式动态字幕常见），跳过字幕带，只靠画面`)
+      } else {
+        console.log(`[字幕] ${hasSubs
+          ? `无可用官方字幕，检出烧录字幕带（${(bandResult.topRatio * 100).toFixed(0)}%-${(bandResult.botRatio * 100).toFixed(0)}%，置信度 ${Number(conf).toFixed(2)}）→ 字幕带 1 张`
+          : '无可用字幕 → 只靠画面'}`)
+      }
+    }
     }
-  }
-
   // 2.5 弹幕（第三个信息源：观众反应）
   // 不参与「能不能看懂」的判定，只用来找高光——观众在哪一段最激动，那里通常最值得精读
   const danmakuRaw = await getDanmaku(cid, range)
@@ -551,10 +619,11 @@ export async function stageAuto(bvid, budget, opts = {}) {
   const framesNeeded = Math.ceil(duration / maxGap)
   const minGrids = Math.max(1, Math.ceil(framesNeeded / 9))
 
-  const subsCost = official ? Math.round(official.chars) : hasSubs ? COST.subs : 0
+  const subsCost = official ? Math.round(official.chars) : transcript ? transcript.length : hasSubs ? estimateTokens('subs', 1) : 0
   const subsRows = duration <= 180 ? 14 : duration <= 600 ? 20 : 24
   const minFine = (official || hasSubs) ? 2 : 3   // 字幕已在手，精读需求自然变少
-  const fixedCost = subsCost + minFine * COST.fine
+  const fineReserve = estimateTokens('fine', minFine)
+  const fixedCost = subsCost + fineReserve
   const maxGridsByBudget = Math.max(1, Math.floor((budget - fixedCost) / gridCost))
 
   let gridCount = minGrids
@@ -573,10 +642,10 @@ export async function stageAuto(bvid, budget, opts = {}) {
   const actualGap = duration / (gridCount * 9)
 
   // 5. 报告
-  const estTotal = subsCost + gridCount * gridCost + minFine * COST.fine
+  const estTotal = subsCost + gridCount * gridCost + fineReserve
   console.log(`[张数] 密度需要 ${minGrids} 张，预算允许 ${maxGridsByBudget} 张 → 采用 ${gridCount} 张`)
   console.log(`[参数] chunk=${chunk.toFixed(1)}s（每张覆盖），实际平均 ${actualGap.toFixed(1)}s/帧`)
-  console.log(`[预算] ${budget} token ≈ 字幕带 ${subsCost} + 拼图 ${gridCount * gridCost} + 精读预留 ${minFine * COST.fine} = ${estTotal}`)
+  console.log(`[预算] ${budget} token ≈ 字幕带 ${subsCost} + 拼图 ${gridCount * gridCost} + 精读预留 ${fineReserve} = ${estTotal}`)
   if (estTotal > budget) {
     console.log(`[警告] 最低配置已要 ${estTotal} token，超出预算 ${budget}（字幕带和精读预留不可再砍），将超支运行`)
   }
@@ -588,13 +657,19 @@ export async function stageAuto(bvid, budget, opts = {}) {
   const pre = {
     mp4, view, scenes, bandResult, subsSheet: hasSubs, range, page: pageNo,
     subsCovered: !!(official || hasSubs),          // 字幕信息是否已被覆盖（官方文本或烧录字幕带）
-    subsSource: official ? 'official' : hasSubs ? 'burned-in' : null,
+    subsSource: official ? 'official' : transcript ? 'audio' : hasSubs ? 'burned-in' : null,
     danmakuHot: dmHot,                             // 写进 manifest，让 refine 也能用弹幕热区挑点
     danmakuTotal: danmaku?.length ?? 0,
     adSegments: adSegs,                            // 视频内疑似广告段（精读会避开 high 置信度的）
     useDanmakuFrames: opts.useDanmakuFrames !== false,  // 弹幕热区是否也参与铺网取帧（默认是）
   }
-  const manifest = await stageGrid(bvid, chunk, '3x3', pre)
+  let manifest
+  if (opts.resume === true && prevManifest && resumeInfo?.resumable) {
+    manifest = prevManifest
+    console.log(`[断点] 复用已有拼图（${resumeInfo.doneGrids} 张），跳过抽帧`)
+  } else {
+    manifest = await stageGrid(bvid, chunk, '3x3', pre)
+  }
   if (hasSubs) await stageSubs(bvid, subsRows, 'auto', { mp4, view, bandResult, scenes, range, page: pageNo })
 
   // 7. 精读建议 = 几何规则（画面变化剧烈）+ 弹幕热区（观众反应最激烈）
@@ -633,7 +708,14 @@ export async function stageAuto(bvid, budget, opts = {}) {
   } else {
     console.log(`\n[精读建议] 两个信号都没命中；读图后如需精读：node fisheye.mjs refine ${bvid} --template`)
   }
-  return { gridCount, chunk, actualGap, maxGap, hasSubs, estTotal, notes, danmaku: danmaku?.length ?? 0, top: suggestions }
+  try {
+    const st = loadManifestState(OUT, bvid)
+    if (st) {
+      st.plan = { budget, density: opts.density ?? null, from: opts.from ?? null, to: opts.to ?? null }
+      recordStage(st, 'auto', { status: 'done', gridCount, hasSubs, audio: Boolean(transcript) })
+    }
+  } catch {}
+  return { gridCount, chunk, actualGap, maxGap, hasSubs, audio: Boolean(transcript), estTotal, notes, danmaku: danmaku?.length ?? 0, top: suggestions }
 }
 
 // refine：决定哪些格需要精读，然后自动截原分辨率单帧
@@ -775,12 +857,12 @@ export async function stageRefine(bvid, opts) {
   console.log(`\n[精读] 选中 ${picks.length} 个时间点：`)
   for (const p of picks) console.log(`  ${p.ts}  ${p.source}  —— ${p.reason}`)
   if (picks.length > 8) {
-    console.warn(`[警告] ${picks.length} 帧 ≈ ${picks.length * COST.fine} token，建议先只留真正看不清的几帧再跑`)
+    console.warn(`[警告] ${picks.length} 帧 ≈ ${estimateTokens('fine', picks.length)} token，建议先只留真正看不清的几帧再跑`)
   }
   console.log('')
   const grabbed = await stageGrab(bvid, picks.map((p) => p.t).join(','), { page: manifest.page ?? 1 })
-  const est = picks.length * COST.fine
-  console.log(`\n精读成本 ≈ ${est} token（${picks.length} 帧 × ${COST.fine}）`)
+  const est = estimateTokens('fine', picks.length)
+  console.log(`\n精读成本 ≈ ${est} token（${picks.length} 帧 × ${tokensPerUnit('fine')}）`)
   return { picks, grabbed }
 }
 
@@ -818,6 +900,159 @@ export async function stageGrab(bvid, timeStr, opts = {}) {
 
 // 本地视频：不依赖 B站，直接用 ffmpeg 抽帧拼图（fisheye local <文件>）
 
+export function cleanTargets(target = 'all') {
+  const want = String(target ?? 'all').trim().toLowerCase()
+  if (!['cache', 'out', 'all'].includes(want)) {
+    throw new Error(`--target 只能是 cache / out / all，收到：${JSON.stringify(target)}`)
+  }
+  const dirs = []
+  if (want === 'cache' || want === 'all') dirs.push({ name: 'cache', dir: CACHE })
+  if (want === 'out' || want === 'all') dirs.push({ name: 'out', dir: OUT })
+  return dirs
+}
+
+// 递归统计文件数与总大小（不跟符号链接：链接按 0 字节计，避免统计到外部大文件）
+function dirStat(root) {
+  let files = 0
+  let bytes = 0
+  const walk = (dir) => {
+    let ents = []
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of ents) {
+      const p = path.join(dir, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.isFile()) {
+        files++
+        try { bytes += fs.statSync(p).size } catch { /* 读不到就按 0 计 */ }
+      }
+    }
+  }
+  walk(root)
+  return { files, bytes }
+}
+
+function humanSize(bytes) {
+  const n = Number(bytes) || 0
+  if (n >= 1024 ** 3) return `${(n / 1024 ** 3).toFixed(2)} GB`
+  if (n >= 1024 ** 2) return `${(n / 1024 ** 2).toFixed(2)} MB`
+  if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${n} B`
+}
+
+// dry-run 时列出实际会被删掉的文件（最多 20 个/目录，避免长视频跑完刷屏几千行）
+function listEntries(root, max = 20) {
+  const out = []
+  const walk = (dir, depth) => {
+    if (out.length >= max) return
+    let ents = []
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+    ents.sort((a, b) => a.name.localeCompare(b.name))
+    for (const e of ents) {
+      if (out.length >= max) return
+      const p = path.join(dir, e.name)
+      const rel = path.relative(root, p)
+      if (e.isDirectory()) walk(p, depth + 1)
+      else if (e.isFile()) {
+        let size = 0
+        try { size = fs.statSync(p).size } catch {}
+        out.push({ rel, size })
+      }
+    }
+  }
+  walk(root, 0)
+  return out
+}
+
+
+export async function stageClean(opts = {}) {
+  const target = String(opts.target ?? 'all').trim().toLowerCase()
+  const yes = opts.yes === true
+  const dirs = cleanTargets(target)          // 先校验，非法 target 直接抛错
+  console.log(`\n=== 清理（target=${target}${yes ? '，--yes 实际删除' : '，dry-run'}）===`)
+
+  const plans = []
+  for (const d of dirs) {
+    const exists = fs.existsSync(d.dir)
+    if (!exists) {
+      console.log(`[${d.name}] 目录不存在，跳过：${d.dir}`)
+      continue
+    }
+    const st = dirStat(d.dir)
+    plans.push({ ...d, ...st })
+    if (!st.files) {
+      console.log(`[${d.name}] 空目录：${d.dir}`)
+      continue
+    }
+    console.log(`[${d.name}] ${st.files} 个文件 / ${humanSize(st.bytes)}  → ${d.dir}`)
+    for (const e of listEntries(d.dir)) {
+      console.log(`    ${e.rel}  ${humanSize(e.size)}`)
+    }
+    if (st.files > 20) console.log(`    …还有 ${st.files - 20} 个文件未列出`)
+  }
+
+  const totalFiles = plans.reduce((s, p) => s + p.files, 0)
+  const totalBytes = plans.reduce((s, p) => s + p.bytes, 0)
+  if (!plans.length) {
+    console.log('\n没有可清理的内容。')
+    return { target, deleted: false, files: 0, bytes: 0 }
+  }
+  if (!totalFiles) {
+    console.log('\n目录都是空的，没有可清理的内容。')
+    return { target, deleted: false, files: 0, bytes: 0 }
+  }
+
+  if (!yes) {
+    console.log(`\n将删除 ${totalFiles} 个文件 / ${humanSize(totalBytes)}（dry-run，什么都没删）`)
+    console.log('加 --yes 才会真正删除')
+    return { target, deleted: false, dryRun: true, files: totalFiles, bytes: totalBytes }
+  }
+
+  // 只删每个目录的内容，目录本身保留
+  let removedFiles = 0
+  let failed = 0
+  let freed = 0
+  for (const p of plans) {
+    let ents = []
+    try { ents = fs.readdirSync(p.dir, { withFileTypes: true }) } catch { continue }
+    for (const e of ents) {
+      const abs = path.join(p.dir, e.name)
+      const st = e.isDirectory() ? dirStat(abs) : { files: 1, bytes: (() => { try { return fs.statSync(abs).size } catch { return 0 } })() }
+      try {
+        fs.rmSync(abs, { recursive: true, force: true })
+        removedFiles += st.files
+        freed += st.bytes
+      } catch (err) {
+        failed++
+        console.warn(`[${p.name}] 删除失败：${abs}（${err?.message ?? err}）`)
+      }
+    }
+  }
+  console.log(`\n已删除 ${removedFiles} 个文件 / 释放 ${humanSize(freed)}${failed ? `（${failed} 项删除失败）` : ''}`)
+  return { target, deleted: true, files: removedFiles, bytes: freed, failed }
+}
+
+// CLI
+
+export async function stageTranscribe(bvid, opts = {}) {
+  const pageNo = opts.page ?? 1
+  const caps = audioCaps()
+  if (!caps.available) {
+    console.error(`[音频] 转写不可用：${caps.hint ?? caps.reason}`)
+    return null
+  }
+  const mp4 = await ensureMp4(bvid, pageNo)
+  const result = await transcribeAudio(mp4, OUT, { lang: opts.lang ?? 'zh', quiet: false })
+  if (!result?.text) {
+    console.error('[音频] 转写失败或结果为空')
+    return null
+  }
+  const outFile = path.join(OUT, `${bvid}-audio-transcript.txt`)
+  fs.writeFileSync(outFile, result.text, 'utf8')
+  console.log(`[音频] 转写完成：${result.text.length} 字 → ${outFile}`)
+  console.log(result.text.slice(0, 500))
+  return result
+}
+
 export async function stageLocal(inputFile, opts = {}) {
   const file = path.resolve(inputFile)
   if (!fs.existsSync(file)) throw new Error(`文件不存在: ${file}`)
@@ -855,3 +1090,53 @@ export async function stageLocal(inputFile, opts = {}) {
 }
 
 // CLI
+
+// OCR：识别一张图片里的文字（截图/画面帧/字幕带）
+export async function stageOcr(imagePath, opts = {}) {
+  const input = String(imagePath ?? '')
+  if (!input) { console.error('[OCR] 需要图片路径'); return null }
+  if (!fs.existsSync(input)) { console.error('[OCR] 文件不存在: ' + input); return null }
+  const caps = ocrCaps()
+  if (!caps.available) { console.error('[OCR] 不可用：' + (caps.hint ?? caps.reason)); return null }
+  const r = await ocrImage(input, { lang: opts.lang ?? 'chi_sim+eng', timeoutMs: 60000 })
+  if (!r?.text) { console.error('[OCR] 未识别到文字（或识别失败）'); return null }
+  fs.mkdirSync(OUT, { recursive: true })
+  const outFile = path.join(OUT, path.basename(input, path.extname(input)) + '.ocr.txt')
+  fs.writeFileSync(outFile, r.text, 'utf8')
+  console.log('[OCR] ' + r.text.length + ' 字 → ' + outFile)
+  console.log(r.text.slice(0, 1000))
+  return r
+}
+
+// URL：用 yt-dlp 下载任意平台视频，再走本地视频流程
+export async function stageUrl(url, opts = {}) {
+  const link = String(url ?? '').trim()
+  if (!/^https?:\/\//i.test(link)) { console.error('[URL] 只支持 http(s) 链接'); return null }
+  const caps = ytdlpCaps()
+  if (!caps.available) { console.error('[URL] yt-dlp 不可用：' + (caps.hint ?? caps.reason)); return null }
+  fs.mkdirSync(CACHE, { recursive: true })
+  console.log('[URL] 下载中（可能需要几分钟）：' + link)
+  const dl = await downloadVideo(link, CACHE, { timeoutMs: 600000 })
+  if (!dl?.file) { console.error('[URL] 下载失败'); return null }
+  console.log('[URL] 已下载 → ' + dl.file)
+  return stageLocal(dl.file, opts)
+}
+
+// 批量：从清单（文件或参数列表）逐条处理
+export async function stageBatch(input, opts = {}) {
+  const { items, errors } = parseBatchList(input)
+  for (const e of errors) console.error(`[批量] 第 ${e.line} 行无法识别：${String(e.raw).slice(0, 60)}`)
+  if (!items.length) { console.error('[批量] 没有可处理的条目'); return null }
+  console.log(`[批量] 共 ${items.length} 条（并发 ${opts.concurrency ?? 1}）`)
+  let idx = 0
+  const summary = await runBatch(items, async (item) => {
+    idx++
+    console.log(`\n[批量 ${idx}/${items.length}] ${item.kind}: ${String(item.value).slice(0, 80)}`)
+    if (item.kind === 'bv') return stageAuto(item.value, opts.budget ?? 20000, { page: opts.page ?? 1, audio: opts.audio === true, audioLang: opts.lang ?? null })
+    if (item.kind === 'file') return stageLocal(item.value, { grid: opts.grid ?? '3x3', from: opts.from ?? null, to: opts.to ?? null })
+    if (item.kind === 'url') return stageUrl(item.value, { grid: opts.grid ?? '3x3', from: opts.from ?? null, to: opts.to ?? null })
+    return null
+  }, { concurrency: opts.concurrency ?? 1 })
+  console.log('\n' + formatBatchReport(summary))
+  return summary
+}

package/lib/util.mjs

@@ -1,5 +1,6 @@
 // 通用工具：时间格式化、参数解析、文件头探测
 import fs from 'node:fs'
+import { t } from './i18n.mjs'
 
 // 时长格式化：超过 1 小时显示 01:05:30，否则 MM:SS
 
@@ -37,21 +38,21 @@ export function jpegSize(file) {
 // 参数校验（在 CLI 分发处用；Number('')===0、Infinity、NaN 都要挡掉）
 
 export const fail = (msg) => {
-  console.error(`参数错误：${msg}`)
+  console.error(`${t('err.argPrefix')}${msg}`)
   process.exit(2)
 }
 
 export const num = (v, name, { min, max } = {}) => {
   const n = Number(v)
-  if (v === '' || !Number.isFinite(n)) fail(`--${name} 需要数字，收到：${JSON.stringify(v)}`)
-  if (min !== undefined && n < min) fail(`--${name} 不能小于 ${min}（收到 ${n}）`)
-  if (max !== undefined && n > max) fail(`--${name} 不能大于 ${max}（收到 ${n}）`)
+  if (v === '' || !Number.isFinite(n)) fail(t('err.num.notNumber', { name, value: JSON.stringify(v) }))
+  if (min !== undefined && n < min) fail(t('err.num.min', { name, min, n }))
+  if (max !== undefined && n > max) fail(t('err.num.max', { name, max, n }))
   return n
 }
 
 export const gridStr = (v) => {
   const s = String(v ?? '3x3').toLowerCase()
-  if (!/^[1-9]x[1-9]$/.test(s)) fail(`--grid 格式应为 NxM（如 3x3，行列 1~9），收到：${JSON.stringify(v)}`)
+  if (!/^[1-9]x[1-9]$/.test(s)) fail(t('err.grid.format', { value: JSON.stringify(v) }))
   return s
 }
 // 时间参数：支持 330（秒）/ 5:30 / 1:05:30
@@ -61,16 +62,16 @@ export const parseTime = (v, name) => {
   const s = String(v).trim()
   if (/^\d+(\.\d+)?$/.test(s)) return Number(s)
   const parts = s.split(':')
-  if (parts.length < 2 || parts.length > 3) fail(`--${name} 时间格式应为 330 / 5:30 / 1:05:30，收到：${JSON.stringify(v)}`)
+  if (parts.length < 2 || parts.length > 3) fail(t('err.time.format', { name, value: JSON.stringify(v) }))
   const nums = parts.map(Number)
-  if (nums.some((n) => !Number.isFinite(n) || n < 0)) fail(`--${name} 时间格式非法：${JSON.stringify(v)}`)
+  if (nums.some((n) => !Number.isFinite(n) || n < 0)) fail(t('err.time.invalid', { name, value: JSON.stringify(v) }))
   return parts.length === 2 ? nums[0] * 60 + nums[1] : nums[0] * 3600 + nums[1] * 60 + nums[2]
 }
 
 export const pageNum = (v) => {
   if (v === null || v === undefined || v === '') return 1
   const n = Number(v)
-  if (!Number.isInteger(n) || n < 1 || n > 200) fail(`--p 分P序号应为 1~200 的整数，收到：${JSON.stringify(v)}`)
+  if (!Number.isInteger(n) || n < 1 || n > 200) fail(t('err.page.range', { value: JSON.stringify(v) }))
   return n
 }