Manim-Captcha

Overview

Animated visual captcha generation library using Manim Framework.

Traditional CAPTCHAs are static images. Manim-Captcha generates animated visual challenges (e.g., moving selectors, distributed numbers, dynamic noise).

This library offers:

• A "Captcha Generator" that allows to request generation of captcha files.
• A "Captcha Automatic Generator" for async operation that acts as a background process to automatically generate captcha files in the filesystem for a custom interval and keeping a maximum number of captchas files (file rotation).
• Some builtin captchas animations that you can select to use.
• Kind of "plugin" based system were you can provide any external custom Manim captcha animation script (scene) and make the library use it.
• Easy way to pass custom properties to the captcha scenes for customization (like scenes).

Table of Contents

• Requirements
• Installation
• Usage
• Library Development

Requirements

The manim-captcha library requires python 3 (tested with v3.12), Manim Community framework, and the corresponding requirements for Manim (like Cairo and Pango libraries).

Installation

Note: The next installation instructions are for Debian based Linux systems.

From a command line, install the different requirements:

sudo apt-get update
sudo apt-get install build-essential make python3 python3-dev python3-pip
sudo apt-get install libcairo2-dev libpango1.0-dev

The library has been published to pypi so can be easily installed via pip:

pip install manim-captcha

Usage

Basic captcha generator:

from manim_captcha.generator import CaptchaGenerator
from manim_captcha.scenes import CaptchaScene
from pathlib import Path

generator = CaptchaGenerator()

captcha = generator.generate(
    code="1234",
    scene=CaptchaScene.CIRCLE_NUMS,
    out_dir=Path("./captchas"),
    properties={
        "theme": "dark",
        "noise": True
    }
)

if captcha.error:
    print("Fail to create the captcha:")
    print(captcha.error_info)
else:
    print("Captcha successfully created")
    print(f"  Code: \"{captcha.code}\"")
    print(f"  File: {captcha.file}")
print("")

Async and non-blocking automatic captcha generator:

import asyncio
import logging
from manim_captcha.auto_generator import CaptchaAutoGenerator
from pathlib import Path

logging.basicConfig(
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    level=logging.INFO
)
logger = logging.getLogger(__name__)

async def main():
    # Setup the CaptchaAutoGenerator
    MAX_NUM_CAPTCHAS = 5
    TIME_GEN_INTERVAL_S = 10
    OUT_DIR = Path("./captchas")
    auto_generator = CaptchaAutoGenerator(
        OUT_DIR, TIME_GEN_INTERVAL_S, MAX_NUM_CAPTCHAS)
    # Start the generator process
    start_success = await auto_generator.start()
    if not start_success:
        logger.error("Fail to Start CaptchaAutoGenerator")
        return
    # Wait and get some captchas during 1 minute
    TIME_CHECK = 60
    time_pass_s = 0
    run = True
    while run:
        # Show number of captchas availables
        num_captchas = auto_generator.num_captchas()
        logger.info("Num Captchas Availables: %d", num_captchas)
        # Try to get a captcha
        captcha = auto_generator.get_captcha()
        if not captcha.error:
            logger.info("Captcha retrieved:")
            logger.info("  Code: \"%s\"", captcha.code)
            logger.info("  File: %s", str(captcha.file))
        await asyncio.sleep(TIME_GEN_INTERVAL_S)
        # Check if check end time has arrive to exit the loop
        time_pass_s = time_pass_s + TIME_GEN_INTERVAL_S
        if time_pass_s >= TIME_CHECK:
            run = False
    # Stop the generator process
    await auto_generator.stop()

if __name__ == '__main__':
    asyncio.run(main())

Note: You can find some extra usages in the examples/ directory.

Library Development

For library development, to ease project setup and installation of all the requirements, a Makefile and some bash scripts are provided for Linux systems based on Debian.

Setup the project (this will install all system requirements and creates a python virtual environment):

make setup

Extra actions can be performed through make, just run make without argments to see the usage help:

make

Usage:
  setup: Setup Project and install requirements
  test: Run project tests
  check_code_style: Run Code Style Checks
  check_static_types: Run Static Types Checks
  install: Install local package in edit mode
  publish: Publish the library to pypi

Now open any code editor (i.e. vscode) withing the python environment and start coding!