dsh-convert-core 0.1.0-alpha.1

package/src/media/convert.ts

@@ -0,0 +1,232 @@
+/**
+ * 主编排:一个本地文件 → 知识就绪 Markdown + 本地图片。
+ *
+ * 档位规则(刻意保持简单可预测):
+ *
+ * | mode            | 字幕 | 转写 | 说明 |
+ * | --------------- | ---- | ---- | ---- |
+ * | `auto`(默认)  | 优先 | 仅当允许下载模型 | 有字幕就绝不碰模型 |
+ * | `subtitle-only` | 只用 | 永不 | 拿不到字幕就是"没有逐字稿",不报错 |
+ * | `transcribe`    | 跳过 | 强制 | 必须允许下载模型 |
+ * | `frames-only`   | 跳过 | 跳过 | 只要关键帧(连 OCR 也要显式开) |
+ */
+
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { probeTools, runFfmpeg, FFMPEG_HINT } from './binaries.js'
+import { buildMarkdown } from './markdown.js'
+import { extractKeyframes, extractSubtitles, parseSrt, probeMedia } from './media.js'
+import { describeModel, ocrImages, transcribe } from './models.js'
+import {
+  MediaToMarkdownError,
+  type MediaMeta,
+  type MediaMode,
+  type MediaSourceFormat,
+  type MediaToMarkdownOptions,
+  type MediaToMarkdownResult,
+  type MediaWarning,
+} from './types.js'
+
+export const VIDEO_EXTENSIONS = [
+  '.mp4', '.m4v', '.mov', '.mkv', '.webm', '.avi', '.flv', '.wmv', '.mpg', '.mpeg', '.ogv',
+]
+export const AUDIO_EXTENSIONS = [
+  '.mp3', '.m4a', '.wav', '.aac', '.flac', '.ogg', '.opus', '.aiff', '.aif', '.amr', '.wma',
+]
+export const IMAGE_EXTENSIONS = [
+  '.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.tif', '.tiff', '.heic',
+]
+export const MEDIA_EXTENSIONS = [...VIDEO_EXTENSIONS, ...AUDIO_EXTENSIONS, ...IMAGE_EXTENSIONS]
+
+const IMAGE_MAGIC: Array<{ test: (data: Buffer) => boolean; extension: string; contentType: string }> = [
+  { test: data => data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])), extension: 'png', contentType: 'image/png' },
+  { test: data => data[0] === 0xff && data[1] === 0xd8, extension: 'jpg', contentType: 'image/jpeg' },
+  { test: data => data.subarray(0, 3).toString('latin1') === 'GIF', extension: 'gif', contentType: 'image/gif' },
+  { test: data => data.subarray(0, 4).toString('latin1') === 'RIFF' && data.subarray(8, 12).toString('latin1') === 'WEBP', extension: 'webp', contentType: 'image/webp' },
+  { test: data => data.subarray(0, 2).toString('latin1') === 'BM', extension: 'bmp', contentType: 'image/bmp' },
+]
+
+async function sha256OfFile(file: string): Promise<string> {
+  const hash = createHash('sha256')
+  await new Promise<void>((resolve, reject) => {
+    createReadStream(file)
+      .on('data', chunk => hash.update(chunk))
+      .on('error', reject)
+      .on('end', () => resolve())
+  })
+  return `sha256:${hash.digest('hex')}`
+}
+
+function progressReporter(options: MediaToMarkdownOptions) {
+  return (stage: Parameters<NonNullable<MediaToMarkdownOptions['onProgress']>>[0]['stage'], progress: number | null, message?: string): void => {
+    options.onProgress?.({ stage, progress, ...(message ? { message } : {}) })
+  }
+}
+
+export async function convertMedia(options: MediaToMarkdownOptions): Promise<MediaToMarkdownResult> {
+  const file = options.file
+  const fileInfo = await stat(file).catch(() => undefined)
+  if (!fileInfo?.isFile()) {
+    throw new MediaToMarkdownError('INPUT_NOT_A_FILE', `输入不是文件:${file}`)
+  }
+  const versions = await probeTools({ ...(options.tools?.uvxPath ? { uvxPath: options.tools.uvxPath } : {}) })
+  if (!versions.ffmpeg || !versions.ffprobe) {
+    const missing = [!versions.ffprobe ? 'ffprobe' : null, !versions.ffmpeg ? 'ffmpeg' : null].filter(Boolean).join('、')
+    throw new MediaToMarkdownError('DEPENDENCY_MISSING', `缺少外部二进制:${missing}`, FFMPEG_HINT)
+  }
+
+  const extension = extname(file).toLowerCase()
+  const title = options.title?.trim() || basename(file, extname(file))
+  const mode: MediaMode = options.mode ?? 'auto'
+  const report = progressReporter(options)
+  const warnings: MediaWarning[] = []
+  const scratch = await mkdtemp(join(tmpdir(), 'media-to-md-'))
+  const dependencyVersions: Record<string, string> = { ffmpeg: versions.ffmpeg }
+  if (versions.uvx) dependencyVersions.uvx = versions.uvx
+
+  const externalId = await sha256OfFile(file)
+
+  try {
+    /* ------------------------------ 图片档 ------------------------------ */
+    if (IMAGE_EXTENSIONS.includes(extension)) {
+      report('probing', null, '读取图片')
+      const bytes = await readFile(file)
+      const magic = IMAGE_MAGIC.find(entry => entry.test(bytes))
+      const assetExtension = magic?.extension ?? (extension.replace('.', '') || 'bin')
+      const rel = `assets/image-${createHash('sha1').update(bytes).digest('hex').slice(0, 12)}.${assetExtension}`
+      let ocrText = ''
+      if (options.imageOcr) {
+        report('ocr', null, '本地 OCR')
+        const ocr = await ocrImages([file], options.tools, options.signal)
+        warnings.push(...ocr.warnings)
+        ocrText = (ocr.entries[0]?.text ?? '').trim()
+        warnings.push({ code: 'IMAGE_OCR_ENABLED', message: '已显式开启图片 OCR(imageOcr=true)。' })
+      } else {
+        warnings.push({ code: 'IMAGE_OCR_SKIPPED', message: '未做图片 OCR:图片直接收录、靠多模态召回;如需文字请设 imageOcr=true。' })
+      }
+      const meta: MediaMeta = {
+        sourceFormat: 'image',
+        containerExtension: assetExtension,
+        durationSeconds: 0,
+        sizeBytes: fileInfo.size,
+        hasVideo: false,
+        hasAudio: false,
+        hasSubtitleTrack: false,
+        transcriptSource: 'none',
+      }
+      return {
+        title: title.slice(0, 300),
+        markdown: buildMarkdown({ title, meta, frames: [], cues: [], image: { rel, ocrText } }),
+        assets: [{ rel, data: bytes, ...(magic ? { contentType: magic.contentType } : {}) }],
+        meta,
+        transcript: { source: 'none', cues: [] },
+        warnings,
+        dependencyVersions,
+        externalId,
+      }
+    }
+
+    /* ------------------------------ 音视频档 ------------------------------ */
+    report('probing', 0.05, '探测媒体信息')
+    const probe = await probeMedia(file, options.signal)
+    const sourceFormat: MediaSourceFormat = probe.hasVideo ? 'video' : 'audio'
+
+    let frames: Awaited<ReturnType<typeof extractKeyframes>> = []
+    if (probe.hasVideo) {
+      report('frames', 0.2, mode === 'frames-only' ? '抽取关键帧(只要帧)' : '抽取关键帧')
+      frames = await extractKeyframes(file, probe.durationSeconds, scratch, options.frames ?? {}, options.signal)
+    }
+    if (frames.length > 0) {
+      warnings.push({ code: 'KEYFRAMES_EXTRACTED', message: `已抽出 ${frames.length} 个关键帧并落地为 assets/。` })
+    }
+
+    let frameOcr = new Map<string, string>()
+    if (options.ocrFrames && frames.length > 0) {
+      report('ocr', 0.35, '关键帧画面文字 OCR')
+      // OCR 读的是落盘的真实路径(scratch 下),结果再按顺序映射回 rel。
+      const ocr = await ocrImages(frames.map(frame => frame.sourcePath), options.tools, options.signal)
+      warnings.push(...ocr.warnings)
+      const bySourcePath = new Map(ocr.entries.map(entry => [entry.path, entry.text.trim()]))
+      frameOcr = new Map(
+        frames
+          .map(frame => [frame.rel, bySourcePath.get(frame.sourcePath) ?? ''] as const)
+          .filter(([, text]) => text.length > 0),
+      )
+    }
+
+    let cues: MediaToMarkdownResult['transcript']['cues'] = []
+    let transcriptSource: MediaToMarkdownResult['transcript']['source'] = 'none'
+
+    if (mode !== 'frames-only') {
+      report('subtitles', 0.45, '查找字幕轨')
+      const subtitleText = await extractSubtitles(file, probe, scratch, options.signal)
+      if (subtitleText) {
+        cues = parseSrt(subtitleText)
+        transcriptSource = 'subtitle'
+        warnings.push({ code: 'SUBTITLE_USED', message: `使用字幕轨/旁挂字幕(${cues.length} 条),未下载任何转写模型。` })
+      } else if (!probe.hasAudio) {
+        warnings.push({ code: 'NO_AUDIO_TRACK', message: '该文件没有音频轨,也没有字幕。' })
+      } else if (mode === 'subtitle-only') {
+        warnings.push({ code: 'SUBTITLE_MISSING', message: '没有可用字幕;subtitle-only 档不做转写。' })
+      } else {
+        const asr = options.asr ?? {}
+        const model = asr.model?.trim() || 'small'
+        const mayDownload = asr.allowModelDownload === true || isLocalModelPath(model)
+        if (mode === 'auto' && !mayDownload) {
+          throw new MediaToMarkdownError(
+            'ASR_MODEL_REQUIRED',
+            `无字幕,转写需要下载本地 whisper 模型(${model},${describeModel(model)});当前未允许下载,已放弃转换。`,
+            '确认后设 allowModelDownload=true 重试;中文建议 model=large-v3-turbo、language=zh。也可以先用 ffmpeg 抽字幕轨,或改用带字幕的来源。',
+          )
+        }
+        report('transcribing', 0.6, '本地转写(首次会下载模型)')
+        const audio = join(scratch, 'audio-16k.wav')
+        await runFfmpeg(['-hide_banner', '-loglevel', 'error', '-y', '-i', file, '-vn', '-ac', '1', '-ar', '16000', '-c:a', 'pcm_s16le', audio])
+        const result = await transcribe(audio, scratch, asr, options.tools, options.signal)
+        cues = result.cues
+        transcriptSource = cues.length > 0 ? 'transcription' : 'none'
+        warnings.push({
+          code: 'ASR_LOCAL',
+          message: `无字幕,已用本地 faster-whisper(${result.model},语言 ${result.language ?? 'auto'})转写;音频未离开本机。`,
+        })
+      }
+    }
+
+    report('assembling', 0.9, '装配 Markdown')
+    const meta = {
+      sourceFormat,
+      containerExtension: extension.replace('.', ''),
+      durationSeconds: probe.durationSeconds,
+      sizeBytes: probe.sizeBytes,
+      ...(probe.width ? { width: probe.width } : {}),
+      ...(probe.height ? { height: probe.height } : {}),
+      ...(probe.fps ? { fps: probe.fps } : {}),
+      ...(probe.videoCodec ? { videoCodec: probe.videoCodec } : {}),
+      ...(probe.audioCodec ? { audioCodec: probe.audioCodec } : {}),
+      hasVideo: probe.hasVideo,
+      hasAudio: probe.hasAudio,
+      hasSubtitleTrack: probe.hasSubtitleTrack,
+      transcriptSource,
+    }
+    return {
+      title: title.slice(0, 300),
+      markdown: buildMarkdown({ title, meta, frames, cues, frameOcr }),
+      assets: frames.map(frame => ({ rel: frame.rel, data: frame.data, contentType: 'image/jpeg' })),
+      meta,
+      transcript: { source: transcriptSource, cues },
+      warnings,
+      dependencyVersions,
+      externalId,
+    }
+  } finally {
+    if (!options.keepScratch) await rm(scratch, { recursive: true, force: true }).catch(() => undefined)
+  }
+}
+
+/** 模型名看着像路径(本地目录)时不视为需要下载。 */
+function isLocalModelPath(model: string): boolean {
+  return model.includes('/') || model.startsWith('.') || model.startsWith('~')
+}

