Album Download Manager with Persistent State

[yopichy]

Album Download Manager

Overview

The Album Download Manager allows you to batch download entire albums from Telegram Web and track their download status across sessions using persistent local storage.

---

1. Scanning an Album

What is Scanning?

Scanning marks a multi-item album for tracking and creates a badge showing download progress.

How to Scan:

1. Navigate to a Telegram conversation with media albums
2. Click on any media item (image or video) within a multi-item album (2+ items)
3. A blue "Download" badge will appear in the top-right corner

Important:

• Only multi-item albums get badges
• Single media messages are not tracked
• The album must be detected as .is-album or contain multiple .album-item.grouped-item elements

---

2. Downloading an Album

Click the Badge to Start Download

1. After scanning, click the "Download" badge
2. The script will automatically:
   • Scan all media items in the album
   • Download images directly
   • Open viewer for videos to extract stream URLs
   • Save files with message IDs as filenames
3. Track progress in the bottom-right corner
4. Badge updates automatically:
   • "Partial downloaded" - Some items processed
   • "Downloaded" - All items completed

Download Flow by Media Type:

For Videos:

1. Media viewer opens automatically
2. Script detects video src or probes for stream URL
3. Performs HEAD check to validate video (not HTML/error pages)
4. Initiates download with progress tracking
5. Viewer remains open until download completes
6. Note: You may need to manually close the viewer or press Escape
7. Next video begins processing

For Images:

1. Downloads directly from src or blob: URLs
2. No progress bar (instant download)
3. Extracts mime-type for correct file extension
4. Continues to next item

---

3. Redownloading an Album

When to Use Redownload:

• Download was incomplete
• You want to re-download everything
• Starting fresh with an album

How to Redownload:

1. Locate an album with:

   • "Partial downloaded" badge, OR
   • "Downloaded" badge

2. A red "Redownload" button appears next to the badge

3. Click "Redownload":

   • Re-downloads ALL items in the album
   • Updates storage for re-downloaded items only
   • Previously skipped items remain marked as downloaded
   • Progress bars show for each item
   • Badge updates when complete

---

4. Badge Status Reference

Badge Status	Meaning	What Happens When Clicked
Download	Album detected, ready to download	Begins downloading all items
Partial downloaded	X of Y items downloaded	Downloads remaining items, skips already-done items
Downloaded	All items completed	Nothing happens (use Redownload button instead)

---

5. Download Progress & Troubleshooting

Progress Indicators:

• Progress text shows "Downloading... X/Y" during active processing
  • Updates in real-time as items complete
  • Shows current count vs total items
  • Updates displayed in badge
• Progress bars appear in bottom-right corner for videos only
• Shows filename and completion percentage
• Displays "Completed" when done
• Can be dismissed by clicking × button

If Download Fails:

1. Progress bar turns red showing "Aborted"
2. Close button becomes clickable to dismiss
3. The item is not marked as downloaded in storage
4. Click the badge again to retry that specific item

Viewer Issues:

• Viewer doesn't close: Press Escape key manually
• Viewer doesn't open: Ensure popup permission is enabled
• Wrong video detected: Verify message has video indicator (.video-time class)

---

6. Storage & Persistence

How State is Saved:

• Each album stored in browser localStorage
• Key format: tel_album_states_v1_{albumMessageId}
• Per-item tracking: item stored only if successfully downloaded
• Survives page refresh and browser restart

Storage Structure:

{
  "status": "partial",  // "scanned" | "partial" | "downloaded"
  "items": {
    "4295114062": true,  // item message ID → downloaded
    "4295114063": true
  }
}

Data Persistence:

• ✅ Survives page refresh
• ✅ Survives tab close
• ✅ Cleared only when browser data is wiped
• ❌ Not synced across devices

---

7. Tips & Best Practices

For Best Results:

• Keep the browser tab active during downloads
• Don't navigate away during video download sequences
• Use Firefox or Chrome for best compatibility
• Ensure popup/media permissions enabled

Large Albums (10+ items):

• Videos process sequentially (one at a time)
• Each video opens viewer, streams, then closes
• Total time = (avg video download time × number of videos)
• Can take 5-30+ minutes depending on media size
• Progress displays as "Downloading... X/Y" throughout

Avoiding Issues:

• Don't click badge multiple times rapidly
• Let each video complete before closing viewer manually
• Images download instantly; don't wait for them
• Check console (F12) for error details if items fail

---

8. Advanced: Console Commands

View Album States:

// List all saved album states
for (let i = 0; i < localStorage.length; i++) {
  const key = localStorage.key(i);
  if (key.startsWith('tel_album_states_v1_')) {
    const data = JSON.parse(localStorage.getItem(key));
    console.log(key, data);
  }
}

