instagram-download

name	instagram-download
description	Download Instagram Reels and posts using browser-assisted extraction. Bypasses login requirement by extracting video URLs from the browser session's network performance entries.
version	1
author	Hermes Agent
license	MIT
platforms	["linux","macos"]
prerequisites	{"commands":["ffmpeg","ffprobe"]}
metadata	{"hermes":{"tags":["instagram","social-media","download","reels"],"homepage":"https://www.instagram.com"}}

Instagram Download — Browser-Assisted Extraction

Download Instagram Reels (and potentially posts) at highest quality without requiring login credentials. Instagram blocks yt-dlp and bare curl — the workaround is to load the page in the browser tool and extract video URLs from the network resource entries.

---

When to Use

• User sends an Instagram Reel link and asks you to download it
• yt-dlp returns: login required, rate-limit reached, or unable to extract shared data
• You have browser tool access

---

Workflow

1. Open the Reel in the Browser

browser_navigate(url="https://www.instagram.com/reel/REEL_ID/")

The page loads even without login — Instagram shows the content behind a signup prompt but the video elements and network resources are still accessible.

2. Extract Video URLs from Browser Network Performance Entries

performance.getEntriesByType('resource').filter(r => r.name.includes('.mp4')).map(r => r.name)

This returns an array of MP4 URLs from Instagram's CDN. You'll typically see:

• Video-only stream — bitrate ~1 Mbps+, H.264, 720×1280 (the best quality)
• Lower-bitrate video stream — ~273 kbps
• Audio-only stream — AAC, ~12-87 kbps (look for "audio" or "vbr3_audio" in the efg URL parameter)

3. Download the Full Files

Instagram splits streams into byte-range chunks (bytestart=N&byteend=M). Use the full URL without bytestart and byteend parameters — this gives the complete file:

curl -sL -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  -o reel_video.mp4 "VIDEO_URL_WITHOUT_BYTESTART_PARAMS"
curl -sL -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  -o reel_audio.mp4 "AUDIO_URL_WITHOUT_BYTESTART_PARAMS"

4. Identify Which Stream Is Which

Not every URL has "audio" in its params. Use ffprobe to check:

ffprobe -v quiet -print_format json -show_streams file.mp4

• Video stream: codec_type: "video", codec H.264, 720×1280
• Audio stream: codec_type: "audio", codec AAC

5. Merge Audio + Video with ffmpeg

ffmpeg -i reel_video.mp4 -i reel_audio.mp4 \
  -c:v copy -c:a aac -b:a 128k \
  -map 0:v:0 -map 1:a:0 -shortest \
  -movflags +faststart reel_final.mp4 -y

• -c:v copy — copy video stream without re-encoding (lossless, fast)
• -c:a aac -b:a 128k — re-encode audio to a good bitrate (original is often very low ~12 kbps)
• -map 0:v:0 -map 1:a:0 — take video from first file, audio from second
• -movflags +faststart — enables streaming-friendly moov atom at start
• -y — overwrite output

6. Deliver the Result

Send the file via send_message with MEDIA:/path/to/reel_final.mp4.

---

Pitfalls

• Don't use yt-dlp for Instagram — it fails with login/rate-limit errors. The browser workaround is the reliable path.
• Byte-range URLs are not full files — URLs with bytestart=N&byteend=M params are chunks. Strip those params to get the complete file. If the base URL already includes them in a way you can't cleanly remove, download ALL byte chunks and concatenate them.
• Audio stream may have very low bitrate (~12 kbps). The ffmpeg command above upscales it to 128k AAC for acceptable quality.
• Clean up temp files — video/audio downloads and the final output are large. Delete them after sending.
• Single video stream (no audio) — sometimes the reel has no separate audio track. Check with ffprobe and skip the audio merge if there's no audio stream.
• Cookie-based download — if the user provides Instagram cookies (exported from Cookie-Editor extension as JSON), you can use them with curl -b cookies.json or yt-dlp --cookies cookies.json for a simpler download path. Ask for cookies before falling back to the browser method.

---

References

For provider-specific details, error transcripts, and reproduction recipes, see references/instagram-cdn-patterns.md.===ME:instagram-download