ds4-mapper 0.1.0__tar.gz

ds4_mapper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jared Mahan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ds4_mapper-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: ds4-mapper
+Version: 0.1.0
+Summary: Map a DualShock 4 controller to keyboard inputs with a live TUI
+Author: Jared Mahan
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jaredmahan/ds4-mapper
+Project-URL: Repository, https://github.com/jaredmahan/ds4-mapper
+Project-URL: Issues, https://github.com/jaredmahan/ds4-mapper/issues
+Keywords: ds4,dualshock4,controller,keyboard,mapping,gamepad,pygame
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame-ce
+Requires-Dist: pynput
+Requires-Dist: rich
+Requires-Dist: textual
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# DS4 Mapper
+
+Maps a DualShock 4 controller to keyboard inputs system-wide, so you can play browser games with a controller. Profiles are hot-swappable at runtime without restarting.
+
+## Requirements
+
+- Python 3.11+
+- A DualShock 4 connected via Bluetooth
+
+**macOS:** Grant Accessibility permission to your terminal in **System Settings → Privacy & Security → Accessibility** (required for keyboard injection).
+
+## Install
+
+From PyPI:
+
+```bash
+pip install ds4-mapper
+```
+
+Or from source (development mode):
+
+```bash
+git clone https://github.com/jaredmahan/ds4-mapper.git
+cd ds4-mapper
+pip install -e ".[dev]"
+```
+
+## Usage
+
+Connect your DS4 via Bluetooth, then run:
+
+```bash
+ds4-mapper
+```
+
+Or without installing:
+
+```bash
+python -m ds4mapper
+```
+
+### Options
+
+```
+--profile NAME    Profile to load on startup (default: default)
+--discover        Print raw button/axis indices — useful for building new profiles
+```
+
+### Discover Mode
+
+If a button isn't registering, use discover mode to see the raw event index:
+
+```bash
+ds4-mapper --discover
+```
+
+## CLI Commands
+
+Once the mapper is running, type commands at the `>` prompt:
+
+| Command | Effect |
+|---------|--------|
+| `list` | Show available profiles |
+| `switch <name>` | Load a profile (Tab-completes) |
+| `current` | Show the active profile name |
+| `reload` | Reload the current profile from disk |
+| `view [<name>]` | Show button/axis/trigger mappings for a profile |
+| `edit [<name>]` | Open the profile editor for an existing profile |
+| `new <name>` | Create a new profile in the editor |
+| `help` | Show command list |
+| `quit` / `exit` | Stop |
+
+## Profile Editor
+
+`edit` and `new` open an interactive editor screen where you can map controller inputs to keyboard keys:
+
+1. **Press a DS4 button, stick, or trigger** — the editor enters *waiting* mode and prompts for a key.
+2. **Press the keyboard key** you want it mapped to — the mapping is recorded.
+3. Repeat for each input you want to map.
+
+You can also type commands in the editor's input field:
+
+| Command | Effect |
+|---------|--------|
+| `save [stem]` | Save to disk (optional custom filename) |
+| `delete <input>` | Remove a mapping (e.g. `delete Cross`) |
+| `name <text>` | Set the profile display name |
+| `desc <text>` | Set the profile description |
+| `cancel` | Discard changes and return to the main screen |
+
+Keyboard injection is suspended while the editor is open so controller inputs don't fire game actions.
+
+## Profiles
+
+Profiles live in `ds4mapper/profiles/`. Each is a TOML file:
+
+```toml
+name = "default"
+description = "Standard browser game layout"
+
+[buttons]
+0 = "x"      # Cross
+1 = "z"      # Circle
+2 = "s"      # Square
+3 = "a"      # Triangle
+4 = "v"      # Share
+6 = "enter"  # Options / START
+9 = "q"      # L1
+10 = "e"     # R1
+11 = "up"
+12 = "down"
+13 = "left"
+14 = "right"
+
+[axes]
+0 = ["f", "h"]   # Left Stick X (neg, pos)
+1 = ["t", "g"]   # Left Stick Y
+2 = ["j", "l"]   # Right Stick X
+3 = ["i", "k"]   # Right Stick Y
+
+[triggers]
+4 = "tab"    # L2
+5 = "r"      # R2
+```
+
+Special key names: `enter`, `tab`, `up`, `down`, `left`, `right`, `space`, `esc`, `shift`, `ctrl`, `alt`. Single characters are used directly.
+
+Profiles can be created or edited from the CLI with `new` and `edit`, or by copying and editing TOML files directly.
+
+## Publishing to PyPI
+
+This project uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) via GitHub Actions. To release a new version:
+
+1. Bump `version` in `pyproject.toml`.
+2. Create a GitHub release — the `publish.yml` workflow builds and uploads the distribution automatically.