package/src/media/index.ts

@@ -0,0 +1,43 @@
+/**
+ * media-to-md —— 本地音视频 / 图片 → Markdown + 本地图片。
+ *
+ * 纯本地:不调用云端 API、不调用大模型。两个专用小模型(whisper 语音识别、RapidOCR
+ * 画面文字)都是可选档位,是否允许下载由调用方显式决定。
+ *
+ * ```ts
+ * import { convertMedia } from 'dsh-convert-core/media'
+ *
+ * const result = await convertMedia({
+ *   file: '/abs/path/clip.mp4',
+ *   mode: 'auto',
+ *   asr: { model: 'large-v3-turbo', language: 'zh', allowModelDownload: true },
+ *   frames: { samples: 12, maxFrames: 40, sceneThreshold: 0.3 },
+ *   onProgress: p => console.log(p.stage, p.progress),
+ * })
+ * // result.markdown / result.assets / result.warnings / result.meta
+ * ```
+ */
+
+export { convertMedia, MEDIA_EXTENSIONS, VIDEO_EXTENSIONS, AUDIO_EXTENSIONS, IMAGE_EXTENSIONS } from './convert.js'
+export { convertScannedDocument } from './scanned.js'
+export { probeTools, FFMPEG_HINT, UVX_HINT, type ToolVersions } from './binaries.js'
+export { probeMedia, extractKeyframes, extractSubtitles, parseSrt, type MediaProbe, type ExtractedFrame } from './media.js'
+export { transcribe, ocrImages, ASR_MODEL_SIZES, describeModel, type TranscriptionResult, type OcrEntry } from './models.js'
+export { buildMarkdown, buildScannedMarkdown, formatClock, type BuildMarkdownInput, type BuildScannedMarkdownInput } from './markdown.js'
+export {
+  MediaToMarkdownError,
+  type MediaAsset,
+  type MediaAsrOptions,
+  type MediaCue,
+  type MediaFrameOptions,
+  type MediaMeta,
+  type MediaMode,
+  type MediaSourceFormat,
+  type MediaToMarkdownOptions,
+  type MediaToMarkdownProgress,
+  type MediaToMarkdownResult,
+  type MediaToolOptions,
+  type MediaWarning,
+  type ScannedPage,
+  type ScannedPdfOptions,
+} from './types.js'

