Merge branch 'feature/css_animation' into develop

Switch from SMIL animations to CSS or WAAPI animations This should address #75, #86, #94 and #95
nbedos · Jun 30, 2019 · c9a3ecb · c9a3ecb
2 parents 1980275 + 7b6aaf9
commit c9a3ecb
Show file tree

Hide file tree

Showing 38 changed files with 4,573 additions and 776 deletions.
diff --git a/Makefile b/Makefile
@@ -46,7 +46,6 @@ html:
  termtosvg render $(CASTS_DIR)/htop.cast $(EXAMPLES_DIR)/htop_gjm8.svg -t gjm8
  termtosvg render $(CASTS_DIR)/ipython.cast $(EXAMPLES_DIR)/ipython_window_frame.svg -t window_frame
  termtosvg render $(CASTS_DIR)/unittest.cast $(EXAMPLES_DIR)/unittest_solarized_dark.svg -t solarized_dark
- rm -rf $(CASTS_DIR)
 
 deploy_test:
  twine upload -r pypitest dist/*

diff --git a/README.md b/README.md
@@ -5,9 +5,7 @@
 termtosvg is a Unix terminal recorder written in Python that renders your command
 line sessions as standalone SVG animations.
 
-<p align="center">
- <img src="https://nbedos.github.io/termtosvg/examples/awesome_window_frame.svg">
-</p>
+![Example](./docs/examples/awesome_window_frame.svg)
 
 * [Gallery of examples](https://nbedos.github.io/termtosvg/pages/examples.html)
 * [Gallery of templates](https://nbedos.github.io/termtosvg/pages/templates.html)

diff --git a/docs/examples/awesome_window_frame.svg b/docs/examples/awesome_window_frame.svg
diff --git a/docs/examples/awesome_window_frame_js.svg b/docs/examples/awesome_window_frame_js.svg
diff --git a/docs/examples/colors_progress_bar.svg b/docs/examples/colors_progress_bar.svg
diff --git a/docs/examples/htop_gjm8.svg b/docs/examples/htop_gjm8.svg
diff --git a/docs/examples/ipython_window_frame.svg b/docs/examples/ipython_window_frame.svg
diff --git a/docs/examples/unittest_solarized_dark.svg b/docs/examples/unittest_solarized_dark.svg
diff --git a/docs/templates/base16_default_dark.svg b/docs/templates/base16_default_dark.svg
diff --git a/docs/templates/dracula.svg b/docs/templates/dracula.svg
diff --git a/docs/templates/gjm8.svg b/docs/templates/gjm8.svg
diff --git a/docs/templates/gjm8_play.svg b/docs/templates/gjm8_play.svg
diff --git a/docs/templates/gjm8_single_loop.svg b/docs/templates/gjm8_single_loop.svg
diff --git a/docs/templates/progress_bar.svg b/docs/templates/progress_bar.svg
diff --git a/docs/templates/solarized_dark.svg b/docs/templates/solarized_dark.svg
diff --git a/docs/templates/solarized_light.svg b/docs/templates/solarized_light.svg
diff --git a/docs/templates/window_frame.svg b/docs/templates/window_frame.svg
diff --git a/docs/templates/window_frame_js.svg b/docs/templates/window_frame_js.svg
diff --git a/docs/templates/window_frame_waapi.svg b/docs/templates/window_frame_waapi.svg
diff --git a/man/termtosvg-templates.md b/man/termtosvg-templates.md
@@ -9,7 +9,8 @@ templates are SVG files in which termtosvg embeds animations. Using templates ma
 * Add a terminal UI or window frame to the animation
 * Have interactive animations (for example play/pause buttons)
 
-See [here](https://nbedos.github.io/termtosvg/pages/templates.html) for a gallery of the templates included with termtosvg
+See [here](https://nbedos.github.io/termtosvg/pages/templates.html) for a gallery of the templates
+included with termtosvg
 
 ## TEMPLATE STRUCTURE
 
@@ -21,6 +22,7 @@ Here is the basic structure of a template:
  <defs>
  <termtosvg:template_settings xmlns:termtosvg="https://github.com/nbedos/termtosvg">
  <termtosvg:screen_geometry columns="82" rows="19"/>
+ <termtosvg:animation type="css"/>
  </termtosvg:template_settings>
  <style type="text/css" id="generated-style">
  <!-- [snip!] -->
@@ -32,17 +34,91 @@ Here is the basic structure of a template:
  <svg id="screen" width="656" viewBox="0 0 656 323" preserveAspectRatio="xMidYMin meet">
  <!-- [snip!] -->
  </svg>
+ <script type="text/javascript" id="generated-js">
+ <!-- [snip!] -->
+ </script>
 </svg>
 ```
 
 Overall, one can identify:
 
 * An `svg` element with id "terminal"
 * A `defs` element which includes:
- * A termtosvg specific `template_settings` element used to specify the terminal size (number of columns and rows) for which the template is made
+ * A termtosvg specific `template_settings` element used to specify:
+ * the terminal size (number of columns and rows) for which the template is made
+ * the animation rendering methods ("css" for CSS or "waapi" for Web Animations API)
  * A `style` element with id "generated-style" that will be overwritten by termtosvg
  * Another `style` element with id "user-style" that should contain at least the terminal color theme. This element is defined by the template creator and won't be overwritten by termtosvg
 * An inner `svg` element with id "screen" which will contain the animation produced by termtosvg
+* A machine generated script element with id "generated-js"
+
+### Animation rendering: CSS vs Web Animations API
+termtosvg can create animations using either CSS or Web Animations API.
+
+#### Choice of the rendering method
+The rendering method used for a specific template is defined by an element `termtosvg:animation`
+of the template which has an attribute "type" set to either "css" or "waapi".
+
+#### CSS animations
+When set to use CSS animations, termtosvg defines a single CSS animation for the element
+with id `screen_view` as shown below. If need be, this animation can be overriden in another,
+user defined, style element.
+
+```SVG
+<style type="text/css" id="generated-style"><![CDATA[
+/* Snip! */
+
+@keyframes roll {
+ 0.000%{transform:translateY(0px)}
+ 1.426%{transform:translateY(-323px)}
+ 1.953%{transform:translateY(-646px)}
+ /* Snip! */
+ 96.344%{transform:translateY(-29393px)}
+}
+
+#screen_view {
+ animation-duration: var(--animation-duration);
+ animation-iteration-count:infinite;
+ animation-name:roll;
+ animation-timing-function: steps(1,end);
+}
+]]></style>
+```
+
+CSS animations makes it a little bit harder to add interactivity using JS code but have a better
+chance to be displayed as is by online platforms.
+
+#### Web Animations API
+When using Web Animations API, termtosvg defines an object `termtosvg_vars` with two attributes
+named `transforms` and `timings` as shown below.
+```SVG
+<script type="text/javascript" id="generated-js"><![CDATA[
+var termtosvg_vars = {
+ transforms: [
+ {transform: 'translate3D(0, 0px, 0)', easing: 'steps(1, end)'},
+ {transform: 'translate3D(0, -323px, 0)', easing: 'steps(1, end)', offset: 0.014},
+ {transform: 'translate3D(0, -646px, 0)', easing: 'steps(1, end)', offset: 0.020},
+ /* Snip! */
+ {transform: 'translate3D(0, -29393px, 0)', easing: 'steps(1, end)'}
+ ],
+ timings: {
+ duration: 27349,
+ iterations: Infinity
+ }
+};]]></script>
+```
+These two attributes should be used in another user-defined script element to create an animation
+for the element with id "screen_view". Here is an abridged example taken from the window_frame_js
+template.
+
+```SVG
+<script type="text/javascript">
+var animation = document.getElementById("screen_view").animate(
+ termtosvg_vars.transforms,
+ termtosvg_vars.timings
+)
+</script>
+```
 
 
 ## TEMPLATE CUSTOMIZATION
@@ -96,6 +172,17 @@ Just add your code in a new `script` element.
 
 Complete example here: [window_frame_js](../termtosvg/data/templates/window_frame_js.svg)
 
+### Restricting the animation to a single loop
+For a template using CSS, simple add a custom style element specifying the number of loops like so:
+```SVG
+<style type="text/css" id="user-style">
+ #screen_view {
+ animation-iteration-count:1;
+ }
+</style>
+```
+Complete example here: [window_frame_js](../termtosvg/data/templates/gjm8_single_loop.svg)
+
 ## termtosvg internal template usage
 In order to produce the final animation, termtosvg will modify the template in a number of ways.
 

diff --git a/man/termtosvg.md b/man/termtosvg.md
@@ -3,11 +3,11 @@
 % December 2018
 
 ## SYNOPSIS
-**termtosvg** [output_path] [-c COMMAND] [-g GEOMETRY] [-m MIN_DURATION] [-M MAX_DURATION] [-s] [-t TEMPLATE] [--help]
+**termtosvg** [output_path] [-c COMMAND] [-D DELAY] [-g GEOMETRY] [-m MIN_DURATION] [-M MAX_DURATION] [-s] [-t TEMPLATE] [--help]
 
 **termtosvg record** [output_path] [-c COMMAND] [-g GEOMETRY] [-h]
 
-**termtosvg render** *input_file* [output_path] [-m MIN_DURATION] [-M MAX_DURATION] [-s] [-t TEMPLATE] [-h]
+**termtosvg render** *input_file* [output_path] [-D DELAY] [-m MIN_DURATION] [-M MAX_DURATION] [-s] [-t TEMPLATE] [-h]
 
 ### DESCRIPTION
 termtosvg makes recordings of terminal sessions in animated SVG format. If no output
@@ -36,6 +36,9 @@ program to execute together will all arguments to be made available to the progr
 option is not set, termtosvg will record the program specified by the $SHELL environment variable
 or `/bin/sh`.
 
+#### -D, --loop-delay=DELAY
+Duration of the delay between two consecutive loops of the animation in milliseconds.
+
 ##### -g, --screen-geometry=GEOMETRY
 geometry of the terminal screen used for rendering the animation. The geometry must
 be given as the number of columns and the number of rows on the screen separated by
@@ -117,6 +120,11 @@ Enforce both minimal and maximal frame durations
 termtosvg -m 17 -M 2000
 ```
 
+Specify a 2 seconds delay between animation loops
+```
+termtosvg -D 2000
+```
+
 Render still frames instead of an animated SVG using a specific template
 ```
 termtosvg -s -t gjm8_play