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

Argument	Short	Description
url_or_username		The URL of the .mpd manifest, a raw Instagram username, or a raw instagram user ID.
output_path		The destination filepath for the final video. Defaults to .mkv if no extension is provided.
--cookies		Path to a Netscape-format cookie file for Instagram authentication.
--interactive	-i	Interactively select video and audio quality.
--log-file		Path to a file to write logs to.
--summary-file		Path to a file to write a download summary to.
--verbose	-v	Enable verbose (DEBUG level) logging.
--quiet	-q	Suppress informational (INFO level) logging.
--video-quality		One or more representation IDs for video, in order of preference.
--audio-quality		One or more representation IDs for audio, in order of preference.
--poll-interval		Seconds to wait between polling the manifest for live segments.
--max-search-requests		Maximum concurrent requests when searching for past segments.
--download-retries		Number of retries for a failed segment download.
--download-retry-delay		Initial delay in seconds between download retries.
--check-url-retries		Number of retries for a failed URL check.
--proxy		Proxy URL (e.g. http://user:pass@host:port or socks5://host:port).
--no-past		Do not download past segments, start with the livestream.
--end-stream-miss-threshold		Number of consecutive timestamps to search before assuming the past stream has ended.
--search-chunk-size		Number of segments to check for existence in a single batch when searching.
--live-end-timeout		Seconds to wait without a new live segment before assuming the stream has ended.
--past-segment-delay		Minimum time in seconds between each past segment download.
--keep-segments		Do not delete the temporary segments directory after finishing.
--ffmpeg-path		Path to the ffmpeg executable.
--ffprobe-path		Path to the ffprobe executable.