Koofr Album Downloader

Advanced Playwright-based automation tool that dynamically analyzes and downloads all files from Koofr photo album links. Uses intelligent DOM analysis to work with Koofr's current interface structure.

🚀 Features

• ✅ Dynamic file discovery - Automatically detects all downloadable files
• ✅ Smart album naming - Extracts album name from breadcrumbs, title, or URL
• ✅ HTTP-based downloads - Reliable file downloads using browser session
• ✅ Parallel downloads - Download up to 10 files simultaneously (configurable)
• ✅ Large album support - Handles albums with 100+ files using smart scrolling
• ✅ Skip existing files - Automatically skips already downloaded files
• ✅ Media format support - Handles images (.jpg, .png) and videos (.mp4, .mov, .avi, etc.)
• ✅ Cross-platform compatibility - Works on Windows, Mac, and Linux
• ✅ Headless by default - Fast background downloads with option for visible browser
• ✅ Error resilience - Individual file failures don't stop the batch process
• ✅ Sharing limit bypass - Automatically handles "Public sharing limit reached" errors

📦 Installation

Option 1: Using npx (Recommended - No Installation Required)

# Download from default album
npx koofr-downloader

# Download from custom album
npx koofr-downloader "https://app.koofr.net/links/your-album-id"

# Show browser window for debugging
npx koofr-downloader --visible

# Control download speed (1-20 parallel downloads)
npx koofr-downloader --concurrency=5

Download Location: When using npx, files are saved to your ~/Downloads/AlbumName/ folder.

Option 2: Local Development Setup

Prerequisites

• Node.js (version 16 or higher)
• Chrome browser

Setup

1. Clone or download this project
2. Install dependencies:

   npm install

3. Install Playwright Chrome browser:

   npm run test:install

Download Location: When running locally, files are saved to the project directory.

💻 Usage

NPX Usage (Global Access)

# Basic usage with default album
npx koofr-downloader

# Custom album URL
npx koofr-downloader "https://app.koofr.net/links/your-album-id"

# Show browser for debugging
npx koofr-downloader --visible

# Faster downloads with more parallel connections
npx koofr-downloader --concurrency=15

# Show help
npx koofr-downloader --help

Local Development Usage

# Download from default album (headless mode)
npm run download

# Download with visible browser (for debugging)
npm run download:visible

Custom Album URL (Local)

# Download from any Koofr album link
npm run download:custom "https://app.koofr.net/links/your-album-id"

# Or directly with node
node koofr-downloader.js "https://app.koofr.net/links/your-album-id"

# With custom parallel download settings
node koofr-downloader.js "https://app.koofr.net/links/your-album-id" --concurrency=15

Performance Options

# Adjust parallel downloads (1-20, default: 10)
node koofr-downloader.js --concurrency=5    # Conservative (slower, less server load)
node koofr-downloader.js --concurrency=15   # Aggressive (faster, more server load)

# Combine with other options
node koofr-downloader.js "https://app.koofr.net/links/your-album-id" --visible --concurrency=8

Available Scripts

• npm run download - Download files in headless mode (default)
• npm run download:visible - Download with visible browser window
• npm run download:custom - Use with custom URL as argument
• npm test - Run test suite with visible browser
• npm run test:headless - Run tests in headless mode

🎯 How It Works

1. Page Analysis: Navigates to the Koofr album and analyzes the DOM structure
2. File Discovery: Finds all download links using pattern matching (/files/get/)
3. Album Naming: Extracts album name from breadcrumbs, page title, or URL
4. Download Setup: Creates album-named folder in project directory
5. HTTP Downloads: Uses browser's fetch API to download files with session cookies
6. File Management: Saves files with sanitized names and proper extensions

📁 Output Structure

koofr-downloader/
├── Album_Name/           # Generated folder named after the album
│   ├── file1.jpg         # Downloaded image files
│   ├── video1.mp4        # Downloaded video files
│   └── ...
├── koofr-downloader.js   # Main script
└── README.md

🔧 Supported File Formats

Images: .jpg, .jpeg, .png, .gif Videos: .mp4, .mov, .avi, .mkv, .webm, .wmv, .flv, .3gp

The downloader automatically preserves correct file extensions by analyzing both the URL and display text.

⚙️ Configuration

Default Settings

• Headless mode: Enabled (no browser window)
• Parallel downloads: 10 concurrent downloads
• Browser: Chrome with optimized settings
• Timeouts: 30s for page load, 15s for downloads
• Error handling: Continue on individual failures
• Batch delays: 1 second between batches of downloads

Command Line Options

• --visible - Run with visible browser window (default: headless)
• --concurrency=N - Set parallel downloads (1-20, default: 10)
• Can be used as --concurrency=5 or --concurrency 5

🐛 Troubleshooting

Common Issues

"No downloadable files found"

• Verify the album URL is publicly accessible
• Check if the album contains files
• Try running with --visible to see what's happening

"Failed to download [filename]"

• Network connectivity issues
• File might be corrupted or unavailable
• Check the error message for specific details

"Album name extraction failed"

• Falls back to URL-based or date-based folder naming
• This doesn't affect file downloads

Debug Mode

Run with visible browser to see the download process:

npm run download:visible

Logs and Screenshots

• Detailed console logging shows download progress
• Error screenshots saved automatically on failures
• Check the generated album folder for successfully downloaded files

🧪 Testing

# Run full test suite
npm test

# Test in headless mode
npm run test:headless

# Install test browsers
npm run test:install

📄 Example Output

🤖 Running in headless mode with 10 parallel downloads
🚀 Starting Koofr Album Download...
📡 Navigating to: https://app.koofr.net/links/442cdc2c-1a24-4119-9252-b8554f2b8c58
⚠️ Public sharing limit reached - clicking "Show me the link contents" button
✅ Successfully bypassed sharing limit
✅ Page loaded successfully
🔍 Extracting file links...
🔄 Checking for more files by scrolling...
🔢 Initial file count: 20
Found 32 files in DOM, total collected: 138 (+12 new) (scroll attempt 1, 9% down)
📊 Complete scroll finished: collected 138 unique files
✅ Found 138 downloadable files
📂 Extracting album name...
✅ Found album name: "Album_Name"
📁 Created download directory: /path/to/koofr-downloader/Album_Name
📥 Starting download of 138 files...
🚀 Using parallel downloads with concurrency limit of 10

📄 Processing file 1/138: file1.jpg (1.4 MB)
📄 Processing file 2/138: file2.mp4 (17.9 MB)
📄 Processing file 3/138: file3.jpg (2.1 MB)
✅ Downloaded: file1.jpg (1483 KB)
✅ Downloaded: file3.jpg (2156 KB)
📊 Progress: 10/138 files processed (8 downloaded, 2 skipped, 0 failed)

📊 Download Summary:
   🆕 Downloaded: 125
   ⏭️ Skipped (existing): 13
   ❌ Failed: 0
   📁 Saved to: /path/to/koofr-downloader/Album_Name
🎉 Download process completed!

🔒 Privacy & Security

• Downloads are performed using your browser's session
• No authentication credentials are stored
• Only publicly accessible album links are supported
• Downloads are saved locally to your machine

📜 License

ISC License - Free for personal and commercial use.

🤝 Contributing

Feel free to submit issues, feature requests, or pull requests to improve this tool.