ds4_mapper-0.1.0/README.md

@@ -0,0 +1,135 @@
+# DS4 Mapper
+
+Maps a DualShock 4 controller to keyboard inputs system-wide, so you can play browser games with a controller. Profiles are hot-swappable at runtime without restarting.
+
+## Requirements
+
+- Python 3.11+
+- A DualShock 4 connected via Bluetooth
+
+**macOS:** Grant Accessibility permission to your terminal in **System Settings → Privacy & Security → Accessibility** (required for keyboard injection).
+
+## Install
+
+From PyPI:
+
+```bash
+pip install ds4-mapper
+```
+
+Or from source (development mode):
+
+```bash
+git clone https://github.com/jaredmahan/ds4-mapper.git
+cd ds4-mapper
+pip install -e ".[dev]"
+```
+
+## Usage
+
+Connect your DS4 via Bluetooth, then run:
+
+```bash
+ds4-mapper
+```
+
+Or without installing:
+
+```bash
+python -m ds4mapper
+```
+
+### Options
+
+```
+--profile NAME    Profile to load on startup (default: default)
+--discover        Print raw button/axis indices — useful for building new profiles
+```
+
+### Discover Mode
+
+If a button isn't registering, use discover mode to see the raw event index:
+
+```bash
+ds4-mapper --discover
+```
+
+## CLI Commands
+
+Once the mapper is running, type commands at the `>` prompt:
+
+| Command | Effect |
+|---------|--------|
+| `list` | Show available profiles |
+| `switch <name>` | Load a profile (Tab-completes) |
+| `current` | Show the active profile name |
+| `reload` | Reload the current profile from disk |
+| `view [<name>]` | Show button/axis/trigger mappings for a profile |
+| `edit [<name>]` | Open the profile editor for an existing profile |
+| `new <name>` | Create a new profile in the editor |
+| `help` | Show command list |
+| `quit` / `exit` | Stop |
+
+## Profile Editor
+
+`edit` and `new` open an interactive editor screen where you can map controller inputs to keyboard keys:
+
+1. **Press a DS4 button, stick, or trigger** — the editor enters *waiting* mode and prompts for a key.
+2. **Press the keyboard key** you want it mapped to — the mapping is recorded.
+3. Repeat for each input you want to map.
+
+You can also type commands in the editor's input field:
+
+| Command | Effect |
+|---------|--------|
+| `save [stem]` | Save to disk (optional custom filename) |
+| `delete <input>` | Remove a mapping (e.g. `delete Cross`) |
+| `name <text>` | Set the profile display name |
+| `desc <text>` | Set the profile description |
+| `cancel` | Discard changes and return to the main screen |
+
+Keyboard injection is suspended while the editor is open so controller inputs don't fire game actions.
+
+## Profiles
+
+Profiles live in `ds4mapper/profiles/`. Each is a TOML file:
+
+```toml
+name = "default"
+description = "Standard browser game layout"
+
+[buttons]
+0 = "x"      # Cross
+1 = "z"      # Circle
+2 = "s"      # Square
+3 = "a"      # Triangle
+4 = "v"      # Share
+6 = "enter"  # Options / START
+9 = "q"      # L1
+10 = "e"     # R1
+11 = "up"
+12 = "down"
+13 = "left"
+14 = "right"
+
+[axes]
+0 = ["f", "h"]   # Left Stick X (neg, pos)
+1 = ["t", "g"]   # Left Stick Y
+2 = ["j", "l"]   # Right Stick X
+3 = ["i", "k"]   # Right Stick Y
+
+[triggers]
+4 = "tab"    # L2
+5 = "r"      # R2
+```
+
+Special key names: `enter`, `tab`, `up`, `down`, `left`, `right`, `space`, `esc`, `shift`, `ctrl`, `alt`. Single characters are used directly.
+
+Profiles can be created or edited from the CLI with `new` and `edit`, or by copying and editing TOML files directly.
+
+## Publishing to PyPI
+
+This project uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) via GitHub Actions. To release a new version:
+
+1. Bump `version` in `pyproject.toml`.
+2. Create a GitHub release — the `publish.yml` workflow builds and uploads the distribution automatically.

