@movementinfra/expo-twostep-video 0.1.0

package/ios/TwoStepVideo/Models/ExportConfiguration.swift

@@ -0,0 +1,104 @@
+import Foundation
+import AVFoundation
+
+/// Configuration for video export operations
+public struct ExportConfiguration {
+
+    /// Output file type
+    public let fileType: AVFileType
+
+    /// Video codec to use for export
+    public let videoCodec: AVVideoCodecType
+
+    /// Video quality preset
+    public let quality: Quality
+
+    /// Output URL for the exported file
+    public let outputURL: URL
+
+    /// Whether to optimize for network use
+    public let optimizeForNetworkUse: Bool
+
+    /// Custom video settings (overrides quality preset if provided)
+    public let customVideoSettings: [String: Any]?
+
+    /// Custom audio settings
+    public let customAudioSettings: [String: Any]?
+
+    /// Video quality presets
+    public enum Quality {
+        case low
+        case medium
+        case high
+        case highest
+
+        /// Recommended bitrate for the quality level
+        /// - Parameter resolution: The video resolution
+        /// - Returns: Bitrate in bits per second
+        func bitrate(for resolution: CGSize) -> Int {
+            let pixels = resolution.width * resolution.height
+
+            switch self {
+            case .low:
+                return Int(pixels * 0.1) // ~0.1 bits per pixel
+            case .medium:
+                return Int(pixels * 0.2) // ~0.2 bits per pixel
+            case .high:
+                return Int(pixels * 0.4) // ~0.4 bits per pixel
+            case .highest:
+                return Int(pixels * 0.8) // ~0.8 bits per pixel
+            }
+        }
+    }
+
+    /// Initialize export configuration
+    /// - Parameters:
+    ///   - outputURL: URL where the exported file will be saved
+    ///   - fileType: Output file type (default: .mp4)
+    ///   - videoCodec: Video codec (default: .h264)
+    ///   - quality: Quality preset (default: .high)
+    ///   - optimizeForNetworkUse: Optimize for network streaming (default: true)
+    ///   - customVideoSettings: Custom video settings (default: nil)
+    ///   - customAudioSettings: Custom audio settings (default: nil)
+    public init(
+        outputURL: URL,
+        fileType: AVFileType = .mp4,
+        videoCodec: AVVideoCodecType = .h264,
+        quality: Quality = .high,
+        optimizeForNetworkUse: Bool = true,
+        customVideoSettings: [String: Any]? = nil,
+        customAudioSettings: [String: Any]? = nil
+    ) {
+        self.outputURL = outputURL
+        self.fileType = fileType
+        self.videoCodec = videoCodec
+        self.quality = quality
+        self.optimizeForNetworkUse = optimizeForNetworkUse
+        self.customVideoSettings = customVideoSettings
+        self.customAudioSettings = customAudioSettings
+    }
+
+    /// Create a default configuration with a generated temporary file URL
+    /// - Returns: A default export configuration
+    public static func `default`() -> ExportConfiguration {
+        let fileName = "export_\(UUID().uuidString).mp4"
+        let outputURL = FileManager.default.temporaryDirectory
+            .appendingPathComponent(fileName)
+        return ExportConfiguration(outputURL: outputURL)
+    }
+}
+
+// MARK: - CustomStringConvertible
+extension ExportConfiguration: CustomStringConvertible {
+    public var description: String {
+        return """
+        ExportConfiguration(
+            outputURL: \(outputURL.lastPathComponent),
+            fileType: \(fileType.rawValue),
+            codec: \(videoCodec.rawValue),
+            quality: \(quality),
+            optimizeForNetwork: \(optimizeForNetworkUse)
+        )
+        """
+    }
+}

package/ios/TwoStepVideo/Models/LoopConfiguration.swift

