Metadata-Version: 2.4
Name: TTCaptchaSolved
Version: 1.0.0
Summary: Solve TikTok CAPTCHAs locally using OpenCV - supports slide, rotate, and 3D shapes captchas
Author: TikTok CAPTCHA Solver
License: MIT
Project-URL: Homepage, https://github.com/yourusername/tiktok-captcha-solver
Project-URL: Documentation, https://github.com/yourusername/tiktok-captcha-solver#readme
Project-URL: Repository, https://github.com/yourusername/tiktok-captcha-solver
Project-URL: Issues, https://github.com/yourusername/tiktok-captcha-solver/issues
Keywords: tiktok,captcha,solver,opencv,slide,puzzle,rotate,whirl,3d,shapes,selenium,playwright,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: numpy>=1.19.0
Requires-Dist: Pillow>=8.0.0
Provides-Extra: selenium
Requires-Dist: selenium>=4.0.0; extra == "selenium"
Provides-Extra: playwright
Requires-Dist: playwright>=1.20.0; extra == "playwright"
Provides-Extra: all
Requires-Dist: selenium>=4.0.0; extra == "all"
Requires-Dist: playwright>=1.20.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Dynamic: license-file
Dynamic: requires-python

# TikTok CAPTCHA Solver 🧩

A Python library for solving TikTok CAPTCHAs using OpenCV.

**Get your API key at: https://captchasolved.com**

Supports:
- ✅ **Slide/Puzzle CAPTCHA** - Slide a piece to fit into a gap
- ✅ **Rotate/Whirl CAPTCHA** - Rotate an image to match the background
- ✅ **3D Shapes CAPTCHA** - Click on matching 3D objects

## Features

- 🚀 **Fast** - Solves CAPTCHAs in milliseconds using optimized OpenCV algorithms
- 🎯 **Accurate** - High accuracy using edge detection and template matching
- 🔌 **Easy Integration** - Works with Selenium, Playwright, or standalone
- 🐍 **Pure Python** - Simple pip install

## Installation

```bash
pip install captchasolved
```

### With Browser Automation Support

```bash
# For Selenium
pip install captchasolved[selenium]

# For Playwright
pip install captchasolved[playwright]

# For both
pip install captchasolved[all]
```

## Quick Start

### 1. Get Your API Key

Sign up at **https://captchasolved.com** to get your API key.

### 2. Set Your API Key

```python
from tiktok_captcha_solver import set_api_key

# Option 1: Set in code
set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

# Option 2: Set via environment variable
# export CAPTCHA_SOLVER_API_KEY="cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### 3. Solve CAPTCHAs

```python
from tiktok_captcha_solver import TikTokCaptchaSolver, set_api_key

set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
solver = TikTokCaptchaSolver()

# Solve slide/puzzle captcha
result = solver.solve_slide(
    background="path/to/background.png",  # or base64, bytes, numpy array
    piece="path/to/piece.png"
)
print(f"Slide distance: {result.x} pixels")
print(f"Confidence: {result.confidence}")

# Solve rotate captcha
result = solver.solve_rotate(
    outer="path/to/outer.png",
    inner="path/to/inner.png"
)
print(f"Rotate angle: {result.angle} degrees")

# Solve 3D shapes captcha
result = solver.solve_shapes(
    image="path/to/shapes.png"
)
print(f"Click points: ({result.x1}, {result.y1}) and ({result.x2}, {result.y2})")
```

### With Selenium

```python
from tiktok_captcha_solver import SeleniumSolver, set_api_key
from selenium import webdriver

set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

driver = webdriver.Chrome()
driver.get("https://www.tiktok.com/login")

solver = SeleniumSolver(driver)
solver.solve_captcha_if_present()
```

### With Playwright (Sync)

```python
from tiktok_captcha_solver import PlaywrightSolver, set_api_key
from playwright.sync_api import sync_playwright

set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = browser.new_page()
    page.goto("https://www.tiktok.com/login")
    
    solver = PlaywrightSolver(page)
    solver.solve_captcha_if_present()
```

### With Playwright (Async)

```python
import asyncio
from tiktok_captcha_solver import AsyncPlaywrightSolver, set_api_key
from playwright.async_api import async_playwright

