[changt]

Summary

Fixes #140. A background change now takes effect only once the new background is ready. Until then, the current blur or image stays on screen. With neither a blur nor an image set, the composite shows the camera.

• renderFrame: with no blur and no image, composites against the frame itself instead of whatever bgTexture last held. A blur radius of 0 now shows the camera instead of a black background.
• setBackgroundImage: no longer clears customBackgroundImage or uploads the transparent placeholder when a change is requested. It sets and uploads the image only once the crop resolves, so swapping one image for another keeps the old image up until the new one lands. A crop whose image was replaced or cleared in the meantime, including by cleanup(), is dropped by comparing against backgroundSourceImage.
• setBlurRadius: no longer clears the image as a side effect.
• BackgroundTransformer.update(): loads the image before changing the blur, so blur → image keeps blurring until the image is ready instead of exposing the camera's own background. If a newer update() changes imagePath while the image is loading, the stale image is not applied and the newer blur is not cleared.

This is the distinction the issue asks for: leaving image mode releases the image straight away, while replacing one image with another holds the old one until the new one is ready.

Measured

Every frame of the published track recorded across each transition with the e2e probe, with createImageBitmap slowed by 300 ms to widen the loading window:

transition	main	this branch
blur → image, first time	7 black frames, then 9 white (placeholder)	none
image → image	9 white	none
blur → image, again	9 white	none
image → blur	none	none

Without the delay, both are clean in headless Chrome, because the harness images load and crop within one frame.

Tests

• Three new pipeline tests: clearing the blur shows the camera, clearing the image shows the camera, and the previous image stays up until the next one is ready. All three fail on main.
• Unit tests, typecheck and all 18 e2e tests pass locally.

Not covered by a committed test: the transformer's reordering (blur stays up while an image loads). Testing it needs a per-frame e2e case with a slowed image load, like the recording above.

[changeset-bot]

🦋 Changeset detected

Latest commit: 8983e1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@livekit/track-processors	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[1egoman]

Makes sense! Does this result in any change to the switching artifacts when jumping between blur and multiple background images? And are any e2e tests worth adding / updating as part of this? I see the test/webgl-pipeline.test.ts tests which seem to cover it pretty well but I'm unsure if there's anything alse that could be useful in the e2e suite.

[changt]

Makes sense! Does this result in any change to the switching artifacts when jumping between blur and multiple background images? And are any e2e tests worth adding / updating as part of this? I see the test/webgl-pipeline.test.ts tests which seem to cover it pretty well but I'm unsure if there's anything alse that could be useful in the e2e suite.

I tested this manually with the e2e harness app and verified there's no flickering. Note that the corresponding PR is needed, otherwise there's a built-in flicker with the media reload.