Skip to content

Archive Management Guide

Quick Reference

Feature: Extract archives and create ZIPs for external apps Supported Formats: ZIP, RAR, 7Z, TAR, TAR.GZ, TAR.BZ2 Compression: STORE (fastest) | DEFLATE | BZIP2 | LZMA (maximum) Use Case: Handle compressed galleries and multi-host uploads

What is Archive Support?

Archive support in BBDrop provides two key features:

  1. Archive Extraction - Extract compressed gallery folders and select which ones to upload
  2. ZIP Creation - Automatically create compressed archives for external applications and multi-host uploads

This guide covers how to use both features effectively.

Supported Archive Formats

Extraction Formats

BBDrop can extract and process the following compressed archive formats:

Format Extension Best For Notes
ZIP .zip Universal Most common, wide compatibility
RAR .rar Large files Excellent compression, requires WinRAR
7-Zip .7z High compression Best compression ratio, slower
TAR .tar Unix/Linux Uncompressed archive
TAR.GZ .tar.gz Unix/Linux Compressed with gzip
TAR.BZ2 .tar.bz2 Unix/Linux Compressed with bzip2

Compression Formats (ZIP Creation)

When BBDrop creates archives automatically, it supports these compression modes:

Mode Type Speed Size Recommended Use
STORE No compression 0.5-2x faster Original size + 1-2% Images (already compressed)
DEFLATE Standard Normal 5-15% smaller Mixed content
BZIP2 High compression Slower 10-20% smaller Archive storage
LZMA Maximum compression Slowest 15-25% smaller Final archival

Recommendation: Use STORE mode for image galleries since images (JPG, PNG) are already compressed and ZIP compression provides minimal benefit while wasting CPU time.

How Archive Extraction Works

Step 1: Adding an Archive to the Queue

You can add an archive file to BBDrop in three ways:

Drag & Drop

  1. Locate your archive file in File Explorer
  2. Drag it directly into the BBDrop window
  3. BBDrop will auto-detect the archive type

Using the GUI

  1. In BBDrop, click File -> Add Archive
  2. Select your archive file
  3. Click Open

Command Line

python bbdrop.py vacation.zip --gui

Step 2: Archive Detection & Extraction

When you add an archive, BBDrop will:

  1. Validate the archive integrity and format
  2. Extract to a temporary system directory (/tmp on Linux, %TEMP% on Windows)
  3. Scan for image-containing folders
  4. Display a folder selection dialog

Step 3: Folder Selection Dialog

The Archive Folder Selector appears after extraction:

+--- Select Folders to Upload ---+
| Archive: vacation_photos.zip    |
| Extracted to: /tmp/bbdrop_xyz   |
|                                 |
| Found 3 image folders:          |
| [x] Day1_Beach (127 images)    |
| [x] Day2_City (84 images)      |
| [ ] Day3_Mountain (95 images)  |
|                                 |
| [Select All] [Upload] [Cancel] |
+---------------------------------+

Actions: - Check/uncheck folders to include/exclude them - Select All - Include all detected folders - Upload - Add selected folders to the queue as separate galleries - Cancel - Discard extraction and close dialog

Step 4: Automatic Cleanup

After selection: - Unchecked folders are permanently deleted - Checked folders are converted to temporary galleries - Temporary extraction directory is cleaned up after upload completes - All temporary files are removed (success or failure)

Archive Extraction Example

Scenario: Multi-Day Event Photos

You have a single ZIP file containing photos from a 3-day event, organized by day:

vacation_photos.zip
+-- Day1_Beach/
|   +-- IMG_0001.jpg
|   +-- IMG_0002.jpg
|   +-- ... (127 total)
+-- Day2_City/
|   +-- IMG_0128.jpg
|   +-- IMG_0129.jpg
|   +-- ... (84 total)
+-- Day3_Mountain/
    +-- IMG_0212.jpg
    +-- IMG_0213.jpg
    +-- ... (95 total)

Steps: 1. Drag vacation_photos.zip into BBDrop 2. BBDrop extracts and detects 3 folders 3. Folder selector appears with all 3 checked by default 4. Click Upload to add all three as separate galleries 5. Each folder becomes a separate queue entry: - Gallery 1: "Day1_Beach" (127 images, 245 MB) - Gallery 2: "Day2_City" (84 images, 156 MB) - Gallery 3: "Day3_Mountain" (95 images, 189 MB)

Archive Creation for External Hooks

What is ZIP Creation for Hooks?

When you use external apps (hooks) to upload to additional hosts, BBDrop can automatically create temporary ZIP archives. This is useful for:

  • Multi-host uploaders (like muh.py for Gofile)
  • Custom scripts that process entire galleries
  • Cloud sync to Dropbox, Google Drive, etc.
  • Backup services that want compressed archives

How It Works

1. Configure External App

In Settings -> External Apps, set up an app with the %z parameter:

