https://github.com/mlshukai/pamiq-io
Versatile I/O library for Python, providing easy access to audio, video, and input device capabilities.
https://github.com/mlshukai/pamiq-io
audio directinput inputtino keyboard linux mouse obs-studio opencv-python osc python video windows
Last synced: 11 months ago
JSON representation
Versatile I/O library for Python, providing easy access to audio, video, and input device capabilities.
- Host: GitHub
- URL: https://github.com/mlshukai/pamiq-io
- Owner: MLShukai
- License: mit
- Created: 2025-04-05T14:08:45.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-12T02:07:46.000Z (12 months ago)
- Last Synced: 2025-06-12T04:38:41.937Z (12 months ago)
- Topics: audio, directinput, inputtino, keyboard, linux, mouse, obs-studio, opencv-python, osc, python, video, windows
- Language: Python
- Homepage:
- Size: 257 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pamiq-io
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings)
**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\.
## ✨ Features
- 🎤 Audio input/output via SoundCard
- 📹 Video input via OpenCV
- 🎛️ OSC (Open Sound Control) communication
- ⌨️ Keyboard simulation (Linux and Windows)
- 🖱️ Mouse simulation (Linux and Windows)
## 🔧 Requirements
- Python 3.12+
- Platform-specific dependencies:
- **Linux**: Inputtino (for keyboard/mouse simulation)
- OBS Studio (for video capture)
## 📦 Installation
### Using pip
```bash
# Install the base package
pip install pamiq-io
# Install with optional dependencies as needed
pip install pamiq-io[opencv] # For video input (all platforms)
pip install pamiq-io[osc] # For OSC communication (all platforms)
pip install pamiq-io[soundcard] # For audio input/output (all platforms)
# Platform-specific input simulation:
# For Linux:
pip install pamiq-io[inputtino] # For keyboard and mouse output on Linux
# For Windows:
pip install pamiq-io[windows] # For keyboard and mouse output on Windows
# For running demo scripts
pip install pamiq-io[demo]
```
### Linux-specific setup
**For keyboard and mouse output on Linux, you must first install [inputtino](https://github.com/games-on-whales/inputtino/tree/stable/bindings/python).**
### Development installation
```bash
# Clone and setup
git clone https://github.com/MLShukai/pamiq-io.git
cd pamiq-io
make venv # Sets up virtual environment with all dependencies
```
## 🧰 Command-Line Tools
pamiq-io includes several helpful command-line tools:
```bash
# List available video input devices
pamiq-io-show-opencv-available-input-devices
# List available audio input devices
pamiq-io-show-soundcard-available-input-devices
# List available audio output devices
pamiq-io-show-soundcard-available-output-devices
```
## 🛠️ Setup
### OBS Virtual Camera
1. Install OBS Studio following the official installation instructions:
- Visit [https://obsproject.com](https://obsproject.com)
- Follow the installation guide for your platform (Windows or Linux)
2. In OBS, start the virtual camera (Tools → Start Virtual Camera)
3. Linux-specific: If the virtual camera functionality is not available after installing OBS on Linux, you may need to install v4l2loopback:
```bash
sudo apt install v4l2loopback-dkms
sudo modprobe v4l2loopback
```
To find the virtual camera device, you can install v4l-utils:
```bash
sudo apt install v4l-utils
v4l2-ctl --list-devices | grep -A 1 'OBS Virtual Camera' | grep -oP '\t\K/dev.*'
```
## 🐳 Docker
A Docker configuration is provided for easy development and deployment on Linux.
### Basic usage:
```dockerfile
# Build a basic image with required dependencies
FROM ubuntu:latest
# Install dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
python3 python3-pip \
git cmake build-essential pkg-config libevdev-dev clang \
libopencv-dev \
libsndfile1 \
pulseaudio \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
# Install pamiq-io with desired optional dependencies
RUN pip install "git+https://github.com/games-on-whales/inputtino.git#subdirectory=bindings/python&branch=stable" && \
pip install pamiq-io[inputtino,opencv,osc,soundcard,demo]
# For development, you may want to check our devcontainer configuration:
# https://github.com/MLShukai/pamiq-io/blob/main/.devcontainer/Dockerfile
```
When running the container, you need privileged access for hardware devices:
```bash
docker run --privileged -it your-pamiq-image
```
> \[!IMPORTANT\]
> ⚠️ **Note**: The `--privileged` flag is required for hardware access to input devices.
### PulseAudio in Docker (Linux host only)
To use audio inside Docker, you need to set up PulseAudio properly:
```bash
docker run --privileged -it \
-v ${XDG_RUNTIME_DIR}/pulse/native:${XDG_RUNTIME_DIR}/pulse/native \
-v $HOME/.config/pulse/cookie:/root/.config/pulse/cookie \
-e PULSE_SERVER=unix:${XDG_RUNTIME_DIR}/pulse/native \
-e PULSE_COOKIE=/root/.config/pulse/cookie \
your-pamiq-image
```
## 📚 Usage
### Video Input
```python
# If OpenCV is installed:
from pamiq_io.video import OpenCVVideoInput
from pamiq_io.video.input.opencv import show_video_devices
# List available video devices
show_video_devices()
# Capture from camera using default parameters
video_input = OpenCVVideoInput(camera=0)
frame = video_input.read()
# Capture with specific resolution
video_input = OpenCVVideoInput(camera=0, width=640, height=480, fps=30.0)
frame = video_input.read()
# Capture with mixed parameters (use default width, but specify height)
video_input = OpenCVVideoInput(camera=0, width=None, height=720, fps=None)
frame = video_input.read()
```
### Audio Input/Output
```python
# If SoundCard is installed:
from pamiq_io.audio import SoundcardAudioInput, SoundcardAudioOutput
from pamiq_io.audio.input.soundcard import show_all_input_devices
from pamiq_io.audio.output.soundcard import show_all_output_devices
# List available devices
show_all_input_devices()
show_all_output_devices()
# Capture audio
audio_input = SoundcardAudioInput(sample_rate=44100, channels=2)
audio_data = audio_input.read(frame_size=1024)
# Play audio
import numpy as np
sample_rate = 44100
duration = 1.0 # seconds
t = np.linspace(0, duration, int(sample_rate * duration), endpoint=False)
sine_wave = np.sin(2 * np.pi * 440 * t).reshape(-1, 1).astype(np.float32) # 440Hz
audio_output = SoundcardAudioOutput(sample_rate=sample_rate, channels=1)
audio_output.write(sine_wave)
```
### OSC Communication
```python
# If python-osc is installed:
from pamiq_io.osc import OscOutput, OscInput
# Send OSC messages
osc_output = OscOutput(host="127.0.0.1", port=9001)
osc_output.send("/test/address", 42)
# Receive OSC messages
def handler(addr, value):
print(f"Received {value} from {addr}")
osc_input = OscInput(host="127.0.0.1", port=9001)
osc_input.add_handler("/test/address", handler)
osc_input.start(blocking=False)
```
### Keyboard Simulation
#### Linux (Inputtino)
```python
# Linux only - if inputtino is installed:
from pamiq_io.keyboard import Key, InputtinoKeyboardOutput
# Using the InputtinoKeyboardOutput implementation
keyboard = InputtinoKeyboardOutput()
keyboard.press(Key.CTRL, Key.C) # Press Ctrl+C
keyboard.release(Key.CTRL, Key.C) # Release Ctrl+C
```
#### Windows
```python
from pamiq_io.keyboard import Key, WindowsKeyboardOutput
# Using the WindowsKeyboardOutput implementation
keyboard = WindowsKeyboardOutput()
keyboard.press(Key.CTRL, Key.C) # Press Ctrl+C
keyboard.release(Key.CTRL, Key.C) # Release Ctrl+C
```
### Mouse Simulation
#### Linux (Inputtino)
```python
# Linux only - if inputtino is installed:
from pamiq_io.mouse import MouseButton, InputtinoMouseOutput
# Using the InputtinoMouseOutput implementation
mouse = InputtinoMouseOutput(fps=100)
mouse.move(100, 50) # Move 100 pixels/sec right, 50 pixels/sec down
mouse.press(MouseButton.LEFT)
mouse.release(MouseButton.LEFT)
```
#### Windows
```python
from pamiq_io.mouse import MouseButton, WindowsMouseOutput
# Using the WindowsMouseOutput implementation
mouse = WindowsMouseOutput()
mouse.move(100, 50) # Move 100 pixels/sec right, 50 pixels/sec down
mouse.press(MouseButton.LEFT)
mouse.release(MouseButton.LEFT)
```
## 🧪 Demo Scripts
The repo includes several demo scripts to help you get started:
```bash
# Audio demos (requires pamiq-io[soundcard,demo])
python demos/soundcard_audio_input.py --list-devices
python demos/soundcard_audio_output.py --frequency 440 --duration 3
# Video demos (requires pamiq-io[opencv,demo])
python demos/opencv_video_input.py --camera 0 --output frame.png
# OSC demos (requires pamiq-io[osc])
python demos/osc_io.py
# Input simulation demos
# Linux, requires pamiq-io[inputtino]
python demos/inputtino_keyboard_output.py
python demos/inputtino_mouse_output.py --radius 100 --duration 5
# Windows, requires pamiq-io[windows]
python demos/windows_keyboard_output.py
python demos/windows_mouse_output.py --radius 100 --duration 5
```
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Run tests (`make test`)
4. Commit your changes (`git commit -m 'Add some amazing feature'`)
5. Push to the branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request