Skip to content

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[] with name, version, executableName and artifacts[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 raises INVALID_MANIFEST instead of silently falling back.

Bumping a sidecar

  1. Edit manifests/sidecar.json: version, url and sha256 (lowercase hex, sha256sum of the exact file at the URL) per platform; set updatedAt. Keep two-space indentation.
  2. npx vitest run src/main/sidecars/manifest.schema.test.ts (CI runs it too and rejects invalid manifests). Copy the file to src/main/sidecars/__fixtures__/sidecar.json, which a test keeps identical.
  3. Merge to main: running apps pick it up on the next sidecars:check (the manifest is not tied to an app release). Versions are pinned, so any change marks the tool outdated and 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 days

Cancellation (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:

  1. rename(pruned, final) with backoff on EPERM/EBUSY/EACCES (~10 s total on Windows, ~0.7 s elsewhere).
  2. Recursive copy of the pruned tree to final (the locked source is left to cleanup/GC).
  3. Same two steps with the full tree, which was never executed by the app and has no probe handle.
  4. 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.json stores a validator (strong ETag or Last-Modified). The next attempt sends Range: bytes=N- + If-Range. 206 with a matching Content-Range appends (the existing bytes are re-hashed first); 200 restarts from zero; 416 discards the part.
  • Retry: up to 4 attempts, backoff 1 s → 8 s, only for NETWORK errors. Cancellation and network failures keep the .part; CHECKSUM_MISMATCH deletes it.
  • 30 s idle timeout, redirects to http are 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 contents
downloads/<sha256>.<ext>[.part|.part.json]

Known limitations

  • Trust root is the main branch of this repository: whoever can change manifests/sidecar.json can 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.