Qivaryn

Qivaryn is a high-performance, multi-platform media downloader with a shared command-line interface and Python API. Its platform integrations handle the details that differ between services, while common download options and history management work the same way everywhere.

Features

• Four platforms, one engine: Instagram, TikTok, YouTube and Facebook share the same CLI, filtering, batch limits, resume logic and state database.
• Automatic URL Detection: Pass a URL from any supported platform and Qivaryn routes it to the right downloader.
• Native integrations: Every platform is handled by Qivaryn's own scrapers — no yt-dlp or other downloader dependency.
• High-quality downloads: Platform integrations pick the best available progressive or adaptive stream (up to 1080p where offered) and download carousel slides in original resolution.
• Media Filtering: Filter account downloads by media type where the platform supports it.
• Audio & Video Merging: When a platform provides split video/audio streams (Instagram DASH, YouTube adaptive formats), Qivaryn uses FFmpeg to merge them.
• Batch Limits (--count): Specify the exact number of new items to save. Previously downloaded content is skipped without counting toward the quota.
• Download Resumption: Tracks downloaded items per platform in a local SQLite database (qivaryn_state.db).
• Dual Interface: Offers both a command-line interface (CLI) and a Python library API.

Supported platforms

Run qivaryn platforms to see the available platforms and filters in your installed version.

Requirements

• Python 3.10 or newer
• FFmpeg available on your system PATH when downloading content with split audio/video streams (Instagram DASH, YouTube adaptive formats).
• Authentication is optional but platform-specific. See Authentication.

Installation

Install from PyPI (Recommended)

python -m pip install qivaryn-engine

Install from local checkout (Recommended for development)

git clone https://github.com/usamanadim/qivaryn-engine.git
cd qivaryn-engine
python -m pip install -e .

Install latest development version from GitHub

python -m pip install --upgrade "git+https://github.com/usamanadim/qivaryn-engine.git@main"

Quick Start (Cheatsheet)

# Instagram profile
qivaryn "https://www.instagram.com/USERNAME/"

# TikTok profile
qivaryn "https://www.tiktok.com/@USERNAME"

# YouTube channel
qivaryn "https://www.youtube.com/@CHANNEL/videos"

# Facebook page
qivaryn "https://www.facebook.com/PAGE/videos"

Qivaryn detects the platform from the URL, so --platform is only needed for the explicit subcommands.

Command-Line Usage

1. Automatic URL Command

qivaryn "<SUPPORTED_URL>" [OPTIONS]

Available Options

2. Explicit Subcommands

qivaryn single

Downloads a single item by URL or identifier:

qivaryn single "https://www.instagram.com/p/SHORTCODE/"
qivaryn single "https://www.tiktok.com/@user/video/7300000000000000000"
qivaryn single "https://youtu.be/VIDEO_ID"
qivaryn single "https://www.facebook.com/watch/?v=123456789"

qivaryn download

Downloads account or channel content. Use --platform when the account name is not prefixed by a URL:

# Instagram Reels
qivaryn download natgeo --type reels --count 25

# YouTube Shorts from a channel handle
qivaryn download @somechannel --platform youtube --type shorts --count 10

# TikTok profile feed
qivaryn download someuser --platform tiktok --count 20

# Facebook page videos
qivaryn download somepage --platform facebook

qivaryn platforms

Lists the supported platforms and their media filters:

qivaryn platforms

Media Filtering Guide (--type)

Requesting a filter a platform does not support fails with a clear message rather than silently downloading something else.

Authentication

Cookies are optional and never required to run Qivaryn. Public TikTok, YouTube and Facebook content downloads anonymously; Instagram is the platform that most often needs a session. When you do need cookies, export them with a browser extension such as Get cookies.txt LOCALLY or Cookie-Editor (select Export → Netscape), then:

qivaryn "https://www.instagram.com/USERNAME/" --cookies cookies.txt

If a request is refused, Qivaryn retries anonymous fallbacks first and only then suggests --cookies.

Using --sessionid Directly

For Instagram and TikTok you can pass the sessionid cookie value instead of a cookies file:

qivaryn "https://www.instagram.com/USERNAME/" --sessionid "YOUR_SESSION_ID"

Managing Download History (clear-db)

Download history is stored per platform, so an Instagram shortcode and a TikTok video ID can never collide. clear-db manages history without deleting media files:

# Remove a single item so it can be re-downloaded
qivaryn clear-db SHORTCODE
qivaryn clear-db --item "https://www.instagram.com/p/SHORTCODE/"

# Limit the operation to one platform
qivaryn clear-db --platform youtube --yes

# Prune records for media files that were deleted from disk
qivaryn clear-db --missing

# Clear one platform's history (prompts for confirmation)
qivaryn clear-db --platform tiktok

Databases created by older versions are migrated automatically: existing rows are kept and attributed to Instagram.

File Naming

• Instagram keeps the historical <shortcode>.<ext> layout.
• Other platforms use <platform>_<id>.<ext> so files from different services never overwrite each other.
• Carousels append a slide index: <stem>_1.<ext>, <stem>_2.<ext>, …

Python Library API

from qivaryn import QivarynEngine

engine = QivarynEngine(
    platform="youtube",             # "instagram", "tiktok", "youtube" or "facebook"
    output_dir="./downloads",
    db_path="./qivaryn_state.db",
    cookies_file="./cookies.txt",   # Optional: omit for public content
    consecutive_threshold=3,        # Stop after N consecutive known items
    allow_network_fallbacks=True,   # Retry without the session when it expires
)

# 1. Download automatically from a URL
engine.download_url(
    "https://www.youtube.com/@CHANNEL/videos",
    count=20,
    media_type="videos",
)

# 2. Download account/channel content
engine.download_account(
    "@CHANNEL",
    media_type_filter="shorts",
    count=10,
)

# 3. Download a single item
engine.download_single("https://youtu.be/VIDEO_ID", force=False)

# 4. Playlists (YouTube)
engine.download_playlist("PLxxxxxxxxxxxxxxxx")

InstagramEngine remains available as an alias of QivarynEngine, and the platform clients are importable directly:

from qivaryn import InstagramClient, TikTokClient, YouTubeClient, FacebookClient

See qivaryn/examples/library_usage.py for a complete runnable script.

Platform Limitations

Qivaryn uses native scrapers, so some platform-side restrictions cannot be worked around:

• YouTube: Formats whose URLs are protected by a signatureCipher require executing YouTube's obfuscated JavaScript player. Qivaryn has no JavaScript engine, so a video offering only ciphered formats is reported as unsupported instead of producing a broken file. Some streams also download slower without the n parameter transform. Live streams in progress are not downloadable.
• TikTok: Public posts and profile feeds work without cookies. Profile pagination follows TikTok's public creator feed 15 posts at a time; private accounts and posts hidden from that feed still require --cookies.
• Facebook: Single video and reel URLs work anonymously. Some page video tabs are gated behind a login wall and require --cookies.
• Instagram: Public posts usually work anonymously, but Instagram is the platform most likely to demand a session. Age-gated profiles require an adult (19+) session.

Development & Testing

# Run all unit tests
python -m unittest discover -s tests -v

# Build wheels and source distribution
python -m pip install build
python -m build

License and Required Attribution

Qivaryn is licensed under the Qivaryn Attribution License 1.0 in LICENSE. Commercial use is permitted. Anyone using, modifying, incorporating, or distributing Qivaryn must credit the original author:

Qivaryn by Usama Nadeem (@usamanadim) — https://github.com/usamanadim/qivaryn-engine

Machine-readable attribution metadata is available in qivaryn/ATTRIBUTION.json.