readme.md

Known.txt

@@ -0,0 +1 @@
+([Yor], Yor Briar, Yor Forger)

multipart_downloader.py

@@ -13,61 +13,64 @@ DOWNLOAD_CHUNK_SIZE_ITER = 1024 * 256  # 256KB for iter_content within a chunk d
 
 
 def _download_individual_chunk(chunk_url, temp_file_path, start_byte, end_byte, headers,
-                               part_num, total_parts, progress_data, cancellation_event, skip_event, logger,
+                               part_num, total_parts, progress_data, cancellation_event, skip_event, pause_event, global_emit_time_ref, cookies_for_chunk, # Added cookies_for_chunk
-                               signals=None, api_original_filename=None): # Added signals and api_original_filename
+                               logger_func, emitter=None, api_original_filename=None): # Renamed logger, signals to emitter
     """Downloads a single chunk of a file and writes it to the temp file."""
     if cancellation_event and cancellation_event.is_set():
-        logger(f"   [Chunk {part_num + 1}/{total_parts}] Download cancelled before start.")
+        logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Download cancelled before start.")
         return 0, False  # bytes_downloaded, success
     if skip_event and skip_event.is_set():
-        logger(f"   [Chunk {part_num + 1}/{total_parts}] Skip event triggered before start.")
+        logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Skip event triggered before start.")
         return 0, False
 
+    if pause_event and pause_event.is_set():
+        logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Download paused before start...")
+        while pause_event.is_set():
+            if cancellation_event and cancellation_event.is_set():
+                logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Download cancelled while paused.")
+                return 0, False
+            time.sleep(0.2) # Shorter sleep for responsive resume
+        logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Download resumed.")
+
     chunk_headers = headers.copy()
-    # end_byte can be -1 for 0-byte files, meaning download from start_byte to end of file (which is start_byte itself)
     if end_byte != -1 : # For 0-byte files, end_byte might be -1, Range header should not be set or be 0-0
         chunk_headers['Range'] = f"bytes={start_byte}-{end_byte}"
     elif start_byte == 0 and end_byte == -1: # Specifically for 0-byte files
-        # Some servers might not like Range: bytes=0--1.
-        # For a 0-byte file, we might not even need a range header, or Range: bytes=0-0
-        # Let's try without for 0-byte, or rely on server to handle 0-0 if Content-Length was 0.
-        # If Content-Length was 0, the main function might handle it directly.
-        # This chunking logic is primarily for files > 0 bytes.
-        # For now, if end_byte is -1, it implies a 0-byte file, so we expect 0 bytes.
         pass
 
 
     bytes_this_chunk = 0
-    last_progress_emit_time_for_chunk = time.time()
     last_speed_calc_time = time.time()
     bytes_at_last_speed_calc = 0
 
     for attempt in range(MAX_CHUNK_DOWNLOAD_RETRIES + 1):
         if cancellation_event and cancellation_event.is_set():
-            logger(f"   [Chunk {part_num + 1}/{total_parts}] Cancelled during retry loop.")
+            logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Cancelled during retry loop.")
             return bytes_this_chunk, False
         if skip_event and skip_event.is_set():
-            logger(f"   [Chunk {part_num + 1}/{total_parts}] Skip event during retry loop.")
+            logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Skip event during retry loop.")
             return bytes_this_chunk, False
+        if pause_event and pause_event.is_set():
+            logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Paused during retry loop...")
+            while pause_event.is_set():
+                if cancellation_event and cancellation_event.is_set():
+                    logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Cancelled while paused in retry loop.")
+                    return bytes_this_chunk, False
+                time.sleep(0.2)
+            logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Resumed from retry loop pause.")
 
         try:
             if attempt > 0:
-                logger(f"   [Chunk {part_num + 1}/{total_parts}] Retrying download (Attempt {attempt}/{MAX_CHUNK_DOWNLOAD_RETRIES})...")
+                logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Retrying download (Attempt {attempt}/{MAX_CHUNK_DOWNLOAD_RETRIES})...")
                 time.sleep(CHUNK_DOWNLOAD_RETRY_DELAY * (2 ** (attempt - 1)))
-                # Reset speed calculation on retry
                 last_speed_calc_time = time.time()
                 bytes_at_last_speed_calc = bytes_this_chunk # Current progress of this chunk
-            
-            # Enhanced log message for chunk start
             log_msg = f"   🚀 [Chunk {part_num + 1}/{total_parts}] Starting download: bytes {start_byte}-{end_byte if end_byte != -1 else 'EOF'}"
