npm - p5-phone - Versions diffs - 1.4.4 → 1.6.0 - Mend

p5-phone 1.4.4 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (72) hide show

package/README.md CHANGED Viewed

@@ -1,15 +1,14 @@
 # p5-phone
-![P5Phone.png](P5Phone.png)
+![P5Phone.png](p5-phone.png)
+*Illustration by [Angela Torchio](https://angelatorchio.com/)*
-**Simplified mobile hardware access for p5.js** - handle sensors, microphone, touch, and browser gestures with ease.
-##  [Link for Interactive Examples](https://digitalfuturesocadu.github.io/P5-Phone-Interactions/examples/homepage)
+##  [Link for Interactive Examples](https://npuckett.github.io/p5-phone/examples/homepage)
 # Overview
 P5.js on mobile provides unique opportunities and challenges. The main P5 framework does an excellent job of making it easy to read data from various phone inputs and sensors, however it doesn't deal with the realities of contemporary browser's built in gestures and security protocols.
 That's where this library comes in:
-- Simplifies accessing phone hardware from the browser (accelerometers, gyroscopes, microphone)
+- Simplifies accessing phone hardware from the browser (accelerometers, gyroscopes, microphone, vibration motor)
 - Simplifies disabling default phone gestures (Zoom, refresh, back, etc)
 - Simplifies enabling audio output
 - Simplifies using an on-screen console to display errors and debug info
@@ -61,16 +60,17 @@ This library simplifies access to the following p5.js mobile sensor and audio co
   - [Motion Sensor Activation](#motion-sensor-activation)
   - [Microphone Activation](#microphone-activation)
   - [Sound Output Activation](#sound-output-activation)
+  - [Vibration Motor (Android Only)](#vibration-motor-android-only)
   - [Debug System](#debug-system)
 ### CDN (Recommended)
 ```html
 <!-- Minified version (recommended) -->
-<script src="https://cdn.jsdelivr.net/npm/p5-phone@1.4.4/dist/p5-phone.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/p5-phone@1.5.0/dist/p5-phone.min.js"></script>
 <!-- Development version (larger, with comments) -->
-<!-- <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.4.4/dist/p5-phone.js"></script> -->
+<!-- <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.5.0/dist/p5-phone.js"></script> -->
 ```
 ### Basic Setup
@@ -98,7 +98,7 @@ This library simplifies access to the following p5.js mobile sensor and audio co
   <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.11.10/p5.min.js"></script>
   <!-- Load p5-phone library -->
-  <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.4.4/dist/p5-phone.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/p5-phone@1.5.0/dist/p5-phone.min.js"></script>
 </head>
 <body>
@@ -192,10 +192,17 @@ enableMicButton(text)     // Button-based microphone activation
 enableSoundTap(message)   // Tap anywhere to enable sound playback
 enableSoundButton(text)   // Button-based sound activation
+// Vibration motor (Android only)
+enableVibrationTap(message)   // Tap anywhere to enable vibration
+enableVibrationButton(text)   // Button-based vibration activation
+vibrate(pattern)              // Trigger vibration (duration or pattern array)
+stopVibration()               // Stop any ongoing vibration
 // Status variables (check these in your code)
 window.sensorsEnabled     // Boolean: true when motion sensors are active
 window.micEnabled         // Boolean: true when microphone is active
 window.soundEnabled       // Boolean: true when sound output is active
+window.vibrationEnabled   // Boolean: true when vibration is available (Android only)
 // Debug system (enhanced in v1.4.0)
 showDebug()       // Show on-screen debug panel with automatic error catching
@@ -226,6 +233,7 @@ this.enableGyroTap('Tap to start');
 - `window.sensorsEnabled` - Boolean indicating if motion sensors are active
 - `window.micEnabled` - Boolean indicating if microphone is active
 - `window.soundEnabled` - Boolean indicating if sound output is active
+- `window.vibrationEnabled` - Boolean indicating if vibration is available (Android only)
 **Usage:**
 ```javascript
@@ -245,6 +253,11 @@ function draw() {
     // Safe to play sounds
     mySound.play();
   }
+  if (window.vibrationEnabled) {
+    // Safe to use vibration (Android only)
+    vibrate(50);
+  }
 }
 // You can also use them for conditional UI
@@ -454,6 +467,255 @@ function mousePressed() {
 }
 ```
+### Vibration Motor (Android Only)
+**Purpose:** Access the device's vibration motor for haptic feedback and tactile interactions.
+**⚠️ Platform Support:**
+- ✅ **Android** - Full support in Chrome and most Android browsers
+- ❌ **iOS** - Not supported (Vibration API not available on iOS devices)
+**Important:** The vibration feature will automatically detect if the device supports vibration. On iOS or unsupported devices, `window.vibrationEnabled` will be `false` and vibration calls will be safely ignored with console warnings.
+**Commands:**
+- `enableVibrationTap(message)` - Tap anywhere on screen to enable vibration
+- `enableVibrationButton(text)` - Creates a button with custom text to enable vibration
+- `vibrate(pattern)` - Trigger vibration with a duration (ms) or pattern array
+- `stopVibration()` - Stop any ongoing vibration
+**Usage:**
+```javascript
+function setup() {
+  createCanvas(windowWidth, windowHeight);
+  // Enable vibration with tap (Android only)
+  enableVibrationTap('Tap to enable vibration');
+  // Or use a button
+  // enableVibrationButton('Enable Haptics');
+}
+function draw() {
+  background(220);
+  if (window.vibrationEnabled) {
+    text('Vibration ready! Tap anywhere', 20, 20);
+  } else {
+    text('Vibration not available', 20, 20);
+  }
+}
+function mousePressed() {
+  if (window.vibrationEnabled) {
+    // Simple vibration - 50ms pulse
+    vibrate(50);
+  }
+}
+```
+**Vibration Patterns:**
+```javascript
+// Single vibration (duration in milliseconds)
+vibrate(100);  // Vibrate for 100ms
+// Pattern: [vibrate, pause, vibrate, pause, ...]
+vibrate([100, 50, 100]);           // Short-short pattern
+vibrate([200, 100, 200, 100, 200]); // Triple pulse
+vibrate([50, 50, 50, 50, 500]);     // Quick taps then long
+// Stop any ongoing vibration
+stopVibration();
+```
+**Common Use Cases:**
+```javascript
+// Haptic feedback for button presses
+function mousePressed() {
+  if (window.vibrationEnabled) {
+    vibrate(20);  // Quick tap feedback
+  }
+}
+// Touch zones with different haptic patterns
+function touchStarted() {
+  if (window.vibrationEnabled) {
+    if (mouseX < width/2) {
+      vibrate(50);  // Left side - short pulse
+    } else {
+      vibrate([50, 30, 50]);  // Right side - double pulse
+    }
+  }
+  return false;
+}
+// Collision detection
+function checkCollision() {
+  if (collision && window.vibrationEnabled) {
+    vibrate([100, 50, 100, 50, 200]);  // Alert pattern
+  }
+}
+// Game events
+function gameOver() {
+  if (window.vibrationEnabled) {
+    vibrate(500);  // Long vibration for game over
+  }
+}
+```
+**Best Practices:**
+- Use short vibrations (20-100ms) for subtle feedback
+- Use patterns for more complex haptic responses
+- Always check `window.vibrationEnabled` before calling `vibrate()`
+- Don't overuse - vibration can quickly drain battery
+- Test on Android devices as iOS doesn't support vibration
+### PhoneCamera (ML5 Integration)
+**Purpose:** Simplified camera access optimized for ML5.js machine learning models (FaceMesh, HandPose, BodyPose, etc.). Handles camera initialization, coordinate mapping, mirroring, and display modes automatically.
+**Key Features:**
+- **Automatic Coordinate Mapping** - ML5 keypoints automatically mapped to canvas coordinates
+- **Mirror Support** - Handles front camera mirroring for natural interaction
+- **Display Modes** - Multiple video sizing options (fitHeight, cover, contain, fixed)
+- **ML5 Optimized** - Direct integration with ML5 v1.x models
+- **Auto-initialization** - Camera starts automatically when permissions are granted
+**Commands:**
+| Function | Purpose | Parameters |
+|----------|---------|------------|
+| `createPhoneCamera(active, mirror, mode)` | Create new camera instance | active: 'user' or 'environment'<br>mirror: true/false<br>mode: 'fitHeight', 'cover', 'contain', 'fixed' |
+| `enableCameraTap(message)` | Tap to enable camera | Optional message string |
+| `cam.onReady(callback)` | Execute code when camera ready | Callback function |
+| `cam.mapKeypoint(keypoint)` | Map single ML5 keypoint to screen | ML5 keypoint object |
+| `cam.mapKeypoints(keypoints)` | Map array of ML5 keypoints | Array of ML5 keypoints |
+**Properties:**
+| Property | Description | Type |
+|----------|-------------|------|
+| `cam.ready` | Camera initialization status | Boolean |
+| `cam.video` | p5.js video element | p5.Element |
+| `cam.active` | Current camera ('user'/'environment') | String |
+| `cam.mirror` | Mirror state | Boolean |
+| `cam.mode` | Display mode | String |
+| `cam.width` | Video width | Number |
+| `cam.height` | Video height | Number |
+**Basic Setup:**
+```javascript
+let cam;
+let facemesh;
+let faces = [];
+function setup() {
+  createCanvas(windowWidth, windowHeight);
+  // Create camera: front camera, mirrored, fit to canvas height
+  cam = createPhoneCamera('user', true, 'fitHeight');
+  // Enable camera (auto-starts if permission granted)
+  enableCameraTap();
+  // Start ML5 when camera is ready
+  cam.onReady(() => {
+    let options = {
+      maxFaces: 1,
+      refineLandmarks: false,
+      flipHorizontal: false  // cam.mapKeypoint() handles mirroring
+    };
+    facemesh = ml5.faceMesh(options, modelLoaded);
+  });
+}
+function modelLoaded() {
+  // Start detection - use cam.videoElement for ML5
+  facemesh.detectStart(cam.videoElement, (results) => {
+    faces = results;
+  });
+}
+function draw() {
+  background(220);
+  // Draw camera feed
+  if (cam.ready) {
+    image(cam, 0, 0);  // PhoneCamera handles positioning automatically
+  }
+  // Draw tracked face keypoints
+  if (faces.length > 0) {
+    let face = faces[0];
+    // Map nose tip keypoint (index 1) to screen coordinates
+    let nose = cam.mapKeypoint(face.keypoints[1]);
+    // Use coordinates for interaction
+    fill(255, 0, 0);
+    circle(nose.x, nose.y, 30);
+    // Map all keypoints at once
+    let allPoints = cam.mapKeypoints(face.keypoints);
+    for (let point of allPoints) {
+      circle(point.x, point.y, 3);
+    }
+  }
+}
+```
+**Display Modes:**
+| Mode | Behavior |
+|------|----------|
+| `'fitHeight'` | Scale video to canvas height (default, recommended) |
+| `'cover'` | Fill entire canvas (may crop video) |
+| `'contain'` | Fit entire video in canvas (may show letterboxing) |
+| `'fixed'` | Fixed size (set with `cam.fixedWidth`, `cam.fixedHeight`) |
+**Coordinate Mapping:**
+The `mapKeypoint()` and `mapKeypoints()` functions automatically handle:
+- Video-to-canvas scaling
+- Mirror transformation (for front camera)
+- Offset positioning (for different display modes)
+- 3D coordinates (preserves z-depth from BlazePose)
+```javascript
+// Single keypoint
+let nose = cam.mapKeypoint(face.keypoints[1]);
+console.log(nose.x, nose.y, nose.z);  // Screen coordinates + depth
+// Multiple keypoints
+let hands = cam.mapKeypoints(hand.keypoints);
+hands.forEach(point => {
+  circle(point.x, point.y, 5);
+});
+```
+**ML5 Model Examples:**
+```javascript
+// FaceMesh (468 keypoints)
+let options = { maxFaces: 1, refineLandmarks: false, flipHorizontal: false };
+facemesh = ml5.faceMesh(options, modelLoaded);
+// HandPose (21 keypoints per hand)
+let options = { maxHands: 2, runtime: 'mediapipe', flipHorizontal: false };
+handpose = ml5.handPose(options, modelLoaded);
+// BodyPose (33 keypoints with 3D)
+let options = { modelType: 'MULTIPOSE_LIGHTNING', flipped: false };
+bodypose = ml5.bodyPose('BlazePose', options, modelLoaded);
+```
+**Important Notes:**
+- Always set `flipHorizontal: false` in ML5 options (PhoneCamera handles mirroring)
+- Use `cam.videoElement` (native HTML video element) when passing to ML5's `detectStart()`
+- Check `cam.ready` before using video or drawing keypoints
+- Call `enableCameraTap()` to handle camera permissions automatically
 ### Debug System
 **Purpose:** Essential on-screen debugging system for mobile development where traditional browser dev tools aren't accessible. Provides automatic error catching, timestamped logging, and color-coded messages.