lottie-ios 4.3.0 → 4.3.2

package/.github/workflows/main.yml

@@ -32,30 +32,17 @@ jobs:
         xcode:
         - '14.2' # Swift 5.7
         - '14.3' # Swift 5.8
+        - '15.0' # Swift 5.9
     steps:
       - uses: actions/checkout@v2
       - uses: ./.github/actions/setup
         with:
           xcode: ${{ matrix.xcode }}
       - name: Build Package
+        # Once there is a production Xcode version with the visionOS SDK,
+        # we will want to use that version without `SKIP_VISION_OS=true`
         run: SKIP_VISION_OS=true bundle exec rake build:package:all
 
-  build-package-macos-13-xcode-15:
-    name: "Build Package"
-    runs-on: macos-13
-    strategy:
-      fail-fast: false
-      matrix:
-        xcode:
-        - '15.0' # Swift 5.9, first version that includes visionOS SDK.
-    steps:
-      - uses: actions/checkout@v2
-      - uses: ./.github/actions/setup
-        with:
-          xcode: ${{ matrix.xcode }}
-      - name: Build Package
-        run: bundle exec rake build:package:all
-
   build-example:
     name: "Build Example App"
     runs-on: macos-13
@@ -65,7 +52,9 @@ jobs:
         with:
           xcode: '15.0' # Swift 5.9
       - name: Build Example
-        run: bundle exec rake build:example:all
+        # Once there is a production Xcode version with the visionOS SDK,
+        # we will want to remove `SKIP_VISION_OS=true`
+        run: SKIP_VISION_OS=true bundle exec rake build:example:all
 
   test-package:
     name: "Test Package"
@@ -115,6 +104,8 @@ jobs:
         with:
           xcode: ${{ matrix.xcode }}
       - name: Build XCFramework
+        # Once there is a production Xcode version with the visionOS SDK, we will 
+        # need to also build an XCFramework using that version but without `SKIP_VISION_OS=true`
         run: SKIP_VISION_OS=true bundle exec rake build:xcframework[Lottie-Xcode-${{ matrix.xcode }}]
       - name: Upload XCFramework
         uses: actions/upload-artifact@v2
@@ -128,32 +119,6 @@ jobs:
           # to an `archives` directory containing our `Lottie.xcframework.zip`.
           path: .build/archives
 
-  build-xcframework-macos-13:
-    name: "Build XCFramework"
-    runs-on: macos-13
-    strategy:
-      matrix:
-        xcode:
-        - '15.0' # Swift 5.9, and the first Xcode version with the visionOS SDK.
-    steps:
-      - uses: actions/checkout@v2
-      - uses: ./.github/actions/setup
-        with:
-          xcode: ${{ matrix.xcode }}
-      - name: Build XCFramework
-        run: bundle exec rake build:xcframework[Lottie-Xcode-${{ matrix.xcode }}]
-      - name: Upload XCFramework
-        uses: actions/upload-artifact@v2
-        with:
-          name: BuildProducts
-          # The xcframework is at the path `.build/archives/Lottie.xcframework.zip`.
-          # GitHub always zips the artifacts before uploading, so if we uploaded the .xframework.zip
-          # directly then it would actually upload a double-zip (a .zip containing our `Lottie.xcframework.zip`).
-          # This is confusing especially since macOS Archive Utility automatially unzips both layers at once.
-          # Instead, we upload the entire archives folder, resulting in an `XCFramework.zip` that unzips
-          # to an `archives` directory containing our `Lottie.xcframework.zip`.
-          path: .build/archives
-
   cocoapod:
     name: "Lint CocoaPods podspec"
     runs-on: macos-13
@@ -171,7 +136,7 @@ jobs:
     strategy:
       matrix:
         xcode:
-        - '15.0' # Swift 5.9, first version with visionOS SDK.
+        - '15.0' # Swift 5.9
     steps:
       - uses: actions/checkout@v2
       - uses: ./.github/actions/setup

package/Lottie.xcodeproj/project.pbxproj

@@ -330,6 +330,7 @@
 		0887347B28F0CCDD00458627 /* LottieAnimationView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0887347428F0CCDD00458627 /* LottieAnimationView.swift */; };
 		0887347C28F0CCDD00458627 /* LottieAnimationView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0887347428F0CCDD00458627 /* LottieAnimationView.swift */; };
 		0887347D28F0CCDD00458627 /* LottieAnimationView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0887347428F0CCDD00458627 /* LottieAnimationView.swift */; };
+		089C50C22ABA0C6D007903D3 /* LoggingTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 089C50C12ABA0C6D007903D3 /* LoggingTests.swift */; };
 		08AB05552A61C20400DE86FD /* ReducedMotionOption.swift in Sources */ = {isa = PBXBuildFile; fileRef = 08AB05542A61C20400DE86FD /* ReducedMotionOption.swift */; };
 		08AB05562A61C20400DE86FD /* ReducedMotionOption.swift in Sources */ = {isa = PBXBuildFile; fileRef = 08AB05542A61C20400DE86FD /* ReducedMotionOption.swift */; };
 		08AB05572A61C20400DE86FD /* ReducedMotionOption.swift in Sources */ = {isa = PBXBuildFile; fileRef = 08AB05542A61C20400DE86FD /* ReducedMotionOption.swift */; };
@@ -1176,6 +1177,7 @@
 		0887347228F0CCDD00458627 /* LottieAnimationHelpers.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = LottieAnimationHelpers.swift; sourceTree = "<group>"; };
 		0887347328F0CCDD00458627 /* LottieAnimationViewInitializers.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = LottieAnimationViewInitializers.swift; sourceTree = "<group>"; };
 		0887347428F0CCDD00458627 /* LottieAnimationView.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = LottieAnimationView.swift; sourceTree = "<group>"; };
+		089C50C12ABA0C6D007903D3 /* LoggingTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LoggingTests.swift; sourceTree = "<group>"; };
 		08AB05542A61C20400DE86FD /* ReducedMotionOption.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReducedMotionOption.swift; sourceTree = "<group>"; };
 		08AB05582A61C5B700DE86FD /* DecodingStrategy.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DecodingStrategy.swift; sourceTree = "<group>"; };
 		08AB055C2A61C5CC00DE86FD /* RenderingEngineOption.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = RenderingEngineOption.swift; sourceTree = "<group>"; };
@@ -1755,6 +1757,7 @@
 				08CB2680291ED2B700B4F071 /* AnimationViewTests.swift */,
 				2E70F79E295BB6D30089A0EF /* CompatibleAnimationViewTests.swift */,
 				080F5FDB2AB1075000ADC32C /* TextProviderTests.swift */,
