Sidecar management
ffmpeg and mkvtoolnix are never bundled. Everything lives in src/main/sidecars/, which has no dependency on electron: createSidecarModule() receives paths, the 7za path, a consent gate, a progress emitter and a logger. This allows running the whole flow in plain Node.
Manifests
Fetched by ManifestClient from manifests/sidecar.json in this repository, through https://raw.githubusercontent.com/lsilvatti/bakasub/main/manifests (src/main/config/remote.ts; the repo must stay public), 10 s timeout, validated with Zod (manifest.schema.ts). The old bakasub-manifests repository and version.json are gone: app updates now go through GitHub Releases (see release.md).
sidecar.json:tools[]withname,version,executableNameandartifacts[platform][arch] = { url (https), sha256, archiveType: zip|7z|appimage, binaryRelativePath }.- Last valid manifest is cached in
userData/cache/manifests/. The cache is used only when the network fails; an invalid remote manifest raisesINVALID_MANIFESTinstead of silently falling back.
Bumping a sidecar
- Edit
manifests/sidecar.json:version,urlandsha256(lowercase hex,sha256sumof the exact file at the URL) per platform; setupdatedAt. Keep two-space indentation. npx vitest run src/main/sidecars/manifest.schema.test.ts(CI runs it too and rejects invalid manifests). Copy the file tosrc/main/sidecars/__fixtures__/sidecar.json, which a test keeps identical.- Merge to
main: running apps pick it up on the nextsidecars:check(the manifest is not tied to an app release). Versions are pinned, so any change marks the tooloutdatedand asks for consent again.
The ffmpeg URLs point to versioned builds hosted by third parties (martin-riedl.de, gyan.dev). The provider may remove old builds: when a URL starts returning 404, bump to the current build. A silently replaced file fails safely with CHECKSUM_MISMATCH.
States
SidecarManager.check() never downloads. Per tool: unsupported (no artifact for platform/arch), missing (not registered or binary absent), outdated (registered version differs from the manifest: versions are pinned, not “at least”), ok.
Install flow
sidecars:install { tools } └─ mutex (SIDECAR_BUSY if another install is running) └─ load manifest, compute pending tools (state != ok) └─ group by sha256 into InstallUnits (mkvextract+mkvmerge share one) └─ ConsentGate.confirmDownload() ← native dialog in Main, default = Cancel declined ─► { outcome: 'declined' }, nothing touches the disk └─ per unit (independent: one failing unit does not stop the others; the result carries `failures[]`): 1. reuse bin/archives/<sha>/ if all binaries already exist 2. downloadVerified() → bin/downloads/<sha>.<ext> 3. extract into bin/archives/.partial-<sha>-<uuid> 4. tryPrune(): copy only needed files, probe the copy, adopt it (fallback: full tree) 5. adopt → bin/archives/<sha>/ (rename ladder, see “Windows file locks”) 6. probeAll(): chmod + run `--version` (`-version` for ffmpeg) 7. InstalledRegistry.update() → bin/installed.json (atomic write) └─ collectGarbage(): drop archives no tool references; drop downloads older than 7 daysCancellation (sidecars:cancel or shutdown) aborts the shared AbortController, which reaches fetch and the ProcessRunner.
Windows file locks (fs-resilient.ts)
A freshly executed .exe (the probe of the pruned copy) can keep a handle open for several seconds (Defender real-time scan, Search Indexer, the exiting process), so rename of a folder containing it fails with EPERM/EBUSY/EACCES. SidecarInstaller.adopt() therefore climbs a ladder, logging the original error before each step:
rename(pruned, final)with backoff on EPERM/EBUSY/EACCES (~10 s total on Windows, ~0.7 s elsewhere).- Recursive copy of the pruned tree to
final(the locked source is left to cleanup/GC). - Same two steps with the full tree, which was never executed by the app and has no probe handle.
- Fail with
EXTRACT_FAILED, message carrying the original error code and the destination path.
All finally cleanups (staging, pruned dir, downloaded archive) and collectGarbage() are best-effort (rm with maxRetries) and never throw, so they cannot mask the install error. Leftover .partial-* folders are removed by collectGarbage() at app boot and after every install.
Tip (optional, never required): excluding %APPDATA%\bakasub\bin from Windows Defender real-time scanning avoids the delays.
Download (downloader.ts)
- Streams to
<dest>.part; SHA-256 is computed on the fly. - Resume: a sidecar
<dest>.part.jsonstores a validator (strong ETag orLast-Modified). The next attempt sendsRange: bytes=N-+If-Range.206with a matchingContent-Rangeappends (the existing bytes are re-hashed first);200restarts from zero;416discards the part. - Retry: up to 4 attempts, backoff 1 s → 8 s, only for
NETWORKerrors. Cancellation and network failures keep the.part;CHECKSUM_MISMATCHdeletes it. - 30 s idle timeout, redirects to
httpare refused, truncated bodies are detected by length.
Extraction and pruning
| Archive | Extractor | Prune rule |
|---|---|---|
zip, 7z |
7za from 7zip-bin (unpacked from the asar; chmod applied on Linux) |
binaries + sibling *.dll |
appimage |
./x.AppImage --appimage-extract (no FUSE) |
binaries + transitive DT_NEEDED closure resolved in usr/lib (elf-needed.ts), symlink chains preserved |
Measured: MKVToolNix AppImage 153 MB → 55 MB; Windows MKVToolNix 260 MB → 50 MB; ffmpeg 315 MB → 101 MB. mkvmerge/mkvextract link libQt6Core (and ICU), so removing Qt wholesale breaks them; the closure is computed from the ELF headers rather than ldd.
Runtime usage
const { path, env } = await sidecars.resolve('mkvmerge')env is mandatory for AppImage-derived binaries: without LD_LIBRARY_PATH=<root>/usr/lib they fail to load their libraries. Spawn through ProcessRunner (optional timeout, SIGTERM → SIGKILL after a grace period, stderr logged, onStdoutLine for line-based progress such as mkvtoolnix --gui-mode, children tracked and killed by disposeAll() on shutdown).
Layout under userData/bin
installed.json tool → { version, archiveSha256, archiveType, binaryRelativePath, installedAt }archives/<sha256>/ pruned, deduplicated contentsdownloads/<sha256>.<ext>[.part|.part.json]Known limitations
- Trust root is the
mainbranch of this repository: whoever can changemanifests/sidecar.jsoncan change what is executed. Keep the branch protected; manifest signing is a possible future step. - Upstream links must be versioned. Rolling links (e.g.
ffmpeg-release-essentials.7z) break the pinned SHA-256 on the next upstream release (safe failure:CHECKSUM_MISMATCH). - Windows execution was verified with the pruned binaries under wine; native Windows execution is covered by the CI smoke test only for the app itself, not for sidecar installation.
The native consent dialog follows the app language (ui.language, else the system locale; src/main/services/sidecar-consent-text.ts), in English and Brazilian Portuguese.