{"id":32470644,"url":"https://github.com/marvin3dp/betlo","last_synced_at":"2026-05-13T23:35:04.628Z","repository":{"id":320516047,"uuid":"1081423340","full_name":"marvin3dp/betlo","owner":"marvin3dp","description":"🤖 Automation bot with intelligent OCR \u0026 modern terminal UI. Multi-service support, headless mode, \u0026 human-like behavior.","archived":false,"fork":false,"pushed_at":"2025-10-24T06:53:58.000Z","size":184,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-24T08:39:17.123Z","etag":null,"topics":["automation","ocr","python","selenium","tesseract"],"latest_commit_sha":null,"homepage":"https://github.com/marvin3dp/betlo","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marvin3dp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-22T19:04:58.000Z","updated_at":"2025-10-24T06:54:01.000Z","dependencies_parsed_at":"2025-10-24T08:39:19.328Z","dependency_job_id":null,"html_url":"https://github.com/marvin3dp/betlo","commit_stats":null,"previous_names":["marvin3dp/betlo"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/marvin3dp/betlo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marvin3dp%2Fbetlo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marvin3dp%2Fbetlo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marvin3dp%2Fbetlo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marvin3dp%2Fbetlo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marvin3dp","download_url":"https://codeload.github.com/marvin3dp/betlo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marvin3dp%2Fbetlo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281132809,"owners_count":26449082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-26T02:00:06.575Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","ocr","python","selenium","tesseract"],"created_at":"2025-10-26T16:19:18.751Z","updated_at":"2026-05-13T23:35:04.614Z","avatar_url":"https://github.com/marvin3dp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/logo.png\" alt=\"TikTok Bot Logo\" width=\"400\"\u003e\n\n\u003cbr\u003e\u003cbr\u003e\n\n### 🚀 Advanced TikTok Services Automation\n\n**Powerful bot with intelligent OCR captcha solver and modern terminal UI**\n\n[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)](https://github.com)\n[![Status](https://img.shields.io/badge/status-active-success.svg)](https://github.com)\n[![OCR](https://img.shields.io/badge/OCR-Tesseract-orange.svg)](https://github.com/tesseract-ocr/tesseract)\n![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/marvin3dp/betlo?utm_source=oss\u0026utm_medium=github\u0026utm_campaign=marvin3dp%2Fbetlo\u0026labelColor=171717\u0026color=FF570A\u0026link=https%3A%2F%2Fcoderabbit.ai\u0026label=CodeRabbit+Reviews)\n\n[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) •\n[Configuration](#-configuration) • [Documentation](#-documentation) •\n[FAQ](#-faq)\n\n---\n\n\u003c/div\u003e\n\n## 📋 Table of Contents\n\n- [✨ Features](#-features)\n- [🎯 Supported Services](#-supported-services)\n- [📸 Screenshots](#-screenshots)\n- [🚀 Installation](#-installation)\n- [💡 Usage](#-usage)\n- [⚙️ Configuration](#-configuration)\n- [🤖 OCR Captcha Solver](#-ocr-captcha-solver)\n- [📊 Performance](#-performance)\n- [📚 Documentation](#-documentation)\n- [🐛 Troubleshooting](#-troubleshooting)\n- [❓ FAQ](#-faq)\n- [🤝 Contributing](#-contributing)\n- [⚠️ Disclaimer](#️-disclaimer)\n- [📜 License](#-license)\n\n---\n\n## ✨ Features\n\n### 🤖 **Intelligent OCR Captcha Solver**\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n**FAST Mode** ⚡\n\n- 5 preprocessing methods\n- 5 OCR configurations\n- ~30 attempts per captcha\n- Processing time: **10-20 seconds**\n- 2 OCR retries before manual\n- **Recommended for most users**\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n**AGGRESSIVE Mode** 🐌\n\n- Up to 12 preprocessing methods\n- Up to 26 OCR configurations\n- 300+ attempts per captcha\n- Processing time: **3-5 minutes**\n- 5 OCR retries before manual\n- For difficult captchas\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n**Advanced Capabilities:**\n\n- 🔍 **Horizontal Reading** - Left→Right like humans\n- 🎯 **Uneven Text Handling** - Handles overlapping \u0026 naik-turun text\n- 📊 **Frequency-based Confidence Scoring** - Selects most reliable result\n- 🐛 **Debug Mode** - Save all preprocessing steps for analysis\n- 🖼️ **Auto-Open Captcha** - Perfect for headless mode\n- ☁️ **Cloud Upload** - Upload captcha to uploader.sh for easy VPS access\n- 🔄 **Manual Input Fallback** - Never gets stuck\n\n### 🎨 **Modern Terminal UI**\n\n- ✨ Beautiful rounded panels with Rich library\n- 🎯 Interactive menus with questionary\n- 📊 Real-time statistics display\n- ⏱️ User-friendly uptime format (e.g., `4m 16s`)\n- 🎨 Colorful logs with emoji support\n- 📈 Progress bars and countdown timers\n- 🖥️ Clean, centered messages\n\n### 🛡️ **Advanced Bot Features**\n\n- 🔄 **Intelligent Cooldown System** - 6 fallback points prevent rate limiting\n- 🎯 **Target Goals \u0026 Progress Tracking** - Set targets and track automatically\n- 🌐 **Headless Mode Support** - Run in background with auto-open captcha\n- 🎭 **Stealth Mode** - Advanced techniques to hide headless/automation\n- 🖥️ **VPS Auto-Detection** - Auto-enable headless on servers (no display)\n- 🚫 **Advanced AdBlock** - DNS-based + Request interception\n- 🤖 **Human-like Behavior** - Random delays, typing simulation\n- 💾 **Session Persistence** - Continue where you left off\n- 🧹 **Auto Cleanup** - Chrome zombie process killer\n- 📝 **Comprehensive Logging** - MAIN/DEBUG/INFO levels\n\n### 🎯 **Service Management**\n\n- ✅ Enable/disable services individually\n- 🎯 Active service marker (visual indicator)\n- 📊 Live service status from Zefoy\n- 🔄 Auto-retry on cooldown\n- 📈 Real-time progress tracking\n- 🎯 Three execution modes:\n  - Manual Executions\n  - Target Amount\n  - Goal Mode (continuous)\n\n---\n\n## 🎯 Supported Services\n\n| Service                | Status     | Rate Limit | Notes          |\n| ---------------------- | ---------- | ---------- | -------------- |\n| ❤️ **Hearts**          | ✅ Active  | ~25/exec   | Most reliable  |\n| 👁️ **Views**           | ✅ Active  | ~500/exec  | High volume    |\n| 🔄 **Shares**          | ✅ Active  | ~50/exec   | Fast cooldown  |\n| ⭐ **Favorites**       | ✅ Active  | ~100/exec  | Stable         |\n| 💬 **Comments Hearts** | ✅ Active  | ~25/exec   | Moderate       |\n| 👥 **Followers**       | ⚠️ Offline | ~50/exec   | Zefoy disabled |\n| 🔴 **Live Stream**     | ⚠️ Offline | ~50/exec   | Zefoy disabled |\n\n\u003e **Note:** Service availability depends on Zefoy's status. Bot automatically\n\u003e detects and marks offline services.\n\n---\n\n## 📸 Screenshots\n\n\u003cdiv align=\"center\"\u003e\n\n### Welcome Screen\n\n```\n╭─────────────────────────── 👋 Welcome ───────────────────────────╮\n│                                                                   │\n│                    TikTok Automation Tool                         │\n│                                                                   │\n│               🚀 Automate TikTok engagement                       │\n│               ✨ Multiple services support                        │\n│               🎯 Target goals \u0026 continuous mode                   │\n│               ⚡ Real-time cooldown tracking                      │\n│                                                                   │\n╰───────────────────────────────────────────────────────────────────╯\n```\n\n### Statistics Display\n\n```\n╭─────────────────────── 📊 Bot Statistics ───────────────────────╮\n│                                                                  │\n│                     Uptime: 1h 23m 45s                           │\n│                     Captchas Solved: 15                          │\n│                     Tasks Completed: 12                          │\n│                     Tasks Failed: 0                              │\n│                                                                  │\n│                     Services Used:                               │\n│                       • Hearts: 8                                │\n│                       • Views: 4                                 │\n│                                                                  │\n╰──────────────────────────────────────────────────────────────────╯\n```\n\n### Captcha Solving\n\n```\n╭──────────────────── 🔍 OCR Captcha Solver ─────────────────────╮\n│                                                                 │\n│  ⚡ FAST Mode: 30 attempts in 10-20s                            │\n│  🎯 Horizontal reading enabled                                  │\n│  📊 Confidence scoring active                                   │\n│                                                                 │\n│  [████████████████░░░░░░░░] 60% Complete                        │\n│                                                                 │\n╰─────────────────────────────────────────────────────────────────╯\n```\n\n\u003c/div\u003e\n\n---\n\n## 🚀 Installation\n\n### Prerequisites\n\n**System Requirements:**\n\n- Python 3.8 or higher\n- Tesseract OCR\n- Google Chrome or Chromium\n- 2GB RAM minimum\n- Linux, macOS, or Windows\n\n### Step 1: Install System Dependencies\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eUbuntu/Debian\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nsudo apt-get update\nsudo apt-get install -y tesseract-ocr tesseract-ocr-eng\nsudo apt-get install -y python3 python3-pip python3-venv\nsudo apt-get install -y google-chrome-stable  # or chromium-browser\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003emacOS\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nbrew install tesseract\nbrew install python3\nbrew install --cask google-chrome\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindows\u003c/b\u003e\u003c/summary\u003e\n\n1. Install [Python 3.8+](https://www.python.org/downloads/)\n2. Install [Tesseract OCR](https://github.com/UB-Mannheim/tesseract/wiki)\n3. Install [Google Chrome](https://www.google.com/chrome/)\n4. Add Tesseract to PATH\n\u003c/details\u003e\n\n### Step 2: Clone Repository\n\n```bash\ncd ~/Documents\ngit clone \u003crepository-url\u003e bots\ncd bots\n```\n\n### Step 3: Install Python Dependencies\n\n**Automated Installation (Recommended):**\n\n```bash\nchmod +x install.sh\n./install.sh\n```\n\nThe `install.sh` script will automatically:\n\n- ✓ Install `python3-venv` and `python3-full` (Debian/Ubuntu)\n- ✓ Install Google Chrome + dependencies\n- ✓ Create virtual environment\n- ✓ Install all Python packages\n- ✓ Setup required directories\n\n**Manual Installation:**\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\n```\n\n### 🖥️ VPS/Server Installation\n\nFor VPS or headless servers, use the **smart automated installer**:\n\n```bash\n./install.sh\n```\n\n**✨ Smart Features:**\n- 🔍 **Auto-detects** VPS/Server environment\n- 📦 **Auto-installs** Chrome + dependencies\n- 🖥️ **Auto-installs** Xvfb (virtual display)\n- ⚙️ **Auto-configures** for optimal performance\n\n**Check VPS Environment:**\n\n```bash\n./check_vps.sh  # Verify everything is configured correctly\n```\n\n**Important for VPS:**\n\n- **⚠️ Zefoy Detection Issue?** Use smart auto-detect for 95%+ reliability!\n  ```bash\n  ./venv.sh  # Smart unified runner - auto-detects \u0026 uses Xvfb on VPS\n  ```\n- **Auto-detection:** Bot automatically enables Xvfb on VPS for best compatibility! 🎉\n- **Fallback:** Pure headless with stealth (60-80% success rate)\n- Minimum 2GB RAM required\n- /dev/shm should be \u003e64MB (check with `df -h /dev/shm`)\n- **Troubleshooting:** [ZEFOY_HEADLESS_FIX.md](docs/ZEFOY_HEADLESS_FIX.md)\n- **Complete guide:** [VPS_SETUP.md](docs/VPS_SETUP.md)\n\n**Key Dependencies:**\n\n- `selenium` 4.15.2 - Browser automation\n- `undetected-chromedriver` 3.5.5 - Anti-detection\n- `pytesseract` 0.3.10 - OCR engine\n- `opencv-python` 4.8.1.78 - Image processing\n- `Pillow` 10.1.0 - Image manipulation\n- `numpy` 1.26.4 - Numerical operations\n- `PyYAML` 6.0.1 - Configuration\n- `rich` 13.7.0 - Terminal UI\n- `questionary` 2.0.1 - Interactive prompts\n\n### Step 4: Configure\n\nEdit `config.yaml` with your preferences:\n\n```yaml\n# Quick Start Configuration\ncaptcha:\n  auto_solve: true # Enable OCR\n  fast_mode: true # Use FAST mode (recommended)\n  manual_input: true # Fallback to manual\n  auto_open_image: true # Auto-open captcha (local mode)\n  upload_to_cloud: false # Upload to uploader.sh (VPS mode)\n\nbrowser:\n  headless: false # Set true for background mode\n  use_adblock: true # Block ads for faster loading\n\nlogging:\n  level: MAIN # Clean user-friendly logs\n  colorful: true # Colorful terminal output\n```\n\n### Step 5: Run\n\n```bash\npython run.py\n```\n\nOr with virtual environment:\n\n```bash\nsource venv/bin/activate\npython run.py\n```\n\n---\n\n## 💡 Usage\n\n### Quick Start (Smart Auto-Detect) ⭐ **RECOMMENDED**\n\nThe **easiest way** - automatically detects your environment and chooses the best mode:\n\n```bash\n./venv.sh\n```\n\n**What it does:**\n- ✅ **Desktop/Laptop** → Runs in visible mode (99% success)\n- ✅ **VPS with Xvfb** → Uses virtual display (95%+ success)\n- ✅ **VPS without Xvfb** → Auto-installs Xvfb or falls back to headless\n\nThis is the smartest way to run the bot - it picks the optimal mode for you!\n\n### Manual Start\n\n1. **Start the bot:**\n\n   ```bash\n   python run.py\n   ```\n\n2. **From main menu, select:** `🚀 Start Bot`\n\n3. **Choose your service:** Hearts, Views, Shares, etc.\n\n4. **Enter TikTok video URL**\n\n5. **Select execution mode:**\n   - **Manual Executions** - Set number of times (e.g., 5 times)\n   - **Target Amount** - Set target count (e.g., 10,000 hearts)\n   - **Goal Mode** - Use targets from config\n\n6. **Sit back and relax!** Bot handles everything automatically.\n\n### Execution Modes Explained\n\n**1. Manual Executions**\n\n```\nExecute service exactly N times\nExample: \"Run 5 times\" → Executes 5 times then stops\nPerfect for: Quick boosts, testing\n```\n\n**2. Target Amount**\n\n```\nRun until reaching specific amount\nExample: \"Get 10,000 hearts\" → Runs until 10k reached\nPerfect for: Specific goals, one-time campaigns\n```\n\n**3. Goal Mode**\n\n```\nUses targets from config.yaml\nTracks progress across sessions\nPerfect for: Long-term goals, continuous growth\n```\n\n### Interactive Menus\n\n**Main Menu:**\n\n- 🚀 Start Bot\n- ⚙️ Configure Settings\n- 📊 View Statistics\n- 📋 View Available Services\n- ❓ Help\n- 🚪 Exit\n\n**Settings Menu:**\n\n- 🌐 Browser Settings (headless, adblock, user agent)\n- ⏱️ Timeout Settings\n- 🔐 Captcha \u0026 OCR Settings (FAST/AGGRESSIVE modes)\n- 📝 Logging Settings\n- 🎯 Service Target Goals\n- 🔌 Enable/Disable Services\n\n**Bot Running Menu:**\n\n- ▶️ Execute Service\n- 📊 View Statistics (live session stats)\n- 🎯 View Target Goals Progress\n- 🔄 Refresh Page\n- ◀️ Back to Main Menu\n\n---\n\n## ⚙️ Configuration\n\n### Configuration File Structure\n\n```yaml\n# config.yaml - Complete configuration reference\n\nbrowser:\n  headless: false # Run in background\n  use_adblock: true # Block ads (recommended)\n  disable_images: false # Disable images for speed\n  window_size: \"1920,1080\" # Browser resolution\n  user_agent: \"Mozilla/5.0...\" # Custom user agent\n\ncaptcha:\n  auto_solve: true # Enable OCR\n  fast_mode: true # FAST mode (10-20s)\n  manual_input: true # Manual fallback\n  save_image: true # Save screenshots\n  auto_open_image: true # Auto-open (headless!)\n  debug_mode: false # Debug preprocessing\n\n  ocr_advanced: # AGGRESSIVE mode settings\n    horizontal_reading: true # Left→Right reading\n    handle_uneven_text: true # Uneven text support\n    aggressive_preprocessing: false # 12 methods vs 5\n    aggressive_ocr_configs: false # 26 configs vs 5\n\ntimeouts:\n  page_load: 30 # Page load timeout\n  element_wait: 10 # Element wait time\n  captcha_solve: 120 # Captcha timeout\n  between_actions: 2 # Action delays\n  retry_delay: 5 # Retry delay\n\nretry:\n  auto_retry_on_cooldown: true # Auto-retry\n  max_attempts: 3 # Max retry attempts\n  on_captcha_fail: true # Retry on captcha fail\n\nservice_execution:\n  show_countdown: true # Show cooldown timer\n  active_service_only: false # Single service mode\n  default_target: 1 # Default target\n\nservice_targets: # Goal mode targets\n  hearts: 10000\n  views: 50000\n  followers: 1000\n  shares: 2000\n  favorites: 3000\n  comments_hearts: 5000\n  livestream: 500\n\n  per_execution: # Average per execution\n    hearts: 100\n    views: 1000\n    followers: 50\n    shares: 50\n    favorites: 100\n    comments_hearts: 50\n    livestream: 50\n\nlogging:\n  level: MAIN # MAIN/INFO/DEBUG\n  colorful: true # Colored output\n  save_to_file: true # Save to logs/\n\nzefoy:\n  url: \"https://zefoy.com\"\n\n  services: # Service configuration\n    - name: \"Hearts\"\n      enabled: true\n      button_class: \"t-hearts-button\"\n\n    - name: \"Views\"\n      enabled: true\n      button_class: \"t-views-button\"\n\n    # ... more services\n\npaths:\n  screenshots: \"screenshots\" # Screenshot folder\n  logs: \"logs\" # Log folder\n  extensions: \"extensions\" # Extensions folder\n```\n\n### Common Configuration Scenarios\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHeadless Mode (Background Operation)\u003c/b\u003e\u003c/summary\u003e\n\n```yaml\nbrowser:\n  headless: true\n\ncaptcha:\n  auto_solve: true\n  auto_open_image: true # Important for headless!\n  save_image: true\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMaximum Speed\u003c/b\u003e\u003c/summary\u003e\n\n```yaml\nbrowser:\n  headless: true\n  use_adblock: true\n  disable_images: true\n\ncaptcha:\n  fast_mode: true # Quick OCR\n\ntimeouts:\n  between_actions: 1 # Minimal delays\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMaximum Accuracy (Difficult Captchas)\u003c/b\u003e\u003c/summary\u003e\n\n```yaml\ncaptcha:\n  auto_solve: true\n  fast_mode: false # AGGRESSIVE mode\n\n  ocr_advanced:\n    aggressive_preprocessing: true\n    aggressive_ocr_configs: true\n    horizontal_reading: true\n    handle_uneven_text: true\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDebug Mode\u003c/b\u003e\u003c/summary\u003e\n\n```yaml\ncaptcha:\n  debug_mode: true # Save all preprocessing\n\nlogging:\n  level: DEBUG # Verbose logging\n```\n\n\u003c/details\u003e\n\n---\n\n## 🤖 OCR Captcha Solver\n\n### How It Works\n\n```\n┌─────────────┐\n│   Captcha   │\n│   Image     │\n└──────┬──────┘\n       │\n       ▼\n┌─────────────────────────────────────┐\n│   Preprocessing (5-12 methods)      │\n│   • Line removal                    │\n│   • Noise reduction                 │\n│   • Contrast enhancement            │\n│   • Thresholding                    │\n└──────┬──────────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────────┐\n│   OCR Engine (5-26 configs)         │\n│   • Tesseract LSTM                  │\n│   • Multiple PSM modes              │\n│   • Horizontal reading              │\n└──────┬──────────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────────┐\n│   Confidence Scoring                │\n│   • Frequency analysis              │\n│   • Length validation               │\n│   • Pattern detection               │\n└──────┬──────────────────────────────┘\n       │\n       ▼\n┌─────────────┐\n│   Result    │\n│   (a-z,A-Z) │\n└─────────────┘\n```\n\n### FAST Mode vs AGGRESSIVE Mode\n\n| Feature             | FAST Mode ⚡  | AGGRESSIVE Mode 🐌 |\n| ------------------- | ------------- | ------------------ |\n| **Preprocessing**   | 5 methods     | Up to 12 methods   |\n| **OCR Configs**     | 5 configs     | Up to 26 configs   |\n| **Total Attempts**  | ~30           | 300+               |\n| **Processing Time** | 10-20 seconds | 3-5 minutes        |\n| **OCR Retries**     | 2 retries     | 5 retries          |\n| **Success Rate**    | 70-85%        | 75-90%             |\n| **Recommended For** | Most users    | Difficult captchas |\n\n### Preprocessing Methods\n\n1. **Line Removal + Adaptive Threshold**\n   - Morphological operations to detect and remove lines\n   - Adaptive thresholding for varying lighting\n\n2. **Morphological Line Removal + Otsu**\n   - Aggressive line detection with larger kernels\n   - Otsu's binarization for optimal threshold\n\n3. **Bilateral Filter + CLAHE**\n   - Edge-preserving noise reduction\n   - Contrast Limited Adaptive Histogram Equalization\n\n4. **Inverted + Line Removal**\n   - For light text on dark background\n   - Inverts colors before processing\n\n5. **Median Blur + Line Removal**\n   - Salt-and-pepper noise removal\n   - Maintains edge sharpness\n\n6. **Erosion-Dilation** _(AGGRESSIVE only)_\n   - Morphological operations\n   - Thick line handling\n\n**+ 6 additional methods in AGGRESSIVE mode**\n\n### OCR Configurations\n\n**Page Segmentation Modes (PSM):**\n\n- PSM 8 - Single word (most common)\n- PSM 7 - Single line of text\n- PSM 6 - Uniform block of text\n- PSM 13 - Raw line (no dictionaries)\n- PSM 10 - Single character\n\n**OCR Engine Modes (OEM):**\n\n- OEM 1 - LSTM only (neural network)\n- OEM 3 - Legacy + LSTM (hybrid)\n\n**+ 21 additional configs in AGGRESSIVE mode**\n\n### Confidence Scoring\n\n```python\n# Scoring factors:\n1. Length score (3-8 chars optimal)\n2. Frequency count (same result multiple times)\n3. Pattern detection (avoid repeated chars like \"aaaa\")\n4. Character whitelist (a-z, A-Z only)\n\n# Example:\nResult \"abCdEf\" appears 5 times → High confidence ✅\nResult \"aaaa\" appears 3 times → Low confidence (pattern) ❌\nResult \"ab12\" appears 2 times → Invalid (numbers) ❌\n```\n\n---\n\n## 📊 Performance\n\n### Success Rates\n\n| Captcha Type     | FAST Mode | AGGRESSIVE Mode |\n| ---------------- | --------- | --------------- |\n| Clean text       | 85-95%    | 90-98%          |\n| With lines       | 70-80%    | 80-90%          |\n| Heavy noise      | 50-65%    | 65-80%          |\n| Overlapping text | 40-55%    | 60-75%          |\n| Uneven text      | 55-70%    | 70-85%          |\n\n### Speed Comparison\n\n| Mode           | Processing Time | Total Attempts | Recommended Use                      |\n| -------------- | --------------- | -------------- | ------------------------------------ |\n| **FAST**       | 10-20 seconds   | ~30            | Daily use, most captchas             |\n| **AGGRESSIVE** | 3-5 minutes     | 300+           | Difficult captchas, low success rate |\n\n### System Performance\n\n**Resource Usage:**\n\n- CPU: 10-30% (during OCR processing)\n- RAM: 200-500 MB\n- Disk: ~10 MB for screenshots (with debug)\n\n**Execution Speed:**\n\n- Captcha solve: 10-20s (FAST) / 3-5min (AGGRESSIVE)\n- Service execution: 5-10s\n- Cooldown wait: 2-5 minutes (varies by service)\n- Total per execution: 3-7 minutes average\n\n---\n\n## 📚 Documentation\n\n### Main Documentation\n\n| Document                          | Description                 |\n| --------------------------------- | --------------------------- |\n| [README.md](README.md)            | This file - Complete guide  |\n| [CHANGELOG.md](docs/CHANGELOG.md) | Version history and updates |\n| [LICENSE](LICENSE)                | MIT License                 |\n\n### Feature Guides\n\n| Guide                                                             | Topic                           |\n| ----------------------------------------------------------------- | ------------------------------- |\n| [VPS_SETUP.md](docs/VPS_SETUP.md)                                 | **VPS/Server setup guide**      |\n| [INSTALLATION.md](docs/INSTALLATION.md)                           | Detailed installation guide     |\n| [CHROME_TROUBLESHOOTING.md](docs/CHROME_TROUBLESHOOTING.md)       | Chrome/ChromeDriver issues      |\n| [OCR_TROUBLESHOOTING.md](docs/OCR_TROUBLESHOOTING.md)             | OCR debugging and optimization  |\n| [AGGRESSIVE_OCR_MODE.md](docs/AGGRESSIVE_OCR_MODE.md)             | AGGRESSIVE mode detailed guide  |\n| [DISPLAY_MODES.md](docs/DISPLAY_MODES.md)                         | **Display modes comparison** ⭐ |\n| [HEADLESS_MODE_GUIDE.md](docs/HEADLESS_MODE_GUIDE.md)             | Running in headless mode        |\n| [HEADLESS_STEALTH.md](docs/HEADLESS_STEALTH.md)                   | Stealth mode details            |\n| [ZEFOY_HEADLESS_FIX.md](docs/ZEFOY_HEADLESS_FIX.md)               | Fix Zefoy detection (Xvfb)      |\n| [ZEFOY_DETECTION_FIX.md](docs/ZEFOY_DETECTION_FIX.md)             | **Captcha not detected fix** ⚠️ |\n| [VPS_CDP_FIX.md](docs/VPS_CDP_FIX.md)                             | **Runtime.evaluate error** ⚠️   |\n| [CDP_ERROR_FINAL_FIX.md](docs/CDP_ERROR_FINAL_FIX.md)             | **CDP error suppression** ✅    |\n| [STUCK_HEADLESS_FIX.md](docs/STUCK_HEADLESS_FIX.md)               | **Bot stuck/timeout fix** ✅    |\n| [FINAL_FIXES_v2.md](docs/FINAL_FIXES_v2.md)                       | **All comprehensive fixes** 📚  |\n| [FIXES_SUMMARY.md](docs/FIXES_SUMMARY.md)                         | **Quick fixes summary** 📋      |\n| [AUTO_OPEN_CAPTCHA_FEATURE.md](docs/AUTO_OPEN_CAPTCHA_FEATURE.md) | Auto-open captcha feature       |\n| [COOLDOWN.md](docs/COOLDOWN.md)                                   | Cooldown system explained       |\n\n### Quick References\n\n| Reference              | Link                                     |\n| ---------------------- | ---------------------------------------- |\n| Installation Help      | See [Installation](#-installation)       |\n| Configuration Examples | See [Configuration](#-configuration)     |\n| FAQ                    | See [FAQ](#-faq)                         |\n| Troubleshooting        | See [Troubleshooting](#-troubleshooting) |\n\n---\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ OCR keeps failing / Low success rate\u003c/b\u003e\u003c/summary\u003e\n\n**Solutions:**\n\n1. **Enable Debug Mode:**\n\n   ```yaml\n   captcha:\n     debug_mode: true\n   logging:\n     level: DEBUG\n   ```\n\n2. **Check Screenshots:**\n   - Look in `screenshots/` folder\n   - Check preprocessing quality\n   - Verify text is readable\n\n3. **Try AGGRESSIVE Mode:**\n\n   ```yaml\n   captcha:\n     fast_mode: false\n     ocr_advanced:\n       aggressive_preprocessing: true\n       aggressive_ocr_configs: true\n   ```\n\n4. **Enable Manual Fallback:**\n   ```yaml\n   captcha:\n     manual_input: true\n   ```\n\n**See:** [docs/OCR_TROUBLESHOOTING.md](docs/OCR_TROUBLESHOOTING.md)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ Chrome not found / ChromeDriver error\u003c/b\u003e\u003c/summary\u003e\n\n**Solutions:**\n\n1. **Install Chrome:**\n\n   ```bash\n   # Ubuntu/Debian\n   sudo apt-get install google-chrome-stable\n\n   # macOS\n   brew install --cask google-chrome\n   ```\n\n2. **Clean Chrome Processes:**\n\n   ```bash\n   chmod +x fix_chrome.sh\n   ./fix_chrome.sh\n   ```\n\n3. **Update ChromeDriver:**\n   ```bash\n   pip install --upgrade undetected-chromedriver\n   ```\n\n**See:** [docs/CHROME_TROUBLESHOOTING.md](docs/CHROME_TROUBLESHOOTING.md)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ Service on cooldown constantly\u003c/b\u003e\u003c/summary\u003e\n\n**This is normal!** Services have cooldowns:\n\n- First execution: No cooldown\n- After success: 2-5 minutes cooldown\n- Bot waits automatically\n\n**Enable auto-retry:**\n\n```yaml\nretry:\n  auto_retry_on_cooldown: true\n```\n\n**See:** [docs/COOLDOWN.md](docs/COOLDOWN.md)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ Headless mode - Can't see captcha\u003c/b\u003e\u003c/summary\u003e\n\n**Solution - Auto-open feature:**\n\n```yaml\nbrowser:\n  headless: true\n\ncaptcha:\n  save_image: true\n  auto_open_image: true # ← This opens captcha automatically!\n```\n\nBot will open captcha image with default viewer automatically!\n\n**See:** [docs/HEADLESS_MODE_GUIDE.md](docs/HEADLESS_MODE_GUIDE.md)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ Tesseract not found\u003c/b\u003e\u003c/summary\u003e\n\n**Install Tesseract:**\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install tesseract-ocr tesseract-ocr-eng\n\n# macOS\nbrew install tesseract\n\n# Windows\n# Download from: https://github.com/UB-Mannheim/tesseract/wiki\n# Add to PATH after installation\n```\n\n**Verify installation:**\n\n```bash\ntesseract --version\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ Bot crashes / Freezes\u003c/b\u003e\u003c/summary\u003e\n\n**Solutions:**\n\n1. **Check logs:**\n\n   ```bash\n   tail -f logs/betlo_*.log\n   ```\n\n2. **Clean Chrome:**\n\n   ```bash\n   ./fix_chrome.sh\n   ```\n\n3. **Restart with DEBUG:**\n\n   ```yaml\n   logging:\n     level: DEBUG\n   ```\n\n4. **Check system resources:**\n   - Ensure 2GB+ RAM available\n   - Close other Chrome instances\n   \u003c/details\u003e\n\n### Getting Help\n\n1. **Check logs:** `logs/betlo_YYYYMMDD.log`\n2. **Enable DEBUG mode:** Set `logging.level: DEBUG`\n3. **Check documentation:** See [docs/](docs/) folder\n4. **Review FAQ:** See [FAQ](#-faq) section below\n\n---\n\n## ❓ FAQ\n\n### General Questions\n\n**Q: Is this safe to use?** A: The bot uses undetected-chromedriver and\nhuman-like behavior to minimize detection. However, use at your own risk and\nfollow TikTok/Zefoy ToS.\n\n**Q: Do I need a Zefoy account?** A: No, Zefoy doesn't require accounts. Just\nvisit the website and use services.\n\n**Q: Can I run multiple instances?** A: Not recommended. Running multiple\ninstances may cause conflicts and increase detection risk.\n\n**Q: Does this work on mobile?** A: No, this is a desktop application requiring\nPython and Chrome.\n\n### OCR Questions\n\n**Q: What's the difference between FAST and AGGRESSIVE mode?** A: FAST mode is\nfaster (10-20s) with good accuracy (70-85%). AGGRESSIVE mode is slower (3-5min)\nbut more thorough (75-90%). Use FAST for daily use, AGGRESSIVE for difficult\ncaptchas.\n\n**Q: Can I train my own OCR model?** A: Not currently. The bot uses Tesseract\nOCR which is pre-trained. You can adjust preprocessing methods in the code.\n\n**Q: OCR never works, should I disable it?** A: Don't disable! Instead, enable\n`manual_input: true` for fallback. This way OCR tries first, manual as backup.\n\n### Configuration Questions\n\n**Q: How do I run in background?** A: Set `browser.headless: true` and\n`captcha.auto_open_image: true` in config.yaml\n\n**Q: Can I customize service targets?** A: Yes! Edit `service_targets` section\nin config.yaml\n\n**Q: How do I enable only specific services?** A: Use Settings menu →\nEnable/Disable Services, or edit config.yaml\n\n### Troubleshooting Questions\n\n**Q: Service shows \"OFFLINE\", what to do?** A: This means Zefoy has disabled the\nservice. Wait for Zefoy to re-enable it. You can still try to use it, but it may\nnot work.\n\n**Q: Cooldown is too long, can I skip it?** A: No, cooldowns are enforced by\nZefoy. Skipping would cause errors. Enable `show_countdown: true` to see\ncountdown timer.\n\n**Q: Statistics not showing, why?** A: Statistics show when bot is running. From\nmain menu, it shows last session data from `target_progress.json`. Execute some\nservices first!\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how you can help:\n\n### Areas for Improvement\n\n- 🎯 Additional preprocessing methods for OCR\n- 📊 Better confidence scoring algorithms\n- 🌐 Support for other captcha types\n- ⚡ Performance optimizations\n- 🎨 UI/UX improvements\n- 📝 Documentation improvements\n- 🌍 Internationalization (i18n)\n\n### How to Contribute\n\n1. **Fork the repository**\n2. **Create a feature branch:** `git checkout -b feature/amazing-feature`\n3. **Make your changes**\n4. **Test thoroughly**\n5. **Commit:** `git commit -m 'Add amazing feature'`\n6. **Push:** `git push origin feature/amazing-feature`\n7. **Open a Pull Request**\n\n### Code Style\n\n- Follow PEP 8 for Python code\n- Use type hints where possible\n- Add docstrings to functions\n- Comment complex logic\n- Keep functions focused and small\n\n### Testing\n\n- Test on multiple platforms (Linux, macOS, Windows)\n- Test with different captcha types\n- Verify no regressions in existing features\n- Check for linter errors\n\n---\n\n## ⚠️ Disclaimer\n\n### Educational Purpose Only\n\nThis bot is created for **educational and research purposes only**. By using\nthis software, you acknowledge that:\n\n- ⚖️ You will use it **responsibly and ethically**\n- 📜 You understand the **risks and consequences**\n- ✅ You will **comply with all applicable laws** and Terms of Service\n- 🚫 You will **not use it for spam, abuse, or commercial purposes** without\n  permission\n- 👤 You take **full responsibility** for your actions\n\n### Legal Notice\n\n- This software is provided \"AS IS\" without warranties\n- Authors are not responsible for misuse or damages\n- Not affiliated with TikTok or Zefoy\n- Users must comply with TikTok and Zefoy Terms of Service\n- Automated interactions may violate platform policies\n\n### Use at Your Own Risk\n\n- Account bans or restrictions are possible\n- Service availability depends on Zefoy\n- Results are not guaranteed\n- No warranty or support guarantee\n\n**By using this software, you agree to these terms.**\n\n---\n\n## 📜 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE)\nfile for details.\n\n### MIT License Summary\n\n✅ **Permissions:**\n\n- Commercial use\n- Modification\n- Distribution\n- Private use\n\n❌ **Limitations:**\n\n- Liability\n- Warranty\n\n📋 **Conditions:**\n\n- License and copyright notice must be included\n\n---\n\n## 🙏 Credits \u0026 Acknowledgments\n\nThis project uses the following open-source libraries:\n\n### Core Dependencies\n\n- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) - Optical\n  character recognition engine\n- [OpenCV](https://opencv.org/) - Image processing library\n- [Selenium](https://www.selenium.dev/) - Browser automation framework\n- [undetected-chromedriver](https://github.com/ultrafunkamsterdam/undetected-chromedriver) -\n  Anti-detection Chrome driver\n\n### UI \u0026 Utilities\n\n- [Rich](https://github.com/Textualize/rich) - Beautiful terminal formatting\n- [Questionary](https://github.com/tmbo/questionary) - Interactive CLI prompts\n- [PyYAML](https://pyyaml.org/) - YAML configuration parser\n- [Pillow](https://python-pillow.org/) - Image manipulation\n- [NumPy](https://numpy.org/) - Numerical operations\n\n### Special Thanks\n\n- The open-source community for amazing tools\n- Tesseract OCR team for powerful OCR engine\n- Contributors and users of this project\n\n---\n\n## 🆕 What's New in v3.0.0\n\n### October 23, 2025 Update - Major Release\n\n#### 🔄 BREAKING CHANGE: Package Renamed to Betlo\n\n- **Package renamed** from `zefoy_bot` to `betlo`\n  - Import changes: `from zefoy_bot.main` → `from betlo.main`\n  - Log files: `zefoy_bot_*.log` → `betlo_*.log`\n  - Module path: `python -m zefoy_bot` → `python -m betlo`\n  - All 37 files updated with new package name\n  - Complete documentation updated across all files\n\n#### ⚡ 10-60x Faster Commits with Optimized Pre-commit\n\n- **Commit speed improved dramatically**\n  - Before: 2-5 minutes (waiting for Node.js/Go installation)\n  - After: 2-5 seconds for normal commits ⚡\n- **Two-tier approach**\n  - Fast hooks: Run automatically on every commit (2-5 seconds)\n  - Slow hooks: Run manually before push (2-5 minutes)\n- **Smart hook staging**\n  - Markdown linter → manual only (was slow)\n  - YAML formatter → manual only (was slow)\n  - Shell formatter → manual only (was slow)\n  - Python formatters → auto-run, scoped to `betlo/*.py`\n\n- **New documentation**\n  - `PRE_COMMIT_GUIDE.md` - Complete usage guide\n  - Learn how to run fast commits and full checks\n\n#### 📝 Migration Guide\n\n**Update your imports:**\n\n```python\n# OLD\nfrom zefoy_bot.main import main\nimport zefoy_bot\n\n# NEW\nfrom betlo.main import main\nimport betlo\n```\n\n**Quick steps:**\n\n1. Pull latest changes: `git pull`\n2. Update imports in your code\n3. Reinstall pre-commit: `pre-commit install`\n4. Enjoy faster commits! 🚀\n\n**See [CHANGELOG.md](docs/CHANGELOG.md) for complete version history**\n\n---\n\n## 📞 Support \u0026 Contact\n\n### Documentation\n\n- 📖 [Full Documentation](docs/)\n- 📝 [Changelog](docs/CHANGELOG.md)\n- ❓ [FAQ](#-faq)\n- 🐛 [Troubleshooting](#-troubleshooting)\n\n### Resources\n\n- 💻 [GitHub Repository](https://github.com)\n- 📊 [Issue Tracker](https://github.com/issues)\n- 💬 [Discussions](https://github.com/discussions)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### ⭐ Star this project if you find it useful!\n\n**Made with ❤️ by the community**\n\n---\n\n**Last Updated:** October 30, 2025 **Current Version:** 4.0.0 - Package Renamed\nto Betlo \u0026 Optimized Pre-commit\n\n**[↑ Back to Top](#-table-of-contents)**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarvin3dp%2Fbetlo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarvin3dp%2Fbetlo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarvin3dp%2Fbetlo/lists"}