@@ -0,0 +1,101 @@
+import Foundation
+import AVFoundation
+
+/// Configuration for looping a video segment
+public struct LoopConfiguration {
+
+    /// The time range to loop
+    public let timeRange: TimeRange
+
+    /// Number of times to repeat the segment (total plays = loopCount + 1)
+    /// For example, loopCount = 2 means the segment plays 3 times total
+    public let loopCount: Int
+
+    /// Whether to include a seamless transition between loops
+    /// When true, attempts to create smoother loop transitions
+    public let seamless: Bool
+
+    /// Initialize a loop configuration
+    /// - Parameters:
+    ///   - timeRange: The time range to loop
+    ///   - loopCount: Number of additional times to repeat (minimum 1)
+    ///   - seamless: Whether to attempt seamless looping
+    /// - Throws: VideoEditingError.invalidConfiguration if loopCount < 1
+    public init(
+        timeRange: TimeRange,
+        loopCount: Int,
+        seamless: Bool = false
+    ) throws {
+        guard loopCount >= 1 else {
+            throw VideoEditingError.invalidConfiguration(
+                reason: "Loop count must be at least 1 (total plays = loopCount + 1)"
+            )
+        }
+
+        guard loopCount <= 100 else {
+            throw VideoEditingError.invalidConfiguration(
+                reason: "Loop count cannot exceed 100 to prevent excessive memory usage"
+            )
+        }
+
+        self.timeRange = timeRange
+        self.loopCount = loopCount
+        self.seamless = seamless
+    }
+
+    /// Create a loop configuration from seconds
+    /// - Parameters:
+    ///   - startSeconds: Start time in seconds
+    ///   - endSeconds: End time in seconds
+    ///   - loopCount: Number of times to repeat
+    ///   - seamless: Whether to attempt seamless looping
+    /// - Returns: A LoopConfiguration instance
+    /// - Throws: VideoEditingError if parameters are invalid
+    public static func fromSeconds(
+        start startSeconds: Double,
+        end endSeconds: Double,
+        loopCount: Int,
+        seamless: Bool = false
+    ) throws -> LoopConfiguration {
+        let timeRange = try TimeRange.fromSeconds(start: startSeconds, end: endSeconds)
+        return try LoopConfiguration(
+            timeRange: timeRange,
+            loopCount: loopCount,
+            seamless: seamless
+        )
+    }
+
+    /// Total number of times the segment will play (loopCount + 1)
+    public var totalPlays: Int {
+        return loopCount + 1
+    }
+
+    /// Total duration after looping
+    public var totalDuration: CMTime {
+        return CMTimeMultiply(timeRange.duration, multiplier: Int32(totalPlays))
+    }
+
+    /// Validate that this loop configuration fits within an asset's duration
+    /// - Parameter asset: The video asset to validate against
+    /// - Throws: VideoEditingError if the time range exceeds the asset duration
+    public func validate(against asset: VideoAsset) throws {
+        try timeRange.validate(against: asset)
+    }
+}
+
+// MARK: - CustomStringConvertible
+extension LoopConfiguration: CustomStringConvertible {
+    public var description: String {
+        let rangeDesc = timeRange.description
+        let totalSeconds = CMTimeGetSeconds(totalDuration)
+        return """
+        LoopConfiguration(
+            range: \(rangeDesc),
+            loopCount: \(loopCount),
+            totalPlays: \(totalPlays),
+            totalDuration: \(String(format: "%.2f", totalSeconds))s,
+            seamless: \(seamless)
+        )
+        """
+    }
+}

package/ios/TwoStepVideo/Models/TimeRange.swift

