Nextcloud video player not working: fix buffering, no thumbnails and odd formats with Video Gallery

If your Nextcloud video player stutters, refuses to start, or shows a wall of gray boxes instead of thumbnails, the cause is usually the same: the browser is being handed a file it cannot decode. Nextcloud's built-in viewer is fine for a phone clip in H.264, but hand it an MKV, an HEVC or 10-bit file, a VC-1 or MPEG-2 rip, or a file with DTS or TrueHD audio, and the player either stalls or stays black. Video Gallery is a Nextcloud plugin that solves this at the source. It indexes every video in the account, plays the formats a browser cannot open on its own, and chooses per file how to send it so you are not paying for a full re-encode when a simple repackage would do. This tutorial is for people who run their own instance and want the player to behave.

What you get

Video Gallery (videogallery) finds every video file in an account — home folder, shared folders, external storage — arranges them by the date they were actually shot, and plays each one in the browser. It handles HEVC, 10-bit, VC-1, MPEG-2, DTS, TrueHD, AVI and MKV. For each file and each browser it decides whether to send the file untouched, repackage it (container changed, streams copied), convert only the sound, or re-encode it on the graphics card. That per-file decision is the heart of the fix: a file that already plays is never touched, and a file that cannot play is converted only as far as needed.

Prerequisites

• Nextcloud 34 and PHP 8.4 or newer. The app refuses to enable below 8.4.
• ffmpeg on the server: sudo apt install ffmpeg (Debian, Ubuntu), sudo dnf install ffmpeg (Fedora, RHEL) or sudo apk add ffmpeg (Alpine).
• Working Nextcloud background jobs (Cron) for indexing and preview generation.
• Optional but recommended: a graphics card for conversion (NVIDIA NVENC, Intel Quick Sync, VA-API for Intel/AMD). Without one, conversion runs on the CPU.
• Recommended: a fast disk, ideally NVMe and separate from the system disk, for temporary files.

Step 1 — Install and enable the app

Download the archive videogallery-x.y.z.tar.gz from your MediaLab Works account under Licenses, then extract it into the Nextcloud apps/ (or custom_apps/) folder so you get apps/videogallery/, owned by the web-server user:

cd /var/www/nextcloud/apps
sudo tar -xzf ~/videogallery-x.y.z.tar.gz
sudo chown -R www-data:www-data videogallery

Enable it:

sudo -u www-data php occ app:enable videogallery

Then open Administration settings → Video Gallery → License, paste your license key and save. The app contacts the license server, binds the key to this instance and shows the license as Active.

Step 2 — Build the library now instead of waiting

Cron will index your files eventually, but you can start immediately:

sudo -u www-data php occ videogallery:scan

You can pass a user name to scan a single account. If new videos do not appear later, the usual cause is that background jobs are not running; press Look for new files under The library in the settings, or run the scan command again.

Step 3 — Point temporary files at a fast disk

Open Administration settings → Video Gallery. The app finds ffmpeg, tests what the machine can really do and picks a scratch directory by itself; the page tells you in one sentence what is missing and the command that fixes it. Under Working files, point the scratch directory to a fast disk that is not the system disk. The app only ever deletes inside its own marked directory, so your media is never at risk.

Step 4 — Measure the machine and set up the GPU

Under This server you see the encoders that actually work here: NVENC, Quick Sync, VA-API, VideoToolbox or software. Run Measure this machine: it tests the graphics card with a demanding sample and keeps the best working combination of presets and decode path. Every figure can be overridden. If you have several cards, switch each on or off under Graphics cards, or give each its own limit.

Many distributions start PHP-FPM with PrivateDevices=true, which hides the card — you get "no CUDA-capable device is detected" although it works from a shell. For NVIDIA, add a drop-in with sudo systemctl edit php8.4-fpm (use your PHP version):

[Service]
PrivateDevices=no
DevicePolicy=closed
DeviceAllow=/dev/nvidia0 rw
DeviceAllow=/dev/nvidiactl rw
DeviceAllow=/dev/nvidia-uvm rw
DeviceAllow=/dev/nvidia-uvm-tools rw
DeviceAllow=/dev/nvidia-modeset rw

For Intel and AMD: sudo usermod -aG render www-data. Then sudo systemctl daemon-reload && sudo systemctl restart php8.4-fpm. After changing drivers, press Test the hardware again.

Step 5 — Let it measure the connection

Under Quality and the connection, enable measuring the connection before playing and keep adjusting while playing. The app measures the link before and during playback, so a high-bitrate file is only sent untouched when the connection can carry it, and quality follows the connection. In the player, the quality menu shows what was chosen, for example Automatic (4.0 Mbit/s); pick a fixed quality there if you prefer.

Step 6 — Get the timeline and thumbnails right

The Timeline is built from real capture dates read from inside the file, then from the file name, then from its timestamp. That is why a copied library no longer looks like it was all filmed on the day you migrated. You can also sort by newest added, newest filmed, name, length or size; the choice is kept on the account, on every device. Under Previews, set hover clip length and height and the space reserved for cached previews — this is what fills in the cover cards with silent hover previews instead of gray boxes. If previews are missing, run sudo -u www-data php occ videogallery:preview (optionally for one user) and make sure Cron is working.

Step 7 — Subtitles, audio tracks and chapters

In the player menus you get every embedded and sidecar subtitle, every audio track and chapters. Sidecar files named like Film.en.srt or Film_en.srt beside the video are found too. The player also offers full screen, frame preview while dragging, touch gestures for brightness, volume and seeking, picture in picture, and resume across devices. When you want a bit-for-bit copy or to watch on a TV, Open in another player hands the untouched original to VLC, Infuse or another player on the device.

Step 8 — Series and courses in order

A folder of numbered files is played in order, with the next part offered at the end. Under Kinds of folder the administrator writes the rules that sort folders into courses, camera, series and films. If your course folder jumps around, check those rules first.

Tips and troubleshooting

• Something does not play: run sudo -u www-data php occ videogallery:selftest. It converts part of a real file both ways, seeks into the middle, checks the result plays and that nothing is left behind.
• The graphics card is not used: check occ videogallery:status. Usually PHP-FPM cannot see the card (PrivateDevices) or www-data is not in the render group.
• ffmpeg not found: install it, or set its path under The library → Paths, if ffmpeg is somewhere unusual.
• Check overall state: occ videogallery:status --probe gives you a quick picture; occ videogallery:cleanup (or --all) clears temporary files.
• Sharing: share a video or a folder with a person, a group or a link, with or without download, through Nextcloud's own sharing. Links for external players carry a signed, expiring token and nothing is stored for them.

Conclusion

Most "Nextcloud video player not working" reports come down to a browser being asked to decode something it cannot. Video Gallery fixes that per file — untouched, repackaged, audio-only or re-encoded — measures the connection so untouched playback is only attempted when the link can carry it, and builds a timeline from real capture dates with hover previews. Install it, run Measure this machine, point the scratch directory at a fast disk, and let Cron do the rest. The full walkthrough is in the user guide; the changelog tracks what changed, and if something still misbehaves, the knowledge base and FAQ are the next stop.