{"id":50471472,"url":"https://github.com/riqqqque/openlaunchdeck","last_synced_at":"2026-06-07T12:01:17.471Z","repository":{"id":361771102,"uuid":"1252062206","full_name":"Riqqqque/OpenLaunchDeck","owner":"Riqqqque","description":"Windows desktop macro deck app for Novation Launchpad Mini MK3.","archived":false,"fork":false,"pushed_at":"2026-06-01T09:56:40.000Z","size":2301,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T11:07:29.573Z","etag":null,"topics":["launchpad-mini-mk3","midi","openlaunchdeck","pyside6","stream-deck","windows"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/Riqqqque.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T06:45:03.000Z","updated_at":"2026-06-01T09:56:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Riqqqque/OpenLaunchDeck","commit_stats":null,"previous_names":["riqqqque/openlaunchdeck"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/Riqqqque/OpenLaunchDeck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riqqqque%2FOpenLaunchDeck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riqqqque%2FOpenLaunchDeck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riqqqque%2FOpenLaunchDeck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riqqqque%2FOpenLaunchDeck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Riqqqque","download_url":"https://codeload.github.com/Riqqqque/OpenLaunchDeck/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riqqqque%2FOpenLaunchDeck/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34020187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["launchpad-mini-mk3","midi","openlaunchdeck","pyside6","stream-deck","windows"],"created_at":"2026-06-01T11:00:14.672Z","updated_at":"2026-06-07T12:01:17.428Z","avatar_url":"https://github.com/Riqqqque.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenLaunchDeck\n\n![OpenLaunchDeck logo](openlaunchdeck/resources/icons/openlaunchdeck_wordmark.svg)\n\nOpenLaunchDeck turns a Novation Launchpad Mini MK3 into a Windows desktop macro deck with profiles, pages, actions, soundboard buttons, MIDI debug tools, update checks, and installer support.\n\nIt is a normal desktop app: install it, launch it, assign actions, keep it running in the background, and store user data in AppData so upgrades do not overwrite profiles or settings.\n\n## Supported Hardware\n\n- Novation Launchpad Mini MK3\n- USB MIDI input for pad presses\n- USB MIDI output for pad lighting\n- Simulation mode when no Launchpad is connected\n\nProgrammer Mode is recommended for predictable pad messages. Device mode can affect note/control mappings, so OpenLaunchDeck includes MIDI Debug and calibration tools instead of spreading note numbers through the app.\n\n## Screenshots\n\n![Main window dark theme](docs/screenshots/main-window-dark.png)\n\n![Main window light theme](docs/screenshots/main-window-light.png)\n\nMore screenshots are tracked in [docs/screenshots](docs/screenshots).\n\n## Features\n\n- Editable 8x8 Launchpad-style grid\n- Modern dark/light desktop UI with configurable grid density\n- Multiple profiles and pages\n- Simulation testing without hardware through the button editor\n- MIDI input/output structure for Launchpad Mini MK3\n- Isolated A1-H8 MIDI mapping with calibration\n- Page lighting refresh with changed-pad batching\n- Button editor with action-specific settings\n- Dangerous action double-press confirmation\n- Soundboard playback with stop controls\n- Background action execution\n- Manual update checks with SHA256 verification\n- Optional startup update checks\n- Logs, diagnostics, settings, backups, profiles, MIDI mappings, and update downloads in AppData\n- Starter profiles for PC shortcuts, streaming, Discord audio, soundboard, server admin, and Minecraft server workflows\n- Optional native helper for focused mapping/hash/checksum utilities\n\n## Installation\n\nDownload the latest installer from the releases page when available and run it.\n\nUser data is stored in:\n\n```text\n%APPDATA%\\OpenLaunchDeck\n```\n\nInstaller upgrades replace program files only. Profiles, settings, logs, backups, MIDI mappings, imported assets, and update downloads stay in AppData.\n\n## Updating\n\nOpen `Help \u003e Check for Updates` to check a configured update manifest. Startup checks are optional and run in the background.\n\nThe updater can:\n\n- Fetch a remote JSON manifest with a timeout\n- Compare semantic versions\n- Detect required updates and unsupported current versions\n- Download installers to `%APPDATA%\\OpenLaunchDeck\\updates`\n- Verify SHA256 before allowing installer launch\n- Keep the current app running when download or checksum verification fails\n- Back up profile JSON files before launching a verified installer when automatic backups are enabled\n\nOpenLaunchDeck does not install updates silently. Portable/source runs may need a manual update after the verified installer is downloaded.\n\nSee [docs/updating.md](docs/updating.md) for the manifest format and local update testing.\n\n## Running From Source\n\n```powershell\npython -m venv .venv\n.venv\\Scripts\\activate\npip install -r requirements.txt\npython -m openlaunchdeck.main\n```\n\nFor hardware MIDI testing from source, Python 3.11-3.13 is currently the safest Windows path because the real-time MIDI backend has prebuilt wheels there. Newer Python versions can still run simulation mode and tests, but MIDI hardware support may need a local C++ toolchain.\n\n## Running Tests\n\nTests do not require Launchpad hardware.\n\n```powershell\npytest\n```\n\n## Building The EXE\n\n```powershell\npowershell -ExecutionPolicy Bypass -File build.ps1 -SkipInstaller\n```\n\nThe build script creates `.venv` if needed, installs requirements, runs tests, and builds `dist\\OpenLaunchDeck\\OpenLaunchDeck.exe` with PyInstaller.\nIt also writes `dist\\OpenLaunchDeck-\u003cversion\u003e-Windows.zip` and a `.sha256` checksum file for portable testing.\n\nFor repeat local packaging after tests have already passed, use:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File build.ps1 -SkipInstaller -SkipTests -FastPackage\n```\n\n## Creating The Installer\n\nInstall Inno Setup, then run:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File build.ps1\n```\n\nWhen Inno Setup is available, the script builds `dist\\installer\\OpenLaunchDeckSetup-\u003cversion\u003e.exe` and writes a `.sha256` file beside it. The version comes from `openlaunchdeck/version.py`.\n\n## Publishing A Release\n\nEvery tagged release should publish ready-to-download Windows packages. Push a `v\u003cversion\u003e` tag after the version bump is committed:\n\n```powershell\ngit tag v0.1.12\ngit push origin v0.1.12\n```\n\nThe Release workflow builds and uploads the installer EXE, portable ZIP, and SHA256 checksum files to GitHub Releases. It uses the same build script with CI-specific fast packaging flags so tagged releases spend less time on packaging.\n\n## First Setup\n\nOn first launch, choose a starter profile or start with a blank deck. If no Launchpad is connected, OpenLaunchDeck stays in simulation mode. Click grid pads to edit them, then use the selected button's Test control when you want to run an action from the app.\n\nWhen the Launchpad is connected:\n\n1. Put the device in Programmer Mode.\n2. Open `Device \u003e MIDI Debug`.\n3. Confirm input and output ports are detected.\n4. Press pads and watch raw MIDI messages.\n5. Use calibration if parsed button IDs do not match A1-H8.\n6. Save the mapping and reconnect.\n\nThe Launchpad Mini MK3 has extra navigation and scene-launch buttons around the 8x8 grid. The current OpenLaunchDeck mapping treats the 8x8 grid as the reliable macro surface. To change OpenLaunchDeck pages today, assign a grid pad to the Switch Page action. Extra hardware buttons can be inspected in MIDI Debug, but they are not bound to previous/next OpenLaunchDeck pages by default until their messages are verified on hardware.\n\n## MIDI Troubleshooting\n\nUse `Device \u003e MIDI Debug` when pads do not map or light correctly. The debug window shows available ports, raw incoming messages, outgoing lighting messages, parsed button IDs, and the current mapping table.\n\nIf the default mapping is wrong for your device mode, run calibration. Saved mappings live in:\n\n```text\n%APPDATA%\\OpenLaunchDeck\\midi_mappings\n```\n\nSee [docs/hardware_notes.md](docs/hardware_notes.md) and [docs/midi_mapping.md](docs/midi_mapping.md).\n\n## Soundboard Setup\n\nSoundboard buttons can play local `.wav`, `.mp3`, and platform-supported `.ogg` files through QtMultimedia. Each button supports volume, looping, already-playing behavior, active color, and stop behavior.\n\nTo make Discord or a game hear the soundboard, route audio through external virtual audio cable software and choose that output device in OpenLaunchDeck. The app does not install or bundle audio drivers.\n\nSee [docs/soundboard_setup.md](docs/soundboard_setup.md).\n\n## Performance Notes\n\nOpenLaunchDeck keeps expensive work away from the GUI thread:\n\n- MIDI callbacks parse and emit lightweight events\n- Blocking actions run through a worker pool\n- Update checks and downloads run on Qt worker threads\n- Sound playback uses non-blocking QtMultimedia APIs\n- Lighting refreshes skip unchanged pad colors\n- Grid cells skip redundant text/style updates\n- Performance logging is quiet by default and can be enabled in Settings\n\nSee [docs/performance.md](docs/performance.md).\n\n## Optional Native Acceleration\n\nThe app runs fully in Python by default. The optional Rust helper uses PyO3/maturin for focused utilities:\n\n- Button ID validation and conversion\n- Profile text hashing\n- SHA256 verification\n\nIf the helper is missing, disabled, or cannot be imported, OpenLaunchDeck uses Python fallbacks.\n\nBuild without native acceleration:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File build.ps1\n```\n\nBuild and install the optional helper into the local virtual environment:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File build.ps1 -BuildNative\n```\n\n## Profile Format\n\nProfiles are human-readable JSON files stored in:\n\n```text\n%APPDATA%\\OpenLaunchDeck\\profiles\n```\n\nMinimal example:\n\n```json\n{\n  \"name\": \"Basic PC\",\n  \"id\": \"basic_pc\",\n  \"default_page\": \"main\",\n  \"pages\": [\n    {\n      \"name\": \"Main\",\n      \"id\": \"main\",\n      \"buttons\": {\n        \"A1\": {\n          \"label\": \"Browser\",\n          \"color\": \"green\",\n          \"enabled\": true,\n          \"dangerous\": false,\n          \"action\": {\n            \"type\": \"open_url\",\n            \"config\": {\n              \"url\": \"https://www.google.com\"\n            }\n          }\n        }\n      }\n    }\n  ]\n}\n```\n\nSee [docs/profile_format.md](docs/profile_format.md).\n\n## Adding Custom Actions\n\nActions live in `openlaunchdeck/actions/`. Add a class derived from `BaseAction`, define `type_name`, `display_name`, `config_fields`, and `execute()`, then register it in `actions/registry.py`.\n\nReturn clear `ActionResult` values so the GUI, logs, and Launchpad feedback can show useful status.\n\n## Roadmap\n\n- Hardware-verified Launchpad Mini MK3 mapping and lighting presets\n- Full OBS WebSocket implementation\n- Secure SSH secrets flow\n- More advanced audio output routing\n- Richer first-run wizard and tray polish\n- Signed installer\n- Update manifest publishing automation\n\n## Known Limitations\n\n- OBS WebSocket support is structured but not implemented yet.\n- SSH command support depends on Paramiko and key-based authentication setup.\n- Endpoint-specific Windows volume control is not implemented; current volume actions use media keys.\n- Launchpad mappings should be verified in MIDI Debug before relying on them live.\n- The default lighting palette is a Programmer Mode preset and needs hardware verification for each target mode.\n- Startup update checks are intentionally quiet; manual checks show full detail.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friqqqque%2Fopenlaunchdeck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friqqqque%2Fopenlaunchdeck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friqqqque%2Fopenlaunchdeck/lists"}