Kemono-Downloader/features.md

Kemono Downloader - Comprehensive Feature Guide

This guide provides a detailed overview of all user interface elements, input fields, buttons, popups, and functionalities available in the application.

---

1. URL Input (🔗)

This is the primary input field where you specify the content you want to download.

Functionality:

• Creator URL: A link to a creator's main page (e.g., https://kemono.su/patreon/user/12345). Downloads all posts from the creator.
• Post URL: A direct link to a specific post (e.g., .../post/98765). Downloads only the specified post.

Interaction with Other Features: The content of this field influences "Manga Mode" and "Page Range". "Page Range" is enabled only with a creator URL.

---

2. Creator Selection & Update (🎨)

The color palette emoji button opens the Creator Selection & Update dialog. This allows managing and downloading from a local creator database.

Functionality:

• Creator Browser: Loads a list from creators.json. Search by name, service, or paste a URL to find creators.
• Batch Selection: Select multiple creators and click "Add Selected" to add them to the batch download session.
• Update Checker: Use a saved profile (.json) to download only new content based on previously fetched posts.
• Post Fetching & Filtering: "Fetch Posts" loads post titles, allowing you to choose specific posts for download.

---

3. Download Location Input (📁)

This input defines the destination directory for downloaded files.

Functionality:

• Manual Entry: Enter or paste the folder path.
• Browse Button: Opens a system dialog to choose a folder.
• Directory Creation: If the folder doesn't exist, the app can create it after user confirmation.

---

4. Filter by Character(s) & Scope Button

Used to download content for specific characters or series and organize them into subfolders.

Input Field (Filter by Character(s)):

• Enter comma-separated names (e.g., Tifa, Aerith).
• Group aliases using parentheses (e.g., (Cloud, Zack)).
• Names are matched against titles, filenames, or comments.
• If "Separate Folders by Known.txt" is enabled, the name becomes the subfolder name.

Scope Button Modes:

• Filter: Title (default) – Match names in post titles only.
• Filter: Files – Match names in filenames only.
• Filter: Both – Try title match first, then filenames.
• Filter: Comments – Try filenames first, then post comments if no match.

---

5. Skip with Words & Scope Button

Prevents downloading content based on keywords.

Input Field (Skip with Words):

• Enter comma-separated keywords (e.g., WIP, sketch, preview).
• Matching is case-insensitive.
• If a keyword matches, the file or post is skipped.

Scope Button Modes:

• Scope: Posts (default) – Skips post if title contains a keyword.
• Scope: Files – Skips individual files with keyword matches.
• Scope: Both – Skips entire post if title matches, otherwise filters individual files.

Filter File Section (Radio Buttons)

This section uses a group of radio buttons to control the primary download mode, dictating which types of files are targeted. Only one of these modes can be active at a time.

• All: Default mode. Downloads every file and attachment provided by the API, regardless of type.
• Images/GIFs: Filters for common image formats (.jpg, .png, .gif, .webp), skipping non-image files.
• Videos: Filters for common video formats like .mp4, .webm, and .mov, skipping all others.
• Only Archives: Downloads only archive files (.zip, .rar). Disables "Compress to WebP" and unchecks "Skip Archives".
• Only Audio: Filters for common audio formats like .mp3, .wav, and .flac.
• Only Links: Extracts external hyperlinks from post descriptions (e.g., Mega, Google Drive) and displays them in the log. Disables all download options.
• More: Opens the "More Options" dialog to download text-based content instead of media files.
  • Scope: Choose to extract from post description or comments.
  • Export Format: Save text as PDF, DOCX, or TXT.
  • Single PDF: Optionally compile all text into one PDF.

---

Check Box Buttons

These checkboxes provide additional toggles to refine the download behavior and enable special features.

• ⭐ Favorite Mode: Changes workflow to download from your personal favorites. Disables the URL input.
  • Favorite Artists: Opens a dialog to select from your favorited creators.
  • Favorite Posts: Opens a dialog to select from your favorited posts on Kemono and Coomer.
