I built a video clipper that downloads only the part you need

Vallabh Sharma — Sat, 14 Nov 2026 08:10:31 +0000

I needed twelve minutes from a ninety-minute conference talk. Every tool I tried downloaded the whole thing first, then asked me to trim it afterward. That is backwards. I already knew the range before I clicked download.

So I built Clipshed: paste a YouTube, Facebook, or Instagram link, pick a start and end time, choose MP4, MP3, or both, and fetch only that section. It runs entirely on your machine, and it ships as a Windows desktop app with yt-dlp, ffmpeg, and QuickJS bundled, so there is no Python or Node install on the target PC.

This post is about why it exists, how it is put together, and the decisions that turned out to matter.

Why I built it

Most downloaders treat the time range as an afterthought: download everything, open the file in an editor, scrub, cut, export. That workflow is fine if you want the whole video. It is wasteful if you want a clip.

The range is not something you discover after downloading. It is an input, like the URL. If yt-dlp can be told to fetch 00:15:00 through 00:20:00, then the full download was never necessary.

Two smaller frustrations pushed me in the same direction:

Generic yt-dlp GUIs hide the interesting switches. Fast cut versus frame-accurate cut is a real quality and speed trade-off, and it deserves a button.
Download tools see your URLs, and often your cookies. I did not want an account, a cloud queue, or a telemetry pipeline in the middle of that.

Local-first was the obvious constraint. Everything else followed from it.

What it does

Range-first: full video or an exact start/end range, with a draggable timeline and chapter markers.
MP4, MP3, or both: "Both" downloads the section once and extracts the MP3 locally.
Fast or exact cuts: keyframe-aligned stream copy, or a frame-accurate re-encode.
Real job handling: queue, live progress over SSE, cancellation, history, and cleanup.
Local only: the server binds to 127.0.0.1; no account, no uploads, no telemetry.

Architecture: one server, two shells

The repository is four pieces:

Package	Role
`shared/`	Types, time parsing, platform URL rules
`server/`	Express API, job manager, yt-dlp/ffmpeg orchestration
`web/`	React + Vite UI
`desktop/`	Electron shell, packaging, Windows integration

The important part is that the desktop app is not a separate implementation. Electron starts the same Express server that npm start runs, then points a window at it:

// desktop/main.cjs
const { startLocalServer } = require(serverBundle);

return startLocalServer({ host: "127.0.0.1", port: 0 });

Port 0 asks the OS for a free loopback port, so the app never collides with a dev server or another instance. Electron reads the assigned port and loads http://127.0.0.1:<port>.

┌──────────────────────────────────────────────────────┐
│ Electron main                                        │
│  single instance · window · downloads · notifications│
│         │ starts on 127.0.0.1:<random>               │
│         ▼                                            │
│  Express server (one esbuild bundle)                 │
│   /api/probe   /api/jobs   /api/settings   SSE       │
│         │ spawns                                     │
│         ├── yt-dlp.exe ──► ffmpeg.exe                │
│         └── ffprobe.exe                              │
│         │ serves                                     │
│         ▼                                            │
│  React UI in a sandboxed BrowserWindow               │
└──────────────────────────────────────────────────────┘

The server is bundled to a single CommonJS file (about 1.9 MB) with esbuild. The renderer runs with contextIsolation: true, nodeIntegration: false, and sandbox: true; it is just a browser talking to loopback HTTP.

This buys a lot for very little: the browser workflow still works, the API can be tested without Electron, and the UI iterates with Vite's dev server. The desktop shell only owns things a browser cannot do: the window, the single-instance lock, download handling, notifications, and lifecycle.

Engineering decisions that mattered

1. The range is a yt-dlp argument, not a post-processing step

This is the whole product in a few lines:

if (plan.range) {
  const start = formatSectionTimestamp(plan.range.start);
  const end = formatSectionTimestamp(plan.range.end);
  args.push("--download-sections", `*${start}-${end}`);
}

if (plan.precise && plan.range && plan.kind !== "mp3") {
  args.push("--force-keyframes-at-cuts");
}

--download-sections hands the range to yt-dlp's ffmpeg integration, which seeks into the stream and pulls the fragments it needs instead of the entire file. For a one-hour video, a two-minute clip is roughly two minutes of transfer, not sixty.

The precise flag is the interesting trade-off:

Fast cut (default) uses stream copy. It is fast and lossless, but the start snaps to the nearest keyframe, so you may get a few extra seconds at the beginning.
Exact cut adds --force-keyframes-at-cuts, which re-encodes around the cut points. Frame-accurate, slower, especially at 4K.

MP3 is always re-encoded, so its cuts are effectively sample-accurate either way.

2. "Both" means one download, two outputs

The naive implementation of MP4 + MP3 is two jobs: download the video, download the audio again, convert. That doubles the network traffic for the same range.

Instead, "Both" downloads the MP4 section once, then extracts the MP3 from that file with ffmpeg:

await extractMp3(source, mp3Temp, task.bitrate ?? 192, (ffmpeg) => (activeChild = ffmpeg));
await moveFile(mp3Temp, path.join(outDir, `${task.base}.mp3`));

The extracted MP3 is probed with ffprobe for duration and size, and both outputs are exposed as separate download buttons. One fetch, two files, and the audio is derived from exactly the same section.

3. Machine-readable progress, not log scraping

yt-dlp's default output is human-readable and changes. Parsing [download] 42.3% of ... works until it doesn't. A progress template is far more stable:

