instarec: Instagram Livestream Downloader

instarec is a Python-based command-line tool for downloading Instagram livestreams. It is designed to be robust, featuring concurrent downloading of video and audio segments, recovery of past segments, and automatic merging of the final video file.

Features

• Interactive Quality Selection: Interactively choose from available video and audio stream qualities.
• Past and Live Recording: Downloads both previously broadcasted segments and continues to record the livestream in real-time.
• Optimized Performance: Downloads segments efficiently and merges the final video without needing to re-encode.
• Segment Loss Detection: Can generate a summary file detailing any missing segments from the download.
• Flexible Usage: Use either a direct .mpd manifest URL or an Instagram username to start a download.
• Customizable: Offers a wide range of command-line arguments to tailor the downloading process.

Installation

Prerequisites

You must have ffmpeg and ffprobe installed and accessible in your system's PATH. These are required for merging the final video and audio files.

Standard Installation

The recommended way to install instarec is via pip:

pip install instarec

This will install the tool and make the instarec command available in your terminal.

Usage

You can start a download by providing either a direct .mpd URL for a livestream or an Instagram username.

Basic Examples

• Download from an MPD URL with interactive quality selection and mux to MKV:

  instarec <mpd_url> my_video.mkv -i
  

• Download from an MPD URL with the best available quality and mux to MP4:

  instarec <mpd_url> my_video.mp4
  

• Download with specific video/audio quality and create a summary file:

  instarec <mpd_url> my_video.mkv --video-quality <video_id> --summary-file summary.txt
  

Manually Getting the MPD URL

You can manually find the manifest URL (.mpd) thourgh the browser:

1. Open the Instagram livestream in a web browser.
2. Open the Developer Tools (usually by pressing F12 or Ctrl+Shift+I).
3. Go to the Network tab.
4. In the filter box, type .mpd to find the manifest request.
5. Right-click the request and copy the full URL.

Using Instagram Usernames (Requires additional setup)

To download using a username, you need to authenticate with Instagram. There are two methods available: cookie-based authentication and credentials-based authentication (instagrapi).

[!WARNING] Instagram is known for flagging accounts that make automated requests. Continuously polling a user's live status may get your account flagged or temporarily blocked. Use this feature at your own risk.

Cookie-Based Authentication

This method uses cookies exported from your browser and does not require instagrapi.

1. Export your Instagram cookies:

   Log into Instagram in your browser, then export your cookies as a Netscape-format .txt file using a browser extension such as Get cookies.txt LOCALLY.

2. Pass the cookie file with --cookies:

   instarec --cookies cookies.txt <username> my_video.mkv
   

Credentials-Based Authentication (instagrapi)

1. Install instagrapi:

   instagrapi is an optional dependency needed to fetch the stream URL from a username. Install it manually using pip:

   pip install instagrapi
   

2. Configure Credentials:

   instarec needs your Instagram login to check a user's live status. Create a credentials.json file in the application's configuration directory with your username and password.

   The location of this directory depends on your operating system:

   • Linux: ~/.config/instarec/credentials.json
   • macOS: ~/Library/Application Support/instarec/credentials.json
   • Windows: C:\Users\<YourUser>\AppData\Local\instarec\instarec\credentials.json

   The content of credentials.json should be:

   {
     "username": "your_instagram_username",
     "password": "your_instagram_password"
   }
   

Command-Line Arguments