perf(audio): stretch speed regions through libavfilter atempo instead of WSOLA — fixes exports frozen at ~80%

crates/compositor/build.rs

@@ -69,7 +69,7 @@ fn main() {
     if let Some(v) = ff.as_ref() {
         let lib_dir = Path::new(v).join("lib");
         println!("cargo:rustc-link-search=native={}", lib_dir.display());
-        for lib in ["avformat", "avcodec", "avutil", "swscale", "swresample"] {
+        for lib in ["avformat", "avcodec", "avutil", "swscale", "swresample", "avfilter"] {
             println!("cargo:rustc-link-lib=dylib={}", lib);
         }
     }

crates/compositor/wrapper_linux.h

@@ -12,3 +12,6 @@
 #include <libavutil/pixdesc.h>
 #include <libswresample/swresample.h>
 #include <libswscale/swscale.h>
+#include <libavfilter/avfilter.h>
+#include <libavfilter/buffersrc.h>
+#include <libavfilter/buffersink.h>

crates/compositor/wrapper_macos.h

@@ -17,4 +17,7 @@
 /* Software decode path : swscale était déjà LIÉ (build.rs) sans être bindé.
    Conservé identique côté macOS pour que la symétrie avec cpu_frames_windows.rs
    soit claire ; le code effectif vit dans mac_frames.rs. */
-#include <libswscale/swscale.h>
+#include <libswscale/swscale.h>
+#include <libavfilter/avfilter.h>
+#include <libavfilter/buffersrc.h>
+#include <libavfilter/buffersink.h>

crates/compositor/wrapper_windows.h

@@ -12,3 +12,6 @@
    elle couvre les formats exotiques (10 bits, 4:2:2) qu'un interleave écrit à la
    main casserait silencieusement. */
 #include <libswscale/swscale.h>
+#include <libavfilter/avfilter.h>
+#include <libavfilter/buffersrc.h>
+#include <libavfilter/buffersink.h>

nix/compositor-view.nix

@@ -132,7 +132,18 @@ rustPlatform.buildRustPackage {
     # Copy each library under its soname and read its symbol table. awk rather
     # than sed with a backreference: the third field is the name, and anything
     # after an @ is the version tag.
-    for lib in ${ffmpegLgpl.lib}/lib/lib{avformat,avcodec,avutil,swscale,swresample}.so.*; do
+    #
+    # The list must hold every library crates/compositor/build.rs emits a
+    # cargo:rustc-link-lib for -- all six of them, avfilter included since the
+    # speed-region stretch runs through atempo. Miss one and the build either
+    # dies on `cannot find -lavfilter` (no unversioned symlink is staged for it
+    # below) or links the store's UN-renamed copy, and a cdylib tolerating
+    # undefined symbols means the failure surfaces only at require() time as
+    # "undefined symbol: osff_avfilter_graph_alloc" -- the addon then loads as a
+    # no-op and preview plus every export are dead. avfilter's exports are all
+    # av-prefixed (avfilter_*, av_buffersrc_*, av_buffersink_*), so the awk
+    # filter here and the leak check in installPhase already cover them.
+    for lib in ${ffmpegLgpl.lib}/lib/lib{avformat,avcodec,avutil,swscale,swresample,avfilter}.so.*; do
       case "$lib" in *.so.*.*) continue ;; esac
       test -f "$lib" || continue
       cp "$(readlink -f "$lib")" "$stage/lib/$(basename "$lib")"
@@ -190,7 +201,7 @@ rustPlatform.buildRustPackage {
     # Each copy still carries the RUNPATH it inherited from the original ffmpeg
     # output, which is where the UN-renamed libraries live -- so libavcodec's own
     # osff_swr_init would resolve against a libswresample that defines swr_init.
-    # It only works today because all five happen to be direct DT_NEEDED of the
+    # It only works today because all six happen to be direct DT_NEEDED of the
     # addon, so $ORIGIN is searched first; the day --as-needed drops one the
     # loader falls through to the store copy and dlopen fails on an undefined
     # osff_ symbol. Put $ORIGIN in front so the renamed set can only resolve

scripts/before-pack.cjs

@@ -75,13 +75,16 @@ const MAC_REQUIRED = [
 		breaks: "the preview and every export render nothing",
 		fix: FIX_MAC,
 	},
-	{
-		match: (name) => /^libav(codec|format|util)\.\d+\.dylib$/.test(name),
-		what: "the LGPL ffmpeg dylibs the compositor links",
+	// One requirement per library, not `atLeast: N` over a combined regex — the
+	// same trap LINUX_REQUIRED documents above. Several versioned copies of one
+	// library would satisfy a combined count while another was missing entirely,
+	// and the addon would still fail to load.
+	...["avcodec", "avformat", "avutil", "swresample", "swscale", "avfilter"].map((library) => ({
+		match: (name) => new RegExp(`^lib${library}\\.\\d+\\.dylib$`).test(name),
+		what: `the LGPL lib${library} dylib the compositor links`,
 		breaks: "the compositor addon cannot be loaded at all (dyld error at require())",
 		fix: FIX_MAC,
-		atLeast: 3,
-	},
+	})),
 	{
 		match: (name) => name === "whisper-stt-server",
 		what: "the whisper.cpp STT helper",
@@ -131,7 +134,7 @@ const LINUX_REQUIRED = [
 	// pendant qu'une autre manquait. Le paquet passait alors la garde et le
 	// compositeur ne chargeait pas : exactement le mode de panne que cette garde
 	// existe pour attraper.
-	...["avcodec", "avformat", "avutil", "swresample", "swscale"].map((library) => ({
+	...["avcodec", "avformat", "avutil", "swresample", "swscale", "avfilter"].map((library) => ({
 		match: (name) => new RegExp(`^lib${library}\\.so\\.\\d+$`).test(name),
 		what: `the symbol-renamed lib${library} shared object the compositor links`,
 		breaks: "the compositor addon cannot be loaded at all (ld.so error at require())",
@@ -234,7 +237,7 @@ const WIN_REQUIRED = [
 	// (avcodec-60/61/62.dll left by an earlier fetch) would satisfy a combined count
 	// while another library was missing entirely, and the addon would still fail to
 	// load.
-	...["avcodec", "avformat", "avutil"].map((library) => ({
+	...["avcodec", "avformat", "avutil", "swresample", "swscale", "avfilter"].map((library) => ({
 		match: (name) => new RegExp(`^${library}-\\d+\\.dll$`).test(name),
 		what: `the ${library} DLL the compositor links`,
 		breaks: "the addon cannot be loaded at all under MSIX, which ignores PATH",

scripts/build-linux-compositor-addon.mjs

@@ -16,7 +16,7 @@
 //      (ensureFfmpegSharedDllsOnPath), but glibc reads LD_LIBRARY_PATH once at
 //      process start, so the equivalent trick cannot work after Electron is
 //      already running. Instead the addon is linked with `-rpath,$ORIGIN` and
-//      the five ffmpeg sonames are copied next to it, which makes the .node
+//      the six ffmpeg sonames are copied next to it, which makes the .node
 //      self-contained wherever it is installed — no env var, no PATH surgery.
 
 import { spawnSync } from "node:child_process";
@@ -36,6 +36,7 @@ const FFMPEG_SONAMES = [
 	"libavutil.so.60",
 	"libswscale.so.9",
 	"libswresample.so.6",
+	"libavfilter.so.11",
 ];
 
 const run = (command, args, options = {}) =>

scripts/fetch-ffmpeg.mjs

@@ -407,13 +407,33 @@ async function fetchSharedDlls(tag, binDir) {
 		return;
 	}
 
-	// probe for any previously vendored DLL by name; re-download is driven by
-	// --force same as the static exe, checked once we know what we'd extract.
-	const alreadyVendored =
-		process.platform === "win32" &&
+	// Completeness probe, not a mere existence probe. The compositor addon now
+	// links six shared ffmpeg DLLs — see crates/compositor/build.rs
+	// (avcodec, avformat, avutil, swresample, swscale, avfilter). A warm dev/CI
+	// tree that already holds the five pre-avfilter DLLs would satisfy an "any
+	// av*.dll is present" check and let `avfilter-11.dll` go un-vendored, breaking
+	// require() at runtime (OpenScreen#371 review, EtienneLescot). Require all
+	// six explicitly so a missing one forces a re-vendor.
+	const REQUIRED_SHARED_DLLS = [
+		"avcodec",
+		"avformat",
+		"avutil",
+		"swresample",
+		"swscale",
+		"avfilter",
+	];
+	fs.mkdirSync(binDir, { recursive: true });
+	const vendoredFiles = new Set(
 		fs
 			.readdirSync(binDir, { withFileTypes: true })
-			.some((e) => e.isFile() && isSharedLib(e.name) && /^(lib)?av/i.test(e.name));
+			.filter((e) => e.isFile())
+			.map((e) => e.name),
+	);
+	const alreadyVendored =
+		process.platform === "win32" &&
+		REQUIRED_SHARED_DLLS.every((lib) =>
+			[...vendoredFiles].some((f) => new RegExp(`^${lib}-\\d+\\.dll$`).test(f)),
+		);
 	// The build-time SDK comes out of this same archive, so a tree that has the
 	// DLLs but not the SDK must still re-download — otherwise we skip here and
 	// the compositor build fails afterwards on the missing FFMPEG_DIR.

technical-documentation/architecture/export-pipeline.md

@@ -61,18 +61,30 @@ and **one** encoder + muxer pair:
   per-segment rounded frame counts into a single output frame counter;
   audio follows the same integer accumulation (`AudioConcatPlan`).
 
-- **Audio and video junctions are seamless.** Audio is decoded per
-  segment up front (`audio.rs::decode_clip_audio`), WSOLA stretches each
-  speed sub-segment to its output sample count, and
+- **Audio and video junctions are seamless.** Audio is decoded per clip
+  (`audio.rs::decode_clip_audio`), a libavfilter `atempo` chain stretches
+  each speed sub-segment to its output sample count, and
   `assemble_concatenated_pcm` concatenates the per-segment PCM at the
   integer sample offsets the video loop just produced — never
   `round(cumulativeSec * sampleRate)`, because that compounds per-segment
   rounding error into audible A/V drift across a long multi-segment
   timeline. A short equal-power fade (`cos` on the tail, `sin` on the
   head, `cos² + sin² = 1`) covers each internal boundary to suppress the
   click where two recordings meet butt-joined, without shifting timing.
-  The WSOLA stretch is kicked off before the video loop so it overlaps
-  the encode and does not add to the wall.
+  The in-tree WSOLA stretcher is still there, but only as the fallback
+  `stretch_pcm_to_length` takes when the filter chain cannot be built or
+  yields too little audio (see [Audio](native-compositor.md#audio)).
+
+- **The stretch is not overlapped with the encode.** Decode and stretch
+  run inside `walk_composited_timeline`'s `on_clip_end` callback
+  (`pipeline.rs`), which fires once per clip *after* that clip's frames
+  have been composed and encoded, on the same thread — so the stretch
+  time is added to the export wall, not hidden behind it. `progress()` is
+  driven only by encoded video frames, so nothing moves while it runs and
+  a long clip parks the export at whatever percentage the last frame
+  reported. That is why the `atempo` path matters: it is O(n) where WSOLA
+  is O(grain × radius) per rendered sample, which on a long clip meant
+  minutes of an apparently frozen export.
 
 - **Output** honours the timeline's selected aspect ratio
   (`resolveAspectRatioValue` over `getEditorSettings(document).aspectRatio` —

technical-documentation/architecture/native-compositor.md

@@ -31,7 +31,7 @@ and without that flag the runtime corruption is silent.
 | [`crates/compositor/src/scene.rs`](../../crates/compositor/src/scene.rs) | the `Scene` struct parsed from the app's `SceneDescription` JSON |
 | [`crates/compositor/src/regions.rs`](../../crates/compositor/src/regions.rs) | zoom / speed / Full Camera regions — envelope shapes and per-frame state sampling |
 | [`crates/compositor/src/pipeline.rs`](../../crates/compositor/src/pipeline_windows.rs) | demux + `D3D11VA` decode + composite + AMF encode + mux (`run_c0` for decode/encode only, `run_composited` for the full path) |
-| [`crates/compositor/src/audio.rs`](../../crates/compositor/src/audio.rs) | per-clip audio decode, swresample → f32 planar 48 kHz stereo, WSOLA speed stretch, multi-track mix, AAC encoder |
+| [`crates/compositor/src/audio.rs`](../../crates/compositor/src/audio.rs) | per-clip audio decode, swresample → f32 planar 48 kHz stereo, libavfilter `atempo` speed stretch (WSOLA fallback), multi-track mix, AAC encoder |
 | [`crates/compositor/src/cursor.rs`](../../crates/compositor/src/cursor.rs) | `.cursor.json` parser + interpolated cursor track (position, click bounces, adaptive follow samples) |
 | [`crates/compositor/src/text.rs`](../../crates/compositor/src/text_windows.rs) | DirectWrite + Direct2D text rasterisation for annotation labels, cached per (content, style, box) |
 | [`crates/compositor/src/text_anim.rs`](../../crates/compositor/src/text_anim.rs) | text-annotation appearance animations (port of the TS animation curves, in fractions of the output short side) |
@@ -199,9 +199,28 @@ each track is recut to the same `[source_start_sec, source_end_sec)` —
 pads in front for late-starting tracks, trims the pre-roll for early-decoded
 ones — so a summing mixer is enough and a real mix matrix is not needed.
 
-Speed regions apply after decode: WSOLA stretches each speed sub-segment to
-its output frame count, sharing search positions across channels from a
-mono down-mix (so the stereo image does not wander between channels).
+Speed regions apply after decode: `stretch_pcm_to_length` stretches each
+speed sub-segment to its output frame count through a libavfilter
+`abuffer → atempo… → abuffersink` graph built in-process
+(`avfilter_atempo_stretch`). The graph is pinned to the fltp / 48 kHz /
+stereo format `decode_clip_audio` already produces, and `atempo` preserves
+format, channels and rate, so no conversion is involved; the result is
+recut to the exact target length by truncation or zero-padding. `atempo`
+only accepts a factor in `[0.5, 100.0]`, so `atempo_factors` chains
+several instances whose product is the requested speed (0.2 →
+`[0.5, 0.5, 0.8]`).
+
+The in-tree WSOLA stretcher remains as the fallback, taken whenever
+`avfilter_atempo_stretch` returns `None` — the graph could not be built or
+configured, a buffersrc/buffersink call failed, or the chain drained fewer
+than 90% of the target samples, which is what happens on a span too short
+for `atempo`'s analysis window (a few tens of milliseconds between two
+speed regions). WSOLA shares its search positions across channels from a
+mono down-mix, so the stereo image does not wander between them. The move
+to `atempo` is a cost change, not a quality one: WSOLA is
+O(grain × radius) per rendered sample, minutes of a full core on a long
+clip, against `atempo`'s O(n) with ffmpeg's SIMD routines.
+
 Across segments, `build_audio_concat_plan` sizes each segment's PCM by
 **integer accumulation of the per-segment rounded sample count**, never
 `round(cumulativeSec * sampleRate)` — that single change is what keeps A/V

technical-documentation/engineering/build-and-packaging.md

@@ -42,7 +42,7 @@ Electron-builder copies only the matching `electron/native/bin/<platform>-<arch>
 
 This is a hard requirement on Windows, not a tidiness preference.
 
-The addon dlopens `avcodec`/`avformat`/`avutil` at `require()` time. Until 1.9.0 the Windows build shipped it inside `app.asar.unpacked/electron/native/compositor-view/build/`, one directory away from `electron/native/bin/win32-x64/*.dll`, and the gap was bridged at runtime by `ensureFfmpegSharedDllsOnPath` prepending the DLL directory to `PATH` before the require.
+The addon pulls in six ffmpeg libraries at `require()` time — `avcodec`, `avformat`, `avutil`, `swresample`, `swscale` and `avfilter`, the exact set `crates/compositor/build.rs` emits `cargo:rustc-link-lib` lines for. (`avfilter` is the newest of them: the speed-region time stretch runs through its `atempo` filter.) Until 1.9.0 the Windows build shipped it inside `app.asar.unpacked/electron/native/compositor-view/build/`, one directory away from `electron/native/bin/win32-x64/*.dll`, and the gap was bridged at runtime by `ensureFfmpegSharedDllsOnPath` prepending the DLL directory to `PATH` before the require.
 
 That works for the NSIS installer. **It does not work under MSIX**, which resolves an addon's dependent DLLs through the package graph and ignores `PATH`. Measured inside a registered package, with the directory verifiably present and correctly prepended to `PATH`:
 
@@ -60,7 +60,7 @@ require BEFORE PATH : LOADED OK
 
 Node loads `.node` files with `LOAD_WITH_ALTERED_SEARCH_PATH`, so the addon's own directory is searched for its dependencies. Colocating removes the `PATH` mechanism rather than repairing it, and works on every Windows packaging format.
 
-This shipped: the 1.9.0 Store build loaded no compositor at all, so the editor opened with a permanently blank preview while audio kept playing — audio comes from the renderer, every frame comes from the addon. It read as an application bug rather than a packaging one, because every file was present in the package and the NSIS build of the same commit was fine. `scripts/before-pack.cjs` now refuses to package unless the addon and at least `avcodec`/`avformat`/`avutil` are in the same directory, on Windows as it already did on macOS.
+This shipped: the 1.9.0 Store build loaded no compositor at all, so the editor opened with a permanently blank preview while audio kept playing — audio comes from the renderer, every frame comes from the addon. It read as an application bug rather than a packaging one, because every file was present in the package and the NSIS build of the same commit was fine. `scripts/before-pack.cjs` now refuses to package unless the addon and all six of those libraries are in the same directory, on Windows as it already did on macOS. It checks one requirement **per library** rather than a count over a combined pattern, on all three platforms: several versioned copies of one library (an `avcodec-60`/`61`/`62.dll` left by an earlier fetch) would satisfy a combined count while another was missing entirely, and the addon would still fail to load.
 
 `electron/native/bin/`, local native build directories, the compositor build output, models, and caches are gitignored. Rebuilding from a source checkout therefore requires the complete platform toolchain and third-party SDKs; running the generic `npm run build` alone does not manufacture missing native artifacts. The Windows compositor's D3D11/FFmpeg prerequisites are described by the source POC in `crates/README.md`, while capture helper lookup and output conventions are documented in `electron/native/README.md`.
 
@@ -204,7 +204,7 @@ The hook now reads `electron/native/bin/darwin-<arch>/` — the directory `mac.e
 | Required | Without it |
 |---|---|
 | `compositor_view.node` | preview and every export render nothing |
-| `libavcodec/libavformat/libavutil.*.dylib` | the addon cannot load at all (dyld error at `require()`) |
+| `libavcodec/libavformat/libavutil/libavfilter/libswresample/libswscale.*.dylib` | the addon cannot load at all (dyld error at `require()`) |
 | `whisper-stt-server` | transcription and captions fail with a developer error shown to end users |
 | `libggml*.dylib` | the helper dies in dyld before `main()`; STT times out with no diagnostic |
 | `openscreen-screencapturekit-helper` | native screen capture unavailable |