Hexo-live-photo

A lightweight and user-friendly Hexo plugin for displaying Live Photos (dynamic photos) and similar dynamic images taken by devices like iPhones and Androids in your blog posts.

Origin and Introduction

Modern smartphones (such as iPhone’s Live Photo and similar features on some Android devices) can capture dynamic photos, recording approximately 3 seconds of video and audio before and after the shot. However, when deploying blog posts to static websites, these dynamic photos are often reduced to static JPEG images, losing their vivid essence.

Hexo-live-photo was created to solve this problem. It parses Live Photo resources (a .jpg image and a .mp4 video) and utilizes HTML5 video playback technology to perfectly restore the dynamic photo playback effect in your Hexo blog without affecting page load performance, making your memories more vivid.

Live

Dynamic Image Display

Installation

Run the following command in the root directory of your Hexo blog:

1	npm install hexo-live-photo --save

Configuration

Add the following options to the main configuration file _config.yml of Hexo:

# Live Photo Plugin Configuration
livephoto:
  enable: true
  autoplay: true          # Whether to auto-play (when entering the viewport)
  hover_to_play: true     # Whether to enable hover-to-play
  click_to_play: true    # Whether to enable click-to-play
  lazy_load: true         # Whether to enable lazy loading
  threshold: 0.8          # The visible proportion to trigger auto-play
  badge: true             # Whether to display the Live badge
  badge_text: 'Live'      # Badge text
  badge_position: 'bottom-left' # Badge position: bottom-left, bottom-right, top-left, top-right
  loading_animation: true # Whether to display a loading animation
  preload: 'auto'         # Video preloading strategy: auto, metadata, none
  keep_observing: false   # Whether to continuously observe the element
  hover_delay: 300        # Hover delay (milliseconds)
  touch_delay: 100        # Touch delay (milliseconds)
  weixin_disable_autoplay: true # Whether to disable auto-play in the WeChat built-in browser

Usage Guide

Preparing Resource Files

Ensure you have the two core files for the dynamic photo:

Video File (.mp4): The video part of the dynamic photo
Cover Image File (.jpg): The static cover part of the dynamic photo

Place these two files in your Hexo blog source directory, for example, source/images/posts/.

Example File Structure:

1 2	source/images/posts/my-vacation.jpg source/images/posts/my-vacuation.mov

It is recommended to use object storage or a CDN to host these resources to improve loading speed and user experience.

Example URL Structure:

1 2	https://your-cdn.com/images/posts/my-vacation.jpg https://your-cdn.com/images/posts/my-vacation.mp4

Using in Articles

Use the {% live_photo %} tag anywhere in your Markdown articles (.md files) where you need to insert a dynamic photo.

Basic Syntax:

1	{% livephoto image_path video_path %}

Displaying Two Dynamic Photos in a Row:

The plugin includes built-in CSS code that uses Flexbox layout, allowing you to achieve this with HTML code.

<div class="image-grid">
  <div class="image-column">
    {% livephoto image_path video_path %}
  </div>
  <div class="image-column">
    {% livephoto image_path video_path %}
  </div>
</div>

Advanced Usage

You can add additional parameters within the tag, such as custom titles, and set width and height.

Extended Syntax:

1	{% livephoto image_path video_path "Image Description" "Optional Title" "Optional Width" "Optional Height" %}

Example:

1	{% livephoto /images/sunset.jpg /videos/sunset.mp4 "Beach Sunset" "Maldives Sunset Beauty" "600px" %}

Implementation Principle

The plugin generates the following HTML structure:

<div class="live-photo-container" id="livePhoto">
    <img src="/images/sunset.jpg" alt="Beach Sunset" class="static-image">
    <video class="video" muted playsinline>
        <source src="/videos/sunset.mp4" type="video/mp4">
    </video>
    <div class="live-badge">Live</div>
</div>

Interaction: When you scroll down the page and the image fully enters the viewport, the Live Photo will auto-play once. The video will play again when the mouse hovers or when it is touched.
Appearance: The “Live” badge can be displayed in one of the four corners of the image to enhance the recognition of dynamic photos.

Notes

Video Format: It is recommended to use MP4 format encoded with H.264 to ensure compatibility with most browsers.
Performance: Although the plugin is optimized, please ensure the video files are not too large and consider using a fast CDN to host video resources.
Browser Support: Ensure your browser supports HTML5 video playback. After testing, the Xiaomi browser will convert the video to a video player, although this does not affect viewing, you will lose the opportunity to download the static image and the dynamic playback experience.
WeChat Browser: Since the WeChat built-in browser has strict restrictions on auto-play, it is recommended to enable the weixin_disable_autoplay option to avoid white screen issues caused by auto-play.

Change Log

V1.1.2: Fixed the display issue of the loading indicator, added CSS styles for displaying two images in a row on mobile devices.
V1.1.1: Added compatibility support for WeChat, fixed auto-play issues in some browsers.