@movementinfra/expo-twostep-video 0.1.11 → 0.1.12

package/README.md

@@ -126,6 +126,7 @@ function VideoEditor() {
 | `adjustSpeed({ assetId, speed, startTime?, endTime? })` | Change speed | `VideoComposition` |
 | `loopSegment({ assetId, startTime, endTime, loopCount })` | Loop a segment | `LoopResult` |
 | `transformVideo({ assetId, speed?, mirrorAxis?, startTime?, endTime? })` | Combined transform | `VideoComposition` |
+| `panZoomVideo({ assetId, panX, panY, zoomLevel })` | Apply pan/zoom crop | `VideoComposition` |
 | `generateThumbnails({ assetId, times, size? })` | Extract frames | `string[]` (base64) |
 | `exportVideo({ compositionId, quality? })` | Export composition | `ExportResult` |
 | `exportAsset({ assetId, quality? })` | Export asset directly | `ExportResult` |
@@ -420,6 +421,7 @@ function VideoPlayer({ compositionId }: { compositionId: string }) {
 | `onProgress` | `function` | Called periodically with `{ currentTime, duration, progress }` |
 | `onEnd` | `function` | Called when video ends (not called if `loop` is true) |
 | `onError` | `function` | Called on playback error |
+| `onPanZoomChange` | `function` | Called when user pinches/pans with `{ panX, panY, zoomLevel }` |
 
 #### Player Methods (via ref)
 
@@ -439,6 +441,205 @@ await playerRef.current?.seek(10.5);
 await playerRef.current?.replay();
 ```
 
+### Pan & Zoom
+
+The `TwoStepVideoView` component supports interactive pan and zoom gestures, allowing users to zoom into video content and pan around while zoomed.
+
+#### Gesture Controls
+
+| Gesture | Action |
+|---------|--------|
+| Pinch (2 fingers) | Zoom in/out (1x to 5x) |
+| Drag (2 fingers) | Pan around when zoomed in |
+
+#### Pan/Zoom Events
+
+Listen for pan/zoom state changes with the `onPanZoomChange` prop:
+
+```tsx
+import { TwoStepVideoView, PanZoomState } from 'expo-twostep-video';
+
+function VideoWithZoom() {
+  const [panZoom, setPanZoom] = useState<PanZoomState>({
+    panX: 0,
+    panY: 0,
+    zoomLevel: 1,
+  });
+
+  return (
+    <View>
+      <TwoStepVideoView
+        assetId={asset.id}
+        onPanZoomChange={(e) => setPanZoom(e.nativeEvent)}
+        style={{ width: '100%', height: 300 }}
+      />
+
+      {panZoom.zoomLevel > 1 && (
+        <Text>
+          Zoom: {panZoom.zoomLevel.toFixed(1)}x |
+          Pan: ({panZoom.panX.toFixed(2)}, {panZoom.panY.toFixed(2)})
+        </Text>
+      )}
+    </View>
+  );
+}
+```
+
+#### Pan/Zoom Methods (via ref)
+
+Control pan/zoom programmatically using the player ref:
+
+```typescript
+const playerRef = useRef<TwoStepVideoViewRef>(null);
+
+// Get current pan/zoom state
+const state = await playerRef.current?.getPanZoomState();
+// Returns: { panX: number, panY: number, zoomLevel: number }
+
+// Set pan/zoom programmatically
+await playerRef.current?.setPanZoomState({
+  panX: 0.5,      // Pan right (range: -1 to 1)
+  panY: -0.3,     // Pan up (range: -1 to 1)
+  zoomLevel: 2.0  // 2x zoom (range: 1 to 5)
+});
+
+// Reset to default (no zoom, centered)
+await playerRef.current?.resetPanZoom();
+```
+
+#### Baking Pan/Zoom into Export
+
+To permanently apply the pan/zoom transform to a video for export, use `panZoomVideo`:
+
+```typescript
+import * as TwoStepVideo from 'expo-twostep-video';
+
+// Apply pan/zoom as a permanent transformation
+const composition = await TwoStepVideo.panZoomVideo({
+  assetId: asset.id,
+  panX: 0.3,       // Pan position (-1 to 1)
+  panY: -0.2,
+  zoomLevel: 1.5,  // Zoom level (1 to 5)
+});
+
+// Export the cropped/zoomed video
+const result = await TwoStepVideo.exportVideo({
+  compositionId: composition.id,
+  quality: 'high',
+});
+```
+
+#### Complete Pan/Zoom Example
+
+A full implementation with gesture preview and export:
+
+```tsx
+import React, { useState, useRef } from 'react';
+import { View, Button, Text, StyleSheet } from 'react-native';
+import * as TwoStepVideo from 'expo-twostep-video';
+import {
+  TwoStepVideoView,
+  TwoStepVideoViewRef,
+  PanZoomState,
+} from 'expo-twostep-video';
+
+function PanZoomEditor({ assetId }: { assetId: string }) {
+  const playerRef = useRef<TwoStepVideoViewRef>(null);
+  const [panZoom, setPanZoom] = useState<PanZoomState>({
+    panX: 0,
+    panY: 0,
+    zoomLevel: 1,
+  });
+
+  const hasTransform = panZoom.zoomLevel > 1 ||
+    panZoom.panX !== 0 ||
+    panZoom.panY !== 0;
+
+  const handleReset = async () => {
+    await playerRef.current?.resetPanZoom();
+    setPanZoom({ panX: 0, panY: 0, zoomLevel: 1 });
+  };
+
+  const handleApplyAndExport = async () => {
+    // Bake the pan/zoom into a composition
+    const composition = await TwoStepVideo.panZoomVideo({
+      assetId,
+      panX: panZoom.panX,
+      panY: panZoom.panY,
+      zoomLevel: panZoom.zoomLevel,
+    });
+
+    // Export the result
+    const result = await TwoStepVideo.exportVideo({
+      compositionId: composition.id,
+      quality: 'high',
+    });
+
+    // Reset the preview since transform is now baked in
+    await handleReset();
+
+    console.log('Exported to:', result.uri);
+  };
+
+  return (
+    <View style={styles.container}>
+      {/* Video Preview with Gestures */}
+      <TwoStepVideoView
+        ref={playerRef}
+        assetId={assetId}
+        onPanZoomChange={(e) => setPanZoom(e.nativeEvent)}
+        style={styles.video}
+      />
+
+      {/* Gesture Hint */}
+      <Text style={styles.hint}>
+        Pinch to zoom, drag with 2 fingers to pan
+      </Text>
+
+      {/* Transform Info */}
+      {hasTransform && (
+        <View style={styles.info}>
+          <Text>Zoom: {panZoom.zoomLevel.toFixed(2)}x</Text>
+          <Text>Pan X: {panZoom.panX.toFixed(3)}</Text>
+          <Text>Pan Y: {panZoom.panY.toFixed(3)}</Text>
+        </View>
+      )}
+
+      {/* Controls */}
+      <View style={styles.buttons}>
+        <Button
+          title="Reset"
+          onPress={handleReset}
+          disabled={!hasTransform}
+        />
+        <Button
+          title="Apply & Export"
+          onPress={handleApplyAndExport}
+          disabled={!hasTransform}
+        />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, padding: 16 },
+  video: { width: '100%', height: 300, backgroundColor: '#000' },
+  hint: { textAlign: 'center', color: '#666', marginTop: 8 },
+  info: { padding: 12, backgroundColor: '#f0f0f0', borderRadius: 8, marginTop: 12 },
+  buttons: { flexDirection: 'row', justifyContent: 'space-around', marginTop: 16 },
+});
+
+export default PanZoomEditor;
+```
+
+#### Pan/Zoom Notes
+
+- **Zoom range**: 1x (no zoom) to 5x by default
+- **Pan range**: -1 to 1 on both axes (only effective when zoomed in)
+- **Pan constraint**: Pan is automatically constrained to keep video content visible at the current zoom level
+- **Simulator testing**: Multi-touch gestures work best on real devices. The iOS Simulator uses Option+drag for pinch, which can be unreliable
+
 ### Events
 
 #### `addExportProgressListener(callback)`
@@ -570,6 +771,7 @@ interface TwoStepVideoViewProps {
   onProgress?: (event: { nativeEvent: ProgressEvent }) => void;
   onEnd?: (event: { nativeEvent: {} }) => void;
   onError?: (event: { nativeEvent: ErrorEvent }) => void;
+  onPanZoomChange?: (event: { nativeEvent: PanZoomState }) => void;
   style?: ViewStyle;
 }
 
@@ -578,6 +780,25 @@ interface TwoStepVideoViewRef {
   pause: () => Promise<void>;
   seek: (time: number) => Promise<void>;
   replay: () => Promise<void>;
+  getPanZoomState: () => Promise<PanZoomState>;
+  setPanZoomState: (state: Partial<PanZoomState>) => Promise<void>;
+  resetPanZoom: () => Promise<void>;
+}
+
+// Pan/Zoom types
+interface PanZoomState {
+  panX: number;      // Horizontal pan (-1 to 1, 0 = center)
+  panY: number;      // Vertical pan (-1 to 1, 0 = center)
+  zoomLevel: number; // Zoom level (1 to 5, 1 = no zoom)
+}
+
+interface PanZoomVideoOptions {
+  assetId: string;
+  panX: number;
+  panY: number;
+  zoomLevel: number;
+  startTime?: number;
+  endTime?: number;
 }
 ```
 

package/ios/ExpoTwoStepVideoView.swift

@@ -42,8 +42,7 @@ class ExpoTwoStepVideoView: ExpoView {
     private var lastPinchScale: CGFloat = 1.0
 
     /// Starting pan position when gesture begins
-    private var panStartX: CGFloat = 0.0
-    private var panStartY: CGFloat = 0.0
+    private var panStartPosition: CGPoint = .zero
 
     /// Minimum zoom level (configurable)
     var minZoom: CGFloat = 1.0
@@ -55,6 +54,25 @@ class ExpoTwoStepVideoView: ExpoView {
     private var pinchGesture: UIPinchGestureRecognizer?
     private var panGesture: UIPanGestureRecognizer?
 
+    // MARK: - Pan/Zoom Helpers
+
+    /// Maximum pan amount allowed at current zoom level
+    /// At zoom 2x, this is 0.5 (can pan halfway). At zoom 1x, this is 0.
+    private var maxPanAmount: CGFloat {
+        guard currentZoom > 1.0 else { return 0 }
+        return (currentZoom - 1.0) / currentZoom
+    }
+
+    /// Clamp a value between min and max bounds
+    private func clamp(_ value: CGFloat, min minValue: CGFloat, max maxValue: CGFloat) -> CGFloat {
+        return Swift.min(Swift.max(value, minValue), maxValue)
+    }
+
+    /// Whether pan/zoom is at the default (untransformed) state
+    private var isAtDefaultTransform: Bool {
+        return currentZoom == 1.0 && currentPanX == 0 && currentPanY == 0
+    }
+
     // MARK: - Initialization
 
     required init(appContext: AppContext? = nil) {
@@ -183,19 +201,16 @@ class ExpoTwoStepVideoView: ExpoView {
         case .began:
             lastPinchScale = 1.0
         case .changed:
-            // Calculate incremental scale change
+            // Calculate incremental scale change from last gesture update
             let scaleChange = gesture.scale / lastPinchScale
             lastPinchScale = gesture.scale
 
-            // Apply to current zoom
-            let newZoom = currentZoom * scaleChange
-            currentZoom = min(max(newZoom, minZoom), maxZoom)
+            // Apply zoom with clamping to valid range
+            currentZoom = clamp(currentZoom * scaleChange, min: minZoom, max: maxZoom)
 
-            // Constrain pan when zoom changes
+            // Constrain pan (may need adjustment when zoom decreases)
             constrainPan()
-
-            updateLayerTransform()
-            emitPanZoomChange()
+            applyTransformAndNotify()
         case .ended, .cancelled:
             lastPinchScale = 1.0
         default:
@@ -209,29 +224,23 @@ class ExpoTwoStepVideoView: ExpoView {
 
         switch gesture.state {
         case .began:
-            panStartX = currentPanX
-            panStartY = currentPanY
+            panStartPosition = CGPoint(x: currentPanX, y: currentPanY)
         case .changed:
             let translation = gesture.translation(in: self)
 
-            // Convert translation to normalized pan values
-            // When zoomed in 2x, a full-width drag should change pan by the available pan range
-            let availablePanX = (currentZoom - 1.0) / currentZoom
-            let availablePanY = (currentZoom - 1.0) / currentZoom
+            // Convert screen translation to normalized pan delta
+            // Dragging full width changes pan by 2x the available pan range
+            let panDelta = CGPoint(
+                x: (translation.x / bounds.width) * 2 * maxPanAmount,
+                y: (translation.y / bounds.height) * 2 * maxPanAmount
+            )
 
-            // Normalize translation to view size
-            let normalizedDeltaX = translation.x / bounds.width
-            let normalizedDeltaY = translation.y / bounds.height
+            // Apply delta from start position (negative because dragging right shows left content)
+            currentPanX = panStartPosition.x - panDelta.x
+            currentPanY = panStartPosition.y - panDelta.y
 
-            // Scale by available pan range and apply
-            currentPanX = panStartX - normalizedDeltaX * 2 * availablePanX
-            currentPanY = panStartY - normalizedDeltaY * 2 * availablePanY
-
-            // Constrain pan
             constrainPan()
-
-            updateLayerTransform()
-            emitPanZoomChange()
+            applyTransformAndNotify()
         case .ended, .cancelled:
             break
         default:
@@ -239,39 +248,35 @@ class ExpoTwoStepVideoView: ExpoView {
         }
     }
 
-    /// Constrain pan values so content stays visible
+    /// Constrain pan values to keep content visible at current zoom level
     private func constrainPan() {
-        // When zoomed, limit how far we can pan
-        // At zoom level 2x, we can pan at most to show the edge (normalized to -1...1)
-        let maxPanAmount = (currentZoom - 1.0) / currentZoom
-
-        currentPanX = min(max(currentPanX, -maxPanAmount), maxPanAmount)
-        currentPanY = min(max(currentPanY, -maxPanAmount), maxPanAmount)
+        let limit = maxPanAmount
+        currentPanX = clamp(currentPanX, min: -limit, max: limit)
+        currentPanY = clamp(currentPanY, min: -limit, max: limit)
+    }
 
-        // If not zoomed in, reset pan to center
-        if currentZoom <= 1.0 {
-            currentPanX = 0
-            currentPanY = 0
-        }
+    /// Apply transform to layer and notify JS of the change
+    private func applyTransformAndNotify() {
+        updateLayerTransform()
+        emitPanZoomChange()
     }
 
     /// Apply the current pan/zoom transform to the player layer
     private func updateLayerTransform() {
         guard let layer = playerLayer else { return }
 
-        var transform = CATransform3DIdentity
+        // Start with identity and apply zoom
+        var transform = CATransform3DScale(CATransform3DIdentity, currentZoom, currentZoom, 1.0)
 
-        // Apply zoom (scale)
-        transform = CATransform3DScale(transform, currentZoom, currentZoom, 1.0)
-
-        // Apply pan (translation) - scale the translation by zoom to account for scaled coordinate space
-        let translateX = -currentPanX * bounds.width * (currentZoom - 1.0) / (2.0 * currentZoom)
-        let translateY = -currentPanY * bounds.height * (currentZoom - 1.0) / (2.0 * currentZoom)
+        // Apply pan translation (scaled for zoomed coordinate space)
+        // Formula: translate by half the extra visible area in the zoom direction
+        let translateX = -currentPanX * bounds.width * maxPanAmount / 2.0
+        let translateY = -currentPanY * bounds.height * maxPanAmount / 2.0
         transform = CATransform3DTranslate(transform, translateX, translateY, 0)
 
-        // Apply transform with animation for smoothness
+        // Apply without implicit animations for responsive feel
         CATransaction.begin()
-        CATransaction.setDisableActions(true) // Disable implicit animations for responsiveness
+        CATransaction.setDisableActions(true)
         layer.transform = transform
         CATransaction.commit()
     }
@@ -299,7 +304,7 @@ class ExpoTwoStepVideoView: ExpoView {
     /// Set the pan/zoom state programmatically
     func setPanZoomState(panX: CGFloat?, panY: CGFloat?, zoomLevel: CGFloat?) {
         if let zoom = zoomLevel {
-            currentZoom = min(max(zoom, minZoom), maxZoom)
+            currentZoom = clamp(zoom, min: minZoom, max: maxZoom)
         }
         if let x = panX {
             currentPanX = x
@@ -309,8 +314,7 @@ class ExpoTwoStepVideoView: ExpoView {
         }
 
         constrainPan()
-        updateLayerTransform()
-        emitPanZoomChange()
+        applyTransformAndNotify()
     }
 
     /// Reset pan/zoom to default state
@@ -318,15 +322,14 @@ class ExpoTwoStepVideoView: ExpoView {
         currentZoom = 1.0
         currentPanX = 0.0
         currentPanY = 0.0
-        updateLayerTransform()
-        emitPanZoomChange()
+        applyTransformAndNotify()
     }
 
     override func layoutSubviews() {
         super.layoutSubviews()
         playerLayer?.frame = bounds
-        // Reapply transform after frame changes
-        if currentZoom != 1.0 || currentPanX != 0 || currentPanY != 0 {
+        // Reapply transform after frame changes (only if not at default)
+        if !isAtDefaultTransform {
             updateLayerTransform()
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@movementinfra/expo-twostep-video",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Minimal video editing for React Native using AVFoundation",
   "main": "build/index.js",
   "types": "build/index.d.ts",