modotte-python

A universal Python package for accessing and using all AI models trained by Modotte.

Installation

Install from PyPI

Install the latest stable version directly from PyPI:

pip install modotte

Then import Modotte in your Python project:

from modotte import Audio, Image

Upgrade to the latest version

pip install --upgrade modotte

---

Install from GitHub

You can also install the latest development version directly from GitHub:

pip install git+https://github.com/Modotte/modotte-python.git

Clone the repository

If you want to develop or modify Modotte locally:

git clone https://github.com/Modotte/modotte-python.git
cd modotte-python

---

Project Structure

modotte-python/
├── 📄 .gitignore
├── 📄 LICENSE
├── 📄 README.md
├── 📄 pyproject.toml
└── 📁 src/
    └── 📁 modotte/
        ├── 📄 AIRealNet.py
        ├── 📄 __init__.py
        ├── 📄 _common.py        ← internal
        ├── 📄 _formats.py       ← internal
        ├── 📄 audio.py          ← public API
        └── 📄 image.py          ← public API

Hugging Face Token (Optional, Recommended)

The models are downloaded from the Hugging Face Hub on first use.

Without a token, you may see:

Warning: You are sending unauthenticated requests to the HF Hub

Unauthenticated requests are subject to lower rate limits. A free Hugging Face token can provide higher rate limits and more reliable downloads.

Create a token from:

https://huggingface.co/settings/tokens

There are three ways to provide it.

1. Pass the token directly

from modotte import Audio, Image

detector = Audio(hf_token="hf_xxxxxxxxxxxxxxxx")
detector = Image(hf_token="hf_xxxxxxxxxxxxxxxx")

2. Set the HF_TOKEN environment variable

Windows PowerShell — current session

$env:HF_TOKEN = "hf_xxxxxxxxxxxxxxxx"

Windows — permanent

setx HF_TOKEN "hf_xxxxxxxxxxxxxxxx"

Open a new terminal after running setx.

macOS / Linux

export HF_TOKEN="hf_xxxxxxxxxxxxxxxx"

3. Log in using the Hugging Face CLI

hf auth login

An explicit hf_token= argument takes priority over the HF_TOKEN environment variable.

The token is only used for downloading models. Modotte does not store or print your token.

Models are downloaded once and subsequently loaded from the local cache.

---

Audio Classification

Import the audio detector:

from modotte import Audio

detector = Audio()

On first use, Modotte checks for the model locally and downloads it if necessary.

You can optionally provide a Hugging Face token:

detector = Audio(hf_token="hf_xxxxxxxxxxxxxxxx")

Detect Bonafide / Real Audio

result = detector.predict("bonafide.wav", threshold=0.5)

print(result["label"])
print(result["confidence"])

Detect Spoof / AI-Generated Audio

result = detector.predict("spoof.wav", threshold=0.5)

print(result["label"])
print(result["confidence"])

The threshold parameter must be a float between 0.0 and 1.0, inclusive.

Invalid types such as integers, strings, or booleans raise TypeError.

Values outside the range 0.0–1.0 raise ValueError.

---

Image Classification

Import the image detector:

from modotte import Image

detector = Image()

On first use, Modotte checks for the model locally and downloads it if necessary.

You can optionally provide a Hugging Face token:

detector = Image(hf_token="hf_xxxxxxxxxxxxxxxx")

Run a prediction:

result = detector.predict("cat.jpg")

print(result["label"])
print(result["confidence"])
print(result["scores"])

Example:

{
    "label": "real",
    "confidence": 0.94,
    "scores": {
        "artificial": 0.06,
        "real": 0.94
    }
}

Modotte/AIRealNet is a binary SwinV2 Tiny classifier:

• Class 0: AI-generated
• Class 1: Real human image

Both import styles are supported:

from modotte import Audio, Image

and:

from modotte.AIRealNet import Audio, Image

---

Supported file types

• Audio: MP3, WAV, AAC, FLAC, OGG, Opus, M4A, AIFF
• Image: JPG, JPEG, PNG, WebP, GIF, SVG, BMP, TIFF, AVIF, HEIC, HEIF

Other extensions raise ValueError. WAV/FLAC/OGG/Opus/AIFF/MP3 are decoded with soundfile; AAC and M4A (and any file soundfile can't read) fall back to PyAV, which bundles ffmpeg. HEIC/HEIF/AVIF need pillow-heif, and SVG needs cairosvg (which requires the Cairo library on some systems). GIF and multi-page TIFF use the first frame; transparent images are composited on white.

Models load on CUDA when available, otherwise CPU.

---

Quick Start

After installing Modotte:

pip install modotte

You can immediately use the supported models:

from modotte import Audio, Image

audio_detector = Audio()
image_detector = Image()

audio_result = audio_detector.predict("audio.wav")
image_result = image_detector.predict("image.jpg")

print(audio_result)
print(image_result)

---

Development

Clone the repository:

git clone https://github.com/Modotte/modotte-python.git
cd modotte-python

Create a virtual environment:

python -m venv .venv

Activate it and install the package in editable mode:

pip install -e .

After making changes to the source code, the changes will be available immediately in your environment.

---

Authors

• Sujal Rajpoot — GitHub
• Parvesh Rawal — GitHub

---

License

See the LICENSE file for licensing information.