+				089C50C12ABA0C6D007903D3 /* LoggingTests.swift */,
 			);
 			path = Tests;
 			sourceTree = "<group>";
@@ -3233,6 +3236,7 @@
 				2EAF59A727A076BC00E00531 /* Bundle+Module.swift in Sources */,
 				2E70F79F295BB6D30089A0EF /* CompatibleAnimationViewTests.swift in Sources */,
 				2E8044AE27A07347006E74CB /* Snapshotting+presentationLayer.swift in Sources */,
+				089C50C22ABA0C6D007903D3 /* LoggingTests.swift in Sources */,
 				36E57EAC28AF7ADF00B7EFDA /* HardcodedTextProvider.swift in Sources */,
 				2E72128527BB32DB0027BC56 /* PerformanceTests.swift in Sources */,
 				6DB3BDC328245AA2002A276D /* ParsingTests.swift in Sources */,

package/Lottie.xcworkspace/xcuserdata/calstephens.xcuserdatad/xcdebugger/Breakpoints_v2.xcbkptlist

@@ -52,22 +52,6 @@
             </Locations>
          </BreakpointContent>
       </BreakpointProxy>
-      <BreakpointProxy
-         BreakpointExtensionID = "Xcode.Breakpoint.FileBreakpoint">
-         <BreakpointContent
-            uuid = "7317D33F-83F7-487F-92D8-361AFDC3108F"
-            shouldBeEnabled = "No"
-            ignoreCount = "0"
-            continueAfterRunningActions = "No"
-            filePath = "Sources/Private/CoreAnimation/Layers/AnimationLayer.swift"
-            startingColumnNumber = "9223372036854775807"
-            endingColumnNumber = "9223372036854775807"
-            startingLineNumber = "59"
-            endingLineNumber = "59"
-            landmarkName = "addingKeypathComponent(_:)"
-            landmarkType = "7">
-         </BreakpointContent>
-      </BreakpointProxy>
       <BreakpointProxy
          BreakpointExtensionID = "Xcode.Breakpoint.FileBreakpoint">
          <BreakpointContent
@@ -79,8 +63,8 @@
             filePath = "Sources/Private/CoreAnimation/Animations/CALayer+addAnimation.swift"
             startingColumnNumber = "9223372036854775807"
             endingColumnNumber = "9223372036854775807"
-            startingLineNumber = "105"
-            endingLineNumber = "105"
+            startingLineNumber = "104"
+            endingLineNumber = "104"
             landmarkName = "CALayer"
             landmarkType = "21">
             <Locations>
@@ -303,6 +287,21 @@
                   endingLineNumber = "412"
                   offsetFromSymbolStart = "127">
                </Location>
+               <Location
+                  uuid = "E5D4F221-8220-42A8-BB35-32D5BEE1328B - 12a91848e5910a61"
+                  shouldBeEnabled = "Yes"
+                  ignoreCount = "0"
+                  continueAfterRunningActions = "No"
+                  symbolName = "__C.UIView.systemLayoutFittingIntrinsicWidthFixedHeight(_: CoreGraphics.CGFloat, priority: __C.UILayoutPriority) -&gt; __C.CGSize"
+                  moduleName = "Lottie"
+                  usesParentBreakpointCondition = "Yes"
+                  urlString = "file:///Users/calstephens/Documents/lottie/Sources/Private/EmbeddedLibraries/EpoxyCore/SwiftUI/LayoutUtilities/SwiftUIMeasurementContainer.swift"
+                  startingColumnNumber = "9223372036854775807"
+                  endingColumnNumber = "9223372036854775807"
+                  startingLineNumber = "412"
+                  endingLineNumber = "412"
+                  offsetFromSymbolStart = "99">
+               </Location>
             </Locations>
          </BreakpointContent>
       </BreakpointProxy>
@@ -412,6 +411,21 @@
                   endingLineNumber = "393"
                   offsetFromSymbolStart = "128">
                </Location>
+               <Location
+                  uuid = "7043C7FC-0028-426B-91A7-E05945E62122 - 94200cadb594d8f7"
+                  shouldBeEnabled = "Yes"
+                  ignoreCount = "0"
+                  continueAfterRunningActions = "No"
+                  symbolName = "__C.UIView.systemLayoutFittingIntrinsicHeightFixedWidth(_: CoreGraphics.CGFloat, priority: __C.UILayoutPriority) -&gt; __C.CGSize"
+                  moduleName = "Lottie"
+                  usesParentBreakpointCondition = "Yes"
+                  urlString = "file:///Users/calstephens/Documents/lottie/Sources/Private/EmbeddedLibraries/EpoxyCore/SwiftUI/LayoutUtilities/SwiftUIMeasurementContainer.swift"
+                  startingColumnNumber = "9223372036854775807"
+                  endingColumnNumber = "9223372036854775807"
+                  startingLineNumber = "393"
+                  endingLineNumber = "393"
+                  offsetFromSymbolStart = "97">
+               </Location>
             </Locations>
          </BreakpointContent>
       </BreakpointProxy>
@@ -525,49 +539,49 @@
       <BreakpointProxy
          BreakpointExtensionID = "Xcode.Breakpoint.FileBreakpoint">
          <BreakpointContent
-            uuid = "75697A31-C456-456F-815B-95974E3598BE"
+            uuid = "93EDC5AB-8948-4148-83CC-FDDCB8BE5AFE"
             shouldBeEnabled = "No"
             ignoreCount = "0"
             continueAfterRunningActions = "No"
             filePath = "Example/Example/AnimationPreviewView.swift"
             startingColumnNumber = "9223372036854775807"
             endingColumnNumber = "9223372036854775807"