ds4_mapper-0.1.0/ds4_mapper.egg-info/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: ds4-mapper
+Version: 0.1.0
+Summary: Map a DualShock 4 controller to keyboard inputs with a live TUI
+Author: Jared Mahan
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jaredmahan/ds4-mapper
+Project-URL: Repository, https://github.com/jaredmahan/ds4-mapper
+Project-URL: Issues, https://github.com/jaredmahan/ds4-mapper/issues
+Keywords: ds4,dualshock4,controller,keyboard,mapping,gamepad,pygame
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame-ce
+Requires-Dist: pynput
+Requires-Dist: rich
+Requires-Dist: textual
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# DS4 Mapper
+
+Maps a DualShock 4 controller to keyboard inputs system-wide, so you can play browser games with a controller. Profiles are hot-swappable at runtime without restarting.
+
+## Requirements
+
+- Python 3.11+
+- A DualShock 4 connected via Bluetooth
+
+**macOS:** Grant Accessibility permission to your terminal in **System Settings → Privacy & Security → Accessibility** (required for keyboard injection).
+
+## Install
+
+From PyPI:
+
+```bash
+pip install ds4-mapper
+```
+
+Or from source (development mode):
+
+```bash
+git clone https://github.com/jaredmahan/ds4-mapper.git
+cd ds4-mapper
+pip install -e ".[dev]"
+```
+
+## Usage
+
+Connect your DS4 via Bluetooth, then run:
+
+```bash
+ds4-mapper
+```
+
+Or without installing:
+
+```bash
+python -m ds4mapper
+```
+
+### Options
+
+```
+--profile NAME    Profile to load on startup (default: default)
+--discover        Print raw button/axis indices — useful for building new profiles
+```
+
+### Discover Mode
+
+If a button isn't registering, use discover mode to see the raw event index:
+
+```bash
+ds4-mapper --discover
+```
+
+## CLI Commands
+
+Once the mapper is running, type commands at the `>` prompt:
+
+| Command | Effect |
+|---------|--------|
+| `list` | Show available profiles |
+| `switch <name>` | Load a profile (Tab-completes) |
+| `current` | Show the active profile name |
+| `reload` | Reload the current profile from disk |
+| `view [<name>]` | Show button/axis/trigger mappings for a profile |
+| `edit [<name>]` | Open the profile editor for an existing profile |
+| `new <name>` | Create a new profile in the editor |
+| `help` | Show command list |
+| `quit` / `exit` | Stop |
+
+## Profile Editor
+
+`edit` and `new` open an interactive editor screen where you can map controller inputs to keyboard keys:
+
+1. **Press a DS4 button, stick, or trigger** — the editor enters *waiting* mode and prompts for a key.
+2. **Press the keyboard key** you want it mapped to — the mapping is recorded.
+3. Repeat for each input you want to map.
+
+You can also type commands in the editor's input field:
+
+| Command | Effect |
+|---------|--------|
+| `save [stem]` | Save to disk (optional custom filename) |
+| `delete <input>` | Remove a mapping (e.g. `delete Cross`) |
+| `name <text>` | Set the profile display name |
+| `desc <text>` | Set the profile description |
+| `cancel` | Discard changes and return to the main screen |
+
+Keyboard injection is suspended while the editor is open so controller inputs don't fire game actions.
+
+## Profiles
+
+Profiles live in `ds4mapper/profiles/`. Each is a TOML file:
+
+```toml
+name = "default"
+description = "Standard browser game layout"
+
+[buttons]
+0 = "x"      # Cross
+1 = "z"      # Circle
+2 = "s"      # Square
+3 = "a"      # Triangle
+4 = "v"      # Share
+6 = "enter"  # Options / START
+9 = "q"      # L1
+10 = "e"     # R1
+11 = "up"
+12 = "down"
+13 = "left"
+14 = "right"
+
+[axes]
+0 = ["f", "h"]   # Left Stick X (neg, pos)
+1 = ["t", "g"]   # Left Stick Y
+2 = ["j", "l"]   # Right Stick X
+3 = ["i", "k"]   # Right Stick Y
+
+[triggers]
+4 = "tab"    # L2
+5 = "r"      # R2
+```
+
+Special key names: `enter`, `tab`, `up`, `down`, `left`, `right`, `space`, `esc`, `shift`, `ctrl`, `alt`. Single characters are used directly.
+
+Profiles can be created or edited from the CLI with `new` and `edit`, or by copying and editing TOML files directly.
+
+## Publishing to PyPI
+
+This project uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) via GitHub Actions. To release a new version:
+
+1. Bump `version` in `pyproject.toml`.
+2. Create a GitHub release — the `publish.yml` workflow builds and uploads the distribution automatically.

