Apple Silicon with local services
Run natively to use the Mac's GPU: Metal for preparation, titles and photo moves, VideoToolbox for decode and encode. The app, captions and the text reader stay on one Mac; Immich can live elsewhere on your network. For a packaged install without local music generation, use the Python install.
Your Immich
Immich Memories
Caption server
Metadata + previewsPreparation starts with your library; originals remain in Immich.
Preview tiles + framesImages go to the caption service; the text reader is a separate role.
The app and caption runtime share one Mac. Captions and the reader are enabled in this recipe; generated music is optional. Select a service for details.
Timings for this path, on Metal and VideoToolbox, are in the measured examples.
Install the app
For a source checkout, install uv, ffmpeg-full, exiftool and Node 22 first. Use Python 3.12 if you plan to add
local ACE-Step. From your release checkout:
brew install uv ffmpeg-full exiftool llama.cpp
export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"
ffmpeg -hide_banner -filters | grep zscale
git clone https://github.com/sam-dumont/immich-memories.git
cd immich-memories
git checkout YOUR_RELEASE_TAG
make dev
make dev-mac
uv pip install --python .venv/bin/python "laya-mlx>=0.2,<0.6"
uv run --no-sync python -c "import pi_heif, laya_mlx"
Replace YOUR_RELEASE_TAG with the release tag you intend to run. The Mac extras install the
Metal bindings, but not laya-mlx. The extra install above supplies the audience classifier
used by GPU and Full. pi-heif is already a base dependency for HEIC decoding. Keep the FFmpeg
PATH export in your shell startup file and in the environment used to launch a service.
After changing checkout revisions, rerun make dev-mac and the laya-mlx install before
starting the app. Copying source into an older environment does not update dependencies.
The --no-sync commands below preserve that separately installed runtime; an explicit sync
may require installing it again. Development setup covers source tools;
the requirements page covers memory and supported platforms.
Set your Immich connection in Settings or a small config file.
Keep the normal tier: auto setting. Start the
local caption server in another
terminal, using its pinned model and smolvlm2-500m-base-public alias. The llama.cpp recipe
holds less resident memory than an mlxcel service; if you already run one, stop it, or both models
stay loaded. For an app on this same Mac,
bind the caption server to 127.0.0.1.
Connect captions and the reader
advanced:
editorial:
preparation:
caption_base_url: http://localhost:8092/v1
llm:
enabled: true
base_url: ""
The blank reader URL uses the app-owned local llama.cpp model. It starts when needed and releases its model before local music, stems and rendering. You do not need a second reader server. If you already use one, configure its URL and served model name using the reader guide.
Fetch the model files required by this configuration, then check it:
uv run --no-sync immich-memories models fetch
uv run --no-sync immich-memories preflight -v
uv run --no-sync immich-memories config show tier
uv run --no-sync immich-memories ui --host 127.0.0.1
Open http://localhost:8080 and make your first film.
Automatic selection can use the native Metal preparation runtime; Full also needs the enabled
reader, captions and Laya ready. Preflight names any missing requirement. A Docker container on
a Mac cannot use Metal directly; this recipe runs outside Docker.
Optional local music
Bundled or chosen music works without another model. To generate tracks locally, stop the app and install the separate audio environment in this checkout:
make install-acestep
make check-local-audio
Then add:
advanced:
ace_step:
enabled: true
mode: lib
use_lm: false
Restart the app. A Mac with 64 GB or more loads the 4B XL model (about 21 GB free for resident weights, 20 GB on disk); a smaller one plays a bundled track instead of generating. Generation needs working memory too. Generated music and the audio runtime cover larger profiles, checks and fallback reporting. Each checkout or worktree needs its own audio installation.
Access from another machine
Keep the explicit localhost app bind for a private desktop setup. To reach it from another machine, choose authentication and a network/proxy configuration first. Local caption routes have no built-in authentication; only broaden their bind address when another trusted app needs access.