From ef383df761c3fea0ead56b7648fe66c8eba12da7 Mon Sep 17 00:00:00 2001 From: "Simon L." Date: Tue, 20 Oct 2026 12:17:10 +0200 Subject: [PATCH 1/2] docs(admin): document ffmpeg-over-ip for video previews Relates to nextcloud/server#65717 and nextcloud/all-in-one#8865 Assisted-by: Claude Code:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 Signed-off-by: Simon L. --- admin_manual/installation/server_tuning.rst | 48 ++++++++++++++++++++- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/admin_manual/installation/server_tuning.rst b/admin_manual/installation/server_tuning.rst index 354195de369..712569db67c 100644 --- a/admin_manual/installation/server_tuning.rst +++ b/admin_manual/installation/server_tuning.rst @@ -351,11 +351,11 @@ external microservice: `Imaginary `_. See https://github.com/nextcloud/server/issues/34262 We strongly recommend running our custom Docker image, which is more up to date than the official image. -You can find the image at ``_. When running it, map a port by adding `-p :9000` to the `docker run` command (or Compose equivalent), e.g. +You can find the image at ``_. When running it, map a port by adding `-p 127.0.0.1::9000` to the `docker run` command (or Compose equivalent), e.g. .. code:: - docker run -d -p 9000:9000 --name nextcloud_imaginary --restart always ghcr.io/nextcloud-releases/aio-imaginary:latest + docker run -d -p 127.0.0.1:9000:9000 --name nextcloud_imaginary --restart always ghcr.io/nextcloud-releases/aio-imaginary:latest Ensure the service is only accessible from your internal servers. Then, configure Nextcloud to use Imaginary by editing your ``config.php`` file: @@ -404,3 +404,47 @@ The default WebP quality setting for preview images is '80'. Change this with: :: occ config:app:set preview webp_quality --value="30" + +Video previews +^^^^^^^^^^^^^^ + +.. versionadded:: 36 + +Like Imaginary for images, video previews can be generated on an external +`ffmpeg-over-ip `_ server. The ``OC\Preview\MovieRemote`` provider runs +``ffprobe`` and ``ffmpeg`` on that server and receives a single still image. Neither ``ffmpeg`` nor the CPU load of +decoding videos is then needed on the Nextcloud server. The server reads the video from Nextcloud over the same +connection, so it needs no access to the data directory and works with any storage, including object storage and +external storages. + +.. warning:: + + The connection to the ffmpeg-over-ip server is not encrypted. Only use it within a trusted network. + +We recommend running our custom Docker image. You can find the image at +``_. The server listens on port ``5050`` and requires the +``FFMPEG_SECRET`` environment variable to be set, e.g. + +.. code:: + + docker run -d -p 127.0.0.1:5050:5050 -e FFMPEG_SECRET=secret \ + --name nextcloud_ffmpeg --restart always ghcr.io/nextcloud-releases/aio-ffmpeg:latest + +Ensure the service is only accessible from your internal servers. Then, configure Nextcloud to use it by editing your +``config.php`` file: + +.. code:: php + + 'enabledPreviewProviders' => [ + // ... the providers you already use ... + 'OC\Preview\MovieRemote', + ], + 'preview_ffmpeg_url' => ':5050', + 'preview_ffmpeg_key' => 'secret', + +``preview_ffmpeg_url`` is the address of the server as ``host:port``, without a scheme. ``preview_ffmpeg_key`` must +match ``FFMPEG_SECRET``, or the ``authSecret`` of the server if you run ffmpeg-over-ip yourself. + +.. note:: + + Do not enable ``OC\Preview\Movie`` at the same time, otherwise the local provider is tried as well. From f73876ea86de7b33c4342fc26fde5b091f8ad0cf Mon Sep 17 00:00:00 2001 From: "Simon L." Date: Thu, 5 Nov 2026 10:22:10 +0100 Subject: [PATCH 2/2] docs(admin): update ffmpeg-over-ip docs to latest server changes Follow nextcloud/server#65717: rename preview_ffmpeg_url to preview_ffmpeg_address, document tls:// and unix: addresses, the preview_ffmpeg_timeout option and the read limits on non-local storages, and that MovieRemote is tried before Movie when both are enabled. Assisted-by: Claude Code:claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 Signed-off-by: Simon L. --- admin_manual/installation/server_tuning.rst | 27 +++++++++++++++++---- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/admin_manual/installation/server_tuning.rst b/admin_manual/installation/server_tuning.rst index 712569db67c..3bb63aa3268 100644 --- a/admin_manual/installation/server_tuning.rst +++ b/admin_manual/installation/server_tuning.rst @@ -419,7 +419,9 @@ external storages. .. warning:: - The connection to the ffmpeg-over-ip server is not encrypted. Only use it within a trusted network. + ffmpeg-over-ip does not encrypt the connection and does not authenticate the server, so anyone answering on the + configured address can read the videos. Only use it within a trusted network, or put a TLS terminating proxy + (e.g. stunnel) in front of the server and use a ``tls://`` address. We recommend running our custom Docker image. You can find the image at ``_. The server listens on port ``5050`` and requires the @@ -439,12 +441,27 @@ Ensure the service is only accessible from your internal servers. Then, configur // ... the providers you already use ... 'OC\Preview\MovieRemote', ], - 'preview_ffmpeg_url' => ':5050', + 'preview_ffmpeg_address' => ':5050', 'preview_ffmpeg_key' => 'secret', -``preview_ffmpeg_url`` is the address of the server as ``host:port``, without a scheme. ``preview_ffmpeg_key`` must -match ``FFMPEG_SECRET``, or the ``authSecret`` of the server if you run ffmpeg-over-ip yourself. +``preview_ffmpeg_address`` is the address of the server as ``host:port``, ``tls://host:port`` or +``unix:/path/to/socket``. It is not an HTTP URL. ``preview_ffmpeg_key`` must match ``FFMPEG_SECRET``, or the +``authSecret`` of the server if you run ffmpeg-over-ip yourself. + +For ``tls://`` addresses, the certificate of the server is verified against Nextcloud's certificate bundle, like for +other outgoing connections. Import the certificate of an internal CA with ``occ security:certificates:import``. + +Generating a single video preview on the server may take ``120`` seconds in total by default. Change this with: + +.. code:: php + + 'preview_ffmpeg_timeout' => 300, .. note:: - Do not enable ``OC\Preview\Movie`` at the same time, otherwise the local provider is tried as well. + Like with ``OC\Preview\Movie``, the server can only read up to 20 MB of videos on storages that are not local + (e.g. object storage or external storage), and only the first 10 MB of videos on storages that cannot seek (e.g. + WebDAV or FTP external storage). + +If ``OC\Preview\Movie`` is enabled as well, the ffmpeg-over-ip server is tried first. The local ``ffmpeg`` is then only +used if the server could not generate a preview.