.. Copyright (c) 2008-2016 OpenShot Studios, LLC (http://www.openshotstudios.com). This file is part of OpenShot Video Editor (http://www.openshot.org), an open-source project dedicated to delivering high quality video editing and animation solutions to the world. .. OpenShot Video Editor is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. .. OpenShot Video Editor is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. .. You should have received a copy of the GNU General Public License along with OpenShot Library. If not, see . .. _animation_ref: Animation ========= OpenShot has been designed specifically with animation in mind. The powerful curve-based animation framework can handle most jobs with ease, and is flexible enough to create just about any animation. Key frames specify values at certain points on a clip, and OpenShot does the hard work of interpolating the in-between values. Key Frames ---------- OpenShot Cloud API supports the following key frame interpolation modes: ======= ================== ============ Value Name Description ======= ================== ============ 0 Bézier Interpolated values use a quadratic curve, and ease-in and ease-out 1 Linear Interpolated values are calculated linear (each step value is equal) 2 Constant Interpolated values stay the same until the next key frame, and jump to the new value ======= ================== ============ Use the :ref:`clip_keyframe_endpoint_ref` endpoint to create new key frames. JSON Structure -------------- The Clip API endpoint has a ``json`` property, which can be used to pass custom things, such as key frames and custom animations. Common properties which can use key frames in this exact same method include ``alpha, location_x, location_y, scale_x, scale_y, rotation, and volume`` (View all properties :ref:`clip_properties_ref`). .. code-block:: bash :caption: **Example key frame** (uses an X,Y coordinate system to graph/adjust properties over time): { "Points": [ { "interpolation": interpolation, <- 0=bezier, 1=linear, 2=constant "co": { "X": start_frame, <- frame number "Y": start_value <- value of key frame } }, { "interpolation": interpolation, "co": { "X": end_frame, "Y": end_value } } ] } .. code-block:: bash :caption: So, to **adjust volume** (fading in): "volume" : { "Points": [ { "interpolation": 1, "co": { "X": 1, <- Frame 1 "Y": 0.0 <- No volume } }, { "interpolation": 1, <- Interpolate the values 'linear' between 0.0 and 1.0 (for 300 frames) "co": { "X": 300, <- Frame 300 "Y": 1.0 <- Full volume } } ] } .. code-block:: bash :caption: And then you would pass this object along with the Clip API endpoint: clip_data = { "file": file_url, "position": start, "start": trimstart, "end": trimstart + length, "layer": track, "project": project_url, "json": { "volume": { -- insert key frame object here -- } } } You can have as many Points as needed in each key frame, and can build some really amazing animations by combining various properties and key frames. .. _frame_numbers_ref: Frame Numbers ------------- Key frame Point coordinates use frame numbers for the position of each Point, and I recommend using this general formula: ``(PositionInSeconds * FPS) + 1``. Frame numbers always begin on frame 1 (there is no frame zero, hence the + 1). FPS (Frames Per Second) should be the same as the **Project FPS** setting, since all clips are automatically converted to this framerate. The Y value will always be interpolated between points automatically. .. code-block:: javascript :caption: For example, if you want the volume to stay at 60% for most of the clip: Point (X: 1, Y: 0.6) <- Frame 1, set volume to 60% Point (X: 240, Y: 0.6) <- Frame 240, set volume to 60% Point (X: 300, Y: 0.0) <- Frame 300, set volume to 0% You can also only set the last 2 points. The first point will always default the entire curve to that value. .. code-block:: javascript :caption: The following is identical to the above example: Point (X: 240, Y: 0.6) <- first point will set entire clip volume to 60% Point (X: 300, Y: 0.0) <- Frame 300, set volume to 0% Generate Key Frames in OpenShot ------------------------------- You can also use the Desktop version of OpenShot Video Editor to generate JSON key frames. Just use the normal UI, drag and drop files/clips onto the timeline, customize properties over time, and then save the project file (which happens to be this same JSON format). The file extension is ``.osp``, but it is actually just a text file with ``JSON`` formatted data. This is a quick way to prototype out animations, and simply dump them into OpenShot Cloud API using the :ref:`load_endpoint_ref` endpoint. .. _bezier_curves_ref: Bézier Presets -------------- When using a Bézier curve for animation, OpenShot includes more than 20 curve presets (which affect the shape of the curve). For example, **Ease-In** has a more gradual slope at the beginning, making an animation move slower at the beginning, and faster at the end. **Ease-In/Out (Back)** has a gradual beginning and ending, but actually goes past the expected value and then back (producing a bounce effect). ===================== ========================== Curve Presets Value ===================== ========================== Linear 0,0,0,0, Ease (Default) 0.250,0.100,0.250,1.000 Ease In 0.420,0.000,1.000,1.000 Ease Out 0.000,0.000,0.580,1.000 Ease In/Out 0.420,0.000,0.580,1.000 Ease In (Quad) 0.550,0.085,0.680,0.530 Ease In (Cubic) 0.550,0.055,0.675,0.190 Ease In (Quart) 0.895,0.030,0.685,0.220 Ease In (Quint) 0.755,0.050,0.855,0.060 Ease In (Sine) 0.470,0.000,0.745,0.715 Ease In (Expo) 0.950,0.050,0.795,0.035 Ease In (Circ) 0.600,0.040,0.980,0.335 Ease In (Back) 0.600,-0.280,0.735,0.045 Ease Out (Quad) 0.250,0.460,0.450,0.940 Ease Out (Cubic) 0.215,0.610,0.355,1.000 Ease Out (Quart) 0.165,0.840,0.440,1.000 Ease Out (Quint) 0.230,1.000,0.320,1.000 Ease Out (Sine) 0.390,0.575,0.565,1.000 Ease Out (Expo) 0.190,1.000,0.220,1.000 Ease Out (Circ) 0.075,0.820,0.165,1.000 Ease Out (Back) 0.175,0.885,0.320,1.275 Ease In/Out (Quad) 0.455,0.030,0.515,0.955 Ease In/Out (Cubic) 0.645,0.045,0.355,1.000 Ease In/Out (Quart) 0.770,0.000,0.175,1.000 Ease In/Out (Quint) 0.860,0.000,0.070,1.000 Ease In/Out (Sine) 0.445,0.050,0.550,0.950 Ease In/Out (Expo) 1.000,0.000,0.000,1.000 Ease In/Out (Circ) 0.785,0.135,0.150,0.860 Ease In/Out (Back) 0.680,-0.550,0.265,1.550 ===================== ========================== .. _keyframe_presets_ref: Animation Presets ----------------- Use the :ref:`clip_presets_endpoint_ref` endpoint to quickly apply a preset to a clip (such as fade in, fade out, etc...). ===================== ========================== Animation Presets Value ===================== ========================== Fade In alpha Fade Out alpha Slide In (from left) location_x Slide Out (to right) location_x Slide In (from top) location_y Slide Out (to bottom) location_y ===================== ========================== Reset Key frames ---------------- On occasion you might need to quickly clear all key frames on a clip. OpenShot Cloud API has a special endpoint to make this as easy as possible. Use the :ref:`reset_endpoint_ref` endpoint to clear all key frames on a clip and reset everything back to the defaults.