qivaryn-engine 0.1.0__tar.gz

qivaryn_engine-0.1.0/LICENSE

@@ -0,0 +1,95 @@
+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.

qivaryn_engine-0.1.0/PKG-INFO

@@ -0,0 +1,381 @@
+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).