Author: kelexine
A GitHub Actions workflow for extracting, processing, and uploading Android ROM files. Supports Android 11-16, multiple manufacturers, various archive formats, and maintains backward compatibility with legacy devices.
- ✅ Universal Archive Support: ZIP, 7Z, TAR (all variants), RAR, GZIP, BZIP2, XZ, ZSTD, LZ4, Brotli
- ✅ Multiple ROM Formats:
- Payload.bin (A/B devices)
- Super partition (Dynamic partitions)
- Traditional IMG files
- SDAT/DAT files (Android 5-9)
- OZIP (OPPO/Realme)
- ✅ Android Version Support: Android 11, 12, 12L, 13, 14, 15, 16
- ✅ Manufacturer Support: Samsung, Xiaomi, OPPO, Vivo, Realme, OnePlus, Motorola, Nokia, ASUS, Google, Huawei, Honor, TECNO, Infinix, iTel, and more
- ✅ Smart Extraction Modes: Full, System only, Boot images only, Smart auto-select
- ✅ Automatic File Splitting: Handles files larger than GitHub's 2GB limit
- ✅ Nested Archive Extraction: Automatically processes archives within archives
- ✅ Checksum Generation: SHA256 checksums for file verification
- ✅ Comprehensive Metadata: Detailed extraction logs and file information
- 🔍 Automatic ROM Structure Detection: Intelligently identifies payload, super, traditional, or SDAT formats
- 🗜️ Multi-Level Compression: Configurable XZ compression (levels 0-9)
- 📦 Smart File Management: Automatically removes unnecessary files and compresses large images
- 🔄 Resume Support: Uses aria2c for robust downloads with auto-resume
- 🛡️ Error Handling: Graceful fallbacks and comprehensive error reporting
- 📊 Detailed Logging: Step-by-step extraction logs with collapsible groups
git clone https://github.com/kelexine/rom-dumper.git
cd rom-dumper- Go to Settings → Actions → General
- Enable "Allow all actions and reusable workflows"
- Navigate to Actions → Universal ROM Dumper
- Click Run workflow
- Fill in the required parameters:
- DOWNLOAD_URL: Direct download link to ROM archive
- DEVICE_NAME: Your device model
- MANUFACTURER: Select from dropdown
- ANDROID_VERSION: Select or use auto-detect
- ROM_TYPE: Stock ROM, Custom ROM, OTA, or Firmware
- EXTRACT_MODE: Choose extraction scope
- COMPRESSION_LEVEL: 0-9 (default: 6)
- SPLIT_LARGE_FILES: Enable for files >1.8GB
- Results will be uploaded to Releases with the tag
dump-{run_id} - Download all files or individual partitions as needed
Used by: Google Pixel, OnePlus, ASUS, Xiaomi (newer devices)
rom.zip
└── payload.bin
Processing: Extracted using payload-dumper-go → individual partition images
Used by: Most Android 10+ devices
rom.zip
└── super.img (or super.img.lz4/zst)
Processing: Decompressed → unpacked with lpunpack/imjtool → individual logical partitions
Used by: Older devices, MediaTek
rom.zip
├── system.img
├── vendor.img
├── boot.img
└── recovery.img
Processing: Direct extraction and optional compression
Used by: Older Xiaomi, Samsung
rom.zip
├── system.new.dat
├── system.transfer.list
└── system.patch.dat
Processing: Converted to .img using sdat2img
Used by: OPPO, Realme
rom.zip
└── firmware.ozip
Processing: Decryption attempted (may require manual intervention)
| Mode | Description | Use Case |
|---|---|---|
| Full (All partitions) | Extracts every partition image | Complete ROM backup, development |
| System only | Extracts system, system_ext | System modifications, theming |
| Boot images only | Extracts boot, recovery, vendor_boot | Custom recovery, kernel development |
| Smart (Auto-select) | Extracts important partitions only | General use, balanced output size |
Smart mode includes: system, vendor, product, system_ext, boot, recovery, vbmeta, dtbo, super
COMPRESSION_LEVEL: '9' # Maximum compression (slower, smaller files)
COMPRESSION_LEVEL: '1' # Fast compression (faster, larger files)
COMPRESSION_LEVEL: '6' # Balanced (recommended)If files are split due to size limits:
# Reassemble on Linux/Mac
cat system_a.img.xz.part* > system_a.img.xz
xz -d system_a.img.xz
# Reassemble on Windows (PowerShell)
cmd /c copy /b system_a.img.xz.part* system_a.img.xz# Make script executable
chmod +x extract.sh
# Extract ROM archive
./extract.sh rom_archive.zip output_directory
# The script will:
# - Auto-install dependencies
# - Detect archive type
# - Extract nested archives
# - Provide detailed summary- Uses
.tar.md5archives - May include multiple CSC files
- AP file contains system partitions
- MIUI ROMs use
.tgzformat - Fastboot ROMs may have sparse images
- Some devices use payload.bin (newer), others use traditional images
.ozipformat requires decryption- Some ROMs are encrypted with device-specific keys
- Newer devices may use standard payload.bin
- Always uses payload.bin
- Includes both A and B slot images
- OTA files directly processable
- Often use traditional scatter-based ROMs
- May include
scatter.txtfile - Super partition support on newer chipsets
Release: DEVICE_NAME-MANUFACTURER-{run_id}
├── system_a.img.xz
├── vendor_a.img.xz
├── product_a.img.xz
├── system_ext_a.img.xz
├── boot.img.xz
├── recovery.img.xz
├── vbmeta.img.xz
├── dtbo.img.xz
├── METADATA.txt
└── SHA256SUMS.txt
- Device information
- ROM type and source
- Extraction timestamp
- Detected ROM structure
- Complete file listing with sizes
Solutions:
- Verify the download URL is direct (no redirects)
- Check if the server requires authentication
- Try using a different mirror
Solutions:
- Check if archive is corrupted
- Verify archive format is supported
- Review workflow logs for specific error
Solutions:
- Image may be encrypted
- Check if simg2img conversion is needed
- Try manual extraction with lpunpack locally
Solutions:
- Check extraction mode selected
- Verify files weren't too large (>2GB)
- Enable file splitting option
Solutions:
- OZIP requires manufacturer-specific keys
- Extract locally with OzipDecrypt tool
- Request decrypted version from source
Contributions are welcome! Areas for improvement:
- OZIP Decryption: Implement automated decryption for OPPO/Realme devices
- Samsung TAR.MD5: Enhanced support for Samsung's multi-part archives
- Scatter File Parsing: Better support for MediaTek scatter-based ROMs
- UI Improvements: Better release page formatting
- Error Recovery: More robust handling of corrupted archives
# Fork the repository
# Create your feature branch
git checkout -b feature/amazing-feature
# Commit your changes
git commit -m "Add amazing feature"
# Push to branch
git push origin feature/amazing-feature
# Open a Pull Request| Partition | Purpose | Critical |
|---|---|---|
| system | Core Android OS | ✅ Yes |
| vendor | Hardware-specific libraries | ✅ Yes |
| product | Additional apps/features | |
| system_ext | Extended system components | |
| boot | Kernel and ramdisk | ✅ Yes |
| recovery | Recovery mode | |
| vbmeta | Verified boot metadata | ✅ Yes |
| dtbo | Device tree overlay | |
| super | Container for logical partitions | ✅ Yes (A10+) |
| Format | Extension | Tool | Speed | Ratio |
|---|---|---|---|---|
| XZ | .xz | xz | Slow | Excellent |
| ZSTD | .zst | zstd | Fast | Good |
| LZ4 | .lz4 | lz4 | Very Fast | Fair |
| Brotli | .br | brotli | Medium | Very Good |
| GZIP | .gz | gzip | Fast | Good |
This project is open-source and available under the MIT License.
- Android Open Source Project (AOSP)
- payload-dumper-go
- lpunpack
- imjtool
- sdat2img
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Author: kelexine
- ✅ Complete rewrite with modular architecture
- ✅ Support for Android 11-16
- ✅ Multi-manufacturer support
- ✅ Enhanced error handling and logging
- ✅ Automatic file splitting
- ✅ Smart extraction modes
- ✅ Comprehensive metadata generation
- ✅ Nested archive extraction
- ✅ Multiple compression formats
- Basic ZIP extraction
- Super partition support
- Payload.bin extraction
Made with ❤️ by kelexine
Star ⭐ this repository if you find it useful!