dsh-video-merger
Manifest validMerges every folder's videos into one file per folder, matching the first clip's resolution, frame rate, and codec; clips with identical specs are concatenated losslessly, while mismatched clips can b
dsh-video-merger
Merge every folder's videos into one file — without changing the video spec.
A DeepSeek Harness plugin that scans a folder tree, groups the videos by folder, and writes one merged video per folder. It picks the cheapest safe path for each folder: stream copy when the clips are truly identical, timestamp-safe remux when only the container or start time differs, audio-only repair when the video matches but the audio does not, and a single-pass hardware-accelerated encode only when the streams really differ.
按文件夹合并视频:每个包含至少 2 个视频的文件夹生成一个合并文件。完全一致时 无损拼接;仅容器/时间戳不同则重封装;仅音频不同只修音频;真正规格不一致时才 单遍转码(优先 NVENC/QSV/AMF,失败自动回退 x264)。
Contents
- Features
- Requirements
- Install
- Usage
- Screenshots
- Output rules
- How it works
- ffmpeg resolution
- Development
- Limitations
- Troubleshooting
- License
- 中文说明
Features
- Folder-aware. Recursively scans a root folder, groups clips per folder, and merges every folder with at least two videos. Natural file-name ordering.
- Lossless by default. Matching clips are concatenated with the ffmpeg concat demuxer and stream copy. No quality loss, no re-encode, same container.
- Smooth seams. The copy path validates profile, level, time base, SAR,
rotation, colour metadata and VFR, and automatically falls back to an
MPEG-TS remux if ffmpeg reports a timestamp warning. This removes the
frozen/duplicated frames that a naive
-c copycan produce. - Audio-only repair. If the video streams match but the audio layout or sample rate differs, only the audio is re-encoded; video stays untouched.
- One encode pass, hardware first. Truly mixed clips are joined with a single concat filter and encoded once (not once per clip), using NVENC → QSV → AMF → libx264 (or HEVC equivalents) with automatic fallback.
- Optional unified output. Put every result in one folder (defaults to the scanned root), or keep the original per-folder layout.
- Web UI. In-app directory browser, folder checklist, live progress, speed, ETA, cancel, play, and reveal in file manager.
- Data management. One dialog clears the current selection, the remembered root folders, or the merge history; Clear everything wipes all three.
- Two more entry points. The
merge_folder_videosDSH tool and a standalone CLI, both using the same engine. - ffmpeg bootstrap. Detects an existing install; on Windows the UI can download a known-good build.
Requirements
- DeepSeek Harness with the Web UI (desktop or browser profile).
ffmpegandffprobefor the actual merge. Put them onPATH, point the plugin at their folder, or use the Windows auto-download.- Node.js 20+ only if you use the CLI or run the tests.
Install
Clone this repository somewhere stable, then install the folder as a DSH bundle.
In DSH, call the plugin_manager tool:
plugin_manager install_bundle target = <absolute path to dsh-video-merger>
For example:
git clone https://github.com/a-mochis/dsh-video-merger.git
plugin_manager install_bundle target = E:\code\6-plugins\dsh-video-merger
Or download the packaged zip from the latest release, unzip it, and install the extracted folder the same way.
After installing or updating, force-refresh the Web UI (Ctrl+Shift+R). Open any
session and choose the 视频合并 / Video Merge tab in the session tab bar.
Install from Discover
The repository also publishes a one-plugin market index. In DSH open Plugins → Discover → Index sources → Add index source and paste:
https://cdn.jsdelivr.net/gh/a-mochis/dsh-video-merger@main/market/index.json
The Video Merger card then appears in Discover and installs the same bundle. This is a personal index hosted beside the project, not an entry in the curated community catalog. See docs/marketplace.md for the release/update checklist.
The plugin has no runtime npm dependencies.
npm installis only needed for the client tests (react/react-domare dev dependencies).
Usage
Web UI
- Open the 视频合并 tab.
- Choose a root folder. The built-in browser supports entering folders, going up, and typing a path directly. Click 选择此文件夹 to confirm.
- Review the folder list and uncheck anything you do not want to merge. Expand a folder to inspect clip order.
- Leave 统一输出到同一个文件夹 checked to collect all results in one place (the output path defaults to the scanned root), or uncheck it to write each result back into its source folder.
- Click 开始合并. Progress, speed, and ETA are shown per folder and overall.
- Play the result or reveal it in the file manager when the job finishes.
- Open 管理 / Manage in the header to switch back to a recent root folder, clear the current selection, clear the folder history or merge history, or wipe everything at once.
Screenshots
1. Choose the root folder. Click 选择文件夹 / Select folder, browse into the target folder in the built-in browser, then click 选择此文件夹 / Select this folder. The path is filled back and scanned automatically.
2. Review and merge. Check the folders you want, leave 统一输出到同一个文件夹 checked to collect every result in one place (the root by default), then click 开始合并 / Start merge. Progress, speed, and the finished output are shown per folder.
Tool
merge_folder_videos root="E:\videos" recursive=true outputDir="E:\videos\merged"
| Argument | Default | Meaning |
|---|---|---|
root | required | Root directory to scan. |
folder | – | Merge only this folder instead of scanning root. |
recursive | true | Scan sub-folders. |
order | name | Clip order: name or mtime. |
overwrite | false | Overwrite an existing output instead of auto-renaming. |
reencodeFallback | true | Normalize folders whose clips have different specs. |
deleteSource | false | Delete source clips after a successful merge. |
outputDir | – | Put every result in this folder (created if missing). |
wait | true | Wait for completion; false returns a job id immediately. |
CLI
node bin/merge-videos.mjs "E:\videos" --out "E:\videos\merged"
--no-recursive scan only the root folder
--folder <path> merge only this folder
--order name|mtime clip order (default: name)
--out <dir> unified output folder
--overwrite overwrite existing *_merged output
--no-reencode skip folders whose clips have mismatched specs
--delete-source delete source clips after a successful merge
--ffmpeg <dir> directory containing ffmpeg and ffprobe
--json print the final job snapshot as JSON
Exit codes: 0 all succeeded, 1 at least one failure, 2 bad arguments,
3 ffmpeg/ffprobe not found.
Output rules
- Name:
<folder>_merged.<original extension>. - Unified mode uses the folder's path relative to the scan root as a prefix, so
root/a/b/becomesa_b_merged.mp4instead of colliding withroot/a/. - Reserved Windows characters are replaced with
_; an empty name becomesmerged. - Existing outputs are auto-renamed with
(1),(2), … unless overwrite is on. - Files matching
*_merged.*are ignored on the next scan, so you can safely scan the same tree again. - The source clips are never deleted unless
deleteSource/--delete-sourceis set.
How it works
scan folders → ffprobe every clip → compare strict signatures
├─ identical streams, time base and start → concat demuxer + -c copy
├─ video identical, audio differs → copy video + encode audio
├─ streams identical, container differs → per-clip TS remux + concat copy
└─ streams really differ → single concat-filter encode
(NVENC/QSV/AMF → x264 fallback)
The copy signature is deliberately strict:
video: codec | profile | level | width | height | pixel format | fps | avg fps |
SAR | rotation | field order | colour space/primaries/transfer/range |
time base
audio: codec | profile | sample rate | channels | channel layout (or "no audio")
- Copy path:
-f concat -safe 0 -i list -map 0:v:0 -map 0:a? -c copy. If ffmpeg prints a non-monotonic/DTS warning (or fails), the folder is automatically redone through the remux path. - Remux path: each clip is first remuxed to MPEG-TS so every segment starts
at zero and shares a 90 kHz time base, then the segments are concatenated with
-c copyand written as MP4 with-video_track_timescale 30000. - Audio fix path: video is stream-copied; a single AAC track is encoded from the concatenated audio, with silence generated for silent clips.
- Encode path: one
concatfilter produces a single output generation; resolution/fps come from the first clip,yuv420p, H.264/HEVC hardware encoder when available, AAC 192 kbps. A silent track is generated only when the target folder has audio. - Progress comes from
-progress pipe:1 -nostats(out_time_usandspeed).
Performance notes
- One generation, not N. The old fallback encoded every clip to an intermediate file and then concatenated; the new path encodes the whole folder once. That also avoids quality loss from repeated generations.
- No double fast-start. Intermediate files no longer rewrite their index.
- Hardware encode. NVENC is probed once per ffmpeg build and cached. If the driver or GPU cannot open an encoder session, the next candidate is tried; the final fallback is always libx264/libx265.
- No unnecessary work. Matching folders are pure I/O; audio-only differences never touch the video stream; only genuinely mixed folders are encoded.
- Why it used to stutter. Matching was based on too few fields, and
-fflags +genpts -avoid_negative_ts make_zerowas applied to-c copy, which can make the second clip's timestamps collide with the first. The stricter signature plus the TS-remux fallback removes that class of seams.
ffmpeg resolution
Checked in this order:
- The folder configured in the plugin (Web UI → 指定 ffmpeg 目录).
FFMPEG_DIR, thenFFMPEG_PATH.%DSH_HOME%/plugin-data/dsh-video-merger/bin(managed download).- Directories on
PATH. - A few common install locations.
The configuration file is
%DSH_HOME%/plugin-data/dsh-video-merger/config.json ($DSH_HOME or ~/.dsh
when the variable is unset). The detection result is cached for 15 seconds.
The in-app download is Windows-only and fetches the gyan.dev "essentials" build. On macOS/Linux install ffmpeg with your package manager, for example:
brew install ffmpeg # macOS
sudo apt install ffmpeg # Debian / Ubuntu
Development
npm install
npm run check # node --check for every runtime file
npm test # directory-listing normalization + React SSR
npm run test:merge # generates synthetic clips, merges them, asserts specs
npm run test:merge creates test/fixtures/ and test/output/ with ffmpeg
lavfi sources (two identical clips, mixed resolutions, Matroska, an apostrophe
in the file name, missing audio, and a single-clip folder). Both directories are
git-ignored; no test media is committed.
The client tests load lib/client.js through the same
window.__ModuleLoader__ wrapper the Harness uses. If React is not installed
locally, set DSH_PROFILE_PACKAGE to a DSH profile's package.json path.
See CONTRIBUTING.md for the development install flow and PR expectations.
Limitations
- A folder needs at least two videos; a single clip is skipped.
- "Lossless" requires an exact signature match. Otherwise the folder is re-encoded once, which is inherently lossy.
- Subtitles, chapters, and per-clip metadata are not specifically preserved.
- Merging very large folders needs temporary disk space roughly equal to the output size.
- Auto-download of ffmpeg is Windows-only.
Troubleshooting
“ffmpeg not found”. Install ffmpeg and ffprobe and put them on PATH, or set
ffmpegDir in the plugin settings / merge_folder_videos call. The Web UI shows
the resolved binary under the status card; on Windows the Download ffmpeg
button installs the official essentials build into the plugin data directory.
“No folders with at least two videos”. The scan skips single clips and
outputs ending in _merged. Pick the parent folder, not one clip's folder.
A folder shows “转码 / Transcode”. The clips really differ in resolution, frame rate, pixel format, or codec. The first clip is the target; the folder is encoded once with the concat filter. “重封装 / Remux” means only the container or start time differed and no video was re-encoded. Turn off the normalization option to make truly mixed folders fail instead.
A merge fails midway. The per-folder error is shown in the list and in the tool result. The temporary concat list and partial output are removed. Re-run with Overwrite enabled; the job is resumable per folder, not per clip.
The page shows the old UI after an update. Force-refresh with
Ctrl+Shift+R (macOS Cmd+Shift+R); a client bundle is cached per page load.
License
MIT © 2026 a-mochis
中文说明
功能
- 递归扫描根目录,每个含至少 2 个视频的文件夹合并成一个文件。
- 完全一致时使用 concat demuxer +
-c copy,无损、不重新编码。 - 仅容器或起始时间不同:先逐段转 MPEG-TS,再
-c copy重封装,避免接缝卡顿。 - 视频一致、音频参数不同:只重新编码音频(AAC),视频保持原样。
- 真正规格不一致时(默认开启)以第一个视频为基准,用一次 concat filter 完成 单遍转码;优先 NVENC/QSV/AMF,失败自动回退 x264/x265。缺失音轨的片段补静音。
- 进度会显示每个文件夹的处理方式(无损 / 重封装 / 修音频 / 转码 + 编码器)。
- 可把所有结果统一输出到一个文件夹(默认扫描根目录),也可以保持写回各源文件夹。
- Web UI 支持目录浏览、文件夹勾选、实时进度、取消、播放和定位。
- 顶部「管理」弹窗可清空当前选择、历史文件夹记录或历史生成记录,也可一键清空全部。
- 同时提供
merge_folder_videos对话工具和bin/merge-videos.mjs命令行。
安装
git clone https://github.com/a-mochis/dsh-video-merger.git
在 DSH 中调用:
plugin_manager install_bundle target = <dsh-video-merger 的绝对路径>
The profile package can also be installed from a terminal with the DSH CLI:
dsh plugin --profile desktop add git+https://github.com/a-mochis/dsh-video-merger.git
plugin_manager install_bundle additionally enables the bundle in the profile;
after a bare dsh plugin add, make sure dsh-video-merger is listed under
dsh.profile.bundles in the profile's package.json.
安装或更新后强制刷新页面,在会话顶部打开「视频合并」。
使用
- 图形界面:选根目录 → 勾选文件夹 → 按需勾选「统一输出」→ 开始合并。
- 顶部「管理」可查看最近使用的根目录,清空当前选择、历史文件夹或历史生成记录。
界面示意
1. 选择根目录:点「选择文件夹」,在插件自带的目录浏览器中进入目标文件夹, 再点「选择此文件夹」。路径会回填并自动扫描。
2. 核对并合并:勾选要处理的文件夹;「统一输出到同一个文件夹」默认勾选, 留空即输出到扫描根目录;点「开始合并」后可查看总进度、速度和结果。
- 工具:
merge_folder_videos root="E:\videos" outputDir="E:\videos\merged"。 - 命令行:
node bin/merge-videos.mjs "E:\videos" --out "E:\videos\merged"。
输出命名 <文件夹名>_merged.<原扩展名>;统一输出时嵌套目录会带相对路径前缀
(如 a_b_merged.mp4),重名默认自动加 (1),勾选覆盖则直接覆盖。
测试
npm install
npm test
npm run test:merge
测试会用 ffmpeg 的 lavfi 现场生成素材,覆盖同规格、混合分辨率、MKV、文件名
带单引号、缺音轨和单视频文件夹。
许可
MIT © 2026 a-mochis
Comments
Loading…
Similar plugins
by zemul
dsh-better-sidebar 的视频文件预览插件: 在侧边栏打开 .mp4 .webm .mov .mkv .avi 等视频文件时,内联渲染一个可播放、可拖拽进度条的 <video> 播放器。
★ 11
↓ 508/wk
MIT
JavaScript
Nov 14, 2026
dsh plugin --profile web add dsh-video-previewTikTok-style video feed in a floating sidebar window: swipe local or SMB-NAS folders, or paste online video URLs (yt-dlp, bilibili/YouTube, cookies.txt login state); the window auto-fits the video asp
★ 0
dsh plugin --profile web add dsh-plugin-video-playerBrowser-local audio/video toolkit for DSH — extract frames, capture thumbnails, compress images, and convert clips to GIF with FFmpeg.wasm.
★ 0
dsh plugin --profile web add @piedpiper911/dsh-video-toolsby a1121611810
DeepSeek Harness 的多媒体工具箱插件:转换 / 裁剪 / 提取音轨 / 字幕 / 元数据 / Base64,本机 ffmpeg 完成。
★ 0
MIT
JavaScript
Nov 10, 2026
dsh plugin --profile web add dsh-media-converterby ayst-z
DSH 插件:把一支 MV 写成代码(music-code-mv)。确定性的 Canvas2D / Three.js 镜头在无头 Chrome 里逐帧渲染,再用 ffmpeg 编码;并带一个中文图形界面「MV 工坊」。 / DSH plugin: render code-driven music videos, with a Chinese MV Studio GUI.
★ 4
MIT
JavaScript
Oct 15, 2026
dsh plugin --profile web add dsh-music-code-mvby llafztq
Video editing toolset for DeepSeek Harness - trim, concat, audio, subtitles, transform, transcode and frame grabbing, powered by ffmpeg.
★ 4
JavaScript
Oct 8, 2026
dsh plugin --profile web add dsh-video-tool