XPath Downloader

A powerful, highly customizable browser extension (built on Manifest V3) designed to extract and download media files (images, videos, audio tracks, or generic files) and text content from any webpage using user-defined XPath expressions. Official Website: rednebula.org/xpath-downloader —

🚀 Features

• Customizable XPath Selection: Specify multiple alternative XPaths for images/videos. The extension tries them in order, stopping at the first successful match. This allows a single profile to work across multiple page layouts.
• Interactive Element Picker (Dropper): Click the eye icon (👁) next to Name or Date fields to select an element directly on the page. The extension automatically calculates a clean XPath for the selected element.
• Dynamic Filename Formatting: Automate file organization by constructing filenames dynamically using extracted page metadata:
  • Custom Prefix (e.g., myphoto_).
  • XPath for Name (e.g., uploader’s name).
  • XPath for Date (e.g., post date from attributes like datetime or inner text).
  • Resulting Format: [Prefix][Name]_[Date_Time]_[Index].[extension]
• List Navigation & Batch Preview: If an XPath points to a list container element (<ul> or <ol>), the extension extracts media links from all child <li> items. A built-in list navigator (Previous/Next buttons) appears in the popup, allowing you to cycle through, preview, and download each item in sequence.
• Smart Media Previews: Detects and displays real-time previews inside the popup based on the file type:
  • Images: Displays the natural dimensions/resolution.
  • Videos: Supports standard HTML5 video previews.
  • Audio: Renders a playable audio preview controller.
  • Documents/Other: Shows a generic file icon highlighting the extension.
• Text Extraction Mode: If the XPath resolves to text instead of media (e.g., an article body or description), the extension switches to text mode, displaying the text in the popup with a “Copy All” button.
• Domain-Specific Profiles: Save your configurations (prefix, XPaths, name/date fields) as profiles. The extension automatically matches the current site’s hostname and loads the correct settings when you open the popup.

• Backup & Sharing: Export saved profiles as a JSON file, or import existing profiles to set up another device instantly.

  🛠️ How It Works (Under the Hood)

  CORS Bypass System

  Many websites block media downloads or canvas image rendering from other origins due to Cross-Origin Resource Sharing (CORS) rules. XPath Downloader dynamically injects headers (Access-Control-Allow-Origin: * and Access-Control-Allow-Methods: GET, OPTIONS) into network GET requests using Chromium’s declarativeNetRequest API. This allows the extension popup to successfully request and download media files that would otherwise be blocked.

  CORS Exclusion List

  Modifying CORS headers can break or conflict with DRM-protected streaming sites and major media platforms. Under the CORS Bypass settings, you can specify domains (one per line) to exclude from modifications. By default, platforms like YouTube, Netflix, Disney+, Prime Video, Twitch, HBO/Max, and Globoplay are pre-configured to be bypassed/ignored to ensure they load normally.

  Blob URLs and Media Source Extensions (MSE) handling

  Some websites load video and audio streams as encrypted or segmented blobs (blob:https://...), which cannot be downloaded or previewed directly via normal URLs.

• For image or audio blobs: The content script fetches the raw data inside the website’s execution context and sends it to the extension as a Base64-encoded string.

• For video blobs (MSE): The content script uses the Performance Resource Timing API to inspect network transfers, matching the largest transferred segments to find the real source URL of the video file, making downloads possible.

  📦 Installation (Developer Mode)

  Since this extension is built using Manifest V3, you can load it directly into any Chromium-based browser (Chrome, Edge, Brave, Opera, Vivaldi):

  1. Clone or download this repository.
  2. Open your browser and navigate to chrome://extensions/ (or equivalent).
  3. Enable Developer mode (usually a toggle in the top-right corner).
  4. Click on Load unpacked (Carregar sem compactação).

  5. Select the folder containing this extension (where manifest.json is located).

     📖 User Guide & Workflow

     Step 1: Open Settings

     Open the extension popup and click the Gear icon (⚙) at the top-right to access the settings.

     Step 2: Define your XPaths

• Filename Prefix: (Optional) Enter text to prepend to all downloaded files.
• XPath Complete: (Required) Add one or more XPaths pointing to the main media elements on the page (e.g., //img[@id='main-image'] or //video). Click “Add” to input alternative XPaths for different pages.
• XPath - Name: (Optional) Enter the XPath pointing to the uploader name or profile name.
• XPath - Date: (Optional) Enter the XPath pointing to the post date.
• Tip: Click the eye icon (👁) on the Name or Date fields to point and click on the webpage to automatically fill the field with the correct XPath.

  Step 3: Save Profile

  Scroll up to the “Profiles” section:

• Click New (Novo).
• Enter a recognizable name. The extension will associate it with the current site’s domain.
• Click Save Profile (Salvar perfil).
• Click Save and Analyze (Salvar e Analisar) at the bottom.

  Step 4: Download Media

  Once back on the Main View:

• Check the preview and file resolution.
• Verify the dynamically constructed file name.
• If it’s a list, use the navigation arrows (← / →) to find the correct item.

• Click the Download button. The download will start automatically in your browser’s default downloads directory.

  🔐 Permissions Used

• activeTab: To inspect and run xpath queries in the active tab context.
• downloads: To trigger downloads directly using the browser’s native download manager.
• scripting: To dynamically inject the content script parser into tabs.
• storage: To save profiles, prefixes, settings, and CORS exclusions.
• declarativeNetRequest & declarativeNetRequestWithHostAccess: To safely modify CORS response headers for unblocked file downloads.
• Host Permissions (<all_urls>): Required for the dynamic rule system to bypass CORS across all source domains.