Skip to content

First Time Setup

Jump to bottom
Aashish Kumar Shukla edited this page Jul 22, 2025 · 1 revision

🚀 First Time Setup Guide

Complete configuration guide for new AutoTyper users on macOS.

🎯 Overview

This guide will walk you through the initial setup process to get AutoTyper running smoothly on your macOS system with all features enabled.

⏱️ Setup Time Estimate

Task Estimated Time Difficulty
Accessibility Permissions 2-3 minutes Easy
Testing Basic Functions 1-2 minutes Easy
Hotkey Configuration 2-3 minutes Easy
Speed Calibration 3-5 minutes Medium
Total Setup Time 8-13 minutes Easy

📋 Pre-Setup Checklist

Before beginning, ensure you have:

  • ✅ AutoTyper successfully installed (Installation Guide)
  • ✅ Admin access to your macOS system
  • ✅ Terminal or iTerm2 application
  • ✅ Basic text to test with (we'll provide examples)

🔐 Step 1: Accessibility Permissions Setup

🎯 Why Permissions Are Needed

AutoTyper requires accessibility permissions to:

  • 🎮 Register global hotkeys (F1-F10, Ctrl+Shift combinations)
  • ⌨️ Simulate keyboard input across all applications
  • 🔍 Monitor keyboard events for hotkey detection

📱 Grant Accessibility Access

Method 1: Through System Preferences (Recommended)

# Open System Preferences
open /System/Applications/System\ Preferences.app

# Navigate manually:
# System Preferences → Security & Privacy → Privacy → Accessibility

Method 2: Direct Command (macOS 11+)

# Open directly to Accessibility settings
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"

🔧 Step-by-Step Permission Setup

  1. Open Security & Privacy

    • Click System Preferences from Apple menu
    • Select Security & Privacy
    • Click Privacy tab

  2. Access Accessibility Settings

    • Scroll down and click Accessibility in the left sidebar
    • You'll see a list of applications with accessibility access

  3. Unlock Settings

    • Click the lock icon 🔒 in the bottom-left corner
    • Enter your admin password
    • The lock should now show as unlocked 🔓

  4. Add Terminal/Python

    • Click the + button below the application list
    • Navigate to Applications → Utilities → Terminal.app
    • Select Terminal and click Open
    • ✅ Ensure the checkbox next to Terminal is checked

  5. Alternative: Add Python Directly

    # Find Python location first
which python3
# Output example: /usr/bin/python3

# Add this path in System Preferences instead of Terminal

  6. Verify Settings

    • Terminal (or Python) should now appear in the list
    • The checkbox should be ✅ checked
    • The lock can be clicked again to secure settings

🧪 Test Accessibility Access 

# Run this test command
python3 -c "
import keyboard
try:
    keyboard.is_pressed('space')
    print('✅ Accessibility permissions: GRANTED')
except Exception as e:
    print('❌ Accessibility permissions: DENIED')
    print(f'Error: {e}')
"

🎮 Step 2: First Launch and Hotkey Test

🚀 Initial Launch 

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

# Launch AutoTyper
python3 autotyper.py

📊 Expected 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

📊 STATUS: 🔴 STOPPED
⚡ Current WPM Setting: 85 (±25)
📋 Clipboard: Empty

[INFO] 🎹 Setting up enhanced hotkey controls...
[INFO] 🔐 Testing accessibility permissions...

✅ Success Indicators

Look for these messages indicating successful setup:

# Primary hotkeys registered successfully:
[INFO] ✅ F1 - Slow Mode (50 WPM)
[INFO] ✅ F2 - Normal Mode (85 WPM)
[INFO] ✅ F3 - Fast Mode (120 WPM)
[INFO] ✅ F4 - Custom 100 WPM
[INFO] ✅ F5 - Custom 150 WPM
[INFO] ✅ F8 - Pause
[INFO] ✅ F9 - Resume/General Start
[INFO] ✅ F10 - Stop

[SUCCESS] 🎉 8/8 hotkeys registered!

⚠️ Fallback Mode

If primary hotkeys fail, look for:

[INFO] 🔄 Trying alternative hotkey combinations...
[INFO] ✅ Ctrl+Shift+1 - Slow Mode (50 WPM)
[INFO] ✅ Ctrl+Shift+2 - Normal Mode (85 WPM)
# ... additional alternative hotkeys

❌ Manual Mode Fallback

If all hotkeys fail:

[INFO] 📝 Hotkey setup failed. Starting Manual Mode...
[INFO] 🍎 Manual mode works without accessibility permissions!

============================================================
           📝 MANUAL MODE - macOS Compatible
============================================================

📝 Step 3: First Typing Test

🧪 Basic Functionality Test

  1. Prepare Test Text

    # Copy simple test text to clipboard
echo "Hello, AutoTyper! This is a test message with punctuation, numbers like 123, and special characters: @#$%." | pbcopy

  2. Start AutoTyper

    python3 autotyper.py

# If using hotkeys: Press F2 (Normal mode)
# If using manual mode: Press Enter or type '2'

  3. Position Your Cursor

    • Open TextEdit or any text application
    • Click where you want the text to appear
    • Wait for the 3-second countdown

  4. Observe Typing Behavior

    [INFO] ⏰ Typing starts in 3 seconds... Position your cursor!
[INFO] ⏱️  3...
[INFO] ⏱️  2...
[INFO] ⏱️  1...
[INFO] 🚀 Starting to type 84 characters...
[INFO] ⚡ Target WPM: 85 (±25)
[INFO] 🌊 Starting with 'steady' typing flow

🎯 What to Look For

✅ Correct Behavior

  • Text appears character by character
  • Natural pauses at punctuation
  • Longer pauses at sentence endings
  • Occasional speed variations
  • Special characters typed correctly

❌ Potential Issues

  • Text appears all at once (not character-by-character)
  • Special characters missing or incorrect
  • No pauses or unnatural timing
  • Application crashes or freezes

⚡ Step 4: Speed Calibration and Testing

🎯 Test Different Speed Modes

Test Slow Mode (50 WPM)

# Copy test text
echo "Slow typing test with careful precision." | pbcopy

# Use hotkey F1 or manual mode option '1'
# Observe: Should type slowly and deliberately

Test Normal Mode (85 WPM)

# Copy test text  
echo "Normal typing speed for everyday use." | pbcopy

# Use hotkey F2 or manual mode option '2'
# Observe: Should feel like natural typing speed

Test Fast Mode (120 WPM)

# Copy test text
echo "Fast typing for quick document creation." | pbcopy

# Use hotkey F3 or manual mode option '3'  
# Observe: Should type quickly but still naturally

Test Custom Speeds

# Copy test text
echo "Custom speed testing with precise WPM control." | pbcopy

# Use F4 (100 WPM) or F5 (150 WPM)
# Or in manual mode, type any number: '75', '200', etc.

📊 Speed Comparison Table

Mode WPM Character Delay Best For
Slow 50 200-300ms Precision typing, learning
Normal 85 100-150ms General use, documents
Fast 120 70-100ms Quick content, familiar text
Custom 100 100 80-120ms Professional speed
Custom 150 150 50-80ms Advanced users

🎮 Step 5: Hotkey Mastery

📚 Hotkey Reference Card

Create this reference card for quick access:

╔══════════════════════════════════════════╗
║         AUTOTYPER HOTKEY REFERENCE       ║
╠══════════════════════════════════════════╣
║  SPEED MODES:                           ║
║  F1  → 🐌 Slow (50 WPM)                ║
║  F2  → ⚡ Normal (85 WPM)               ║  
║  F3  → 🚀 Fast (120 WPM)               ║
║  F4  → 🎯 Custom (100 WPM)             ║
║  F5  → 🎯 Custom (150 WPM)             ║
║                                         ║
║  PLAYBACK CONTROLS:                     ║
║  F8  → ⏸️  Pause typing                ║
║  F9  → ▶️  Resume/Start                ║
║  F10 → ⏹️  Stop typing                 ║
║                                         ║
║  ALTERNATIVES (if F-keys fail):         ║
║  Ctrl+Shift+1-5 → Speed modes          ║
║  Ctrl+Shift+8-0 → Playback controls    ║
╚══════════════════════════════════════════╝

🧪 Hotkey Testing Routine

  1. Test Each Speed Mode

    # Copy the same text
echo "Testing hotkey speed: The quick brown fox jumps over the lazy dog." | pbcopy

# Try each hotkey in sequence:
# F1 → Watch slow typing
# F2 → Watch normal typing  
# F3 → Watch fast typing
# F4 → Watch 100 WPM
# F5 → Watch 150 WPM

  2. Test Playback Controls

    # Copy longer text
echo "This is a longer text to test playback controls. We can pause, resume, and stop the typing process. This demonstrates the full control system." | pbcopy

# Start typing with F2
# After a few words, press F8 to pause
# Press F9 to resume
# Press F10 to stop completely

🔧 Step 6: Configuration Customization

⚙️ Basic Configuration Options

Edit autotyper.py to customize default settings:

# WPM Configuration (around line 18)
DEFAULT_BASE_WPM = 85      # Change default speed
WPM_VARIATION = 0.3        # ±30% variation (0.1 = ±10%)
FATIGUE_FACTOR = 0.12      # Gradual slowdown (0.05 = less fatigue)
BURST_CHANCE = 0.10        # Fast bursts (0.15 = more bursts)
HESITATION_CHANCE = 0.04   # Thinking pauses (0.08 = more pauses)

# Enhanced timing
MICRO_PAUSE_CHANCE = 0.15  # Tiny hesitations
RHYTHM_VARIATION = 0.4     # Keystroke variations

🎯 Create Personal Profiles

Create a config.py file for personal settings:

# config.py - Personal AutoTyper Configuration

# Professional Profile
PROFESSIONAL_CONFIG = {
    'base_wpm': 95,
    'variation': 0.2,        # Less variation for consistency
    'fatigue': 0.08,         # Less fatigue for longer sessions
    'bursts': 0.05,          # Fewer bursts for professionalism
    'hesitation': 0.02       # Minimal hesitation
}

# Casual Profile  
CASUAL_CONFIG = {
    'base_wpm': 75,
    'variation': 0.4,        # More natural variation
    'fatigue': 0.15,         # Normal fatigue
    'bursts': 0.12,          # More bursts
    'hesitation': 0.06       # More thinking pauses
}

# Learning Profile
LEARNING_CONFIG = {
    'base_wpm': 45,
    'variation': 0.5,        # High variation for learning
    'fatigue': 0.20,         # More fatigue simulation
    'bursts': 0.03,          # Fewer bursts
    'hesitation': 0.10       # More thinking time
}

✅ Step 7: Verification and Testing

🧪 Complete System Test

Run this comprehensive test to verify everything works:

# Create test script
cat > test_autotyper.sh << 'EOF'
#!/bin/bash

echo "🧪 AutoTyper System Test"
echo "========================"

# Test 1: Clipboard functionality
echo "Test 1: Clipboard integration"
echo "Sample test text for AutoTyper verification." | pbcopy
echo "✅ Test text copied to clipboard"

# Test 2: Application launch
echo "Test 2: Application launch"
timeout 5 python3 autotyper.py --test 2>/dev/null || echo "⚠️  Manual testing required"

# Test 3: Dependency check
echo "Test 3: Dependency verification"
python3 -c "import pyautogui, pyperclip, keyboard; print('✅ All dependencies available')" 2>/dev/null || echo "❌ Missing dependencies"

echo "🎯 Manual tests required:"
echo "   - Hotkey functionality (F1-F10)"
echo "   - Typing speed accuracy"
echo "   - Human-like behavior"
echo "   - Accessibility permissions"

EOF

chmod +x test_autotyper.sh
./test_autotyper.sh

📋 Final Checklist

  • ✅ Accessibility permissions granted
  • ✅ AutoTyper launches without errors
  • ✅ Hotkeys register successfully (or manual mode works)
  • ✅ Clipboard integration functions
  • ✅ Text types character-by-character
  • ✅ Different speed modes work correctly
  • ✅ Playback controls (pause/resume/stop) function
  • ✅ Human-like timing patterns observed
  • ✅ Special characters handled correctly
  • ✅ Multi-line text supported

🎓 Next Steps

After completing the first-time setup:

  1. 📖 Learn Advanced Features: Advanced Features Guide
  2. 🎮 Master Hotkey Combinations: Hotkey Configuration
  3. ⚡ Optimize Speed Settings: Speed Customization
  4. 📝 Explore Use Cases: Usage Examples
  5. 🔧 Troubleshoot Issues: Troubleshooting Guide

🆘 Getting Help

If you encounter issues during setup:

Congratulations! 🎉 You've successfully set up AutoTyper and are ready to experience human-like automated typing on macOS!

Clone this wiki locally