const PROGRESS_TEMPLATE =
  "download:PROGRESS|%(progress.status)s|%(progress.downloaded_bytes)s|" +
  "%(progress.total_bytes)s|%(progress.total_bytes_estimate)s|" +
  "%(progress.speed)s|%(progress.eta)s|%(info.format_id)s|" +
  "%(info.vcodec)s|%(info.acodec)s";

That line arrives on stdout and is split on |. ffmpeg, meanwhile, is told to emit -progress pipe:2, which writes out_time_us, speed, and size to stderr. The tracker merges both sources, throttles updates to 250 ms, and pushes them to the UI over SSE.

One detail that cost me an afternoon: ffmpeg writes progress with carriage returns, so a normal line-based reader misses updates. The line splitter splits on \r\n, \n, and \r:

const parts = (this.buffer + chunk).split(/\r\n|\n|\r/);

Without that, the progress bar freezes during the range download and then jumps to 100%.

4. Cancellation is a process-tree problem

yt-dlp spawns ffmpeg for merging, converting, and section cuts. Killing the parent leaves children behind, still writing files.

On Windows the reliable way to kill the whole tree is taskkill /T /F; on POSIX, the child is started in its own process group and the group is killed:

if (process.platform === "win32") {
  spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
    windowsHide: true,
    stdio: "ignore",
  });
} else {
  process.kill(-child.pid, "SIGKILL");
}

Cancellation is also a state machine, not a single kill. The manager marks the job, freezes progress, kills the active child (which may be yt-dlp or ffmpeg), removes temp files, and only then reports cancelled. Otherwise a late close event would mark the job failed after the user already cancelled it.

5. Some binaries are read-only; one must be writable

Bundling ffmpeg, ffprobe, and QuickJS is straightforward: they never change, so they live in Electron's resources directory and run from there.

yt-dlp is different. Extractors break when sites change, so the app needs yt-dlp -U to work. The install directory may be read-only, especially under Program Files, and tools that self-update inside an asar archive are asking for trouble.

The split is:

Bundled, read-only: ffmpeg.exe, ffprobe.exe, qjs.exe.
Staged, writable: yt-dlp.exe is copied once to %LOCALAPPDATA%\Clipshed\bin and updated in place.

const ytdlpSource = path.join(bundledBinDir, "yt-dlp.exe");
const ytdlpDestination = path.join(binDir, "yt-dlp.exe");
if (!fs.existsSync(ytdlpDestination) && fs.existsSync(ytdlpSource)) {
  await fsp.copyFile(ytdlpSource, ytdlpDestination);
}

That one decision makes in-app yt-dlp updates work in a packaged build, which is the difference between an app that works for a month and one that works next year.

6. yt-dlp needs a JavaScript runtime, and Electron is not one

YouTube's extraction path needs a JavaScript engine for signature challenges. Shipping Node would be absurd inside a desktop app, so the build bundles QuickJS-ng and points yt-dlp at it:

if (existsSync(config.qjsPath)) return ["--js-runtimes", `quickjs:${config.qjsPath}`];
return ["--js-runtimes", "node"];

In development it falls back to Node. In the packaged app there is no Node on the PATH, so the bundled qjs.exe is what keeps extraction working.

7. Local-only changes the security checklist

A loopback server is not a public API, but it still handles URLs, cookies, and filesystem paths, so a few things are deliberate:

Bind to 127.0.0.1, never 0.0.0.0.
Renderer is sandboxed with no Node integration, and navigation to other origins is blocked and handed to the system browser.
Job IDs are validated as UUIDs before they are used in any filesystem path, and cleanup only removes UUID-named directories under trusted roots.
Time input is capped at 64 characters before parsing, which kills a potential ReDoS.
Cookies are never returned by the API and never written to job history.

I also dismissed two "missing rate limiting" scanner findings. For a single-user app bound to loopback, throttling would only interfere with large downloads and SSE while adding no meaningful protection. Not every scanner finding deserves code.

How to use it

Run it from source ⭐

Requirements: Windows 10/11 and Node.js 22+.

npm install
npm run setup
npm run dev

Open http://127.0.0.1:5173. npm run setup fetches yt-dlp, static ffmpeg/ffprobe builds, and QuickJS into bin/. For a production-style local run:

npm run build
npm start

Or try the desktop app (pre-release)

https://github.com/ivsharma/clipshed/releases

The workflow

Paste a video link. Clipshed probes it and shows the title, duration, chapters, and available qualities.
Choose MP4, MP3, or Both.
Leave Full video on, or switch to a custom range and drag the handles (or type 12:30 / 01:02:03).
Pick Fast cut unless you need frame accuracy; then enable Exact cut.
Download. When the job finishes, save the file from the job panel.

A few practical notes:

Both is the bandwidth-efficient choice when you want audio and video.
Fast cut may include a few seconds before your start time. That is the keyframe, not a bug.
Facebook and Instagram are experimental and often need cookies from a signed-in browser. YouTube is the stable path.
Playlists are intentionally unsupported. One video, one range.
Download only content you have the right to use, and follow each site's terms.

What I would change

Electron is heavy. The portable build is about 217 MB, and most of that is Chromium. A Tauri build would be smaller, but it would also mean rebuilding the server in Rust and giving up the "same Node server in dev and production" property that made the whole thing quick to build.

I would also reconsider bundling ffprobe: it only measures finished files, and dropping it would remove a 162 MB binary at the cost of independent output verification

The range-first approach is also a bet on yt-dlp's extractors. When a site changes, the app changes with it, which is why the managed, updatable yt-dlp copy matters more than any UI detail.

The trade-off I am happy with: a boring Express server, a plain React UI, and two well-understood command-line tools, packaged so none of them need to be installed separately.

DEV Community: Vallabh Sharma