Metadata-Version: 2.4
Name: qivaryn-engine
Version: 0.1.0
Summary: A media download engine designed for multiple platforms, currently supporting Instagram.
Author: Usama Nadeem (@usamanadim)
License: QIVARYN ATTRIBUTION LICENSE
        Version 1.0, 2026-10-17
        
        Copyright (c) 2026 Usama Nadeem (@usamanadim)
        
        IMPORTANT: This is a project-specific source-available license, not a standard
        open-source license. It permits commercial use, but requires attribution as
        described below. By exercising any of the rights granted by this license, you
        agree to its terms.
        
        1. DEFINITIONS
        
        "Work" means the Qivaryn software, including its source code and documentation,
        made available by the copyright holder under this license.
        
        "You" means the person or legal entity exercising rights under this license.
        
        "Derivative Work" means a work based on or incorporating all or a substantial
        portion of the Work, including modifications, adaptations, and applications
        that bundle or incorporate the Work.
        
        2. GRANT OF RIGHTS
        
        Subject to the conditions in this license, the copyright holder grants You a
        worldwide, non-exclusive, royalty-free, perpetual, and irrevocable license to
        use, reproduce, modify, create Derivative Works from, publicly display,
        distribute, sublicense, and commercially exploit the Work and Derivative Works.
        
        Commercial use is expressly permitted. No separate fee or permission is
        required if You comply with this license.
        
        3. ATTRIBUTION CONDITION
        
        Whenever You exercise the rights in section 2 to use, reproduce, modify, or
        create a Derivative Work, You must preserve this license and the attribution
        record with the Work and any modified source copy. If You incorporate or use
        the Work in an application, or distribute the Work or a Derivative Work, You
        must also give clear and reasonably prominent credit to both Qivaryn and its
        original author, Usama Nadeem (@usamanadim), and include a link to the
        original project repository:
        
            Qivaryn by Usama Nadeem (@usamanadim)
            https://github.com/usamanadim/qivaryn-engine
        
        For an application, place this credit in an About, credits, acknowledgments,
        or third-party notices screen or document. If the application has no such
        screen or documentation, include it in a third-party notices file distributed
        with the application. For source or binary redistribution, retain this license
        and the attribution record, and preserve existing copyright and license
        notices. You may add your own notices, but may not imply that the original
        author endorses Your work.
        
        These conditions also apply to modifications and Derivative Works. They do
        not require You to publish your source code or license Your own independent
        contributions under this license.
        
        4. AI-ASSISTED DEVELOPMENT
        
        If an AI coding agent uses or incorporates the Work to develop another
        application or Derivative Work, the person or organization distributing or
        using that application remains responsible for complying with this license.
        The agent must preserve and communicate the attribution requirement and should
        add the credit above to the application's appropriate documentation, license
        notices, About/credits screen, or third-party acknowledgments. AI-generated
        changes do not remove these obligations.
        
        5. NO TRADEMARK OR ENDORSEMENT RIGHTS
        
        This license does not grant rights to use the Qivaryn name, logos, or other
        trademarks except as reasonably needed to provide the required attribution.
        Attribution does not imply endorsement.
        
        6. DISCLAIMER AND LIMITATION OF LIABILITY
        
        THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. TO THE MAXIMUM EXTENT
        PERMITTED BY APPLICABLE LAW, THE COPYRIGHT HOLDER SHALL NOT BE LIABLE FOR ANY
        CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT,
        OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE WORK OR THE USE
        OR OTHER DEALINGS IN THE WORK.
        
        7. TERMINATION
        
        If You fail to comply with the attribution condition, the rights granted to
        You terminate. They will be reinstated if You cure the violation within 30
        days after becoming aware of it, and will not otherwise be permanently
        terminated for that cured violation. All other termination rights available
        under applicable law remain unaffected.
        
        8. GOVERNING LAW
        
        This license is governed by the laws applicable to the copyright holder,
        without regard to conflict-of-law rules. If any provision is unenforceable,
        the remaining provisions continue in effect.
        
Project-URL: Homepage, https://github.com/usamanadim/qivaryn-engine
Project-URL: Repository, https://github.com/usamanadim/qivaryn-engine
Project-URL: Issues, https://github.com/usamanadim/qivaryn-engine/issues
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: click>=8.0.0
Requires-Dist: tqdm>=4.64.0
Dynamic: license-file

# 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 wherever supported. Instagram is the first supported platform; support for additional platforms is planned.

---

## Features