@@ -0,0 +1,98 @@
+import Foundation
+import AVFoundation
+
+/// Represents a time range for video editing operations
+public struct TimeRange {
+
+    /// The start time of the range
+    public let start: CMTime
+
+    /// The end time of the range
+    public let end: CMTime
+
+    /// Duration of the time range
+    public var duration: CMTime {
+        return CMTimeSubtract(end, start)
+    }
+
+    /// The CMTimeRange representation
+    public var cmTimeRange: CMTimeRange {
+        return CMTimeRange(start: start, duration: duration)
+    }
+
+    /// Initialize with start and end times
+    /// - Parameters:
+    ///   - start: Start time
+    ///   - end: End time
+    /// - Throws: VideoEditingError.invalidTimeRange if end <= start
+    public init(start: CMTime, end: CMTime) throws {
+        guard CMTimeCompare(end, start) > 0 else {
+            throw VideoEditingError.invalidTimeRange(
+                reason: "End time must be greater than start time"
+            )
+        }
+        self.start = start
+        self.end = end
+    }
+
+    /// Initialize with start time and duration
+    /// - Parameters:
+    ///   - start: Start time
+    ///   - duration: Duration of the range
+    /// - Throws: VideoEditingError.invalidTimeRange if duration <= 0
+    public init(start: CMTime, duration: CMTime) throws {
+        guard CMTimeCompare(duration, .zero) > 0 else {
+            throw VideoEditingError.invalidTimeRange(
+                reason: "Duration must be greater than zero"
+            )
+        }
+        self.start = start
+        self.end = CMTimeAdd(start, duration)
+    }
+
+    /// Create a time range from seconds
+    /// - Parameters:
+    ///   - startSeconds: Start time in seconds
+    ///   - endSeconds: End time in seconds
+    /// - Returns: A TimeRange instance
+    /// - Throws: VideoEditingError.invalidTimeRange if end <= start
+    public static func fromSeconds(
+        start startSeconds: Double,
+        end endSeconds: Double
+    ) throws -> TimeRange {
+        return try TimeRange(
+            start: CMTime(seconds: startSeconds, preferredTimescale: 600),
+            end: CMTime(seconds: endSeconds, preferredTimescale: 600)
+        )
+    }
+
+    /// Validate that this time range fits within an asset's duration
+    /// - Parameter asset: The video asset to validate against
+    /// - Throws: VideoEditingError.invalidTimeRange if the range exceeds the asset duration
+    public func validate(against asset: VideoAsset) throws {
+        let assetDuration = asset.duration
+
+        guard CMTimeCompare(start, .zero) >= 0 else {
+            throw VideoEditingError.invalidTimeRange(
+                reason: "Start time cannot be negative"
+            )
+        }
+
+        guard CMTimeCompare(end, assetDuration) <= 0 else {
+            throw VideoEditingError.invalidTimeRange(
+                reason: "End time exceeds asset duration (\(CMTimeGetSeconds(assetDuration))s)"
+            )
+        }
+    }
+}
+
+// MARK: - CustomStringConvertible
+extension TimeRange: CustomStringConvertible {
+    public var description: String {
+        let startSeconds = CMTimeGetSeconds(start)
+        let endSeconds = CMTimeGetSeconds(end)
+        let durationSeconds = CMTimeGetSeconds(duration)
+        return String(format: "TimeRange(%.2fs - %.2fs, duration: %.2fs)",
+                     startSeconds, endSeconds, durationSeconds)
+    }
+}

package/ios/TwoStepVideo/Models/VideoAsset.swift

