Preface¶

In the plugin-based usage of DSH (DeepSeek Harness), agents often need to call external tools to complete specific tasks. Video processing through temporary shell scripts frequently requires repeated handling of command assembly, argument boundaries, process timeouts, and output overwrites. dsh-ffmpeg is a DSH video processing tool plugin: it uses the local ffmpeg/ffprobe to provide seven types of tools: probing, cutting, concatenation, transcoding, subtitles, extraction, and GIF creation.

What This Is¶

dsh-ffmpeg is an MIT-licensed DSH video processing tool plugin, with the repository located at:

https://github.com/STARDUSTLC666/dsh-ffmpeg

According to the documentation, it was verified on @deepseek-ai/dsh@0.1.1-rc.2 (2026-08-26). The package.json requires node >=22. The plugin has zero runtime dependencies, but requires a locally available ffmpeg.

Core Features¶

Below are the seven types of tools listed.

ffmpeg_probe¶

Probes media information, including format, duration, resolution, frame rate, bitrate, audio tracks, and subtitle tracks. Returns the complete videos list when multiple video streams are present.

ffmpeg_cut¶

Cuts segments. Defaults to stream copy for speed; can also perform precise re-encoding as needed.

ffmpeg_concat¶

Concatenates 2-20 segments. Supports stream copy for identical encoding scenarios, and re-encoding for mixed encoding scenarios.

ffmpeg_encode¶

Transcodes. Supports presets such as bilibili-1080p, 4K, vertical 1080p, and web-720p, and also allows overriding crf, fps, and scale.

ffmpeg_subtitle¶

Burns in SRT/ASS hard subtitles.

ffmpeg_extract¶

Extracts m4a audio tracks, frame sequences, single frames, or subtitle streams.

ffmpeg_gif¶

Generates GIFs from videos, using a two-pass palette method to improve quality.

Runtime Constraints¶

• All arguments are passed as separate argv arrays, not through the shell.
• Processes run through the official DSH subprocess service.
• Timeouts are triggered via AbortSignal for tree-level termination: SIGTERM followed by force kill; Windows uses taskkill /T.
• By default, existing output files are not overwritten; sequence numbers are added automatically. Output paths identical to input paths are directly rejected.
• Single-operation timeouts are clamped within 10 seconds to 2 hours; probing has an additional 60-second limit.

Installation and Enablement¶

First, confirm that ffmpeg is available locally:

ffmpeg -version

Then install the plugin in the target profile:

dsh plugin --profile web add dsh-ffmpeg

If ffmpeg is not on the PATH, you can override the plugin line in the profile’s cordis.patch.yml:

- id: ffmpeg
  name: 'dsh-ffmpeg'
  config:
    ffmpegPath: C:\tools\ffmpeg\bin\ffmpeg.exe
    ffprobePath: C:\tools\ffmpeg\bin\ffprobe.exe
    timeoutMs: 300000

Environment variables can also be used:

DSH_FFMPEG_PATH
DSH_FFPROBE_PATH

To uninstall:

dsh plugin --profile web remove dsh-ffmpeg

Restart the Web service after uninstalling. For thorough cleanup, manually delete the overridden plugin line in your profile’s cordis.patch.yml.

Typical Usage¶

Below are the examples provided in the documentation:

ffmpeg_probe { input: E:\videos\raw.mp4 }
ffmpeg_cut { input: E:\videos\raw.mp4, start: 10, end: 30 }
ffmpeg_encode { input: E:\videos\raw.mp4, preset: bilibili-1080p }
ffmpeg_subtitle { input: E:\videos\raw.mp4, subtitle: E:\videos\subs.srt }
ffmpeg_gif { input: E:\videos\raw.mp4, duration: 3, width: 480 }

These examples cover probing, cutting, transcoding, subtitle burning, and GIF generation. In practice, you can first probe the input file, then choose cutting or transcoding parameters based on the returned duration, stream information, and resolution.

Applicable Scenarios and Notes¶

Best suited for automating local video material processing within DSH agent workflows, such as probing first, then cutting, transcoding, adding subtitles, or exporting GIFs.

Notes:

• The plugin launches ffmpeg/ffprobe subprocesses, so it runs within the environment and permission scope accessible to the current DSH process.
• Before installation, inspect the source code, configuration options, and the MIT license.
• A usable local ffmpeg must be installed.
• By default, existing output files are protected from overwriting; output paths identical to input paths are directly rejected.
• Single operations have a timeout range of 10 seconds to 2 hours; probing has an additional 60-second limit.

Conclusion¶

The value of dsh-ffmpeg lies in encapsulating common ffmpeg video operations into DSH tools, reducing repetitive work such as shell assembly, process management, and output overwriting. The documentation does not provide a landing page URL; the GitHub address is:

https://github.com/STARDUSTLC666/dsh-ffmpeg