{"id":43608148,"url":"https://github.com/amiable-dev/conductor","last_synced_at":"2026-03-04T10:04:20.967Z","repository":{"id":325535368,"uuid":"1101557911","full_name":"amiable-dev/conductor","owner":"amiable-dev","description":"Multi-protocol input automation for MIDI controllers, game controllers, and custom hardware","archived":false,"fork":false,"pushed_at":"2026-02-17T17:46:33.000Z","size":28745,"stargazers_count":2,"open_issues_count":56,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-17T20:26:16.027Z","etag":null,"topics":["automation","controller-mapping","gamepad","hid","midi","productivity","rust","tauri"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amiable-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T21:11:29.000Z","updated_at":"2026-02-17T16:40:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amiable-dev/conductor","commit_stats":null,"previous_names":["amiable-dev/conductor"],"tags_count":112,"template":false,"template_full_name":null,"purl":"pkg:github/amiable-dev/conductor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amiable-dev%2Fconductor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amiable-dev%2Fconductor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amiable-dev%2Fconductor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amiable-dev%2Fconductor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amiable-dev","download_url":"https://codeload.github.com/amiable-dev/conductor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amiable-dev%2Fconductor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29680147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T11:29:27.227Z","status":"ssl_error","status_checked_at":"2026-02-21T11:29:20.292Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","controller-mapping","gamepad","hid","midi","productivity","rust","tauri"],"created_at":"2026-02-04T10:57:23.890Z","updated_at":"2026-02-21T12:06:02.005Z","avatar_url":"https://github.com/amiable-dev.png","language":"HTML","readme":"# Conductor\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)\n[![Build Status](https://github.com/amiable-dev/conductor/workflows/CI/badge.svg)](https://github.com/amiable-dev/conductor/actions)\n[![codecov](https://codecov.io/gh/amiable-dev/conductor/branch/main/graph/badge.svg)](https://codecov.io/gh/amiable-dev/conductor)\n[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://amiable-dev.github.io/conductor/)\n\nTransform MIDI controllers and game controllers into advanced macro pads with multi-protocol input, velocity sensitivity, LED feedback, daemon architecture, visual configuration GUI, and LLM-powered natural language configuration.\n\n**v4.11.0**: LLM Integration - Chat UI, MCP Server, Agent Skills for natural language configuration\n**v3.0.0**: Multi-protocol input support - MIDI Controllers + Game Controllers (HID)\n**v2.0.0**: Full-featured Tauri GUI with MIDI Learn, per-app profiles, device templates, and live event console\n**v1.0.0**: Production-ready daemon with 0-10ms config reloads, IPC control, and auto-start support\n\n![Conductor Demo](docs/images/hero-demo.gif)\n*Velocity-sensitive RGB LED feedback on Native Instruments Maschine Mikro MK3*\n\n## Features\n\n### Multi-Protocol Input (v3.0.0 NEW!)\n\nConductor now supports multiple input protocols through a unified input system:\n\n#### MIDI Controllers (v1.0+)\n- **Full MIDI Support** - All MIDI message types (Note, CC, Aftertouch, Pitch Bend)\n- **RGB LED Feedback** - Full HID-based LED control for supported devices\n- **Velocity Sensitivity** - Different actions for soft/medium/hard presses\n- **Device Templates** - 6 built-in templates for popular MIDI controllers\n\n#### Game Controllers (HID) (v3.0+)\n- **Gamepads**: Xbox (360, One, Series X|S), PlayStation (DualShock 4, DualSense), Switch Pro Controller\n- **Joysticks**: Flight sticks, arcade sticks (any SDL2-compatible device)\n- **Racing Wheels**: Logitech, Thrustmaster, any SDL2-compatible racing wheel\n- **HOTAS**: Hands On Throttle And Stick systems\n- **Custom Controllers**: Any SDL2-compatible HID device\n- **Official Templates**: 3 built-in templates (Xbox, PlayStation, Switch Pro)\n- **Analog Support**: Triggers, analog sticks with threshold detection\n- **Button Chords**: Multi-button combinations for complex macros\n\n#### Unified Input System\n- **Hybrid Workflows** - Use MIDI controller + gamepad simultaneously\n- **Hot-Plug Detection** - Automatic device connection/disconnection handling\n- **MIDI Learn Mode** - One-click auto-detection works with both MIDI and gamepad inputs\n- **Protocol-Agnostic** - Same event processing for all input types\n- **Non-Overlapping IDs** - MIDI (0-127), Gamepad (128-255), no conflicts\n\n### Visual Configuration (v2.0.0)\n- **Tauri GUI** - Modern desktop application for visual configuration\n- **MIDI Learn Mode** - One-click auto-detection of MIDI and gamepad inputs\n- **Device Templates** - 9 built-in templates (6 MIDI + 3 gamepad)\n- **Per-App Profiles** - Automatic profile switching based on active application\n- **Live Event Console** - Real-time input event monitoring and debugging\n- **Settings Panel** - Configure auto-start, theme, and preferences\n\n### LLM Integration (v4.11.0 NEW!)\n- **Chat UI** - Natural language interface for configuration assistance\n- **Multi-Provider Support** - OpenAI (GPT-4) and Anthropic (Claude) providers\n- **Agent Skills** - Bundled skills for MIDI mapping, Learn mode, and device setup\n- **MCP Server** - Model Context Protocol server for external LLM agent access\n- **Secure API Keys** - System keychain storage for API credentials\n- **Tool Calling** - LLMs can query daemon state via ReadOnly tools\n\n\u003e 📖 **See [ADR-007](docs/adrs/ADR-007-llm-integration-architecture.md) for complete LLM integration architecture**\n\n### Core Features\n- **Background Daemon** - Runs as a system service with auto-start\n- **Hot-Reload** - Configuration changes detected and applied in 0-10ms\n- **IPC Control** - Control daemon via `conductorctl` CLI or GUI\n- **Multi-mode operation** - Switch between different mapping sets\n- **Configurable mappings** - Visual editor or TOML-based configuration\n- **Ultra-low latency** - Sub-millisecond input response, \u003c20ms config reload\n- **Cross-platform** - Works on macOS and Linux (systemd/launchd)\n\n### Enhanced Event Detection\n- **Velocity Sensitivity** - Different actions for soft/medium/hard presses\n- **Long Press Detection** - Hold actions with configurable thresholds\n- **Double-Tap Detection** - Quick double-tap triggers\n- **Chord Detection** - Multiple buttons/pads pressed simultaneously\n- **Encoder Direction** - Clockwise/counter-clockwise detection\n- **Analog Sticks** - Directional detection with dead zones\n- **Analog Triggers** - Threshold-based trigger actions\n- **Aftertouch Support** - Pressure-sensitive actions (MIDI)\n- **Pitch Bend Support** - Touch strip integration (MIDI)\n\n### LED Feedback System\n- **Visual Feedback** - Real-time LED feedback on supported MIDI devices\n- **Multiple Schemes** - Rainbow, pulse, breathing, reactive, and more\n- **Mode Indication** - Color-coded modes for easy identification\n- **Velocity Visualization** - LED brightness matches pad velocity\n- **HID Support** - Full RGB control for Maschine Mikro MK3\n- **MIDI LED** - Basic feedback for standard MIDI devices\n\n\u003e 📖 **See the [LED Feedback Guide](https://amiable-dev.github.io/conductor/configuration/led-feedback.html) for complete LED system documentation**\n\n## Hardware Compatibility\n\n### MIDI Controllers\n\n| Device | Status | LED Feedback | Notes |\n|--------|--------|--------------|-------|\n| Native Instruments Maschine Mikro MK3 | ✅ Full Support | RGB (HID) | Recommended |\n| Generic MIDI Controllers | ✅ Supported | Basic (MIDI) | Most features work |\n| Akai APC Mini | ⚠️ Untested | Basic (MIDI) | Should work |\n| Novation Launchpad | ⚠️ Untested | Basic (MIDI) | Should work |\n\n### Game Controllers (v3.0+)\n\n#### Gamepads (Official Templates Available)\n\n| Controller | Template | Status | Platform Compatibility |\n|-----------|----------|--------|----------------------|\n| Xbox Controller (360, One, Series X\\|S) | ✅ Official | ✅ Full Support | Windows, macOS, Linux |\n| PlayStation Controller (DualShock 4, DualSense) | ✅ Official | ✅ Full Support | Windows, macOS, Linux |\n| Nintendo Switch Pro Controller | ✅ Official | ✅ Full Support | Windows, macOS, Linux |\n| Generic SDL2-Compatible Gamepads | ⚠️ Manual Config | ✅ Supported | Windows, macOS, Linux |\n\n#### Joysticks \u0026 Flight Controllers (Manual Configuration)\n\n| Device Type | Template | Status | Notes |\n|------------|----------|--------|-------|\n| Flight Sticks | ⚠️ Coming Soon | ✅ Supported | Any SDL2-compatible device works |\n| Arcade Sticks | ⚠️ Coming Soon | ✅ Supported | Button mapping via MIDI Learn |\n| HOTAS Systems | ⚠️ Coming Soon | ✅ Supported | Full analog axis support |\n\n#### Racing Wheels (Manual Configuration)\n\n| Device Type | Template | Status | Notes |\n|------------|----------|--------|-------|\n| Logitech Wheels | ⚠️ Coming Soon | ✅ Supported | Steering, pedals, buttons |\n| Thrustmaster Wheels | ⚠️ Coming Soon | ✅ Supported | All SDL2 axes supported |\n| Generic Racing Wheels | ⚠️ Coming Soon | ✅ Supported | Any SDL2-compatible wheel |\n\n**Want to add support for your device?** See [CONTRIBUTING.md](CONTRIBUTING.md#device-support)\n\n## Installation\n\n### From Binary (Recommended)\n\nDownload the latest release for your platform:\n- [macOS (Intel)](https://github.com/amiable-dev/conductor/releases/latest/download/conductor-macos-intel)\n- [macOS (Apple Silicon)](https://github.com/amiable-dev/conductor/releases/latest/download/conductor-macos-arm)\n- [Linux (x86_64)](https://github.com/amiable-dev/conductor/releases/latest/download/conductor-linux-x86_64)\n\n```bash\n# Install binaries\nsudo install -m 755 conductor /usr/local/bin/\nsudo install -m 755 conductorctl /usr/local/bin/\n\n# macOS: Install as LaunchAgent\nlaunchctl load ~/Library/LaunchAgents/com.amiable.conductor.plist\n\n# Linux: Install as systemd service\nsystemctl --user enable conductor\nsystemctl --user start conductor\n```\n\nSee the [installation guide](https://amiable-dev.github.io/conductor/installation/macos.html) for complete setup instructions.\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/amiable-dev/conductor.git\ncd conductor\n\n# Build the workspace (all 3 packages)\ncargo build --release --workspace\n\n# Install binaries\nsudo install -m 755 target/release/conductor /usr/local/bin/\nsudo install -m 755 target/release/conductorctl /usr/local/bin/\n\n# Install man pages\nsudo mkdir -p /usr/local/share/man/man1\nsudo install -m 644 conductor-daemon/docs/*.1 /usr/local/share/man/man1/\n```\n\n**Workspace Structure** (v1.0.0):\n\nConductor uses a modular 3-package Cargo workspace:\n\n```\nconductor/\n├── conductor-core/       # Pure Rust engine library\n│   ├── Public API for embedding (30+ types)\n│   ├── Zero UI dependencies\n│   └── Event processing, mapping, actions\n├── conductor-daemon/     # Background daemon + diagnostic tools\n│   ├── Main daemon binary (conductor)\n│   ├── CLI control tool (conductorctl)\n│   └── 6 diagnostic binaries\n└── conductor/            # Backward compatibility layer\n    └── Re-exports conductor-core (v0.1.0 tests only)\n```\n\n**Package Guide**:\n- **Use conductor-core** when embedding Conductor as a library\n- **Use conductor-daemon** for standalone CLI/daemon usage\n- **Use conductor (root)** only for v0.1.0 backward compatibility\n\n**Public API Example**:\n```rust\nuse conductor_core::{Config, MappingEngine, EventProcessor, ActionExecutor};\n\nlet config = Config::load(\"config.toml\")?;\nlet mut engine = MappingEngine::new();\n// Process MIDI events, map to actions, execute...\n```\n\n**Build Commands**:\n```bash\n# Build entire workspace (all 3 packages)\ncargo build --workspace\n\n# Build specific package\ncargo build -p conductor-core\ncargo build -p conductor-daemon\n\n# Test workspace\ncargo test --workspace\n```\n\n**Requirements:**\n- Rust 1.70+ ([Install via rustup](https://rustup.rs/))\n- macOS 11+ or Linux with systemd\n\n## Quick Start\n\n### Quick Start - MIDI Controllers\n\n#### Daemon Mode (Recommended)\n\n1. **Install binaries** (see Installation above)\n2. **Create config** at `~/.config/conductor/config.toml`\n3. **Start daemon**:\n   ```bash\n   # macOS\n   launchctl load ~/Library/LaunchAgents/com.amiable.conductor.plist\n\n   # Linux\n   systemctl --user start conductor\n   ```\n4. **Control daemon**:\n   ```bash\n   conductorctl status   # Check daemon status\n   conductorctl reload   # Reload configuration\n   conductorctl ping     # Test connectivity\n   ```\n5. **Edit config** - Changes are auto-detected and reloaded in \u003c10ms!\n\n#### Manual Mode (Development/Testing)\n\n1. **Connect your MIDI controller** (e.g., Native Instruments Maschine Mikro MK3)\n2. **Install necessary drivers** (Native Instruments Controller Editor for NI devices)\n3. **Run directly**:\n   ```bash\n   conductor --config config.toml --log-level debug\n   ```\n4. **Press pads** to trigger macros!\n\n### Quick Start - Game Controllers (Template-Based)\n\nFor gamepads with official templates (Xbox, PlayStation, Switch Pro):\n\n1. **Open Conductor GUI** (or use CLI with template config)\n2. **Select Device Template**:\n   - Navigate to \"Device Templates\" section\n   - Filter by category: \"Gamepad Controllers\"\n   - Choose your controller:\n     - **Xbox Controller** (Xbox 360, One, Series X|S)\n     - **PlayStation Controller** (DualShock 4, DualSense)\n     - **Switch Pro Controller**\n3. **Generate Configuration**:\n   - Click \"Create from Template\"\n   - Templates include pre-configured modes:\n     - **Desktop Mode**: Navigation, window management, shortcuts\n     - **Media Mode**: Playback control, volume adjustment\n     - **Additional Modes**: Browser (Switch), Gaming (PlayStation)\n4. **Connect Gamepad** and press buttons to trigger actions\n5. **Customize** via MIDI Learn or manual TOML editing\n\n**Pre-configured Features**:\n- Face buttons → Enter, Escape, Copy, Paste\n- D-Pad → Arrow keys\n- Shoulder buttons → Tab navigation\n- Guide/Home button → Spotlight search\n- Analog triggers → Volume control\n- Button chords → Mode switching\n\n### Quick Start - Game Controllers (Manual Configuration)\n\nFor joysticks, racing wheels, HOTAS, or custom controllers:\n\n1. **Create Base Configuration**:\n   ```bash\n   # Start with minimal config\n   cp config/examples/gamepad-basic.toml ~/.config/conductor/config.toml\n   ```\n\n2. **Use MIDI Learn to Map Buttons**:\n   - Open Conductor GUI\n   - Enable \"MIDI Learn\" mode\n   - Click on a mapping you want to configure\n   - Press the button/axis on your controller\n   - Pattern detection will auto-suggest GamepadButton or GamepadAnalogStick\n   - Save the mapping\n\n3. **Manual TOML Configuration Example**:\n   ```toml\n   [[modes]]\n   name = \"Flight Mode\"\n   color = \"blue\"\n\n   [[modes.mappings]]\n   description = \"Fire primary weapon\"\n   [modes.mappings.trigger]\n   type = \"GamepadButton\"\n   button = 128  # First trigger button\n   [modes.mappings.action]\n   type = \"Keystroke\"\n   keys = \"space\"\n\n   [[modes.mappings]]\n   description = \"Pitch control via stick\"\n   [modes.mappings.trigger]\n   type = \"GamepadAnalogStick\"\n   axis = 129  # Y-axis\n   direction = \"Up\"\n   threshold = 0.5\n   [modes.mappings.action]\n   type = \"Keystroke\"\n   keys = \"w\"\n   ```\n\n4. **Test Your Configuration**:\n   ```bash\n   conductorctl reload\n   # Move sticks, press buttons to trigger actions\n   ```\n\n**Button ID Reference** (for manual config):\n- **Face Buttons**: 128-131\n- **D-Pad**: 132-135\n- **Shoulders**: 136-137 (bumpers), 143-144 (triggers)\n- **Stick Clicks**: 138-139\n- **Menu/System**: 140-142\n- **Analog Axes**: 128-133 (sticks + triggers)\n\n\u003e 📖 **See technical documentation for complete button/axis mapping reference**\n\n## Configuration\n\nEdit `config.toml` to customize your mappings. The enhanced configuration supports:\n\n### Basic Note Trigger (MIDI)\n```toml\n[[modes.mappings]]\ndescription = \"Spotlight Search\"\n[modes.mappings.trigger]\ntype = \"Note\"\nnote = 12\nvelocity_min = 1  # Optional\nvelocity_max = 127  # Optional\n[modes.mappings.action]\ntype = \"Keystroke\"\nkeys = \"space\"\nmodifiers = [\"cmd\"]\n```\n\n### Gamepad Button Trigger (v3.0)\n```toml\n[[modes.mappings]]\ndescription = \"Gamepad A Button\"\n[modes.mappings.trigger]\ntype = \"GamepadButton\"\nbutton = 128  # South button (A/Cross/B)\n[modes.mappings.action]\ntype = \"Keystroke\"\nkeys = \"space\"\n```\n\n### Gamepad Button Chord (v3.0)\n```toml\n[[modes.mappings]]\ndescription = \"Quick Save (LB + A)\"\n[modes.mappings.trigger]\ntype = \"GamepadButtonChord\"\nbuttons = [136, 128]  # LB + A\nmax_interval_ms = 100\n[modes.mappings.action]\ntype = \"Keystroke\"\nkeys = \"s\"\nmodifiers = [\"ctrl\"]\n```\n\n### Gamepad Analog Stick (v3.0)\n```toml\n[[modes.mappings]]\ndescription = \"Left stick up → W key\"\n[modes.mappings.trigger]\ntype = \"GamepadAnalogStick\"\naxis = 129  # Left stick Y-axis\ndirection = \"Up\"\nthreshold = 0.5\n[modes.mappings.action]\ntype = \"Keystroke\"\nkeys = \"w\"\n```\n\n### Gamepad Analog Trigger (v3.0)\n```toml\n[[modes.mappings]]\ndescription = \"Right trigger → Volume up\"\n[modes.mappings.trigger]\ntype = \"GamepadTrigger\"\ntrigger = 133  # Right trigger analog axis\nthreshold = 0.3\n[modes.mappings.action]\ntype = \"VolumeControl\"\naction = \"Up\"\n```\n\n### Velocity-Sensitive Actions (MIDI)\n```toml\n# Soft press\n[[modes.mappings]]\ndescription = \"Volume Down (soft)\"\n[modes.mappings.trigger]\ntype = \"VelocityRange\"\nnote = 13\nmin_velocity = 1\nmax_velocity = 40\n[modes.mappings.action]\ntype = \"VolumeControl\"\naction = \"Down\"\n\n# Hard press\n[[modes.mappings]]\ndescription = \"Volume Up (hard)\"\n[modes.mappings.trigger]\ntype = \"VelocityRange\"\nnote = 13\nmin_velocity = 80\nmax_velocity = 127\n[modes.mappings.action]\ntype = \"VolumeControl\"\naction = \"Up\"\n```\n\n### Long Press\n```toml\n[[modes.mappings]]\ndescription = \"Quit App (long press)\"\n[modes.mappings.trigger]\ntype = \"LongPress\"\nnote = 4\nmin_duration_ms = 1500\n[modes.mappings.action]\ntype = \"Keystroke\"\nkeys = \"q\"\nmodifiers = [\"cmd\"]\n```\n\n### Double-Tap\n```toml\n[[modes.mappings]]\ndescription = \"Fullscreen (double tap)\"\n[modes.mappings.trigger]\ntype = \"DoubleTap\"\nnote = 16\nmax_interval_ms = 300\n[modes.mappings.action]\ntype = \"Keystroke\"\nkeys = \"f\"\nmodifiers = [\"ctrl\", \"cmd\"]\n```\n\n### Chord Detection (MIDI)\n```toml\n[[modes.mappings]]\ndescription = \"Force Quit (chord)\"\n[modes.mappings.trigger]\ntype = \"NoteChord\"\nnotes = [8, 12]  # Both pads must be pressed\nmax_interval_ms = 100\n[modes.mappings.action]\ntype = \"Keystroke\"\nkeys = \"escape\"\nmodifiers = [\"cmd\", \"option\"]\n```\n\n### Encoder Actions (MIDI)\n```toml\n[[global_mappings]]\ndescription = \"Volume Up\"\n[global_mappings.trigger]\ntype = \"EncoderTurn\"\ncc = 2\ndirection = \"Clockwise\"\n[global_mappings.action]\ntype = \"VolumeControl\"\naction = \"Up\"\n```\n\n## Daemon Control\n\n### conductorctl CLI\n\nControl the daemon from the command line:\n\n```bash\n# Check daemon status\nconductorctl status\n\n# Reload configuration\nconductorctl reload\n\n# Test connectivity\nconductorctl ping\n\n# Stop daemon\nconductorctl stop\n\n# Validate config before applying\nconductorctl validate --config new-config.toml\n\n# JSON output for scripting\nconductorctl --json status | jq .data.uptime_secs\n```\n\n### Performance Monitoring\n\n```bash\n# View reload performance\nconductorctl status | grep -A5 \"Reload Performance\"\n\n# Output includes:\n# - Last reload time (ms)\n# - Average reload time\n# - Fastest/slowest reloads\n# - Performance grade (A-F)\n```\n\nSee `man conductorctl` for full command reference.\n\n## Diagnostic Tools\n\n### MIDI Diagnostic Tool\nVisualize all MIDI events from your controller:\n```bash\nmidi_diagnostic 2  # If installed\n# Or: cargo run --bin midi_diagnostic 2\n```\n\nFeatures:\n- Real-time event visualization\n- Velocity bars\n- Hold duration tracking\n- Beautiful colored output\n\n### Test MIDI Ports\nList all available MIDI devices:\n```bash\ntest_midi  # If installed\n# Or: cargo run --bin test_midi\n```\n\n## Action Types\n\n### Basic Actions\n- **Keystroke** - Simulate keyboard shortcuts\n- **Text** - Type text strings\n- **Launch** - Open applications\n- **Shell** - Execute shell commands\n- **Delay** - Add delays between actions\n- **MouseClick** - Simulate mouse clicks\n\n### Advanced Actions\n- **VolumeControl** - System volume control (Up/Down/Mute/Set)\n- **ModeChange** - Switch between mapping modes\n- **Sequence** - Chain multiple actions\n- **Repeat** - Repeat an action multiple times\n- **Conditional** - Execute based on conditions\n\n## Modes\n\nThe system supports multiple modes, each with its own set of mappings:\n\n1. **Default Mode** - General productivity shortcuts\n2. **Development Mode** - Git commands, build tools\n3. **Media Mode** - Music and video controls\n4. **Custom Modes** - Create your own!\n\nSwitch modes using:\n- Encoder rotation (MIDI)\n- Specific button/pad combinations\n- CC messages (MIDI)\n- Button chords (Gamepad)\n\n## Troubleshooting\n\n### MIDI Device Not Found\n1. Check if device is connected: `system_profiler SPUSBDataType | grep -i mikro`\n2. Install necessary drivers (e.g., Native Instruments Controller Editor)\n3. Check Audio MIDI Setup: `open -a \"Audio MIDI Setup\"`\n\n### Gamepad Not Detected (v3.0)\n1. Check if gamepad is connected and recognized by OS\n2. Test with system gamepad settings or Steam Big Picture\n3. Ensure SDL2-compatible drivers are installed\n4. Check debug output: `conductor --log-level debug`\n5. Verify gamepad shows in system controller list\n\n### High Latency\n- Build in release mode: `cargo build --release`\n- Close unnecessary applications\n- Check CPU usage\n\n### Events Not Triggering\n- Run diagnostic tool to verify input events\n- Check config.toml for correct button/note numbers\n- Verify velocity/duration thresholds\n- For gamepads: Check button ID mapping (MIDI Learn recommended)\n\n## Advanced Configuration\n\n### Timing Settings\n```toml\n[advanced_settings]\nchord_timeout_ms = 50        # Max time between notes for chord\ndouble_tap_timeout_ms = 300  # Max time between taps\nhold_threshold_ms = 2000     # Time before hold is detected\n```\n\n### Conditional Actions\n```toml\n[[modes.mappings]]\ndescription = \"Context-aware action\"\n[modes.mappings.trigger]\ntype = \"Note\"\nnote = 20\n[modes.mappings.action]\ntype = \"Conditional\"\n[modes.mappings.action.condition]\ntype = \"AppRunning\"\napp_name = \"Terminal\"\n[modes.mappings.action.then_action]\ntype = \"Keystroke\"\nkeys = \"c\"\nmodifiers = [\"ctrl\"]\n[modes.mappings.action.else_action]\ntype = \"Launch\"\napp = \"Terminal\"\n```\n\n## Development\n\n### Project Structure\n```\nconductor/\n├── src/\n│   ├── main.rs           # Main application\n│   ├── config.rs         # Configuration structures\n│   ├── actions.rs        # Action execution\n│   ├── mappings.rs       # Trigger mapping engine\n│   ├── event_processor.rs # Enhanced event processing\n│   └── bin/\n│       ├── test_midi.rs  # MIDI port tester\n│       └── midi_diagnostic.rs # Diagnostic tool\n├── config.toml           # User configuration\n└── Cargo.toml           # Dependencies\n```\n\n### Adding New Trigger Types\n1. Add to `Trigger` enum in `config.rs`\n2. Add to `ProcessedEvent` enum in `event_processor.rs`\n3. Update `EventProcessor::process()` to detect the trigger\n4. Update `MappingEngine::trigger_matches_processed()` to handle matching\n\n### Adding New Action Types\n1. Add to `ActionConfig` enum in `config.rs`\n2. Add to `Action` enum in `actions.rs`\n3. Update `ActionExecutor::execute()` to handle the action\n\n## Performance\n\n- **Input Event Latency**: \u003c 1ms typical\n- **Config Reload Time**: 0-10ms typical (Grade A: \u003c20ms target)\n- **Startup Time**: \u003c 500ms\n- **Memory Usage**: 5-10MB\n- **CPU Usage**: \u003c 1% idle, \u003c 5% active\n- **Binary Size**: ~3-5MB (release build with LTO)\n\nRun benchmarks:\n```bash\ncargo bench --package conductor-daemon\n```\n\nTypical benchmark results (Apple M1):\n- 2 modes, 10 mappings: 0-2ms reload\n- 5 modes, 50 mappings: 2-5ms reload\n- 10 modes, 100 mappings: 5-8ms reload\n\nAll achieve **Grade A** performance (\u003c20ms).\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:\n- How to report bugs\n- How to propose features\n- Development setup guide\n- Coding standards\n- Pull request process\n\nCheck out [good first issues](https://github.com/amiable-dev/conductor/labels/good-first-issue) to get started.\n\n## Documentation\n\n- **[Full Documentation](https://amiable-dev.github.io/conductor/)** - Complete user guide\n- **[Configuration Reference](https://amiable-dev.github.io/conductor/configuration/overview.html)** - TOML configuration guide\n- **[LED Feedback System](https://amiable-dev.github.io/conductor/configuration/led-feedback.html)** - LED control documentation\n- **[API Documentation](https://docs.rs/conductor)** - Rust API docs\n- **Man Pages**: `man conductor`, `man conductorctl`\n\n## Community \u0026 Support\n\n- **[Discussions](https://github.com/amiable-dev/conductor/discussions)** - Ask questions, share configs\n- **[Issues](https://github.com/amiable-dev/conductor/issues)** - Bug reports, feature requests\n- **[Security](SECURITY.md)** - Security vulnerability reporting\n\n## Roadmap\n\n### ✅ Phase 1 - v0.2.0 (Complete)\n- Workspace architecture (conductor-core, conductor-daemon, conductor)\n- Pure Rust engine library with zero UI dependencies\n- 339 tests, all passing\n\n### ✅ Phase 2 - v1.0.0 (Complete)\n- Background daemon with IPC server\n- Config hot-reload with 0-10ms latency\n- CLI control tool (conductorctl)\n- systemd/launchd integration\n- Comprehensive documentation and deployment guides\n\n### ✅ Phase 3 - v2.0.0 (Complete)\n- Tauri-based visual configurator\n- MIDI Learn mode (click → press → auto-map)\n- Per-app profiles with frontmost app detection\n- Device templates for popular controllers\n- Live event console\n\n### ✅ Phase 4 - v3.0.0 (Complete)\n- Multi-protocol input system (MIDI + HID/Gamepad)\n- Unified InputEvent abstraction\n- Gamepad device templates (Xbox, PlayStation, Switch Pro)\n- MIDI Learn support for gamepad buttons\n- Hot-plug detection for game controllers\n\n### 🚀 Phase 5 - v4.0.0 (Future)\n- OSC protocol support\n- Keyboard intercept (system-wide hotkeys)\n- Custom USB device support\n- Plugin system for community extensions\n\n### 🔮 Phase 6 - v5.0.0 (Vision)\n- Virtual MIDI output for DAW integration\n- Profile sharing/export marketplace\n- WebSocket API for remote control\n- AI-powered natural language configuration\n- Workflow pattern recognition\n\nSee [.research/](https://github.com/amiable-dev/conductor/tree/main/.research) for detailed implementation proposals.\n\n## License\n\nConductor is licensed under the [MIT License](LICENSE).\n\nCopyright (c) 2025 Amiable\n\n## Credits\n\nBuilt with:\n- [midir](https://github.com/Boddlnagg/midir) - MIDI I/O\n- [gilrs](https://gitlab.com/gilrs-project/gilrs) - Game controller input (v3.0+)\n- [enigo](https://github.com/enigo-rs/enigo) - Input simulation\n- [colored](https://github.com/mackwic/colored) - Terminal colors\n- [serde](https://serde.rs/) - Serialization\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famiable-dev%2Fconductor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famiable-dev%2Fconductor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famiable-dev%2Fconductor/lists"}