Merge pull request #159 from shotstack/derk/motion-descriptions

Describe text animation, tween and transition options as they render

Author: dazzatronus

schemas/richcaptionproperties.yaml

@@ -80,7 +80,7 @@ RichCaptionAnimation:
           <li>`highlight` - Word changes to active color when spoken (shows all words)</li>
           <li>`pop` - Each word scales up when active</li>
           <li>`fade` - Gradual opacity transition per word</li>
-          <li>`slide` - Words slide in from a direction</li>
+          <li>`slide` - Words slide in, travelling in `direction`</li>
           <li>`bounce` - Spring animation on word appearance</li>
           <li>`typewriter` - Words appear one by one and stay visible</li>
           <li>`none` - No animation, all words visible immediately</li>
@@ -98,7 +98,7 @@ RichCaptionAnimation:
       default: "highlight"
       example: "highlight"
     direction:
-      description: Direction for directional animations (slide). Only applicable when style is `slide`.
+      description: The direction words travel when style is `slide`.
       type: string
       enum:
         - left

schemas/richtextproperties.yaml

@@ -275,14 +275,14 @@ RichTextAnimation:
   properties:
     preset:
       description: >-
-        The animation preset to apply. Available presets:
+        The animation preset to apply. Every preset starts with the clip. Available presets:
         <ul>
-          <li>`fadeIn` - fadeIn in animation</li>
-          <li>`slideIn` - slide in from a direction</li>
-          <li>`typewriter` - typewriter effect</li>
-          <li>`ascend` - ascend from a direction</li>
-          <li>`shift` - shift in from a direction</li>
-          <li>`movingLetters` - letters move in from a direction</li>
+          <li>`fadeIn` - fade in</li>
+          <li>`slideIn` - fade in while sliding in `direction`</li>
+          <li>`typewriter` - type the text out behind a cursor</li>
+          <li>`ascend` - each word rises (`up`) or drops (`down`) into place</li>
+          <li>`shift` - fade in while shifting a short distance in `direction`</li>
+          <li>`movingLetters` - fade in, then ripple the letters along `direction` for the rest of the clip. Ignores `duration` and `style`.</li>
         </ul>
       type: string
       enum:
@@ -296,22 +296,25 @@ RichTextAnimation:
     duration:
       description: >-
         Override animation duration in seconds.
-        Must be between 0.1 and 30 seconds.
+        Must be between 0.1 and 30 seconds. When omitted, the text animates at about 30 characters per second,
+        taking at least 0.3 seconds and at most 90% of the clip.
       type: number
       minimum: 0.1
       maximum: 30
       example: 2
     style:
       description: >-
-        Animation style - animate by character or by word. Only applicable for typewriter and shift animations.
+        Animate by character or by word. Applies to `fadeIn`, `slideIn`, `typewriter` and `shift`, where `shift`
+        defaults to `character`. `ascend` always animates by word.
       type: string
       enum:
         - character
         - word
       example: "character"
     direction:
       description: >-
-        Direction for directional animations. Required for slideIn, ascend, shift, and movingLetters presets.
+        The direction the text travels. Defaults to `left` for `slideIn` and `shift`, and to `up` for `ascend` and
+        `movingLetters`.
         <ul>
           <li>`ascend` - supports: up, down</li>
           <li>`shift` - supports: left, right, up, down</li>

schemas/transition.yaml

@@ -28,7 +28,7 @@
                 <li>`zoom` - fast zoom in</li>
               </ul>
             The transition speed can also be controlled by appending `Fast` or `Slow`
-            to the transition, e.g. `fadeFast` or `CarouselLeftSlow`.
+            to any transition except `zoom`, e.g. `fadeFast` or `carouselLeftSlow`.
           enum:
             - none
             - fade
@@ -120,7 +120,7 @@
                 <li>`zoom` - fast zoom out</li>
               </ul>
             The transition speed can also be controlled by appending `Fast` or `Slow`
-            to the transition, e.g. `fadeFast` or `CarouselLeftSlow`.
+            to any transition except `zoom`, e.g. `fadeFast` or `carouselLeftSlow`.
           enum:
             - none
             - fade

schemas/tween.yaml

@@ -5,9 +5,11 @@
           <ul>
             <li>Opacity - animate the transparency of a clip.</li>
             <li>Offset - animate the x and y position of a clip.</li>
+            <li>Scale - animate the size of a clip.</li>
             <li>Rotation - animate the rotation of a clip.</li>
             <li>Skew - animate the horizontal and vertical shearing effect.</li>
             <li>Volume - animate the audio volume of a clip.</li>
+            <li>Speed - animate the playback speed of a video clip.</li>
           </ul>
       properties:
         from: