Script Documentation

Description

A script consists of a JSON text defining an array of objects.

Each object has unique identifier (id) within the scripts documents.

All objects have several properties which can be defined. But not all properties affect all types of objects.

The most important properties of any object are the following two:

Duration: defines how long an object lasts after the "play event". This property can be manually defined for all kind of objects. However in case of objects with temporal dimension (video, audio) this property can be left unset, and its value will be the duration of the associated media.

Play: defines when an object will be processed during the producing process.

Objects can modify their properties during the producing process based in "events" which are executed at defined times.

Events

Each object can define one or more events which will be executed at the specified time. An event consists of an execution time and an action. An action can be a object property modification or a procedure call.

Expressions

An expression is an evaluable formula with some return value. The most simple expression is a literal, such a number (ie: 1). Expressions can use the following usual arithmetic operators: +, -, *, or /. When acting as a value, an expression can use a literal number or an object property, which is addressed with the object ID, a dot, and the property name.

Variables

Expressions can contain variables. These are identified as a string prepended with the dollar symbol (ie: $variable1). Variables are assigned at video creation time (API method Template_Video_New). Variable types are number or boolean depending of the property.

Object types


Object Properties List

Property nameAllowed valuesDefault Value (if not set)Objects affectedDescription

Event procedures List

Procedure nameParametersObjects affectedDescription

Object Properties

id

text1 -> "Sezion"


                [
                  {"text" : {
                  "id" : "text1",
                  "duration": 2000,
                  }}
                ]
              
Guidelines

All the elements must have a identifier (id). The element is a UTF-8 string and must be unique. This id could be used for referal other objects and for define media expressions.
If a element don't have id the system define a defaul value like "object_##".

Examples:
  • "id": "text1" . The element text1 is defined.
  • "play": "text1.start" . When the element with id "text1" start, this element start too.

Duration

text1 -> "Sezion"


                [
                  {"text" : {
                  "id" : "text1",
                  "duration": 2000,
                  "play": 0,
                  "textLines": 2
                  }}
                ]
              
Guidelines

The duration is expressed in milliseconds and could not be a negative number.

Play

text1 -> "Sezion"

image1 -> "guitar.jpeg"


                [
                  {"image" : {
                      "id" : "image1",
                      "duration": 3000,
                      "play": 0
                  }},

                  {"text" : {
                      "id" : "text1",
                      "duration": 1000,
                      "play": ["image1.start", 2000],
                      "textLines": 3
                  }}
                ]
              
Guidelines

Define the timeline positions where the element will start to play separates by commas. We can have different cases:

  • A time position (in milliseconds). Examples.
    • "play": 1000 . The element start to play in the second 1 of the final video.
    • "play": 0 . The element start to play at the beginning of the final video.
  • Media expression. Is composed of the media id and the position.
    • id.start: define the media start position
    • id.end: define the media end position
    Examples:
    • "play": "image1.start" . When the element with id "image1" start, this element start too.
  • Composition of expressions
    • Media expression.
    • A time position.
    • Operators ( +, - , * , / )
    Examples:
    • "play": "image1.start"+1000 . Start to play 1 second after image1 start to play.
    • "play": "text1.end"-2000 . Start to play 2 seconds before the reproduction of text1 end.
    • "play": "text1.start"*2, 5000 . Start to play 2*start position of text1 seconds and in the second 5 of the global timeline.

Events

image1 -> "guitar.jpeg"


                [

                {"image":{
                    "id" : "image1",
                    "play" : 0,
                    "duration" : 3000,
                    "events" : [
                          {
                             "start" : {
                                "imageFadeIn" : 1000
                             }
                          },
                          {
                             "start+2000" : {
                                "imageFadeOut" : 1000
                             }
                          }
                       ],
                  }
                }

                ]
              
Guidelines

our system support multiples events over each objet. for use it it necessary difine the property events. This property is an array of events.
The events applied are referal to the objet. For that is possible to use the media expressions start and end to define when the event happend. The structure of a events property is the next:


                      ...
                      "events" : [
                            {
                               "position-event" : {
                                  "event" : duration
                               }
                            },
                            {
                               "position-event2" : {
                                  "event2" : duration2
                               }
                            },
                            ...
                         ],
                      ...
                    
  • events : the definition of array of events.
  • position-event : Expression returning unsigned integer. this Expression have the next two possibilities:
    • "start + timeposition":
      • start (required): the start position of the objet.
      • + timeposition (optional): the time in milisecond when the event start from the beginning of the objet timeline
    • "end - timeposition":
      • end (required): the end position of the objet.
      • - timeposition (optional): the time in milisecond when the event start before of the end of the objet timeline
    • If you need apply two differents events in the same position is necesary define the position-event for each of them.
  • "event","event2",...: different events that affect to the object. You can see the list of the availables events
  • Examples.
    
                          ...
                          "events" : [
                                {
                                   "start" : {
                                      "imageFadeIn " : 2000
                                   }
                                }
                             ],
                          ...
                        
    In this event the objet have a chante in the alpha channel from current value to 100% in 2 second in the start of the object
    
                          ...
                          "events" : [
                                {
                                   "start" : {
                                      "imageFadeIn " : 2000
                                   }
                                   "start" : {
                                      "moveTo" : {
                                         "duration" : 1000,
                                         "x" : -0.90,
                                         "y" : 0.880
                                      }
                                   }
                                }
                             ],
                          ...
                        
    In this event the objet have a change in the alpha channel from current value to 100% in 2 second in the start of the object and in the same temporal position have a linear movement in 1 second to the indicates coordinates.
    
                          ...
                          "events" : [
                                {
                                   "start+1000" : {
                                      "imageFadeOut " : 2000
                                   }
                                }
                             ],
                          ...
                        
    In this event the objet have a change in the alpha channel from current value to 0% in 2 second in the start of the object plus 1 second.
    
                          ...
                          "events" : [
                                {
                                   "end-2000" : {
                                      "FadeOut " : 2000
                                   }
                                }
                             ],
                          ...
                        
    In this event the objet have a change in the audio from current value to silence in 2 second in the end of the object minus 2 seconds.