@movementinfra/expo-twostep-video 0.1.0 → 0.1.1

package/README.md

@@ -9,8 +9,13 @@ Professional video editing for React Native, powered by native AVFoundation.
 
 - 🎬 **Load videos** from file system or Photos library
 - ✂️ **Trim videos** with frame-accurate precision
+- 🪞 **Mirror videos** horizontally, vertically, or both
+- ⏱️ **Speed adjustment** - slow motion (0.25x) to fast forward (4x)
+- 🔄 **Loop segments** - repeat video sections for perfect loops
+- 🎛️ **Combined transformations** - trim + mirror + speed in one operation
 - 🎞️ **Create multi-segment compositions** (highlight reels)
 - 📸 **Generate thumbnails** at any timestamp
+- 🎥 **Native video player** with playback controls
 - 💾 **Export** with customizable quality settings
 - 📊 **Real-time progress tracking** during exports
 - 🧹 **Automatic cleanup** of partial/temp files
@@ -108,6 +113,26 @@ function VideoEditor() {
 
 ## API Reference
 
+### Quick Reference
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `loadAsset({ uri })` | Load video from file URI | `VideoAsset` |
+| `loadAssetFromPhotos(id)` | Load from Photos library | `VideoAsset` |
+| `validateVideoUri(uri)` | Validate without loading | `boolean` |
+| `trimVideo({ assetId, startTime, endTime })` | Trim to time range | `VideoComposition` |
+| `trimVideoMultiple({ assetId, segments })` | Multi-segment trim | `VideoComposition` |
+| `mirrorVideo({ assetId, axis, startTime?, endTime? })` | Mirror/flip video | `VideoComposition` |
+| `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` |
+| `generateThumbnails({ assetId, times, size? })` | Extract frames | `string[]` (base64) |
+| `exportVideo({ compositionId, quality? })` | Export composition | `ExportResult` |
+| `exportAsset({ assetId, quality? })` | Export asset directly | `ExportResult` |
+| `releaseAsset(id)` | Free memory | `void` |
+| `releaseComposition(id)` | Free memory | `void` |
+| `releaseAll()` | Free all memory | `void` |
+
 ### Loading Videos
 
 #### `loadAsset(options)`
@@ -177,6 +202,149 @@ const thumbnails = await TwoStepVideo.generateThumbnails({
 <Image source={{ uri: `data:image/png;base64,${thumbnails[0]}` }} />
 ```
 
+### Video Mirroring
+
+#### `mirrorVideo(options)`
+Mirror (flip) a video horizontally, vertically, or both. Perfect for selfie videos that need to be flipped.
+
+```typescript
+// Mirror horizontally (flip left-right) - common for selfie videos
+const mirrored = await TwoStepVideo.mirrorVideo({
+  assetId: asset.id,
+  axis: 'horizontal'
+});
+
+// Mirror vertically (flip top-bottom)
+const flipped = await TwoStepVideo.mirrorVideo({
+  assetId: asset.id,
+  axis: 'vertical'
+});
+
+// Mirror both axes (180° rotation effect)
+const both = await TwoStepVideo.mirrorVideo({
+  assetId: asset.id,
+  axis: 'both'
+});
+
+// Mirror only a specific segment (5s to 10s)
+const partialMirror = await TwoStepVideo.mirrorVideo({
+  assetId: asset.id,
+  axis: 'horizontal',
+  startTime: 5,
+  endTime: 10
+});
+```
+
+### Speed Adjustment
+
+#### `adjustSpeed(options)`
+Change the playback speed of a video. Supports slow motion (< 1.0) and fast forward (> 1.0).
+
+```typescript
+// Slow motion (0.5x = 2x slower, video becomes twice as long)
+const slowMo = await TwoStepVideo.adjustSpeed({
+  assetId: asset.id,
+  speed: 0.5
+});
+
+// Very slow motion (0.25x = 4x slower)
+const verySlow = await TwoStepVideo.adjustSpeed({
+  assetId: asset.id,
+  speed: 0.25
+});
+
+// Fast forward (2x speed, video becomes half as long)
+const fastForward = await TwoStepVideo.adjustSpeed({
+  assetId: asset.id,
+  speed: 2.0
+});
+
+// Timelapse effect (4x speed)
+const timelapse = await TwoStepVideo.adjustSpeed({
+  assetId: asset.id,
+  speed: 4.0
+});
+
+// Speed up only a specific segment (10s to 30s becomes a quick timelapse)
+const partialSpeed = await TwoStepVideo.adjustSpeed({
+  assetId: asset.id,
+  speed: 4.0,
+  startTime: 10,
+  endTime: 30
+});
+```
+
+### Video Looping
+
+#### `loopSegment(options)`
+Loop a segment of video multiple times. Great for creating perfect loops for social media or extending short clips.
+
+```typescript
+// Loop a 2-second segment 3 times (plays 4 times total = 8 seconds)
+const looped = await TwoStepVideo.loopSegment({
+  assetId: asset.id,
+  startTime: 5,
+  endTime: 7,
+  loopCount: 3  // Repeats 3 times after first play
+});
+
+console.log(`Duration: ${looped.duration}s`);     // 8 seconds
+console.log(`Total plays: ${looped.totalPlays}`); // 4 times
+
+// Create a 15-second loop from a 3-second clip for Instagram/TikTok
+const socialLoop = await TwoStepVideo.loopSegment({
+  assetId: asset.id,
+  startTime: 0,
+  endTime: 3,
+  loopCount: 4  // 3s * 5 plays = 15 seconds
+});
+
+// Loop the best moment of a video
+const bestMoment = await TwoStepVideo.loopSegment({
+  assetId: asset.id,
+  startTime: 12.5,  // Start at 12.5 seconds
+  endTime: 14.0,    // 1.5 second clip
+  loopCount: 9      // 1.5s * 10 plays = 15 seconds
+});
+```
+
+### Combined Transformations
+
+#### `transformVideo(options)`
+Apply multiple transformations in a single operation: trim, mirror, and speed adjustment combined.
+
+```typescript
+// Mirror and slow down (selfie video correction + slow-mo effect)
+const transformed = await TwoStepVideo.transformVideo({
+  assetId: asset.id,
+  speed: 0.5,
+  mirrorAxis: 'horizontal'
+});
+
+// Just mirror (speed defaults to 1.0)
+const mirrored = await TwoStepVideo.transformVideo({
+  assetId: asset.id,
+  mirrorAxis: 'both'
+});
+
+// Trim + mirror + speed all at once
+const fullTransform = await TwoStepVideo.transformVideo({
+  assetId: asset.id,
+  speed: 2.0,
+  mirrorAxis: 'horizontal',
+  startTime: 0,
+  endTime: 10  // Take first 10 seconds, mirror it, speed it up
+});
+
+// Speed up without mirroring (just provide speed)
+const fastVersion = await TwoStepVideo.transformVideo({
+  assetId: asset.id,
+  speed: 1.5,
+  startTime: 5,
+  endTime: 15
+});
+```
+
 ### Exporting
 
 #### `exportVideo(options)`
@@ -200,6 +368,77 @@ const result = await TwoStepVideo.exportAsset({
 });
 ```
 
+### Video Player View
+
+#### `TwoStepVideoView`
+A native video player component for playing assets and compositions with full playback control.
+
+```tsx
+import { TwoStepVideoView, TwoStepVideoViewRef } from 'expo-twostep-video';
+import { useRef, useState } from 'react';
+import { View, Button, Text } from 'react-native';
+
+function VideoPlayer({ compositionId }: { compositionId: string }) {
+  const playerRef = useRef<TwoStepVideoViewRef>(null);
+  const [status, setStatus] = useState<string>('ready');
+  const [progress, setProgress] = useState(0);
+
+  return (
+    <View style={{ flex: 1 }}>
+      <TwoStepVideoView
+        ref={playerRef}
+        compositionId={compositionId}
+        loop={false}
+        onPlaybackStatusChange={(e) => setStatus(e.nativeEvent.status)}
+        onProgress={(e) => setProgress(e.nativeEvent.progress)}
+        onEnd={() => console.log('Video ended')}
+        onError={(e) => console.error(e.nativeEvent.error)}
+        style={{ width: '100%', height: 300 }}
+      />
+
+      <Text>Status: {status} | Progress: {Math.round(progress * 100)}%</Text>
+
+      <View style={{ flexDirection: 'row', gap: 10 }}>
+        <Button title="Play" onPress={() => playerRef.current?.play()} />
+        <Button title="Pause" onPress={() => playerRef.current?.pause()} />
+        <Button title="Seek 5s" onPress={() => playerRef.current?.seek(5)} />
+        <Button title="Replay" onPress={() => playerRef.current?.replay()} />
+      </View>
+    </View>
+  );
+}
+```
+
+#### Player Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `compositionId` | `string` | ID from `mirrorVideo`, `trimVideo`, `loopSegment`, etc. |
+| `assetId` | `string` | ID from `loadAsset` (for playing without transformations) |
+| `loop` | `boolean` | Enable continuous looping (default: `false`) |
+| `onPlaybackStatusChange` | `function` | Called when status changes (`ready`, `playing`, `paused`, `ended`, `seeked`) |
+| `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 |
+
+#### Player Methods (via ref)
+
+```typescript
+const playerRef = useRef<TwoStepVideoViewRef>(null);
+
+// Start playback
+await playerRef.current?.play();
+
+// Pause playback
+await playerRef.current?.pause();
+
+// Seek to specific time (in seconds)
+await playerRef.current?.seek(10.5);
+
+// Restart from beginning
+await playerRef.current?.replay();
+```
+
 ### Events
 
 #### `addExportProgressListener(callback)`
@@ -228,20 +467,41 @@ TwoStepVideo.releaseAll();
 TwoStepVideo.cleanupFile(tempFileUri);
 ```
 
-## Quality Presets
+## Constants
+
+### Quality Presets
 
 ```typescript
-TwoStepVideo.Quality.LOW       // ~0.1 bits per pixel
-TwoStepVideo.Quality.MEDIUM    // ~0.2 bits per pixel
-TwoStepVideo.Quality.HIGH      // ~0.4 bits per pixel (recommended)
-TwoStepVideo.Quality.HIGHEST   // ~0.8 bits per pixel
+TwoStepVideo.Quality.LOW       // ~0.1 bits per pixel - fast, small files
+TwoStepVideo.Quality.MEDIUM    // ~0.2 bits per pixel - good for web/social
+TwoStepVideo.Quality.HIGH      // ~0.4 bits per pixel (recommended default)
+TwoStepVideo.Quality.HIGHEST   // ~0.8 bits per pixel - archival quality
 ```
 
+### Mirror Axis
+
+```typescript
+TwoStepVideo.Mirror.HORIZONTAL  // Flip left-right (selfie correction)
+TwoStepVideo.Mirror.VERTICAL    // Flip top-bottom
+TwoStepVideo.Mirror.BOTH        // Flip both axes (180° rotation effect)
+```
+
+### Speed Ranges
+
+| Speed | Effect | Duration Change |
+|-------|--------|-----------------|
+| 0.25 | Very slow motion | 4x longer |
+| 0.5 | Slow motion | 2x longer |
+| 1.0 | Normal speed | No change |
+| 2.0 | Fast forward | 2x shorter |
+| 4.0 | Timelapse | 4x shorter |
+
 ## TypeScript Support
 
 Full TypeScript definitions included:
 
 ```typescript
+// Core types
 interface VideoAsset {
   id: string;
   duration: number;
@@ -260,6 +520,65 @@ interface ExportResult {
   uri: string;
   path: string;
 }
+
+// Transformation types
+type MirrorAxis = 'horizontal' | 'vertical' | 'both';
+type VideoQuality = 'low' | 'medium' | 'high' | 'highest';
+
+interface MirrorVideoOptions {
+  assetId: string;
+  axis: MirrorAxis;
+  startTime?: number;  // Optional: mirror only a segment
+  endTime?: number;
+}
+
+interface AdjustSpeedOptions {
+  assetId: string;
+  speed: number;       // 0.25 to 4.0
+  startTime?: number;
+  endTime?: number;
+}
+
+interface LoopSegmentOptions {
+  assetId: string;
+  startTime: number;
+  endTime: number;
+  loopCount: number;   // Repeats after first play
+}
+
+interface LoopResult {
+  id: string;
+  duration: number;
+  loopCount: number;
+  totalPlays: number;  // loopCount + 1
+}
+
+interface TransformVideoOptions {
+  assetId: string;
+  speed?: number;
+  mirrorAxis?: MirrorAxis;
+  startTime?: number;
+  endTime?: number;
+}
+
+// Player types
+interface TwoStepVideoViewProps {
+  compositionId?: string;
+  assetId?: string;
+  loop?: boolean;
+  onPlaybackStatusChange?: (event: { nativeEvent: PlaybackStatusEvent }) => void;
+  onProgress?: (event: { nativeEvent: ProgressEvent }) => void;
+  onEnd?: (event: { nativeEvent: {} }) => void;
+  onError?: (event: { nativeEvent: ErrorEvent }) => void;
+  style?: ViewStyle;
+}
+
+interface TwoStepVideoViewRef {
+  play: () => Promise<void>;
+  pause: () => Promise<void>;
+  seek: (time: number) => Promise<void>;
+  replay: () => Promise<void>;
+}
 ```
 
 ## Advanced Usage
@@ -291,6 +610,293 @@ async function createHighlightReel(videoUri: string) {
 }
 ```
 
+### Selfie Video Mirror & Loop
+
+A complete example for processing selfie videos with mirror correction and perfect loops:
+
+```tsx
+import React, { useState, useRef, useEffect } from 'react';
+import { View, Button, Text, StyleSheet, ActivityIndicator } from 'react-native';
+import * as TwoStepVideo from 'expo-twostep-video';
+import { TwoStepVideoView, TwoStepVideoViewRef } from 'expo-twostep-video';
+
+interface Props {
+  videoUri: string;
+}
+
+function SelfieVideoEditor({ videoUri }: Props) {
+  const playerRef = useRef<TwoStepVideoViewRef>(null);
+  const [asset, setAsset] = useState<TwoStepVideo.VideoAsset | null>(null);
+  const [composition, setComposition] = useState<TwoStepVideo.VideoComposition | null>(null);
+  const [isProcessing, setIsProcessing] = useState(false);
+  const [exportProgress, setExportProgress] = useState(0);
+
+  // Load the video asset
+  useEffect(() => {
+    async function loadVideo() {
+      const loaded = await TwoStepVideo.loadAsset({ uri: videoUri });
+      setAsset(loaded);
+    }
+    loadVideo();
+
+    return () => {
+      // Cleanup on unmount
+      TwoStepVideo.releaseAll();
+    };
+  }, [videoUri]);
+
+  // Mirror the selfie video (fix the mirror effect from front camera)
+  const handleMirror = async () => {
+    if (!asset) return;
+    setIsProcessing(true);
+
+    const mirrored = await TwoStepVideo.mirrorVideo({
+      assetId: asset.id,
+      axis: 'horizontal'
+    });
+
+    setComposition(mirrored);
+    setIsProcessing(false);
+  };
+
+  // Create a slow-motion effect
+  const handleSlowMo = async () => {
+    if (!asset) return;
+    setIsProcessing(true);
+
+    const slowMo = await TwoStepVideo.adjustSpeed({
+      assetId: asset.id,
+      speed: 0.5  // Half speed
+    });
+
+    setComposition(slowMo);
+    setIsProcessing(false);
+  };
+
+  // Mirror + slow motion combined
+  const handleMirrorAndSlowMo = async () => {
+    if (!asset) return;
+    setIsProcessing(true);
+
+    const transformed = await TwoStepVideo.transformVideo({
+      assetId: asset.id,
+      speed: 0.5,
+      mirrorAxis: 'horizontal'
+    });
+
+    setComposition(transformed);
+    setIsProcessing(false);
+  };
+
+  // Create a perfect loop for social media
+  const handleCreateLoop = async () => {
+    if (!asset) return;
+    setIsProcessing(true);
+
+    // Loop the first 3 seconds to create 15 seconds of content
+    const looped = await TwoStepVideo.loopSegment({
+      assetId: asset.id,
+      startTime: 0,
+      endTime: 3,
+      loopCount: 4  // 3s * 5 plays = 15 seconds
+    });
+
+    setComposition(looped);
+    setIsProcessing(false);
+    console.log(`Created ${looped.totalPlays}-play loop, ${looped.duration}s duration`);
+  };
+
+  // Export the result
+  const handleExport = async () => {
+    if (!composition) return;
+
+    const subscription = TwoStepVideo.addExportProgressListener((event) => {
+      setExportProgress(event.progress);
+    });
+
+    try {
+      const result = await TwoStepVideo.exportVideo({
+        compositionId: composition.id,
+        quality: 'high'
+      });
+
+      alert(`Exported to: ${result.uri}`);
+    } finally {
+      subscription.remove();
+      setExportProgress(0);
+    }
+  };
+
+  if (!asset) {
+    return <ActivityIndicator size="large" />;
+  }
+
+  return (
+    <View style={styles.container}>
+      {/* Video Player */}
+      <TwoStepVideoView
+        ref={playerRef}
+        compositionId={composition?.id}
+        assetId={!composition ? asset.id : undefined}
+        loop={true}
+        style={styles.video}
+      />
+
+      {/* Video Info */}
+      <Text style={styles.info}>
+        Duration: {composition?.duration.toFixed(1) || asset.duration.toFixed(1)}s |
+        Size: {asset.width}x{asset.height}
+      </Text>
+
+      {/* Processing Indicator */}
+      {isProcessing && <ActivityIndicator size="small" />}
+
+      {/* Transformation Buttons */}
+      <View style={styles.buttons}>
+        <Button title="Mirror" onPress={handleMirror} disabled={isProcessing} />
+        <Button title="Slow-Mo" onPress={handleSlowMo} disabled={isProcessing} />
+        <Button title="Mirror + Slow" onPress={handleMirrorAndSlowMo} disabled={isProcessing} />
+        <Button title="Create Loop" onPress={handleCreateLoop} disabled={isProcessing} />
+      </View>
+
+      {/* Playback Controls */}
+      <View style={styles.controls}>
+        <Button title="Play" onPress={() => playerRef.current?.play()} />
+        <Button title="Pause" onPress={() => playerRef.current?.pause()} />
+        <Button title="Replay" onPress={() => playerRef.current?.replay()} />
+      </View>
+
+      {/* Export */}
+      {composition && (
+        <View style={styles.export}>
+          <Button title="Export Video" onPress={handleExport} />
+          {exportProgress > 0 && (
+            <Text>Exporting: {Math.round(exportProgress * 100)}%</Text>
+          )}
+        </View>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, padding: 16 },
+  video: { width: '100%', height: 300, backgroundColor: '#000' },
+  info: { textAlign: 'center', marginVertical: 8 },
+  buttons: { flexDirection: 'row', flexWrap: 'wrap', gap: 8, marginVertical: 8 },
+  controls: { flexDirection: 'row', justifyContent: 'center', gap: 16 },
+  export: { marginTop: 16, alignItems: 'center' },
+});
+
+export default SelfieVideoEditor;
+```
+
+### Timestamp-Based Effects
+
+Apply different effects to specific timestamps/segments of a video:
+
+```typescript
+import * as TwoStepVideo from 'expo-twostep-video';
+
+async function applyTimestampEffects(videoUri: string) {
+  const asset = await TwoStepVideo.loadAsset({ uri: videoUri });
+
+  // Example: Mirror only the segment from 5s to 10s
+  const mirroredSegment = await TwoStepVideo.mirrorVideo({
+    assetId: asset.id,
+    axis: 'horizontal',
+    startTime: 5,
+    endTime: 10
+  });
+
+  // Example: Speed up only a boring middle section (10s to 30s at 4x speed)
+  const timelapseMiddle = await TwoStepVideo.adjustSpeed({
+    assetId: asset.id,
+    speed: 4.0,
+    startTime: 10,
+    endTime: 30
+  });
+
+  // Example: Transform a specific segment (trim + mirror + speed)
+  const transformedClip = await TwoStepVideo.transformVideo({
+    assetId: asset.id,
+    speed: 0.5,          // Slow motion
+    mirrorAxis: 'horizontal',
+    startTime: 45,       // Best moment starts at 45s
+    endTime: 50          // 5 seconds of slow-mo mirrored footage
+  });
+
+  return transformedClip;
+}
+```
+
+### Create Social Media Loop with Mirror
+
+Perfect for TikTok/Instagram Reels - select a short segment, mirror it, and loop it:
+
+```typescript
+async function createSocialMediaLoop(
+  videoUri: string,
+  startTime: number,
+  endTime: number,
+  targetDuration: number = 15
+) {
+  const asset = await TwoStepVideo.loadAsset({ uri: videoUri });
+
+  // First, create the mirrored and trimmed base clip
+  const mirroredClip = await TwoStepVideo.transformVideo({
+    assetId: asset.id,
+    mirrorAxis: 'horizontal',
+    startTime,
+    endTime
+  });
+
+  // Export the mirrored clip first (loopSegment needs the original asset)
+  const exportedMirror = await TwoStepVideo.exportVideo({
+    compositionId: mirroredClip.id,
+    quality: 'high'
+  });
+
+  // Load the exported mirrored video
+  const mirroredAsset = await TwoStepVideo.loadAsset({
+    uri: exportedMirror.uri
+  });
+
+  // Calculate how many loops needed to reach target duration
+  const clipDuration = endTime - startTime;
+  const loopCount = Math.ceil(targetDuration / clipDuration) - 1;
+
+  // Create the loop
+  const looped = await TwoStepVideo.loopSegment({
+    assetId: mirroredAsset.id,
+    startTime: 0,
+    endTime: mirroredAsset.duration,
+    loopCount
+  });
+
+  console.log(`Created ${looped.duration}s loop from ${clipDuration}s clip`);
+
+  // Export final result
+  const result = await TwoStepVideo.exportVideo({
+    compositionId: looped.id,
+    quality: 'high'
+  });
+
+  // Cleanup intermediate files
+  TwoStepVideo.cleanupFile(exportedMirror.uri);
+
+  return result;
+}
+
+// Usage
+const socialLoop = await createSocialMediaLoop(
+  'file:///path/to/selfie.mp4',
+  5.0,   // Start at 5 seconds
+  8.0,   // End at 8 seconds (3 second clip)
+  15     // Target 15 seconds for Instagram
+);
+```
+
 ### With Progress Bar
 
 ```typescript

package/package.json

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