@@ -0,0 +1,126 @@
+import Foundation
+import AVFoundation
+
+/// Represents a video asset with its composition and metadata
+public struct VideoAsset {
+
+    /// The underlying AVAsset
+    public let avAsset: AVAsset
+
+    /// The URL of the video asset (if available)
+    public let url: URL?
+
+    /// Cached duration of the video
+    private let _duration: CMTime?
+
+    /// Cached natural size of the video
+    private let _naturalSize: CGSize?
+
+    /// Cached frame rate of the video
+    private let _frameRate: Float?
+
+    /// Cached hasAudio flag
+    private let _hasAudio: Bool?
+
+    /// Duration of the video
+    public var duration: CMTime {
+        // Return cached duration (should always be set for properly loaded assets)
+        // For compositions, duration is passed during initialization
+        return _duration ?? .zero
+    }
+
+    /// Natural size of the video (may return nil if not yet loaded)
+    public var naturalSize: CGSize? {
+        return _naturalSize
+    }
+
+    /// Frame rate of the video (may return nil if not yet loaded)
+    public var frameRate: Float? {
+        return _frameRate
+    }
+
+    /// Whether the asset has audio (defaults to false if not loaded)
+    public var hasAudio: Bool {
+        return _hasAudio ?? false
+    }
+
+    /// Initialize with an AVAsset (basic initialization without preloading)
+    /// - Parameters:
+    ///   - avAsset: The AVAsset to wrap
+    ///   - url: Optional URL of the asset
+    public init(avAsset: AVAsset, url: URL? = nil) {
+        self.avAsset = avAsset
+        self.url = url
+        self._duration = nil
+        self._naturalSize = nil
+        self._frameRate = nil
+        self._hasAudio = nil
+    }
+
+    /// Initialize with preloaded metadata
+    /// - Parameters:
+    ///   - avAsset: The AVAsset to wrap
+    ///   - url: Optional URL of the asset
+    ///   - duration: Preloaded duration
+    ///   - naturalSize: Preloaded natural size
+    ///   - frameRate: Preloaded frame rate
+    ///   - hasAudio: Preloaded hasAudio flag
+    public init(
+        avAsset: AVAsset,
+        url: URL? = nil,
+        duration: CMTime,
+        naturalSize: CGSize?,
+        frameRate: Float?,
+        hasAudio: Bool
+    ) {
+        self.avAsset = avAsset
+        self.url = url
+        self._duration = duration
+        self._naturalSize = naturalSize
+        self._frameRate = frameRate
+        self._hasAudio = hasAudio
+    }
+
+    /// Load metadata asynchronously and return a new VideoAsset with cached values
+    public static func load(from avAsset: AVAsset, url: URL? = nil) async throws -> VideoAsset {
+        let duration = try await avAsset.load(.duration)
+
+        let videoTracks = try await avAsset.loadTracks(withMediaType: .video)
+        var naturalSize: CGSize? = nil
+        var frameRate: Float? = nil
+
+        if let videoTrack = videoTracks.first {
+            naturalSize = try await videoTrack.load(.naturalSize)
+            frameRate = try await videoTrack.load(.nominalFrameRate)
+        }
+
+        let audioTracks = try await avAsset.loadTracks(withMediaType: .audio)
+        let hasAudio = !audioTracks.isEmpty
+
+        return VideoAsset(
+            avAsset: avAsset,
+            url: url,
+            duration: duration,
+            naturalSize: naturalSize,
+            frameRate: frameRate,
+            hasAudio: hasAudio
+        )
+    }
+}
+
+// MARK: - CustomStringConvertible
+extension VideoAsset: CustomStringConvertible {
+    public var description: String {
+        let durationSeconds = CMTimeGetSeconds(duration)
+        let size = naturalSize.map { "\($0.width)x\($0.height)" } ?? "unknown"
+        let fps = frameRate.map { String(format: "%.2f", $0) } ?? "unknown"
+        return """
+        VideoAsset(
+            duration: \(String(format: "%.2f", durationSeconds))s,
+            size: \(size),
+            fps: \(fps),
+            hasAudio: \(hasAudio)
+        )
+        """
+    }
+}

package/ios/TwoStepVideo/Models/VideoEditingError.swift

