Skip to main content

Regenerating the demo assets

After changing the UI or fixture, regenerate in this order from the repository root:

make screenshots
make demo-output
make demo-output-trip
make demo-cli
make demo-ui
make demo-hero
make demo-ui DEMO_THEME=dark
make demo-hero DEMO_THEME=dark

The trip preview needs the network for map tiles and place names; everything else runs on the public fixture alone. The README's hero GIF is served by the docs site, so it changes when the docs deploy. The homepage picks the light or dark screenshots, posters and walkthrough to match the visitor's theme; finished films have no theme and share one preview.

The docs use the app’s pinned @immich/ui theme tokens. After updating that package in both projects, run npm --prefix docs-site run ui-theme; the docs build checks for token drift.

Fixture and asset contracts​

Use only the credited demo fixture (CC0 and CC BY) for public library pictures. The private test households are separate: their real-person photos must never appear in screenshots, demos, hosted previews or the public website. Only anonymous aggregate test results may leave them.

Nothing on the docs site or in the README is a screenshot of a real library. The demo is a React recreation of the UI rendered with Remotion over the demo library, the CLI demo is a VHS recording, and the app screenshots come from a hermetic run over the same library.

The library is 1,119 picture files and 7 clips under tests/e2e/fixtures/library/, all real files from Wikimedia Commons under CC0 or CC BY: one household's July 2025, ten days at home in Brussels and a road trip to Nordkapp that is one photographer's own holiday. make fixture-library builds it from sources.json (scripts/build_fixture_library.py): it checks each file's licence on the file, scales pictures to 1280 px (the ones a cut can reach) or 500 px (the rest), trims clips to five seconds at 720p, records each file's own GPS and capture time in library.json, pins the detected faces to the cast, and writes CREDITS.md. It needs the network and caches everything under ~/.cache/immich-memories-fixture, so a curation change only fetches what is new.

A picture is served with the GPS in its own file or with none, and at its own time moved by whole days at most (the trip not at all). One indoor series from one shoot (the birthday at home) may stand for the household's home and is served there; the test refuses a second one. tests/test_fixture_library.py pins that, the credits, the hashes and the 60 MB ceiling. tests/e2e/fake_library.py is the script on top: which picture carries which story (30 carriers), and a reason for every picture left out, most of them computed from the moments the photographers' own sets form.

The household is eleven people pinned onto real faces: Kit (27 pictures), Robin, Charlie, Remy, Pat, Jo, Lou and Alex clear the people floor, and Sasha, Mo and Nico are the tail a real library has. The faces are strangers from CC0 and CC BY stock shoots, so a person's pictures don't show one face; the pinned boxes make Immich group them anyway. The people pictures carry no GPS: a stock photo's own place would be a lie in a Brussels July.

The household also carries the facts a real one keeps: Robin owns the library, Charlie is Robin's partner, Kit their child (born 5 July, so the 5th is a birthday), and Pat and Lou are Robin's parents. Immich holds the birth dates; the People page's registry holds who is who (household_people in tests/e2e/fake_library.py, which the feature suite and the recordings import with people import). That is what lets a film find "Kit's birthday" or the grandparents' visit from facts.

Each memory type was also cut once for real: Full tier, a local model, a real Immich seeded with the library (scripts/record_demo_runs.py). Its decisions sit under tests/e2e/fixtures/recordings/<memory type>/: the plan, the decision trace, the render projection and the run's own story. Setting IMMICH_E2E_RECORDING=<memory type> makes the hermetic editor replay that cut instead of the scripted one, so docs and demos show what the product chose without running a model again. Record again only when the library or the editor changes on purpose. make screenshots replays the recorded month (DEMO_RECORDING=monthly_highlights); the tests themselves keep the scripted cut.

The three tiers page is that month cut once more on each tier, against the same seeded Immich: scripts/record_tier_example.py --state <real_seed state.json> --home <dir> gives Basic, GPU and Full a home each, so nothing one tier prepared reaches the next, and the same bundled track. GPU and Full read the caption server the Apple Silicon setup starts on port 8092, Full the model your own config names, and the GPU tier needs laya-mlx installed. It writes the films, their contact sheets and provenance.json under docs-site/static/demo/tiers/.

The Synology setup screenshots under docs-site/static/img/platforms/ come from the real DSM project and folder dialogs. Capture only the relevant dialog, with generic example names. Exclude server addresses, account names, keys and unrelated projects before saving the image. These captures verify the controls shown, not a completed installation.

The demo shows the recorded run of the month (DEMO_RECORDING=monthly_highlights, the same one the screenshots replay), not the scripted cut. make demo-fixture reads that recording: its one-line summary, its 15 pictures in cut order with the reason the run gave each, its stories heaviest first, and for every other picture the reason the run left it out. The edit scene swaps the first still that has another picture of its moment and removes the first lone still after it; both picks come from the cut (active_edit in tests/e2e/fake_editorial.py), and the output clip is cut with the same two edits, saved as revision 1 and rendered at 1080p without music. The finished film is about 57 seconds; the walkthrough adds its own soundtrack. The generated fixture carries the cut's timeline positions, its weighed stories, the seconds the titles leave the pictures and where the film's last photograph ends.

