MacroPad/MP-Server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Modernize application to v0.9.0 with PySide6, FastAPI, and PWA support

Browse Source 
## Major Changes

### Build System
- Replace requirements.txt with pyproject.toml for modern dependency management
- Support for uv package manager alongside pip
- Update PyInstaller spec files for new dependencies and structure

### Desktop GUI (Tkinter → PySide6)
- Complete rewrite of UI using PySide6/Qt6
- New modular structure in gui/ directory:
  - main_window.py: Main application window
  - macro_editor.py: Macro creation/editing dialog
  - command_builder.py: Visual command sequence builder
- Modern dark theme with consistent styling
- System tray integration

### Web Server (Flask → FastAPI)
- Migrate from Flask/Waitress to FastAPI/Uvicorn
- Add WebSocket support for real-time updates
- Full CRUD API for macro management
- Image upload endpoint

### Web Interface → PWA
- New web/ directory with standalone static files
- PWA manifest and service worker for installability
- Offline caching support
- Full macro editing from web interface
- Responsive mobile-first design
- Command builder UI matching desktop functionality

### Macro System Enhancement
- New command sequence model replacing simple text/app types
- Command types: text, key, hotkey, wait, app
- Support for delays between commands (wait in ms)
- Support for key presses between commands (enter, tab, etc.)
- Automatic migration of existing macros to new format
- Backward compatibility maintained

### Files Added
- pyproject.toml
- gui/__init__.py, main_window.py, macro_editor.py, command_builder.py
- gui/widgets/__init__.py
- web/index.html, manifest.json, service-worker.js
- web/css/styles.css, web/js/app.js
- web/icons/icon-192.png, icon-512.png

### Files Removed
- requirements.txt (replaced by pyproject.toml)
- ui_components.py (replaced by gui/ modules)
- web_templates.py (replaced by web/ static files)
- main.spec (consolidated into platform-specific specs)

### Files Modified
- main.py: Simplified entry point for PySide6
- macro_manager.py: Command sequence model and migration
- web_server.py: FastAPI implementation
- config.py: Version bump to 0.9.0
- All .spec files: Updated for PySide6 and new structure
- README.md: Complete rewrite for v0.9.0
- .gitea/workflows/release.yml: Disabled pending build testing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
jknapp
2026-01-03 16:57:14 -08:00
parent ded281cc64
commit 5888aeb603
29 changed files with 3436 additions and 1604 deletions
Download Patch File Download Diff File Expand all files Collapse all files

301
README.md
View File

@@ -1,164 +1,261 @@
# MacroPad Server
A versatile MacroPad server application that lets you create, manage, and execute custom macros from both a local interface and remotely via a web interface.
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
- **Text Macros**: Insert frequently used text snippets with a single click
- **Application Macros**: Launch applications or scripts directly
- **Key Modifiers**: Add Ctrl, Alt, Shift modifiers and Enter keypress to your text macros
### 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 for better organization
- **Web Interface**: Access and trigger your macros from other devices on your network
- **System Tray Integration**: Minimize to tray when minimized, exit when closed
- **QR Code Generation**: Quickly connect mobile devices to the web interface
- **Sorting Options**: Sort macros by name, type, or recent usage
- **Persistent Storage**: Macros are automatically saved for future sessions
- **Dark Theme**: Modern dark interface for comfortable use
- **Modular Architecture**: Clean separation of concerns with dedicated modules
- **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+
- Required Python packages (install via requirements.txt):
- tkinter
- flask
- pyautogui
- pystray
- Pillow (PIL)
- waitress
- netifaces
- qrcode
- 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: From Source
### Method 1: Using uv (Recommended)
1. Clone or download this repository
2. Install the required dependencies:
```bash
pip install -r requirements.txt
# 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: Pre-built Executables
### Method 2: Using pip
```bash
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](https://repo.anhonesthost.net/MacroPad/MP-Server/releases) page
2. Download the appropriate version for your operating system:
2. Download for your operating system:
- Windows: `macropad.exe`
- Linux: `macropad`
- macOS: `macropad.app`
- macOS: `MacroPad Server.app`
3. Run the downloaded file
> [!IMPORTANT]
> The executables are unsigned and may trigger security warnings. You may need to click "More info" and "Run anyway" in Windows SmartScreen, adjust permissions on Linux (`chmod +x macropad`), or override Gatekeeper on macOS.
> 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
### Main Interface
### Running the Application
When launched, MacroPad displays your existing macros with options to:
```bash
# If installed with uv
uv run python main.py
- **Add New Macro**: Create text snippets or application shortcuts
- **Edit Macro**: Modify existing macros
- **Delete Macro**: Remove unwanted macros
- **Sort Options**: Sort the Macros by type, name, and recent usage
- **Manage Tabs**: Assign categories to macros for better organization
- **Start Web Server**: Starts the web server to serve the MacroPad web interface.
# If installed with pip
python main.py
```
### Creating a Macro
1. Click the "Add Macro" button
2. Fill in the details:
- **Name**: A descriptive name for your macro
- **Category**: Assign a category to associate with a tab
- **Type**: Choose between Text or Application
- **Command/Text**: The text to insert or application command to run
- **Modifiers**: Select any combination of Ctrl, Alt, Shift, and Enter
- **Image**: Optionally add an image for visual identification
3. Click "Save" to create your 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**
### Remote Access
### Example: Login Macro
The application runs a web server enabling remote access:
A macro that types a username, waits, presses Tab, types a password, and presses Enter:
1. Note your computer's local IP address (shown in the application header)
2. From another device on the same network, open a web browser
3. Navigate to `http://<your-ip-address>:40000`
4. Click on any macro to execute it on your main computer
```
[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
When minimized to the system tray:
- Right-click the tray icon to show options
- Select "Show" to restore the window
- Select "Exit" to close the application
- 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 Examples
#### Steam Applications
```
### Windows
```bash
# Steam game
"C:\Program Files (x86)\Steam\steam.exe" steam://rungameid/2767030
```
#### Chrome to a website
```
"C:\Program Files\Google\Chrome\Application\chrome.exe" http://twitch.tv/shadowdao
```
# Chrome to website
"C:\Program Files\Google\Chrome\Application\chrome.exe" https://example.com
#### Run Notepad
```
notepad.exe
```
#### Open File Explorer to a specific location
```
# Open folder
explorer.exe "C:\Users\YourUsername\Documents"
```
### Linux Examples
#### Opening Firefox
```
### Linux
```bash
# Firefox
firefox https://example.com
```
#### Opening Steam
```
# Steam game
steam steam://rungameid/2767030
```
#### Launch Terminal
```
# Terminal
gnome-terminal
```
#### Open File Manager
```
nautilus ~/Documents
```
### macOS Examples
#### Opening Safari
```
### macOS
```bash
# Safari
open -a Safari https://example.com
```
#### Opening Terminal
```
open -a Terminal
```
# VS Code
open -a "Visual Studio Code"
#### Open Finder to a specific location
```
# Folder
open ~/Documents
```
#### Launch Applications
```
open -a "Visual Studio Code"
## Building Executables
Build platform-specific executables using PyInstaller:
```bash
# 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
```
#### Special Thanks to CatArgent_ on Twitch for proof reading my stuff and providing valuable feedback.
> [!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:
```json
{
"type": "text",
"command": "Hello",
"modifiers": {"enter": true}
}
```
Becomes the new command sequence format:
```json
{
"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.