{
  "name": "Upload to Gofile",
  "command": "python",
  "arguments": ["hooks/muh.py", "gofile", "%z"],
  "execute_on": "completed",
  "capture_output": true
}

The %z parameter tells BBDrop to create a ZIP file.

After your gallery finishes uploading to the image host:

  1. BBDrop creates a temporary ZIP file:
  2. Location: System temp directory
  3. Name: bbdrop_<gallery_id>_<gallery_name>.zip
  4. Contents: All images from the gallery

  5. Compression: STORE mode (fastest)

  6. Example: bbdrop_abc123_Summer_Vacation.zip (245 MB)

3. External App Executes

BBDrop runs the external app and passes the ZIP path:

python hooks/muh.py gofile /tmp/bbdrop_abc123_Summer_Vacation.zip

4. Automatic Cleanup

After the external app completes (success or failure): - Temporary ZIP file is automatically deleted - No manual cleanup needed - Disk space is immediately freed

ZIP Creation Example

Scenario: Upload to both your image host and Gofile

  1. Drag 250 MB gallery into BBDrop
  2. Start upload
  3. Gallery uploads to the image host (takes 2 minutes at 2 MB/s)
  4. Gallery completes and gallery_id is obtained
  5. External app configured: 
    Name: Upload to Gofile
Command: python
Arguments: hooks/muh.py gofile %z
Execute on: completed
  6. BBDrop automatically:
  7. Creates 250 MB ZIP in temp directory (0.5 seconds)
  8. Runs: python hooks/muh.py gofile /tmp/bbdrop_abc123_Summer_Vacation.zip
  9. Waits for Gofile upload to complete
  10. Deletes temporary ZIP file
  11. External app output (like Gofile URL) is captured and stored in ext1 field

Archive Performance & Storage

Extraction Performance

Archive Type Size Extraction Time Notes
ZIP (STORE) 250 MB 1-2 sec Fastest, no decompression
ZIP (DEFLATE) 200 MB 3-5 sec Standard compression
7Z 150 MB 5-8 sec High compression, slower
RAR 180 MB 4-6 sec Depends on compression

ZIP Creation Performance

Compression Speed Output Size Time (250 MB)
STORE Fastest 250 MB 0.5 sec
DEFLATE Normal 230 MB 3-4 sec
BZIP2 Slower 210 MB 6-8 sec
LZMA Slowest 190 MB 10-15 sec

BBDrop uses STORE mode by default for ZIP creation because: - JPG and PNG files are already compressed - STORE is 50-100x faster than DEFLATE - Size difference is negligible (<1% for images)

Storage Locations

Temporary Extraction: 

Windows: C:\Users\[username]\AppData\Local\Temp\bbdrop_extract_*
Linux:   /tmp/bbdrop_extract_*

Temporary ZIP Creation: 

Windows: C:\Users\[username]\AppData\Local\Temp\bbdrop_[id]_[name].zip
Linux:   /tmp/bbdrop_[id]_[name].zip

These directories are automatically cleaned up: - After successful extraction/upload - After external app completes - On application restart (orphaned temp files removed)

Best Practices

When to Use Archives vs. Folders

Use Archives When:

  1. Receiving from others - Someone sends you a ZIP file
  2. Organized by folders - Multi-day events, different locations
  3. Network transfer - Downloading galleries over slow connections
  4. Storage efficiency - Long-term storage of completed galleries
  5. Distribution - Sharing gallery sets with others

Use Folders When:

  1. Local gallery - Already have a folder of images
  2. Single category - All images are from same event/location
  3. Quick upload - No extraction overhead
  4. Adding images - Can easily add more files to folder

Performance Optimization Tips

For Large Archives

  1. Use DEFLATE or STORE compression
  2. RAR and 7Z decompress slowly

  3. ZIP with STORE is fastest for already-compressed images

  4. Split large galleries

  5. Extract all folders, but only upload needed ones

  6. Can resume later by re-adding archive

  7. Monitor extraction progress

  8. Check Logs (Ctrl+L) for extraction status
  9. Large 7Z archives may take 10+ seconds

For External Apps

  1. Use STORE compression for speed
  2. Default STORE mode takes 0.5 sec for 250 MB

  3. DEFLATE takes 5-10x longer with minimal size reduction

  4. Set appropriate timeout

  5. External app timeout (Settings -> External Apps)
  6. Recommend 5 minutes (300 seconds) for multi-host uploads

  7. Gofile uploads typically take 1-3 minutes

  8. Monitor with logs

  9. Check if external app executes successfully
  10. View Logs (Ctrl+L) -> Filter: "archive" or "external"

Archive Organization

For multi-location photo events:

vacation_2025.zip
+-- Day1_Beach/
|   +-- Morning/
|   |   +-- IMG_*.jpg
|   +-- Sunset/
|       +-- IMG_*.jpg
+-- Day2_City/
|   +-- Downtown/
|   |   +-- IMG_*.jpg
|   +-- Museum/
|       +-- IMG_*.jpg
+-- Day3_Mountain/
    +-- Summit/
    |   +-- IMG_*.jpg
    +-- Base/
        +-- IMG_*.jpg

Benefits: - Extract once, see all available folders - Select which day/location to upload - Easy to skip unwanted folders - Maintain organization across uploads

Avoid Flat Archives

Don't do this:

all_vacation_photos.zip
+-- IMG_0001.jpg
+-- IMG_0002.jpg
+-- IMG_0003.jpg
+-- ... (300+ files)

Problems: - All images treated as single folder - Hard to manage different photo sets - No clear organization

Troubleshooting

Archive Won't Extract

Error: "Failed to extract archive"

Solutions: 1. Verify archive integrity - Try extracting manually with 7-Zip or WinRAR - Confirm file isn't corrupted

  1. Check file permissions
  2. Ensure BBDrop has read access to archive

  3. Check temp directory has write access

  4. Free up disk space

  5. Archive extraction needs space for full uncompressed size
  6. Check available disk space > archive size x 1.5

Folders Not Detected

Problem: "Found 0 image folders" but archive contains images

Solutions: 1. Check image format support - Only JPG, PNG, GIF supported - Other formats (TIFF, BMP) won't be detected - Verify filenames have correct extensions

  1. Check folder structure
  2. Images must be in folders, not at root of archive
  3. Create folders: Photos/ -> IMG_*.jpg

  4. Subfolder depth doesn't matter

  5. Check image count

  6. Folder must contain at least 1 image
  7. Hidden files not counted

ZIP Creation Too Slow

Problem: External app ZIP creation takes 30+ seconds

Solutions: 1. Switch to STORE compression - Currently using high compression (DEFLATE/BZIP2/LZMA) - STORE mode: 10-50x faster - Minimal size difference for images

  1. Check disk I/O
  2. Slow disk (HDD) can bottleneck ZIP creation
  3. External SSD recommended for large galleries

  4. Check System tab in Task Manager

  5. Monitor memory

  6. Large galleries (500+ MB) use significant RAM
  7. Close other apps if system is sluggish

Temporary Files Not Cleaned Up

Problem: C:\Users\[user]\AppData\Local\Temp\bbdrop_* files remain

Solutions: 1. Manual cleanup (one-time) 

# Windows
rmdir /s /q %TEMP%\bbdrop_*

# Linux
rm -rf /tmp/bbdrop_*

  1. Ensure proper shutdown
  2. Application crashed during extraction/upload

  3. Restart BBDrop and check Logs

  4. Check disk space

  5. If drive is full, cleanup may fail
  6. Free up space and restart

External Apps & Multi-Host Uploads

Using muh.py with ZIP Archives

The muh.py script is a multi-host uploader that works great with BBDrop-created ZIPs:

# Upload ZIP to Gofile
python hooks/muh.py gofile /tmp/bbdrop_abc123_Summer_Vacation.zip

# Upload ZIP to Pixeldrain
python hooks/muh.py pixeldrain /tmp/bbdrop_abc123_Summer_Vacation.zip

# Upload ZIP with authentication (Rapidgator)
python hooks/muh.py rapidgator /tmp/bbdrop_abc123_Summer_Vacation.zip username:password

Configuring Multiple External Apps

Upload same gallery to multiple hosts:

App 1: Gofile 

{
  "name": "Upload ZIP to Gofile",
  "command": "python",
  "arguments": ["hooks/muh.py", "gofile", "%z"],
  "execute_on": "completed",
  "output_mapping": {"ext1": "$.download_link"}
}

App 2: Pixeldrain 

{
  "name": "Upload ZIP to Pixeldrain",
  "command": "python",
  "arguments": ["hooks/muh.py", "pixeldrain", "%z"],
  "execute_on": "completed",
  "output_mapping": {"ext2": "$.download_link"}
}

Both execute after gallery upload completes, and results are stored in ext1 and ext2 fields.

Parameter Substitution in Archives

Available parameters for external apps:

Parameter Description Example
%z ZIP path (auto-created) /tmp/bbdrop_abc123_vacation.zip
%N Gallery name Summer Vacation
%p Gallery path /home/user/images/vacation
%C Image count 127
%g Gallery ID abc123xyz
%j JSON artifact path ~/.bbdrop/artifacts/abc123.json

Summary

Archive support in BBDrop is designed to be intuitive and automatic:

  • Extract archives with a single drag-and-drop
  • Select folders visually with a friendly dialog
  • Create ZIPs automatically for external applications
  • Clean up automatically without manual intervention
  • Support multiple formats (ZIP, RAR, 7Z, TAR variants)

Use archives to handle complex gallery structures, multi-host uploads, and external application workflows efficiently.