Live Photo Converter is a cross-platform tool for processing live photos. It can combine a static image and a video into a live photo, convert a video directly into a live photo, repair live photos that fail to parse due to broken metadata, extract the static image and video from a live photo, or export every frame of the video as an image, and supports converting live photos to long exposure photos.
live-photo-make- Create live photos from images and videos
live-photo-extract- Extract images, videos, and video frames from live photos
- Convert live photos to long exposure photos
live-photo-repair- Repair corrupted live photos
live-photo-conv- A comprehensive command for creating, extracting, converting, and repairing live photos
copy-img-meta- Copy metadata from one image to another
- Choose whether to include or exclude EXIF, XMP, and IPTC metadata
liblivephototools- A library that provides functions for creating and extracting live photos, as well as exporting frames from videos
- The library can be used in any language that supports GObject Introspection
Background (Chinese Introduction)
Android live photos are a gradually popularizing media file format that combines a video with audio and a static image to form a live photo. This type of photo is supported on various devices, such as Google's Pixel series, Samsung's Galaxy series, and most models from manufacturers like Xiaomi.
Essentially, an Android live photo appends a video file directly to the end of a static image. This video file contains both audio and video streams. The position of the video file is marked using XMP metadata, allowing quick location of the video file during parsing. The advantage of this format is that it adds dynamic effects to the image without altering the original image. Since this extension is not a standard for image formats, such images will only be displayed as static images in unsupported image viewers.
This tool can be used for extracting, repairing, editing, and composing such live photos.
For Windows users, the package is already available in the MSYS2 official repository. Make sure you have MSYS2 installed and updated, then you can install it directly with pacman (UCRT64 as an example):
pacman -S mingw-w64-ucrt-x86_64-live-photo-convOn Arch Linux, you can install directly from the AUR using an AUR helper like paru:
paru -S live-photo-convAlternatively, you can manually clone the AUR repository and build/install:
git clone https://aur.archlinux.org/live-photo-conv.git
cd live-photo-conv
makepkg -siYou can also download pre-built binaries from the Releases page. Historical versions are included, and Arch Linux and Windows (MSYS2) are supported.
Please install as required and do not run the binaries directly after extraction, otherwise you may encounter missing dependencies and other issues. If you run into compatibility problems, please use other installation methods. For most users, the easy installation methods above are recommended.
For Arch Linux users, download the file named like live-photo-conv-<version>-x86_64.pkg.tar.zst, and install it using pacman:
sudo pacman -U live-photo-conv-<version>-x86_64.pkg.tar.zstFor Windows users, the Releases page provides pre-built packages for the MSYS2 UCRT64 environment. Installation steps:
- Download the Windows package file named like
mingw-w64-ucrt-x86_64-live-photo-conv-<version>-any.pkg.tar.zst. - Open your MSYS2 shell (UCRT64).
- Install the package using
pacman:
pacman -U mingw-w64-ucrt-x86_64-live-photo-conv-<version>-any.pkg.tar.zst- Build Dependencies
- Meson
- Vala
- GExiv2
- GStreamer (optional, used for exporting images from attached videos, otherwise FFmpeg commands are used)
gstreamergst-plugins-base-libs
- gdk-pixbuf2 (optional, used for exporting images from attached videos, otherwise FFmpeg commands are used)
- gobject-introspection (optional, used for generating GObject Introspection information)
- Runtime Dependencies
- GLib
- GObject
- GIO
- GExiv2
- GStreamer (required when built with GStreamer support)
gstreamergst-plugins-base-libsgst-plugins-goodgst-plugins-badgst-plugin-va(optional, for hardware acceleration)
- gdk-pixbuf2 (required when built with GStreamer support)
gdk-pixbuf2- To support more export formats, you can install optional dependencies such as:
libavif: .aviflibheif: .heif, .heic, and .aviflibjxl: .jxlwebp-pixbuf-loader: .webp
- FFmpeg (optional, required when not built with GStreamer support and need to export images from attached videos)
- GLib
For example, to install dependencies on Arch Linux:
sudo pacman -S --needed glib2 libgexiv2 meson vala gstreamer gst-plugins-base-libs gdk-pixbuf2 gobject-introspection gst-plugins-good gst-plugins-bad gst-plugin-vaTo install dependencies on Debian/Ubuntu:
sudo apt install build-essential meson valac libgexiv2-dev libglib2.0-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libgdk-pixbuf-2.0-dev gobject-introspection libgirepository1.0-dev gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-vaapiTo install dependencies on Windows by MSYS2 (UCRT64 environment):
pacman -S --needed mingw-w64-ucrt-x86_64-glib2 mingw-w64-ucrt-x86_64-cc mingw-w64-ucrt-x86_64-gexiv2 mingw-w64-ucrt-x86_64-meson mingw-w64-ucrt-x86_64-vala mingw-w64-ucrt-x86_64-gstreamer mingw-w64-ucrt-x86_64-gst-plugins-base mingw-w64-ucrt-x86_64-gdk-pixbuf2 mingw-w64-ucrt-x86_64-gobject-introspection mingw-w64-ucrt-x86_64-gst-plugins-good mingw-w64-ucrt-x86_64-gst-plugins-badUse Meson and Ninja to build the project. When configuring the build with Meson, it automatically detects whether GStreamer is supported and whether GObject Introspection information can be generated.
Meson build options:
gst- Whether to enable GStreamer
- Possible values are
auto,enabled,disabled. Default isauto.
gir- Whether to generate GObject Introspection information
- Possible values are
auto,enabled,disabled. Default isauto.
docs- Whether to generate documentation
- Possible values are
auto,enabled,disabled. Default isauto.
First, you need to clone the project and navigate to the top-level directory of the project. The following reference commands should be executed in the top-level directory of the project:
git clone https://github.com/wszqkzqk/live-photo-conv.git
cd live-photo-convYou can configure the build with the following command:
meson setup builddir --buildtype=releaseIf you do not want to generate GObject Introspection information, for example, you can disable it with the following command:
meson setup builddir --buildtype=release -D gir=disabledThen compile the project:
meson compile -C builddirInstall the project:
meson install -C builddirTo simplify common tasks, this project provides three streamlined command-line tools, which are symbolic links to live-photo-conv but offer a more concise and focused set of options for specific tasks:
live-photo-make: For creating live photos from images and videos.live-photo-extract: For extracting images, videos, and video frames from live photos.live-photo-repair: For repairing corrupted live photos.
For complex scenarios that require all features, you can directly use the more comprehensive live-photo-conv command.
In addition, to address compatibility issues with live photos on Android devices, this project also provides the copy-img-meta tool for copying image metadata to meet additional requirements from phone manufacturers.
Create live photos from images and videos.
Usage:
live-photo-make [OPTION…] - Make Live Photos from image and video files
WebSite: https://github.com/wszqkzqk/live-photo-conv
Report Bugs: https://github.com/wszqkzqk/live-photo-conv/issues
Help Options:
-h, --help Show help options
Application Options:
-v, --version Display version number
--color=LEVEL Color level of log, 0 for no color, 1 for auto, 2 for always, defaults to 1
-i, --image=PATH The path to the main static image file
-m, --video=PATH The path to the video file (required)
-o, --output=PATH The output live photo file path
--export-metadata Export metadata (default)
--drop-metadata Do not export metadata
--use-ffmpeg Use FFmpeg to extract instead of GStreamer
--use-gst Use GStreamer to extract instead of FFmpeg (default)
Create a live photo:
live-photo-make --image /path/to/image.jpg --video /path/to/video.mp4 --output /path/to/output.jpgConvert a video to a live photo:
live-photo-make --video /path/to/video.mp4 --output /path/to/output.jpgExtract images, videos, and video frames from live photos.
Usage:
live-photo-extract [OPTION…] - Extract images and videos from Live Photos
WebSite: https://github.com/wszqkzqk/live-photo-conv
Report Bugs: https://github.com/wszqkzqk/live-photo-conv/issues
Help Options:
-h, --help Show help options
Application Options:
-v, --version Display version number
--color=LEVEL Color level of log, 0 for no color, 1 for auto, 2 for always, defaults to 1
-p, --live-photo=PATH The live photo file to extract (required)
-d, --dest-dir=PATH The destination directory to export
-i, --image=PATH The path to export the main image
-m, --video=PATH The path to export the video
-l, --long-exposure=PATH Convert the embedded video to a long exposure photo
--export-metadata Export metadata (default)
--drop-metadata Do not export metadata
--frame-to-photos Export every frame of the video as photos
-f, --img-format=FORMAT The format of the image exported from video, defaults to automatic detection
--minimal Minimal export, ignore unspecified exports
-T, --threads=NUM Number of threads to use for extracting, 0 for auto
--use-ffmpeg Use FFmpeg to extract instead of GStreamer
--use-gst Use GStreamer to extract instead of FFmpeg (default)
Extract a live photo:
live-photo-extract --live-photo /path/to/live_photo.jpg --dest-dir /path/to/destExtract a live photo and export video frames as images:
live-photo-extract --live-photo /path/to/live_photo.jpg --dest-dir /path/to/dest --frame-to-photos --img-format avifOnly convert the live photo to a long exposure photo without extracting other contents:
live-photo-extract --live-photo /path/to/live_photo.jpg --long-exposure /path/to/long_exposure.jpg --minimalRepair corrupted live photos.
Usage:
live-photo-repair [OPTION…] - Repair Live Photos with missing or corrupted metadata
WebSite: https://github.com/wszqkzqk/live-photo-conv
Report Bugs: https://github.com/wszqkzqk/live-photo-conv/issues
Help Options:
-h, --help Show help options
Application Options:
-v, --version Display version number
--color=LEVEL Color level of log, 0 for no color, 1 for auto, 2 for always, defaults to 1
-p, --live-photo=PATH The live photo file to repair (required)
-f, --force Force to update video offset in XMP metadata and repair
-s, --video-size=SIZE Force repair with the specified video size
Repair a live photo:
live-photo-repair --live-photo /path/to/live_photo.jpglive-photo-conv is a comprehensive tool that integrates all functionalities for creating, extracting, and repairing live photos. Use this command when the simplified tools do not meet your needs.
Usage:
live-photo-conv [OPTION…] - Extract, Repair or Make Live Photos
WebSite: https://github.com/wszqkzqk/live-photo-conv
Report Bugs: https://github.com/wszqkzqk/live-photo-conv/issues
Help Options:
-h, --help Show help options
Application Options:
-v, --version Display version number
--color=LEVEL Color level of log, 0 for no color, 1 for auto, 2 for always, defaults to 1
-g, --make Make a live photo
-e, --extract Extract a live photo (default)
-r, --repair Repair a live photo from missing or corrupted metadata
--force-repair Force repair a live photo (force update video offset in XMP metadata)
--repair-with-video-size=SIZE Force repair a live photo with the specified video size
-i, --image=PATH The path to the main static image file
-m, --video=PATH The path to the video file
-p, --live-photo=PATH The destination path for the live image file. If not provided in 'make' mode, a default destination path will be generated based on the main static image file
-d, --dest-dir=PATH The destination directory to export
--export-metadata Export metadata (default)
--drop-metadata Do not export metadata
--frame-to-photos Export every frame of a live photo's video as a photo
-f, --img-format=FORMAT The format of the image exported from video, defaults to automatic detection
-l, --long-exposure=PATH Convert the embedded video to a long exposure photo
--minimal Minimal export, ignore unspecified exports
-T, --threads=NUM Number of threads to use for extracting, 0 for auto (not work in FFmpeg mode)
--use-ffmpeg Use FFmpeg to extract instead of GStreamer
--use-gst Use GStreamer to extract instead of FFmpeg (default)
Please run live-photo-conv --help to see all command line options. (If GStreamer support is not enabled, the --use-ffmpeg and --use-gst options will not be available)
Operations with live-photo-conv are similar to the simplified commands but require specifying the mode (e.g., --make, --extract, --repair).
Create a live photo:
live-photo-conv --make --image /path/to/image.jpg --video /path/to/video.mp4 --live-photo /path/to/output.jpgExtract a live photo:
live-photo-conv --extract --live-photo /path/to/live_photo.jpg --dest-dir /path/to/destYou can also use URI to specify the path:
live-photo-conv --make --image file:///path/to/image.jpg --video file:///path/to/video.mp4 --live-photo file:///path/to/output.jpgRepair a live photo:
live-photo-conv --repair --live-photo /path/to/live_photo.jpgUsage:
copy-img-meta [OPTION…] <source-img> <dest-img> - Copy the metadata from one image to another
WebSite: https://github.com/wszqkzqk/live-photo-conv
Report Bugs: https://github.com/wszqkzqk/live-photo-conv/issues
Help Options:
-h, --help Show help options
Application Options:
-v, --version Display version number
--color=LEVEL Color level of log, 0 for no color, 1 for auto, 2 for always, defaults to 1
--exclude-exif Do not copy EXIF data
--with-exif Copy EXIF data (default)
--exclude-xmp Do not copy XMP data
--with-xmp Copy XMP data (default)
--exclude-iptc Do not copy IPTC data
--with-iptc Copy IPTC data (default)
Please run copy-img-meta --help to see the command-line options.
Copy metadata from one image to another:
copy-img-meta /path/to/exif-source.jpg /path/to/dest.webpChoose not to copy certain metadata:
copy-img-meta --exclude-xmp --exclude-iptc /path/to/exif-source.jpg /path/to/dest.webp- Warning: The API of this library may change with future versions.
liblivephototools is a library for creating and extracting live photos, as well as exporting frames from embedded videos. It can be used in any language that supports GObject Introspection, such as C, Vala, Rust, C++, Python, etc.
For example, in Python, make sure the python-gobject package has been installed, and then import the library:
import gi
gi.require_version('LivePhotoTools', '0.4') # Adjust according to the actual version number
from gi.repository import LivePhotoToolsUsage example:
# Load a live photo
livephoto = LivePhotoTools.LivePhotoGst.new("MVIMG_20241104_164717.jpg")
# Extract the static image from the live photo
livephoto.export_main_image()
# Extract the video from the live photo
livephoto.export_video()
# Export frames from the embedded video
livephoto.split_images_from_video(None, None, 0)
# Convert the live photo to a long exposure photo
livephoto.generate_long_exposure("long_exposure.jpg")# Create a live photo
livemaker = LivePhotoTools.LiveMakerGst.new('VID_20241104_164717.mp4', 'IMG_20241104_164717.jpg')
# Export
livemaker.export()This project is licensed under the LGPL-2.1-or-later license. For more details, see the COPYING file.
If GStreamer support is enabled during the build, GStreamer will be used by default to export images from embedded videos. Otherwise, the program will attempt to create an FFmpeg subprocess via command to export images. Even with GStreamer support enabled, you can use the --use-ffmpeg option to use FFmpeg.
The speed of exporting images using GStreamer versus FFmpeg is not always consistent. The GStreamer-based video export tool built by me encodes in parallel, and the number of threads can be controlled by adjusting the -T/--threads option. However, I has not optimized the decoding part of GStreamer very well; each frame undergoes a forced color space conversion （due to the limitation of gdk-pixbuf2）, which may introduce performance overhead. Therefore, in summary:
- When the selected image encoding is slow, GStreamer exports images faster.
- When the selected image encoding is fast, FFmpeg exports images faster.
Due to limitations in Exiv2 and incomplete bindings in GExiv2, it is currently not possible on Windows to read or write metadata for paths that contain non-ASCII characters.
Due to the fragmentation among Android phone manufacturers, different vendors may require proprietary metadata in live photos to correctly recognize them. As a result, live photos generated by this tool may not be recognized on some devices.
Workarounds:
- Take a photo (usually not live photo) with a phone from the respective manufacturer.
- Use
copy-img-meta --exclude-xmp <source_image> <dest_image>to copy the metadata from that photo to the generated live photo. - If the phone recognizes the live photo but fails to play it, repair the live photo using the
live-photo-convtool:- For example, run
live-photo-conv --repair -p /path/to/live_photo.jpg - Or force a repair with
live-photo-conv --force-repair -p /path/to/live_photo.jpg - In rare cases where the repair still fails, you can try specifying the embedded video size using
live-photo-conv --repair-with-video-size=SIZE -p /path/to/live_photo.jpg(usually not necessary)
- For example, run
You can also copy the metadata to the ordinary photo used to create the live photo beforehand, and then use the live-photo-conv tool to create the live photo (recommended):
copy-img-meta --exclude-xmp /path/to/source.jpg /path/to/dest.jpg
live-photo-conv --make --image /path/to/dest.jpg --video /path/to/video.mp4 --live-photo /path/to/output.jpgThis way, you can obtain a live photo that is recognized and playable on the respective brand's phone.