saMacros Icon
saMacros
v2.0.0 Scripting Guide API Docs
S

saMacros

A High-Performance Desktop Automation Platform

saMacros lets you record and replay any sequence of mouse & keyboard actions on your desktop — with precise timing, loop control, and an intuitive pause/resume workflow.

Pause & Resume 7+ Languages JDK 21+ Apache 2.0
⏺

Record Actions

Capture any mouse click, scroll, or keystroke into a reusable macro file.

▶

Replay Precisely

Replay macros with exact timing, loop count, and Quick Mode for speed.

🚀 Quick Start

1 — Installation

Option A · JAR

  1. 1Install JDK 21+ from Oracle or Adoptium.
  2. 2Download the latest .jar from Releases.
  3. 3Double-click the jar, or run:
java -jar saMacros.jar

Option B · EXE (Windows)

  1. 1Download the latest .exe from Releases.
  2. 2Double-click to launch — JRE is bundled.
  3. 3Windows may show a SmartScreen warning; click More info → Run anyway.

2 — First Launch Checklist

  • ✓
    Choose your language — open Settings and select a language from the combo box, or enable Follow System Settings.
  • ✓
    Resize if needed — different languages affect button label width. Drag the window edge to fit all buttons.
  • ✓
    Configure hotkeys — open Settings → Macro Settings to customise the Record / Stop / Play / Abort keys (defaults: F2 / F3 / F4 / F5).
  • ✓
    Allow accessibility — on macOS / Linux you may need to grant saMacros accessibility (input monitoring) permission for global hotkeys to work.

3 — Your First Macro in 60 Seconds

  1. 1
    Press F2 (or click Start Recording). The status log shows "Recording started".
  2. 2
    Perform any mouse clicks, scrolls, or key presses on your desktop.
  3. 3
    Press F3 (or click Stop Recording). The log shows the action count.
  4. 4
    Press F4 (or click Play Macro). saMacros reproduces every action with exact timing.
  5. 5
    Click Save Macros to export the recording as a .mmc file for later use.

⏺ Recording a Macro

How saMacros captures your actions in real time.

How Recording Works

When you start recording, saMacros registers a global low-level hook (via JNativeHook) that captures all mouse and keyboard events at the OS level — even when the application window is not focused.

Each captured event is converted into a MouseAction object containing:

Field Description
x, yScreen coordinates
type1=press, 2=release, 3=wheel, 10=key press, 11=key release
buttonMouse button index (1=left, 2=right, 3=middle)
delayMilliseconds elapsed since the previous action
keyCode / awtKeyCodeNative and AWT key codes for keyboard events
wheelAmountScroll distance (wheel events)

⚠ Important Notes

  • Actions are not captured while a macro is playing back (the isReplayingInput flag prevents re-entrant capture).
  • The Save button is disabled while recording to prevent data loss.

▶ Playing Back a Macro

Replay recorded or loaded macros with precision.

Starting Playback

  1. 1Ensure the action list is not empty (record or load first).
  2. 2Press F4 or click Play Macro.
  3. 3saMacros launches a dedicated playback thread and executes each action in order.

Loop & Quick Mode

  • Repeat count — set in Settings → Macro Settings. A value of 0 means loop indefinitely.
  • Quick Mode — skips inter-action delays; actions are executed as fast as the Robot allows. Enable in Settings.

⏸ Pause & Resume

Intelligently interrupt and continue macro execution without losing state.

⏸

Pause

Press F5 during playback. The playback thread suspends at the current action and waits on an internal lock.

▶

Resume

Press F4 while paused. The lock is released and execution continues from exactly where it stopped.

⏹

Abort

Press F5 while already paused. saMacros interrupts the thread and fully resets playback state.

💡 State Machine Summary

Idle → Playing (F4) → Paused (F5) → Resume (F4) → Playing → Done → Idle

Paused → Abort (F5) → Idle

💾 Save & Load Macros

Persist your recordings as .mmc files and reload them any time.

💾 Saving

  1. 1Stop recording (the Save button is disabled during recording).
  2. 2Click Save Macros. A file-chooser dialog opens at your last-used directory.
  3. 3Choose a filename and location. The file is saved as UTF-8 encoded CSV.

📂 Loading

  1. 1Click Load Macro (also disabled during recording).
  2. 2Browse to your .mmc file and confirm.
  3. 3The log shows the number of actions loaded. Press Play to execute.

.mmc File Format

Each line represents one action in CSV format:

x,y,type,button,delay,wheelAmount,keyCode,awtKeyCode
# Example lines:
960,540,1,1,250,0,0,0
960,540,2,1,120,0,0,0
0,0,10,0,80,0,65,65

The loader supports older file formats for backward compatibility.

⚙ Settings

All configuration is stored in %USERPROFILE%/AppData/saMacros/.

General Settings

Setting Config Key Description
Follow System SettingsfollowSystemSettingsAuto-detect system language and dark mode.
LanguagelangUI language: EN, ZH, JA, RU, KO, ES, FR (when not following system).
Dark ModeenableDarkModeEnable/disable dark theme (when not following system).
Default Storage PathdefaultStoragePathPre-fill the Save/Load dialog with this directory.

Macro Settings

Setting Description
Repeat CountNumber of times to loop the macro. 0 = infinite loop.
Quick ModeSkip inter-action delays for maximum speed.
Hotkey — Start RecordingDefault: F2. Click the key capture field and press your desired key.
Hotkey — Stop RecordingDefault: F3
Hotkey — Play / ResumeDefault: F4
Hotkey — Pause / AbortDefault: F5

⌨ Hotkey Reference

Default Key Action Notes
F2 Start Recording Global hotkey; works even when the app window is not focused.
F3 Stop Recording Finalises the recorded action list.
F4 Play Macro / Resume Starts playback, or resumes if currently paused.
F5 Pause / Abort First press pauses; second press (while paused) aborts.

All hotkeys can be remapped in Settings → Macro Settings → Hotkey Configuration.

🔧 Troubleshooting

Common issues and solutions derived from the application's error-handling logic.

! Hotkeys are not working / global input not captured

Cause: saMacros uses JNativeHook to capture global keyboard/mouse events. On some OS configurations, this requires special permissions.

  • macOS: Go to System Preferences → Privacy & Security → Accessibility and add the saMacros executable.
  • Linux: Run as a user with input device access, or add your user to the input group.
  • Windows: Try running as Administrator if UAC is blocking native hooks.
! Playback aborted unexpectedly — "Macro aborted" in log

Cause A — Thread interrupted: The playback thread received an interrupt signal. This can happen if the JVM is shutting down.

Cause B — Exception during action: The log shows "Playback error: [message]". Check the console output for the full stack trace.

  • Re-record the macro on the same screen resolution and layout.
? Macro save failed — "Saving failed" in log

Cause: An IOException occurred while writing the file. The error message appended in the log gives the exact reason.

  • Check that the target directory exists and is writable.
  • Ensure the filename contains no illegal characters.
  • Verify you have sufficient disk space.
i Settings reset to default after update

Cause: If config.cfg cannot be parsed (e.g., it was corrupted or its schema changed), the application automatically calls resetToDefault() and recreates the file.

  • Back up %USERPROFILE%\AppData\saMacros\config.cfg before major version upgrades.
  • After the reset, reconfigure your preferred language, hotkeys, and repeat count in Settings.
i Buttons are cut off / partially hidden

Cause: The selected UI language produces longer button labels that exceed the default window width.

  • Drag the window edge to make it wider.
  • Consider switching to a language with shorter button labels (English is usually the narrowest).