mouseloop

1. Introduction and Purpose

mouseloop is a simple desktop utility that records mouse clicks (location and button) and then replays those clicks in a continuous loop until stopped. It runs in the terminal and is controlled entirely by a few keys:

• Press r to start recording clicks.
• Press Esc to stop recording or stop playback.
• Press p to start looping playback of the recorded clicks.
• Press q to quit the program.

Purpose & Problem Statement

Many repetitive computer tasks require clicking the same spots over and over. This script records the positions of those clicks once and then replays them on repeat, hands-free.

Value Proposition

• Save time on repetitive clicking (e.g., form submissions, button confirmations).
• No complex setup: run a single Python file, press a few keys.
• Predictable timing: playback preserves the timing gaps between recorded clicks.

---

2. Dependencies (Required Software/Libraries)

The script is a single file: main.py.

Runtime

• Python 3.7+ Needed to run the script.

  • Download: https://www.python.org/downloads/

  • Verify install:

    python --version

    or on some systems:

    python3 --version

Python Libraries

• pynput Used to listen for keyboard and mouse input and to control the mouse for playback.

  • Install (after Python is installed):

    pip install pynput

    or:

    python -m pip install pynput

    or on some systems:

    pip3 install pynput

System Permissions (important)

• Windows: usually works out of the box.

• macOS: grant the terminal app Accessibility permissions:

  • System Settings → Privacy & Security → Accessibility → enable access for your terminal/IDE.

• Linux: requires an active desktop session (e.g., X11/Wayland). Some environments may need additional permissions to control input devices.

No other external software is required beyond Python and pynput.

---

3. Getting Started (Installation & Execution)

Download the repository

1. On the GitHub page, click the green “<> Code” button.
2. Click “Download ZIP.”
3. Extract the ZIP to a folder (e.g., Downloads/mouseloop/).

Open a terminal/command prompt

• Windows: Press Win + R, type cmd, press Enter.
• macOS: Open Terminal from Applications → Utilities.
• Linux: Open Terminal from the applications menu.

Navigate to the project folder

Use the cd command to change directories to the extracted folder. For example:

cd ~/Downloads/mouseloop

(Adjust the path to where you extracted the ZIP.)

Install the dependency

pip install pynput

Run the program

python main.py

(If your system uses python3, run python3 main.py.)

You will see:

Instructions:
- Press 'r' to start recording
- Press 'p' to start playback loop
- Press 'Esc' during recording/playback to stop them
- Press 'q' to quit

---

4. User Guide (How to Effectively Use the Program)

Controls

• r — Start recording mouse clicks.

  • The program prints: [Recording] Press 'Esc' to stop...
  • Click anywhere on the screen. Each press is recorded with position and button.
  • Press Esc to stop recording.

• p — Start playback loop.

  • Playback begins after a 3-second countdown.
  • The script moves the mouse to each recorded position and clicks, preserving the recorded timing between clicks.
  • At the end of the sequence, it restarts automatically (loops) until stopped.
  • Press Esc to stop playback.

• q — Quit the program at any time. This stops recording/playback and exits.

Inputs

• Mouse click presses only (left or right) are recorded.
• The exact screen coordinates of each click are captured.
• Timing between clicks is captured (used during playback).

Outputs

• Console messages confirm actions, for example:

  [Recording] Press 'Esc' to stop...
  Recorded click at (512, 430) with left
  Recorded click at (890, 742) with right
  [Recording stopped]
  [Playback] Starting in 3 seconds... Press 'Esc' to stop.
  [Playback] One loop finished. Restarting...
  

Configuration & Options

• There are no config files, flags, or environment variables. Behavior is fixed and controlled by keys as described.

Important Notes & Limitations

• Absolute positions: Playback uses the recorded screen coordinates. It is best used on the same screen setup and resolution as recording.

• Click types: The script maps:

  • "left" → left click

  • Any other button → right click

    Middle or extra buttons will be replayed as right click.

• No cursor movement recording: It does not record continuous mouse movement or scroll. Only click presses are recorded.

• Stop behavior: Press Esc during recording or playback to stop that activity; press q to exit the program entirely.

---

5. Use Cases and Real-World Examples

The examples below reflect exactly what the script supports: recording mouse clicks and looping playback with preserved timing.

1) Repeating a two-button confirmation flow

Scenario: An app requires clicking “Open” then “Confirm” repeatedly.

• Steps:

  1. Run python main.py.
  2. Press r.
  3. Click the “Open” button (left click).
  4. Wait 1 second.
  5. Click the “Confirm” button (left click).
  6. Press Esc to stop recording.
  7. Press p to start playback.

• Expected behavior: After a 3-second delay, the script left-clicks “Open,” waits ~1 second, left-clicks “Confirm,” then repeats the two clicks in a loop.

2) Alternating left/right actions

Scenario: A tool uses left click to select and right click to finalize, repeated many times.

• Steps:

  1. Press r.
  2. Left click the target area.
  3. Wait ~0.5 seconds.
  4. Right click the confirmation area.
  5. Press Esc.
  6. Press p.

• Expected behavior: The script replays left then right clicks with the same delay, looping continuously.

3) Scheduled batch confirmation with natural pauses

Scenario: A sequence of three left clicks spaced a few seconds apart is needed.

• Steps:

  1. Press r.
  2. Left click area A.
  3. Wait 2 seconds.
  4. Left click area B.
  5. Wait 3 seconds.
  6. Left click area C.
  7. Press Esc.
  8. Press p.

• Expected behavior: Playback honors the 2-second and 3-second waits between clicks and repeats the three-click cycle.

---

6. Disclaimer & Important Notices

• The repository and its contents may be updated at any time without notice.
• Updates may render portions of this README inaccurate or out of date.
• There is no commitment to maintain or update this README to reflect future changes.
• The code is provided “as-is.” No guarantees are made regarding functionality, reliability, compatibility, or correctness.