{"id":28619299,"url":"https://github.com/mlshukai/pamiq-io","last_synced_at":"2025-07-24T19:11:54.191Z","repository":{"id":286361204,"uuid":"960987501","full_name":"MLShukai/pamiq-io","owner":"MLShukai","description":"Versatile I/O library for Python, providing easy access to audio, video, and input device capabilities.","archived":false,"fork":false,"pushed_at":"2025-06-12T02:07:46.000Z","size":263,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-12T04:38:41.937Z","etag":null,"topics":["audio","directinput","inputtino","keyboard","linux","mouse","obs-studio","opencv-python","osc","python","video","windows"],"latest_commit_sha":null,"homepage":"","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/MLShukai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-05T14:08:45.000Z","updated_at":"2025-06-12T02:07:48.000Z","dependencies_parsed_at":"2025-04-25T03:20:05.744Z","dependency_job_id":"f4966d22-7105-4b9e-9b3d-231df5d1611c","html_url":"https://github.com/MLShukai/pamiq-io","commit_stats":null,"previous_names":["mlshukai/game-io","mlshukai/pamiq-io"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/MLShukai/pamiq-io","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLShukai%2Fpamiq-io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLShukai%2Fpamiq-io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLShukai%2Fpamiq-io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLShukai%2Fpamiq-io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MLShukai","download_url":"https://codeload.github.com/MLShukai/pamiq-io/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLShukai%2Fpamiq-io/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265156074,"owners_count":23719646,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["audio","directinput","inputtino","keyboard","linux","mouse","obs-studio","opencv-python","osc","python","video","windows"],"created_at":"2025-06-12T04:30:39.216Z","updated_at":"2025-07-24T19:11:54.173Z","avatar_url":"https://github.com/MLShukai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![logo](./docs/images/logo.svg)\n\n# pamiq-io\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Document Style](https://img.shields.io/badge/%20docstyle-google-3666d6.svg)](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings)\n\n**pamiq-io** is a versatile I/O library for Python, providing easy access to audio, video, and input device capabilities for interactive applications, simulations, and AI projects, made for P-AMI\\\u003cQ\u003e.\n\n## ✨ Features\n\n- 🎤 Audio input/output via SoundCard\n- 📹 Video input via OpenCV\n- 🎛️ OSC (Open Sound Control) communication\n- ⌨️ Keyboard simulation (Linux and Windows)\n- 🖱️ Mouse simulation (Linux and Windows)\n\n## 🔧 Requirements\n\n- Python 3.12+\n- Platform-specific dependencies:\n  - **Linux**: Inputtino (for keyboard/mouse simulation)\n- OBS Studio (for video capture)\n\n## 📦 Installation\n\n### Using pip\n\n```bash\n# Install the base package\npip install pamiq-io\n\n# Install with optional dependencies as needed\npip install pamiq-io[opencv]       # For video input (all platforms)\npip install pamiq-io[osc]          # For OSC communication (all platforms)\npip install pamiq-io[soundcard]    # For audio input/output (all platforms)\n\n# Platform-specific input simulation:\n# For Linux:\npip install pamiq-io[inputtino]    # For keyboard and mouse output on Linux\n\n# For Windows:\npip install pamiq-io[windows]  # For keyboard and mouse output on Windows\n\n# For running demo scripts\npip install pamiq-io[demo]\n```\n\n### Linux-specific setup\n\n**For keyboard and mouse output on Linux, you must first install [inputtino](https://github.com/games-on-whales/inputtino/tree/stable/bindings/python).**\n\n### Development installation\n\n```bash\n# Clone and setup\ngit clone https://github.com/MLShukai/pamiq-io.git\ncd pamiq-io\nmake venv     # Sets up virtual environment with all dependencies\n```\n\n## 🧰 Command-Line Tools\n\npamiq-io includes several helpful command-line tools:\n\n```bash\n# List available video input devices\npamiq-io-show-opencv-available-input-devices\n\n# List available audio input devices\npamiq-io-show-soundcard-available-input-devices\n\n# List available audio output devices\npamiq-io-show-soundcard-available-output-devices\n```\n\n## 🛠️ Setup\n\n### OBS Virtual Camera\n\n1. Install OBS Studio following the official installation instructions:\n\n   - Visit [https://obsproject.com](https://obsproject.com)\n   - Follow the installation guide for your platform (Windows or Linux)\n\n2. In OBS, start the virtual camera (Tools → Start Virtual Camera)\n\n3. Linux-specific: If the virtual camera functionality is not available after installing OBS on Linux, you may need to install v4l2loopback:\n\n   ```bash\n   sudo apt install v4l2loopback-dkms\n   sudo modprobe v4l2loopback\n   ```\n\n   To find the virtual camera device, you can install v4l-utils:\n\n   ```bash\n   sudo apt install v4l-utils\n   v4l2-ctl --list-devices | grep -A 1 'OBS Virtual Camera' | grep -oP '\\t\\K/dev.*'\n   ```\n\n## 🐳 Docker\n\nA Docker configuration is provided for easy development and deployment on Linux.\n\n### Basic usage:\n\n```dockerfile\n# Build a basic image with required dependencies\nFROM ubuntu:latest\n\n# Install dependencies\nRUN apt-get update \u0026\u0026 apt-get install -y --no-install-recommends \\\n    python3 python3-pip \\\n    git cmake build-essential pkg-config libevdev-dev clang \\\n    libopencv-dev \\\n    libsndfile1 \\\n    pulseaudio \\\n    \u0026\u0026 apt-get clean \\\n    \u0026\u0026 rm -rf /var/lib/apt/lists/*\n\n# Install pamiq-io with desired optional dependencies\nRUN pip install \"git+https://github.com/games-on-whales/inputtino.git#subdirectory=bindings/python\u0026branch=stable\" \u0026\u0026 \\\n    pip install pamiq-io[inputtino,opencv,osc,soundcard,demo]\n\n# For development, you may want to check our devcontainer configuration:\n# https://github.com/MLShukai/pamiq-io/blob/main/.devcontainer/Dockerfile\n```\n\nWhen running the container, you need privileged access for hardware devices:\n\n```bash\ndocker run --privileged -it your-pamiq-image\n```\n\n\u003e \\[!IMPORTANT\\]\n\u003e ⚠️ **Note**: The `--privileged` flag is required for hardware access to input devices.\n\n### PulseAudio in Docker (Linux host only)\n\nTo use audio inside Docker, you need to set up PulseAudio properly:\n\n```bash\ndocker run --privileged -it \\\n    -v ${XDG_RUNTIME_DIR}/pulse/native:${XDG_RUNTIME_DIR}/pulse/native \\\n    -v $HOME/.config/pulse/cookie:/root/.config/pulse/cookie \\\n    -e PULSE_SERVER=unix:${XDG_RUNTIME_DIR}/pulse/native \\\n    -e PULSE_COOKIE=/root/.config/pulse/cookie \\\n    your-pamiq-image\n```\n\n## 📚 Usage\n\n### Video Input\n\n```python\n# If OpenCV is installed:\nfrom pamiq_io.video import OpenCVVideoInput\nfrom pamiq_io.video.input.opencv import show_video_devices\n\n# List available video devices\nshow_video_devices()\n\n# Capture from camera using default parameters\nvideo_input = OpenCVVideoInput(camera=0)\nframe = video_input.read()\n\n# Capture with specific resolution\nvideo_input = OpenCVVideoInput(camera=0, width=640, height=480, fps=30.0)\nframe = video_input.read()\n\n# Capture with mixed parameters (use default width, but specify height)\nvideo_input = OpenCVVideoInput(camera=0, width=None, height=720, fps=None)\nframe = video_input.read()\n```\n\n### Audio Input/Output\n\n```python\n# If SoundCard is installed:\nfrom pamiq_io.audio import SoundcardAudioInput, SoundcardAudioOutput\nfrom pamiq_io.audio.input.soundcard import show_all_input_devices\nfrom pamiq_io.audio.output.soundcard import show_all_output_devices\n\n# List available devices\nshow_all_input_devices()\nshow_all_output_devices()\n\n# Capture audio\naudio_input = SoundcardAudioInput(sample_rate=44100, channels=2)\naudio_data = audio_input.read(frame_size=1024)\n\n# Play audio\nimport numpy as np\nsample_rate = 44100\nduration = 1.0  # seconds\nt = np.linspace(0, duration, int(sample_rate * duration), endpoint=False)\nsine_wave = np.sin(2 * np.pi * 440 * t).reshape(-1, 1).astype(np.float32)  # 440Hz\n\naudio_output = SoundcardAudioOutput(sample_rate=sample_rate, channels=1)\naudio_output.write(sine_wave)\n```\n\n### OSC Communication\n\n```python\n# If python-osc is installed:\nfrom pamiq_io.osc import OscOutput, OscInput\n\n# Send OSC messages\nosc_output = OscOutput(host=\"127.0.0.1\", port=9001)\nosc_output.send(\"/test/address\", 42)\n\n# Receive OSC messages\ndef handler(addr, value):\n    print(f\"Received {value} from {addr}\")\n\nosc_input = OscInput(host=\"127.0.0.1\", port=9001)\nosc_input.add_handler(\"/test/address\", handler)\nosc_input.start(blocking=False)\n```\n\n### Keyboard Simulation\n\n#### Linux (Inputtino)\n\n```python\n# Linux only - if inputtino is installed:\nfrom pamiq_io.keyboard import Key, InputtinoKeyboardOutput\n\n# Using the InputtinoKeyboardOutput implementation\nkeyboard = InputtinoKeyboardOutput()\nkeyboard.press(Key.CTRL, Key.C)  # Press Ctrl+C\nkeyboard.release(Key.CTRL, Key.C)  # Release Ctrl+C\n```\n\n#### Windows\n\n```python\nfrom pamiq_io.keyboard import Key, WindowsKeyboardOutput\n\n# Using the WindowsKeyboardOutput implementation\nkeyboard = WindowsKeyboardOutput()\nkeyboard.press(Key.CTRL, Key.C)  # Press Ctrl+C\nkeyboard.release(Key.CTRL, Key.C)  # Release Ctrl+C\n```\n\n### Mouse Simulation\n\n#### Linux (Inputtino)\n\n```python\n# Linux only - if inputtino is installed:\nfrom pamiq_io.mouse import MouseButton, InputtinoMouseOutput\n\n# Using the InputtinoMouseOutput implementation\nmouse = InputtinoMouseOutput(fps=100)\nmouse.move(100, 50)  # Move 100 pixels/sec right, 50 pixels/sec down\nmouse.press(MouseButton.LEFT)\nmouse.release(MouseButton.LEFT)\n```\n\n#### Windows\n\n```python\nfrom pamiq_io.mouse import MouseButton, WindowsMouseOutput\n\n# Using the WindowsMouseOutput implementation\nmouse = WindowsMouseOutput()\nmouse.move(100, 50)  # Move 100 pixels/sec right, 50 pixels/sec down\nmouse.press(MouseButton.LEFT)\nmouse.release(MouseButton.LEFT)\n```\n\n## 🧪 Demo Scripts\n\nThe repo includes several demo scripts to help you get started:\n\n```bash\n# Audio demos (requires pamiq-io[soundcard,demo])\npython demos/soundcard_audio_input.py --list-devices\npython demos/soundcard_audio_output.py --frequency 440 --duration 3\n\n# Video demos (requires pamiq-io[opencv,demo])\npython demos/opencv_video_input.py --camera 0 --output frame.png\n\n# OSC demos (requires pamiq-io[osc])\npython demos/osc_io.py\n\n# Input simulation demos\n# Linux, requires pamiq-io[inputtino]\npython demos/inputtino_keyboard_output.py\npython demos/inputtino_mouse_output.py --radius 100 --duration 5\n\n# Windows, requires pamiq-io[windows]\npython demos/windows_keyboard_output.py\npython demos/windows_mouse_output.py --radius 100 --duration 5\n```\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Run tests (`make test`)\n4. Commit your changes (`git commit -m 'Add some amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlshukai%2Fpamiq-io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlshukai%2Fpamiq-io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlshukai%2Fpamiq-io/lists"}