Installation Guide

📦 Installation Guide

Complete step-by-step installation guide for AutoTyper on macOS.

🔍 System Requirements

✅ Minimum Requirements

Operating System: macOS 10.14+ (Mojave or later)
Python Version:   3.6 or higher
RAM:             512 MB available
Storage:         50 MB free space
Permissions:     Admin access for accessibility setup

🚀 Recommended Specifications

Operating System: macOS 11.0+ (Big Sur or later)
Python Version:   3.8 or higher
RAM:             1 GB available
Storage:         100 MB free space
Terminal:        Terminal.app or iTerm2

📋 Pre-Installation Checklist

1️⃣ Check Python Installation

# Check if Python is installed
python3 --version

# Expected output (version may vary):
# Python 3.8.10

# If Python is not installed, install via Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install python

2️⃣ Verify Git Installation

# Check Git installation
git --version

# Expected output:
# git version 2.32.0

# Install Git if needed:
xcode-select --install

3️⃣ Create Project Directory

# Navigate to your preferred directory
cd ~/Documents

# Or create a dedicated projects folder
mkdir ~/Projects && cd ~/Projects

🚀 Installation Methods

Method 1: Quick Install (Recommended)

# One-command installation
curl -fsSL https://raw.githubusercontent.com/aashish-shukla/Autotyper-for-MacOS/main/install.sh | bash

Method 2: Manual Installation

Step 1: Clone Repository

# Clone the repository
git clone https://github.com/aashish-shukla/Autotyper-for-MacOS.git

# Navigate to project directory
cd Autotyper-for-MacOS

# Verify files
ls -la

Step 2: Install Dependencies

# Install required Python packages
pip3 install pyautogui pyperclip keyboard

# Or install from requirements file
pip3 install -r requirements.txt

Step 3: Verify Installation

# Test the installation
python3 autotyper.py --version

# Expected output:
# AutoTyper v3.4 - Individual Mode Hotkeys Edition

Method 3: Virtual Environment (Recommended for Developers)

# Create virtual environment
python3 -m venv autotyper-env

# Activate virtual environment
source autotyper-env/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run AutoTyper
python autotyper.py

🔧 Dependency Details

📚 Required Libraries

Library	Version	Purpose	Installation
pyautogui	0.9.54+	GUI automation and keyboard simulation	pip install pyautogui
pyperclip	1.8.2+	Cross-platform clipboard operations	pip install pyperclip
keyboard	0.13.5+	Global hotkey detection and events	pip install keyboard

📋 Installation Commands

# Individual installations
pip3 install pyautogui==0.9.54
pip3 install pyperclip==1.8.2  
pip3 install keyboard==0.13.5

# Bulk installation
pip3 install pyautogui pyperclip keyboard

# With version specifications
pip3 install "pyautogui>=0.9.54" "pyperclip>=1.8.2" "keyboard>=0.13.5"

🔍 Post-Installation Verification

✅ Test Basic Functionality

# Run AutoTyper
python3 autotyper.py

# Expected initial output:
# ======================================================================
#            🤖 AutoTyper v3.4 - Individual Mode Hotkeys Edition
# ======================================================================
# [INFO] 🚀 Hotkey-controlled clipboard auto-typer
# [INFO] 📋 Types ONLY clipboard content with human-like behavior
# [INFO] ⚡ Features individual hotkeys for each speed mode
# [INFO] 🍎 Optimized for macOS compatibility

🧪 Test Clipboard Integration

# Copy test text to clipboard
echo "Hello, AutoTyper!" | pbcopy

# Run AutoTyper and check status
python3 autotyper.py

# Should show:
# 📋 Clipboard: 17 chars, 2 words, 1 lines
# 👀 Preview: Hello, AutoTyper!

🎹 Test Hotkey Detection

# AutoTyper will attempt to register hotkeys
# Look for these messages:

# ✅ Success:
# [INFO] ✅ F9 - Resume/General Start
# [INFO] ✅ F8 - Pause  
# [INFO] ✅ F10 - Stop

# ❌ Permission needed:
# [ERROR] ❌ Accessibility permissions required!

🛠️ Troubleshooting Installation Issues

❌ Common Issues & Solutions

Issue 1: Python Command Not Found

# Problem:
# zsh: command not found: python

# Solutions:
# Try python3 instead
python3 autotyper.py

# Or create alias
echo 'alias python=python3' >> ~/.zshrc
source ~/.zshrc

Issue 2: Permission Denied for pip

# Problem:
# ERROR: Could not install packages due to an EnvironmentError

# Solutions:
# Use user installation
pip3 install --user pyautogui pyperclip keyboard

# Or use virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install pyautogui pyperclip keyboard

Issue 3: SSL Certificate Error

# Problem:
# SSL: CERTIFICATE_VERIFY_FAILED

# Solutions:
# Update certificates
/Applications/Python\ 3.x/Install\ Certificates.command

# Or bypass SSL (not recommended)
pip3 install --trusted-host pypi.org --trusted-host pypi.python.org pyautogui

Issue 4: Xcode Command Line Tools Missing

# Problem:
# xcrun: error: invalid active developer path

# Solution:
xcode-select --install

# Follow the installation prompts

🔧 Advanced Troubleshooting

Check Python Installation Path

# Find Python installation
which python3
# Output: /usr/bin/python3

# Check Python path
python3 -c "import sys; print(sys.executable)"
# Output: /usr/bin/python3

Verify Package Installation

# Check installed packages
pip3 list | grep -E "(pyautogui|pyperclip|keyboard)"

# Expected output:
# keyboard      0.13.5
# pyautogui     0.9.54
# pyperclip     1.8.2

Test Individual Libraries

# Test pyautogui
python3 -c "import pyautogui; print('PyAutoGUI OK')"

# Test pyperclip  
python3 -c "import pyperclip; print('Pyperclip OK')"

# Test keyboard
python3 -c "import keyboard; print('Keyboard OK')"

📁 Project Structure

After successful installation, your project directory should look like:

Autotyper-for-MacOS/
├── autotyper.py              # Main application file
├── README.md                 # Project documentation
├── requirements.txt          # Python dependencies
├── LICENSE                   # MIT license file
├── install.sh               # Quick installation script
├── examples/                # Usage examples
│   ├── basic_usage.py       # Basic usage examples
│   ├── advanced_config.py   # Advanced configuration
│   └── custom_timing.py     # Custom timing patterns
├── docs/                    # Additional documentation
│   ├── API.md              # API reference
│   ├── CONTRIBUTING.md     # Contribution guidelines
│   └── CHANGELOG.md        # Version history
└── tests/                   # Test files
    ├── test_basic.py       # Basic functionality tests
    ├── test_hotkeys.py     # Hotkey system tests
    └── test_timing.py      # Timing accuracy tests

🔄 Updating AutoTyper

📥 Update to Latest Version

# Navigate to project directory
cd path/to/Autotyper-for-MacOS

# Pull latest changes
git pull origin main

# Update dependencies if needed
pip3 install -r requirements.txt --upgrade

# Verify update
python3 autotyper.py --version

🔖 Version Management

# Check current version
git log --oneline -1

# List all versions
git tag -l

# Switch to specific version
git checkout v3.4

# Return to latest
git checkout main

🎯 Next Steps

After successful installation:

1. 🔐 Setup Permissions: Permissions Setup Guide
2. 🚀 First Time Setup: First Time Setup Guide
3. 📖 Learn Basic Usage: Basic Usage Guide
4. 🎮 Configure Hotkeys: Hotkey Configuration

---

Need help? Check our Troubleshooting Guide or create an issue on GitHub.