# FFBox wraps FFmpeg in a filter graph editor and a remote backend

> FFBox is an Electron and TypeScript front end for FFmpeg that builds commands from a filter graph, ships as a desktop app or a deployable service, and deliberately leaves FFmpeg itself to the user.

**ttqftech/FFBox** — 一个多媒体转码百宝箱 / 一个 FFmpeg 的套壳

- Repository: https://github.com/ttqftech/FFBox
- Stars: 1,109 · Forks: 39
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/ttqftech-ffbox

## The problem FFBox takes on: FFmpeg is powerful and hard to type

FFmpeg's command line covers nearly every multimedia operation, and its option count is what makes it useful and what makes it unpleasant. A single transcode can require demuxer and decoder selection, filter graph construction, codec flags, and container selection, and the resulting line is long enough that editing it by hand becomes the bottleneck. The README describes FFBox in two phrases, one of them a mouthful: a multimedia transcoding toolbox and a shell around FFmpeg.

The audience is therefore people who know what a codec or a filter is but do not want to assemble a long argument for every job. The README positions the parameter panel as visible and transparent, with the claim that a user operating the interface can simultaneously learn the native FFmpeg usage. That is a design statement, not a benchmark, and the project does not publish timings or comparisons, so there is no measurement here about whether the interface is faster than typing.

What the README does claim is scope of coverage. It states that FFBox automatically scans the local FFmpeg and loads all the muxers, demuxers, filters, encoders and their parameters that this machine supports, and it describes that as full adaptation of FFmpeg capability. The practical consequence is that the tool is defined by the binary on your machine rather than by a fixed feature list, which also means the same build of FFBox on two different hosts exposes different options.

## The four stage pipeline and the filter graph behind it

The README lays out the workflow as a chain: input, then filters, then encoding, then output. Each stage is a place where FFmpeg options are chosen, and the generated command mirrors that structure, so what you see in the interface maps onto the argument string you would write by hand.

The part that separates FFBox from simpler wrappers is the graph editor. The README states that FFBox supports complete stream graphs and filter graph editing rather than only simple filters, and that it can handle multi input and multi output tasks. It also mentions scanning the FFmpeg filter documentation so the reference is available while working. A graph editor is the right tool for the case where a job is not a single linear filter chain, for instance when audio and video streams need different treatment before muxing, and it is also the part most likely to be demanding for a newcomer, since the graph concepts come from FFmpeg itself rather than from the application.

Two supporting features are worth naming because they affect real workflows. The progress panel shows progress, speed, bitrate and remaining time graphically, and can present the same run as charts. The task manager supports drag in and immediate start, removing a task when it completes, start and pause per task or across all tasks, copying a task, a custom concurrency count, and keeping unfinished tasks after a crash. Timestamp handling is also offered, either preserving file timestamps or rewriting them conditionally. These are conveniences around a long job rather than transcoding features, which is a reasonable division.

## One codebase, three deployment shapes: desktop, remote service, and mixed

The architecture is separated so the backend can run away from the user. The README lists three ways to use the project: use FFBox directly as an application, use the Node.js remote transcoding service together with a WebUI deployed separately, or mix the two. Complete support is claimed for Windows, Linux and macOS, and the service can be deployed on Android.

That separation is the real differentiator for a shared machine. A team can run the backend on a workstation or a server that holds the media, and any operator with the WebUI can queue work against it. The custom concurrency count matters here, because a shared transcoding host needs a ceiling on how many encodes run at once, and the crash recovery behaviour matters more still: on a machine that is restarted mid job, the unfinished task list survives.

The version history in the README shows why this architecture has moved. The 1.x line was plain HTML, CSS and JavaScript with no engineering or modular structure, 2.x moved to Vue 2 with control logic concentrated in a state manager, 3.x introduced higher cohesion, separated service from UI, added TypeScript and added remote control, 4.x brought a new interface, a rewritten build and packaging script and a full front end and back end separation, and 5.x keeps the 4.x architecture while pushing further on how completely FFmpeg is adapted. The current default branch is 6.0+ and package.json reports the version as 6.0.0-alpha, so the code in the repository is ahead of the newest tagged release.

## Compiling it yourself, and the FFmpeg prerequisite

The project does not ship FFmpeg. The README is explicit: without FFmpeg, FFBox can only show you the startup command and cannot perform transcoding. It directs users to the FFmpeg download page, then to place FFmpeg on the system path, which is the recommended route, or in the program directory.

For users of a release build, that download plus the installed application is the whole setup, and the official site at ffbox.ttqf.tech holds the software description. For people who want to build the project, the README lists the requirements rather than a tutorial, and the numbers are specific: Node.js version 22.12 or newer for compilation, pnpm as the recommended package manager with version 8 preferred, and Visual Studio 2022 if you intend to compile the Windows helper yourself. The prebuilt FFBoxHelper.exe sits in the repository root; Linux and macOS packaging need no extra software, while Windows packaging requires Inno Setup 6 with iscc.exe on the environment path and a ChineseSimplified.isl file prepared in the same directory.

The build and packaging commands are exposed as npm scripts, and this is the sequence that produces a distributable application:

```json
"build:frontend": "node scripts/build-frontend.mjs",
"build:backend": "node scripts/build-backend.mjs",
"package": "electron-builder",
"build:everything": "npm run build:frontend && npm run build:backend && npm run package"
```

The back end is compiled into a standalone binary per platform before electron-builder assembles the desktop application:

```bash
"pkg:backend:win": "pkg --config ./config/pkg.win.config.json ./app/backend/index.cjs",
"pkg:backend:mac": "pkg --config ./config/pkg.mac.config.json ./app/backend/index.cjs",
"pkg:backend:linux": "pkg --config ./config/pkg.linux.config.json ./app/backend/index.cjs"
```

