dsh-ffmpeg 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.5.1（2026-10-26）
+
+- 抽帧默认使用每次独立的 run 目录；显式帧序列检查实际文件冲突。输出保护覆盖所有拼接输入、字幕源、符号链接及硬链接别名。
+- Windows 回归 114 项通过、1 项跳过；宿主与未验收范围见[本次记录](docs/validation-0.5.1.md)。
+
+## 0.5.0 (2026-10-15)
+
+- 修复 GIF 的起点和时长选项作用到错误输入，调色板以单帧写入；非零起点也能按指定区间导出。
+- 重编码拼接先统一画布、帧率、像素比例与时间戳，可指定目标宽高和帧率，等比补边。
+- 混合有声/无声素材时只为无声片段补静音，保留其余片段的声音；全无声素材保持无音轨。
+
 ## 0.4.5 (2026-10-05)
 
 - 输入、输出、字幕与抽帧路径按当前 DSH 会话工作区解析，避免宿主启动目录造成找错文件；非法时间参数立即报错。

package/README.en.md

@@ -8,9 +8,12 @@ Use FFmpeg to process existing audio and video files through natural-language re
 
 [![npm](https://img.shields.io/npm/v/dsh-ffmpeg)](https://www.npmjs.com/package/dsh-ffmpeg) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-ffmpeg-downloads.svg)](https://www.npmjs.com/package/dsh-ffmpeg)
 
+Feedback and contributions are welcome: report [issues](https://github.com/STARDUSTLC666/dsh-ffmpeg/issues) or submit [pull requests](https://github.com/STARDUSTLC666/dsh-ffmpeg/pulls).
+
 ## What it does
 
 - Inspect media and trim, join or transcode video.
+- Fit clips with different sizes and frame rates to one canvas; silent clips receive silence without muting the other clips.
 - Add subtitles, create GIFs and extract frames.
 - Execute commands through the host subprocess service.
 

package/README.md

@@ -8,9 +8,12 @@
 
 [![npm](https://img.shields.io/npm/v/dsh-ffmpeg)](https://www.npmjs.com/package/dsh-ffmpeg) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-ffmpeg-downloads.svg)](https://www.npmjs.com/package/dsh-ffmpeg)
 
+欢迎使用，遇到问题或有改进建议，请提交 [issues](https://github.com/STARDUSTLC666/dsh-ffmpeg/issues) 和 [PR](https://github.com/STARDUSTLC666/dsh-ffmpeg/pulls)。
+
 ## 功能
 
 - 探测媒体信息，裁剪、拼接和压制视频。
+- 拼接不同尺寸和帧率的素材时可统一画布并等比补边；无声片段补静音，保留其余原声。
 - 添加字幕、生成 GIF、抽取画面。
 - 通过宿主 subprocess 执行命令。
 

package/docs/USAGE.en.md

@@ -2,6 +2,10 @@
 
 [Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
 
+## Frame output and source protection
+
+Default frame sequences go to a fresh `<input>-frames/run-*/` directory. An explicit pattern needs `overwrite=true` for existing outputs; even then it cannot overwrite any input/subtitle source or its file aliases.
+
 ## Current improvements
 
 Relative paths resolve against the current session workspace. Explicit start / duration values must be valid; invalid values never silently fall back to full-video processing.
@@ -42,7 +46,7 @@ Override the plugin row in your profile's `cordis.patch.yml` (defaults apply whe
 | :-- | :-- | :-- |
 | `ffmpeg_probe` | Probe media info (format/duration/resolution/fps/bitrate/audio/subtitle streams; multi-video files return a full videos list) | `input` required |
 | `ffmpeg_cut` | Cut a clip (stream copy by default, accurate re-encode optional) | `input` required; `start`/`end`/`duration` |
-| `ffmpeg_concat` | Concatenate 2-20 clips (stream copy for identical codecs / re-encode for mixed; video-only when any input has no audio) | `inputs` array required |
+| `ffmpeg_concat` | Join 2-20 clips; re-encoding normalizes size/fps/SAR with letterboxing and fills silent clips while keeping other audio | `inputs` required; with `reencode=true`, optionally set `width` + `height` and `fps` |
 | `ffmpeg_encode` | Transcode with presets (bilibili 1080p/4K, vertical 1080p, web-720p) plus crf/fps/scale overrides | `input` required; `preset` optional |
 | `ffmpeg_subtitle` | Burn subtitles (SRT/ASS hard subs) | `input` + `subtitle` required |
 | `ffmpeg_extract` | Extract audio (m4a; non-AAC is auto-transcoded to AAC) / frame sequences / single frame / subtitle stream | `input` + `what` required |
@@ -71,7 +75,7 @@ ffmpeg_gif { input: E:\videos\raw.mp4, duration: 3, width: 480 }
 
 ```bash
 pnpm install
-pnpm test       # build + 104 tests
+pnpm test       # build + 115 tests
 ```
 
 ## License

package/docs/USAGE.md

@@ -2,6 +2,10 @@
 
 [返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
 
+## 抽帧与源文件保护
+
+默认帧序列写入 `<输入名>-frames/run-*/`，每次使用新目录。显式指定序列时，已有输出需要 `overwrite=true`；即使允许覆盖，也不能覆盖任何输入或字幕源及其文件别名。
+
 ## 本次改进
 
 相对文件路径以当前会话工作区为基准。提供 start / duration 时必须是合法时间，非法输入不会退回默认值或意外处理整段视频。
@@ -42,7 +46,7 @@ dsh plugin --profile web remove dsh-ffmpeg
 | :-- | :-- | :-- |
 | `ffmpeg_probe` | 探测媒体信息（格式/时长/分辨率/帧率/码率/音轨/字幕轨；多视频流时返回完整 videos 列表） | `input` 必填 |
 | `ffmpeg_cut` | 剪辑片段（默认流拷贝秒级，可精确重编码） | `input` 必填；`start`/`end`/`duration` |
-| `ffmpeg_concat` | 拼接 2-20 个片段（同编码流拷贝 / 混合编码重编码；无音轨输入按纯视频拼接） | `inputs` 数组必填 |
+| `ffmpeg_concat` | 拼接 2-20 个片段；重编码时等比补边到同一画布，混合无声片段会补静音并保留其余原声 | `inputs` 数组必填；`reencode=true` 时可用 `width` + `height`、`fps` 指定输出 |
 | `ffmpeg_encode` | 转码（B 站 1080p/4K、竖屏 1080p、web-720p 预设 + crf/fps/scale 覆盖） | `input` 必填；`preset` 可选 |
 | `ffmpeg_subtitle` | 字幕烧录（SRT/ASS 硬字幕） | `input`+`subtitle` 必填 |
 | `ffmpeg_extract` | 提取音轨（m4a，非 AAC 自动转 AAC）/ 抽帧序列 / 单帧 / 字幕流 | `input`+`what` 必填 |
@@ -75,7 +79,7 @@ ffmpeg_adjust { input: E:\videos\raw.mp4, volume: +2dB }
 
 ```bash
 pnpm install
-pnpm test       # 构建 + 104 个测试
+pnpm test       # 构建 + 115 个测试
 ```
 
 ## License

package/docs/VALIDATION.md

@@ -1,5 +1,9 @@
 # dsh-ffmpeg 验证记录
 
+## 2026-10-26：0.5.1
+
+[本次修复、回归与未验收范围](validation-0.5.1.md)。
+
 本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
 
 ## 原中文记录

package/docs/validation-0.5.1.md

@@ -0,0 +1,19 @@
+# 0.5.1 验证记录
+
+日期：2026-10-26。官方 Windows 宿主：DSH 0.2.1-rc.3。
+
+## 行为变化
+
+抽帧默认使用每次独立的 run 目录；显式帧序列检查实际文件冲突。输出保护覆盖所有拼接输入、字幕源、符号链接及硬链接别名。
+
+## 验证与限制
+
+- Windows 本地：115 项，114 通过、1 跳过；没有把跳过计为通过。
+- 官方 RC.3 调用真实 FFmpeg 连续抽帧两次，目录互不覆盖，原有帧哨兵保持不变。Windows 跳过 1 项 POSIX 大小写检查，Linux 结果以 CI 为准。
+- GitHub 的跨平台 CI 和 npm 发布完整性以该版本工作流及 registry 为准；本记录不把本地测试等同于已发布。
+
+## English
+
+Frame extraction uses a separate run directory by default. Explicit frame sequences check existing output names. Output protection covers every concat input, subtitle sources and symlink/hard-link aliases.
+
+Runtime/account limits are listed above. Synthetic peers and model adapters do not establish live account delivery or model quality.

package/lib/args.d.ts

@@ -28,6 +28,17 @@ export interface ConcatSpec {
     reencode: boolean;
     /** 所有输入都含音频流（probe 结果）：只有全有才能用 a=1，否则 concat filter 绑定失败。 */
     hasAudio?: boolean;
+    /** 统一到目标画布；等比缩放并补边，不拉伸画面。 */
+    normalize?: {
+        width: number;
+        height: number;
+        fps: number;
+    };
+    /** 缺音轨片段用等长静音补齐，保留其余片段的原声。 */
+    audioInputs?: Array<{
+        present: boolean;
+        duration: number;
+    }>;
 }
 /** 拼接：同编码流拷贝走 concat demuxer（需 list 文件），否则 filter_complex 重编码。 */
 export declare function concatArgs(ffmpeg: string, spec: ConcatSpec): string[];

package/lib/args.js

@@ -37,11 +37,35 @@ export function concatArgs(ffmpeg, spec) {
     const parts = [ffmpeg, flag];
     for (const input of spec.inputs)
         parts.push('-i', input);
-    parts.push('-filter_complex', 'concat=n=' + spec.inputs.length + ':v=1:a=' + (spec.hasAudio === false ? '0' : '1'));
-    // a=0 时 filter 没有音频 pad，但 ffmpeg 仍可能自动选中输入音轨；用 -an 明确只要视频
-    if (spec.hasAudio === false)
+    const hasAudio = spec.audioInputs?.some(input => input.present) ?? spec.hasAudio !== false;
+    const filters = [];
+    const pads = [];
+    spec.inputs.forEach((_input, i) => {
+        const steps = [];
+        if (spec.normalize !== undefined) {
+            const { width, height, fps } = spec.normalize;
+            // First convert anamorphic pixels to square pixels, then fit the shared canvas.
+            steps.push('scale=trunc(iw*sar/2)*2:ih', 'setsar=1', 'scale=' + width + ':' + height + ':force_original_aspect_ratio=decrease:force_divisible_by=2', 'pad=' + width + ':' + height + ':(ow-iw)/2:(oh-ih)/2', 'fps=' + fps);
+        }
+        steps.push('setsar=1', 'format=yuv420p', 'setpts=PTS-STARTPTS');
+        filters.push('[' + i + ':v:0]' + steps.join(',') + '[v' + i + ']');
+        pads.push('[v' + i + ']');
+        if (hasAudio) {
+            const audio = spec.audioInputs?.[i];
+            const source = audio?.present === false
+                ? 'anullsrc=r=48000:cl=stereo,atrim=duration=' + fmtSeconds(audio.duration)
+                : '[' + i + ':a:0]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo';
+            filters.push(source + ',asetpts=PTS-STARTPTS[a' + i + ']');
+            pads.push('[a' + i + ']');
+        }
+    });
+    filters.push(pads.join('') + 'concat=n=' + spec.inputs.length + ':v=1:a=' + (hasAudio ? '1[vout][aout]' : '0[vout]'));
+    parts.push('-filter_complex', filters.join(';'), '-map', '[vout]');
+    if (hasAudio)
+        parts.push('-map', '[aout]', '-c:a', 'aac');
+    else
         parts.push('-an');
-    parts.push('-c:v', 'libx264', '-preset', 'veryfast', '-crf', '18', '-c:a', 'aac', spec.output);
+    parts.push('-c:v', 'libx264', '-preset', 'veryfast', '-crf', '18', spec.output);
     return parts;
 }
 /** concat demuxer 的 list 文件内容（路径中的单引号按 ffmpeg 规则转义）。 */
@@ -116,12 +140,12 @@ export function frameAtArgs(ffmpeg, spec) {
 /** GIF 第一遍：调色板生成（palettegen）。 */
 export function gifPaletteArgs(ffmpeg, spec) {
     const filter = 'fps=' + spec.fps + ',scale=' + spec.width + ':-1:flags=lanczos,palettegen';
-    return [ffmpeg, '-y', '-i', spec.input, '-ss', fmtSeconds(spec.start), '-t', fmtSeconds(spec.duration), '-vf', filter, spec.palettePath];
+    return [ffmpeg, '-y', '-ss', fmtSeconds(spec.start), '-t', fmtSeconds(spec.duration), '-i', spec.input, '-vf', filter, '-frames:v', '1', '-update', '1', spec.palettePath];
 }
 /** GIF 第二遍：paletteuse 合成。 */
 export function gifUseArgs(ffmpeg, spec) {
     const filter = 'fps=' + spec.fps + ',scale=' + spec.width + ':-1:flags=lanczos[x];[x][1:v]paletteuse';
-    return [ffmpeg, overwriteFlag(spec.overwrite), '-i', spec.input, '-ss', fmtSeconds(spec.start), '-t', fmtSeconds(spec.duration), '-i', spec.palettePath, '-filter_complex', filter, spec.output];
+    return [ffmpeg, overwriteFlag(spec.overwrite), '-ss', fmtSeconds(spec.start), '-t', fmtSeconds(spec.duration), '-i', spec.input, '-i', spec.palettePath, '-filter_complex', filter, spec.output];
 }
 /**
  * atempo 单滤镜只接受约 [0.5, 100]，超出范围用多个 atempo 级联

package/lib/paths.d.ts

@@ -2,8 +2,12 @@
 export declare function assertInputFile(input: string, cwd?: string): string;
 /** 清洗文件名中的危险字符。 */
 export declare function sanitizeName(name: string): string;
+/** Compare every source, resolving junctions/symlinks and detecting hard-link aliases. */
+export declare function assertOutputNotSource(inputs: readonly string[], target: string, cwd?: string): void;
+/** image2's -n does not protect expanded sequence files. Check a supported pattern first. */
+export declare function resolveFramePattern(input: string, explicit: string | undefined, overwrite: boolean, cwd?: string): string;
 /**
  * 决定输出路径：缺省时放在输入同目录，名字 = 输入名 + suffix + ext。
  * 目标已存在且不允许覆写时自动追加 _1/_2…。
  */
-export declare function resolveOutputPath(input: string, explicit: string | undefined, suffix: string, ext: string, overwrite: boolean, cwd?: string): string;
+export declare function resolveOutputPath(input: string | readonly string[], explicit: string | undefined, suffix: string, ext: string, overwrite: boolean, cwd?: string): string;

package/lib/paths.js

@@ -3,7 +3,7 @@
  *
  * @module dsh-ffmpeg/paths
  */
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, lstatSync, realpathSync, mkdirSync, mkdtempSync, readdirSync } from 'node:fs';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 /** 校验输入文件存在且是文件；返回绝对路径。 */
 export function assertInputFile(input, cwd = process.cwd()) {
@@ -21,22 +21,96 @@ export function sanitizeName(name) {
     const cleaned = name.trim().replace(/[<>:"/\\|?*\x00-\x1f]/g, '_').replace(/\s+/g, '_').slice(0, 120);
     return cleaned === '' ? 'output' : cleaned;
 }
+function canonicalPath(file) {
+    let parent = resolve(file);
+    const missing = [];
+    while (!existsSync(parent)) {
+        if (lstatSync(parent, { throwIfNoEntry: false })?.isSymbolicLink())
+            throw new Error('输出路径包含悬空链接，已拒绝：' + file);
+        const next = dirname(parent);
+        if (next === parent)
+            throw new Error('无法解析输出路径：' + file);
+        missing.unshift(basename(parent));
+        parent = next;
+    }
+    const result = join(realpathSync(parent), ...missing);
+    return process.platform === 'win32' ? result.toLowerCase() : result;
+}
+/** Compare every source, resolving junctions/symlinks and detecting hard-link aliases. */
+export function assertOutputNotSource(inputs, target, cwd = process.cwd()) {
+    const absolute = resolve(cwd, target), canonical = canonicalPath(absolute);
+    const targetStat = existsSync(absolute) ? statSync(absolute, { bigint: true }) : undefined;
+    for (const input of inputs) {
+        const source = resolve(cwd, input), sourceStat = existsSync(source) ? statSync(source, { bigint: true }) : undefined;
+        if (canonicalPath(source) === canonical || (targetStat && sourceStat && sourceStat.ino !== 0n && targetStat.ino === sourceStat.ino && targetStat.dev === sourceStat.dev)) {
+            throw new Error('输出路径与输入文件相同或指向同一文件，已拒绝（避免覆盖源文件）。');
+        }
+    }
+}
+/** image2's -n does not protect expanded sequence files. Check a supported pattern first. */
+export function resolveFramePattern(input, explicit, overwrite, cwd = process.cwd()) {
+    if (!explicit?.trim()) {
+        const directory = join(dirname(input), sanitizeName(basename(input, extname(input))) + '-frames');
+        mkdirSync(directory, { recursive: true });
+        return join(mkdtempSync(join(directory, 'run-')), sanitizeName(basename(input, extname(input))) + '-%03d.png');
+    }
+    let pattern = resolve(cwd, explicit.trim());
+    if (!basename(pattern).includes('%')) {
+        const ext = extname(pattern);
+        pattern = ext ? pattern.slice(0, -ext.length) + '-%03d' + ext : pattern + '-%03d.png';
+    }
+    if (dirname(pattern).includes('%'))
+        throw new Error('序列占位符只能放在输出文件名中，不能放在目录名中。');
+    const filename = basename(pattern);
+    let source = '^', count = 0;
+    const literal = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    for (let i = 0; i < filename.length;) {
+        if (filename[i] !== '%') {
+            source += literal(filename[i++]);
+            continue;
+        }
+        if (filename[i + 1] === '%') {
+            source += '%';
+            i += 2;
+            continue;
+        }
+        const marker = /^%(?:0([1-9][0-9]?))?d/.exec(filename.slice(i));
+        if (!marker)
+            throw new Error('抽帧序列文件名只支持 %d 或 %0Nd（例如 %03d），字面的 % 请写成 %%。');
+        count++;
+        source += '[0-9]{' + (marker[1] ? Number(marker[1]) : 1) + ',}';
+        i += marker[0].length;
+    }
+    if (count !== 1)
+        throw new Error('抽帧序列文件名必须包含且只包含一个 %d 或 %0Nd。');
+    const matcher = new RegExp(source + '$', process.platform === 'win32' ? 'i' : '');
+    const directory = dirname(pattern);
+    mkdirSync(directory, { recursive: true });
+    const existing = readdirSync(directory).filter(name => matcher.test(name));
+    for (const name of existing)
+        assertOutputNotSource([input], join(directory, name), cwd);
+    if (!overwrite && existing.length)
+        throw new Error('抽帧输出已存在（' + existing.length + ' 个同名序列文件），已拒绝覆盖；请更换输出目录或文件名前缀。');
+    return pattern;
+}
 /**
  * 决定输出路径：缺省时放在输入同目录，名字 = 输入名 + suffix + ext。
  * 目标已存在且不允许覆写时自动追加 _1/_2…。
  */
 export function resolveOutputPath(input, explicit, suffix, ext, overwrite, cwd = process.cwd()) {
+    const inputs = typeof input === 'string' ? [input] : input;
+    if (!inputs.length)
+        throw new Error('至少需要一个输入源文件。');
+    const primary = resolve(cwd, inputs[0]);
     let target;
     if (explicit !== undefined && explicit.trim() !== '') {
         target = resolve(cwd, explicit.trim());
     }
     else {
-        const base = basename(input, extname(input));
-        target = join(dirname(input), sanitizeName(base) + suffix + ext);
-    }
-    if (target.toLowerCase() === resolve(input).toLowerCase()) {
-        throw new Error('输出路径与输入文件相同，已拒绝（避免覆盖源文件）。');
+        const base = basename(primary, extname(primary));
+        target = join(dirname(primary), sanitizeName(base) + suffix + ext);
     }
+    assertOutputNotSource(inputs, target, cwd);
     if (overwrite || !existsSync(target))
         return target;
     const directory = dirname(target);

package/lib/tools.js

@@ -10,7 +10,7 @@ import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 import { adjustArgs, concatArgs, concatListContent, cutArgs, ENCODE_PRESETS, encodeArgs, extractArgs, fmtSeconds, frameAtArgs, gifPaletteArgs, gifUseArgs, probeArgs, subtitleArgs, } from './args.js';
 import { parseProbeJson } from './ffprobe.js';
-import { assertInputFile, resolveOutputPath, sanitizeName } from './paths.js';
+import { assertInputFile, resolveOutputPath, resolveFramePattern, sanitizeName } from './paths.js';
 import { parseTimeArg } from './config.js';
 function executionCwd(exec) { return exec?.agent?.session?.header?.cwd || process.cwd(); }
 /** 编译作者 DSL 为原始 JSON Schema（正是 defineTool 存为 definition.parameters 的值）。 */
@@ -243,11 +243,14 @@ export function buildFfmpegTools(config, runner) {
     };
     const concat = {
         name: 'ffmpeg_concat',
-        description: '拼接多个视频片段。默认要求编码一致（流拷贝，秒级完成）；reencode=true 时统一重编码拼接（慢；先 probe 各输入，任一输入无音轨就按纯视频拼接，避免音轨绑定失败）。inputs 为 2-20 个文件路径。',
+        description: '拼接 2-20 个视频片段。默认同编码流拷贝；reencode=true 将不同分辨率、帧率和像素比例统一到第一个片段的画布，等比补边；可指定 width/height/fps。混合有声与无声素材时只为无声段补静音，保留其他段的声音。',
         parameters: compileParameters({
             inputs: { type: 'array', items: { type: 'string' }, required: true, description: '输入文件路径数组（2-20 个，必填）。' },
             output: { type: 'string', description: '输出路径（可选，默认第一个输入同目录加 .concat 后缀）。' },
             reencode: { type: 'boolean', description: '是否统一重编码拼接（默认 false=流拷贝）。' },
+            width: { type: 'integer', description: '重编码目标宽度；与 height 一起指定，2-8192 的偶数。默认采用首段宽度。' },
+            height: { type: 'integer', description: '重编码目标高度；与 width 一起指定，2-8192 的偶数。默认采用首段高度。' },
+            fps: { type: 'number', description: '重编码目标帧率 1-240。默认采用首段帧率，无法识别时用 30。' },
         }),
         output: {
             schema: produceSchema,
@@ -265,8 +268,22 @@ export function buildFfmpegTools(config, runner) {
                 throw new Error('inputs 最多 20 个文件（当前 ' + inputs.length + ' 个）。');
             const absolute = inputs.map(input => assertInputFile(input, executionCwd(exec)));
             const reencode = args.reencode === true;
+            const requestedWidth = optionalNumber(args, 'width');
+            const requestedHeight = optionalNumber(args, 'height');
+            const requestedFps = optionalNumber(args, 'fps');
+            if ([requestedWidth, requestedHeight, requestedFps].some(value => value !== undefined) && !reencode)
+                throw new Error('width/height/fps 需要 reencode=true。');
+            if ((requestedWidth === undefined) !== (requestedHeight === undefined))
+                throw new Error('width 与 height 需要一起指定。');
+            for (const [name, value] of [['width', requestedWidth], ['height', requestedHeight]]) {
+                if (value !== undefined && (!Number.isInteger(value) || value < 2 || value > 8192 || value % 2 !== 0))
+                    throw new Error(name + ' 必须是 2-8192 的偶数。');
+            }
+            if (requestedFps !== undefined && (!Number.isFinite(requestedFps) || requestedFps < 1 || requestedFps > 240))
+                throw new Error('fps 必须在 1-240 之间。');
             const firstExt = extname(absolute[0]) || '.mp4';
-            const output = resolveOutputPath(absolute[0], optionalString(args, 'output'), '.concat', firstExt, cfg.overwrite, executionCwd(exec));
+            const output = resolveOutputPath(absolute, optionalString(args, 'output'), '.concat', firstExt, cfg.overwrite, executionCwd(exec));
+            let normalized;
             if (!reencode) {
                 const listPath = join(tmpdir(), 'dsh-ffmpeg-concat-' + Date.now() + '-' + randomUUID().slice(0, 8) + '.txt');
                 writeFileSync(listPath, concatListContent(absolute), 'utf8');
@@ -278,18 +295,27 @@ export function buildFfmpegTools(config, runner) {
                 }
             }
             else {
-                // concat filter 的 a=1 要求每个输入都含音频轨，否则报 Error binding filtergraph inputs/outputs；先 probe 确认
-                let allHaveAudio = true;
+                const media = [];
                 for (const inputPath of absolute) {
                     const probeResult = await runChecked(runner, probeArgs(cfg.ffprobePath, inputPath), Math.min(timeout, 60000), 'ffprobe', exec?.signal);
-                    if (parseProbeJson(probeResult.stdout).audio.length === 0) {
-                        allHaveAudio = false;
-                        break;
-                    }
+                    const info = parseProbeJson(probeResult.stdout);
+                    if (info.video === null || info.video.width < 1 || info.video.height < 1)
+                        throw new Error('拼接输入缺少有效视频画面：' + inputPath);
+                    media.push(info);
                 }
-                await runChecked(runner, concatArgs(cfg.ffmpegPath, { inputs: absolute, output, overwrite: cfg.overwrite, reencode: true, hasAudio: allHaveAudio }), timeout, 'ffmpeg 拼接', exec?.signal);
+                const first = media[0].video;
+                normalized = { width: requestedWidth ?? Math.ceil(first.width / 2) * 2, height: requestedHeight ?? Math.ceil(first.height / 2) * 2,
+                    fps: requestedFps ?? (first.fps !== null && first.fps >= 1 && first.fps <= 240 ? first.fps : 30) };
+                const anyAudio = media.some(info => info.audio.length > 0);
+                const audioInputs = media.map((info, index) => {
+                    const duration = info.video.durationSeconds ?? info.durationSeconds ?? 0;
+                    if (anyAudio && info.audio.length === 0 && duration <= 0)
+                        throw new Error('无法确定无声片段的时长，不能安全补齐静音：' + absolute[index]);
+                    return { present: info.audio.length > 0, duration };
+                });
+                await runChecked(runner, concatArgs(cfg.ffmpegPath, { inputs: absolute, output, overwrite: cfg.overwrite, reencode: true, normalize: normalized, audioInputs }), timeout, 'ffmpeg 拼接', exec?.signal);
             }
-            return { output, count: absolute.length, reencode };
+            return { output, count: absolute.length, reencode, ...(normalized === undefined ? {} : { normalized }) };
         },
         timeoutMs: timeout,
     };
@@ -365,7 +391,7 @@ export function buildFfmpegTools(config, runner) {
             const args = asRecord(rawArgs);
             const input = assertInputFile(requiredString(args, 'input', '输入视频'), executionCwd(exec));
             const subtitlePath = assertInputFile(requiredString(args, 'subtitle', '字幕文件'), executionCwd(exec));
-            const output = resolveOutputPath(input, optionalString(args, 'output'), '.sub', extname(input) || '.mp4', cfg.overwrite, executionCwd(exec));
+            const output = resolveOutputPath([input, subtitlePath], optionalString(args, 'output'), '.sub', extname(input) || '.mp4', cfg.overwrite, executionCwd(exec));
             await runChecked(runner, subtitleArgs(cfg.ffmpegPath, { input, subtitle: subtitlePath, output, overwrite: cfg.overwrite }), timeout, 'ffmpeg 字幕', exec?.signal);
             return { output, mode: 'burn' };
         },
@@ -412,20 +438,7 @@ export function buildFfmpegTools(config, runner) {
                 output = resolveOutputPath(input, optionalString(args, 'output'), '.subtitle', '.srt', cfg.overwrite, executionCwd(exec));
             }
             else {
-                const rawOutput = optionalString(args, 'output');
-                const explicit = rawOutput === undefined ? undefined : resolve(executionCwd(exec), rawOutput);
-                if (explicit !== undefined) {
-                    if (explicit.includes('%')) {
-                        output = explicit;
-                    }
-                    else {
-                        const explicitExt = extname(explicit);
-                        output = explicitExt === '' ? explicit + '-%03d.png' : explicit.slice(0, -explicitExt.length) + '-%03d' + explicitExt;
-                    }
-                }
-                else {
-                    output = join(dirname(input), sanitizeName(basename(input, extname(input))) + '-%03d.png');
-                }
+                output = resolveFramePattern(input, optionalString(args, 'output'), cfg.overwrite, executionCwd(exec));
             }
             const spec = { input, what: what, output, overwrite: cfg.overwrite, start, duration, fps, streamIndex };
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ffmpeg",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "description": "用自然语言调用 FFmpeg，处理已有音视频文件。",
   "type": "module",
   "main": "lib/index.js",