Configuration

Use the admin interface

Starting with v5.0.0, you can fully configure memories using the admin panel. With an admin account in Nextcloud, go to Settings -> Memories. Using the admin interface for configuration is strongly recommended in most cases.

Memories runs a background indexing job to extract EXIF metadata from photos and videos, as well as immediately on every upload.

If you just installed memories and want to speed up indexing, run the following commands. For usage of the occ command line, refer here for more information.

occ memories:places-setup    # set up reverse geocoding, will force re-indexing
occ memories:index           # index existing photo files (can run in parallel, refer to admin panel)

Cron

You DO NOT need to set up a cron job or run occ memories:index periodically, since this is handled internally. Any subsequently uploaded files will be indexed automatically with hooks. In case you upload files externally and run files:scan, the background job will index these files. Make sure Nextcloud cron is configured correctly.

OCC with Docker

If you are using docker, make sure you run these commands with an interactive TTY. For example,

docker exec -it my_nc_container php occ memories:index
#           ^^^  <-- this is required

If you are using Nextcloud AIO, see this documentation.

Recommended Apps

For the best experience and performance, the following apps are recommended.

Preview Generator - For pre-generating image previews (required for performance)
Recognize - The official Nextcloud app for AI tagging of images and people.
Photos - The official Nextcloud Photos app, required for albums support.
Face Recognition - An alternative face recognition app, which offers more fine-tuning. Alpha stage integration.

Storage Support

Memories works out-of-the-box with most Nextcloud setups, including with external storage.

If you upload any photos from outside of Nextcloud, you may need to run the occ files:scan and occ memories:index commands.
With external storage, indexing may be slow since all files must be downloaded.

Transcoding with external storage

Video transcoding requires the entire file to be available locally for ffmpeg. To prevent downloading the entire for every playback, transcoding is disabled for external storage.

Transcoding

Memories bundles a transcoding server with HLS capabilites for adaptive streaming. You need to configure transcoding to be able to play any videos. HLS enables the browser to download the video as small chunks and in resolutions adaptive to the connection speed. As a result, this is usually expected to have a major boost in video experience and performance.

You can configure transcoding from the admin panel. Make sure to test all settings carefully on different kinds of videos.

Read the following considerations carefully regarding transcoding:

In general, transcoding can be very compute intensive. If you run Nextcloud on an RPi, it will not work for you.
If you use external storage, transcoding might be very slow or not work at all. In this case, you should disable it.
Make sure there is a lot of space available in /tmp for the transcoded files.
If transcoding fails, the video player will fall back to the original video stream. Check the output of /tmp/go-vod/<instanceid>.log
For better performance, you may configure the transcoder to use hardware acceleration. See this page.

Hardware Acceleration

Memories supports hardware acceleration for transcoding using VA-API and NVENC. If you have compatible hardware, using acceleration can significantly improve performance. See the instructions on this page for more information.

Reverse Geocoding

Reverse geocoding to find the location of photos. To set up geocoding you need to download the planet boundary dataset and store it in the database. This works only on MySQL / MariaDB / Postgres (no SQLite support). To set up reverse geocoding, go to the Memories admin panel.

World map of photos

Reverse geocoding and the map of photos are two separate features and do not depend on each other.

Preview Storage

By default, previews upto 4096px size are generated by Nextcloud. Each of the largest previews might be a few megabytes in size. This may not be ideal if you have limited storage space, since the preview size may become larger than the originals (especially if you use efficient image formats like HEIC). In this case, you can limit previews to a smaller size like 2048px.

Note that Memories will, by default, load the full image upon zooming in. If you are okay with this, you may use a even smaller size like 1024px to save more space as well as faster preview generation time. Non-JPEG files will be converted on the server when loading in full-res, which may lead to some server load. These options are also configurable through the admin panel.

occ config:system:set preview_max_x --value="2048" --type=integer
occ config:system:set preview_max_y --value="2048" --type=integer

You can also set the preview JPEG quality to 60 to save even more space with lower quality previews.

occ config:system:set jpeg_quality --value="60" --type=integer
occ config:app:set preview jpeg_quality --value="60" --type=integer

If you already generated previews and want to regenerate, run the following (at your own risk; have backups)

rm -rf <nextcloud-data-dir>/appdata_*/preview
occ files:scan-app-data

Nextcloud supports customizing the logo for your instance. To properly theme the logo to match the user's theme, the logo you use in Admninistration => Theming must follow the following criteria:

It must be an SVG file.
The viewBox attribute on the <svg> element must be set appropriately.
All paths that correspond to white areas must have the fill attribute set to currentColor. These areas will then automatically be colored according to the user's theme.
Since Nextcloud doesn't support currentColor, you must set the default value for the color (e.g. white) as an inline style on the <svg> element (<svg style="color:white">).

A sample SVG that follows these criteria is shown below (from here):

<svg viewBox="0 0 256 128" style="color:white" width="256" height="128" version="1.1" xmlns="http://www.w3.org/2000/svg">
<path fill="currentColor" d="m128 7c-25.871 0-47.817 17.485-54.713 41.209-5.9795-12.461-18.642-21.209-33.287-21.209-20.304 0-37 16.696-37 37s16.696 37 37 37c14.645 0 27.308-8.7481 33.287-21.209 6.8957 23.724 28.842 41.209 54.713 41.209s47.817-17.485 54.713-41.209c5.9795 12.461 18.642 21.209 33.287 21.209 20.304 0 37-16.696 37-37s-16.696-37-37-37c-14.645 0-27.308 8.7481-33.287 21.209-6.8957-23.724-28.842-41.209-54.713-41.209zm0 22c19.46 0 35 15.54 35 35s-15.54 35-35 35-35-15.54-35-35 15.54-35 35-35zm-88 20c8.4146 0 15 6.5854 15 15s-6.5854 15-15 15-15-6.5854-15-15 6.5854-15 15-15zm176 0c8.4146 0 15 6.5854 15 15s-6.5854 15-15 15-15-6.5854-15-15 6.5854-15 15-15z" />
</svg>

Note that you may skip these steps and also use a PNG file, but the logo will not be colored according to the user's theme. This can be especially troublesome since Nextcloud mostly shows the logo on a dark background while Memories uses both light and dark backgrounds.

Migration

Memories directly uses EXIF metadata from files, so migration to and from other apps should be generally easy. The file structure of your photos is preserved as-is.

If you are migrating from Nextcloud Photos, you don't need to do anything. Your albums and tags will be carried to Memories as-is.

If you are migrating from Google Takeout, you may run the following command to move JSON metadata to EXIF.

occ memories:migrate-google-takeout

Other notes

Make sure your server timezone is configured correctly. If a photo does not contain an EXIF date, the server time is used.
Perform additional server tuning for Nextcloud. See performance section of troubleshooting.
The archive feature moves photos to a separate folder called .archive at the root of your timeline or the current storage. You can, for example, mount this folder to a cold storage.