Welcome to sNCL’s documentation!

sNCL is a DSL (Domain Specific Language) that aims to simplify the authoring of multimedia applications. It is based on NCL (Nested Context Language), the standard language of the Brazilian Digital TV System.

sNCL can be installed following the instructions below:

Getting started

Installing sNCL

sNCL relies on Lua and LuaRocks, which can be installed from the standard repositories of most distros. LuaRocks is a plugin manager for Lua.

For example, on Ubuntu Linux and Arch Linux:

sudo apt-get install lua luarocks
sudo pacman -S lua luarocks

After LuaRocks and Lua are installed, sNCL can be installed using LuaRocks. This command will install sncl and all the Lua plugins it requires.

sudo luarocks install sncl

Todo

How to install cloning the github repo

Todo

How to install on Windows and MacOS?

Running an sNCL program

Todo

Add some instructions on how to run an sncl program.

And can be used according to the examples and tutorials:

Basic Concepts of sNCL

sNCL (simpler Nested Context Language) follows the NCM model, which is a conceptual model for the representation and handling of hypermedia documents. The model separates its elements in representation elements, that defines the representation of a media object in time and space and relationship elements, that defines the relationship between the media objects.

Thus, the elements in sNCL are divided in Representation elements and Relationship Elements.

Representation Elements are:

1. Context
2. Media
3. Area
4. Switch
5. Region

Relationship Elements are:

1. Link

As the name suggests, the language is composed of nested context. The whole body of the document itself is seen as a context, the main context, in which the application starts, that can have other contexts inside it.

Todo

Explain context, and access to elements inside of the context

sNCL also has a new element, the macro element, that is neither a Representation Element or a Relantionship Element.This new element behaves exactly like a macro is supposed to.

macro macro1 (mName, mType)
   media mName
      type: mType
   end
end

Default Properties

These are the properties of the Ginga-NCL Player:

Properties	Default Values
top, left, bottom, right, width, height	0
location	0
size	0
bound	0
plan	“video”
baseDeviceRegion	no default
deviceClass
explicitDur
background	transparent
visible	true
transparency	0%
rgbChromaKey	nil
fit	nil
scroll	none
style	nil
soundLevel, trebleLevel, bassLevel	1
balanceLevel	0
zIndex	0
fontColor	white
fontAlign	left
fontFamily
fontStyle	normal
fontSize	no default
fontVariant	normal
fontWeight	normal
player	no default
reusePlayer	false
playerLife	close
moveLeft, moveRight, moveUp, moveDown	nil
focusIndex	nil
focusBorderColor
selBorderColor
focusBorderWidth
focusBorderTransparency
focusSrc, focusSelSrc	nil
freeze	false
transIn, transOut	empty string

sNCL Elements

Media Element

The media element defines an media object, that can be an image, video, text and even HTML documents or Lua scripts.

Its syntax is defined as:

Media = "media" * Id *(Comentario + MacroCall + Area + Propriedade)^0 * end
Area = "area" * Id * (Comentario + Propriedade)^0 * "end"

It is identified univocally by the id field, for example, the code below declares a media object that is a HTML document and has the id “media1”. In this case, no other element in the entire application may have the id “media1”.

media media1
   type: "text/html"
end

The media element must have either a type, a source or refer to another element, so the player knows what is the type of the media object.

media media1
   type: "text/html" -- a type
end
media media2
   src: "docs/index.html" -- a source
end
media media3
   refer: media2 -- media3 refers to media2
end

In addition to specifying the type of the media object, or what the object is, it can also be specified where the object will appear in the screen, the location of it, the list of these other possible properties is in Default Properties

media media4
   -- a media with margin of 15 pixels on both sides
   src: "medias/image.jpg"
   left: 15px
   right: 15px
end

Area Element

The area element defines an anchor ( a part of the information of the media element) that may be used in relationships with other objects.

Area = "area" * Id * (Comentario + Propriedade)^0 * "end"

Anchors can represent:

• Spatial portions of images (begin, end, first, last)
• Temporal portions of continuous media content (begin, end, coords, first, last)
• Textual segments

For example, a temporal portion of a video can used like the example below. When the media1 gets in 20s, media2 will start.

port pBody media1

media media1
   src: "medias/video1.jpg"
   area area1
      begin: 20s
   end
