Route Wallpaper Engine video projects to video-native backends and clean up conflicting renderers

[louzt]

Closes #277

Summary

Route Wallpaper Engine video projects to video-native backends (mpvpaper or gslapper) when available, instead of sending static video loops through linux-wallpaperengine.

This keeps scene and web projects on linux-wallpaperengine, while allowing raw video projects to use backends that already specialize in video playback.

Why

Wallpaper Engine video projects are different from interactive scene/web projects: their project.json points to a concrete media file such as .mp4 or .webm. When Waypaper can identify that intent, handing the media file to a video-native backend avoids unnecessary renderer work and keeps idle desktop playback on the simpler path.

The practical effect is a cleaner backend choice:

• video projects can use the existing video playback backends
• scene/web projects still use linux-wallpaperengine
• transitions clean up conflicting dynamic renderers before launching the new backend

Architecture

This branch is standalone on top of main; it does not require #279 to be merged first.

To keep the same module boundary requested in #279 without making this PR depend on the full launcher-hardening branch, this PR adds a small waypaper/wallpaperengine.py helper module containing only the metadata/routing pieces needed for video handoff:

• project directory normalization
• project.json loading and type normalization
• real entry-file resolution for video projects
• backend recommendation for video projects

waypaper/changer.py remains the high-level dispatcher: it asks the helper module for the project intent, then calls change_with_mpvpaper(), change_with_gslapper(), or the normal linux-wallpaperengine path.

If #279 lands first, the shared module boundary can be reconciled during a normal rebase. If #279 does not land, this PR still remains reviewable as the narrow video-routing slice.

Scope Boundary

• No default configuration policy is changed.
• No scene/web project is rerouted away from linux-wallpaperengine.
• Video-native handoff is skipped unless the target backend is already available in Waypaper's installed backend list.
• Renderer-side web/runtime compatibility remains separate from this PR.

Validation

• python3 -m py_compile waypaper/changer.py waypaper/common.py waypaper/wallpaperengine.py tests/test_wallpaperengine.py
• python3 -m unittest discover -s tests
• git diff --check origin/main...HEAD

Current result: 16 tests pass.

[louzt]

Additional local validation note: the current web cases I tested split into at least two groups. Mouse/parallax-driven web wallpapers such as EVA are detected correctly but may still look static on Wayland when the background surface does not receive pointer motion consistently. Audio/API-driven web wallpapers such as Customizable Module Visualizer can fail earlier in linux-wallpaperengine with runtime/property parsing limitations. I am treating that as follow-up compatibility hardening rather than broadening this video-handoff PR.

[louzt]

Rebased this branch onto current main and resolved the waypaper/changer.py conflict.

Resolution kept the newer upstream macOS backend change:

• System Events instead of the older Finder AppleScript path
• argv-based subprocess.Popen(["osascript", "-e", script]) instead of shell=True

and reapplied the PR's transition cleanup:

• cleanup_dynamic_backends(monitor) before setting a static macOS wallpaper

Validation after the rebase:

• python3 -m py_compile waypaper/changer.py waypaper/common.py
• git diff --check origin/main...HEAD

I also checked the PR state after push; GitHub now reports it as mergeable/clean.

[louzt]

Updated this branch after the #279 module-boundary work.

The important change is that #280 is still standalone on top of main: it now adds a small waypaper/wallpaperengine.py module for the video-handoff metadata helpers instead of placing those helpers in common.py or depending on the full #279 launcher-hardening branch.

So the review paths are independent:

• if Harden linux-wallpaperengine launcher resolution and failure reporting #279 lands first, this branch can rebase and reuse the same module boundary
• if Harden linux-wallpaperengine launcher resolution and failure reporting #279 does not land, Route Wallpaper Engine video projects to video-native backends and clean up conflicting renderers #280 still remains a narrow video-routing change for Prefer video-native backends for Wallpaper Engine video projects and stop conflicting renderers #277

Validation after the update:

python3 -m py_compile waypaper/changer.py waypaper/common.py waypaper/wallpaperengine.py tests/test_wallpaperengine.py
python3 -m unittest discover -s tests
git diff --check origin/main...HEAD

Result: 16 tests pass.

[anufrievroman]

Honestly, I don't know about passing some scenes to other backends. I think if the user explicitly selected WE as backend, it should not quietly use other backends for videos. It add this level of complexity for a very hypothetical problem. I think the user should be responsible for the choice of backend and see if the resource usage is acceptable or not. Like, if the user already has the mpvpaper or gslapper installed, I'd expect he to manually switch if the video playing with WE is too heavy.

[louzt]

Fair concern, and you're consistent with what you said on the issue.
I over-indexed on a local repro of WE videos going black and
pushed Waypaper into backend-selection territory it shouldn't own.
You're right.

This branch is now rebased onto current main (the conflict was in
changer.py against the merged #288 / #289 / #290 cleanup work) and
the silent rerouting is removed:

• get_wallpaperengine_recommended_backend and the mpvpaper /
  gslapper handoff blocks in change_with_linux_wallpaperengine
  are gone.
• cf.installed_backends is no longer consulted for routing.
• Waypaper keeps using whatever backend the user selected.

What stays on this branch, with the rerouting gone:

• waypaper/wallpaperengine.py as a small internal module for
  project.json normalization. Surface Wallpaper Engine project type in the UI #278 uses the same module name for
  its tooltip work, so this avoids two branches re-implementing the
  same helpers.
• cleanup_dynamic_backends(monitor, exclude=...) before each
  change_with_*. This isn't routing — it's making sure the chosen
  backend starts from a clean state. The "previous dynamic renderer
  still alive" failure mode is real for any backend switch on
  Wayland, not just WE.
• The find_process_pids helper that finds all matching PIDs. The
  old find_process_pid only returned the first match, which could
  leave a second mpvpaper -f socket-… alive on a multi-monitor
  switch.
• Tests for the metadata normalization and the PID-helper.

On the "user should be responsible for backend choice" point —
agreed, and I want to keep it that way. The one thing I'd add as a
small follow-up, only if you think it fits the design, is a one-line
advisory print from the WE path when the project is detected as a
video type:

Note: this is a Wallpaper Engine video project. linux-wallpaperengine
can be several times heavier than mpvpaper for raw .mp4 playback.
Switch the backend in the picker if the resource usage is a concern.

That doesn't change behavior — it just makes the tradeoff visible.
I have local CPU/battery measurements behind that "several times
heavier" claim and the script + hardware notes are reproducible. If
even that advisory print crosses the "Waypaper shouldn't comment on
backend choice" line for you, I'll drop it and keep the PR strictly
to the metadata module + cleanup.

Re: the #278 / #279 / #280 ordering — the three branches all touch
wallpaperengine.py, and two of them touch changer.py. The
least-painful merge order is probably #278 (smallest, tooltip-only,
~1 line in common.py) → #280 (this branch, reduced) → #279
(launcher-hardening, the bigger module + diagnostics). That way
#279 can rebase once at the end to consolidate wallpaperengine.py
without dragging behavioral changes.

I'll push the rebased + reduced branch shortly, re-run
python3 -m unittest discover -s tests against current main, and
ping back with the diff stat. Apologies for the scope creep on the
first pass.