-            startingLineNumber = "60"
-            endingLineNumber = "60"
-            landmarkName = "body"
-            landmarkType = "24">
+            startingLineNumber = "119"
+            endingLineNumber = "119"
+            landmarkName = "AnimationPreviewView"
+            landmarkType = "14">
          </BreakpointContent>
       </BreakpointProxy>
       <BreakpointProxy
          BreakpointExtensionID = "Xcode.Breakpoint.FileBreakpoint">
          <BreakpointContent
-            uuid = "EAF29C5C-15A1-4F9D-AB63-8130DBD6049A"
+            uuid = "6054DF71-1266-422E-9C2F-56F48E5C9F70"
             shouldBeEnabled = "Yes"
             ignoreCount = "0"
             continueAfterRunningActions = "No"
-            filePath = "Example/Example/AnimationPreviewView.swift"
+            filePath = "Sources/Public/iOS/FilepathImageProvider.swift"
             startingColumnNumber = "9223372036854775807"
             endingColumnNumber = "9223372036854775807"
-            startingLineNumber = "59"
-            endingLineNumber = "59"
-            landmarkName = "body"
-            landmarkType = "24">
+            startingLineNumber = "40"
+            endingLineNumber = "40"
+            landmarkName = "imageForAsset(asset:)"
+            landmarkType = "7">
          </BreakpointContent>
       </BreakpointProxy>
       <BreakpointProxy
          BreakpointExtensionID = "Xcode.Breakpoint.FileBreakpoint">
          <BreakpointContent
-            uuid = "93EDC5AB-8948-4148-83CC-FDDCB8BE5AFE"
-            shouldBeEnabled = "No"
+            uuid = "8628051F-F131-475B-8FBA-5C9F7B7F9CF8"
+            shouldBeEnabled = "Yes"
             ignoreCount = "0"
             continueAfterRunningActions = "No"
-            filePath = "Example/Example/AnimationPreviewView.swift"
+            filePath = "Sources/Private/MainThread/LayerContainers/Utility/LayerImageProvider.swift"
             startingColumnNumber = "9223372036854775807"
             endingColumnNumber = "9223372036854775807"
-            startingLineNumber = "119"
-            endingLineNumber = "119"
-            landmarkName = "AnimationPreviewView"
-            landmarkType = "14">
+            startingLineNumber = "49"
+            endingLineNumber = "49"
+            landmarkName = "reloadImages()"
+            landmarkType = "7">
          </BreakpointContent>
       </BreakpointProxy>
    </Breakpoints>

package/README.md