package/src/media/markdown.ts

@@ -0,0 +1,105 @@
+/**
+ * Markdown 装配 —— 纯模板,零模型、零网络。
+ *
+ * 产物只返回**正文**:front matter 是宿主的契约(转换内核自己写,CLI 自己写),
+ * 这个包不该替宿主决定 front matter 字段。
+ */
+
+import type { ExtractedFrame } from './media.js'
+import type { MediaCue, MediaMeta } from './types.js'
+
+export function formatClock(seconds: number): string {
+  const total = Math.max(0, Math.floor(seconds))
+  const hours = Math.floor(total / 3600)
+  const minutes = Math.floor((total % 3600) / 60)
+  const secs = total % 60
+  const mm = String(minutes).padStart(2, '0')
+  const ss = String(secs).padStart(2, '0')
+  return hours > 0 ? `${String(hours).padStart(2, '0')}:${mm}:${ss}` : `${mm}:${ss}`
+}
+
+export interface BuildMarkdownInput {
+  title: string
+  meta: MediaMeta
+  frames: ExtractedFrame[]
+  cues: MediaCue[]
+  /** 关键帧 rel → 画面文字(仅在开启帧 OCR 时非空)。 */
+  frameOcr?: Map<string, string>
+  /** 图片输入的资产与文字。 */
+  image?: { rel: string; ocrText: string }
+}
+
+export function buildMarkdown(input: BuildMarkdownInput): string {
+  const { title, meta, frames, cues, image } = input
+  const frameOcr = input.frameOcr ?? new Map<string, string>()
+  const lines: string[] = [`# ${title}`, '']
+
+  const facts = [
+    meta.durationSeconds > 0 ? `时长 ${formatClock(meta.durationSeconds)}` : null,
+    meta.width && meta.height ? `${meta.width}×${meta.height}` : null,
+    meta.videoCodec ?? null,
+    meta.audioCodec ? `音频 ${meta.audioCodec}` : null,
+  ].filter((value): value is string => value !== null)
+  if (facts.length > 0) lines.push(`> ${facts.join(' · ')}`, '')
+
+  if (image) {
+    lines.push(`![${title}](${image.rel})`, '')
+    if (image.ocrText) lines.push('## 画面文字', '', image.ocrText, '')
+    else lines.push('_图片已原样收录(未做 OCR);以多模态方式参与召回。_', '')
+  }
+
+  if (frames.length > 0) {
+    lines.push('## 时间轴', '')
+    for (const [index, frame] of frames.entries()) {
+      const start = frame.seconds
+      const end = index + 1 < frames.length ? frames[index + 1]!.seconds : Number.POSITIVE_INFINITY
+      lines.push(`### ${formatClock(start)}`, '', `![${formatClock(start)}](${frame.rel})`, '')
+      const ocr = frameOcr.get(frame.rel)
+      if (ocr) lines.push('**画面文字**', '', ocr, '')
+      const inWindow = cues.filter(cue => cue.seconds >= start - 0.01 && cue.seconds < end)
+      for (const cue of inWindow) lines.push(`- \`${formatClock(cue.seconds)}\` ${cue.text}`)
+      if (inWindow.length > 0) lines.push('')
+    }
+  }
+
+  if (!image) {
+    lines.push('## 逐字稿', '')
+    if (cues.length === 0) {
+      lines.push(meta.transcriptSource === 'none' ? '_没有字幕轨,也未开启本地转写。_' : '_未识别到可用语音内容。_', '')
+    } else {
+      for (const cue of cues) lines.push(`- \`${formatClock(cue.seconds)}\` ${cue.text}`)
+      lines.push('')
+    }
+  }
+  return lines.join('\n')
+}
+
+export interface BuildScannedMarkdownInput {
+  title: string
+  totalPages: number
+  pageImages: boolean
+  pages: Array<{ index: number; rel: string; text: string }>
+}
+
+/**
+ * 扫描档的 Markdown:逐页一节,页内先图后文。
+ *
+ * 不承诺版面顺序与表格结构 —— 这一档只负责"把图片页里的字读出来"。
+ */
+export function buildScannedMarkdown(input: BuildScannedMarkdownInput): string {
+  const { title, totalPages, pageImages, pages } = input
+  const lines: string[] = [`# ${title}`, '']
+  const facts = [`共 ${totalPages} 页`, `已识别 ${pages.length} 页`, '本地 OCR(轻量档,无版面还原)']
+  lines.push(`> ${facts.join(' · ')}`, '')
+  if (pages.length === 0) {
+    lines.push('_没有可识别的页面。_', '')
+    return lines.join('\n')
+  }
+  for (const page of pages) {
+    lines.push(`## 第 ${page.index} 页`, '')
+    if (pageImages) lines.push(`![第 ${page.index} 页](${page.rel})`, '')
+    if (page.text.trim()) lines.push(page.text.trim(), '')
+    else lines.push('_本页未识别到文字。_', '')
+  }
+  return lines.join('\n')
+}

