LivePhoto Processing in XHS-Downloader#

LivePhoto refers to XiaoHongShu's (小红书) feature where image posts can carry an accompanying short video clip per image — analogous to Apple Live Photos. In XHS-Downloader, each image entry in the API's imageList array may include an H.264 video stream URL alongside the static image URL. The downloader extracts, tracks, and optionally saves those video clips independently of the static image files.

Extraction from imageList#

The entry point for LivePhoto URL extraction is Image.get_image_link() in source/application/image.py. It:

1. Reads the imageList array from the API response via data.safe_extract("imageList", []) 1.
2. Immediately calls __get_live_link(images), which iterates every image item and pulls the H.264 master URL at the JSON path stream.h264[0].masterUrl 2. If no such URL exists for an item, None is stored at that position.
3. Returns a parallel pair of lists — (image_urls, live_links) — preserving index correspondence between static images and their video counterparts 3.

LivePhoto video URLs are served as plain HTTP URLs and are formatted through Html.format_url() before being returned 4.

Download Behavior#

The (urls, lives) pair from Image.get_image_link() is passed to Download.run(), which routes image/album posts to __ready_download_image().

Inside __ready_download_image(), each image and its paired live video are handled together via zip(urls, lives) 5. The LivePhoto video download task is added only when all three conditions are met 6:

1. self.live_download is True
2. The live URL for this image is not None
3. The corresponding .mp4 file does not already exist on disk

The live video file is saved using the same base filename as its paired image (e.g. {filename}_1.mp4, {filename}_2.mp4, …), distinguished by the live_format which is always "mp4" 7.

Configuration#

The live_download flag controls whether LivePhoto video components are downloaded. It is wired through several layers:

Note: The default in settings.json is False 8, meaning LivePhoto video files are not downloaded unless explicitly enabled. The Manager fallback default when the value is not a boolean is True 9, but since settings.py always writes a proper boolean, the effective out-of-box default is False.

To enable LivePhoto downloads, set "live_download": true in settings.json.

Data Flow Summary#

API imageList[]
    └─ Image.get_image_link()
           ├─ static image URLs ──────────────────────────┐
           └─ live_link[] (stream.h264[0].masterUrl | None) │
                                                             ▼
                                               Download.__ready_download_image()
                                                   ├─ always queues static image
                                                   └─ queues live .mp4 if live_download=True AND URL present

Key Files#