Making vivo / iQOO dual-file live photos work in Immich (merge + link, no fork)

[duruonanni]

Sharing a small tool in case anyone else has a phone that splits live photos into two files.

The problem

My vivo X100 Ultra (also iQOO, and some OPPO/realme builds) saves a live photo as two loose files:

IMG_20260101_120000.jpg
IMG_20260101_120000.mp4     # ~2 s

They're joined only by a private vivo Live Photo ID that Immich never reads, so both detection
paths in metadata.service.js miss them — Apple's ContentIdentifier pairing and the Android
Camera:MotionPhoto / MicroVideo single-file formats.

The consequences:

• the timeline shows the photo and a 2-second clip as two separate assets;
• downloading the photo hands you two files instead of one moving picture;
• on Windows the clip plays as a black frame with audio.

The black frame is not an Immich bug

This one cost me a while, so it's worth stating: the clips are full-range yuvj420p with
color_range=pc, and the Windows hardware decoding path renders them black. The very same file
plays fine in Chromium on Linux (software decoding), which is what made it look like an Immich
problem. Re-encoding to yuv420p / tv / bt709 fixes it, and also cuts the file size roughly
in half.

What I ended up building

https://github.com/duruonanni/motion-photo-bridge (MIT, Python 3.10+, ffmpeg)

1. Merge the pair into a real Motion Photo — one JPEG, clip appended, Container:Directory XMP.
   The photo's pixels and the entire EXIF segment are copied byte for byte (verified by hashing the
   segment before and after).
2. Optionally re-encode full-range clips so Windows plays them.
3. Link the assets in Immich: livePhotoVideoId on the image and visibility=hidden on the
   clip — exactly what Immich does for a phone it recognises.

For photos already in the library there's no need to delete and re-upload:
tools/apply_batch.py replaces the image file in place and moves the clip under encoded-video/,
so asset IDs, albums, tags, favourites and dates all survive. I ran it over 878 pairs (~55 min,
every pair backed up first). The download archive is now a single .jpg, and the timeline shows
one picture with a motion button.

Integration: workflow + webhook, no fork

I deliberately didn't fork Immich. It uses a Workflow (AssetCreate, filename matches \.mp4$)
that POSTs to a small receiver, which then calls the official API. Two details that cost me time
and might save someone else:

• Workflows are scoped to their owner — workflowRepository.search({userId: asset.ownerId}).
  The workflow must be created by the account that uploads the photos; an admin creating it on their
  behalf will never fire.
• From inside the container, reach a host service at http://172.17.0.1:<port>.
  host.docker.internal isn't configured in the stock compose file.
• If the clip lands before its photo, the receiver reports defer; the next upload or a periodic
  sweep catches it.

Why not a plugin?

The plugin system is clearly coming along — @immich/plugin-sdk, the Extism JS PDK, and host
functions including httpRequest that do exactly what my receiver does. But on v3.3.3
/api/plugins only exposes GET routes (/, /:id, /methods, /templates); there's no
install/upload endpoint yet, so a workflow webhook is still the only supported way in from outside.
Once plugins can be installed, this maps onto one almost directly.

Happy to answer questions — and I'd love to hear from anyone whose phone uses a different pairing
scheme, since same-stem JPG + MP4 may not be the only convention out there.