Video Quality Selection#

XHS-Downloader selects the highest-quality video file available from XiaoHongShu's API by sorting all available stream variants according to a user-defined preference metric. A cookie is required to unlock higher-quality tiers from the API; without one, only low-resolution files are accessible.

video_preference Setting#

The video_preference key in settings.json controls the sort dimension used to rank quality tiers. Three values are accepted 1:

Invalid values fall back to "resolution" 2.

How Selection Works#

The entry point is Video.deal_video_link(data, preference). It tries a fast path first:

1. generate_video_link 3 — if the API response contains a direct video.consumer.originVideoKey, it constructs a CDN URL at https://sns-video-bd.xhscdn.com/{key} and returns it immediately, bypassing quality selection.
2. get_video_link 4 — if no direct key exists, it fetches all H.264 and H.265 stream objects from video.media.stream.h264 and video.media.stream.h265 5, sorts them by the requested metric, and returns either the first backupUrls entry or the masterUrl of the highest-ranked variant.

The call site in app.py passes self.manager.video_preference directly 6:

container["下载地址"] = self.video.deal_video_link(data, self.manager.video_preference)

Cookie and Quality Tier Access#

The README explicitly warns: without a cookie, video downloads are limited to low-resolution files; configuring a cookie unlocks higher quality — no login required 7.

Cookies are integrated at the HTTP client level. Manager.__init__ converts the cookie string to a dict via cookie_str_to_dict and injects it into the AsyncClient used for all API requests 8. The cookie parameter is optional in settings.json 9 and also overridable per-request via the API mode's cookie field 10.

To obtain a valid cookie, the README instructs filtering the browser DevTools Network tab for cookie-name:web_session while visiting xiaohongshu.com/explore, then copying the full Cookie header 11.

The Manager.clean_cookie utility strips webId and web_session tokens from a cookie string 12 — used when displaying or logging cookies without sensitive values.

Configuration Reference#

Key source files:

• source/application/video.py — quality selection logic
• source/module/manager.py — cookie injection and preference validation
• source/module/settings.py — default configuration values
• source/application/app.py — call site wiring video_preference into extraction