RPJosh
/
memories
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: general updates 

Signed-off-by: Varun Patil <radialapps@gmail.com>
pull/877/head
Varun Patil 2023-10-16 22:46:47 -07:00
parent 65b1de8296
commit 4400307fe5
4 changed files with 179 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.vscode/settings.json vendored
View File

@ -88,7 +88,8 @@
"editor.defaultFormatter": "esbenp.prettier-vscode" "editor.defaultFormatter": "esbenp.prettier-vscode"
}, },
"[markdown]": { "[markdown]": {
"files.trimTrailingWhitespace": false "files.trimTrailingWhitespace": false,
"editor.formatOnSave": false,
}, },
"search.exclude": { "search.exclude": {
"**/l10n": true, "**/l10n": true,

76
docs/config.md
View File

@ -4,7 +4,7 @@ description: Steps to configure Memories for the best experience and performance
# Configuration # Configuration
!!! danger "Use the admin interface" !!! success "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`. 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. Using the admin interface for configuration is **strongly recommended** in most cases.
@ -39,6 +39,15 @@ 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). If you are using Nextcloud AIO, see [this documentation](https://github.com/nextcloud/all-in-one#how-to-run-occ-commands).
## 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)
- [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. The app can work with external storage for photos. Just set the mountpoint as the timeline directory.
@ -55,12 +64,7 @@ The app can work with external storage for photos. Just set the mountpoint as th
To get support for all file types including HEIC, TIFF and RAW, refer to [this page](./file-types.md). 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 To enable support for high resolution images, you need to update the preview generation configuration from the admin panel.
```php
'preview_max_memory' => 4096,
'preview_max_filesize_image' => 256,
```
## Transcoding ## Transcoding
@ -76,28 +80,25 @@ 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/<instanceid>.log` 1. If transcoding fails, the video player will fall back to the original video stream. Check the output of `/tmp/go-vod/<instanceid>.log`
1. For better performance, you may configure the transcoder to use hardware acceleration. See [this page](./hw-transcoding.md). 1. For better performance, you may configure the transcoder to use hardware acceleration. See [this page](./hw-transcoding.md).
!!! 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.
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, go to the admin panel. Note that all your files will be re-indexed after downloading the planet database. 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.
## 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 ## 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`. 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. 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.
On Nextcloud AIO, these options are set to the recommended values by default. ```bash
occ config:system:set preview_max_x --value="2048"
```php occ config:system:set preview_max_y --value="2048"
'preview_max_x' => 2048,
'preview_max_y' => 2048,
``` ```
You can also set the preview JPEG quality to 80 to save more space. You can also set the preview JPEG quality to 80 to save more space.
@ -113,21 +114,7 @@ rm -rf <nextcloud-data-dir>/appdata_*/preview
occ files:scan-app-data occ files:scan-app-data
``` ```
## Migration ## Header logo
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
```
## Customization
### 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: 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:
@ -144,9 +131,20 @@ A sample SVG that follows these criteria is shown below (from [here](https://git
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. 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 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 ## 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. - 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). - Perform additional server tuning for Nextcloud. See [performance](/troubleshooting/#performance) section of troubleshooting.
- 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. - 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.

181
docs/hw-transcoding.md
View File

@ -4,29 +4,50 @@ description: Configuration for hardware acceleration for transcoding with VA-API
# Hardware transcoding # Hardware transcoding
Memories supports transcoding acceleration with VA-API and NVENC. 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**.
## Overview
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.
NVIDIA GPUs support hardware transcoding using NVENC.
!!! tip "Hardware acceleration is optional"
Hardware acceleration is optional and not required for Memories to function. If you do not have hardware acceleration, Memories will use the CPU for transcoding.
!!! bug "Filing bugs related to transcoding"
If you have issues with hardware transcoding, reach out for [help](/faq/#getting-help). Make sure you include details about your setup such as how the transcoder is set up, the version of each component and **the logs from the transcoder**.
## External Transcoder ## 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. !!! success "Recommmended configuration"
In the directory with the `docker-compose.yml` file, run the following replacing `<tag>` with the correct tag, which can be found in the admin panel (note that this is _not_ the same as the version of Memories you run). 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.
If you cannot use an external docker container, other installation methods are also possible (see below).
```bash [go-vod](https://github.com/pulsejet/go-vod), the transcoder of Memories, ships with a Dockerfile that already includes the latest ffmpeg and VA-API drivers. To set up an external transcoder, follow these steps.
git clone -b <tag> https://github.com/pulsejet/go-vod
```
!!! warning "go-vod version" 1. Clone the go-vod repository. Make sure you use the correct tag, which can be found in the admin panel. Note that this is **not** the same as the version of Memories you run.
```bash
git clone -b <tag> https://github.com/pulsejet/go-vod
```
!!! tip "go-vod version"
Make sure you always use the correct version of go-vod corresponding to your Memories installation. If you use a different version, the admin panel will show a warning and transcoding may not work properly. Make sure you always use the correct version of go-vod corresponding to your Memories installation. If you use a different version, the admin panel will show a warning and transcoding may not work properly.
If you are using docker, configure a service to start go-vod with the correct devices and filesystem structure. Otherwise, manually start the container with these parameters. 1. Use a `docker-compose` file that builds the go-vod container and mounts the Nextcloud data directories to it. The directory containing the `docker-compose.yml` must contain the `go-vod` repository in it. You can then run `docker compose build` to build the image and `docker compose up -d` to start the containers.
```yaml
# docker-compose.yml
```yaml services:
# docker-compose.yml nc:
services:
app:
image: nextcloud image: nextcloud
restart: always restart: always
depends_on: depends_on:
@ -42,39 +63,74 @@ services:
- /dev/dri:/dev/dri - /dev/dri:/dev/dri
volumes: volumes:
- ncdata:/var/www/html:ro - ncdata:/var/www/html:ro
```
!!! tip "Devices and volumes"
In this example, the VA-API device `/dev/dri/renderD128` is passed to the container, along with the Nextcloud data directory (as readonly). All volumnes must be mounted at the same location as the Nextcloud container.
1. You can now configure the go-vod connect address in the Memories admin panel to point to the external container. go-vod uses port `47788` by default, so in our example the **connection address** would be set to **`go-vod:47788`**.
1. Finally, turn on **enable external transcoder** in the admin panel. This will initiate a test of the transcoder and show the result.
Your external transcoder should now be functional. You can check the transcoding logs by running `docker compose logs -f go-vod`.
!!! info "Usage with Nextcloud AIO"
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"
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.
### NVENC
If you want to use NVENC instead of VA-API, the steps are similar. In this case, you need to build the image from `Dockerfile.nvidia` instead.
You can specify the image to build in the `docker-compose.yml` file.
```yaml
...
go-vod:
build:
context: ./go-vod
dockerfile: Dockerfile.nvidia
...
``` ```
Make sure to put the container and the container into the same network so that they can talk to each other! ### Logging
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`. When running an external transcoder, the logs go to the container logs. You can view them using
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 ```bash
docker compose logs -f go-vod # for docker-compose
docker logs -f <container-name> # if not using docker-compose
```
## Internal Transcoder
Memories ships with an internal transcoder binary that you can directly use. In this case, you must install the drivers and ffmpeg on the same host as Nextcloud, and Memories will automatically handling starting and communicating with go-vod. This is also the default setup when you enable transcoding without hardware acceleration.
!!! danger "Advanced usage only"
In most cases, it is easier to use an external transcoder when you need hardware acceleration.
The internal transcoder is only suitable for CPU transcoding or if you do not use Docker.
!!! tip "NVENC"
These instructions mostly focus on VA-API. For NVENC, you may find further useful
pointers in [this](https://github.com/pulsejet/go-vod/blob/master/build-ffmpeg-nvidia.sh) build script.
### Bare Metal
If you are running Nextcloud on bare metal, you can install the drivers and ffmpeg directly on the host. You need to make sure that the `www-data` user has access to the drivers. You can do this by adding the `www-data` user to the appropriate groups.
```bash
## Ubuntu
sudo apt-get update sudo apt-get update
sudo apt-get install -y intel-media-va-driver-non-free ffmpeg sudo apt-get install -y intel-media-va-driver-non-free ffmpeg # install VA-API drivers
``` sudo usermod -aG video www-data # add www-data to the video group (may be different)
Alpine: ## Alpine
```bash
apk update apk update
apk add --no-cache bash ffmpeg libva-utils libva-vdpau-driver libva-intel-driver intel-media-driver mesa-va-gallium apk add --no-cache bash ffmpeg libva-utils libva-vdpau-driver libva-intel-driver intel-media-driver mesa-va-gallium
``` ```
@ -90,6 +146,7 @@ You can run a test using a sample video file to check if VA-API is working corre
```bash ```bash
# download sample or or use any other video file # download sample or or use any other video file
wget https://github.com/pulsejet/memories-assets/raw/main/sample.mp4 wget https://github.com/pulsejet/memories-assets/raw/main/sample.mp4
chown www-data:www-data sample.mp4
# check if VA-API is working # check if VA-API is working
sudo -u www-data \ sudo -u www-data \
@ -98,24 +155,26 @@ sudo -u www-data \
output-www-data.mp4 output-www-data.mp4
``` ```
### Docker installations 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 script](https://github.com/pulsejet/go-vod/blob/master/build-ffmpeg.sh) for VA-API or [this one](https://github.com/pulsejet/go-vod/blob/master/build-ffmpeg-nvidia.sh) for NVENC might be useful.
!!! danger "Use an en external transcoder" ### Docker
!!! danger "Use an external transcoder"
If you need hardware transcoding and use Docker, it can be significantly easier to use an external transcoder. See [above](#external-transcoder) for instructions. If you need hardware transcoding and use Docker, it can be significantly easier to use an external transcoder. See [above](#external-transcoder) for instructions.
The instructions below, as a result, are mostly historical and **not recommended** for normal usage.
If you use Docker, you need to: If you use Docker and want to use the internal transcoder, you need to:
1. Pass the `/dev/dri` device to the container. In `docker-compose.yml`: 1. Pass the `/dev/dri` device to the Nextcloud container. In `docker-compose.yml`:
```yaml ```yaml
app: nc:
build: . build: .
restart: always restart: always
devices: devices:
- /dev/dri:/dev/dri - /dev/dri:/dev/dri
``` ```
1. Make sure the right drivers are installed. This can be done using a custom Dockerfile, for example 1. Make sure the right drivers are installed. This can be done using a custom Dockerfile as illustrated below.
```Dockerfile ```Dockerfile
FROM nextcloud:stable-fpm FROM nextcloud:stable-fpm
@ -131,8 +190,7 @@ If you use Docker, you need to:
CMD /start.sh CMD /start.sh
``` ```
In `start.sh`, 1. The `start.sh` should add the user to the video group and start php-fpm.
```bash ```bash
#!/bin/bash #!/bin/bash
GID=`stat -c "%g" /dev/dri/renderD128` GID=`stat -c "%g" /dev/dri/renderD128`
@ -143,15 +201,9 @@ If you use Docker, you need to:
php-fpm php-fpm
``` ```
1. Check the output of `/tmp/go-vod/<instance-id>.log` if playback has issues ### Linuxserver Image
### Nextcloud AIO The `linuxserver/nextcloud` image is based on Alpine. You can add the following to the `docker-compose.yml` file to install the VA-API drivers and use the internal transcoder directly.
See the instructions [here](https://github.com/nextcloud/all-in-one#how-to-enable-hardware-transcoding-for-nextcloud).
### Linuxserver Nextcloud image
This image is based on Alpine. You can add the following to the `docker-compose.yml` file to install the drivers.
```yaml ```yaml
devices: devices:
@ -161,19 +213,12 @@ environment:
- INSTALL_PACKAGES=libva|libva-intel-driver|intel-media-driver|mesa-va-gallium - INSTALL_PACKAGES=libva|libva-intel-driver|intel-media-driver|mesa-va-gallium
``` ```
### FFmpeg from source ### Logging
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. When using the internal transcoder, the logs go to `/tmp/go-vod/<instance-id>.log`, where `<instance-id` is a unique ID for your Nextcloud instance that can be found in `config.php`. You can view them as illustrated below.
```Dockerfile ```bash
FROM nextcloud:25 tail -f /tmp/go-vod/<instance-id>.log # bare metal
# Enable QSV support docker exec -it <container-name> cat /tmp/go-vod/<instance-id>.log # Docker
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
...
``` ```

8
docs/troubleshooting.md
View File

@ -64,6 +64,14 @@ app:
`tpmfs` is automatically configured when using Nextcloud AIO v7.0.0. `tpmfs` is automatically configured when using Nextcloud AIO v7.0.0.
!!! tip "Changing the binary temp directory"
Alternatively, you may change the temp directory used for binary files to a different directory that is not mounted as `tmpfs`, and allows the executable bit to be set. Use this option with caution.
```bash
occ config:system:set memories.exiftool.tmp --value /path/to/temp/dir
```
## Reverse Geocoding (Places) ## Reverse Geocoding (Places)
You need to have a MySQL / MariaDB / Postgres database for reverse geocoding to work. SQLite is not supported. You need to have a MySQL / MariaDB / Postgres database for reverse geocoding to work. SQLite is not supported.