set_api_key("cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=False)
        page = await browser.new_page()
        await page.goto("https://www.tiktok.com/login")
        
        solver = AsyncPlaywrightSolver(page)
        await solver.solve_captcha_if_present()

asyncio.run(main())
```

## Pricing

| Plan | Solves | Price |
|------|--------|-------|
| Starter | 1,000 | $9 |
| Pro | 10,000 | $49 |
| Enterprise | 100,000 | $299 |

Get your API key at: **https://captchasolved.com**

## Check Your Usage

```python
from tiktok_captcha_solver import get_usage_info

info = get_usage_info()
print(f"Plan: {info['plan']}")
print(f"Remaining: {info['remaining_solves']} solves")
```

## API Reference

### TikTokCaptchaSolver

Main solver class that combines all CAPTCHA types.

```python
solver = TikTokCaptchaSolver()
```

#### Methods

##### `solve_slide(background, piece, piece_start_x=0) -> SlideResult`

Solve a slide/puzzle CAPTCHA.

**Parameters:**
- `background`: Background image (path, base64, bytes, numpy array, or PIL Image)
- `piece`: Puzzle piece image
- `piece_start_x`: Starting X position of the piece (default: 0)

**Returns:** `SlideResult` with:
- `x`: X position/slide distance
- `y`: Y position
- `confidence`: Match confidence (0-1)

##### `solve_rotate(outer, inner) -> RotateResult`

Solve a rotate/whirl CAPTCHA.

**Parameters:**
- `outer`: Outer/background image
- `inner`: Inner image to rotate

**Returns:** `RotateResult` with:
- `angle`: Degrees to rotate
- `confidence`: Match confidence (0-1)

##### `solve_shapes(image) -> ShapesResult`

Solve a 3D shapes matching CAPTCHA.

**Parameters:**
- `image`: CAPTCHA image with shapes

**Returns:** `ShapesResult` with:
- `x1, y1`: First click point
- `x2, y2`: Second click point
- `confidence`: Match confidence (0-1)

### SeleniumSolver

Selenium integration with automatic CAPTCHA detection.

```python
solver = SeleniumSolver(
    driver,              # Selenium WebDriver instance
    max_retries=3,       # Max retry attempts
    retry_delay=1.0,     # Delay between retries
    callback=None        # Optional callback(event, data)
)
```

#### Methods

- `solve_captcha_if_present()`: Detect and solve any CAPTCHA
- `solve_slide_captcha()`: Solve slide CAPTCHA
- `solve_rotate_captcha()`: Solve rotate CAPTCHA
- `solve_shapes_captcha()`: Solve shapes CAPTCHA
- `detect_captcha_type()`: Returns 'slide', 'rotate', 'shapes', or None

### PlaywrightSolver / AsyncPlaywrightSolver

Playwright integration (sync and async versions).

```python
# Sync
solver = PlaywrightSolver(page, max_retries=3, retry_delay=1.0, callback=None)

# Async
solver = AsyncPlaywrightSolver(page, max_retries=3, retry_delay=1.0, callback=None)
```

Same methods as SeleniumSolver (async versions return coroutines).

## Advanced Usage

### Using Individual Solvers

```python
from tiktok_captcha_solver import SlideSolver, RotateSolver, ShapesSolver

# Slide solver with custom settings
slide_solver = SlideSolver(use_edge_detection=True)
result = slide_solver.solve(background, piece)

# Get position as ratio (useful for different screen sizes)
x_ratio, y_ratio = slide_solver.solve_with_ratio(background, piece)

# Rotate solver with custom angle steps
rotate_solver = RotateSolver(angle_step=1.0, refine_step=0.1)
result = rotate_solver.solve(outer, inner)

# Get as drag distance for a slider
distance = rotate_solver.solve_as_distance(outer, inner, slider_width=348)
```

### Callback Events

```python
def on_event(event, data):
    print(f"Event: {event}, Data: {data}")

solver = SeleniumSolver(driver, callback=on_event)
solver.solve_captcha_if_present()

# Events:
# - 'solving': Starting to solve (data = captcha type)
# - 'solved': Solution found (data = result)
# - 'attempt': Retry attempt (data = attempt number)
# - 'success': Successfully solved
# - 'failed': Failed to solve
# - 'error': Error occurred (data = error message)
```

### Loading Images

The solver accepts multiple image formats:

```python
# File path
result = solver.solve_slide("background.png", "piece.png")

# Base64 string
result = solver.solve_slide(base64_bg, base64_piece)

# Bytes
result = solver.solve_slide(image_bytes_bg, image_bytes_piece)

# NumPy array (OpenCV format)
import cv2
bg = cv2.imread("background.png")
result = solver.solve_slide(bg, piece_array)

# PIL Image
from PIL import Image
bg = Image.open("background.png")
result = solver.solve_slide(bg, piece_image)
```

## How It Works

### Slide/Puzzle CAPTCHA

1. Load background and puzzle piece images
2. Remove whitespace/transparent borders from piece
3. Apply Canny edge detection to both images
4. Use OpenCV template matching (`cv2.matchTemplate`)
5. Find the position with highest correlation score

### Rotate/Whirl CAPTCHA

1. Load outer and inner images
2. Rotate inner image through 0-360 degrees
3. Calculate similarity between rotated inner and outer
4. Find angle with highest similarity
5. Refine with smaller angle steps

### 3D Shapes CAPTCHA

1. Load the CAPTCHA image
2. Detect shape regions using contour detection
3. Extract features using ORB detector
4. Compare all pairs of shapes using feature matching
5. Return the centers of the best matching pair

## Requirements

- Python 3.8+
- OpenCV (opencv-python)
- NumPy
- Pillow

Optional:
- Selenium (for browser automation)
- Playwright (for browser automation)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) file.

## Disclaimer

This library is for educational purposes only. Please ensure you comply with TikTok's Terms of Service when using this library. The authors are not responsible for any misuse of this software.