- **Multi-platform design**: A shared downloader interface is built to support multiple media platforms through platform-specific integrations.
- **Automatic URL Detection**: Pass a URL from a supported platform and Qivaryn routes it to the appropriate downloader.
- **High-quality downloads**: The current Instagram integration selects available progressive or DASH video streams (up to 1080p) and downloads carousel slides in original resolution.
- **Media Filtering**: Filter account downloads by media type where the platform supports it. Available types can vary by platform.
- **DASH Audio & Video Merging**: On platforms that provide split DASH streams, Qivaryn uses FFmpeg to merge audio and video.
- **Batch Limits (`--count`)**: Specify the exact number of **new** items to save. Previously downloaded content is automatically skipped without counting toward the quota.
- **Download Resumption**: Tracks downloaded item identifiers in a local SQLite database (`qivaryn_state.db`), allowing previously saved items to be skipped. The current Instagram integration tracks post shortcodes.
- **Dual Interface**: Offers both a command-line interface (CLI) and a Python library API.

### Supported platforms

- **Instagram** — currently supported.
- **Additional platforms** — planned; not supported yet.

Commands and common options are intended to remain consistent across platforms. URL formats, authentication methods, media filters, and other service-specific options may differ.

---

## Requirements

- **Python 3.8** or newer
- **FFmpeg** available on your system `PATH` when downloading from a platform that requires it to merge DASH audio and video.
- Authentication is platform-specific. For Instagram, an optional session (`--cookies cookies.txt` or `--sessionid`) may be needed for private content, deeper pagination, or higher rate limits.

---

## Installation

### Install from local checkout (Recommended for development)

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

### Install latest development version from GitHub

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

---

## Quick Start (Cheatsheet)

Download content from a supported platform with one command. This example uses Instagram, the platform currently supported:

```bash
qivaryn "https://www.instagram.com/USERNAME/"
```

---

## Command-Line Usage

### 1. Automatic URL Command

Pass a URL from a supported platform directly to the CLI. Qivaryn detects the platform and content type from the URL:

```console
qivaryn "<SUPPORTED_URL>" [OPTIONS]
```

For the currently supported Instagram URLs, Qivaryn routes automatically:

- **Single Post / Reel URL** (`/p/SHORTCODE/` or `/reel/SHORTCODE/`):
  Downloads that specific item. If it is a carousel, all slides (images and videos) are downloaded.
- **Reels Tab URL** (`/<username>/reels/`):
  Scans the dedicated Reels tab and downloads Reels chronologically.
- **Account Profile URL** (`/<username>/`):
  - When `--type` is omitted or `all`: downloads grid posts (photos and carousels) and continues into the dedicated Reels tab.
  - When `--type posts`: downloads photos and carousels from the profile grid.
  - When `--type carousels`: downloads only multi-slide carousel albums.
  - When `--type reels`: downloads videos from the Reels tab.

#### Available Options

| Option | Shorthand | Description | Default |
| --- | --- | --- | --- |
| `--type TYPE` | | Filter media where supported. Instagram types include `all`, `posts`, `reels`, `videos`, or `carousels`. | `all` |
| `--count N` | `-n N`, `--limit N` | Maximum number of **new** items to save before stopping. | Unlimited |
| `--cookies PATH` | `--cookies-file` | Instagram: path to a Netscape-format `cookies.txt` file. Authentication options may vary by platform. | None |
| `--sessionid STR` | | Instagram-specific `sessionid` cookie value. | None |
| `--output DIR` | `-o DIR` | Directory to save downloaded media files. | `./downloads` |
| `--db PATH` | | Path to SQLite state database for download tracking. | `qivaryn_state.db` |
| `--max-pages N` | | Maximum feed pagination pages to scan. | Unlimited |
| `--force` | `-f` | Re-download and overwrite even if already saved. | `False` |

The explicit `single`, `download`, and `clear-db` subcommands also accept `--platform`. At present, the available platform choice is `instagram`.

---

### 2. Explicit Subcommands

If you prefer explicit subcommands instead of automatic URL detection:

#### `qivaryn single`

Downloads a single item by URL or identifier. The accepted identifier depends on the selected platform. For Instagram:

```console
qivaryn single "https://www.instagram.com/p/SHORTCODE/"
qivaryn single "https://www.instagram.com/p/SHORTCODE/" --output ./my_media
qivaryn single SHORTCODE --cookies ./cookies.txt
```

#### `qivaryn download`