• Skip Archives: When checked, archive files (.zip, .rar) are ignored. Disabled in "Only Archives" mode.
• Download Thumbnail Only: Saves only thumbnail previews, not full-resolution files. Enables "Scan Content for Images".
• Scan Content for Images: Parses post HTML for embedded images not listed in the API. Looks for <img> tags and direct image links.
• Compress to WebP: Converts large images (over 1.5 MB) to WebP format using the Pillow library for space-saving.
• Keep Duplicates: Provides control over duplicate handling via the "Duplicate Handling Options" dialog.
  • Skip by Hash: Default – skip identical files.
  • Keep Everything: Save all files regardless of duplication.
  • Limit: Set a limit on how many copies of the same file are saved. A limit of 0 means no limit.

Folder Organization Checkboxes

• Separate folders by Known.txt: Automatically organizes downloads into folders based on name matches.
  • Uses "Filter by Character(s)" input first, if available.
  • Then checks names in Known.txt.
  • Falls back to extracting from post title.
• Subfolder per post: Creates a unique folder per post, using the post’s title.
  • Prevents mixing files from multiple posts.
  • Can be combined with Known.txt-based folders.
  • Ensures uniqueness (e.g., My Post Title_1).
  • Automatically removes empty folders.
• Date prefix: Enabled only with "Subfolder per post". Prepends the post date (e.g., 2025-08-03 My Post Title) for chronological sorting.

General Functionality Checkboxes

• Use cookie: Enables login-based access via cookies.
  • Paste cookie string directly, or browse to select a cookies.txt file.
  • Cookies are used in all authenticated API requests.
• Use Multithreading: Enables parallel downloading of posts.
  • Specify the number of worker threads (e.g., 10).
  • Disabled for Manga Mode and Only Links mode.
• Show external links in log: Adds a secondary log that displays links (e.g., Mega, Dropbox) found in post text.
• Manga/Comic mode: Sorts posts chronologically before download.
  • Ensures correct page order for comics/manga.
  Scope Button (Name: ...): Controls filename style:
  • Name: Post Title — e.g., Chapter-1.jpg
  • Name: Date + Original — e.g., 2025-08-03_filename.png
  • Name: Date + Title — e.g., 2025-08-03_Chapter-1.jpg
  • Name: Title+G.Num — e.g., Page_001.jpg
  • Name: Date Based — e.g., 001.jpg, with optional prefix
  • Name: Post ID — uses unique post ID as filename

Start Download

• Default State ("⬇️ Start Download"): When idle, this button gathers all current settings (URL, filters, checkboxes, etc.) and begins the download process via the DownloadManager.
• Restore State: If an interrupted session is detected, the tooltip will indicate that starting a new download will discard previous session progress.
• Update Mode (Phase 1 - "🔄 Check For Updates"): If a creator profile is loaded, clicking this button will fetch the creator's posts and compare them against your saved profile to identify new content.
• Update Mode (Phase 2 - "⬇️ Start Download (X new)"): After new posts are found, the button text updates to reflect the number. Clicking it downloads only the new content.

Pause / Resume Download

• While Downloading: The button toggles between:
  • "⏸️ Pause Download": Sets a pause_event, which tells all worker threads to halt their current task and wait.
  • "▶️ Resume Download": Clears the pause_event, allowing threads to resume their work.
• While Idle: The button is disabled.
• Restore State: Changes to "🔄 Restore Download", which resumes the last session from saved data.

Cancel & Reset UI

• Functionality: Stops downloads gracefully using a cancellation_event. Threads finish current tasks before shutting down.
• The Soft Reset: After cancellation is confirmed by background threads, the UI resets via the download_finished function. Input fields (URL and Download Location) are preserved for convenience.
• Restore State: Changes to "🗑️ Discard Session", which deletes session.json and resets the UI.
• Update State: Changes to "🗑️ Clear Selection", unloading the selected creator profile and returning to normal UI state.

Error Button