The fixture has 1,126 media files on disk and serves 1,131 assets (1,124 photos, 7 videos): a few files stand for more than one asset, so the pool count in the demo is not the file count.

Command (repo root)Produces
make demo-uidocs-site/static/demo/demo.mp4, 2,754 video frames at 30 fps (about 92 s), 1920×1080 H.264; it shows the film the product made, then holds a closing frame with the docs address
make demo-herodocs-site/static/img/demo-hero.gif, the README hero: the brief, the cut and the review, then Render pressed and the film arriving on the page, then that film full bleed from the moment the page's player shows (the shared timeline supplies the windows), 720 px, 10 fps, under 4 MB
make demo-clidocs-site/remotion/public/cli-demo.mp4 and docs-site/remotion/src/cli-timing.ts, VHS recording the real CLI: scripts/demo-cli-hermetic.py runs generate, runs story and runs why against the hermetic fakes from tests/e2e, types each command, and writes the second each one starts at so the scene cuts there; it also copies the video to docs-site/static/demo/cli-demo.mp4 and cuts its poster cli-demo-poster.jpg, which the homepage's CLI section plays (make demo-cli-run plays the same session without recording; as root in a container, set VHS_NO_SANDBOX=true)
make demo-outputdocs-site/remotion/public/output-preview.mp4 and output-frame.jpg, cut on the hermetic launch
make demo-output-tripdocs-site/static/demo/trip-preview.mp4 and docs-site/static/img/trip-map-flyover.jpg, the fixture's road north cut as a trip memory asked for 40 seconds and the still of its map fly-over, both played by the trip memory page. Needs the network: the satellite tiles come from ArcGIS World Imagery and the trip's name from Nominatim, and neither has an offline stand-in
make demo-soundtrackdocs-site/remotion/public/demo-music.wav, crossfaded and normalised from a bundled acoustic track; also runs with make demo-ui
make demo-musicOptional ACE-Step candidates under docs-site/static/demo/music-candidates/
make screenshotsthe light and dark screenshots under docs-site/static/img/screenshots/
make demo-ui-devRemotion Studio for a live preview

make demo-ui-install copies tests/e2e/fixtures/library to docs-site/remotion/public/library (credits in its CREDITS.md), so the demo shows the same pictures as the tests and the docs. The demo never shows a screenshot: every UI frame is the web client recreated in React.

The order that keeps everything consistent after a UI or a fixture change: make screenshots, then make demo-output and make demo-output-trip, then make demo-cli, then make demo-ui (which runs make demo-fixture first, exporting the fixture's cut and first pool page into docs-site/remotion/src/fixture.ts), then make demo-hero. The hero GIF is served from the docs site, so it reaches the README on the next docs deploy, not on the next push.

The soundtrack uses happy_acoustic_s411.opus from the project's bundled music package, under the same MIT licence (see packages/immich-memories-music/LICENSE-MUSIC). The recipe crossfades four copies with three-second overlaps, normalises to -18 LUFS with a -2 dB true-peak ceiling, and leaves the fade-in and fade-out to Remotion. It needs no model, API key or media download.

The homepage embeds the full demo with controls and a matching light or dark poster. It autoplays muted, with controls to enable sound. When reduced motion is enabled, the poster stays still until the viewer presses Play. The README shows the short hero GIF and links to the full demo with sound. The finished trip film remains available beside the demo.

The scenes live in docs-site/remotion/src/scenes/, the client's pieces (the app shell, the job panel, the run page, the render panel) in docs-site/remotion/src/components/. Each names the Svelte file under web/src it recreates. When a page name or a button changes in the client, the scene changes with it.

Keep the UI workflow together: brief, cut in progress, review, the edit saved as a revision, render, the film on the page. Runs and Suggestions follow, then the CLI goes straight into the rendered film. The CLI scene plays generate as a time-lapse and holds runs story and runs why long enough to read; it cuts the recording at the seconds in cli-timing.ts, so a new recording moves the cuts with it. Every UI frame is set in Inter from the file the web client serves (make demo-ui-install copies src/immich_memories/web/static/fonts to public/fonts), so a render needs no network. They are copies, not symlinks: a link into src/ or tests/ makes the packaging skip the real folder. The review scene shows the contact sheet and the picture inspector. Its pictures, reasons and stories come from the same fixture as the browser tests; it must not invent model proposals that the fixture did not record. Rebuild the Remotion demo and hero after changing the client's layout. The demo shows the product working: an error card, even a helpful one, reads as the product failing, so refusals live in the install docs, not in a scene.

The opening and closing frames use the docs logo, Inter and the shared colour tokens. Scene headings name the action outside the app window. Preparation and rendering are labelled as sped up; the finished film plays at normal speed.

docs-site/remotion/src/timeline.ts holds scene lengths, transition overlaps and the selected passage of the fixture film. The composition and hero script both read it. After re-cutting the fixture film, review that passage at normal speed: keep complete shots and end before the next shot begins. The last picture holds before the dissolve into the closing frame. The soundtrack fades with that frame and ends half a second before the video.

Check every scene in both themes: text and controls must be readable, the cursor must hit the control it demonstrates, and the UI must match the client. make demo-ui extracts frame 65 from each full demo as its homepage poster, saved as demo-poster.jpg and dark-demo-poster.jpg under docs-site/static/demo/. The fixture film's titles and dates are rendered in English.