MP-Server/README.md

MacroPad Server

A cross-platform macro management application with desktop and web interfaces. Create powerful command sequences with delays, key presses, and text input - accessible locally or remotely via a PWA-enabled web interface.

Features

Macro Capabilities

• Command Sequences: Build multi-step macros with:
  • Text: Type text strings
  • Keys: Press individual keys (Enter, Tab, Escape, etc.)
  • Hotkeys: Key combinations (Ctrl+C, Alt+Tab, etc.)
  • Wait: Insert delays between commands (in milliseconds)
  • App: Launch applications or scripts
• Custom Images: Assign images to macros for easy identification
• Category Management: Organize macros into custom tabs

Interfaces

• Desktop GUI: Modern PySide6/Qt interface with visual command builder
• Web Interface: PWA-enabled for installation on any device
• System Tray: Minimize to tray, always accessible

Additional Features

• QR Code Generation: Quickly connect mobile devices
• Real-time Sync: WebSocket updates across all connected devices
• Offline Support: PWA caches for offline macro viewing
• Dark Theme: Modern dark interface throughout
• Auto-Migration: Existing macros automatically upgraded to new format

Requirements

• Python 3.11+
• Dependencies managed via pyproject.toml

Core Dependencies

• PySide6 (Desktop GUI)
• FastAPI + Uvicorn (Web server)
• PyAutoGUI (Keyboard automation)
• Pillow (Image processing)
• pystray (System tray)
• netifaces (Network detection)
• qrcode (QR code generation)

Installation

Method 1: Using uv (Recommended)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://repo.anhonesthost.net/MacroPad/MP-Server.git
cd MP-Server
uv sync

Method 2: Using pip

git clone https://repo.anhonesthost.net/MacroPad/MP-Server.git
cd MP-Server
pip install -e .

Method 3: Pre-built Executables

1. Go to the Releases page
2. Download for your operating system:
   • Windows: macropad.exe
   • Linux: macropad
   • macOS: MacroPad Server.app
3. Run the downloaded file

Important

Executables are unsigned and may trigger security warnings. You may need to:

• Windows: Click "More info" → "Run anyway" in SmartScreen
• Linux: Run chmod +x macropad before executing
• macOS: Right-click → Open, or adjust Gatekeeper settings

Usage

Running the Application

# If installed with uv
uv run python main.py

# If installed with pip
python main.py

Creating a Macro

1. Click + Add Macro in the toolbar
2. Enter a Name and optional Category
3. Build your command sequence using the buttons:
   • + Text: Add text to type
   • + Key: Add a key press (enter, tab, escape, etc.)
   • + Hotkey: Add a key combination (ctrl+c, alt+tab)
   • + Wait: Add a delay in milliseconds
   • + App: Add an application to launch
4. Reorder commands with Up/Down buttons
5. Click Save

Example: Login Macro

A macro that types a username, waits, presses Tab, types a password, and presses Enter:

[TEXT]   myusername
[WAIT]   200ms
[KEY]    tab
[TEXT]   mypassword
[KEY]    enter

Web Interface (PWA)

1. Start the application (web server starts automatically on port 40000)
2. Note the URL shown in the toolbar (e.g., http://192.168.1.100:40000)
3. Open this URL on any device on your network
4. Install as PWA:
   • Mobile: Tap browser menu → "Add to Home Screen"
   • Desktop: Click install icon in address bar

The web interface provides full macro management:

• View and execute macros
• Create and edit macros with command builder
• Organize into categories
• Real-time sync across devices

System Tray

• Minimize window → App continues in tray
• Right-click tray icon:
  • Show: Restore window
  • Quit: Exit application

Command Types Reference

Type	Description	Parameters
text	Types a text string	value: The text to type
key	Presses a single key	value: Key name (enter, tab, escape, f1-f12, etc.)
hotkey	Presses key combination	keys: List of keys (e.g., ["ctrl", "c"])
wait	Delays execution	ms: Milliseconds to wait
app	Launches application	command: Shell command to execute

Example Application Commands

Windows

# Steam game
"C:\Program Files (x86)\Steam\steam.exe" steam://rungameid/2767030

# Chrome to website
"C:\Program Files\Google\Chrome\Application\chrome.exe" https://example.com

# Open folder
explorer.exe "C:\Users\YourUsername\Documents"

Linux

# Firefox
firefox https://example.com

# Steam game
steam steam://rungameid/2767030

# Terminal
gnome-terminal

macOS

# Safari
open -a Safari https://example.com

# VS Code
open -a "Visual Studio Code"

# Folder
open ~/Documents

Building Executables

Build platform-specific executables using PyInstaller:

# Install PyInstaller
pip install pyinstaller

# Windows (run on Windows)
pyinstaller macropad.spec

# Linux (run on Linux)
pyinstaller macropad_linux.spec

# macOS (run on macOS)
pyinstaller macropad_macos.spec

Note

PyInstaller cannot cross-compile. You must build on the target platform.

Project Structure

MP-Server/
├── main.py              # Application entry point
├── config.py            # Configuration constants
├── macro_manager.py     # Macro storage and execution
├── web_server.py        # FastAPI web server
├── pyproject.toml       # Dependencies and build config
├── gui/                 # PySide6 desktop interface
│   ├── main_window.py
│   ├── macro_editor.py
│   └── command_builder.py
├── web/                 # PWA web interface
│   ├── index.html
│   ├── manifest.json
│   ├── service-worker.js
│   ├── css/styles.css
│   ├── js/app.js
│   └── icons/
└── macros.json          # Macro storage (auto-created)

Migrating from v0.8.x

Existing macros are automatically migrated on first run. The old format:

{
  "type": "text",
  "command": "Hello",
  "modifiers": {"enter": true}
}

Becomes the new command sequence format:

{
  "type": "sequence",
  "commands": [
    {"type": "text", "value": "Hello"},
    {"type": "key", "value": "enter"}
  ]
}

License

MIT License

Acknowledgments

Special thanks to CatArgent_ on Twitch for proofreading and providing valuable feedback.