A documentation endpoint is also generated from schemas, which matters if you intend to drive the service from something other than the bundled WebUI:

```bash
"swagger": "node scripts/generate-schemas.js && node scripts/generate-swagger.js"
```

The README notes that pnpm is configured with node-linker=hoisted because electron-builder has a problem compiling utimes, and that npm is roughly twice as slow with a slightly different resulting package size, and that yarn and bun currently produce a front end that electron-builder can package but a back end that pkg cannot produce a usable binary from.

## Three failure modes you will meet on a fresh clone

The README documents its own rough edges, which is unusual and useful. The first is network access. Running pnpm install, pkg:backend or package all require downloading prebuilt binaries, and the README notes that GitHub URLs are particularly hard to reach from mainland China, suggesting a registry or mirror override such as pnpm set registry or pnpm set ELECTRON_MIRROR. The project already configures a registry and an ELECTRON_MIRROR in .npmrc, but pnpm at version 9 and above stopped reading such unofficial configuration entries, so a fresh install on a newer pnpm can fail before it starts.

The second failure appears as a message about Electron not installing correctly, with the instruction to delete node_modules/electron and try again. The documented remedy is to fall back to pnpm version 8, or to download the Electron archive by hand, unpack it into node_modules/electron/dist, and create node_modules/electron/path.txt containing electron.exe, since Electron's postinstall step downloads through @electron/get and can fail silently.

The third is a missing native binding:

```text
Cannot find module '@rolldown/binding-darwin-arm64'
```

The README attributes this to a node.js version problem and points at the requirement for 22.12 or newer. The common thread across all three is that a clean install depends on a specific combination of a pinned package manager version, a recent Node.js and reachable binary mirrors, and none of that combination is enforced by the project itself.

## Licence, maintenance and the honest comparison

The repository is not archived and the last push was on 2026-10-04, so the code is changing, although the published releases trail it: v5.4 on 2026-06-07, v5.3 on 2026-04-30 and v5.2 on 2025-12-31. The newest tag, v5.4, is older than the 6.0.0-alpha version in package.json, so new work sits on the default branch.

On licensing, the metadata reports a custom licence that GitHub cannot classify, with the repository listing a LICENSE file, and package.json records the license field as "SEE LICENSE IN <LICENSE>". The README advertises a bespoke usage permission and terms of its own. There is no legal advice here, but the practical point for a company is that you have to read that file, because a custom licence may carry conditions that MIT or Apache-2.0 would not.

The alternative worth naming is not another application but the plain command line. Writing ffmpeg by hand costs you a learning curve and no project to maintain, and it gives you exact control with nothing to install besides FFmpeg itself. FFBox inverts that trade: it adds an interface, a filter graph editor, a task queue and a remote backend, and in exchange it introduces a build chain, a pinned Node.js and package manager setup, and a dependency on your installed FFmpeg matching the features you want to see. For a single ad hoc conversion the command line wins on overhead. For an operator queueing work on shared hardware, the FFBox backend with its concurrency limit, pause controls and crash recovery is the part that earns the dependency.

## Conclusion

Adopt FFBox if your team wants a graphical filter graph, visible FFmpeg parameters and a backend that can run away from the operator's desk, and provide FFmpeg on the target machine yourself. Do not adopt it if you need a fully self-contained binary, a stable release API or a permissive licence, since the repository is on a 6.0.0-alpha package version with a custom LICENSE file. Before committing, install FFmpeg on the host, confirm the detected demuxers, decoders and filters match the workloads you plan to run, and read the LICENSE file rather than assuming MIT.

## FAQ

### Does FFBox include FFmpeg, or do I have to install it myself?

You have to install it yourself. The README states that the project does not bundle FFmpeg, and that without it FFBox can only display the startup command and cannot transcode. It points to the FFmpeg download page and asks you to place the binary on the system path or in the program directory.

### How do I build FFBox from source on my own machine?

The README requires Node.js 22.12 or newer, recommends pnpm version 8, and adds Visual Studio 2022 if you want to compile the Windows helper yourself, plus Inno Setup 6 for the Windows installer. The build is driven by npm scripts, with npm run build:everything running the frontend build, the backend build and electron-builder packaging in sequence.

### Can I run FFBox as a remote transcoding service instead of a desktop app?

Yes. The README lists three deployment shapes: using FFBox directly, using the Node.js remote transcoding service with a separately deployed WebUI, or mixing them. The service is described as deployable on Android as well as the usual Windows, Linux and macOS targets.

### Why does pnpm install fail with an Electron error on a fresh clone?

The README ties this to pnpm 9 and above no longer reading the unofficial registry and ELECTRON_MIRROR entries in .npmrc, so Electron is not downloaded during its postinstall step. The suggested fixes are to fall back to pnpm version 8, or to download the Electron archive manually into node_modules/electron/dist and write electron.exe into node_modules/electron/path.txt.

### What licence does FFBox use?

The repository metadata reports a custom licence that GitHub cannot classify, the LICENSE file sits in the project root, and package.json records the license field as "SEE LICENSE IN <LICENSE>". The README also refers to its own bespoke usage permission and terms, so the terms of use have to be read from that file.

## Sources

- [Issues](https://github.com/ttqftech/FFBox/issues)
- [README](https://github.com/ttqftech/FFBox/blob/6.0+/README.md)
- [Releases](https://github.com/ttqftech/FFBox/releases)
- [ttqftech/FFBox on GitHub](https://github.com/ttqftech/FFBox)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ttqftech-ffbox