-            logger(log_msg)
+            logger_func(log_msg)
-            print(f"DEBUG_MULTIPART: {log_msg}") # Direct console print for debugging
+            response = requests.get(chunk_url, headers=chunk_headers, timeout=(10, 120), stream=True, cookies=cookies_for_chunk)
-            response = requests.get(chunk_url, headers=chunk_headers, timeout=(10, 120), stream=True)
             response.raise_for_status()
-
-            # For 0-byte files, if end_byte was -1, we expect 0 content.
             if start_byte == 0 and end_byte == -1 and int(response.headers.get('Content-Length', 0)) == 0:
-                logger(f"   [Chunk {part_num + 1}/{total_parts}] Confirmed 0-byte file.")
+                logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Confirmed 0-byte file.")
                 with progress_data['lock']:
                     progress_data['chunks_status'][part_num]['active'] = False
                     progress_data['chunks_status'][part_num]['speed_bps'] = 0
@@ -77,17 +80,24 @@ def _download_individual_chunk(chunk_url, temp_file_path, start_byte, end_byte,
                 f.seek(start_byte)
                 for data_segment in response.iter_content(chunk_size=DOWNLOAD_CHUNK_SIZE_ITER):
                     if cancellation_event and cancellation_event.is_set():
-                        logger(f"   [Chunk {part_num + 1}/{total_parts}] Cancelled during data iteration.")
+                        logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Cancelled during data iteration.")
                         return bytes_this_chunk, False
                     if skip_event and skip_event.is_set():
-                        logger(f"   [Chunk {part_num + 1}/{total_parts}] Skip event during data iteration.")
+                        logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Skip event during data iteration.")
                         return bytes_this_chunk, False
+                    if pause_event and pause_event.is_set():
+                        logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Paused during data iteration...")
+                        while pause_event.is_set():
+                            if cancellation_event and cancellation_event.is_set():
+                                logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Cancelled while paused in data iteration.")
+                                return bytes_this_chunk, False
+                            time.sleep(0.2)
+                        logger_func(f"   [Chunk {part_num + 1}/{total_parts}] Resumed from data iteration pause.")
                     if data_segment:
                         f.write(data_segment)
                         bytes_this_chunk += len(data_segment)
                         
                         with progress_data['lock']:
-                            # Increment both the chunk's downloaded and the overall downloaded
                             progress_data['total_downloaded_so_far'] += len(data_segment)
                             progress_data['chunks_status'][part_num]['downloaded'] = bytes_this_chunk
                             progress_data['chunks_status'][part_num]['active'] = True
@@ -100,45 +110,42 @@ def _download_individual_chunk(chunk_url, temp_file_path, start_byte, end_byte,
                                 progress_data['chunks_status'][part_num]['speed_bps'] = current_speed_bps
                                 last_speed_calc_time = current_time
                                 bytes_at_last_speed_calc = bytes_this_chunk                            
-
+                            if emitter and (current_time - global_emit_time_ref[0] > 0.25): # Max ~4Hz for the whole file
-                            # Emit progress more frequently from within the chunk download
+                                global_emit_time_ref[0] = current_time # Update shared last emit time
-                            if current_time - last_progress_emit_time_for_chunk > 0.1: # Emit up to 10 times/sec per chunk
+                                status_list_copy = [dict(s) for s in progress_data['chunks_status']] # Make a deep enough copy
-                                if signals and hasattr(signals, 'file_progress_signal'):
+                                if isinstance(emitter, queue.Queue):
-                                    # Ensure we read the latest total downloaded from progress_data
+                                    emitter.put({'type': 'file_progress', 'payload': (api_original_filename, status_list_copy)})
-                                    # Send a copy of the chunks_status list
+                                elif hasattr(emitter, 'file_progress_signal'): # PostProcessorSignals-like
-                                    status_list_copy = [dict(s) for s in progress_data['chunks_status']] # Make a deep enough copy
+                                    emitter.file_progress_signal.emit(api_original_filename, status_list_copy)
-                                    signals.file_progress_signal.emit(api_original_filename, status_list_copy)
-                                last_progress_emit_time_for_chunk = current_time
             return bytes_this_chunk, True
 
         except (requests.exceptions.ConnectionError, requests.exceptions.Timeout, http.client.IncompleteRead) as e:
-            logger(f"   ❌ [Chunk {part_num + 1}/{total_parts}] Retryable error: {e}")
+            logger_func(f"   ❌ [Chunk {part_num + 1}/{total_parts}] Retryable error: {e}")
             if attempt == MAX_CHUNK_DOWNLOAD_RETRIES:
-                logger(f"   ❌ [Chunk {part_num + 1}/{total_parts}] Failed after {MAX_CHUNK_DOWNLOAD_RETRIES} retries.")
+                logger_func(f"   ❌ [Chunk {part_num + 1}/{total_parts}] Failed after {MAX_CHUNK_DOWNLOAD_RETRIES} retries.")
                 return bytes_this_chunk, False
         except requests.exceptions.RequestException as e: # Includes 4xx/5xx errors after raise_for_status
-            logger(f"   ❌ [Chunk {part_num + 1}/{total_parts}] Non-retryable error: {e}")
+            logger_func(f"   ❌ [Chunk {part_num + 1}/{total_parts}] Non-retryable error: {e}")
             return bytes_this_chunk, False
         except Exception as e:
-            logger(f"   ❌ [Chunk {part_num + 1}/{total_parts}] Unexpected error: {e}\n{traceback.format_exc(limit=1)}")
+            logger_func(f"   ❌ [Chunk {part_num + 1}/{total_parts}] Unexpected error: {e}\n{traceback.format_exc(limit=1)}")
             return bytes_this_chunk, False
-    
-    # Ensure final status is marked as inactive if loop finishes due to retries
     with progress_data['lock']:
         progress_data['chunks_status'][part_num]['active'] = False
         progress_data['chunks_status'][part_num]['speed_bps'] = 0
     return bytes_this_chunk, False # Should be unreachable
 
 
-def download_file_in_parts(file_url, save_path, total_size, num_parts, headers,
+def download_file_in_parts(file_url, save_path, total_size, num_parts, headers, api_original_filename,
-                           api_original_filename, signals, cancellation_event, skip_event, logger):
+                           emitter_for_multipart, cookies_for_chunk_session, # Added cookies_for_chunk_session
+                           cancellation_event, skip_event, logger_func, pause_event):
     """
     Downloads a file in multiple parts concurrently.
     Returns: (download_successful_flag, downloaded_bytes, calculated_file_hash, temp_file_handle_or_None)
     The temp_file_handle will be an open read-binary file handle to the .part file if successful, otherwise None.
     It is the responsibility of the caller to close this handle and rename/delete the .part file.
     """
-    logger(f"⬇️ Initializing Multi-part Download ({num_parts} parts) for: '{api_original_filename}' (Size: {total_size / (1024*1024):.2f} MB)")
+    logger_func(f"⬇️ Initializing Multi-part Download ({num_parts} parts) for: '{api_original_filename}' (Size: {total_size / (1024*1024):.2f} MB)")
     temp_file_path = save_path + ".part"
 
     try:
@@ -146,7 +153,7 @@ def download_file_in_parts(file_url, save_path, total_size, num_parts, headers,
             if total_size > 0:
                 f_temp.truncate(total_size) # Pre-allocate space
     except IOError as e:
-        logger(f"   ❌ Error creating/truncating temp file '{temp_file_path}': {e}")
+        logger_func(f"   ❌ Error creating/truncating temp file '{temp_file_path}': {e}")
         return False, 0, None, None
 
     chunk_size_calc = total_size // num_parts
@@ -167,7 +174,7 @@ def download_file_in_parts(file_url, save_path, total_size, num_parts, headers,
             chunk_actual_sizes.append(end - start + 1)
 
     if not chunks_ranges and total_size > 0:
-        logger(f"   ⚠️ No valid chunk ranges for multipart download of '{api_original_filename}'. Aborting multipart.")
+        logger_func(f"   ⚠️ No valid chunk ranges for multipart download of '{api_original_filename}'. Aborting multipart.")
         if os.path.exists(temp_file_path): os.remove(temp_file_path)
         return False, 0, None, None
 
@@ -178,7 +185,8 @@ def download_file_in_parts(file_url, save_path, total_size, num_parts, headers,
             {'id': i, 'downloaded': 0, 'total': chunk_actual_sizes[i] if i < len(chunk_actual_sizes) else 0, 'active': False, 'speed_bps': 0.0}
             for i in range(num_parts)
         ],
-        'lock': threading.Lock()
+        'lock': threading.Lock(),
+        'last_global_emit_time': [time.time()] # Shared mutable for global throttling timestamp
     }
 
     chunk_futures = []
@@ -191,8 +199,9 @@ def download_file_in_parts(file_url, save_path, total_size, num_parts, headers,
             chunk_futures.append(chunk_pool.submit(
                 _download_individual_chunk, chunk_url=file_url, temp_file_path=temp_file_path,
                 start_byte=start, end_byte=end, headers=headers, part_num=i, total_parts=num_parts,
-                progress_data=progress_data, cancellation_event=cancellation_event, skip_event=skip_event, logger=logger,
+                progress_data=progress_data, cancellation_event=cancellation_event, skip_event=skip_event, global_emit_time_ref=progress_data['last_global_emit_time'],
-                signals=signals, api_original_filename=api_original_filename # Pass them here
+                pause_event=pause_event, cookies_for_chunk=cookies_for_chunk_session, logger_func=logger_func, emitter=emitter_for_multipart,
+                api_original_filename=api_original_filename
             ))
 
         for future in as_completed(chunk_futures):
@@ -201,32 +210,29 @@ def download_file_in_parts(file_url, save_path, total_size, num_parts, headers,
             total_bytes_from_chunks += bytes_downloaded_this_chunk
             if not success_this_chunk:
                 all_chunks_successful = False
-            # Progress is emitted from within _download_individual_chunk
 
     if cancellation_event and cancellation_event.is_set():
-        logger(f"   Multi-part download for '{api_original_filename}' cancelled by main event.")
+        logger_func(f"   Multi-part download for '{api_original_filename}' cancelled by main event.")
         all_chunks_successful = False
-    
+    if emitter_for_multipart:
-    # Ensure a final progress update is sent with all chunks marked inactive (unless still active due to error)
-    if signals and hasattr(signals, 'file_progress_signal'):
         with progress_data['lock']:
-            # Ensure all chunks are marked inactive for the final signal if download didn't fully succeed or was cancelled
             status_list_copy = [dict(s) for s in progress_data['chunks_status']]
-            signals.file_progress_signal.emit(api_original_filename, status_list_copy)
+            if isinstance(emitter_for_multipart, queue.Queue):
+                emitter_for_multipart.put({'type': 'file_progress', 'payload': (api_original_filename, status_list_copy)})
+            elif hasattr(emitter_for_multipart, 'file_progress_signal'): # PostProcessorSignals-like
+                emitter_for_multipart.file_progress_signal.emit(api_original_filename, status_list_copy)
 
     if all_chunks_successful and (total_bytes_from_chunks == total_size or total_size == 0):
-        logger(f"   ✅ Multi-part download successful for '{api_original_filename}'. Total bytes: {total_bytes_from_chunks}")
+        logger_func(f"   ✅ Multi-part download successful for '{api_original_filename}'. Total bytes: {total_bytes_from_chunks}")
         md5_hasher = hashlib.md5()
         with open(temp_file_path, 'rb') as f_hash:
             for buf in iter(lambda: f_hash.read(4096*10), b''): # Read in larger buffers for hashing
                 md5_hasher.update(buf)
         calculated_hash = md5_hasher.hexdigest()
-        # Return an open file handle for the caller to manage (e.g., for compression)
-        # The caller is responsible for closing this handle and renaming/deleting the .part file.
         return True, total_bytes_from_chunks, calculated_hash, open(temp_file_path, 'rb')
     else:
-        logger(f"   ❌ Multi-part download failed for '{api_original_filename}'. Success: {all_chunks_successful}, Bytes: {total_bytes_from_chunks}/{total_size}. Cleaning up.")
+        logger_func(f"   ❌ Multi-part download failed for '{api_original_filename}'. Success: {all_chunks_successful}, Bytes: {total_bytes_from_chunks}/{total_size}. Cleaning up.")
         if os.path.exists(temp_file_path):
             try: os.remove(temp_file_path)
-            except OSError as e: logger(f"    Failed to remove temp part file '{temp_file_path}': {e}")
+            except OSError as e: logger_func(f"    Failed to remove temp part file '{temp_file_path}': {e}")
         return False, total_bytes_from_chunks, None, None

readme.md

@@ -1,204 +1,313 @@
-# Kemono Downloader v3.2.0
+<h1 align="center">Kemono Downloader v4.0.0</h1>
 
-A feature-rich GUI application built with PyQt5 to download content from **Kemono.su** or **Coomer.party**.  
+<div align="center">
-Offers robust filtering, smart organization, manga-specific handling, and performance tuning.  
+  <img src="https://github.com/Yuvi9587/Kemono-Downloader/blob/main/Read.png" alt="Kemono Downloader"/>
-
+</div>
-This version introduces:
-- Multi-part downloads  
-- Character filtering by comments  
-- Filename word removal  
-- Various UI/workflow enhancements
 
 ---
 
-## 🚀 What's New in v3.2.0
+A powerful, feature-rich GUI application for downloading content from **[Kemono.su](https://kemono.su)** and **[Coomer.party](https://coomer.party)**.  
-
+Built with **PyQt5**, this tool is ideal for users who want deep filtering, customizable folder structures, efficient downloads, and intelligent automation — all within a modern, user-friendly graphical interface.
-### 🔹 Character Filter by Post Comments (Beta)
-
-- New "Comments" scope for the 'Filter by Character(s)' feature.
-
-**How it works:**
-1. Checks if any **filenames** match your character filter. If yes → downloads the post (skips comment check).
-2. If no filename matches → scans the **post's comments**. If matched → downloads the post.
-
-- Prioritizes filename-matched character name for folder naming, otherwise uses comment match.
-- Cycle through filter scopes with the `Filter: [Scope]` button next to the character input.
 
 ---
 
-### ✂️ Remove Specific Words from Filenames
+##  What's New in v4.0.0?
 
-- Input field: `"✂️ Remove Words from name"`
+Version 3.5.0 focuses on enhancing access to content and providing even smarter organization:
-- Enter comma-separated words (e.g., `patreon, kemono, [HD], _final`)
+
-- These are removed from filenames (case-insensitive) to improve organization.
+###  Cookie Management
+
+- **Access Content:** Seamlessly download from Kemono/Coomer as if you were logged in by using your browser's cookies.
+- **Flexible Input:**
+  - Directly paste your cookie string (e.g., `name1=value1; name2=value2`).
+  - Browse and load cookies from a `cookies.txt` file (Netscape format).
+  - Automatic fallback to a `cookies.txt` file in the application directory if "Use Cookie" is enabled and no other source is specified.
+- **Easy Activation:** A simple "Use Cookie" checkbox in the UI controls this feature.
+- *Important Note: Cookie settings (text, file path, and enabled state) are configured per session and are not saved when the application is closed. You will need to re-apply them on each launch if needed.*
 
 ---
 
-### 🧩 Multi-part Downloads for Large Files
+###  Advanced `Known.txt` and Character Filtering
 
-- Toggle multi-part downloads (OFF by default).
+The `Known.txt` system has been revamped for improved performance and stability. The previous method of handling known names could become resource-intensive with large lists, potentially leading to application slowdowns or crashes. This new, streamlined system offers more direct control and robust organization.
-- Improves speed on large files (e.g., >10MB videos, zips).
+The `Known.txt` file and the "Filter by Character(s)" input field work together to provide powerful and flexible content organization. The `Known.txt` file itself has a straightforward syntax, while the UI input allows for more complex session-specific grouping and alias definitions that can then be added to `Known.txt`.
-- Falls back to single-stream on failure.
+
-- Toggle via `Multi-part: ON/OFF` in the log header.
+**1. `Known.txt` File Syntax (Located in App Directory):**
+
+`Known.txt` stores your persistent list of characters, series, or keywords for folder organization. Each line is an entry:
+
+- **Simple Entries:**
+  - A line like `My Awesome Series` or `Nami`.
+  - **Behavior:** Content matching this term will be saved into a folder named "My Awesome Series" or "Nami" respectively (if "Separate Folders" is enabled).
+
+**2. "Filter by Character(s)" UI Input Field:**
+
+This field allows for dynamic filtering for the current download session and provides options for how new entries are added to `Known.txt`.
+
+- **Standard Names:**
+  - Input: `Nami, Robin`
+  - Session Behavior: Filters for "Nami" OR "Robin". If "Separate Folders" is on, creates folders "Nami" and "Robin".
+  - `Known.txt` Addition: If "Nami" is new and selected for addition in the confirmation dialog, it's added as `Nami` on a new line in `Known.txt`.
+
+- **Grouped Aliases for a Single Character (using `(...)~` syntax):**
+  - Input: `(Boa, Hancock)~`
+  - Meaning: "Boa" and "Hancock" are different names/aliases for the *same character*. The names are listed within parentheses separated by commas (e.g., `name1, alias1, alias2`), and the entire group is followed by a `~` symbol. This is useful when a creator uses different names for the same character.
+  - Session Behavior: Filters for "Boa" OR "Hancock". If "Separate Folders" is on, creates a single folder named "Boa Hancock".
+  - `Known.txt` Addition: If this group is new and selected for addition, it's added to `Known.txt` as a grouped alias entry, typically `(Boa Hancock)`. The first name in the `Known.txt` entry (e.g., "Boa Hancock") becomes the primary folder name.
+
+- **Combined Folder for Distinct Characters (using `(...)` syntax):**
+  - Input: `(Vivi, Uta)`
+  - Meaning: "Vivi" and "Uta" are *distinct characters*, but for this download session, their content should be grouped into a single folder. The names are listed within parentheses separated by commas. This is useful for grouping art of less frequent characters without creating many small individual folders.
+  - Session Behavior: Filters for "Vivi" OR "Uta". If "Separate Folders" is on, creates a single folder named "Vivi Uta".
+  - `Known.txt` Addition: If this "combined group" is new and selected for addition, "Vivi" and "Uta" are added to `Known.txt` as *separate, individual simple entries* on new lines:
+    ```
+    Vivi
+    Uta
+    ```
+    The combined folder "Vivi Uta" is a session-only convenience; `Known.txt` stores them as distinct entities for future individual use.
+
+**3. Interaction with `Known.txt`:**
+
+- **Adding New Names from Filters:** When you use the "Filter by Character(s)" input, if any names or groups are new (not already in `Known.txt`), a dialog will appear after you start the download. This dialog allows you to select which of these new names/groups should be added to `Known.txt`, formatted according to the rules described above.
+- **Intelligent Fallback:** If "Separate Folders by Name/Title" is active, and content doesn't match the "Filter by Character(s)" UI input, the downloader consults your `Known.txt` file for folder naming.
+- **Direct Management:** You can add simple entries directly to `Known.txt` using the list and "Add" button in the UI's `Known.txt` management section. For creating or modifying complex grouped alias entries directly in the file, or for bulk edits, click the "Open Known.txt" button. The application reloads `Known.txt` on startup or before a download process begins.
+
+---
+##  What's in v3.5.0? (Previous Update)
+This version brings significant enhancements to manga/comic downloading, filtering capabilities, and user experience:
+
+###  Enhanced Manga/Comic Mode
+
+- **New "Date Based" Filename Style:**
+
+  - Perfect for truly sequential content! Files are named numerically (e.g., `001.jpg`, `002.jpg`, `003.ext`...) across an *entire creator's feed*, strictly following post publication order.
+
+  - **Smart Numbering:** Automatically resumes from the highest existing number found in the series folder (and subfolders, if "Subfolder per Post" is enabled).
+
+  - **Guaranteed Order:** Disables multi-threading for post processing to ensure sequential accuracy.
+
+  - Works alongside the existing "Post Title" and "Original File Name" styles.
 
 ---
 
-### 🧠 UI and Workflow Enhancements
+###  "Remove Words from Filename" Feature
 
-- **Updated Welcome Tour**  
+- Specify comma-separated words or phrases (case-insensitive) that will be automatically removed from filenames.
-  Shows on first launch, covers all new and core features.
 
-- **Smarter Cancel/Reset**  
+- Example: `patreon, [HD], _final` transforms `AwesomeArt_patreon` `Hinata_Hd` into `AwesomeArt.jpg` `Hinata.jpg`.
-  Cancels active tasks and resets UI — but retains URL and Download Directory fields.
-
-- **Simplified Interface**  
-  - Removed "Skip Current File" and local API server for a cleaner experience.
 
 ---
 
-### 📁 Refined File & Duplicate Handling
+###  New "Only Archives" File Filter Mode
 
-- **Duplicate Filenames**  
+- Exclusively downloads `.zip` and `.rar` files.
-  Adds numeric suffix (`file.jpg`, `file_1.jpg`, etc.).  
-  Removed the "Duplicate" subfolder system.
 
-- **Efficient Hash Check**  
+- Automatically disables conflicting options like "Skip .zip/.rar" and external link logging.
-  Detects and skips duplicate files within the same session (before writing to disk).
-
-- **Better Temp File Cleanup**  
-  Cleans up `.part` files — especially if duplicate or compressed post-download.
 
 ---
 
-## 🧩 Core Features
+###  Improved Character Filter Scope - "Comments (Beta)"
 
-### 🎛 Simple GUI
+- **File-First Check:** Prioritizes matching filenames before checking post comments for character names.
-- Built with **PyQt5**  
-- Dark theme, responsive layout
 
-### 📥 Supports Post and Creator URLs
+- **Comment Fallback:** Only checks comments if no filename match is found, reducing unnecessary API calls.
-- Download a single post or an entire creator’s feed.
-
-### 🔢 Page Range Support
-- Choose page range when downloading creator feeds (except in Manga Mode).
 
 ---
 
-### 🗂 Smart Folder System
+###  Refined "Missed Character Log"
 
-- Organize by character names, post titles, or custom labels.
+- Displays a capitalized, alphabetized list of key terms from skipped post titles.
-- Option to create a separate folder for each post.
+
-- Uses `Known.txt` for fallback names.
+- Makes it easier to spot patterns or characters that might be unintentionally excluded.
 
 ---
 
-### 📚 Known Names Manager
+###  Enhanced Multi-part Download Progress
 
-- Add/edit/delete known characters/shows
+- Granular visibility into active chunk downloads and combined speed for large files.
-- Saves entries in `Known.txt` for automatic folder naming.
 
 ---
 
-### 🔍 Advanced Filtering
+###  Updated Onboarding Tour
 
-- **Filter by Character(s)**  
+- Improved guide for new users, covering v4.0.0 features and existing core functions.
-  Scope: `Files`, `Post Titles`, `Both`, or `Post Comments (Beta)`
-
-- **Skip with Words**  
-  Skip posts or files based on keywords. Toggle scope.
-
-- **Media Type Filters**  
-  Choose: `All`, `Images/GIFs`, `Videos`, `📦 Only Archives (.zip/.rar)`
-
-- **🔗 Only Links Mode**  
-  Extracts links from post descriptions.
-
-- **Skip Archives**  
-  Ignore `.zip`/`.rar` unless in "Only Archives" mode.
 
 ---
 
-### 📖 Manga/Comic Mode (Creator URLs Only)
+###  Robust Configuration Path
 
-- Downloads posts oldest-to-newest.
+- Settings and `Known.txt` are now stored in the same folder as app.
-
-**Filename Style Toggle:**
-- `Post Title` (default): Names first file in post after title.
-- `Original File`: Uses original file names.
-
-- Uses manga/series title for filtering and folder naming.
 
 ---
 
-### 🖼️ Image Compression
+##  Core Features
-
-- Converts large images to **WebP** if it significantly reduces size.
-- Requires `Pillow` library.
 
 ---
 
-### 🖼 Download Thumbnails Only
+### User Interface & Workflow
 
-- Option to fetch only small preview images.
+- **Clean PyQt5 GUI** — Simple, modern, and dark-themed.
+
+- **Persistent Settings** — Saves preferences between sessions.
+
+- **Download Modes:**
+  - Single Post URL
+  - Entire Creator Feed
+
+- **Flexible Options:**
+  - Specify Page Range (disabled in Manga Mode)
+  - Custom Folder Name for single posts
 
 ---
 
-### ⚙️ Multithreaded Downloads
+###  Smart Filtering
 
-- Adjustable threads for:
+- **Character Name Filtering:**
-  - Multiple post processing (creator feeds)
+  - Use `Tifa, Aerith` or group `(Boa, Hancock)` → folder `Boa Hancock`
-  - File-level concurrency (within a post)
+  - Flexible input for current session and for adding to `Known.txt`.
+  - Examples:
+    - `Nami` (simple character)
+    - `(Boa Hancock)~` (aliases for one character, session folder "Boa Hancock", adds `(Boa Hancock)` to `Known.txt`)
+    - `(Vivi, Uta)` (distinct characters, session folder "Vivi Uta", adds `Vivi` and `Uta` separately to `Known.txt`)
+  - See "Advanced `Known.txt` and Character Filtering" for full details.
+  - **Filter Scopes:**
+    - `Files`
+    - `Title`
+    - `Both (Title then Files)`
+    - `Comments (Beta - Files first)`
+
+- **Skip with Words:**
+  - Exclude with `WIP, sketch, preview`
+
+  - **Skip Scopes:**
+    - `Files`
+    - `Posts`
+    - `Both (Posts then Files)`
+
+- **File Type Filters:**
+  - `All`, `Images/GIFs`, `Videos`, `📦 Only Archives`, `🔗 Only Links`
+
+- **Filename Cleanup:**
+  - Remove illegal and unwanted characters or phrases
 
 ---
 
-### ⏯ Download Controls
+### Manga/Comic Mode (Creator Feeds Only)
 
-- Start and cancel active operations.
+- **Chronological Processing** — Oldest posts first
+
+- **Filename Style Options:**
+  - `Name: Post Title (Default)`
+  - `Name: Original File`
+  - `Name: Date Based (New)`
+
+- **Best With:** Character filters set to manga/series title
 
 ---
 
-### 🌙 Dark Mode Interface
+### Folder Structure & Naming
 
-- Modern, dark-themed GUI for comfort and clarity.
+- **Subfolders:**
+  - Auto-created based on character name, post title, or `Known.txt`
+
+  - "Subfolder per Post" option for further nesting
+
+- **Smart Naming:** Cleans invalid characters and structures logically
 
 ---
 
-## 🔧 Backend Enhancements
+### Thumbnail & Compression Tools
 
-### ♻️ Retry Logic
+- **Download Thumbnails Only**
 
-- Retries failed file and chunk downloads before skipping.
+- **Compress to WebP** (via Pillow)
+  - Converts large images to smaller WebP versions
 
 ---
 
-### 🧬 Session-wide Deduplication
+###  Performance Features
 
-- Uses **MD5 hashes** to avoid saving identical files during a session.
+- **Multithreading:**
+  - For both post processing and file downloading
+
+- **Multi-part Downloads:**
+  - Toggleable in GUI
+  - Splits large files into chunks
+  - Granular chunk-level progress display
 
 ---
 
-### 🧹 Smart Naming & Cleanup
+### Logging & Progress
 
-- Cleans special characters in names.
+- **Real-time Logs:** Activity, errors, skipped posts
-- Applies numeric suffixes on collision.
+
-- Removes specified unwanted words.
+- **Missed Character Log:** Shows skipped keywords in easy-to-read list
+
+- **External Links Log:** Shows links (unless disabled in some modes)
+
+- **Export Links:** Save `.txt` of links (Only Links mode)
 
 ---
 
-### 📋 Efficient Logging
+###  Config System
 
-- Toggle verbosity: `Basic` (important) or `Full` (everything).
+- **`Known.txt` for Smart Folder Naming (Located in App Directory):**
-- Separate panel for extracted external links.
+  - A user-editable file that stores a list of preferred names, series titles, or keywords.
-- Real-time feedback with clear statuses.
+  - It's primarily used as an intelligent fallback for folder creation when "Separate Folders by Name/Title" is enabled.
+  - **Syntax:**
+    - Simple entries: `My Favorite Series` (creates folder "My Favorite Series", matches "My Favorite Series").
+    - Grouped entries: `(Desired Folder Name, alias1, alias2)` (creates folder "Desired Folder Name"; matches "Desired Folder Name", "alias1", or "alias2").
+
+- **Settings Stored in App Directory**
+
+- **Editable Within GUI**
 
 ---
 
-## 📦 Installation
+## Installation
+
+---
 
 ### Requirements
-- Python 3.6+
-- Pip (Python package manager)
 
-### Install Libraries
+- Python 3.6 or higher  
+- pip
+
+---
+
+### Install Dependencies
+
 ```bash
 pip install PyQt5 requests Pillow
+
+```
+
+***
+
+## ** Build a Standalone Executable (Optional)**
+
+1. Install PyInstaller:
+```bash
+pip install pyinstaller
+```
+
+2. Run:
+```bash
+pyinstaller --name "Kemono Downloader" --onefile --windowed --icon="Kemono.ico" main.py
+```
+
+3. Output will be in the `dist/` folder.
+
+***
+
+## ** Config Files**
+- `settings.json` — Stores your UI preferences and settings.
+- `Known.txt` — Stores character names, series titles, or keywords for organizing downloaded content into specific folders.
+  - Supports simple entries (e.g., `My Series`) and grouped entries for aliases (e.g., `(Folder Name, alias1, alias2)` where "Folder Name" is the name of the created folder, and all terms are used for matching).
+
+***
+
+## ** Feedback & Support**
+
+Issues? Suggestions?  
+Open an issue on the [GitHub repository](https://github.com/Yuvi9587/kemono-downloader) or join our community.