@@ -0,0 +1,82 @@
+import Foundation
+import AVFoundation
+
+/// Errors that can occur during video editing operations
+public enum VideoEditingError: LocalizedError {
+
+    /// Failed to load asset
+    case assetLoadingFailed(reason: String, underlyingError: Error? = nil)
+
+    /// Invalid time range
+    case invalidTimeRange(reason: String)
+
+    /// No video track found in asset
+    case noVideoTrack
+
+    /// No audio track found in asset
+    case noAudioTrack
+
+    /// Export failed
+    case exportFailed(reason: String, underlyingError: Error? = nil)
+
+    /// Export cancelled
+    case exportCancelled
+
+    /// File already exists at output URL
+    case fileAlreadyExists(url: URL)
+
+    /// Composition creation failed
+    case compositionFailed(reason: String)
+
+    /// Invalid configuration
+    case invalidConfiguration(reason: String)
+
+    /// Unknown error
+    case unknown(underlyingError: Error)
+
+    public var errorDescription: String? {
+        switch self {
+        case .assetLoadingFailed(let reason, let error):
+            var description = "Asset loading failed: \(reason)"
+            if let error = error {
+                description += " - \(error.localizedDescription)"
+            }
+            return description
+
+        case .invalidTimeRange(let reason):
+            return "Invalid time range: \(reason)"
+
+        case .noVideoTrack:
+            return "No video track found in asset"
+
+        case .noAudioTrack:
+            return "No audio track found in asset"
+
+        case .exportFailed(let reason, let error):
+            var description = "Export failed: \(reason)"
+            if let error = error {
+                description += " - \(error.localizedDescription)"
+            }
+            return description
+
+        case .exportCancelled:
+            return "Export was cancelled"
+
+        case .fileAlreadyExists(let url):
+            return "File already exists at: \(url.path)"
+
+        case .compositionFailed(let reason):
+            return "Composition creation failed: \(reason)"
+
+        case .invalidConfiguration(let reason):
+            return "Invalid configuration: \(reason)"
+
+        case .unknown(let error):
+            return "Unknown error: \(error.localizedDescription)"
+        }
+    }
+
+    public var failureReason: String? {
+        return errorDescription
+    }
+}

package/ios/TwoStepVideo/TwoStepVideo.swift

@@ -0,0 +1,30 @@
+import Foundation
+import AVFoundation
+
+/// Main entry point for the TwoStepVideo library
+/// Provides a convenient API for common video editing operations
+public class TwoStepVideo {
+
+    /// Shared singleton instance for convenience
+    public static let shared = TwoStepVideo()
+
+    /// Asset loader instance
+    public let assetLoader: AssetLoader
+
+    /// Video trimmer instance
+    public let videoTrimmer: VideoTrimmer
+
+    /// Video transformer instance for mirroring and speed adjustments
+    public let videoTransformer: VideoTransformer
+
+    /// Video exporter instance
+    public let videoExporter: VideoExporter
+
+    /// Initialize a new instance
+    public init() {
+        self.assetLoader = AssetLoader()
+        self.videoTrimmer = VideoTrimmer()
+        self.videoTransformer = VideoTransformer()
+        self.videoExporter = VideoExporter()
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@movementinfra/expo-twostep-video",
+  "version": "0.1.0",
+  "description": "Minimal video editing for React Native using AVFoundation",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "files": [
+    "build",
+    "ios",
+    "expo-module.config.json",
+    "!ios/Tests",
+    "!ios/.build",
+    "!ios/.swiftpm"
+  ],
+  "scripts": {
+    "build": "expo-module build",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "npm run test:swift",
+    "test:swift": "cd ios && swift test",
+    "test:js": "expo-module test",
+    "prepare": "expo-module prepare",
+    "prepublishOnly": "expo-module prepublishOnly",
+    "expo-module": "expo-module",
+    "open:ios": "xed example/ios"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-module",
+    "video",
+    "video-editing",
+    "trim",
+    "export",
+    "avfoundation",
+    "ios"
+  ],
+  "repository": "https://github.com/rguo123/twostep-video",
+  "bugs": {
+    "url": "https://github.com/rguo123/twostep-video/issues"
+  },
+  "author": "rguo123 <richardg7890@gmail.com> (rguo123)",
+  "license": "MIT",
+  "homepage": "https://github.com/rguo123/twostep-video#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/react": "~19.1.0",
+    "expo-module-scripts": "^5.0.7",
+    "expo": "^54.0.24",
+    "react-native": "0.81.5"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "react": "*",
+    "react-native": "*"
+  }
+}