From a235c7a2fb155cca72aa651bd8ea318a609f1678 Mon Sep 17 00:00:00 2001 From: Varun Patil Date: Tue, 17 Oct 2023 08:43:24 -0700 Subject: [PATCH] docs: general improvements Signed-off-by: Varun Patil --- CHANGELOG.md | 1 + README.md | 6 ++---- docs/config.md | 42 ++++++++++++++++++----------------------- docs/faq.md | 2 +- docs/file-types.md | 2 +- docs/hw-transcoding.md | 6 +++--- docs/install.md | 10 ++++++++++ docs/troubleshooting.md | 6 +++++- 8 files changed, 41 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 344fbb3c..68a010c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file. - **Breaking**: Nextcloud 26+ and PHP 8 are now required. - Significant improvements to code quality and maintainability. +- Improvements to the [documentation](https://memories.gallery/install/). ## [v5.5.0] - 2023-10-06 diff --git a/README.md b/README.md index fc1f3adf..f4441479 100644 --- a/README.md +++ b/README.md @@ -41,11 +41,9 @@ Memories is a _batteries-included_ photo management solution for Nextcloud with ## 📱 Mobile Apps -- An Android app for Memories is available in early access. +An Android client for Memories is available in early access on [Google Play](https://play.google.com/store/apps/details?id=gallery.memories). - - Get it on Google Play - +For automatic uploads, you can use the official Nextcloud mobile apps. These are available for [Android](https://play.google.com/store/apps/details?id=com.nextcloud.client) ([F-Droid](https://f-droid.org/en/packages/com.nextcloud.client/)) and [iOS](https://apps.apple.com/us/app/nextcloud/id1125420102). ## 🏗 Development Setup diff --git a/docs/config.md b/docs/config.md index a66f5c3a..57a48847 100644 --- a/docs/config.md +++ b/docs/config.md @@ -18,11 +18,7 @@ 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" +!!! question "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 @@ -39,33 +35,27 @@ occ memories:index # index existing photo files (can run in parallel, If you are using Nextcloud AIO, see [this documentation](https://github.com/nextcloud/all-in-one#how-to-run-occ-commands). -## Recommended apps +## Recommended Apps For the best experience and performance, the following apps are recommended. -- [Preview Generator](https://github.com/rullzer/previewgenerator) - For pre-generating image previews (**required** for performance) +- [Preview Generator](https://github.com/nextcloud/previewgenerator) - For pre-generating image previews (**required** for 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. -## Storage support +## Storage Support -The app can work with external storage for photos. Just set the mountpoint as the timeline directory. +Memories works out-of-the-box with most Nextcloud setups, including with external storage. -- 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. +- 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. !!! 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 the preview generation configuration from the admin panel. - ## 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. @@ -80,17 +70,21 @@ Read the following considerations carefully regarding transcoding: 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). -!!! tip "Hardware acceleration" +!!! tip "Hardware Acceleration" Memories supports hardware acceleration for transcoding using VA-API and NVENC. - If you have supported hardware, using hardware acceleration can significantly improve performance. + If you have compatible hardware, using acceleration can significantly improve performance. See the instructions on [this page](./hw-transcoding.md) for more information. -## Reverse geocoding +## 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 reverse geocoding, go to the Memories admin panel. +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. -## Preview storage +!!! info "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`. @@ -114,7 +108,7 @@ rm -rf /appdata_*/preview occ files:scan-app-data ``` -## Header logo +## Header Logo 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: @@ -133,7 +127,7 @@ Note that you may skip these steps and also use a PNG file, but the logo will no ## Migration -Memories directly uses EXIF metadata from files, so migration should be generally easy. The file structure of your photos is preserved as-is. +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. diff --git a/docs/faq.md b/docs/faq.md index 207e00bc..5ff16332 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -47,7 +47,7 @@ Yes. All photos are stored in a folder structure, and only displayed as a flat t **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. +The Android app is available in early access on [Google Play](https://play.google.com/store/apps/details?id=gallery.memories). The web app is very responsive on mobile and can be used on Android and iOS. 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?** diff --git a/docs/file-types.md b/docs/file-types.md index e32efcfb..1c52516c 100644 --- a/docs/file-types.md +++ b/docs/file-types.md @@ -2,7 +2,7 @@ description: Steps to configure support for different image and video formats --- -# File type support +# File Type Support !!! danger "Use the admin interface" diff --git a/docs/hw-transcoding.md b/docs/hw-transcoding.md index bc93fff0..e7e761bf 100644 --- a/docs/hw-transcoding.md +++ b/docs/hw-transcoding.md @@ -2,7 +2,7 @@ description: Configuration for hardware acceleration for transcoding with VA-API and NVENC --- -# Hardware transcoding +# Hardware Transcoding This document describes setting up transcoding in Memories, specifically using hardware acceleration. Hardware acceleration can significantly improve transcoding performance, especially for high resolution videos. Memories supports transcoding using **CPU**, **VA-API** and **NVENC**. @@ -26,7 +26,7 @@ NVIDIA GPUs support hardware transcoding using NVENC. ## External Transcoder -!!! success "Recommmended configuration" +!!! success "Recommmended Configuration" The easiest and recommended way to use hardware transcoding is to use an external transcoder. This setup utilizes a separate docker container that contains the hardware drivers and ffmpeg. @@ -79,7 +79,7 @@ Your external transcoder should now be functional. You can check the transcoding With Nextcloud AIO, you will need to put the container into the `nextcloud-aio` network. Also the datadir of AIO needs to be mounted at the same place like in its Netxcloud container into the go-vod container. Usually this would be `nextcloud_aio_nextcloud_data:/mnt/ncdata:ro` or `$NEXTCLOUD_DATADIR:/mnt/ncdata:ro`. See the instructions [here](https://github.com/nextcloud/all-in-one#how-to-enable-hardware-transcoding-for-nextcloud). -!!! info "Usage without docker-compose" +!!! info "Usage without Docker Compose" You can run a similar setup without `docker-compose` by building the go-vod container manually. Make sure that the Nextcloud and go-vod containers are in the same network and that the Nextcloud data directories are mounted at the same locations in both containers. diff --git a/docs/install.md b/docs/install.md index 535cf3d3..eff855bc 100644 --- a/docs/install.md +++ b/docs/install.md @@ -14,6 +14,10 @@ For the best experience, we recommend to use the latest stable version of Nextcl For easy setup and maintenance, you can use the community Nextcloud Docker image, and add extra dependencies using a custom Dockerfile. Another option is to use [Nextcloud AIO](https://github.com/nextcloud/all-in-one#how-to-use-this), in which case most dependencies are already installed. +!!! success "Recommmended Configuration" + + If you plan to use hardware transcoding, using **Docker Compose** or **Nextcloud AIO** is recommended. + ## Requirements Before installing Memories, make sure that the following requirements are met: @@ -42,3 +46,9 @@ To build the app from source, you need to have [node.js](https://nodejs.org/) in 1. Run `make patch-external` to apply patches to external dependencies. 1. Run `make build-js-production` to build the JavaScript files. 1. Enable the app in the Nextcloud app settings page. + +## Mobile Apps + +An Android client for Memories is available in early access on [Google Play](https://play.google.com/store/apps/details?id=gallery.memories). + +For automatic uploads, you can use the official Nextcloud mobile apps. These are available for [Android](https://play.google.com/store/apps/details?id=com.nextcloud.client) ([F-Droid](https://f-droid.org/en/packages/com.nextcloud.client/)) and [iOS](https://apps.apple.com/us/app/nextcloud/id1125420102). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1c3475b4..d8b243f1 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -53,7 +53,7 @@ If you are using Nextcloud AIO, see [this documentation](https://github.com/next ### Usage of tmpfs -If you are using `tmpfs` (e.g. for the Recognize app), make sure the temp directory is set to executable. With Docker compose, your `docker-compose.yml` should look like this: +If you are using `tmpfs` (e.g. for the Recognize app), make sure the temp directory is set to executable. With Docker Compose, your `docker-compose.yml` should look like this: ```yaml app: @@ -114,6 +114,10 @@ On Postgres, the syntax for dropping the index is: DROP INDEX IF EXISTS memories_parent_mimetype; ``` +!!! warning "Reinstallation" + + The reset will clean up all data associated with Memories. While this is safe and will not delete your files, it can sometimes have unintended side effects, such as some files appearing as duplicates in the mobile apps when you reinstall. Try running `occ memories:index --force` before attempting a reset. + ### Moving from x86 to ARM or vice versa In this case you need to reset the paths to the architecture specific binaries.