@xiping/node-utils 1.0.70 → 1.0.77

package/README.md

@@ -6,6 +6,21 @@ Node.js 通用工具库，提供目录树、路径、SRT→VTT 字幕转换、FF
 npm install @xiping/node-utils
 ```
 
+## 命令行
+
+包内提供可执行命令（需本机已安装 Node；部分命令依赖 FFmpeg，见各模块说明）：
+
+| 命令 | 说明 |
+|------|------|
+| `video-thumbnail` | 为视频生成多帧合成缩略图（见 [src/ffmpeg/README.md](./src/ffmpeg/README.md) 中「缩略图生成」与「命令行」） |
+| `translate-srt` | 字幕翻译教学相关 CLI（见 [src/subtitle-translation-teaching/README.md](./src/subtitle-translation-teaching/README.md)） |
+
+**示例（临时执行、未安装依赖）：**
+
+```bash
+npx -p @xiping/node-utils@latest video-thumbnail --input /path/to/video.mp4
+```
+
 ## 使用案例
 
 ```typescript

package/bin/translate-srt

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = join(__dirname, '..');
+
+spawn('npx', ['tsx', join(rootDir, 'src/subtitle-translation-teaching/src/cli.ts'), ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  shell: true,
+});

package/bin/video-thumbnail

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../lib/src/ffmpeg/cli-thumbnail.js";

package/lib/index.d.ts

@@ -4,3 +4,6 @@ export * from "./src/srt-to-vtt/index.js";
 export * from "./src/ffmpeg/index.js";
 export * from "./src/file/getFileConfig.js";
 export * from "./src/image/index.js";
+export { translateSubtitle } from "./src/subtitle-translation-teaching/src/translator/translate.js";
+export type { TranslateOptions } from "./src/subtitle-translation-teaching/src/translator/translate.js";
+export type { TeachingResult, GrammarAnalysis, VocabularyItem, PhraseItem, WordFrequencyItem, RelatedPattern, UsageExample, } from "./src/subtitle-translation-teaching/src/types.js";

package/lib/index.js

@@ -10,3 +10,5 @@ export * from "./src/ffmpeg/index.js";
 export * from "./src/file/getFileConfig.js";
 // 图片处理相关功能
 export * from "./src/image/index.js";
+// 字幕翻译教学功能
+export { translateSubtitle } from "./src/subtitle-translation-teaching/src/translator/translate.js";

package/lib/src/ffmpeg/README.md

@@ -140,6 +140,27 @@ console.log(result.outputPath);
 console.log(result.metadata);
 ```
 
+### 命令行（`video-thumbnail`）
+
+安装 `@xiping/node-utils` 后可用 `video-thumbnail`，与上方 API 选项对应（见 `--help`）。
+
+**未在项目中安装依赖、临时在一台机器上执行：**
+
+```bash
+npx -p @xiping/node-utils@latest video-thumbnail --input /path/to/video.mp4
+```
+
+（包名是 `@xiping/node-utils`，命令名是 `video-thumbnail`，临时拉包时需用 `-p` 指定包名。）
+
+**已全局安装**（之后可省略 `npx` 与 `-p`）：
+
+```bash
+npm i -g @xiping/node-utils
+video-thumbnail --input /path/to/video.mp4
+```
+
+**当前项目已依赖本包** 时，可直接 `npx video-thumbnail --input ...`，无需 `-p`。
+
 ### 进度回调
 
 ```typescript

package/lib/src/ffmpeg/cli-thumbnail.d.ts

@@ -0,0 +1 @@
+export declare function runCli(args: string[]): Promise<void>;

package/lib/src/ffmpeg/cli-thumbnail.js

@@ -0,0 +1,130 @@
+import path from "node:path";
+import { getThumbnail } from "./getThumbnail.js";
+function printHelp() {
+    console.log(`Usage: video-thumbnail --input <video> [options]
+
+Options:
+  -i, --input <path>       Video file path (required)
+  --frames <n>             Frame count for composition (default: 60)
+  --output-width <n>       Output width in pixels (default: 3840)
+  --columns <n>            Grid columns (default: 4)
+  --output-name <name>     Output filename, e.g. thumbnail.avif (default: thumbnail.avif)
+  --quality <1-100>        Output quality (default: 80)
+  --format <fmt>           avif | webp | jpeg | png (default: avif)
+  --batch-size <n>         Batch size (default: 10)
+  --max-concurrency <n>    Max concurrency (default: 4)
+  --temp-dir <path>        Custom temp directory
+  -h, --help               Show this help
+`);
+}
+function parseArgs(args) {
+    const options = { input: "" };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--input" || arg === "-i") {
+            options.input = args[++i] ?? "";
+        }
+        else if (arg === "--frames") {
+            options.frames = parseInt(args[++i] ?? "", 10);
+        }
+        else if (arg === "--output-width") {
+            options.outputWidth = parseInt(args[++i] ?? "", 10);
+        }
+        else if (arg === "--columns") {
+            options.columns = parseInt(args[++i] ?? "", 10);
+        }
+        else if (arg === "--output-name") {
+            options.outputFileName = args[++i] ?? "";
+        }
+        else if (arg === "--quality") {
+            options.quality = parseInt(args[++i] ?? "", 10);
+        }
+        else if (arg === "--format") {
+            const f = args[++i] ?? "";
+            if (f === "avif" || f === "webp" || f === "jpeg" || f === "png") {
+                options.format = f;
+            }
+            else {
+                console.error(`Error: --format must be avif, webp, jpeg, or png, got: ${f}`);
+                process.exit(1);
+            }
+        }
+        else if (arg === "--batch-size") {
+            options.batchSize = parseInt(args[++i] ?? "", 10);
+        }
+        else if (arg === "--max-concurrency") {
+            options.maxConcurrency = parseInt(args[++i] ?? "", 10);
+        }
+        else if (arg === "--temp-dir") {
+            options.tempDir = args[++i] ?? "";
+        }
+        else if (arg === "--help" || arg === "-h") {
+            options.help = true;
+        }
+    }
+    return options;
+}
+function buildThumbnailOptions(opts) {
+    const out = {
+        onProgress: (p) => {
+            const line = `[${p.phase}] ${p.percent}%${p.message ? ` ${p.message}` : ""}`;
+            console.error(line);
+        },
+    };
+    if (opts.frames !== undefined && !Number.isNaN(opts.frames)) {
+        out.frames = opts.frames;
+    }
+    if (opts.outputWidth !== undefined && !Number.isNaN(opts.outputWidth)) {
+        out.outputWidth = opts.outputWidth;
+    }
+    if (opts.columns !== undefined && !Number.isNaN(opts.columns)) {
+        out.columns = opts.columns;
+    }
+    if (opts.outputFileName) {
+        out.outputFileName = opts.outputFileName;
+    }
+    if (opts.quality !== undefined && !Number.isNaN(opts.quality)) {
+        out.quality = opts.quality;
+    }
+    if (opts.format) {
+        out.format = opts.format;
+    }
+    if (opts.batchSize !== undefined && !Number.isNaN(opts.batchSize)) {
+        out.batchSize = opts.batchSize;
+    }
+    if (opts.maxConcurrency !== undefined && !Number.isNaN(opts.maxConcurrency)) {
+        out.maxConcurrency = opts.maxConcurrency;
+    }
+    if (opts.tempDir) {
+        out.tempDir = path.resolve(opts.tempDir);
+    }
+    return out;
+}
+export async function runCli(args) {
+    const opts = parseArgs(args);
+    if (opts.help) {
+        printHelp();
+        return;
+    }
+    if (!opts.input) {
+        console.error("Error: --input is required");
+        printHelp();
+        process.exit(1);
+    }
+    const videoPath = path.resolve(process.cwd(), opts.input);
+    const thumbnailOpts = buildThumbnailOptions(opts);
+    try {
+        const result = await getThumbnail(videoPath, thumbnailOpts);
+        console.log(result.outputPath);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+}
+const argv = process.argv.slice(2);
+runCli(argv).catch((e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+});

package/lib/src/subtitle-translation-teaching/src/parser/srt.d.ts

@@ -0,0 +1,16 @@
+export interface SubtitleBlock {
+    index: number;
+    startTime: string;
+    endTime: string;
+    text: string;
+}
+export interface ParsedSubtitle {
+    index: number;
+    startTime: string;
+    endTime: string;
+    text: string;
+    /** 原始文本行（保留换行） */
+    rawText: string;
+}
+export declare function parseSRT(content: string): ParsedSubtitle[];
+export declare function formatSRTTime(seconds: number): string;

package/lib/src/subtitle-translation-teaching/src/parser/srt.js

@@ -0,0 +1,27 @@
+export function parseSRT(content) {
+    const blocks = [];
+    // 分割字幕块：数字 + 时间 + 文本
+    const regex = /(\d+)\s*\n(\d{2}:\d{2}:\d{2},\d{3})\s*-->\s*(\d{2}:\d{2}:\d{2},\d{3})\s*\n([\s\S]*?)(?=\n\n\d+\s*\n|$)/g;
+    let match;
+    while ((match = regex.exec(content + '\n\n')) !== null) {
+        const [, indexStr, startTime, endTime, text] = match;
+        blocks.push({
+            index: parseInt(indexStr, 10),
+            startTime,
+            endTime,
+            text: text.trim().replace(/\n/g, ' '),
+            rawText: text.trim(),
+        });
+    }
+    return blocks;
+}
+export function formatSRTTime(seconds) {
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    const s = Math.floor(seconds % 60);
+    const ms = Math.floor((seconds % 1) * 1000);
+    return `${pad(h)}:${pad(m)}:${pad(s)},${pad(ms, 3)}`;
+}
+function pad(n, len = 2) {
+    return n.toString().padStart(len, '0');
+}

package/lib/src/subtitle-translation-teaching/src/translator/adapter.d.ts

@@ -0,0 +1,18 @@
+import type { VocabularyItem, PhraseItem, WordFrequencyItem, RelatedPattern, UsageExample } from '../types.js';
+export interface LLMAdapter {
+    analyze(text: string): Promise<{
+        translation: string;
+        difficulty: string;
+        tone: string;
+        phonetics: string;
+        grammar: string;
+        vocabulary: VocabularyItem[];
+        phrases: PhraseItem[];
+        culture: string;
+        wordFrequency: WordFrequencyItem[];
+        relatedPatterns: RelatedPattern[];
+        usageExamples: UsageExample[];
+        mistakeWarnings: string[];
+    }>;
+}
+export declare function createMiMoAdapter(apiKey: string): LLMAdapter;

package/lib/src/subtitle-translation-teaching/src/translator/adapter.js

@@ -0,0 +1,103 @@
+import OpenAI from 'openai';
+export function createMiMoAdapter(apiKey) {
+    const client = new OpenAI({
+        apiKey,
+        baseURL: 'https://api.xiaomimimo.com/v1',
+        dangerouslyAllowBrowser: false,
+    });
+    return new MiMoAdapter(client);
+}
+class MiMoAdapter {
+    constructor(client) {
+        this.client = client;
+        this.model = 'mimo-v2-pro';
+    }
+    async analyze(text) {
+        const prompt = `你是一位专业的英语教师。请分析下面的英文句子，给出详细的教学分解。
+
+英文句子：${text}
+
+请以JSON格式输出，包含以下所有字段：
+- translation: 中文翻译
+- difficulty: CEFR难度等级 (A1/A2/B1/B2/C1/C2)
+- tone: 语气情感 (friendly/neutral/formal/informal/aggressive 等)
+- phonetics: 句子音标 (IPA格式，如 /həˈloʊ/)
+- grammar: 语法分析（句子结构、时态、语态、从句等）
+- vocabulary: 重点词汇列表，每项包含 word（单词）、phonetic（音标，可选）、partOfSpeech（词性）和 meaning（中文释义）
+- phrases: 短语/习语列表，每项包含 phrase（短语）、meaning（中文释义）和 example（例句，可选）
+- culture: 文化背景注释（如果没有可以为空字符串）
+- wordFrequency: 词频信息，每项包含 word（单词）、level（CEFR等级）和 frequency（出现频率描述）
+- relatedPatterns: 相关句型变换，每项包含 pattern（英文句型）和 translation（中文翻译）
+- usageExamples: 用法例句，每项包含 sentence（英文例句）和 translation（中文翻译）
+- mistakeWarnings: 中国人易错点提示（字符串数组，如果没有可以为空数组）
+
+只输出JSON，不要有其他文字。`;
+        const response = await this.client.chat.completions.create({
+            model: this.model,
+            messages: [
+                {
+                    role: 'system',
+                    content: 'You are a professional English teacher. Output ONLY a JSON object with these exact fields: translation, difficulty, tone, phonetics, grammar, vocabulary (array of {word, phonetic, partOfSpeech, meaning}), phrases (array of {phrase, meaning, example}), culture, wordFrequency (array of {word, level, frequency}), relatedPatterns (array of {pattern, translation}), usageExamples (array of {sentence, translation}), mistakeWarnings (array of strings). No other text.',
+                },
+                { role: 'user', content: prompt },
+            ],
+            max_completion_tokens: 4096,
+            temperature: 0.5,
+        });
+        const content = response.choices[0]?.message?.content?.trim() ?? '{}';
+        try {
+            const jsonStr = content.replace(/^```json\n?|```$/g, '');
+            const result = JSON.parse(jsonStr);
+            // 确保所有字段存在并有默认值
+            return {
+                translation: result.translation ?? '',
+                difficulty: result.difficulty ?? 'B1',
+                tone: result.tone ?? 'neutral',
+                phonetics: result.phonetics ?? '',
+                grammar: result.grammar ?? '解析失败',
+                vocabulary: (result.vocabulary ?? []).map((v) => ({
+                    word: v.word ?? '',
+                    phonetic: v.phonetic ?? '',
+                    partOfSpeech: v.partOfSpeech ?? 'unknown',
+                    meaning: v.meaning ?? '',
+                })),
+                phrases: (result.phrases ?? []).map((p) => ({
+                    phrase: p.phrase ?? '',
+                    meaning: p.meaning ?? '',
+                    example: p.example ?? '',
+                })),
+                culture: result.culture ?? '',
+                wordFrequency: (result.wordFrequency ?? []).map((w) => ({
+                    word: w.word ?? '',
+                    level: w.level ?? 'B1',
+                    frequency: w.frequency ?? 'common',
+                })),
+                relatedPatterns: (result.relatedPatterns ?? []).map((r) => ({
+                    pattern: r.pattern ?? '',
+                    translation: r.translation ?? '',
+                })),
+                usageExamples: (result.usageExamples ?? []).map((u) => ({
+                    sentence: u.sentence ?? '',
+                    translation: u.translation ?? '',
+                })),
+                mistakeWarnings: result.mistakeWarnings ?? [],
+            };
+        }
+        catch {
+            return {
+                translation: '',
+                difficulty: 'B1',
+                tone: 'neutral',
+                phonetics: '',
+                grammar: '解析失败',
+                vocabulary: [],
+                phrases: [],
+                culture: '',
+                wordFrequency: [],
+                relatedPatterns: [],
+                usageExamples: [],
+                mistakeWarnings: [],
+            };
+        }
+    }
+}

package/lib/src/subtitle-translation-teaching/src/translator/translate.d.ts

@@ -0,0 +1,7 @@
+import { TranslateResult } from '../types.js';
+export interface TranslateOptions {
+    apiKey: string;
+    batchSize?: number;
+    delayMs?: number;
+}
+export declare function translateSubtitle(filePath: string, options: TranslateOptions): Promise<TranslateResult>;

package/lib/src/subtitle-translation-teaching/src/translator/translate.js

@@ -0,0 +1,88 @@
+import { parseSRT } from '../parser/srt.js';
+import { createMiMoAdapter } from './adapter.js';
+import { readFile } from 'fs/promises';
+export async function translateSubtitle(filePath, options) {
+    const content = await readFile(filePath, 'utf-8');
+    const subtitles = parseSRT(content);
+    const adapter = createMiMoAdapter(options.apiKey);
+    const results = [];
+    let errorCount = 0;
+    const batchSize = options.batchSize ?? 5;
+    const delayMs = options.delayMs ?? 500;
+    for (let i = 0; i < subtitles.length; i += batchSize) {
+        const batch = subtitles.slice(i, i + batchSize);
+        const batchResults = await Promise.all(batch.map((sub) => processSubtitle(sub, adapter)));
+        for (const result of batchResults) {
+            if (result) {
+                results.push(result);
+            }
+            else {
+                errorCount++;
+            }
+        }
+        if (i + batchSize < subtitles.length) {
+            await sleep(delayMs);
+        }
+    }
+    return {
+        subtitles: results,
+        model: 'mimo-v2-pro',
+        totalCount: subtitles.length,
+        errorCount,
+    };
+}
+async function processSubtitle(sub, adapter) {
+    try {
+        const analysis = await adapter.analyze(sub.text);
+        return {
+            index: sub.index,
+            startTime: sub.startTime,
+            endTime: sub.endTime,
+            original: sub.text,
+            translation: analysis.translation,
+            difficulty: analysis.difficulty,
+            tone: analysis.tone,
+            phonetics: analysis.phonetics,
+            grammar: {
+                structure: analysis.grammar,
+                tense: detectTense(sub.text),
+            },
+            vocabulary: analysis.vocabulary,
+            phrases: analysis.phrases,
+            culture: analysis.culture || undefined,
+            wordFrequency: analysis.wordFrequency,
+            relatedPatterns: analysis.relatedPatterns,
+            usageExamples: analysis.usageExamples,
+            mistakeWarnings: analysis.mistakeWarnings,
+        };
+    }
+    catch (err) {
+        console.error(`Failed to process subtitle ${sub.index}:`, err);
+        return null;
+    }
+}
+function detectTense(text) {
+    const lower = text.toLowerCase();
+    if (/\bwill\b/.test(lower))
+        return 'Future';
+    if (/\bwould\b/.test(lower))
+        return 'Conditional';
+    if (/\bcan\b/.test(lower))
+        return 'Modal';
+    if (/\bhave had\b/.test(lower))
+        return 'Past Perfect';
+    if (/\bhad\b/.test(lower))
+        return 'Past';
+    if (/\bis\b.*\b-ing\b|\bare\b.*\b-ing\b|\bwas\b.*\b-ing\b/.test(lower))
+        return 'Present Continuous';
+    if (/\bhave\b.*\b-ing\b|\bhas\b.*\b-ing\b/.test(lower))
+        return 'Present Perfect Continuous';
+    if (/\bhave\b|\bhas\b/.test(lower))
+        return 'Present Perfect';
+    if (/\bam\b.*\b-ing\b/.test(lower))
+        return 'Present Continuous';
+    return 'Simple Present';
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/src/subtitle-translation-teaching/src/types.d.ts

@@ -0,0 +1,61 @@
+export interface TeachingResult {
+    index: number;
+    startTime: string;
+    endTime: string;
+    original: string;
+    translation: string;
+    /** CEFR 难度等级: A1, A2, B1, B2, C1, C2 */
+    difficulty: string;
+    /** 语气/情感: friendly, neutral, formal, informal, aggressive */
+    tone: string;
+    /** 句子音标 */
+    phonetics?: string;
+    grammar: GrammarAnalysis;
+    vocabulary: VocabularyItem[];
+    phrases: PhraseItem[];
+    culture?: string;
+    /** 词频信息 */
+    wordFrequency: WordFrequencyItem[];
+    /** 相关句型变换 */
+    relatedPatterns: RelatedPattern[];
+    /** 例句 */
+    usageExamples: UsageExample[];
+    /** 易错点提示 */
+    mistakeWarnings: string[];
+}
+export interface GrammarAnalysis {
+    structure: string;
+    tense: string;
+    voice?: string;
+    clauses?: string[];
+}
+export interface VocabularyItem {
+    word: string;
+    phonetic?: string;
+    partOfSpeech: string;
+    meaning: string;
+}
+export interface PhraseItem {
+    phrase: string;
+    meaning: string;
+    example?: string;
+}
+export interface WordFrequencyItem {
+    word: string;
+    level: string;
+    frequency: string;
+}
+export interface RelatedPattern {
+    pattern: string;
+    translation: string;
+}
+export interface UsageExample {
+    sentence: string;
+    translation: string;
+}
+export interface TranslateResult {
+    subtitles: TeachingResult[];
+    model: string;
+    totalCount: number;
+    errorCount: number;
+}

package/lib/src/subtitle-translation-teaching/src/types.js

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

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "@xiping/node-utils",
-  "version": "1.0.70",
+  "version": "1.0.77",
   "description": "node-utils",
   "type": "module",
   "author": "The-End-Hero <527409987@qq.com>",
   "homepage": "https://github.com/The-End-Hero/xiping#readme",
   "license": "MIT",
   "main": "lib/index.js",
+  "bin": {
+    "translate-srt": "./bin/translate-srt",
+    "video-thumbnail": "./bin/video-thumbnail"
+  },
   "directories": {
     "lib": "lib",
     "test": "__tests__"
   },
   "files": [
-    "lib"
+    "lib",
+    "bin"
   ],
   "repository": {
     "type": "git",
@@ -25,7 +30,7 @@
   "bugs": {
     "url": "https://github.com/The-End-Hero/xiping/issues"
   },
-  "gitHead": "61f56a865103626696a6b73c0527c2cb5fc859c1",
+  "gitHead": "53cce3c7a028d237fa19f768d9a392bea054d49a",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -33,6 +38,7 @@
   "dependencies": {
     "@xiping/subtitle": "1.0.52",
     "chalk": "^5.6.2",
+    "openai": "^6.33.0",
     "sharp": "^0.34.5",
     "srt-parser-2": "^1.2.3"
   },