XHS-Downloader

Parses XiaoHongShu (RedNote) work URLs to extract structured metadata including post ID, author information, caption text, image/video URLs, and engagement metrics. Uses HTTP request interception with cookie-based authentication to bypass platform anti-scraping measures and retrieve JSON API responses from XHS endpoints, then deserializes and normalizes the response into a standardized work object with media asset references.

Downloads image and video files from XiaoHongShu work URLs and removes platform watermarks by fetching clean media assets directly from XHS CDN endpoints. Supports batch downloading with customizable file naming patterns (template-based: {work_id}_{index}_{timestamp}), automatic format conversion (MP4 video codec normalization, JPEG/PNG image optimization), and resumable downloads with partial file recovery using HTTP range requests.

Stores all downloaded works, extracted links, and search results in a SQLite database with tables for works (work_id, title, author, media_urls, download_status), downloads (download_id, work_id, timestamp, file_paths), and searches (search_query, result_count, timestamp). Implements deduplication logic to prevent re-downloading the same work, tracks download status (pending, completed, failed), and enables querying download history by date range, author, or content type. Database schema includes indexes on frequently-queried columns (work_id, timestamp) for performance.

Manages XiaoHongShu session authentication by storing and refreshing cookies in a persistent cookie jar. Reads cookies from browser storage (via browser extension or manual export) or accepts cookies as configuration input. Implements automatic cookie refresh logic that detects expired sessions (HTTP 401 responses) and attempts to refresh cookies using stored refresh tokens or re-authentication flow. Validates cookie freshness before each request and logs authentication failures for debugging.

Supports template-based file naming and folder organization using variable substitution. Naming templates can include variables like {work_id}, {author}, {title}, {timestamp}, {index} which are replaced with actual values from work metadata. Implements folder structure templates (e.g., {author}/{timestamp}/{work_id}) for organizing downloads into hierarchical directories. Validates template syntax and provides default templates for common use cases (flat structure, author-based organization, date-based organization).

Supports batch downloading of multiple XHS URLs with configurable rate limiting to avoid triggering XHS anti-scraping measures. Implements exponential backoff retry logic for failed downloads (retry up to 3 times with increasing delays), tracks download progress across the batch, and provides detailed error reports for failed items. Rate limiting is configurable (requests per second, delay between downloads) and can be adjusted based on observed XHS response patterns.

Manages all user-configurable parameters through a settings.json file with schema validation and default values. Supports configuration hierarchy: command-line arguments override settings.json, which overrides built-in defaults. Implements configuration validation (type checking, range validation for numeric fields, enum validation for choice fields) and provides clear error messages for invalid configurations. Automatically migrates settings.json schema when application version changes, preserving user settings while adding new fields.

Extracts and aggregates work links from XiaoHongShu user profiles across multiple collection types: published works, bookmarked/saved posts, liked posts, and custom albums. Uses paginated API requests to the XHS user profile endpoint with cursor-based pagination, iterating through all available pages to build a complete inventory of work URLs. Stores extracted links in SQLite database with metadata (collection type, extraction timestamp, user ID) for deduplication and tracking.

Executes XiaoHongShu search queries and extracts work and user links from paginated search results. Sends search requests to XHS search API endpoint with query parameters (keyword, filters, sort order), processes paginated JSON responses containing work and user cards, and extracts URLs with optional filtering by content type, engagement metrics, or publication date. Results are stored in SQLite with search metadata for reproducibility.

Implements a single entry point (main.py) that dispatches execution to five distinct user interfaces based on command-line arguments and configuration: Terminal UI (TUI) for interactive use, CLI for single-command automation, Browser UserScript for in-browser convenience, REST API Server for programmatic integration, and MCP Server for AI assistant integration. Each interface converges on the core XHS class, which coordinates content extraction, download, and storage operations through a shared processing pipeline.

Provides an interactive terminal-based UI built with the Textual framework that monitors system clipboard for XHS URLs, displays real-time download progress, and allows users to configure settings without editing JSON files. Implements a multi-panel layout with URL input field, download queue display, progress bars, and settings editor. Clipboard monitoring runs in a background thread that detects new XHS URLs and automatically queues them for download when enabled.

Provides a command-line interface for single-command downloads with support for specifying which images/videos to download from a multi-media post. Accepts XHS URL as argument, optional image index range (e.g., --images 1-3 to download only images 1-3), and configuration overrides (--output-dir, --naming-template). Executes download synchronously and exits with status code indicating success/failure, suitable for shell scripts and CI/CD pipelines.

Provides a Tampermonkey/Greasemonkey UserScript that runs in the browser and enables in-browser downloads or server-push mode. In standalone mode, the script uses browser APIs (Fetch API, Blob) to download files directly to the user's Downloads folder. In server-push mode (script_server=true in config), the script detects XHS URLs on the page, extracts work IDs, and sends download requests to a running XHS-Downloader instance via HTTP POST, offloading processing to the server while providing browser-side convenience.

Exposes XHS-Downloader functionality as a REST API server running on port 5556 with FastAPI framework. Provides endpoints for work detail retrieval (/xhs/detail), download submission (/xhs/download), and download status polling (/xhs/status). Accepts JSON request bodies with XHS URLs and configuration parameters, processes requests asynchronously using a task queue, and returns JSON responses with download status, file paths, and error messages. Supports CORS for cross-origin requests from web applications.

Exposes XHS-Downloader as an MCP Server running on port 5556, enabling AI assistants (Claude, ChatGPT with plugins, etc.) to call XHS-Downloader functions as tools. Implements MCP protocol handlers for work extraction, download submission, and status checking. AI assistants can invoke these tools within their reasoning loops, enabling autonomous content extraction and download workflows orchestrated by the AI model.