end

media media2
   src: "medias/image2.jpg"
end

onBegin media1.area1 do
   start media2 end
end

Link Element

The syntax of the link element is:

Link = Condition^1 * (Comentario + Propriedade + Action)^0 * end

Condition = AlphaNumeric * Id * TermCond
TermCond = ("and" * Condition) + ("do")

Action = AlphaNumeric * Id * (Comentario + Propriedade) * "end"

onBegin media1 do
   start media2 end
end

The link element must have at least 1 condition and 1 action, in the case above, the condition is “onBegin media1” and the action is “start media2”, meaning that, when the media1 begin, the media2 will start.

The condition and the action can also have properties, like a delay:

onBegin media1 do
   start media2 end
   delay: 10s
end

onBegin media1 do
   start media2
      delay: 10s
   end
end

As seen in the syntax of the element, it can have multiple conditions and actions. To declare more than 1 action, you simply add it, like a son element:

onBegin media1 do
   start media2 end
   start media3 end
end

And for multiple conditions, you can concatenate then with the “and” keyword:

onBegin media1 and onEnd media2 do
   start media3 end
end

In this stage of development, the compiler only accepts the and value, so, the link will only activate when media1 begin and media2 end. Adding the or value will come in later stages.

Below is a list of the accepted conditions and actions:

Conditions	Event Type
onBegin
onEnd
onAbort
onPause
onResume
onSelection
onBeginSelection
onEndSelection
onAbortSelection
onPauseSelection
onResumeSelection
onBeginAttribution
onEndAttribution
onPauseAttribution
onResumeAttribution
onAbortAttribution

Actions	Event Type
start
stop
abort
pause
resume
set

Context Element

The context element defines

Its syntax is defines as:

Context = "context" * Id * (Comentario + Port + Propriedade + Media + Context + Link + MacroCall)^0 * "end"

As can be seen in the grammar especification, a context element can nest other elements, like Media Element, Macro Element, Link Element and other contexts.

Elements that are inside of a context are only visible to the elements of the same context, meaning that, in the example below, the action of the link in the line 10 can not see the media m1, and the action of the line 18 neither.

context c1
   media m1
      src: "medias/image1.jpg"
   end
end

context c2
   media m2
      src: "medias/image2.jpg"
   end
   onBegin m2 do
      start m1 end
   end
end

media m3
   src: "medias/image3.jpg"
end

onBegin m3 do
   start m1 end
end

Region Element

The region element defines the initial values of the region of the screen where the media element will appear.

Region = "region" * Id * (Comentario + Region + Propriedade + MacroCall)^0 * "end"

On the example below,

port pBody1 media1
port pBody2 media2

region rgFullScreen
   width: 100%
   height: 100%
   region rgMidScreen
      width: 50%
      height: 50%
      bottom: 25%
      right: 25%
   end
end

media media1
   rg: rgFullScreen
   src: "medias/image1.jpg"
end

media media2
   rg: rgMidScreen
   src: "medias/image2.jpg"
end

Switch Element

Macro Element

The macro element is

Macro = "macro" Id * (Comentario * MacroCall * Propriedade + Media + Area + Context + Link + Port + Region)^0 * "end"

It behaves like the standard definition of macro, it replaces the words of what it receives as an argument:

macro macro1 (mName, mSource)
   media mName
      src: mSource
   end
end

*macro1("media1", "medias/image1.png")

The example above creates the one shown below. Note that, even if the argument is passed as a string “media1”, when the macro is resolved, it don’t become a string, since it is an Id.

media media1
   src: "medias/image1.png"
end

Macro can contain other macros, and call other macros inside of them, however, recursion is not allowed (it can not call itself, its parent macros or macros that are declared after itself).

macro macro1()
   *macro3() -- NOT ALLOWED, macro3 is declared after
   macro macro2()
      *macro1() -- NOT ALLOWED, macro1 is the parent of macro2
      macro macro3()
         *macro1() -- NOT ALLOWED EITHER
      end
   end
   *macro1() -- NOT ALLOWED, macro1 can not call itself
end

macro macro4()
end

macro macro5()
   *macro4() -- ALLOWED
end

sNCL by Example

The applications used in the tutorial and the media content can be found in sNCL Tutorials

Example 1: Hello world

