You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pkg/media/README.md
+14-12Lines changed: 14 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
## PhotoPrism — Media Package
2
2
3
-
**Last Updated:**February 14, 2026
3
+
**Last Updated:**June 1, 2026
4
4
5
5
### Apple iPhone & iPad
6
6
@@ -10,10 +10,12 @@ We recommend [using an app like PhotoSync](https://docs.photoprism.app/user-guid
10
10
11
11
### Android Devices
12
12
13
-
Some Samsung and Google Android devices support taking "Motion Photos" with the included Camera app. Motion Photos are JPEG/HEIC image with a short MP4 video embedded after the image data.
13
+
Some Samsung and Google Android devices support taking "Motion Photos" with the included Camera app. A Motion Photo is a JPEG/HEIC image with a short MP4 video embedded after the image data.
14
14
15
15
The image part of these files can be opened in any image viewer that supports JPEG/HEIC, but the video part cannot. However, since the MP4 video is simply appended at the end of the image file, it can be easily read by our software and streamed through the API as needed.
16
16
17
+
How PhotoPrism locates the embedded video offset and detects its codec is described in the [`video` subpackage documentation](https://github.com/photoprism/photoprism/blob/develop/pkg/media/video/README.md#codec-detection).
18
+
17
19
### Introductory Tutorials
18
20
19
21
| Title | Date | URL |
@@ -27,16 +29,16 @@ The image part of these files can be opened in any image viewer that supports JP
Copy file name to clipboardExpand all lines: pkg/media/video/README.md
+33-12Lines changed: 33 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,6 @@
1
-
## Video File Support
1
+
## PhotoPrism — Video Package
2
+
3
+
**Last Updated:** June 1, 2026
2
4
3
5
### Codecs & Containers
4
6
@@ -16,15 +18,34 @@ Please Note:
16
18
17
19
1. Not all [video and audio formats](https://caniuse.com/?search=video%20format) can be [played with every browser](https://docs.photoprism.app/getting-started/troubleshooting/browsers/). For example, [AAC](https://caniuse.com/aac"Advanced Audio Coding") - the default audio codec for [MPEG-4 AVC / H.264](https://caniuse.com/avc"Advanced Video Coding") - is supported natively in Chrome, Safari, and Edge, while it is only optionally supported by the OS in Firefox and Opera.
18
20
2. HEVC/H.265 video files can have a `.mp4` file extension too, which is often associated with AVC only. This is because MP4 is a *container* format, meaning that the actual video content may be compressed with H.264, H.265, or something else. The file extension doesn't really tell you anything other than that it's probably a video file.
19
-
3. In case [FFmpeg is disabled](https://docs.photoprism.app/user-guide/settings/advanced/#disable-ffmpeg) or not installed, videos cannot be indexed because still images cannot be created. You should also have [Exiftool enabled](https://docs.photoprism.app/getting-started/config-options/#feature-flags) to extract metadata such as duration, resolution, and codec.
21
+
3. In case [FFmpeg is disabled](https://docs.photoprism.app/user-guide/settings/advanced/#disable-ffmpeg) or not installed, videos cannot be indexed because still images cannot be created. You should also have [ExifTool enabled](https://docs.photoprism.app/getting-started/config-options/#feature-flags) to extract metadata such as duration, resolution, and codec.
20
22
21
23
### Hybrid Photo/Video Formats
22
24
23
25
For more information on hybrid photo/video file formats, e.g. Apple Live Photos and Samsung/Google Motion Photos, see [github.com/photoprism/photoprism/tree/develop/pkg/media](https://github.com/photoprism/photoprism/tree/develop/pkg/media) and [docs.photoprism.app/developer-guide/media/live](https://docs.photoprism.app/developer-guide/media/live/).
24
26
27
+
### Codec Detection
28
+
29
+
PhotoPrism probes MP4 and QuickTime (ISO base media) files with [`go-mp4`](https://github.com/abema/go-mp4) to read the container brand, track layout, and codec. A chunk scan first locates the `ftyp` box and a compatible brand (`Chunks.FileTypeOffset` in `chunks.go`); in hybrid photo/video files this also yields the embedded-video offset, so the leading still image is skipped before parsing. MPEG-4 AVC / H.264 is then reported directly by the parser and needs no further work.
30
+
31
+
HEVC / H.265 and [MagicYUV](https://en.wikipedia.org/wiki/MagicYUV) sample entries are not yet surfaced by `go-mp4`, so PhotoPrism falls back to a chunk scan over the file head when the parser does not return a codec:
32
+
33
+
- The scan looks for the four-byte ISO BMFF sample-entry codes that identify these codecs — `hvc1`, `hev1`, `dvh1`, … for HEVC and `M8RG`, `M8Y2`, … for MagicYUV — in a single buffered pass (see `Chunks.SampleEntryOffset` in `chunks.go`).
34
+
- Each candidate is validated as a genuine visual sample entry rather than a raw byte match: the four bytes that precede it must be a plausible big-endian box size, and the bytes that follow must be the six reserved zero bytes and the nonzero `data_reference_index` mandated by ISO/IEC 14496-12 (`isVisualSampleEntry`). This rejects four-byte codes that merely collide with payload bytes, which is common in raw elementary streams such as the DV data inside some QuickTime files.
35
+
- The scan reads at most `HeadScanLimit` (16 MiB) and stops as soon as a valid entry is found. Buffered reads carry a small overlap so a code straddling a block boundary, and its validation window, stay visible.
36
+
37
+
The detected codec, together with the codec and container reported by ExifTool, drives the FFmpeg exclude list (default `magy`, `vfw`) that keeps known-problematic formats out of transcoding and thumbnail extraction.
38
+
39
+
#### Possible Improvements
40
+
41
+
-**Read the codec from the parsed `stsd` box.** Once `go-mp4` reports HEVC (a pending upstream contribution), the chunk scan and `HeadScanLimit` could be retired for parseable MP4/QuickTime files. Reading the sample entry directly would also detect codecs in large non-faststart files, where `moov` sits past the 16 MiB cap and the head scan cannot reach it today.
42
+
-**Anchor the scan at the video offset.** Hybrid photo/video files embed the video after the still image, so the scan currently reads through several megabytes of image data before reaching the video's sample entry. Starting at the already-known video offset would skip the image prefix without affecting plain video files.
43
+
44
+
> `HeadScanLimit` cannot simply be lowered for speed: motion photos place the video's sample entry several megabytes into the file, and non-faststart MP4/QuickTime files keep `moov` near the end, so a smaller cap would silently miss valid HEVC and MagicYUV streams.
45
+
25
46
### Standard Resolutions
26
47
27
-
The [`PHOTOPRISM_FFMPEG_SIZE`](../../getting-started/config-options.md#file-converters) config option allows to limit the resolution of [transcoded videos](../../getting-started/advanced/transcoding.md). It accepts the following standard sizes, while other values are automatically adjusted to the next supported size:
48
+
The [`PHOTOPRISM_FFMPEG_SIZE`](https://docs.photoprism.app/getting-started/config-options/#file-converters) config option allows to limit the resolution of [transcoded videos](https://docs.photoprism.app/getting-started/advanced/transcoding/). It accepts the following standard sizes, while other values are automatically adjusted to the next supported size:
28
49
29
50
| Size | Usage |
30
51
|:-----|:-------------------|
@@ -39,15 +60,15 @@ The [`PHOTOPRISM_FFMPEG_SIZE`](../../getting-started/config-options.md#file-conv
0 commit comments