@iimrd/hbbtv

A TypeScript implementation of the HbbTV 2.0 Companion Screen components, forked from the original node-hbbtv project by Fraunhofer FOKUS.

• HbbTV App Launch: Launching a Companion Screen application from an HbbTV application
• CS App Launch: Launching a broadcast-independent HbbTV application on an HbbTV terminal from a Companion Screen application
• App2App Communication: Exchange text and binary messages between HbbTV and Companion Screen applications

Please refer to the HbbTV 2.0 spec document for more details, especially the Companion Screen related sections 8.2.6 and 14.

Requirements

• Node.js >= 18
• npm (included with Node.js)

Setup

Install globally (CLI usage)

npm install @iimrd/hbbtv -g

After installation the hbbtv command will be available (see Usage).

Install locally

npm install @iimrd/hbbtv

Or clone this repository and install dependencies:

git clone https://github.com/IIMrd/node-hbbtv.git
cd node-hbbtv
npm install
npm run build

Use as a library

Add @iimrd/hbbtv to your project:

npm install @iimrd/hbbtv

import { HbbTVDialClient, WebSocket } from "@iimrd/hbbtv";

See the API Documentation section for available exports.

Usage

The module can be started as an HbbTV Terminal (terminal mode) or as a Companion Screen (cs mode):

Terminal mode

Your machine will act as an HbbTV 2.0 CS-compliant Terminal. You can use any HbbTV DIAL client to launch HbbTV applications and any WebSocket client for App2App communication.

# globally installed
hbbtv -m terminal -p 8080

# locally installed / from source
node bin/index.js -m terminal -p 8080

Companion Screen mode

Your machine will act as a companion screen running a CSLauncher and HbbTV DIAL Client. The HbbTV Terminal started in the previous step will be able to discover companion screens and launch CS applications.

Since the discovery and communication between HbbTV terminals and CSLaunchers is not part of the HbbTV 2.0 Spec, the DIAL protocol is also used here to discover CSLaunchers and launch CS Applications. The CSLauncher acts as a DIAL Server offering a non-stoppable DIAL application called Famium (registered in the DIAL registry).

# globally installed
hbbtv -m cs -p 8090

# locally installed / from source
node bin/index.js -m cs -p 8090

Help

hbbtv -h

Examples

Quick Start

1. Start in terminal mode: hbbtv -m terminal -p 8080

2. Start in cs mode (same or different device): hbbtv -m cs -p 8090

   Both modes can run on the same device on different ports, but for best results use two devices on the same network.

3. Open the CS Web App in a browser: http://fraunhoferfokus.github.io/node-hbbtv/www/cs-app.html#port=8090

4. Follow the in-app instructions to discover the HbbTV Terminal, launch an HbbTV App, and open a WebSocket App2App channel.

Node.js Client

The module can be used programmatically to discover HbbTV terminals, launch applications, and create App2App connections:

import { HbbTVDialClient, WebSocket } from "@iimrd/hbbtv";

const hbbTVDialClient = new HbbTVDialClient()
    .on("ready", () => {
        console.log("HbbTV DIAL Client is ready");
    })
    .on("found", (terminal) => {
        console.log(`Terminal ${terminal.getFriendlyName()} found`);

        terminal.launchHbbTVApp({
            appUrlBase: "http://example.com/hbbtv-app.html",
            appLocation: "?channel=mychannel",
        }, (launchRes, err) => {
            if (err) {
                console.error("Error launching HbbTV App", err);
                return;
            }
            console.log("HbbTV App launched:", launchRes ?? "");

            // Connect to the App2App endpoint
            const ws = new WebSocket(terminal.getApp2AppURL() + "mychannel");
            ws.on("message", (data) => {
                if (data.toString() === "pairingcompleted") {
                    console.log("Pairing complete");
                    ws.send("Hello from Node.js client");
                }
            });
        });
    })
    .on("error", (err) => {
        console.error(err);
    });

hbbTVDialClient.start();

Browser Apps

The www/ directory contains example browser applications:

• HbbTV App (www/hbbtv-app.html): Discovers CSLaunchers, launches CS Web Apps, and communicates via App2App WebSocket.
• CS Web App (www/cs-app.html): Discovers HbbTV Terminals, launches HbbTV Apps, and communicates via App2App WebSocket.

Both apps use the hbbtv-manager-polyfill.js library. Refer to section 8.2.6 of the HbbTV 2.0 Spec for details on the HbbTVCSManager JavaScript API.

Exported Classes

| Export | Description | |---|---| | HbbTVDialServer | DIAL server exposing HbbTV/YouTube/Famium apps | | HbbTVDialClient | DIAL client for discovering HbbTV terminals | | HbbTVApp2AppServer | WebSocket server for App2App communication | | HbbTVCsManager | JSON-RPC WebSocket manager for CS operations | | HbbTVTerminalManager | Thin wrapper around HbbTVCsManager for terminal discovery | | CsLauncherDialServer | DIAL server for CS Launcher mode | | CsLauncherDialClient | DIAL client for discovering CS Launchers | | WebSocket | Re-exported ws WebSocket class |

Development

git clone https://github.com/IIMrd/node-hbbtv.git
cd node-hbbtv
npm install
npm run build        # compile TypeScript → dist/
node bin/index.js -m terminal -p 8080

License

Free for non-commercial use, released under the GNU Lesser General Public License v3.0. See LICENSE.

Credits

Originally developed by Fraunhofer FOKUS — Competence Center Future Applications and Media (FAME).

Forked and maintained by IIMrd.