This first example shows a simple multimedia application, that only shows one image. It consists of a port element and a media element.

Example 2: Playing a video and an image

TODO.

Example 3: Playing a video in loop

In this example,

Exemplo 4: Slideshow (macros)

Example 5: Slideshow with buttons (macros)

TODO

Exemplo 6: Allen’s operators (macros)

Todo

Seria interessante colocar uma introdução sobre o que são os operadores de Allen.

Precedes e Preceded By

A media1 acontece antes da media2, ou a media2 é precedida pela media1.

macro precedes (A, B, delay)
  onBegin A do
    start B
      delay: delay
    end
  end
end

media media1
   src: "media2.mp4"
end

media media2
  src: "media2.mp4"
end

precedes(media1, media2)

Meets e Met By

A media1 encontra a media2

macro meets (A, B)
  onEnd A do
    start B end
  end
end

media media1
  src: "media2.mp4"
end

media media2
  src: "media2.mp4"
end

meets (media1, media2)

Overlaps e Overlapped By

A media1 sobrepõe a media2

TODO.

Starts e Started By

A media1 começa a media2, ou a media2 é começada pela media1.

macro starts (A, B)
  onBegin A do
    start B end
  end
end

media media1
  src: "media1.mp4"
end

media media2
  src: "media2.mp4"
end

starts (media1, media2)

During e Contains

A media1 acontece durante a media2, ou a media2 contém a media1.

TODO.

Finishes e Finished By

A media1 acaba a media 2, ou a media2 é acabada pela media1.

macro finishes (A, B)
  onEnd A do
    stop B end
  end
end

media media1
  src: "media1.mp4"
end

media media2
  src: "media2.mp4"
end

finishes (media1, media2)

Equals

A duração de ambas as mídias são iguais.

macro equals (A, B)
  onBegin A do
    start B end
  end
  onEnd A do
    stop B end
  end
end

media media1
  src: "media1.mp4"
end

media media2
  src: "media2.mp4"
end

equals (media1, media2)

sNCL full grammar specification

This page presents the grammar of the language. It follows the specification used in LPeg, the tool used in the compiler for grammar especification.

An “+” between elements means an or, an “*” means an and.

“(“ and “)” group elements together, and the repetition of the group, or of a single element, is represented using the “^” operator, “^1” means one or more, “^0” means 0 or more, and “^-1” means one or none.

Elements between “” are literals, the others are non-terminal.

Start = (Comentario + Context + Media + Area + Port + Region + Link + Macro)^0

Comentario = "--" * (AlphaNumeric + Punctuation)^0
Propriedade = AlphaNumeric * ":" * (String + AlphaNumeric)

Context = "context" * Id * (Comentario + Port + Propriedade + Media + Context + Link + MacroCall)^0 * "end"

Media = "media" * Id *(Comentario + MacroCall + Area + Propriedade)^0 * end

Area = "area" * Id * (Comentario + Propriedade)^0 * "end"

Port = "port" * Id * AlphaNumeric

Region = "region" * Id * (Comentario + Region + Propriedade + MacroCall)^0 * "end"

Link = Condition^1 * (Comentario + Propriedade + Action)^0 * end

Condition = AlphaNumeric * Id * TermCond
TermCond = ("and" * Condition) + ("do")

Action = AlphaNumeric * Id * (Comentario + Propriedade) * "end"

Macro = "macro" Id * (Comentario * MacroCall * Propriedade + Media + Area + Context + Link + Port + Region)^0 * "end"

MacroCall = "*" * AlphaNumeric * "(" * Params^-1 * ")"

Params = AlphaNumeric * ("," * AlphaNumeric)^0

sNCL vs. NCL

Todo

Copiar a tabela de completude para cá.

TODO

TODO (Documentação)

Todo

Explain context, and access to elements inside of the context

original entry

Todo

Seria interessante colocar uma introdução sobre o que são os operadores de Allen.

original entry

Todo

How to install cloning the github repo

original entry

Todo

How to install on Windows and MacOS?

original entry

Todo

Add some instructions on how to run an sncl program.

original entry

Todo

Adicionar os exemplos do Garrincha

original entry

Todo

Copiar a tabela de completude para cá.

original entry

Todo

Adicionar os exemplos do Garrincha

Indices and tables

• Index
• Module Index
• Search Page