Reset Specific Album:

// Clear one album's state (replace with actual album message ID)
localStorage.removeItem('tel_album_states_v1_4295114062');

Reset All Albums:

// Clear all album download states
Object.keys(localStorage)
  .filter(k => k.startsWith('tel_album_states_v1_'))
  .forEach(k => localStorage.removeItem(k));

---

9. Example Workflows

Workflow 1: Download New Album

1. Click video in 5-item album
   → Badge shows "Download"

2. Click "Download" badge
   → Video 1 viewer opens, downloads, closes (~30 sec)
   → Progress shows: "Downloading... 1/5"
   → Video 2 viewer opens, downloads, closes (~40 sec)
   → Progress shows: "Downloading... 2/5"
   → Image downloads instantly
   → Progress shows: "Downloading... 3/5"
   → Videos 3-5 process similarly
   → Final: "Downloading... 5/5"

3. Badge changes to "Downloaded"
   → "Redownload" button appears

4. Refresh page
   → Badge still shows "Downloaded" (state restored)

Workflow 2: Resume Incomplete Download

1. Badge shows "Partial downloaded (2/5)"
   → 2 items already done

2. Click badge
   → Script skips items 1-2 (already stored)
   → Progress shows: "Downloading... 2/5"
   → Downloads items 3-5
   → Progress bars show only for new items
   → Final: "Downloading... 5/5"

3. Badge updates to "Downloaded"

Workflow 3: Redownload Everything

1. Album has "Downloaded" badge
   → "Redownload" button visible

2. Click "Redownload"
   → All items download again (even if stored)
   → Progress shows: "Downloading... 1/5" through "5/5"
   → Files overwrite on disk
   → Storage marked as re-downloaded

3. Badge remains "Downloaded"

---

10. Supported Platforms

Platform	Support	Notes
Telegram Web (/a/)	⚠️ Limited	All features work for image only
Telegram Web (/k/)	✅ Full	All features work
Mobile browsers	⚠️ Limited	File system API may not work

---

11. FAQ

Q: Why is my album not getting a badge?
A: Ensure it's a multi-item album (2+ items). Single media messages don't get badges.

Q: Can I download albums from pinned messages?
A: Yes, if they appear as multi-item albums in the chat.

Q: What if I accidentally clear browser data?
A: All album states are lost. Badge data won't restore, but you can re-download anytime.

Q: Do I need to click badge again to download remaining items?
A: No, the script automatically skips already-downloaded items on next badge click.

Q: Can I stop a download in progress?
A: Videos will complete once started. You can manually close the viewer to halt the sequence.

Q: Why are some videos downloading as .bin files?
A: MIME-type detection failed. The file is still valid but may need manual rename to .mp4.

Q: How do I see download history?
A: Check localStorage keys starting with tel_album_states_v1_ via console.

Q: What does "Downloading... X/Y" mean?
A: It shows the current progress: X items completed out of Y total items in the album. Updates in real-time as each item processes.

---

12. Known Limitations

• ❌ No visual progress for image downloads (instant)
• ❌ Videos must download sequentially (one at a time)
• ❌ Viewer may stay open after download (press Escape)
• ❌ No cross-device sync of download states
• ❌ Single-media messages not tracked by design
• ⚠️ Large video files may timeout on slow connections

---

13. Troubleshooting Checklist

Problem	Cause	Solution
Badge not appearing	Single-item album	Ensure 2+ items in album
Download skips items	Already stored	Use "Redownload" to force
Progress bar aborts	Network error	Check connection, click badge again
Wrong filename	No metadata	Files named by message ID (correct)
"Downloading... X/Y" stuck	Slow network	Wait for items to process, check console for errors
Viewer stays open	By design	Press Escape to close manually
localStorage full	Browser limit	Clear old downloads, try again

[Neet-Nestor]

Hi @yopichy , thanks for the contribution! for me to better test and understand the feature, could you please attach some screenshots or screen recording for this functionality please? Thank you!

[Neet-Nestor]

On /a/ version, it shows the badge but doesn't work at all for video album. Please properly handle this.

Also the "scanned" button seems very unintuitive to me: it's unclear to me that this is the button I should click to download the entire album. We should have more intuitive UI/UX.

[yopichy]

On /a/ version, it shows the badge but doesn't work at all for video album. Please properly handle this.

Also the "scanned" button seems very unintuitive to me: it's unclear to me that this is the button I should click to download the entire album. We should have more intuitive UI/UX.

i'm already informed on /a only works for images now, because it's harder to handle streaming video at /a instead of /k. i'll change badge label for now.