User Manual & Help System

BTTB 4.4.0 Core Functionality Manual

Version 4.4.0 introduces incremental, non-blocking GUI tree rendering for large datasets, skipped files tracking saved to index.json, locale-independent parsing/formatting for fractional MB capacities, and complete modular localization parsing Gettext .po translation files in German, Dutch, French, and Spanish, alongside an automatic index.json creator, a native offline JSON TreeView tokenizer parser, and Cauchy Reed-Solomon PAR3 parity verification and copy-restoration, with native Theme Selection and modern Dark Theme options on Linux and Windows. This manual explains BTTB's advanced algorithms, folder constraints, rule structures, and user interface implementations in detail.

1. The Backtracking Subset-Sum Solver

BTTB fits files and folders onto storage media by solving a constrained knapsack / subset-sum mathematical model.

• •
  Entropy-Aware Semantic Packing (v4.0.0): Leverages deep sentence embeddings (Hugging Face's all-MiniLM-L6-v2 transformer model) to cluster files and folders by contextual relevance prior to solver backtracking. Enter a prompt like "keep similar content together", and BTTB will group similar files into virtual cohesive units. If Python/ML libraries are missing, BTTB gracefully falls back to char-level N-gram TF-IDF vectorizers or native C++ string similarity clustering, ensuring it is completely self-contained.
• MiniLM Neural Model Setup Tutorial (Preferred Approach):
  To achieve optimal contextual coherence, BTTB utilizes neural sentence embeddings. While a robust fallback is included, installing MiniLM is highly recommended. Follow these step-by-step instructions to set up the preferred deep learning extension:
  
  STEP 1: Install Python 3 & Pip
  - Linux (Ubuntu/Debian): Open a terminal and run: sudo apt install python3 python3-pip python3-venv
  - Windows: Download the official Python 3 installer from python.org. CRITICAL: Ensure you check the box that says "Add Python to PATH" during installation.
  
  STEP 2: Install sentence-transformers via pip
  Choose one of the following installation methods:
  - Option A: Global/User Installation (Simplest)
  Run in your terminal or Command Prompt:
  pip install sentence-transformers (or python3 -m pip install sentence-transformers)
  - Option B: Virtual Environment Isolation (Recommended for developers)
  python3 -m venv bttb_env
source bttb_env/bin/activate (Windows: bttb_env\Scripts\activate)
  pip install sentence-transformers
  
  STEP 3: Restart Burn to the Brim
  Relaunch the BTTB graphical or command-line app. It will automatically detect the Python environment and load the high-accuracy all-MiniLM-L6-v2 transformer model!
• •
  Interactive Test Simulation Mode (v4.0.0): Added a non-destructive simulation mode accessible via the graphical interfaces and command-line shell with --test. It runs the full clustering and backtracking logic, computes simulated volume slack, prints average pairwise cosine coherence metrics inside volumes, and lists optimal selections with absolutely zero disk write side-effects.
• •
  Unicode & Long-Path Handling (>256 chars): Standardizes full wide-character Unicode compatibility on both Windows and Linux, utilizing standard normalized absolute paths and Windows \\?\ prefixes to support paths up to 32,767 characters. Gracefully skips unreadable files or aborts scanning based on user choices.
• •
  Sector-Based Calculations: To match standard CD/DVD storage media behavior, BTTB converts file sizes from raw bytes into physical disk sectors (defaulting to 2048-byte sectors). The solver calculates the ceiling sector count of each item to ensure absolute sizing accuracy.
• •
  Pruning Search Tree: Utilizing the same optimized Delphi backtracking engine, the C++20 solver builds prefix sums of sizes and immediately prunes search branches when the remaining items combined with the current selection cannot possibly exceed the best result found so far, guaranteeing execution speeds of milliseconds even for thousands of files.
• •
  Slack Space & Early Pruning: Users can define an allowable slack threshold in bytes. The solver will successfully complete once the filled capacity falls within this tolerance. In version 3.3.0, a highly optimized slack early-termination algorithm terminates complex backtracking searches instantly in milliseconds under high-slack conditions.
• •
  Smart Adaptive Capacity Warnings: When a file size exceeds the target volume size, BTTB prompts the user (CLI prompt or graphical message dialog) to automatically increase the target capacity to fit the largest scanned file and retries packing recursively.
• •
  Multi-Volume Spanning Engine: When "Span across multiple volumes" is selected, the solver loops iteratively over the remaining files. The selected files for the first volume are stored, and then the backtracking engine runs recursively on the remaining files to pack successive volumes (Volume 1, Volume 2, etc.) until every single file has been perfectly fitted and organized into its respective target directory.
• •
  Multiple Source Folders Setup (+): Allows adding, editing, or removing multiple source directories recursively. BTTB acts as if they are in a single root folder and filters overlapping nested subdirectories to avoid double scanning.
• •
  Lightweight Symbolic Link Outputs: Instantly create symbolic links pointing back to original files in target folders instead of copy/move operations. Handles Windows native unprivileged symlinks, cmd shell mklink, and robust copy fallback on failure on modern Windows platforms.
• •
  Blu-ray and USB Sectors: Preset capacities for Blu-ray discs use standard 2048-byte sector dimensions. For USB presets (8 GB to 512 GB), BTTB automatically adopts 4096-byte clusters, aligning perfectly with modern exFAT, NTFS, or FAT32 flash drive architectures.
• •
  Analytical Tracing & Visual Progress: In version 3.3.0, users can enable a dedicated "Trace" checkbox in both the Linux GTK 4 and Windows Win32 native interfaces. When enabled, the real-time backtracking choice sequence, branch prunings, and explored state counts are printed directly into the GUI logging panel, letting you watch the solver's thinking progress as it runs.

2. Directory Split-Depth Constraints

Directory structures can be configured utilizing the new Split Depth parameter. This determines whether folders are scanned and moved atomically (as a single solid block) or split apart recursively into individual children.

• •
  Depth 0 (Root Boundary): Subfolders located directly inside the scanned directory are considered atomic units. They are kept solid; BTTB will never split files inside them across different disks.
• •
  Depth 1 or Higher: The splitting boundary is lowered. The solver will recurse down to that depth level, treating folders at that level as atomic, while splitting directories located higher up.

3. Regular Expression Rule Groupings

To keep specific files together (such as multi-part archives, or specific genres), users can define grouping rules using standard wildcards (e.g. `*.mp3`) or robust regular expressions (`std::regex`). Matching items are consolidated by the solver into unified virtual objects, preventing them from being separated across different media targets.

4. Asynchronous File Organization

When a perfect bin-packing configuration is solved, BTTB can automatically organize the files:

• •
  Copy vs Move Mode: If a target folder is specified and "Move fitted folders/files" is checked, BTTB launches a background file system stream that copies files and directories recursively to the destination while preserving the subfolder structure, and then safely removes them from the source folder.

5. Native ISO Image Generation

Both platforms feature an integrated **Create ISO Image** utility that automates CD/DVD backup image compilation:

• •
  Asynchronous C-Pipe Runs: When triggered, the application spawns a background command-line pipe calling `genisoimage` or `mkisofs` natively using standard C-pipes (`_popen`/`_pclose` on Windows, `popen`/`pclose` on Linux). This streams the process logs in real-time straight to the GUI log window while maintaining a completely responsive user interface.

Operating System Interfaces

To deliver premium, platform-native desktop experiences on both operating systems, we designed two dedicated front-end graphical interfaces.

Linux GTK 4 Desktop Application

The Linux client is written utilizing modern **GTK 4** and standard GNOME Adwaita layouts:

• •
  Responsive Thread Safe Marshaling: The solver runs in a standard background thread. To prevent interface freezing or access violations, all solver notifications and execution logs are marshaled back to the GTK main loop thread safe using `g_idle_add` callbacks.
• •
  Sidebar Result Trees: Displays a dynamic sidebar `GtkTreeView` that populates fitted and unfitted categories in visual nested node structures.
• •
  Universal Debian Installer (.deb) Compatibility: Packaged in a native `.deb` container supporting Ubuntu 22.04, 24.04, 25.04, and 26.04 out of the box. Low-level dynamic symbol wrapping (lowering glibc requirement from 2.38 down to 2.35) and static runtime linking eliminates all library and distribution conflicts.

Windows Native Win32 SDK GUI

The Windows client is written in pure **Win32 API (Windows Software Development Kit)**, compiling into a standalone statically-linked binary:

• •
  Zero DLL Footprint: By utilizing only core preinstalled system DLLs (`user32.dll`, `shell32.dll`, `comctl32.dll`, `comdlg32.dll`, `ole32.dll`), BTTB requires zero DLL packaging, solving all open-source licensing and redistribution issues.
• •
  Native Dialog Flow: Utilizes standard Windows Shell directories (`SHBrowseForFolder`) and native save file dialogs (`GetSaveFileName`) for standard system UI interactions.
• •
  Win32 Message Threading: Solver thread updates are posted to the main window procedure in a thread-safe manner using custom windows message identifiers (`PostMessage` and `WM_USER`).
• •
  ISO Dependency Fallbacks: If `genisoimage` is not recognized on Windows, BTTB falls back to `mkisofs`. If both are missing, BTTB prints easy-to-follow package installation steps (Scoop, Chocolatey, Cygwin, or MSYS2) directly into the execution log area.

Legacy Delphi (v2.9.0) Help Directory

If you are running the legacy Delphi-based version of Burn to the Brim, you can browse its dedicated help files using the links below: