Table of Contents

• Table of Contents
• Intro
• Installation
  • Config file
    • Config options
  • Presets
    • Presets options
• Scripting
  • Script options:
  • Script steps
  • iframes

Intro

giffr is an automated video recorder for Web applications.

Automated screen recording with giffr provides many advantages:

• Video content is always up to date.
• The quality of the flows can be improved over time.
• It's scalable - you can maintain hundreds of video flows.
• Full control over actions speed of the entire flows and/or each step.
• Playback speed of certain flow parts.
• Exclude certain flow parts from capturing.
• The same flow can be captured in different formats and sizes for different platforms.
• Editing doesn't require any additional tools or skills.

Installation

To use giffr in your project, run:

npm install giffr

Config file

To get started, you need to create a config file.
In the config file, add an options array and pass it as an argument to the run() function:

const giffr = require("giffr");
let options = [
    {
        "name": "my-project",
        "presetsDir": "presets/",
        "scriptsDir": "scripts/",
        "outputDir": "assets/videos",
        
        "presets": [
            "blog",
            "you-tube",
            "whats-new"
        ],
        
        "scripts": [
            "find-a-product",
            "see-product-details",
            "buy-a-product"
        ]
    }
]
giffr.run(options);

Config options

| key | Description | Default | Optional | | -------------------- | ------------------------------------------------------------------- | ----------- | -------- | | name | Project name that will be included in the exported video file name. | NA | | | rootDir | Root project directory. | "./" | optional | | assetsDir | Assets directory. | "./assets" | optional | | scriptsDir | Scripts directory. | "./scripts" | optional | | presetsDir | Presets directory. | "./presets" | optional | | outputDir | Generated videos directory. | "./output" | optional | | screenshotsDir | Screen shot directory. | "./output" | optional | | showStats | Shows info about capturing (debugging). | false | optional | | renderActualCursor | Visualizes the exact position of the cursor (debugging). | false | optional | | exportGif | Export animated gifs | false | optional | | encodeVideo | Encode video after capturing. | false | optional | | exportGifBulk | Export all scripts as animated gifs. | false | optional | | encodeVideoBulk | Encode all scripts as videos (for better quality/size ratio) | false | optional | | metaData: generate | Meta data will be generated. | false | optional | | metaData: outputPath | Meta data output directory. | "./output | optional |

Presets

Presets define basic properties of the media format, script pace and video quality. They especially useful if you have different platforms for sharing like video, blogs, emails and so on.

{
    "width": 1440,
    "height": 900,
    "scalefactor": 1,
    "captureFPS": 60,
    "playbackFPS": 60,
    "stepDelay": 0,
    "videoBPS": 800000000,
    "speedFactor": 1,
    "audio": true,
    "soundEffects": true,
    "speech": true
}

Presets options

| key | Description | default | | ------------ | ----------------------------- | ------- | | width | Width of the media in pixels | 800 | | height | Height of the media in pixels | 800 | | scalefactor | Scale factor of the media | 800 | | captureFPS | Width of the media in pixels | 800 | | playbackFPS | Width of the media in pixels | 800 | | stepDelay | Delay between steps | 800 | | videoBPS | Video quality | 800 | | speedFactor | Duration of each step | 800 | | audio | Capture audio | false | | soundEffects | Mouse clicks | false | | speech | Text to speech voice over | false |

Scripting

Scripts are plain JSON files:

{
    "url": "https://my-site.com",
    "stepDelay": 240,
    "speedFactor": 1,
    "steps": [{
            "startRecording": ""
        },
        {
            "click": "#b"
        },
        {
            "doubleClick": "#a"
        },
        {
            "tripleClick": "#b"
        },
        {
            "stopRecording": ""
        }
    ]
}

Scripts can be nested:

script-a.json

{
    "steps":[
        {
        "runScript": "./script-b.json"
        }
    ]
}

You can run multiple scripts in one project:

scripts:[
    "script_1",
    "script_2",
    "script_3"
]

Script options:

Options should be provided in the script file itself:

{
    "url": "http://example.com",
    "speedFactor": 1000,
    "steps":[
        ...
    ]
}

Script steps

| Step | Description | Example | | ---------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | addStyleTag | Adds <style> tag to the given frame. | open | | position | Moves cursor to the center of the screen | open | | click | Navigates a cursor to a given target, actualize and visualize one click | open | | clickAndShoot | Navigates to a given target and makes one screenshot | open | | doubleClick | Navigates a cursor to a given target, actualize and visualize two clicks | | | dragAndDrop | Navigates to a given target, drags and drops after traveling for a given distance | open | | fastForward | Moves cursor to the center of the screen | open | | fastForwardStart | Moves cursor to the center of the screen | open | | fastForwardStop | Moves cursor to the center of the screen | open | | hover | Navigates a cursor to a given target | open | | hoverAboveList | Navigates a cursor to a given target and traveling through the list of items | open | | inputText | Navigates to a given target (if provided) and typing a given text | open | | navigate | Navigates to a given url | open | | page | Page provides methods to interact with a single tab | open | | pauseOn | Pauses recording when target appears | open | | pauseRecording | Pauses recording | open | | playSound | Moves cursor to the center of the screen | open | | position | Navigates to a given target, actualize and visualize three clicks | open | | removeStyleTag | Moves cursor to the center of the screen | open | | resumeOn | Resumes recording when target appears | open | | resumeRecording | Resumes recording | open | | rightClick | Navigates a cursor to a given target, actualize and visualize three clicks | open | | scrollBy | Navigates to a given target, actualize and visualize three clicks | open | | scrollIntoView | scrolls the element's parent container such that target is visible to the user | open | | shoot | Makes one screenshot | open | | speak | Moves cursor to the center of the screen | open | | startRecording | Starts recording | open | | stopOn | Stops recording when target appears | open | | stopRecording | Stops recording | | | subtitle | Moves cursor to the center of the screen | open | | tripleClick | Navigates a cursor to a given target, actualize and visualize three clicks | | | wait | Waits for a given amount of time | | | waitForSelector | Waits for target appearance | open | | zoomOn | Waits for target appearance | open |

iframes

At this point, giffr supports one level of iframes. Nesting is not supported.
To select an element inside an iframe include "iframe" string as the first chain of the target selector:

{
    "click": "iframe .my-target"
}