ds4_mapper-0.1.0/ds4_mapper.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+ds4_mapper.egg-info/PKG-INFO
+ds4_mapper.egg-info/SOURCES.txt
+ds4_mapper.egg-info/dependency_links.txt
+ds4_mapper.egg-info/entry_points.txt
+ds4_mapper.egg-info/requires.txt
+ds4_mapper.egg-info/top_level.txt
+ds4mapper/__init__.py
+ds4mapper/__main__.py
+ds4mapper/cli.py
+ds4mapper/keys.py
+ds4mapper/mapper.py
+ds4mapper/profiles.py
+ds4mapper/profiles/default.toml
+tests/test_keys.py
+tests/test_mapper.py
+tests/test_profiles.py

ds4_mapper-0.1.0/ds4_mapper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ds4_mapper-0.1.0/ds4_mapper.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ds4-mapper = ds4mapper.__main__:main

ds4_mapper-0.1.0/ds4_mapper.egg-info/requires.txt

@@ -0,0 +1,8 @@
+pygame-ce
+pynput
+rich
+textual
+
+[dev]
+pytest
+ruff

ds4_mapper-0.1.0/ds4_mapper.egg-info/top_level.txt

@@ -0,0 +1 @@
+ds4mapper

ds4_mapper-0.1.0/ds4mapper/__main__.py

@@ -0,0 +1,84 @@
+import argparse
+import os
+import sys
+import time
+
+os.environ["SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS"] = "1"
+
+import pygame
+
+from ds4mapper.cli import run
+from ds4mapper.profiles import load_profile
+
+
+def _init_pygame() -> pygame.joystick.Joystick:
+    pygame.init()
+    pygame.display.set_caption("DS4 Mapper")
+    pygame.display.set_mode((220, 40))
+    pygame.joystick.init()
+
+    if pygame.joystick.get_count() == 0:
+        timeout = 30
+        deadline = time.monotonic() + timeout
+        while pygame.joystick.get_count() == 0:
+            remaining = int(deadline - time.monotonic())
+            if remaining <= 0:
+                print("\rNo controller found. Connect the DS4 via Bluetooth and try again.")
+                sys.exit(1)
+            print(
+                f"\rNo controller detected. Waiting for DS4... {remaining}s  ", end="", flush=True
+            )
+            pygame.event.pump()
+            time.sleep(1)
+        print()  # newline after countdown
+
+    joy = pygame.joystick.Joystick(0)
+    joy.init()
+    print(f"Connected: {joy.get_name()}")
+    return joy
+
+
+def _discover(joy: pygame.joystick.Joystick) -> None:
+    print("\nDiscover mode — press every button and move every stick/trigger.")
+    print("Ctrl-C to quit.\n")
+    while True:
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                return
+            elif event.type == pygame.JOYBUTTONDOWN:
+                print(f"  BUTTON DOWN  index={event.button}")
+            elif event.type == pygame.JOYBUTTONUP:
+                print(f"  BUTTON UP    index={event.button}")
+            elif event.type == pygame.JOYHATMOTION:
+                print(f"  HAT          value={event.value}")
+            elif event.type == pygame.JOYAXISMOTION:
+                print(f"  AXIS         index={event.axis}  value={event.value:.3f}")
+        time.sleep(0.016)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="DS4 → Keyboard Mapper")
+    parser.add_argument(
+        "--discover", action="store_true", help="Print raw events to verify button/axis indices"
+    )
+    parser.add_argument(
+        "--profile", default="default", help="Profile name to load on startup (default: default)"
+    )
+    args = parser.parse_args()
+
+    joy = _init_pygame()
+    try:
+        if args.discover:
+            print(f"Discover mode — {joy.get_name()}")
+            _discover(joy)
+        else:
+            profile = load_profile(args.profile)
+            run(joy, profile, args.profile)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+    finally:
+        pygame.quit()
+
+
+if __name__ == "__main__":
+    main()