en:docs:tutorial

Getting Started with NCL Composer

2017-02-03T16:31:18-03:00

This page is a draft!!

Getting Started with NCL Composer

This document presents a very fast introduction that allows you to start the development of interactive applications for digital TV using NCL Composer.

Here, we consider that you already have a NCL Composer installation working. If not, please go to download page, get the latest version of NCL Composer and install it.

First steps

1. Creating a new project

When you start NCL Composer the following screen is presented to you. In order to create a new project, click New Project button or go to File→New Project.

TODO: Printscreen.

TODO: What? Where? How? When?

2. What? Adding media objects

After created a new project you will be presented to the various Views of NCL Composer. Each view allows you to focus on a specific task while creating your application.

For example, let's start adding our media objects. For that you can go to Structural View and click with right button on the canvas area and then Insert→Media. You can also drag your media files from your file system and drop in the Structural View drawing area.

3. Where? Creating regions

TODO: All

4. How? Working with properties or descriptors

TODO: All

5. When? Links

TODO: All

How to: build NCL Composer from source code

2017-02-03T16:31:18-03:00

How to: build NCL Composer from source code

For previous versions (<= 0.1.x) go to: How to build NCL Composer from source code (<= 0.1.x) tutorial.

Requirements

Git (>= 1.7.x) http://git-scm.com/
Qt (>=4.7.x) http://qt.nokia.com/downloads/

Getting Source Code

About Git (from sourceforge.net)

Git is a Source Code Management (SCM) tool for software developers which supports collaborative development of software within a team, and the tracking of changes to software source code over time.

Git is used by developers, and advanced users who need the very latest changes to the software (before releases occur). Software users generally do not need Git; typically they will download official file releases made available by the project instead.

Developers should familiarize themselves with Git by reading the Git Documentation.

NCL Composer's Git access

From command line, you just need to execute the following to get the NCL Composer source code:

$ git clone http://git.telemidia.puc-rio.br/nclcomposer.git

Compiling Source Code

From command line, you just need to execute the following lines to compile the NCL Composer:

$ qmake
$ make install

If you are compiling on Windows, you probably must change 'make' to:

$ mingw32-make

and 'make install' to:

$ mingw32-make install

If you are compiling on Debian (or Ubuntu, or Linux Mint, etc.), you probably must change 'make install' to:

$ sudo make install

If you are compiling on MAC, you probably must change 'qmake' to

$ qmake -spec macx-g++

and 'make install' to:

$ sudo make install

Compiling with "Remote Run" feature

By default, you will not compile NCL Composer with “Remote Run” support. We do this in order to not include the libssh2 dependencies inside our source code. However, if you want to use that feature, you must to follow these steps, before compiling composer-gui subproject:

1. Get LIBSSH2 related libraries:

On Ubuntu/Debian you can install these dependencies through:

$ sudo apt-get install libssh2-1-dev libgcrypt11-dev

On Windows you can download them from:

http://composer.telemidia.puc-rio.br/downloads/deps/nclcomposer-gui-0.1.1-deps.zip

and uncompress that file inside src/gui directory. you should finish with something like that (see the to libssh folder):

  + src
    + core
        ...
    + gui
      + data
      + deps
        + libssh2-1.3.0
      + images
      + src
      + translations
         ...
    + plugins
        ...