package/src/media/media.ts

@@ -0,0 +1,204 @@
+/**
+ * 媒体探测、关键帧与字幕 —— 全部走 ffmpeg/ffprobe,不含任何模型。
+ */
+
+import { execFile } from 'node:child_process'
+import { mkdir, readdir, readFile } from 'node:fs/promises'
+import { basename, dirname, extname, join } from 'node:path'
+import { promisify } from 'node:util'
+import { MediaToMarkdownError, type MediaCue, type MediaFrameOptions } from './types.js'
+import { runFfmpeg } from './binaries.js'
+
+const execFileAsync = promisify(execFile)
+
+export interface MediaStream {
+  codec_type?: string
+  codec_name?: string
+  width?: number
+  height?: number
+  r_frame_rate?: string
+}
+
+export interface MediaProbe {
+  durationSeconds: number
+  sizeBytes: number
+  hasVideo: boolean
+  hasAudio: boolean
+  hasSubtitleTrack: boolean
+  width?: number
+  height?: number
+  fps?: number
+  videoCodec?: string
+  audioCodec?: string
+}
+
+export async function probeMedia(file: string, signal?: AbortSignal): Promise<MediaProbe> {
+  let stdout: string
+  try {
+    ({ stdout } = await execFileAsync('ffprobe', [
+      '-v', 'error', '-print_format', 'json', '-show_format', '-show_streams', file,
+    ], { maxBuffer: 32 * 1024 * 1024, ...(signal ? { signal } : {}) }))
+  } catch (cause) {
+    throw new MediaToMarkdownError(
+      'MEDIA_UNREADABLE',
+      `ffprobe 无法读取该文件:${cause instanceof Error ? cause.message : String(cause)}`,
+    )
+  }
+  const parsed = JSON.parse(stdout) as { format?: { duration?: string; size?: string }; streams?: MediaStream[] }
+  const streams = parsed.streams ?? []
+  const video = streams.find(stream => stream.codec_type === 'video')
+  const audio = streams.find(stream => stream.codec_type === 'audio')
+  const subtitle = streams.find(stream => stream.codec_type === 'subtitle')
+  const rate = video?.r_frame_rate?.split('/')
+  const fps = rate && Number(rate[1]) > 0 ? Number(rate[0]) / Number(rate[1]) : undefined
+  return {
+    durationSeconds: Number(parsed.format?.duration ?? 0),
+    sizeBytes: Number(parsed.format?.size ?? 0),
+    hasVideo: video !== undefined,
+    hasAudio: audio !== undefined,
+    hasSubtitleTrack: subtitle !== undefined,
+    ...(video?.width ? { width: video.width } : {}),
+    ...(video?.height ? { height: video.height } : {}),
+    ...(fps !== undefined && Number.isFinite(fps) ? { fps: Number(fps.toFixed(2)) } : {}),
+    ...(video?.codec_name ? { videoCodec: video.codec_name } : {}),
+    ...(audio?.codec_name ? { audioCodec: audio.codec_name } : {}),
+  }
+}
+
+export interface ExtractedFrame {
+  /** 产物内相对路径(含 `assets/` 前缀),写进 Markdown 用。 */
+  rel: string
+  /** 落盘的真实路径(scratch 下),给 OCR 之类的后续步骤用。 */
+  sourcePath: string
+  data: Buffer
+  seconds: number
+}
+
+async function readdirSafe(dir: string): Promise<string[]> {
+  try {
+    return await readdir(dir)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 均匀采样 + 场景变化两路合并,再按内容 sha1 去重。
+ *
+ * 只靠 `scene` 检测会漏内容:口播/图文类视频几乎没有硬切,阈值再低也可能只出 1 帧
+ * (实测:一个 3 段画面的测试视频,阈值降到 0.1 仍然只有 1 帧)。只靠均匀采样又会漏掉
+ * 真正的画面切换。两路都跑,按时间排序、近邻合并、内容去重。
+ */
+export async function extractKeyframes(
+  file: string,
+  durationSeconds: number,
+  scratch: string,
+  options: MediaFrameOptions = {},
+  signal?: AbortSignal,
+): Promise<ExtractedFrame[]> {
+  const samples = Math.max(1, options.samples ?? 12)
+  const maxFrames = Math.max(1, options.maxFrames ?? 40)
+  const scene = clamp01(options.sceneThreshold ?? 0.3)
+  const raw = join(scratch, 'raw')
+  await mkdir(join(raw, 'scene'), { recursive: true })
+
+  const count = Math.max(1, Math.min(samples, maxFrames))
+  const step = durationSeconds > 0 ? Math.max(durationSeconds / count, 0.5) : 1
+  await runFfmpeg([
+    '-hide_banner', '-loglevel', 'error', '-i', file,
+    '-vf', `fps=1/${step.toFixed(3)}`, '-frames:v', String(count), '-q:v', '3',
+    join(raw, 'even-%04d.jpg'),
+  ], { allowFailure: true })
+
+  const sceneRun = await runFfmpeg([
+    '-hide_banner', '-loglevel', 'info', '-i', file,
+    '-vf', `select='gt(scene\\,${scene})',showinfo`, '-fps_mode', 'vfr',
+    '-frames:v', String(maxFrames), '-q:v', '3',
+    join(raw, 'scene', 'scene-%04d.jpg'),
+  ], { allowFailure: true })
+  const sceneTimes = [...(sceneRun.stderr ?? '').matchAll(/pts_time:([0-9.]+)/g)].map(match => Number(match[1]))
+
+  const evenFrames = (await readdirSafe(raw)).filter(name => name.startsWith('even-')).sort()
+    .map((name, index) => ({ seconds: Number((index * step).toFixed(3)), path: join(raw, name) }))
+  const sceneFrames = (await readdirSafe(join(raw, 'scene'))).filter(name => name.startsWith('scene-')).sort()
+    .map((name, index) => ({
+      seconds: Number.isFinite(sceneTimes[index]) ? Number(sceneTimes[index]) : 0,
+      path: join(raw, 'scene', name),
+    }))
+
+  const picked: Array<{ seconds: number; path: string }> = []
+  for (const candidate of [...sceneFrames, ...evenFrames].sort((a, b) => a.seconds - b.seconds)) {
+    if (picked.length >= maxFrames) break
+    if (picked.some(kept => Math.abs(kept.seconds - candidate.seconds) < 0.75)) continue
+    picked.push(candidate)
+  }
+
+  const { createHash } = await import('node:crypto')
+  const frames: ExtractedFrame[] = []
+  const seen = new Set<string>()
+  for (const item of picked) {
+    if (signal?.aborted) throw new MediaToMarkdownError('ABORTED', '已取消。')
+    const data = await readFile(item.path)
+    // 静止画面会被采样多次,按内容去重,别让 assets/ 里塞满一模一样的帧。
+    const digest = createHash('sha1').update(data).digest('hex')
+    if (seen.has(digest)) continue
+    seen.add(digest)
+    frames.push({
+      rel: `assets/frame-${String(frames.length + 1).padStart(4, '0')}.jpg`,
+      sourcePath: item.path,
+      data,
+      seconds: item.seconds,
+    })
+  }
+  return frames
+}
+
+/** 内嵌字幕轨优先,没有再看同名旁挂 `.srt`。 */
+export async function extractSubtitles(file: string, probe: MediaProbe, scratch: string, signal?: AbortSignal): Promise<string | undefined> {
+  if (probe.hasSubtitleTrack) {
+    const target = join(scratch, 'subs.srt')
+    try {
+      await execFileAsync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', '-i', file, '-map', '0:s:0', target], { signal })
+      const text = await readFile(target, 'utf8')
+      if (text.trim()) return text
+    } catch {
+      /* 抽轨失败就退到旁挂字幕 */
+    }
+  }
+  const sidecar = join(dirname(file), `${basename(file, extname(file))}.srt`)
+  try {
+    const text = await readFile(sidecar, 'utf8')
+    if (text.trim()) return text
+  } catch {
+    /* 没有旁挂字幕 */
+  }
+  return undefined
+}
+
+/** 极简 SRT 解析:取起止时间与文本,顺带去掉自动字幕常见的滚动重复行。 */
+export function parseSrt(source: string): MediaCue[] {
+  const cues: MediaCue[] = []
+  const range = /(\d{1,2}):(\d{2}):(\d{2})[,.](\d{1,3})\s*-->\s*(\d{1,2}):(\d{2}):(\d{2})[,.](\d{1,3})/
+  const toSeconds = (h: string, m: string, s: string, ms: string): number =>
+    Number(h) * 3600 + Number(m) * 60 + Number(s) + Number(ms.padEnd(3, '0')) / 1000
+  for (const block of source.replace(/\r/g, '').split(/\n{2,}/)) {
+    const lines = block.split('\n').map(line => line.trim()).filter(Boolean)
+    if (lines.length === 0) continue
+    const timeLine = lines.find(line => line.includes('-->'))
+    if (!timeLine) continue
+    const match = range.exec(timeLine)
+    const text = lines.filter(line => line !== timeLine && !/^\d+$/.test(line)).join(' ').trim()
+    if (!match || !text) continue
+    const seconds = toSeconds(match[1]!, match[2]!, match[3]!, match[4]!)
+    const endSeconds = toSeconds(match[5]!, match[6]!, match[7]!, match[8]!)
+    const previous = cues[cues.length - 1]
+    if (previous && previous.text === text) continue
+    cues.push({ seconds, endSeconds, text })
+  }
+  return cues
+}
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value)) return 0.3
+  return Math.min(1, Math.max(0, value))
+}