Live Photo Converter

• 中文版本

Live Photo Converter is a cross-platform tool for processing live photos, providing an easy-to-use and modern GUI based on GTK4 / LibAdwaita, CLI, and function library.

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.

Features

• live-photo-conv-gtk
  • Graphical interface for making, extracting and repairing live photos (GTK4 / LibAdwaita)
• 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.

Easy Installation

Windows (MSYS2)

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-conv

Arch Linux

On Arch Linux, you can install directly from the AUR using an AUR helper like paru:

paru -S live-photo-conv

Alternatively, 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 -si

Flatpak

Download the .flatpak bundle from GitHub Releases and install (recommended):

flatpak install --user live-photo-conv*.flatpak

To build directly from source with flatpak-builder:

git clone https://github.com/wszqkzqk/live-photo-conv.git
cd live-photo-conv
flatpak install --user flathub org.gnome.Sdk//50 org.gnome.Platform//50
flatpak-builder --user --install --force-clean build-flatpak com.github.wszqkzqk.live-photo-conv.yml
flatpak run com.github.wszqkzqk.live-photo-conv

Manual Build

Dependencies

• Build Dependencies
  • Meson, Vala, GExiv2
  • GTK4, LibAdwaita (optional, for the GUI)
  • GStreamer (gstreamer, gst-plugins-base-libs) — optional, for exporting images from videos; FFmpeg used otherwise
  • gdk-pixbuf2 — optional, same as above
  • gobject-introspection — optional, for generating GObject Introspection data
• Runtime Dependencies
  • GLib (GObject, GIO), GExiv2
  • GTK4, LibAdwaita (required by the GUI)
  • GStreamer (gstreamer, gst-plugins-base-libs, gst-plugins-good, gst-plugins-bad) — required when built with GStreamer; gst-plugin-va optional, for hardware acceleration
  • gdk-pixbuf2 — required when built with GStreamer; optional format loaders: libavif (.avif), libheif (.heif/.heic/.avif), libjxl (.jxl), webp-pixbuf-loader (.webp)
  • FFmpeg — optional, required when not built with GStreamer and need to export images from videos

For example, to install dependencies on Arch Linux:

sudo pacman -S --needed glib2 libgexiv2 meson vala gtk4 libadwaita gstreamer gst-plugins-base-libs gdk-pixbuf2 gobject-introspection gst-plugins-good gst-plugins-bad gst-plugin-va

To install dependencies on Debian/Ubuntu:

sudo apt install build-essential meson valac libgexiv2-dev libglib2.0-dev libgtk-4-dev libadwaita-1-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-vaapi

To 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-gtk4 mingw-w64-ucrt-x86_64-libadwaita 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-bad

Compilation

Use 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 is auto.
• gir
  • Whether to generate GObject Introspection information
  • Possible values are auto, enabled, disabled. Default is auto.
• gui
  • Whether to build the GTK4/LibAdwaita GUI
  • Possible values are auto, enabled, disabled. Default is auto.
• docs
  • Whether to generate documentation
  • Possible values are auto, enabled, disabled. Default is auto.

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-conv

You can configure the build with the following command:

meson setup builddir --buildtype=release

If 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=disabled

Then compile the project:

meson compile -C builddir

Install the project:

meson install -C builddir

Usage

live-photo-conv-gtk (GUI)

The graphical interface provides an intuitive way to make, extract and repair live photos without using the command line. Launch it from your application launcher or terminal:

live-photo-conv-gtk

Three tabs cover all operations:

• Make — combine a video (and optional image) into a live photo. Drag files or click to browse, then click the button to choose where to save.

  

• Extract — select a live photo, tick what to export (main image, video, long exposure, frames), choose an output directory. Supports batch processing of multiple live photos.

  

• Repair — fix corrupted XMP metadata in a live photo. Advanced options for manual video size are available if needed. Supports batch processing of multiple live photos.

  

CLI Tools

To 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: Create live photos from images and videos.
• live-photo-extract: Extract images, videos, and video frames from live photos.
• live-photo-repair: Repair corrupted live photos.
• live-photo-conv: A comprehensive command for all features.
• copy-img-meta: Copy metadata between images.

Run any command with --help to see all available options.

live-photo-make

Create a live photo:

live-photo-make -i /path/to/image.jpg -m /path/to/video.mp4 -o /path/to/output.jpg

Convert a video directly to a live photo:

live-photo-make -m /path/to/video.mp4 -o /path/to/output.jpg

Key options: -i (image), -m (video, required), -o (output), --drop-metadata, --use-ffmpeg / --use-gst.

live-photo-extract

Extract a live photo:

live-photo-extract -p /path/to/live_photo.jpg -d /path/to/dest

Extract and export video frames:

live-photo-extract -p /path/to/live_photo.jpg -d /path/to/dest --frame-to-photos -f avif

Only generate a long exposure photo:

live-photo-extract -p /path/to/live_photo.jpg -l /path/to/long_exposure.jpg --minimal

Key options: -p (live photo, required), -d (output directory), -i (image), -m (video), -l (long exposure), --frame-to-photos, -f (image format), -T (threads), --minimal, --drop-metadata.

live-photo-repair

Repair a live photo:

live-photo-repair -p /path/to/live_photo.jpg

Force repair:

live-photo-repair -p /path/to/live_photo.jpg -f

Key options: -p (live photo, required), -f (force), -s (manual video size).

live-photo-conv (Generic Command)

Operations are similar to the simplified commands but require specifying the mode with --make, --extract, or --repair:

live-photo-conv --make -i /path/to/image.jpg -m /path/to/video.mp4 -p /path/to/output.jpg
live-photo-conv --extract -p /path/to/live_photo.jpg -d /path/to/dest
live-photo-conv --repair -p /path/to/live_photo.jpg

copy-img-meta

Copy all metadata:

copy-img-meta /path/to/source.jpg /path/to/dest.webp

Exclude certain metadata:

copy-img-meta --exclude-xmp --exclude-iptc /path/to/source.jpg /path/to/dest.webp

Key options: --exclude-exif / --with-exif, --exclude-xmp / --with-xmp, --exclude-iptc / --with-iptc.

liblivephototools

• 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.

Example

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 LivePhotoTools

Usage 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()

License

This project is licensed under the LGPL-2.1-or-later license. For more details, see the COPYING file.

FAQ

Exporting Images from Embedded Videos: Using FFmpeg or GStreamer?

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.

Path Encoding on Windows: Unable to Read/Write Metadata for Paths Containing Non-ASCII Characters

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.

Fragmentation Among Android Manufacturers: Live Photos Not Recognized

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-conv tool:
  • 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)

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.jpg

This way, you can obtain a live photo that is recognized and playable on the respective brand's phone.

Contributing

Code Contributions

This project uses Meson as the build system and is primarily written in Vala. See Manual Build for build instructions. Pull requests should target the main branch.

Translations

Translations are managed on Hosted Weblate. Please use Weblate rather than opening pull requests for translation changes.