On Mac OS X you need first to install a software called port (http://www.macports.org/) , which is basically a package management system that simplifies the installation of software on the Mac OS X. Then you can install the dependencies with the following command:

$ sudo port install libssh2 libgcrypt

2. Replace the qmake call above with:

  $ qmake RUNSSHON=true

Testing

In order to test the NCL Composer, you need to execute on:

Windows:

$ C:\composer.exe

Linux

$ /usr/local/bin/composer

MAC OS X

$ open /Applications/Composer.app

Problems ?

If you have problems with any of the previous steps see the FAQ section, and if this does not resolve your problem, contact us.

How to: build NCL Composer from source code (

2017-02-03T16:31:18-03:00

How to: build NCL Composer from source code (<= 0.1.x)

For newer versions (>= 0.2.x) go to: How to build NCL Composer from source code (>= 0.2.x) tutorial.

Requirements

Git (>= 1.7.x) http://git-scm.com/
Qt (>=4.7.x) http://qt.nokia.com/downloads/

Getting Source Code

About Git (from sourceforge.net)

Git is a Source Code Management (SCM) tool for software developers which supports collaborative development of software within a team, and the tracking of changes to software source code over time.

Developers should familiarize themselves with Git by reading the Git Documentation.

NCL Composer's Git access

From command line, you just need to execute the following to get the NCL Composer source code:

$ git clone http://git.telemidia.puc-rio.br/composer-core.git
$ git clone http://git.telemidia.puc-rio.br/composer-gui.git
$ git clone http://git.telemidia.puc-rio.br/composer-plugins.git

Compiling Source Code

From command line, you just need to execute the following lines, for each directory created above, to compile the NCL Composer:

$ qmake
$ make
$ make install

If you are compiling on Windows, you probably must change 'make' to:

$ mingw32-make

and 'make install' to:

$ mingw32-make install

If you are compiling on Debian (or Ubuntu, or Linux Mint, etc.), you probably must change 'make install' to:

$ sudo make install

Additionally, in some new Ubuntu and Mint versions, you probably must change 'qmake' to:

$ qmake-qt4

This last one, is because NCL Composer uses Qt 4.x, and not the new version 5.x, that is not supported in many distro yet.

If you are compiling on MAC, you probably must change 'qmake' to

$ qmake -spec macx-g++

and 'make install' to:

$ sudo make install

Compiling with "Remote Run" feature

1. Get LIBSSH2 related libraries:

On Ubuntu/Debian you can install these dependencies through:

$ sudo apt-get install libssh2-1-dev libgcrypt11-dev

On Windows you can download them from:

http://composer.telemidia.puc-rio.br/downloads/deps/nclcomposer-gui-0.1.1-deps.zip

and uncompress that file inside composer-gui directory. you will have something like that (attetion to libssh folder):

  + composer-core
      ...
  + composer-gui
    + data
    + deps
      + libssh2-1.3.0
    + images
    + include
    + translations
    ...
  + composer-plugins
      ...

$ sudo port install libssh2 libgcrypt

2. Replace the qmake call above with:

  $ qmake RUNSSHON=true

Testing

In order to test the NCL Composer, you need to execute on:

Windows:

$ C:\composer.exe

Linux

$ /usr/local/bin/composer

MAC OS X

$ open /Applications/Composer.app

Problems ?

If you have problems with any of the previous steps see the FAQ section, and if this does not resolve your problem, contact us.

How to configure NCL Composer to run an NCL Application

2017-02-03T16:31:18-03:00

How to configure NCL Composer to run an NCL Application

There are two ways of running your NCL application from NCL Composer:

From a local Ginga-NCL player (e.g. Ginga4Windows); or
From a Virtual Machine (e.g. Ginga Virtual Set-top Box);

Running from local Ginga-NCL

To configure NCL Composer to run the NCL application from the loca Ginga you must select the Menu: Edit→Preferences→Run Configuration.

The following screen will be presented:

In this screen, mark the option Local: Ginga Player and fill the text box Command with the path to the Ginga-NCL binary.

The text box Arguments can be filled with parameters to the Ginga-NCL binary. You mus put each parameter in a different line.

Running from Ginga Virtual Set-top Box

To run your application in the Ginga Virtual Set-top Box choose the option: Remote: Ginga-NCL Virtual Set-top Box.

Usually, the only parameter to be changed is the IP address of the virtual machine. We suggest you do not change the other parameters, unless you know exactly what you are doing

How to Run Applications on Multiple Devices

2017-02-03T16:31:18-03:00

How to Run Applications on Multiple Devices

Ginga-NCL provides support for multimedia applications on multiple devices.
Using NCL Composer you can create and play applications that use secondary devices.

Creating

To play a media on a secondary device you simply put it in a region inside a regionBase with a specified secondary class.

Playing

Clicking the small arrow near the Run NCL Project button you can choose to open instances of Ginga acting as either a secondary active device or a secondary passive device waiting for the primary device.

After choosing Passive or Active some extra information will be asked (like the number of secondary devices) . After pressing Ok the window(s) representing the secondary devices will appear and wait for content.

Then you can click Run NCL Project to execute and the content for secondary devices will be visible when the application playback demands it.

Extra options

In Edit→Preferences→Run Configuration it is possible to add or change parameters to the Ginga-NCL binary in the Arguments box.

How to: Create an NCL Composer Plugin

2017-02-03T16:31:18-03:00

How to: Create an NCL Composer Plugin

This page is a draft

This tutorial assumes you are familiar with C/C++ programming languages and have basic knowledge about Qt framework (mainly the qmake build system and signals & slots mechanism).

What is a Plugin?

A plugin is a piece of software distributed separated from other software (the main or host) aiming to extend its functionalities. In order to allow extensions and customizations NCL Composer architecture is based on plugins.

A common way to extend the NCL Composer functionalities is creating new Views to documents being developed. A View is a plugin that brings out a representation of this document (e.g. showing its entities in a tree, or showing how this document is represented in a timeline, etc.).

NCL Composer Plugins

An NCL Composer plugins is based on two main C++ interfaces that must to be implemented: IPluginFactory and IPlugin.

IPluginFactory

The IPluginFactory is responsible to create new instances of IPlugin's, and keep global informations about the plugin, like its vendor, version, etc. Every time a document is open, the NCL Composer will try to create a new instance of the plugin calling IPluginFactory's method. But if your plugin is a singleton, you can always returns the same instance.

IPlugin

The IPlugin is the NCL Composer plugin itself. When a document is open by NCL Composer, a new instance of the plugin will be required by NCL Composer. The IPlugin is linked with the Document instance and will be called every time this document is changed. Likewise, the IPlugin is also able to require changes in the Document.

An example: Debug Plugin

As a simple example, let's create a Debug Plugin. This plugin will print all the messages that it receives from NCL Composer core.

First of all, let's create our DebugConsolePlugin.h:

#ifndef DEBUGCONSOLEPLUGIN_H
#define DEBUGCONSOLEPLUGIN_H
 
#include <QObject>
#include <core/extensions/IPlugin.h>
 
using namespace composer::core::extension::plugin;
 
class DebugConsolePlugin : public IPlugin
{
        Q_OBJECT
    private:
        QWidget *window;
 
    public:
        explicit DebugConsolePlugin();
        ~DebugConsolePlugin();
 
        QWidget* getWidget();
	bool init();
 
    public slots:
        void onEntityAdded(QString ID, Entity *);
        void onEntityChanged(QString ID, Entity *);
        void onEntityRemoved(QString ID, QString entityID);
 
        void errorMessage(QString error);
};
 
#endif // DEBUGCONSOLEPLUGIN_H

And the DebugConsole.cpp:

#include "DebugConsolePlugin.h"
 
DebugConsolePlugin::DebugConsolePlugin()
{
  // Do nothing
}
 
DebugConsolePlugin::~DebugConsolePlugin()
{
  // Do nothing
}
 
void DebugConsolePlugin::init()
{
  // Do nothing
}
 
QWidget* DebugConsolePlugin::getWidget()
{
    return NULL; /*This tell to NCL Composer that our plugin doesn't have a GUI*/
}
 
void DebugConsolePlugin::onEntityAdded(QString ID, Entity *entity)
{
    QString line = "PLUGIN (" + ID + ") added the Entity (" +
                   entity->getType() + " - " + entity->getUniqueId() +")";
    qDebug() << line;
}
 
void DebugConsolePlugin::errorMessage(QString error)
{
    qDebug() << "ERROR:" << error;
}
 
void DebugConsolePlugin::onEntityChanged(QString ID, Entity * entity)
{
    QString line = "PLUGIN (" + ID + ") changed the Entity (" +
                    entity->getType() + " - " + entity->getUniqueId() +")";
    qDebug() << line;
}
 
void DebugConsolePlugin::onEntityRemoved(QString ID, QString entityID)
{
    QString line = "PLUGIN (" + ID + ") removed Entity (" +
                   entityID + ")";
    qDebug() << line;
}

In order to NCL Composer know how to create new instances of our DebugPlugin, we have to provide a Factory class:

#ifndef DEBUGCONSOLE_H
#define DEBUGCONSOLE_H
 
#include "DebugConsole_global.h"
#include "DebugConsolePlugin.h"
 
#include <core/extensions/IPluginFactory.h>
using namespace composer::extension;
 
class DebugConsoleFactory : public QObject,
                            public IPluginFactory
{
    Q_OBJECT
    Q_INTERFACES(IPluginFactory)
 
    public:
         DebugConsoleFactory();
         ~DebugConsoleFactory();
         IPlugin* createPluginInstance();
         void releasePluginInstance(IPlugin *);
 
         /* Global information about DebugPlugin. */
         QString id() const {return "br.puc-rio.telemidia.DebugPlugin";};
         QString name() const {return "Debug Plugin";};
 
         QString version() { return "0.1"; }
         QString compatVersion() {return "0.1";}
         QString vendor() {return "Telemidia Lab";}
         QString copyright() {return "Telemidia/PUC-Rio";}
         QString description() {return "Debug Console View prints all the messages send by NCL Composer to plugins.";}
         QString url() {return "http://composer.telemidia.puc-rio.br/debug";}
         QString category() {return "Debug";}
 
};

#include "DebugConsoleFactory.h"
 
namespace composer {
    namespace plugin {
        namespace debug {
 
DebugConsoleFactory::DebugConsoleFactory()
{
  //Do nothing
}
 
DebugConsoleFactory::~DebugConsoleFactory()
{
  //Do nothing
}
 
IPlugin* DebugConsoleFactory::createPluginInstance()
{
    return new DebugConsolePlugin();
}
 
void DebugConsoleFactory::releasePluginInstance(IPlugin *plugin)
{
    DebugConsolePlugin *debug = qobject_cast<DebugConsolePlugin*>(plugin);
 
    if (debug)
    {
        delete debug;
        debug = NULL;
    }
 
}
 
// This is very important, and will allow to Qt framework recognize your
// plugin
Q_EXPORT_PLUGIN2(DebugConsole,DebugConsoleFactory)
 
} } } //end namespace

How to: Create an NCL Composer Plugin

2017-02-03T16:31:18-03:00

How to: Create an NCL Composer Plugin

This page is a draft

This page describe NCL Composer plug-in API since version 0.2.x. If you are looking this tutorial for a previous version, please look at this page.

This tutorial assumes you are familiar with C/C++ programming languages and have basic knowledge about Qt framework (mainly the qmake build system and signals & slots mechanism).

What is a Plugin?

NCL Composer Plugins

Since version 0.2.x NCL Composer plugins are based on Qt5 plug-in system. A plug-in is composed of one C++ interface (IPlug-in) implementation and a .json file that describe this plug-in.

An example: Debug Plugin

As a simple example, let's create a Debug Plugin. This plugin will print all the messages that it receives from NCL Composer core.

First of all, let's create our DebugConsolePlugin.h:

#ifndef DEBUGCONSOLEPLUGIN_H
#define DEBUGCONSOLEPLUGIN_H
 
#include <QObject>
 
#include <core/extensions/IPlugin.h>
using namespace composer::extension;
 
class DebugConsolePlugin : public IPlugin
{
  Q_OBJECT
 
private:
  QWidget *window;
public:
  explicit DebugConsolePlugin();
  ~DebugConsolePlugin();
 
  void init();
  QWidget* getWidget();
 
public slots:
  void onEntityAdded(QString pluginID, Entity *);
  void onEntityChanged(QString pluginID, Entity *);
  void onEntityRemoved(QString pluginID, QString entityID);
 
  void errorMessage(QString error);
};
 
#endif // DEBUGCONSOLEPLUGIN_H

And the DebugConsole.cpp:

#include "DebugConsolePlugin.h"
 
DebugConsolePlugin::DebugConsolePlugin()
{
  // Do nothing
}
 
DebugConsolePlugin::~DebugConsolePlugin()
{
  // Do nothing
}
 
void DebugConsolePlugin::init()
{
  qDebug() << "DEBUG MESSAGE:IT STARTED" ;
}
 
QWidget* DebugConsolePlugin::getWidget()
{
    return NULL;/*No window to return,
  This tells to NCL Composer that our plugin doesn't have a GUI*/
}
 
void DebugConsolePlugin::onEntityAdded(QString pluginID, Entity *entity)
{
  QString line = "DEBUG MESSAGE:PLUGIN (" + pluginID + ") added the Entity (" +
      entity->getType() + " - " + entity->getUniqueId() +")";
  qDebug() << line;
}
 
void DebugConsolePlugin::errorMessage(QString error)
{
  qDebug() << "DEBUG MESSAGE:ERROR - " << error;
}
 
void DebugConsolePlugin::onEntityChanged(QString pluginID, Entity * entity)
{
  QString line = "DEBUG MESSAGE: PLUGIN (" + pluginID + ") changed the Entity (" +
      entity->getType() + " - " + entity->getUniqueId() +")";
  qDebug() << line;
}
 
void DebugConsolePlugin::onEntityRemoved(QString pluginID, QString entityID)
{
  QString line = "DEBUG MESSAGE: (" + pluginID + ") removed Entity (" +
      entityID + ")";
  qDebug() << line ;
}

In order to NCL Composer know how to create new instances of our DebugPlugin, we have to provide a Factory class: a DebugConsoleFactory.h

#ifndef DEBUGCONSOLE_H
#define DEBUGCONSOLE_H
 
#include "DebugConsole_global.h"
#include "DebugConsolePlugin.h"
 
#include <core/extensions/IPluginFactory.h>
using namespace composer::extension;
 
class DebugConsoleFactory : public QObject,
    public IPluginFactory
{
  Q_OBJECT
  Q_INTERFACES(IPluginFactory)
 
#if QT_VERSION >= 0x050000
  Q_PLUGIN_METADATA(IID IPluginFactory_iid FILE "DebugConsole.json")
#endif
 
public:
  DebugConsoleFactory();
  ~DebugConsoleFactory();
  IPlugin* createPluginInstance();
  void releasePluginInstance(IPlugin *);
  QList<LanguageType> getSupportedLanguages();
  QString id() const ;
  QIcon icon() const;
  QWidget* getPreferencePageWidget();
 
#if QT_VERSION < 0x050000
  QString name() { return tr("Debug Console"); }
  QString version() { return NCLCOMPOSER_PLUGINS_VERSION; }
  QString compatVersion() {return "0.1";}
  QString vendor() {return "Telemidia Lab";}
  QString copyright() {return "Telemidia/PUC-Rio";}
  QString license() {return "LGPL";}
  QString description() {return tr("Debug Console View prints all the "
                                   " messages send by composer-core to plugins.");}
  QString url() {return "http://composer.telemidia.puc-rio.br/debug";}
  QString category() {return tr("General");}
#endif
 
};
#endif // DEBUGCONSOLE_H

and its DebugConsoleFactory.cpp

#include "DebugConsoleFactory.h"
 
DebugConsoleFactory::DebugConsoleFactory()
{
  //Do nothing
}
 
DebugConsoleFactory::~DebugConsoleFactory()
{
  //Do nothing
}
 
IPlugin* DebugConsoleFactory::createPluginInstance()
{
  return new DebugConsolePlugin();
}
 
void DebugConsoleFactory::releasePluginInstance(IPlugin *plugin)
{
  DebugConsolePlugin *debug = qobject_cast<DebugConsolePlugin*>(plugin);
  if (debug)
    {
      delete debug;
      debug = NULL;
    }
}
 
QList<LanguageType> DebugConsoleFactory::getSupportedLanguages()
{
  QList<LanguageType> lTypes;
  lTypes.append(NCL);
  return lTypes;
}
 
QString DebugConsoleFactory::id() const
{
  return "br.puc-rio.telemidia.DebugConsole";
}
 
QIcon DebugConsoleFactory::icon()  const
{
  return QIcon(":/images/icon.png");
}
 
QWidget* DebugConsoleFactory::getPreferencePageWidget()
{
  return NULL;
}
#if QT_VERSION < 0x050000
Q_EXPORT_PLUGIN2(DebugConsole,DebugConsoleFactory)
#endif

the DebugConsole_global.h used by the factory file:

#ifndef DEBUGCONSOLE_GLOBAL_H
#define DEBUGCONSOLE_GLOBAL_H
 
#include <QtCore/qglobal.h>
 
#if defined(DEBUGCONSOLE_LIBRARY)
#  define DEBUGCONSOLESHARED_EXPORT Q_DECL_EXPORT
#else
#  define DEBUGCONSOLESHARED_EXPORT Q_DECL_IMPORT
#endif
 
#endif // DEBUGCONSOLE_GLOBAL_H

Additionally, you will also need to define the debugplugin.json file describing your plug-in:

{
  "name" : "Debug Console Plug-in",
  "version" : "0.2.0",
  "compatVersion" : "0.2.0",
  "vendor" : "TeleMidia Lab",
  "description" : "Debug Console View prints all the messages sent by NCL Composer to plugins.",
  "url" : "http://composer.telemidia.puc-rio.br/plugin/debug",
  "category" : "Debug"  
  "dependencies" : []
}

Check List for Release NCL Composer

2017-02-03T16:31:18-03:00

Check List for Release NCL Composer

Change version inside .pro files
Update translations
Check update message id
Tag source
Release source
Release Win32 version (zip)
Release Win32 version (Installer)
Release Linux version (deb)
Release MacOS version (dmg)
Update download page (en)
Update download page (pt-br)
Create a new blog post (Blog)

Tutorials

2017-02-03T16:31:18-03:00

Tutorials

For Users

For Developers

NCL Composer Architecture Overview

2017-02-03T16:31:18-03:00

NCL Composer Architecture Overview

A complete description of NCL Composer architecture can be found in the MTAP paper below.