@@ -41,7 +41,7 @@ To install Lottie using [Swift Package Manager](https://github.com/apple/swift-p
 or you can add the following dependency to your `Package.swift`:
 
 ```swift
-.package(url: "https://github.com/airbnb/lottie-spm.git", from: "4.3.0")
+.package(url: "https://github.com/airbnb/lottie-spm.git", from: "4.3.2")
 ```
 
 When using Swift Package Manager we recommend using the [lottie-spm](https://github.com/airbnb/lottie-spm) repo instead of the main lottie-ios repo.  The main git repository for [lottie-ios](https://github.com/airbnb/lottie-ios) is somewhat large (300+ MB), and Swift Package Manager always downloads the full repository with all git history. The [lottie-spm](https://github.com/airbnb/lottie-spm) repo is much smaller (less than 500kb), so can be downloaded much more quickly. 

package/Sources/Private/CoreAnimation/Animations/CALayer+addAnimation.swift

@@ -50,15 +50,14 @@ extension CALayer {
     guard !keyframes.isEmpty else { return nil }
 
     // Check if this set of keyframes uses After Effects expressions, which aren't supported.
-    if let unsupportedAfterEffectsExpression = keyframeGroup.unsupportedAfterEffectsExpression {
+    //  - We only log this once per `CoreAnimationLayer` instance.
+    if keyframeGroup.unsupportedAfterEffectsExpression != nil, !context.loggingState.hasLoggedAfterEffectsExpressionsWarning {
+      context.loggingState.hasLoggedAfterEffectsExpressionsWarning = true
       context.logger.info("""
         `\(property.caLayerKeypath)` animation for "\(context.currentKeypath.fullPath)" \
         includes an After Effects expression (https://helpx.adobe.com/after-effects/using/expression-language.html), \
         which is not supported by lottie-ios (expressions are only supported by lottie-web). \
         This animation may not play correctly.
-
-          \(unsupportedAfterEffectsExpression.replacingOccurrences(of: "\n", with: "\n  "))
-
         """)
     }
 

package/Sources/Private/CoreAnimation/CoreAnimationLayer.swift

@@ -209,6 +209,7 @@ final class CoreAnimationLayer: BaseAnimationLayer {
   private let valueProviderStore: ValueProviderStore
   private let compatibilityTracker: CompatibilityTracker
   private let logger: LottieLogger
+  private let loggingState = LoggingState()
 
   /// The current playback state of the animation that is displayed in this layer
   private var currentPlaybackState: PlaybackState? {
@@ -265,6 +266,7 @@ final class CoreAnimationLayer: BaseAnimationLayer {
       valueProviderStore: valueProviderStore,
       compatibilityTracker: compatibilityTracker,
       logger: logger,
+      loggingState: loggingState,
       currentKeypath: AnimationKeypath(keys: []),
       textProvider: textProvider,
       recordHierarchyKeypath: configuration.recordHierarchyKeypath)
@@ -449,7 +451,9 @@ extension CoreAnimationLayer: RootAnimationLayer {
   }
 
   func forceDisplayUpdate() {
-    display()
+    // Unimplemented
+    //  - We can't call `display()` here, because it would cause unexpected frame animations:
+    //    https://github.com/airbnb/lottie-ios/issues/2193
   }
 
   func logHierarchyKeypaths() {

package/Sources/Private/CoreAnimation/Layers/AnimationLayer.swift

@@ -38,6 +38,9 @@ struct LayerAnimationContext {
   /// The logger that should be used for assertions and warnings
   let logger: LottieLogger
 
+  /// Mutable state related to log events, stored on the `CoreAnimationLayer`.
+  let loggingState: LoggingState
+
   /// The AnimationKeypath represented by the current layer
   var currentKeypath: AnimationKeypath
 
@@ -84,3 +87,19 @@ struct LayerAnimationContext {
     return copy
   }
 }
+
+// MARK: - LoggingState
+
+/// Mutable state related to log events, stored on the `CoreAnimationLayer`.
+final class LoggingState {
+
+  // MARK: Lifecycle
+
+  init() { }
+
+  // MARK: Internal
+
+  /// Whether or not the warning about unsupported After Effects expressions
+  /// has been logged yet for this layer.
+  var hasLoggedAfterEffectsExpressionsWarning = false
+}

package/Sources/Public/Animation/LottieAnimationLayer.swift

@@ -107,7 +107,7 @@ public class LottieAnimationLayer: CALayer {
     guard let animation = animation else { return }
 
     defer {
-      currentPlaybackMode = .toProgress(1, loopMode: loopMode)
+      currentPlaybackMode = .playing(.fromProgress(nil, toProgress: 1, loopMode: loopMode))
     }
 
     if shouldOverrideWithReducedMotionAnimation {
@@ -139,7 +139,7 @@ public class LottieAnimationLayer: CALayer {
     guard let animation = animation else { return }
 
     defer {
-      currentPlaybackMode = .fromProgress(fromProgress, toProgress: toProgress, loopMode: loopMode ?? self.loopMode)
+      currentPlaybackMode = .playing(.fromProgress(fromProgress, toProgress: toProgress, loopMode: loopMode ?? self.loopMode))
     }
 
     if shouldOverrideWithReducedMotionAnimation {
@@ -172,7 +172,7 @@ public class LottieAnimationLayer: CALayer {
     completion: LottieCompletionBlock? = nil)
   {
     defer {
-      currentPlaybackMode = .fromFrame(fromFrame, toFrame: toFrame, loopMode: loopMode ?? self.loopMode)
+      currentPlaybackMode = .playing(.fromFrame(fromFrame, toFrame: toFrame, loopMode: loopMode ?? self.loopMode))
     }
 
     if shouldOverrideWithReducedMotionAnimation {
@@ -216,11 +216,11 @@ public class LottieAnimationLayer: CALayer {
     completion: LottieCompletionBlock? = nil)
   {
     defer {
-      currentPlaybackMode = .fromMarker(
+      currentPlaybackMode = .playing(.fromMarker(
         fromMarker,
         toMarker: toMarker,
         playEndMarkerFrame: playEndMarkerFrame,
-        loopMode: loopMode ?? self.loopMode)
+        loopMode: loopMode ?? self.loopMode))
     }
 
     if shouldOverrideWithReducedMotionAnimation {
@@ -273,7 +273,7 @@ public class LottieAnimationLayer: CALayer {
     }
 
     defer {
-      currentPlaybackMode = .marker(marker, loopMode: loopMode ?? self.loopMode)
+      currentPlaybackMode = .playing(.marker(marker, loopMode: loopMode ?? self.loopMode))
     }
 
     if shouldOverrideWithReducedMotionAnimation {
@@ -311,7 +311,7 @@ public class LottieAnimationLayer: CALayer {
     guard !markers.isEmpty else { return }
 
     defer {
-      currentPlaybackMode = .markers(markers)
+      currentPlaybackMode = .playing(.markers(markers))
     }
 
     if shouldOverrideWithReducedMotionAnimation {
@@ -357,62 +357,124 @@ public class LottieAnimationLayer: CALayer {
   ///
   /// The completion closure will be called with `false`
   open func pause() {
-    removeCurrentAnimation()
-    currentPlaybackMode = .pause
+    pause(at: .currentFrame)
   }
 
-  /// Applies the given `LottiePlaybackMode` to this layer.
-  /// - Parameter animationCompletionHandler: A closure that is called after
-  ///   an animation triggered by this method completes. This completion
-  ///   handler is **not called** after setting the playback mode to a
-  ///   mode that doesn't animate (e.g. `progress`, `frame`, `time`, or `pause`).
+  /// Pauses the animation at a given state.
+  open func pause(at state: LottiePlaybackMode.PausedState) {
+    switch state {
+    case .currentFrame:
+      removeCurrentAnimation()
+
+    case .progress(let animationProgressTime):
+      currentProgress = animationProgressTime
+
+    case .frame(let animationFrameTime):
+      currentFrame = animationFrameTime
+    case .time(let timeInterval):
+      currentTime = timeInterval
+
+    case .marker(let name, let position):
+      guard let from = animation?.markerMap?[name] else {
+        return
+      }
+
+      switch position {
+      case .start:
+        currentTime = from.frameTime
+      case .end:
+        currentTime = from.frameTime + from.durationFrameTime
+      }
+    }
+
+    currentPlaybackMode = .paused(at: state)
+  }
+
+  @available(*, deprecated, renamed: "setPlaybackMode(_:completion:)", message: "Will be removed in a future major release.")
   open func play(
     _ playbackMode: LottiePlaybackMode,
     animationCompletionHandler: LottieCompletionBlock? = nil)
+  {
+    setPlaybackMode(playbackMode, completion: animationCompletionHandler)
+  }
+
+  /// Applies the given `LottiePlaybackMode` to this layer.
+  /// - Parameter playbackMode: The playback mode to apply
+  /// - Parameter completion: A closure that is called after
+  ///   an animation triggered by this method completes.
+  open func setPlaybackMode(
+    _ playbackMode: LottiePlaybackMode,
+    completion: LottieCompletionBlock? = nil)
   {
     switch playbackMode {
+    case .paused(at: let state):
+      pause(at: state)
+
+    case .playing(let mode):
+      play(mode, completion: completion)
+
     case .progress(let progress):
-      currentProgress = progress
+      pause(at: .progress(progress))
 
     case .frame(let frame):
-      currentFrame = frame
+      pause(at: .frame(frame))
 
     case .time(let time):
-      currentTime = time
+      pause(at: .time(time))
 
     case .pause:
-      pause()
+      pause(at: .currentFrame)
+
+    case .fromProgress(let from, let to, let loopMode):
+      play(.fromProgress(from, toProgress: to, loopMode: loopMode), completion: completion)
+
+    case .fromFrame(let from, let to, let loopMode):
+      play(.fromFrame(from, toFrame: to, loopMode: loopMode), completion: completion)
+
+    case .fromMarker(let from, let to, let playEndMarkerFrame, let loopMode):
+      play(.fromMarker(from, toMarker: to, playEndMarkerFrame: playEndMarkerFrame, loopMode: loopMode), completion: completion)
+
+    case .marker(let name, let loopMode):
+      play(.marker(name, loopMode: loopMode), completion: completion)
 
-    case .fromProgress(let fromProgress, let toProgress, let loopMode):
+    case .markers(let names):
+      play(.markers(names), completion: completion)
+    }
+  }
+
+  /// Applies the given `LottiePlaybackMode` to this layer.
+  /// - Parameter playbackMode: The playback mode to apply
+  /// - Parameter completion: A closure that is called after
+  ///   an animation triggered by this method completes.
+  open func play(_ playbackMode: LottiePlaybackMode.PlaybackMode, completion: LottieCompletionBlock? = nil) {
+    switch playbackMode {
+    case .fromProgress(let from, let to, let loopMode):
       play(
-        fromProgress: fromProgress,
-        toProgress: toProgress,
+        fromProgress: from,
+        toProgress: to,
         loopMode: loopMode,
-        completion: animationCompletionHandler)
+        completion: completion)
 
-    case .fromFrame(let fromFrame, let toFrame, let loopMode):
+    case .fromFrame(let from, let to, let loopMode):
       play(
-        fromFrame: fromFrame,
-        toFrame: toFrame,
+        fromFrame: from,
+        toFrame: to,
         loopMode: loopMode,
-        completion: animationCompletionHandler)
+        completion: completion)
 
-    case .fromMarker(let fromMarker, let toMarker, let playEndMarkerFrame, let loopMode):
+    case .fromMarker(let from, let to, let playEndMarkerFrame, let loopMode):
       play(
-        fromMarker: fromMarker,
-        toMarker: toMarker,
+        fromMarker: from,
+        toMarker: to,
         playEndMarkerFrame: playEndMarkerFrame,
         loopMode: loopMode,
-        completion: animationCompletionHandler)
+        completion: completion)
 
-    case .marker(let marker, let loopMode):
-      play(
-        marker: marker,
-        loopMode: loopMode,
-        completion: animationCompletionHandler)
+    case .marker(let name, loopMode: let loopMode):
+      play(marker: name, loopMode: loopMode, completion: completion)
 
-    case .markers(let markers):
-      play(markers: markers, completion: animationCompletionHandler)
+    case .markers(let names):
+      play(markers: names, completion: completion)
     }
   }
 
@@ -602,7 +664,7 @@ public class LottieAnimationLayer: CALayer {
     set {
       if let animation = animation {
         currentFrame = animation.frameTime(forProgress: newValue)
-        currentPlaybackMode = .progress(newValue)
+        currentPlaybackMode = .paused(at: .progress(newValue))
       } else {
         currentFrame = 0
       }
@@ -624,7 +686,7 @@ public class LottieAnimationLayer: CALayer {
     set {
       if let animation = animation {
         currentFrame = animation.frameTime(forTime: newValue)
-        currentPlaybackMode = .time(newValue)
+        currentPlaybackMode = .paused(at: .time(newValue))
       } else {
         currentFrame = 0
       }
@@ -645,7 +707,7 @@ public class LottieAnimationLayer: CALayer {
     set {
       removeCurrentAnimationIfNecessary()
       updateAnimationFrame(newValue)
-      currentPlaybackMode = .frame(currentFrame)
+      currentPlaybackMode = .paused(at: .frame(currentFrame))
     }
     get {
       rootAnimationLayer?.currentFrame ?? 0

package/Sources/Public/Animation/LottieAnimationView.swift

@@ -219,6 +219,13 @@ open class LottieAnimationView: LottieAnimationViewBase {
 
   // MARK: Open
 
+  /// Applies the given `LottiePlaybackMode` to this layer.
+  /// - Parameter completion: A closure that is called after
+  ///   an animation triggered by this method completes.
+  open func play(_ mode: LottiePlaybackMode.PlaybackMode, completion: LottieCompletionBlock? = nil) {
+    lottieAnimationLayer.play(mode, completion: completion)
+  }
+
   /// Plays the animation from its current state to the end.
   ///
   /// - Parameter completion: An optional completion closure to be called when the animation completes playing.
@@ -341,16 +348,22 @@ open class LottieAnimationView: LottieAnimationViewBase {
     lottieAnimationLayer.pause()
   }
 
-  /// Applies the given `LottiePlaybackMode` to this layer.
-  /// - Parameter animationCompletionHandler: A closure that is called after
-  ///   an animation triggered by this method completes. This completion
-  ///   handler is **not called** after setting the playback mode to a
-  ///   mode that doesn't animate (e.g. `progress`, `frame`, `time`, or `pause`).
+  @available(*, deprecated, renamed: "setPlaybackMode(_:completion:)", message: "Will be removed in a future major release.")
   open func play(
     _ playbackMode: LottiePlaybackMode,
     animationCompletionHandler: LottieCompletionBlock? = nil)
   {
-    lottieAnimationLayer.play(playbackMode, animationCompletionHandler: animationCompletionHandler)
+    lottieAnimationLayer.setPlaybackMode(playbackMode, completion: animationCompletionHandler)
+  }
+
+  /// Applies the given `LottiePlaybackMode` to this layer.
+  /// - Parameter completion: A closure that is called after
+  ///   an animation triggered by this method completes.
+  open func setPlaybackMode(
+    _ playbackMode: LottiePlaybackMode,
+    completion: LottieCompletionBlock? = nil)
+  {
+    lottieAnimationLayer.setPlaybackMode(playbackMode, completion: completion)
   }
 
   // MARK: Public
@@ -794,6 +807,9 @@ open class LottieAnimationView: LottieAnimationViewBase {
 
   // MARK: Internal
 
+  // The backing CALayer for this animation view.
+  let lottieAnimationLayer: LottieAnimationLayer
+
   var animationLayer: RootAnimationLayer? {
     lottieAnimationLayer.rootAnimationLayer
   }
@@ -1029,8 +1045,5 @@ open class LottieAnimationView: LottieAnimationViewBase {
 
   // MARK: Private
 
-  // The backing CALayer for this animation view.
-  private let lottieAnimationLayer: LottieAnimationLayer
-
   private let logger: LottieLogger
 }

package/Sources/Public/Animation/LottiePlaybackMode.swift

@@ -7,91 +7,173 @@ import Foundation
 
 /// Configuration for how a Lottie animation should be played
 public enum LottiePlaybackMode: Hashable {
-  /// The animation is paused at the given progress value,
-  /// a value between 0.0 (0% progress) and 1.0 (100% progress).
+
+  /// The animation is paused at the given state (e.g. paused at a specific frame)
+  case paused(at: PausedState)
+
+  /// The animation is playing using the given playback mode (e.g. looping from the start to the end)
+  case playing(_ mode: PlaybackMode)
+
+  @available(*, deprecated, renamed: "LottiePlaybackMode.paused(at:)", message: "Will be removed in a future major release.")
   case progress(_ progress: AnimationProgressTime)
 
-  /// The animation is paused at the given frame of the animation.
+  @available(*, deprecated, renamed: "LottiePlaybackMode.paused(at:)", message: "Will be removed in a future major release.")
   case frame(_ frame: AnimationFrameTime)
 
-  /// The animation is paused at the given time value from the start of the animation.
+  @available(*, deprecated, renamed: "LottiePlaybackMode.paused(at:)", message: "Will be removed in a future major release.")
   case time(_ time: TimeInterval)
 
-  /// Any existing animation will be paused at the current frame.
+  @available(*, deprecated, renamed: "LottiePlaybackMode.paused(at:)", message: "Will be removed in a future major release.")
   case pause
 
-  /// Plays the animation from a progress (0-1) to a progress (0-1).
-  /// - Parameter fromProgress: The start progress of the animation. If `nil` the animation will start at the current progress.
-  /// - Parameter toProgress: The end progress of the animation.
-  /// - Parameter loopMode: The loop behavior of the animation.
+  @available(*, deprecated, renamed: "LottiePlaybackMode.playing(_:)", message: "Will be removed in a future major release.")
   case fromProgress(_ fromProgress: AnimationProgressTime?, toProgress: AnimationProgressTime, loopMode: LottieLoopMode)
 
-  /// The animation plays from the given `fromFrame` to the given `toFrame`.
-  /// - Parameter fromFrame: The start frame of the animation. If `nil` the animation will start at the current frame.
-  /// - Parameter toFrame: The end frame of the animation.
-  /// - Parameter loopMode: The loop behavior of the animation.
+  @available(*, deprecated, renamed: "LottiePlaybackMode.playing(_:)", message: "Will be removed in a future major release.")
   case fromFrame(_ fromFrame: AnimationFrameTime?, toFrame: AnimationFrameTime, loopMode: LottieLoopMode)
 
-  /// Plays the animation from a named marker to another marker.
-  ///
-  /// Markers are point in time that are encoded into the Animation data and assigned a name.
-  ///
-  /// NOTE: If markers are not found the play command will exit.
-  ///
-  /// - Parameter fromMarker: The start marker for the animation playback. If `nil` the
-  /// animation will start at the current progress.
-  /// - Parameter toMarker: The end marker for the animation playback.
-  /// - Parameter playEndMarkerFrame: A flag to determine whether or not to play the frame of the end marker. If the
-  /// end marker represents the end of the section to play, it should be to true. If the provided end marker
-  /// represents the beginning of the next section, it should be false.
-  /// - Parameter loopMode: The loop behavior of the animation.
+  @available(*, deprecated, renamed: "LottiePlaybackMode.playing(_:)", message: "Will be removed in a future major release.")
   case fromMarker(
     _ fromMarker: String?,
     toMarker: String,
     playEndMarkerFrame: Bool = true,
     loopMode: LottieLoopMode)
 
-  /// Plays the animation from a named marker to the end of the marker's duration.
-  ///
-  /// A marker is a point in time with an associated duration that is encoded into the
-  /// animation data and assigned a name.
-  ///
-  /// NOTE: If marker is not found the play command will exit.
-  ///
-  /// - Parameter marker: The start marker for the animation playback.
-  /// - Parameter loopMode: The loop behavior of the animation.
+  @available(*, deprecated, renamed: "LottiePlaybackMode.playing(_:)", message: "Will be removed in a future major release.")
   case marker(_ marker: String, loopMode: LottieLoopMode)
 
-  /// Plays the given markers sequentially in order.
-  ///
-  /// A marker is a point in time with an associated duration that is encoded into the
-  /// animation data and assigned a name. Multiple markers can be played sequentially
-  /// to create programmable animations.
-  ///
-  /// If a marker is not found, it will be skipped.
-  ///
-  /// If a marker doesn't have a duration value, it will play with a duration of 0
-  /// (effectively being skipped).
-  ///
-  /// If another animation is played (by calling any `play` method) while this
-  /// marker sequence is playing, the marker sequence will be cancelled.
-  ///
-  /// - Parameter markers: The list of markers to play sequentially.
+  @available(*, deprecated, renamed: "LottiePlaybackMode.playing(_:)", message: "Will be removed in a future major release.")
   case markers(_ markers: [String])
+
+  // MARK: Public
+
+  public enum PausedState: Hashable {
+    /// Any existing animation will be paused at the current frame.
+    case currentFrame
+
+    /// The animation is paused at the given progress value,
+    /// a value between 0.0 (0% progress) and 1.0 (100% progress).
+    case progress(_ progress: AnimationProgressTime)
+
+    /// The animation is paused at the given frame of the animation.
+    case frame(_ frame: AnimationFrameTime)
+
+    /// The animation is paused at the given time value from the start of the animation.
+    case time(_ time: TimeInterval)
+
+    /// Pauses the animation at a given marker and position
+    case marker(_ name: String, position: LottieMarkerPosition = .start)
+  }
+
+  public enum PlaybackMode: Hashable {
+    /// Plays the animation from a progress (0-1) to a progress (0-1).
+    /// - Parameter fromProgress: The start progress of the animation. If `nil` the animation will start at the current progress.
+    /// - Parameter toProgress: The end progress of the animation.
+    /// - Parameter loopMode: The loop behavior of the animation.
+    case fromProgress(
+      _ fromProgress: AnimationProgressTime?,
+      toProgress: AnimationProgressTime,
+      loopMode: LottieLoopMode)
+
+    /// The animation plays from the given `fromFrame` to the given `toFrame`.
+    /// - Parameter fromFrame: The start frame of the animation. If `nil` the animation will start at the current frame.
+    /// - Parameter toFrame: The end frame of the animation.
+    /// - Parameter loopMode: The loop behavior of the animation.
+    case fromFrame(
+      _ fromFrame: AnimationFrameTime?,
+      toFrame: AnimationFrameTime,
+      loopMode: LottieLoopMode)
+
+    /// Plays the animation from a named marker to another marker.
+    ///
+    /// Markers are point in time that are encoded into the Animation data and assigned a name.
+    ///
+    /// NOTE: If markers are not found the play command will exit.
+    ///
+    /// - Parameter fromMarker: The start marker for the animation playback. If `nil` the
+    /// animation will start at the current progress.
+    /// - Parameter toMarker: The end marker for the animation playback.
+    /// - Parameter playEndMarkerFrame: A flag to determine whether or not to play the frame of the end marker. If the
+    /// end marker represents the end of the section to play, it should be to true. If the provided end marker
+    /// represents the beginning of the next section, it should be false.
+    /// - Parameter loopMode: The loop behavior of the animation.
+    case fromMarker(
+      _ fromMarker: String?,
+      toMarker: String,
+      playEndMarkerFrame: Bool = true,
+      loopMode: LottieLoopMode)
+
+    /// Plays the animation from a named marker to the end of the marker's duration.
+    ///
+    /// A marker is a point in time with an associated duration that is encoded into the
+    /// animation data and assigned a name.
+    ///
+    /// NOTE: If marker is not found the play command will exit.
+    ///
+    /// - Parameter marker: The start marker for the animation playback.
+    /// - Parameter loopMode: The loop behavior of the animation.
+    case marker(
+      _ marker: String,
+      loopMode: LottieLoopMode)
+
+    /// Plays the given markers sequentially in order.
+    ///
+    /// A marker is a point in time with an associated duration that is encoded into the
+    /// animation data and assigned a name. Multiple markers can be played sequentially
+    /// to create programmable animations.
+    ///
+    /// If a marker is not found, it will be skipped.
+    ///
+    /// If a marker doesn't have a duration value, it will play with a duration of 0
+    /// (effectively being skipped).
+    ///
+    /// If another animation is played (by calling any `play` method) while this
+    /// marker sequence is playing, the marker sequence will be cancelled.
+    ///
+    /// - Parameter markers: The list of markers to play sequentially.
+    case markers(_ markers: [String])
+  }
+
 }
 
 extension LottiePlaybackMode {
+  public static var paused: Self {
+    .paused(at: .currentFrame)
+  }
+
+  @available(*, deprecated, renamed: "LottiePlaybackMode.playing(_:)", message: "Will be removed in a future major release.")
+  public static func toProgress(_ toProgress: AnimationProgressTime, loopMode: LottieLoopMode) -> LottiePlaybackMode {
+    .playing(.fromProgress(nil, toProgress: toProgress, loopMode: loopMode))
+  }
+
+  @available(*, deprecated, renamed: "LottiePlaybackMode.playing(_:)", message: "Will be removed in a future major release.")
+  public static func toFrame(_ toFrame: AnimationFrameTime, loopMode: LottieLoopMode) -> LottiePlaybackMode {
+    .playing(.fromFrame(nil, toFrame: toFrame, loopMode: loopMode))
+  }
+
+  @available(*, deprecated, renamed: "LottiePlaybackMode.playing(_:)", message: "Will be removed in a future major release.")
+  public static func toMarker(
+    _ toMarker: String,
+    playEndMarkerFrame: Bool = true,
+    loopMode: LottieLoopMode)
+    -> LottiePlaybackMode
+  {
+    .playing(.fromMarker(nil, toMarker: toMarker, playEndMarkerFrame: playEndMarkerFrame, loopMode: loopMode))
+  }
+}
+
+extension LottiePlaybackMode.PlaybackMode {
   /// Plays the animation from the current progress to a progress value (0-1).
   /// - Parameter toProgress: The end progress of the animation.
   /// - Parameter loopMode: The loop behavior of the animation.
-  public static func toProgress(_ toProgress: AnimationProgressTime, loopMode: LottieLoopMode) -> LottiePlaybackMode {
+  public static func toProgress(_ toProgress: AnimationProgressTime, loopMode: LottieLoopMode) -> Self {
     .fromProgress(nil, toProgress: toProgress, loopMode: loopMode)
   }
 
   // Plays the animation from the current frame to the given frame.
   /// - Parameter toFrame: The end frame of the animation.
   /// - Parameter loopMode: The loop behavior of the animation.
-  public static func toFrame(_ toFrame: AnimationFrameTime, loopMode: LottieLoopMode) -> LottiePlaybackMode {
+  public static func toFrame(_ toFrame: AnimationFrameTime, loopMode: LottieLoopMode) -> Self {
     .fromFrame(nil, toFrame: toFrame, loopMode: loopMode)
   }
 
@@ -110,8 +192,16 @@ extension LottiePlaybackMode {
     _ toMarker: String,
     playEndMarkerFrame: Bool = true,
     loopMode: LottieLoopMode)
-    -> LottiePlaybackMode
+    -> Self
   {
     .fromMarker(nil, toMarker: toMarker, playEndMarkerFrame: playEndMarkerFrame, loopMode: loopMode)
   }
 }
+
+// MARK: - LottieMarkerPosition
+
+/// The position within a marker.
+public enum LottieMarkerPosition: Hashable {
+  case start
+  case end
+}

package/Sources/Public/Animation/LottieView.swift

@@ -140,7 +140,7 @@ public struct LottieView<Placeholder: View>: UIViewConfiguringSwiftUIView {
             let playbackMode = playbackMode,
             playbackMode != context.view.currentPlaybackMode
           {
-            context.view.play(playbackMode, animationCompletionHandler: animationCompletionHandler)
+            context.view.setPlaybackMode(playbackMode, completion: animationCompletionHandler)
           }
         }
         .configurations(configurations)
@@ -175,27 +175,47 @@ public struct LottieView<Placeholder: View>: UIViewConfiguringSwiftUIView {
     return copy
   }
 
-  // Returns a copy of this view playing once from the current frame to the end frame
+  @available(*, deprecated, renamed: "playing()", message: "Will be removed in a future major release.")
   public func play() -> Self {
-    play(loopMode: .playOnce)
+    playbackMode(.playing(.fromProgress(nil, toProgress: 1, loopMode: .playOnce)))
   }
 
   /// Returns a copy of this view that loops its animation from the start to end whenever visible
   public func looping() -> Self {
-    play(.fromProgress(0, toProgress: 1, loopMode: .loop))
+    playbackMode(.playing(.fromProgress(0, toProgress: 1, loopMode: .loop)))
   }
 
-  /// Returns a copy of this view playing from the current frame to the end frame,
-  /// with the given `LottiePlaybackMode`.
+  @available(*, deprecated, renamed: "playing(_:)", message: "Will be removed in a future major release.")
   public func play(loopMode: LottieLoopMode = .playOnce) -> Self {
-    play(.toProgress(1, loopMode: loopMode))
+    playbackMode(.playing(.fromProgress(nil, toProgress: 1, loopMode: loopMode)))
   }
 
-  /// Returns a copy of this view playing with the given `LottiePlaybackMode`
+  @available(*, deprecated, renamed: "playbackMode(_:)", message: "Will be removed in a future major release.")
   public func play(_ playbackMode: LottiePlaybackMode) -> Self {
     self.playbackMode(playbackMode)
   }
 
+  /// Returns a copy of this view playing with the given playback mode
+  public func playing(_ mode: LottiePlaybackMode.PlaybackMode) -> Self {
+    playbackMode(.playing(mode))
+  }
+
+  /// Returns a copy of this view playing from the current frame to the end frame,
+  /// with the given `LottiePlaybackMode`.
+  public func playing(loopMode: LottieLoopMode) -> Self {
+    playbackMode(.playing(.fromProgress(nil, toProgress: 1, loopMode: loopMode)))
+  }
+
+  // Returns a copy of this view playing once from the current frame to the end frame
+  public func playing() -> Self {
+    playbackMode(.playing(.fromProgress(nil, toProgress: 1, loopMode: .playOnce)))
+  }
+
+  /// Returns a copy of this view paused with the given state
+  public func paused(at state: LottiePlaybackMode.PausedState = .currentFrame) -> Self {
+    playbackMode(.paused(at: state))
+  }
+
   /// Returns a copy of this view using the given `LottiePlaybackMode`
   public func playbackMode(_ playbackMode: LottiePlaybackMode) -> Self {
     var copy = self
@@ -332,7 +352,7 @@ public struct LottieView<Placeholder: View>: UIViewConfiguringSwiftUIView {
   public func currentProgress(_ currentProgress: AnimationProgressTime?) -> Self {
     guard let currentProgress = currentProgress else { return self }
     var copy = self
-    copy.playbackMode = .progress(currentProgress)
+    copy.playbackMode = .paused(at: .progress(currentProgress))
     return copy
   }
 
@@ -344,7 +364,7 @@ public struct LottieView<Placeholder: View>: UIViewConfiguringSwiftUIView {
   public func currentFrame(_ currentFrame: AnimationFrameTime?) -> Self {
     guard let currentFrame = currentFrame else { return self }
     var copy = self
-    copy.playbackMode = .frame(currentFrame)
+    copy.playbackMode = .paused(at: .frame(currentFrame))
     return copy
   }
 
@@ -356,7 +376,7 @@ public struct LottieView<Placeholder: View>: UIViewConfiguringSwiftUIView {
   public func currentTime(_ currentTime: TimeInterval?) -> Self {
     guard let currentTime = currentTime else { return self }
     var copy = self
-    copy.playbackMode = .time(currentTime)
+    copy.playbackMode = .paused(at: .time(currentTime))
     return copy
   }
 

package/Sources/Public/iOS/Compatibility/CompatibleAnimationView.swift

@@ -193,8 +193,10 @@ public final class CompatibleAnimationView: UIView {
     commonInit()
   }
 
-  required init?(coder _: NSCoder) {
-    fatalError("init(coder:) has not been implemented")
+  required init?(coder: NSCoder) {
+    animationView = LottieAnimationView()
+    super.init(coder: coder)
+    commonInit()
   }
 
   // MARK: Public

package/lottie-ios.podspec

@@ -8,7 +8,7 @@
 
 Pod::Spec.new do |s|
   s.name             = 'lottie-ios'
-  s.version          = '4.3.0'
+  s.version          = '4.3.2'
   s.summary          = 'A library to render native animations from bodymovin json'
 
   s.description = <<-DESC
@@ -22,7 +22,7 @@ Lottie enables designers to create and ship beautiful animations without an engi
   s.author           = { 'Brandon Withrow' => 'buba447@gmail.com', 'Cal Stephens' => 'cal.stephens@airbnb.com' }
   s.source           = { :git => 'https://github.com/airbnb/lottie-ios.git', :tag => s.version.to_s }
 
-  s.swift_version = '5.5'
+  s.swift_version = '5.6'
   s.ios.deployment_target = '11.0'
   s.osx.deployment_target = '10.12'
   s.tvos.deployment_target = '11.0'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lottie-ios",
-  "version": "4.3.0",
+  "version": "4.3.2",
   "description": "Lottie is a mobile library for Android and iOS that parses Adobe After Effects animations exported as json with bodymovin and renders the vector animations natively on mobile and through React Native!",
   "main": "index.js",
   "scripts": {