# Apple Silicon with local services

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/run/reference/mac-example/>.

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](https://sam-dumont.github.io/immich-memories/docs/run/uv-pip.md).

**Deployment: Local services on Apple Silicon**

Prepare a cut:

- **Your Immich** (Existing Immich server)
  - **Immich API**, Your configured URL: Provides metadata, previews and original media. Upload is optional; the app does not change the source originals.
  - Storage: Your photo and video library
- **Immich Memories** (Your Mac · native app)
  - **App + CLI**, Choose the cut: Reads Immich metadata and previews, saves reusable facts, then chooses the cut. On GPU and Full tiers, Laya runs in the app, even with a remote preparation service.
  - **Owned local reader**, llama.cpp · when enabled: A separate app-owned process reads annotation text. A blank reader URL selects this runtime when the reader is enabled. Its model is released before local rendering and music.
  - Storage: Store · cache · output files
- **Caption server** (Same Mac · separate runtime)
  - **MLX captions**, localhost:8092/v1: Start the caption server separately. It receives picture tiles; keep its bind address on localhost when only this Mac uses it.

1. **Metadata + previews**: Preparation starts with your library; originals remain in Immich.
2. **Preview tiles + frames**: Images 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.

Render a film:

- **Your Immich** (Existing Immich server)
  - **Immich API**, Your configured URL: Provides metadata, previews and original media. Upload is optional; the app does not change the source originals.
  - Storage: Your photo and video library
- **Immich Memories** (Your Mac · native app)
  - **App + CLI**, Assemble the film: Downloads the selected originals and renders locally with FFmpeg.
  - Storage: Store · cache · output files
- **Local rendering** (Same Mac · separate runtime)
  - **Native FFmpeg rendering**, Runs inside the app workflow: Rendering uses VideoToolbox encoding and Metal title effects where available, with CPU fallback. This is not a remote worker or another machine. Docker on macOS cannot use Metal directly.

1. **Selected originals**: The app downloads media for the chosen cut.
2. **Local render work**: No remote handoff: processing and output stay on this Mac.

The app and caption runtime share one Mac. Captions and the reader are enabled in this recipe; generated music is optional.

Open the app:

- **Your Immich** (Existing Immich server)
  - **Immich API**, Your configured URL: Provides metadata, previews and original media. Upload is optional; the app does not change the source originals.
  - Storage: Your photo and video library
- **Immich Memories** (Your Mac · native app)
  - **App + CLI**, Native UI · port 8080: Serves the UI on the native app port and proxies previews. The browser does not receive your Immich API key.
  - Storage: Store · cache · output files
- **Your browser** (Desktop or phone)
  - **Web UI**, App URL · authenticated if exposed: Connects to the app, which serves cached media or fetches it from Immich. Configure authentication before opening access to other machines.

1. **Preview requests**: The app keeps the Immich key on the server.
2. **Browser → app**: UI requests and media go through the app, behind the same login.

The app and caption runtime share one Mac. Captions and the reader are enabled in this recipe; generated music is optional.

**Diagram: On a Mac the app and captions run natively. Add a reader, music or a daily timer when needed.** [(image)](https://sam-dumont.github.io/immich-memories/diagrams/deploy-mac.svg)

```text
┌─────────────────────┐  ┌──────────────────────┐  ┌──────────────────┐
│                     │  │                      │  │                  │
│                     │  │                      │  │      FFmpeg      │
│                     │  │                      │  │     on PATH      │
│    Browser or CLI   │  │    launchd agent     │  │  Config + store  │
│                     │  │auto install, optional│  │~/.immich-memories│
│                     │  │                      │  │      Films       │
│                     │  │                      │  │~/Videos/Memories │
└──────────┬──────────┘  └───────────┬──────────┘  └──────────────────┘
           │                         │
           │                         │
           ├─────────────────────────┘
           │
           ▼
┌─────────────────────┐
│                     │
│   immich-memories   │
│native Python install│
└─────────────────────┘
           │
           │
           ├─────────────────────────┬───────────────────────┐
           │                         │                       │
           ▼                         ▼                       ▼
┌─────────────────────┐  ┌──────────────────────┐  ┌──────────────────┐
│                     │  │                      │  │                  │
│    Caption server   │  │                      │  │                  │
│  GPU and Full tiers │  │                      │  │                  │
│ llama-server reader │  │        Immich        │  │   ACE-Step API   │
│    blank base_url   │  │       API key        │  │     optional     │
│       ACE-Step      │  │                      │  │                  │
│ make install-acestep│  │                      │  │                  │
└─────────────────────┘  └──────────────────────┘  └──────────────────┘
```

Groups:

- Your Mac
  - Optional, on the Mac
    - Caption server; llama-server reader; ACE-Step
  - Browser or CLI
  - immich-memories
  - launchd agent
  - FFmpeg; Config + store; Films
- Your network
  - Immich
  - ACE-Step API

Arrows:

- Browser or CLI → immich-memories
- launchd agent → immich-memories
- immich-memories → Caption server; llama-server reader; ACE-Step
- immich-memories → Immich
- immich-memories → ACE-Step API

Timings for this path, on Metal and VideoToolbox, are in the
[measured examples](https://sam-dumont.github.io/immich-memories/docs/better/measured.md#cold-start-time-by-hardware-and-tier).

## 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:

```bash
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](https://sam-dumont.github.io/immich-memories/docs/contribute/development-setup.md) covers source tools;
the [requirements page](https://sam-dumont.github.io/immich-memories/docs/run/requirements.md) covers memory and supported platforms.

Set your Immich connection in Settings or a [small config file](https://sam-dumont.github.io/immich-memories/docs/run/config-file.md#quick-start-config).
Keep the normal `tier: auto` setting. Start the
[local caption server](https://sam-dumont.github.io/immich-memories/docs/reference/caption-service.md#apple-silicon-with-llamacpp) 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

```yaml
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](https://sam-dumont.github.io/immich-memories/docs/better/reader.md#use-an-existing-server).

Fetch the model files required by this configuration, then check it:

```bash
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](https://sam-dumont.github.io/immich-memories/docs/get-started/first-film.md).
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:

```bash
make install-acestep
make check-local-audio
```

Then add:

```yaml
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](https://sam-dumont.github.io/immich-memories/docs/better/music.md#local-on-a-mac)
and the [audio runtime](https://sam-dumont.github.io/immich-memories/docs/reference/local-audio.md#memory-and-disk) 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](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md) and a
[network/proxy configuration](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md) first. Local caption routes have no
built-in authentication; only broaden their bind address when another trusted app needs access.