• Error Counter: Shows how many files failed to download (e.g., (3) Error). Disabled if there are no errors.
• Error Dialog: Clicking opens the "Files Skipped Due to Errors" dialog (defined in ErrorFilesDialog.py), listing all failed files.
• Dialog Features:
  • View Failed Files: Shows filenames and related post info.
  • Select and Retry: Retry selected failed files in a focused download session.
  • Export URLs: Save a .txt file of direct download links. Optionally include post metadata with each URL.

"Known Area" and its Controls

This section, located on the right side of the main window, manages your personal name database (Known.txt), which the app uses to organize downloads into subfolders.

• Open Known.txt: Opens the Known.txt file in your system's default text editor for manual editing, such as bulk changes or cleanup.
• Search character input: A live search filter that hides any list items not matching your input text. Useful for quickly locating specific names in large lists.
• Known Series/Characters Area: Displays all names currently stored in your Known.txt. These names are used when "Separate folders by Known.txt" is enabled.
• Input at bottom & Add button: Type a new character or series name into the input field, then click "➕ Add". The app checks for duplicates, updates the list, and saves to Known.txt.
• Add to Filter: Opens a dialog showing all entries from Known.txt with checkboxes. You can select one or more to auto-fill the "Filter by Character(s)" field at the top of the app.
• Delete Selected: Select one or more entries from the list and click "🗑️ Delete Selected" to remove them from the app and update Known.txt accordingly.

Other Buttons

• (?_?) mark button (Help Guide): Opens a multi-page help dialog with step-by-step instructions and explanations for all app features. Useful for new users.
• History Button: Opens the Download History dialog (from DownloadHistoryDialog.py), showing:
  • Recently downloaded files
  • The first few posts processed in the last session
  This allows for a quick review of recent activity.
• Settings Button: Opens the Settings dialog (from FutureSettingsDialog.py), where you can change app-wide settings such as theme (light/dark) and language.
• Support Button: Opens the Support dialog (from SupportDialog.py), which includes developer info, source links, and donation platforms like Ko-fi or Patreon.

Log Area Controls

These controls are located around the main log panel and offer tools for managing downloads, configuring advanced options, and resetting the application.

• Multi-part: OFF
  This button acts as both a status indicator and a configuration panel for multi-part downloading (parallel downloading of large files).
  • Function: Opens the Multipart Download Options dialog (defined in MultipartScopeDialog.py).
  • Scope Options: Choose between "Videos Only", "Archives Only", or "Both".
  • Number of parts: Set how many simultaneous connections to use (2–16).
  • Minimum file size: Set a threshold (MB) below which files are downloaded normally.
  • Status: After applying settings, the button's text updates (e.g., Multi-part: Both); otherwise, it resets to Multi-part: OFF.
• 👁️ Eye Emoji Button (Log View Toggle)
  Switches between two views in the log panel:
  • 👁️ Progress Log View: Shows real-time download progress, status messages, and errors.
  • 🚫 Missed Character View: Displays names detected in posts that didn’t match the current filter — useful for updating Known.txt.
• Reset Button
  Performs a full "soft reset" of the UI when the application is idle.
  • Clears all inputs (except saved Download Location)
  • Resets checkboxes, buttons, and logs
  • Clears counters, queues, and restores the UI to its default state
  • Note: This is different from Cancel & Reset UI, which halts active downloads

The Progress Log and "Only Links" Mode Controls

• Standard Mode (Progress Log)
  This is the default behavior. The main_log_output field displays:
  • Post processing steps
  • Download/skipped file notifications
  • Error messages
  • Session summaries
• "Only Links" Mode
  When enabled, the log panel switches modes and reveals new controls.
  • 📜 Extracted Links Log: Replaces progress info with a list of found external links (e.g., Mega, Dropbox).
  • Export Links Button: Saves the extracted links to a .txt file.
  • Download Button: Opens the Download Selected External Links dialog (from DownloadExtractedLinksDialog.py), where you can:
    • View all supported external links
    • Select which ones to download
    • Begin download directly from cloud services
  • Links View Button: Toggles log display between:
    • 🔗 Links View: Shows all extracted links
    • ⬇️ Progress View: Shows download progress from external services (e.g., Mega)