System dependencies

Miru shells out to, or links against, five external tools. Missing any of them does not stop the app booting; it stops one kind of file from being processed, and the upload lands in a failed state with an error the uploader can see.

libvips — required

Every image passes through libvips: decode, auto-orient, resize to the three variant sizes, and write out without metadata. There is no fallback. Without libvips, Miru starts and no photograph will ever process.

# Debian / Ubuntu
apt install libvips-dev

# macOS
brew install vips

heif-convert — required for HEIC

Photographs from any recent iPhone are HEIC. Miru does not ask libvips to decode them; it converts them to JPEG first with heif-convert, which comes from libheif's examples package. Depending on a separately-installed binary rather than on how libvips happened to be compiled is the more predictable of the two options — a distribution's libvips may or may not have libheif linked in, and finding out involves reading vips -l.

apt install libheif-examples     # Debian / Ubuntu
brew install libheif             # macOS

Without it, HEIC uploads fail while JPEG works perfectly — a confusing symptom if you are not expecting it, and the ordinary case for anyone using the iOS app.

Check with:

heif-convert --help

A licensing note for self-hosters. HEVC is covered by patents, and distributing a build with an HEVC encoder has licensing implications that vary by jurisdiction. Miru only ever decodes HEIC; it writes JPEG. That is a narrower position than encoding, but it is not legal advice, and if you are distributing binaries you should look into it rather than take this paragraph as settled.

FFmpeg — required for video

Transcoding to H.264, generating HLS segments for streaming, extracting the thumbnail frame, and reading duration, resolution and frame rate.

apt install ffmpeg     # Debian / Ubuntu
brew install ffmpeg    # macOS

Without it, video uploads fail and images are unaffected.

exiftool and dcraw — required for RAW

RAW files are handled in two steps, and the second is a fallback.

1. exiftool extracts the JPEG preview that almost every camera embeds in its RAW files. This is fast and gives an accurate rendering, because the camera made it.
2. dcraw develops the RAW itself, for the files that have no usable embedded preview.

apt install libimage-exiftool-perl dcraw
brew install exiftool dcraw

Without exiftool, RAW uploads fail. Without dcraw, most RAW files still work — the ones with no embedded preview do not.

The original RAW is always preserved regardless, and always downloadable.

Checking what you have

vips --version
ffmpeg -version | head -1
exiftool -ver
dcraw -h 2>&1 | head -1

In a container

The production image installs all of these. If you are building your own, the relevant lines are:

RUN apt-get update && apt-get install -y --no-install-recommends \
      libvips42 ffmpeg libimage-exiftool-perl dcraw libheif-examples \
    && rm -rf /var/lib/apt/lists/*

Note libvips42 rather than libvips-dev — the runtime image needs the shared library, not the headers.

This list is not advisory. Every one of these is reached by a System.cmd/3 call somewhere in the media pipeline, and without them the app starts happily, /health reports healthy, and then every video, RAW and HEIC upload fails.