Downloads account content using a platform-specific account name or identifier. For Instagram:

```console
# Download up to 25 new Reels from an account
qivaryn download natgeo --type reels --count 25

# Download up to 10 image / carousel posts
qivaryn download natgeo --type posts --count 10

# Download only multi-item carousel albums
qivaryn download natgeo --type carousels --count 5

# Download with an explicit early-exit threshold (halt after 5 consecutive known items)
qivaryn download natgeo --threshold 5
```

---

## Media Filtering Guide (`--type`)

Media type names are platform-specific. The following values describe the current Instagram integration; available content and filters may differ for other platform integrations in the future.

| Value | What It Downloads | Excludes |
| --- | --- | --- |
| `all` *(default)* | All posts, photos, carousels, and Reels. | None |
| `posts` | Profile grid image posts and multi-item carousels. | Standalone video Reels |
| `carousels` | Multi-slide carousel albums only (multi-image / multi-video). | Single-photo posts and Reels |
| `reels` (or `videos`) | Video Reels from the dedicated Reels tab or feed. | Static image posts |

---

## Instagram Authentication (`cookies.txt` and `--sessionid`)

Authentication requirements depend on the platform. For Instagram, public accounts and Reels can often be downloaded without logging in. An authenticated session may be needed for:

- Private accounts you follow.
- Deep pagination of account post grids.
- Avoiding Instagram rate limits (HTTP 429).

### How to Export `cookies.txt` from Your Browser

1. In Google Chrome, Microsoft Edge, or Firefox, install a cookie export extension:
   - **Get cookies.txt LOCALLY** (recommended, open source)
   - **Cookie-Editor** (select *Export* → *Netscape*)
2. Navigate to [instagram.com](https://www.instagram.com) and ensure you are logged into your account.
3. Click the extension icon and export the cookies in **Netscape format**.
4. Save the file as `cookies.txt` in your project folder (or pass its absolute path):
   ```console
   qivaryn "https://www.instagram.com/USERNAME/" --cookies cookies.txt
   ```

### Using `--sessionid` Directly

Alternatively, copy your `sessionid` cookie value directly from your browser:

1. Open [instagram.com](https://www.instagram.com) in your browser.
2. Press `F12` to open Developer Tools.
3. Go to **Application** (or **Storage** in Firefox) → **Cookies** → `https://www.instagram.com`.
4. Copy the value of the `sessionid` cookie and pass it:
   ```console
   qivaryn "https://www.instagram.com/USERNAME/" --sessionid "YOUR_SESSION_ID"
   ```

> [!IMPORTANT]
> Treat `cookies.txt` and session IDs like passwords. Do not commit them to Git. Qivaryn's `.gitignore` automatically ignores `cookies.txt`.

---

## Managing Download History (`clear-db`)

Qivaryn records downloaded item identifiers in `qivaryn_state.db` so you can skip previously saved files. For Instagram, these identifiers are post shortcodes. The `clear-db` command manages download history without deleting media files from disk:

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

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

# Clear the entire download history (prompts for confirmation)
qivaryn clear-db

# Clear the entire history without a confirmation prompt
qivaryn clear-db --yes
```

---

## Python Library API

You can embed Qivaryn into your own Python applications, automation scripts, and background workers. The example below uses the current Instagram integration; available methods and options may vary by platform:

```python
from qivaryn import QivarynEngine

# Initialize the engine
engine = QivarynEngine(
    output_dir="./downloads",
    db_path="./qivaryn_state.db",
    cookies_file="./cookies.txt",  # Optional: omit for public content
    # sessionid="YOUR_SESSION_ID", # Alternative to cookies_file
    consecutive_threshold=3,       # Stop after N consecutive known items
)

# 1. Download automatically based on URL with count limit and media type filter
engine.download_url(
    "https://www.instagram.com/natgeo/",
    count=20,
    media_type="posts",  # 'all', 'posts', 'reels', 'videos', or 'carousels'
)

# 2. Download from an account by username
engine.download_account(
    username="natgeo",
    count=10,
    media_type_filter="carousels",
)

# 3. Download a single post or Reel
engine.download_single(
    "https://www.instagram.com/reel/C7xYabcdefG/",
    force=False,
)
```

See [`qivaryn/examples/library_usage.py`](qivaryn/examples/library_usage.py) for a complete runnable script.

---

## Development & Testing

Activate your virtual environment and install test dependencies:

```console
# 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`](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`](qivaryn/ATTRIBUTION.json).
