From 8318ea1d38d6e19f133df4eb0393922c60f7491f Mon Sep 17 00:00:00 2001 From: Varun Patil Date: Sun, 30 Apr 2023 13:29:12 -0700 Subject: [PATCH] docs: add wiki to repo Signed-off-by: Varun Patil --- docs/config.md | 120 ++++++++++++++++++++++++++++++++ docs/faq.md | 58 ++++++++++++++++ docs/file-types.md | 54 ++++++++++++++ docs/hw-transcoding.md | 139 +++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + docs/memories-vs-photos.md | 22 ++++++ docs/system-config.md | 70 +++++++++++++++++++ mkdocs.yml | 32 +++++++++ 8 files changed, 496 insertions(+) create mode 100644 docs/config.md create mode 100644 docs/faq.md create mode 100644 docs/file-types.md create mode 100644 docs/hw-transcoding.md create mode 100644 docs/index.md create mode 100644 docs/memories-vs-photos.md create mode 100644 docs/system-config.md create mode 100644 mkdocs.yml diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 00000000..ddb98359 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,120 @@ +# Overview + +Starting with v5.0.0, you can fully configure memories using the admin panel. With an admin account in Nextcloud, go to `Settings -> Memories`. 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](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html) for more information. + +```bash +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) +``` + +!!! warning "OCCWeb" + + The OCCWeb app is deprecated, and will not work with Memories. You must use the `occ` command line. + +!!! tip "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. + +!!! tip "OCC with Docker" + + If you are using docker, make sure you run these commands with an interactive TTY. For example, + + ```bash + docker exec -it my_nc_container php occ memories:index + # ^^^ <-- this is required + ``` + +## Storage support + +The app can work with external storage for photos. Just set the mountpoint as the timeline directory. + +- If you add any photos from outside Nextcloud, you must run the scan and index commands. +- Indexing may be slow, since all files must be downloaded from the storage. + +!!! warning "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. + +## Image/Video support + +To get support for all file types including HEIC, TIFF and RAW, refer to [this page](./file-types.md). + +To enable support for high resolution images, you need to update Nextcloud's `config.php` to include + +```php +'preview_max_memory' => 4096, +'preview_max_filesize_image' => 256, +``` + +## Transcoding + +Memories bundles a [transcoding server](https://github.com/pulsejet/go-vod) 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: + +1. In general, transcoding can be very compute intensive. If you run Nextcloud on an RPi, it will not work for you. +1. If you use external storage, transcoding might be very slow or not work at all. In this case, you should disable it. +1. Make sure there is a lot of space available in `/tmp` for the transcoded files. +1. If transcoding fails, the video player will fall back to the original video stream. Check the output of `/tmp/go-vod/.log` +1. For better performance, you may configure the transcoder to use hardware acceleration. See [this page](./hw-transcoding.md). + +## Reverse geocoding + +Memories supports 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, go to the admin panel. Note that all your files will be re-indexed after downloading the planet database. + +## Recommended apps + +- [Preview Generator](https://github.com/rullzer/previewgenerator) - For pre-generating image previews (**required** for best performance) +- [Recognize](https://github.com/nextcloud/recognize) - The official Nextcloud app for AI tagging of images and people. +- [Photos](https://github.com/nextcloud/photos) - The official Nextcloud Photos app, required for albums support. +- [Face Recognition](https://github.com/matiasdelellis/facerecognition) - An alternative face recognition app, which offers more fine-tuning. Alpha stage integration. + +## 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. + +```php +'preview_max_x' => 2048, +'preview_max_y' => 2048, +``` + +You can also set the preview JPEG quality to 80 to save more space. + +```bash +occ config:app:set preview jpeg_quality --value="80" +``` + +If you already generated previews and want to regenerate, run the following (at your own risk; have backups) + +```bash +rm -rf /appdata_*/preview +occ files:scan-app-data +``` + +## Migration + +Memories directly uses EXIF metadata from files, so migration 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. + +```bash +occ memories:migrate-google-takeout +``` + +## Other notes + +- For optimal performance, enable HTTP/2 on your reverse proxy (nginx/apache) +- 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 [the docs](https://docs.nextcloud.com/server/latest/admin_manual/installation/server_tuning.html). +- The archive feature moves photos to a separate folder called `.archive` at the root of your timeline. You can, for example, mount this folder to a cold storage. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 00000000..59fc069a --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,58 @@ +# Frequently Asked Questions + +- **How is it different from the default Nextcloud Photos app?** + You can find a full comparison [here](../memories-vs-photos). + +- **What apps does Memories compete against?** + Commercial cloud photo services. The target is to be better than `X` service provider that you pay $$$ for, and be usable by grandma. + +- **Is it production ready?** + Yes. + +- **Does it support multiple users and external sharing?** + Yes. + +- **Why is it tied to Nextcloud? Isn't this a lot of overhead? Isn't PHP slow?** + + 1. Reinventing the wheel is pointless. If Memories was a dedicated app, that would mean re-implementing everything from automatic file upload to multi-user support and auth integrations. The maintenance overhead of such a codebase increases exponentially, all while completely unnecessary since someone else is maintaining the exact same things in another piece of software. Integrating with Nextcloud is what makes Memories sustainable. + 1. PHP and Nextcloud have become very fast over the last few years, and running both is very minimal overhead. Functions such as upgrading Nextcloud + to newer versions is seamless especially when using Docker. + 1. The power of Memories is integration: the Nextcloud ecosystem provides tons of other apps for extending functionality. + +- **Why doesn't it support `` such as XMP tags and advanced metadata editing?** + The target user of Memories is not a tech-savvy self-hoster. Most commonly used / available features will be given priority over advanced features, e.g. most useful for professionals / photographers / data hoarders. That doesn't mean to say these features will necessarily not be implemented. + +- **Does Memories support a folder structure for storage?** + Yes. All photos are stored in a folder structure, and only displayed as a flat timeline. This means you can swap out Memories for any other photo app if you want (no lock-in). You can also view the photos in the folder structure if you desire. + +- **Does it have a mobile app?** + Not yet. The web app is very responsive on mobile. You can use the official Nextcloud app to auto-upload photos and videos from your device. + +- **How is it better than the `Y` FOSS photo manager?** + UX and performance. The devil is in the details. + +- **It's slow or doesn't work** + Make sure you follow the [configuration steps](../config). Unless you have hundreds of thousands of photos on a Raspberry Pi, Memories should be very fast. File an issue otherwise. + +- **Will it run on my system?** + In general, if you can run Nextcloud, you should be able to run Memories. File an issue if you run into problems. + +- **How to completely remove Memories? Maybe to reinstall after errors?** + Uninstall Memories from the app store, then run the following SQL on your database. + + ```sql + DROP TABLE IF EXISTS oc_memories; + DROP TABLE IF EXISTS oc_memories_livephoto; + DROP TABLE IF EXISTS oc_memories_mapclusters; + DROP TABLE IF EXISTS oc_memories_places; + DROP TABLE IF EXISTS oc_memories_planet; + DROP TABLE IF EXISTS memories_planet_geometry; + DROP INDEX IF EXISTS memories_parent_mimetype ON oc_filecache; + DELETE FROM oc_migrations WHERE app='memories'; + ``` + + On Postgres, the syntax for dropping the index is: + + ```sql + DROP INDEX IF EXISTS memories_parent_mimetype; + ``` diff --git a/docs/file-types.md b/docs/file-types.md new file mode 100644 index 00000000..ab2c343e --- /dev/null +++ b/docs/file-types.md @@ -0,0 +1,54 @@ +# File type support + +Memories supports the file types supported by the Nextcloud previews app. If you add support for any one of the file types below, you must run `occ memories:index` to index these files. + +## Common Formats + +``` +PNG (image/png) +JPEG (image/jpeg) +PNG (image/png) +GIF (image/gif) +BMP (image/bmp) +``` + +These are enabled by having the following in your `config.php`, + +```php +'enabledPreviewProviders' => +array ( + 'OC\\Preview\\Image', +), +``` + +## HEIC and TIFF + +You must enable `HEIC` and `TIFF` in Nextcloud `config.php`, and install Imagemagick (included in the official Nextcloud docker image) + +In `config.php`, add, + +```php +'enabledPreviewProviders' => +array ( + 'OC\\Preview\\HEIC', + 'OC\\Preview\\TIFF', +), +``` + +## Videos + +You need to install `ffmpeg` and add the video config to `config.php` + +```php +'enabledPreviewProviders' => +array ( + 'OC\\Preview\\Movie', + 'OC\\Preview\\MKV', + 'OC\\Preview\\MP4', + 'OC\\Preview\\AVI', +), +``` + +## RAW images + +Install the [camera raw previews](https://github.com/ariselseng/camerarawpreviews) app from the Nextcloud app store. diff --git a/docs/hw-transcoding.md b/docs/hw-transcoding.md new file mode 100644 index 00000000..dac6d861 --- /dev/null +++ b/docs/hw-transcoding.md @@ -0,0 +1,139 @@ +# Hardware transcoding + +Memories supports transcoding acceleration with VA-API and NVENC. + +## External Transcoder + +If you plan to use hardware transcoding, it may be easier to run the transcoder (go-vod) in a separate docker image containing ffmpeg and hardware acceleration dependencies. For this, you need to clone the [go-vod](https://github.com/pulsejet/go-vod) repository and build the docker image. Then you need to change the vod connect address and mark go-vod as external. The important requirement for running go-vod externally is that the file structure must be exactly same for the target video files. + +In the directory with the `docker-compose.yml` file, run, + +```bash +git clone https://github.com/pulsejet/go-vod +``` + +If you are using docker compose, configure a service to start go-vod with the correct devices and filesystem structure. Otherwise, manually start the container with these parameters. + +```yaml +# docker-compose.yml + +services: + app: + image: nextcloud + restart: always + depends_on: + - db + - redis + volumes: + - ncdata:/var/www/html + + go-vod: + build: ./go-vod + restart: always + devices: + - /dev/dri:/dev/dri + volumes: + - ncdata:/var/www/html:ro +``` + +Finally, point Memories to the external go-vod instance. In the admin interface, set go-vod to external and configure the connect URL to `go-vod:47788`. Alternatively, add the following configuration to `config.php`: + +```php +'memories.vod.external' => true, +'memories.vod.connect' => 'go-vod:47788', +``` + +## VA-API + +!!! warning "These instructions are not applicable for external transcoders" + +Newer Intel processors come with a feature called QuickSync that can significantly boost transcoding performance (4-5x improvement over x264 is common). QuickSync can be used for hardware accelerated transcoding using the VA-API in ffmpeg. + +Note: VA-API acceleration may also work with some AMD GPUs. + +To configure VAAPI, you need to have `/dev/dri` available to the Nextcloud instance with the `www-data` in the group owning the drivers. You also need the correct drivers and a compatible version of ffmpeg installed. + +Ubuntu: + +```bash +sudo apt-get update +sudo apt-get install -y intel-media-va-driver-non-free ffmpeg +``` + +Alpine: + +```bash +apk update +apk add --no-cache bash ffmpeg libva-utils libva-vdpau-driver libva-intel-driver intel-media-driver mesa-va-gallium +``` + +### Docker installations + +If you use Docker, you need to: + +1. Pass the `/dev/dri` device to the container. In `docker-compose.yml`: + ```yaml + app: + build: . + restart: always + devices: + - /dev/dri:/dev/dri + ``` +1. Make sure the right drivers are installed. This can be done using a custom Dockerfile, for example + + ```Dockerfile + FROM nextcloud:25 + + RUN apt-get update && \ + apt-get install -y software-properties-common && \ + apt-add-repository -y non-free && \ + apt-get update && \ + apt-get install -y intel-media-va-driver-non-free ffmpeg && \ + rm -rf /var/lib/apt/lists/* + + COPY start.sh / + CMD /start.sh + ``` + + In `start.sh`, + + ```bash + #!/bin/bash + GID=`stat -c "%g" /dev/dri/renderD128` + groupadd -g $GID render2 || true # sometimes this is needed + GROUP=`getent group $GID | cut -d: -f1` + usermod -aG $GROUP www-data + + php-fpm + ``` + +1. Check the output of `/tmp/go-vod/.log` if playback has issues + +### linuxserver/nextcloud image + +You can add the following to the `docker-compose.yml` file to install the drivers: + +```yaml +devices: + - /dev/dri:/dev/dri +environment: + - DOCKER_MODS=linuxserver/mods:universal-package-install + - INSTALL_PACKAGES=libva|libva-intel-driver|intel-media-driver|mesa-va-gallium +``` + +### FFmpeg from source + +In some cases, you may need to build the drivers and `ffmpeg` from source. For example, the available version of the media driver for the current debian image used by Nextcloud only supports upto Ice Lake CPUs. [This recipe](https://gist.github.com/pulsejet/4d81c1356703b2c8ba19c1ca9e6f6e50) might be useful. + +```Dockerfile +FROM nextcloud:25 + +# Enable QSV support +SHELL ["/bin/bash", "-c"] +RUN apt-get update && \ + apt-get install -y sudo curl git && \ + rm -rf /var/lib/apt/lists/* +RUN curl https://gist.githubusercontent.com/pulsejet/4d81c1356703b2c8ba19c1ca9e6f6e50/raw/qsv-docker.sh | bash + +... +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..71301af6 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +This documentation contains information for further configuration for best results. diff --git a/docs/memories-vs-photos.md b/docs/memories-vs-photos.md new file mode 100644 index 00000000..22a9a1ca --- /dev/null +++ b/docs/memories-vs-photos.md @@ -0,0 +1,22 @@ +# Memories vs Photos + +Nextcloud comes bundled with an official "Photos" app. This page provides a brief feature comparison between Memories and Photos, and links some relevant issues in the Photos repository. + +## Features in Memories missing in Photos + +1. **Sorting by Date Taken**: The Photos app sorts images and videos by the file modification time. Memories uses the EXIF data to get the Date Taken, providing for the correct sort order regardless if the files are edited / touched later ([issue](https://github.com/nextcloud/photos/issues/87)). +1. **Scrubbable Timeline**: Both apps provide an infinite virtual scroll. However, Photos has no way to jump at any time in the past, and you need to scroll through all photos to get to any point. Memories provides a scroller to directly jump to any date in the timeline ([issue](https://github.com/nextcloud/photos/issues/426)). +1. **Limiting to a single root for Photos**: Memories can scan through photos in a single (or multiple) directory. Photos scans everything the user has ([issue](https://github.com/nextcloud/photos/issues/141)). +1. **Video Transcoding**: Memories supports all video file formats with live adaptive transcoding, along with quality selection. Photos only supports videos compatible with the user's browser at full resolution. +1. **Archive**: Allows separating photos to a different folder quickly. Photos has no equivalent function. +1. **External Folder Sharing**: Allows sharing a folder to non-Nextcloud users. Photos has no equivalent function ([issue](https://github.com/nextcloud/photos/issues/236)). +1. **EXIF Data Editing**: Memories allows basic editing of EXIF data including fields such as date taken, title, description etc. Photos has no equivalent function. +1. **Support for iOS and Google Live Photos**: Memories supports live photos, Photos does not. ([issue](https://github.com/nextcloud/photos/issues/344), [issue](https://github.com/nextcloud/photos/issues/365)) +1. **Advanced Multi-Selection**: Memories supports all multi-selection methods including selecting a day, selecting with Shift+Click and with Touch+Drag. Photos does not support these ([issue](https://github.com/nextcloud/photos/issues/1154), [issue](https://github.com/nextcloud/photos/issues/83)) +1. **Viewer Gestures**: Memories provides a superior photo viewer experience, including gestures such as zoom in and out using touch. +1. **Preview pipelining**: For maximum performance, Memories highly optimizes loading thumbnails, whereas Photos loads them one by one. +1. **Server-side image editing**: The image editor in Memories works server-side allowing editing of large images and all formats (such as HEIC). The Photos image editor works client-side with HTML5 canvas, limiting it's capabilities and the quality of output. + +## Features in Photos missing in Memories + +1. Photos supports uploading photos directly, Memories does not support this function. diff --git a/docs/system-config.md b/docs/system-config.md new file mode 100644 index 00000000..2cdc8a8a --- /dev/null +++ b/docs/system-config.md @@ -0,0 +1,70 @@ +# config.php options + +This is a list of all options in `config.php` that memories uses + +## General + +```php + '/var/www/html/apps/memories/exiftool-bin/exiftool-amd64-glibc', + +// Do not use packaged binaries of exiftool +// This requires perl to be available +'memories.exiftool_no_local' => false, + +// Makes the memories instance readonly +'memories.readonly' => false, + +// Type of reverse geocoding planet database +// -1 => Unconfigured +// 0 => Disable +// 1 => MySQL / MariaDB +// 2 => PostgreSQL +'memories.gis_type' => -1, +``` + +## Transcoding + +```php + false, + +// Hardware support for transcoding +'memories.vod.vaapi' => false, // Transcode with VA-API +'memories.vod.vaapi.low_power' => false, // Use low_power mode for VA-API + +'memories.vod.nvenc' => false, // Transcode with NVIDIA NVENC +'memories.vod.nvenc.temporal_aq' => false, +'memories.vod.nvenc.scale' => 'npp', // npp or cuda + +// Paths to ffmpeg and ffprobe binaries +'memories.vod.ffmpeg' => '/usr/bin/ffmpeg', +'memories.vod.ffprobe' => '/usr/bin/ffprobe', + +// Path to go-vod binary +'memories.vod.path' => '/var/www/html/apps/memories/exiftool-bin/go-vod-amd64', + +// Path to use for transcoded files (/tmp/go-vod/instanceid) +// Make sure this has plenty of space +'memories.vod.tempdir' => '/tmp/my-dir', + +// Bind address to use when starting the transcoding server +'memories.vod.bind' => '127.0.0.1:47788', + +// Address used to connect to the transcoding server +// If not specified, the bind address above will be used +'memories.vod.connect' => '127.0.0.1:47788', + +// Mark go-vod as external. If true, Memories will not attempt to +// start go-vod if it is not running already. +'memories.vod.external' => false, + +// Set the default video quality for a first time user +// 0 => Auto (default) +// -1 => Original (max quality with transcoding) +// -2 => Direct (disable transcoding) +// 1080 => 1080p (and so on) +'memories.video_default_quality' => '0', +``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..b3052047 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,32 @@ +site_name: Memories +theme: + name: material + features: + - navigation.tabs + - navigation.tabs.sticky + - navigation.tracking + palette: + primary: blue + +nav: + - Home: 'index.md' + - Configuration: + - 'config.md' + - 'file-types.md' + - 'hw-transcoding.md' + - 'system-config.md' + - FAQ: + - 'faq.md' + - 'memories-vs-photos.md' + +markdown_extensions: + - admonition + - codehilite + - pymdownx.highlight: + use_pygments: true + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences