v0.60

WhatsApp Backup Tools v0.60

Version 0.60 brings support for shared contact cards across both tools, complete sticker archiving and gallery viewing, disk space savings with media hardlinking, and a smoother viewing experience in the offline web viewer.

📇 Shared Contact Cards (.vcf): WhatsApp stores shared contacts directly inside backup databases rather than as media files. WhatsApp Backup Tools now extracts and saves contacts as standard .vcf files and displays them as native contact cards in the web viewer, complete with search and 1-click download support!

---

📁 WhatsApp Archiver

✨ New Features

• Sticker Archiving on Android: Stickers sent and received on Android (.webp and .was) are now fully extracted, archived to disk, and recorded in the archive database alongside all other media types.
• Shared Contact Cards Archiving (.vcf): Automatically extracts contacts shared in 1:1 and group chats into organized .vcf files with original message timestamps and duplicate collision protection.
• Hardlink Duplicate Media Files (--link-duplicates): Drastically save disk storage by hardlinking identical media files shared across chats instead of duplicating files on disk. Unsupported filesystems (such as exFAT or network drives) are automatically detected upfront with safe fallback to copying.

⚡ Improvements

• Clearer Duplicate Media Reports: The duplicate_media_report.csv now features a clear link_status column (distinguishing zero-byte filesystem hardlinks from physical duplicate copies) and records original WhatsApp message dates and times for easy auditing.
• Detailed Run Summary & Duplicate Breakdown: The archiver's final report now explains why files were skipped (differentiating files already archived in previous runs from duplicate messages within the same chat), reports hardlink counts under copied files, and highlights overall duplicate totals found across the archive.

🐛 Bug Fixes

• Fixed duplicate reporting when identical files were shared across multiple messages, and ensured address book documents are properly preserved during restore mode.
• Minor bug fixes and reliability improvements.

---

🌐 WhatsApp Viewer

✨ New Features

• Dedicated Stickers Section in Media Gallery: Stickers now have a dedicated section and filter pill in the Media Gallery on both iOS and Android, with server-side filtering and count badges.
• Contact Cards in Chat & Gallery: Received contacts now display in native WhatsApp-style contact cards with contact avatars, names, and a 1-click download button. Contact cards are also browsable in the Media Gallery and fully indexed in search.
• "Edited" Message Indicator: Messages edited in WhatsApp now display an "Edited" badge next to the timestamp.
• Lightbox Wheel Zoom & Pan: Zoom smoothly into photos up to 6× using your mouse wheel, drag to pan around, and reset back to fit with a single click.

⚡ Improvements

• Media Gallery Filter Synchronization: Switching media filters (such as switching from links back to photos) after scrolling down multiple months now seamlessly loads items at your current position without jumping or showing empty areas.
• Photo Aspect Ratio & Shrink-Wrapping: Vertical and tall photos now keep their natural aspect ratio without horizontal stretching, and chat bubbles fit snugly around images without empty space.

🐛 Bug Fixes

• iOS Sticker Classification: Fixed an issue where iOS stickers were treated as standard photos in chat bubbles and the Media Gallery instead of appearing under the dedicated Stickers section.
• Voice Message Audio Player: Fixed an issue where the inline audio player for voice messages was invisible in Google Chrome, Microsoft Edge, and other Chromium-based browsers.
• macOS / Older SQLite Compatibility: Fixed a startup crash (unrecognized option: "contentless_delete") when running on macOS or systems with SQLite versions older than 3.43.
• Minor UI polish and rendering fixes.

---

🚀 How to Upgrade

Update to the latest version using pip:

pip install --upgrade whatsapp-backup-tools

💡 Windows users: If pip is not recognized, run py -m pip install --upgrade whatsapp-backup-tools instead.

v0.51

WhatsApp Backup Tools v0.51

This minor update focuses on fixes, performance optimizations, and documentation refinements that were left outside of the initial stable release. Notably, official PyPI distribution is now available!

What's New in v0.51

🌐 WhatsApp Backup Viewer (wab-viewer)

• Faster & Smoother Media Gallery: Browsing large media collections is now much faster and more responsive. Media items load on demand as you scroll and unload when off-screen, drastically reducing browser memory usage and keeping scrolling smooth.
• Accurate Video Previews: Video thumbnails now show actual preview frames instead of blank or black rectangles, and generate quietly in the background without causing scroll stutter.
• Multi-Year Archive View: Fixed an issue where older years in large chats were omitted. All years are now automatically fetched and browsable in the Archive View.
• Sorted Month Dividers: Fixed out-of-order month headers when browsing through mixed media and documents.
• Accurate Chat Media Size: Fixed the Chat Info panel to accurately calculate and display total media storage used by individual chats.

📁 WhatsApp Backup Archiver (wab-archiver)

• No changes in this release.

📦 Installation & Packaging

• Now on PyPI: You can now install and update the tools directly with pip:

  pip install whatsapp-backup-tools

• Automated Release Pipeline: Configured seamless publishing to PyPI for future updates.

📚 Documentation

• Simplified Onboarding: Streamlined the setup flow into an easy 3-step guide in the README.
• Syncthing Guide: Added a step-by-step walkthrough for pairing and syncing Android media over local Wi-Fi.
• Stickers Archival Status: Clarified that WhatsApp stickers are safely saved into dedicated archive folders by wab-archiver.

---

🚀 Getting Started

Install via pip:

pip install whatsapp-backup-tools

💡 Windows users: If pip is not recognized, run py -m pip install whatsapp-backup-tools instead.

1. Archive your backup

The easiest and recommended way to run the archiver is using a configuration file, avoiding long terminal commands:

1. Generate the configuration file:

   wab-archiver config generate

   This creates an example-config.toml. Open it in any text editor, fill in your paths and encryption key, and save it as config.toml.

2. Preview and run:

   wab-archiver archive --dry-run

   Once the preview completes without errors, run wab-archiver archive to build your archive!

Alternatively, run directly with command-line arguments

# Android example (dry run first)
wab-archiver archive \
  --msgstore /path/to/msgstore.db.crypt15 \
  --e2e-key YOUR_64_CHAR_KEY \
  --wa-root /path/to/WhatsApp \
  --output /path/to/my-archive \
  --dry-run

# iOS example
wab-archiver archive \
  --ios-backup /path/to/Backup/<UDID> \
  --output /path/to/my-archive \
  --dry-run

2. Open the viewer

wab-viewer /path/to/my-archive

Opens locally in your browser at http://127.0.0.1:5000.

v0.50

WhatsApp Backup Tools v0.50

Introducing WhatsApp Backup Tools, a suite to archive and access your WhatsApp data locally and privately.

Privacy, Privacy, Privacy: These tools run 100% locally on your machine. No data leaves your computer.

What's New in v0.50

📦 WhatsApp Backup Archiver (wab-archiver)

The Archiver is the former "WhatsApp Media Archiver" which gave the original name to the repo, now refined and evolved.

• Organized Archive: Automatically sorts your WhatsApp media into structured folders (Contacts/ and Groups/) organized by year and Sent/Received.
• Cross-Platform Support: Works with Android backups (no root required) and iOS backups (both plaintext and encrypted iTunes backups).
• Identity & Rename Tracking: Automatically detects contact renames, phone number migrations, and groups with identical names across runs.
• Audit Reports: Exports comprehensive missing media, duplicate media, and conflict audit CSV reports.
• Safe & Incremental: Skips already archived files and preserves original message timestamps.

Notable features added in this release:

• ADB Media Pull (--pull-media): Pull media directly from your Android device over USB into a permanent staging folder with resume support and remote MD5 verification.
• iOS Auxiliary Databases Extraction: Automatically extracts auxiliary databases (ExtChatDatabase.sqlite, MessagingInfraDatabase.sqlite, LID.sqlite, etc.) from backups to preserve rich metadata and receipts.
• Multi-Root Source Merging (--wa-root): Merge media from multiple drives or backup folders with automatic conflict auditing (source_conflicts_report.csv).
• HD Deduplication: Detects low-resolution and HD copies of the same photo or video, archiving only the best-quality version.
• ...and more!: Config file generator (wab-archiver config generate), automatic database health checks, dry-run folder synchronization, and cyclic contact loop resolution.

🌐 WhatsApp Backup Viewer (wab-viewer)

Access your backups like WhatsApp Web, but local and offline.

• Authentic Local Web UI: Browse and search chats offline in a clean interface replicating WhatsApp Web with full dark and light theme support.
• Rich Timeline: Full message history with quoted messages, reactions, read/delivery receipts, and service events.
• In-Browser Media Player: Stream video, play voice notes with seeking support, and preview photos in a full-screen lightbox.
• Media Gallery: Explore chat media through a thumbnail grid or browse the underlying folder structure.
• Instant Search & Jump to Date: Fast full-text search across all conversations or scoped to individual chats.

⚠️ Initial Release Notes

It's the first release of the Viewer, and work is planned to expand its capacities.

Call history, poll voting details, and stickers are not yet rendered in the timeline. Large media gallery thumbnail optimizations are planned for subsequent updates.

---

🚀 Getting Started

# Clone the repository
git clone https://github.com/auanasgheps/whatsapp-backup-tools.git
cd whatsapp-backup-tools

# Install dependencies and tools
pip install .

# Archive your backup
wab-archiver archive --help

# Open the viewer
wab-viewer /path/to/archive

I am working on distributing the tools via PyPI - pip install wab-tools will be available soon!.

v0.35 - First public pre-release

First public pre-release of WhatsApp Media Archiver, a Python CLI that archives WhatsApp media from device backups into a structured folder hierarchy, with full re-run safety and deduplication.

Features

• Android & iOS: ADB pull from a connected device, --wa_root pointing at an extracted WhatsApp folder, or direct iPhone backup reading (--ios_backup). Encrypted databases and backups supported.
• Organised archive: media lands in Contacts/<Name>/<YYYY>/Sent|Received/ and Groups/<Name>/<YYYY>/ with original WhatsApp timestamps preserved.
• Re-run safe: an SQLite archive database tracks every copied file: duplicates are skipped, not re-copied.
• Contact and group rename tracking: when a name changes, the folder is renamed automatically on the next run.
• Restore mode (--mode restore): reconstruct the original WhatsApp/Media/ folder tree from the archive without needing the original device or database. Only available for Android.
• Config file (--config, --generate-config): save persistent settings in a config.toml instead of retyping long commands every run.
• Cross-platform: macOS, Linux, Windows.

Requirements

• Python 3.11+
• pip install iphone-backup-decrypt, encrypted iOS backups only
• pip install wa-crypt-tools, encrypted Android databases only
• pip install tzdata, Windows only, for --timezone
• adb on PATH, for --mode adb

If you are missing a dependency, the script will inform you.

Pre-release notice

This is a pre-release. Core functionality has been tested on real backups, but there may be edge cases, especially around unusual backup formats, older WhatsApp versions, or less common device configurations. Feedback and bug reports are welcome!

Why 0.35? It's just the internal version, I decided to keep it.