================================================================
  INSTAGRAM ARCHIVER  --  SETUP & USAGE
================================================================

WHAT THIS DOES
--------------
Archives an entire Instagram profile (posts, reels, carousels) to
a folder on your computer or cloud drive. Files are sorted by
author -> year -> month -> file type, and each file is named after
its post date and time.


================================================================
  STEP 1  --  INSTALL PYTHON
================================================================

1. Go to https://www.python.org/downloads/
2. Download Python 3.10 or newer.
3. IMPORTANT during install: check the box that says
   "Add python.exe to PATH"
4. Open Command Prompt and run:

       python --version

   If you see a version number, you are good.


================================================================
  STEP 2  --  INSTALL DEPENDENCIES
================================================================

Open Command Prompt in the archiver folder (Shift + Right-click ->
"Open PowerShell window here" works too) and run:

    python -m pip install -r requirements.txt

That installs gallery-dl, the underlying downloader. One-time setup.


================================================================
  STEP 3  --  INSTALL FFMPEG
================================================================

Some Instagram videos come as separate audio + video streams.
Without ffmpeg you will end up with split files.

Open PowerShell and run:

    winget install Gyan.FFmpeg

Close PowerShell, open a fresh one, and verify:

    ffmpeg -version

If winget is unavailable:
  1. Download "release-essentials" from https://www.gyan.dev/ffmpeg/builds/
  2. Extract somewhere permanent (e.g. C:\ffmpeg).
  3. Add C:\ffmpeg\bin to your Windows PATH environment variable.


================================================================
  STEP 4  --  EXPORT YOUR INSTAGRAM COOKIES
================================================================

Instagram blocks scraping without a logged-in session. Chrome
encrypts its cookie database in a way that blocks tools from
reading it directly, so we export the cookies to a file once.

1. Install the Chrome extension "Get cookies.txt LOCALLY":
   https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc

2. Log into instagram.com in Chrome and confirm you see your feed
   (not a login prompt).

3. While on the instagram.com tab, click the extension's icon in
   the Chrome toolbar, then click "Export" (or "Export As").

4. A file downloads to your Downloads folder (named something like
   www.instagram.com_cookies.txt). Move it into the archiver
   folder (the one with archiver.py) and rename it to exactly:

       cookies.txt


================================================================
  STEP 5  --  PICK A DOWNLOAD FOLDER
================================================================

The archiver asks you where to save things when it starts.

Default suggestion:

    %USERPROFILE%\InstagramArchive\<account>

Just hit Enter to accept it, or paste any folder path (e.g. a
Google Drive folder so everything backs up to the cloud):

    G:\My Drive\archiver

You can use ~ for your home folder and %ENV_VARS% -- the script
expands both. No need to set environment variables or edit code.


================================================================
  STEP 6  --  RUN IT
================================================================

1. Make sure Chrome is fully closed before exporting cookies
   in step 4 (Chrome locks its cookie DB while running). The
   archiver no longer touches Chrome itself -- you stay in
   control of your browser.
2. Double-click  run_archiver.bat
3. Enter the Instagram username when prompted, or paste a profile
   URL like https://www.instagram.com/someuser/
4. Leave "Resume cursor" blank for a fresh run.
5. Answer "n" to the wipe prompt unless you really want to delete
   any existing archive of that account.
6. Let it run. It throttles on purpose (2-5 seconds between API
   requests) to avoid Instagram's rate limiter. Large accounts
   can take hours.

A running counter on the left tracks how many files have been
downloaded vs. skipped (already present).


================================================================
  OUTPUT LAYOUT
================================================================

<ARCHIVER_DIR>\<account>\
    <author>\                       (post author -- collab posts
       <year>\                       go under the collaborator's
          <Month>\                   username)
             Images\   jpg, webp, png, gif
             Videos\   mp4, mov, webm
             JSON\     one .json metadata file per post


================================================================
  TROUBLESHOOTING
================================================================

"401 Unauthorized" mid-run
    Instagram throttled your session. Wait a few minutes, then
    re-export cookies.txt (Step 3) and re-run. To resume where
    you stopped, paste the cursor value gallery-dl printed into
    the "Resume cursor" prompt.

"Failed to decrypt cookie (DPAPI)"
    cookies.txt is missing or in the wrong folder. Re-do Step 3
    and make sure the file ends up next to archiver.py with the
    exact name "cookies.txt".

Videos download as separate audio + video files
    ffmpeg isn't installed or not on PATH. Re-do Step 2 and open
    a fresh terminal before retrying.

"could not invoke gallery-dl"
    Run:
        python -m pip install -r requirements.txt

"available image resolutions are lower than the original"
    Your cookies have gone stale. Re-export cookies.txt while
    actively logged into instagram.com. (mostly not a problem, but this showed up every time for me when archiving no matter what, couldn't figure out why.)


================================================================
  LICENSE
================================================================

MIT. See LICENSE file. Use it however you want.
