Metadata-Version: 2.4
Name: unofficial-api-for-xfreehd
Version: 1.6
Summary: An asynchronous Python API wrapper and scraper for xfreehd.com
Keywords: api,scraper,async,asyncio,video-downloader,selectolax,curl-cffi,xfreehd
Author: Johannes Habel
Author-email: Johannes Habel <EchterAlsFake@proton.me>
License-Expression: AGPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Video
Requires-Dist: selectolax
Requires-Dist: eaf-base-api
Requires-Python: >=3.12
Project-URL: Documentation, https://docs.echteralsfake.me/xfreehd
Project-URL: Repository, https://github.com/EchterAlsFake/unofficial-api-for-xfreehd
Project-URL: Bug Tracker, https://github.com/EchterAlsFake/unofficial-api-for-xfreehd/issues
Project-URL: Support me on Ko-Fi, https://ko-fi.com/EchterAlsFake
Project-URL: Donate via PayPal, https://paypal.me/EchterAlsFake
Project-URL: Donate via Crypto, https://nowpayments.io/donation/EchterAlsFake
Description-Content-Type: text/markdown

<h1 align="center">XFreeHD API</h1>
<p align="center"><em>An asynchronous Python API wrapper and scraper for xfreehd.com</em></p>

<div align="center">
    <a href="https://pepy.tech/project/xfreehd_api"><img src="https://static.pepy.tech/badge/xfreehd_api" alt="Downloads"></a> +
    <a href="https://pepy.tech/project/unofficial-api-for-xfreehd"><img src="https://static.pepy.tech/badge/unofficial-api-for-xfreehd" alt="Downloads"></a>
    <a href="https://github.com/EchterAlsFake/xfreehd_api/workflows/"><img src="https://github.com/EchterAlsFake/xfreehd_api/workflows/CodeQL/badge.svg" alt="CodeQL Analysis"/></a>
    <a href="https://echteralsfake.me/ci/unofficial-api-for-xfreehd/badge.svg"><img src="https://echteralsfake.me/ci/unofficial-api-for-xfreehd/badge.svg" alt="Sync API Tests"/></a>
    </div>

# Disclaimer
> [!IMPORTANT]
> This is an unofficial and unaffiliated project. Please read the full disclaimer before use:
> **[DISCLAIMER.md](https://github.com/EchterAlsFake/API_Docs/blob/master/Disclaimer.md)**
>
> By using this project you agree to comply with the target site's rules, copyright/licensing requirements,
> and applicable laws. Do not use it to bypass access controls or scrape at disruptive rates.

---

# Features

| Category | Details |
|---|---|
| **Video Fetching** | Fetch video objects with metadata scraped directly from HTML |
| **Video Downloading** | RAW/direct-based downloading with quality selection |
| **Album Scraper** | Fetch album details and scrape/download images page-by-page or all at once |
| **Video Search** | Search videos by query with support for pagination |
| **Async-First** | Fully asynchronous (`async` / `await`) built on top of `asyncio` |
| **Built-in Caching** | Automatic response caching with configurable limits to reduce redundant network requests |
| **Type Safety** | Comprehensive type hinting and `dataclass`-based models throughout |

#### Networking Features

The networking layer is provided by the [`eaf_base_api`](https://github.com/EchterAlsFake/eaf_base_api) package and is fully configurable through `RuntimeConfig`:

| Feature | Description |
|---|---|
| **HTTP/1.1, HTTP/2, HTTP/3** | Configurable HTTP version (`v1`, `v2`, `v3` — defaults to HTTP/3) |
| **Browser Impersonation** | Built-in browser fingerprint impersonation via `curl_cffi` (defaults to Chrome) |
| **Custom JA3 Fingerprint** | Override the TLS fingerprint with a custom JA3 string for advanced use cases |
| **Proxy Support** | All proxy types supported (HTTP, HTTPS, SOCKS4, SOCKS5) |
| **Proxy Authentication** | Username/password authentication for proxies |
| **Bandwidth Limiting** | Set a maximum download speed in MB/s (e.g., `2.0`, `3.5`) |
| **DNS over HTTPS** | Route DNS queries over HTTPS for privacy and bypassing DNS-level blocks |
| **SSL Verification** | Toggle SSL certificate verification on or off |
| **Request Delay** | Configurable delay between requests to respect rate limits |
| **Concurrency Control** | Tune video and page concurrency independently for optimal throughput |

---

# Supported Platforms
This API has been tested and confirmed working on:

- Windows 11 (x64) 
- macOS Sequoia (x86_64)
- Linux (Arch) (x86_64)
- Android 16 (aarch64)

---

# Installation
```bash
pip install unofficial-api-for-xfreehd
```

---

# Quickstart

### Have a look at the [Documentation](https://docs.echteralsfake.me/xfreehd) for more details

```python
import asyncio
from xfreehd_api import Client, DownloadConfigRAW

async def main():
    # Initialize a Client object
    client = Client()
    
    # Fetch a video
    video_object = await client.get_video("<insert_url_here>")
    
    # Information from Video objects
    print(video_object.title)

    # Download the video
    config = DownloadConfigRAW(quality="best", path="./") # More options in the documentation
    await video_object.download(config)

if __name__ == "__main__":
    asyncio.run(main())
```

---

# Support the Project ❤️

I develop all my projects entirely for free because I enjoy it and want to keep them accessible.
If you find my work useful, please consider supporting me with a small donation — even 1 € makes a big difference and keeps me motivated!

### ☕ Ko-fi
<a href="https://ko-fi.com/EchterAlsFake">https://ko-fi.com/EchterAlsFake</a>

### 💳 PayPal
<a href="https://paypal.me/EchterAlsFake">https://paypal.me/EchterAlsFake</a>

### 🪙 Crypto (350+ currencies supported)
<a href="https://nowpayments.io/donation?api_key=65b1acaf-735d-4d4b-b3d6-c2237c0b57e3" target="_blank" rel="noreferrer noopener">
   <img src="https://nowpayments.io/images/embeds/donation-button-black.svg" alt="Crypto donation button by NOWPayments">
</a>

---

# Contribution
Do you see any issues or having some feature requests? Simply open an Issue or talk
in the discussions.

Pull requests are also welcome.

# License
This API is licensed under the AGPLv3. See the `LICENSE` file for details.

> [!CAUTION]
> **Using this in a proprietary application?**
> Under the AGPLv3, if you integrate, modify, or host this API as part of your application (even over a network), you must open-source your entire application's code under the AGPL. 
>
> If you want to use this API without open-sourcing your own code, you must purchase a commercial license.
> 
> **For commercial licensing, contact:** EchterAlsFakeBS@proton.me
