From a0904c4008fda06c5f790394b995b7570bccb31e Mon Sep 17 00:00:00 2001 From: Michael Mayer Date: Thu, 5 Oct 2023 09:37:25 +0200 Subject: [PATCH] Docs: Update pkg/live/README.md and pkg/video/README.md Signed-off-by: Michael Mayer --- pkg/live/README.md | 25 +++++++++++++++---------- pkg/video/README.md | 45 ++++++++++++++++++++++++++++++++++++++------- 2 files changed, 53 insertions(+), 17 deletions(-) diff --git a/pkg/live/README.md b/pkg/live/README.md index 71fce7252..9e9bf1665 100644 --- a/pkg/live/README.md +++ b/pkg/live/README.md @@ -1,11 +1,19 @@ Hybrid Photo/Video File Support =============================== -- Apple iOS: Live Photos consist of a JPEG/HEIC image and a QuickTime AVC/HEVC video, which are both required for viewing. -- Android: Samsung and Google Pixel smartphones support taking "Motion Photos" with the included Photos app. Motion Photos are JPEG/HEIC image with a short MP4 video embedded after the image data. 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. +## Apple iPhone and iPad -Introductory Tutorials ----------------------- +[iOS Live Photos](https://developer.apple.com/live-photos/) consist of a JPEG/HEIC image and a QuickTime AVC/HEVC video, which are both required for viewing. + +We recommend [using an app like PhotoSync](https://docs.photoprism.app/user-guide/sync/mobile-devices/#photosync) to upload Live Photos to PhotoPrism, since the iOS web upload usually only submits the HEIC image file without the video. + +## Android Devices + +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. + +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. + +## Introductory Tutorials | Title | Date | URL | |---------------------------------------------------------|----------|------------------------------------------------------------------------------------| @@ -16,8 +24,7 @@ Introductory Tutorials | Working with Motion Photos | Jan 2019 | https://medium.com/android-news/working-with-motion-photos-da0aa49b50c | | Google: Behind the Motion Photos Technology in Pixel 2 | Mar 2018 | https://blog.research.google/2018/03/behind-motion-photos-technology-in.html | -Software Libraries and References ---------------------------------- +## Software Libraries and References | Title | URL | |------------------------------------------------------|-------------------------------------------------------------------------| @@ -30,16 +37,14 @@ Software Libraries and References | How to use the io.Reader interface | https://yourbasic.org/golang/io-reader-interface-explained/ | | AV1 Codec ISO Media File Format | https://aomediacodec.github.io/av1-isobmff | -Related GitHub Issues ---------------------- +## Related GitHub Issues - https://github.com/photoprism/photoprism/issues/439 (Samsung: Initial support for Motion Photos) - https://github.com/photoprism/photoprism/issues/1739 (Google: Initial support for Motion Photos) - https://github.com/photoprism/photoprism/issues/2788 (Metadata: Flag Samsung/Google Motion Photos as Live Photos) - https://github.com/cliveontoast/GoMoPho/issues/23 (Google Motion Photos Video Extractor: Add Android 12 Support) -Related Pull Requests ---------------------- +## Related Pull Requests - https://github.com/photoprism/photoprism/pull/3709 (Google: Initial support for Motion Photos) - https://github.com/photoprism/photoprism/pull/3722 (Google: Add support for Motion Photos) diff --git a/pkg/video/README.md b/pkg/video/README.md index 86a3526cf..a476208d8 100644 --- a/pkg/video/README.md +++ b/pkg/video/README.md @@ -1,8 +1,44 @@ Video File Support ================== -Technical References and Tutorials ----------------------------------- +## Codecs and Containers + +For maximum browser compatibility, PhotoPrism can transcode video codecs and containers [supported by FFmpeg](https://www.ffmpeg.org/documentation.html) to [MPEG-4 AVC](https://en.wikipedia.org/wiki/MPEG-4). + +Running the following command in a terminal displays a list of supported codecs: + +``` +ffmpeg -decoders +``` + +See our advanced setup guide to learn how to [configure hardware video transcoding](https://docs.photoprism.app/getting-started/advanced/transcoding/). + +Please Note: + +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. +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. +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. + +## Hybrid Photo/Video Formats + +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/live](https://github.com/photoprism/photoprism/tree/develop/pkg/live) and [docs.photoprism.app/developer-guide/media/live](https://docs.photoprism.app/developer-guide/media/live/). + +## Standard Resolutions + +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: + +| Size | Usage | +|------|--------------------| +| 720 | SD TV, Mobile | +| 1280 | HD TV, SXGA | +| 1920 | Full HD | +| 2048 | DCI 2K, Tablets | +| 2560 | Quad HD, Notebooks | +| 3840 | 4K Ultra HD | +| 4096 | DCI 4K, Retina 4K | +| 7680 | 8K Ultra HD 2 | + +## Technical References and Tutorials | Title | URL | |-------------------------------------|-----------------------------------------------------------------------------| @@ -14,11 +50,6 @@ Technical References and Tutorials | How to use the io.Reader interface | https://yourbasic.org/golang/io-reader-interface-explained/ | | AV1 Codec ISO Media File Format | https://aomediacodec.github.io/av1-isobmff | -Hybrid Photo/Video Formats --------------------------- - -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/live](https://github.com/photoprism/photoprism/tree/develop/pkg/live). - ---- *PhotoPrism® is a [registered trademark](https://www.photoprism.app/trademark). By using the software and services we provide, you agree to our [Terms of Service](https://www.photoprism.app/terms), [Privacy Policy](https://www.photoprism.app/privacy), and [Code of Conduct](https://www.photoprism.app/code-of-conduct). Docs are [available](https://link.photoprism.app/github-docs) under the [CC BY-NC-SA 4.0 License](https://creativecommons.org/licenses/by-nc-sa/4.0/); [additional terms](https://github.com/photoprism/photoprism/blob/develop/assets/README.md) may apply.*