Shotcut CSS Animations Overlay HTML (Text: HTML) Filter Generator

This generator creates an Overlay HTML filter (otherwise known as a Text: HTML filter) that can be used in the Shotcut video editor to create the animations from an original HTML file that uses CSS3 animation directives. Since many (most?) of the animations have little (or nothing) to do with text I shall use the term "Overlay HTML filter" from now on rather than "Text: HTML filter", but the two are interchangeable.

CSS animations work using seconds or milliseconds as their timeframe. However Shotcut works using "normalised" time, which is 0 at the beginning of the clip and 1 at the end. There is no way for an Overlay HTML Filter to ascertain the (realtime) length of a clip, other than by the user giving it a little help. This "little help" is in the form of the user providing the framerate of the video to which the filter is being applied. Once the filter knows the framerate it can convert from "normalised time" to real time and vice-versa. If an incorrect framerate is supplied the animation will still play in Shotcut, but at the wrong speed.

If you input a negative number as the framrate this has a special meaning. It means that the animation will run throughout a percentage of the clip to which it is applied and the "duration" and "delay" values in the animation data that is supplied do not mean "seconds" (or "milliseconds") but instead are proportional to the duration of the clip itself. For example say:

If you specify the framerate as: i.e. the negative numbers are a percentage of the length of the clip.

Prerequisites

You will need two javascript files in order to run the resulting HTML filter. These can be downloaded by clicking (right-clicking or ctrl-clicking) on the PDF icons in the table below.

Downloads - click (or right-click) on the relevant Javascript symbol
DownloadDescription
jQuery - a JavaScript library designed to simplify HTML DOM tree traversal, manipulation and events.
elusien_cssanims2js.js - the "glue" between Web Animations (Polyfill) and Shotcut-MLT's WebVfx.

Limitations

Partial Keyframes

"Partial Keyframes" are not allowed. CSS allows you just to specify a single keyframe to animate from the original state to this one. This utility (because of the underlying technology) does not allow this; you must specify the original state (0%, or "from") as well as the follow-on state(s) to which you wish the animation to progress. Also, the property or properties you wish to animate MUST appear in every keyframe, otherwise you have a "partial keyframe".

Order of Animation Parameters

The parameters in the animations data MUST be in the following order:

 name            e.g horizontal
 duration        e.g. 1s or 2.5s or 25ms [the latter value is 25 milliseconds]
 timing-function e.g. ease-out or cubic-bezier(0.1, 0.7, 1.0) or linear etc...
 delay           e.g. 0s or 500ms
 iteration-count e.g. 1 or 10 or infinite
 direction       e.g. normal or reverse or alternate or alternate-reverse
 fill-mode       e.g. forwards or backwards or both or none

The CSS standard allows some leeway in how these parameters may be specified (see: animations property). This online generator does not allow this leeway. The parameters must be specified in the order shown and all 7 should be specified. You can omit parameters, but only from the high end. So if you want to specify the "fill-mode" you have to supply 7 parameters, however if you don't want to specify "fill-mode" and "direction" you only have to specify the first 5 parameters.

CSS Pseudo-elements Cannot be Animated

A CSS pseudo-element is a keyword added to a selector that lets you style a specific part of the selected element(s). For example, ::first-line can be used to change the font of the first line of a paragraph. Other pseudo-elements that are commonly used are ::before and ::after. The HTML and CSS can often be changed to replace them by "normal" CSS elements, such as "<div>".

-webkit- prefix

This is a restriction of the version of the webkit HTML engine that Shotcut uses, which does not support the CSS transform property without the ‑webkit‑ prefix. However this is only the case outside keframes. Inside a keyframe clause you must use the form transform, whereas outside a keyframe clause you must use the form ‑webkit‑transform instead.

transform-style: preserve-3d

This too is a restriction of the version of the webkit HTML engine that Shotcut uses, which does not support the CSS transform-style: preserve-3d; property at all, even with the ‑webkit‑ prefix. This is a blow for those wanting to do 3D CSS animations.

Instructions

  1. Open your HTML file (that has CSS3 animations), or better still a copy of this file in a text editor (such as Notepad++) or Atom)
  2. Copy & Paste the keyframes data (see below) into the "Keyframes Data" window below.
  3. Copy & Paste the animations data (see below) into the "Animations Data" window below.
  4. Input the video's framerate in the relevant box.
  5. Press the button that says 'Click to Generate Javascript'.
  6. Copy the code in the "Javascript Code" window into a the file immediately after the line that says "<head>".
  7. Delete the animations data in the file (or comment it out by changing "animation:" to "Xanimation:")
  8. Save your edited HTML file.

You can delete the keyframes data from the file, but you do not need to do this, since keyframes are ignored without any animation clauses referring to them. You can check that the new HTML file works as expected by opening it in a browser. The animations should play the same as they did in the original HTML. The difference is that this new HTML file will produce the same animations when used as an Overlay HTML (Text: HTML) filter in Shotcut, whereas the original will not.

Debugging

If the animation does not work in the browser check the javascript console for any errors. You do this by pressing Function Key F12 while in the browser window then clicking on the tab that says "console". If it works in the browser, but not in Shotcut then look in the shotcut logfile (View -> Application Log...) for any error messages.

Note

The original keyframes data that you copy (including the "@keyframes" keyword) looks something similar to:

 @keyframes horizontal {
    0%  {transform: translateX(  0 );}
    90% {transform: translateX(100%);}
 }
 @keyframes vertical {
    0%  {transform: translateY(  0 );}
    90% {transform: translateY(100%);}
 }
 @keyframes diagonal {
  start {transform: translate(  0 ,   0 ); opacity: 1;}
    50% {transform: translate(100%, 100%); opacity: 0;}
    end {transform: translate(  0 ,   0 ); opacity: 1;}
 }

The original animations data that you copy (including the element ".h", ".v" etc. below) looks something similar to:

 .h       { animation: horizontal 1s ease-out 0s 1 normal forwards; }
 .v       { animation: vertical   1s ease-out 0s 1 normal forwards; }
 .vh, .hv { animation: diagonal   1s ease     0s 1; }

If the animations data is part of a larger CSS clause, break that clause into two, with the animation data separate. e.g.

 .h       { width: 100%; height: 100%; animation: horizontal 1s ease-out 0s 1; }

needs to be split into two parts with the animation clause on its own e.g.

 .h       { width: 100%; height: 100%;}
 .h       { animation: horizontal 1s ease-out 0s 1; }

The Utility

Keyframes Data (copy-paste from your HTML)
Animations Data (cut-paste from your HTML)
Framerate

Resulting Javascript (Insert this immediately after the <head> tag)
Disclaimer

Version 1.0 Copyright © 2019 - Elusien Entertainment (www.elusien.co.uk)

Creative Commons Licence This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

The following is a summary of the license. For the actual wording of the license see: https://creativecommons.org/licenses/by-sa/4.0/legalcode

Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.

ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.

No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.

Notices

  • You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
  • No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
  • The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
  • THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.