Have more questions? Submit a request

How to build your own SMIL Player from source code

If you need to adjust the signageOS SMIL Player behavior or just change the background to match your branding, here is a guide how to build your own version (fork) of the signageOS SMIL Player from source code.


  • signageOS Account
  • created Organization in Box (create one here)
  • Node.js >= 10.15.0, <17
  • NPM
  • a shell/terminal environment (like bash, zsh, powershell...)
  • a source-code editor (like VSCode, Sublime, WebStorm...)

1. Create an Applet

  1. First, navigate to signageOS Box -> Applets -> New Applet
  2. Create a new Applet
  3. Once created, get the Applet UID, we will need it later in the process in Step 5

2. Clone signageOS SMIL Player repository

In your favorite terminal, use the following commands:

git clone https://github.com/signageos/smil-player.git
cd ./smil-player

SignageOS SMIL Player Repository

3. Install signageOS CLI and additional libraries

npm install @signageos/cli@latest -g
npm i -SE @signageos/front-display
npm i -SE @signageos/front-applet

This guide is similar to How to use signageOS with existing application, but tailored for SMIL Player repository. If you want to learn more, check the article.

Initiate signageOS CLI and login

// login with signageOS Account, follow the guide in the terminal
sos login

// select your Organization under which you generated your Applet in the step 1
sos organization set-default

4. Build the project and test it locally

npm install && npm run prepare

sos applet start --applet-dir dist --entry-file-path dist/index.html

Now you should be able to open up your web browser on http://Your-IP-Address:8090 and see the project running. Do your changes, if necessary, and continue with the next step.

5. Login to signageOS CLI and upload your version to signageOS

Adjust package.json file

  1. Open up package.json file in the root folder of the project
  2. Check the 5th line main and make sure there is dist/index.html
  3. Change the appletUid to YOUR Applet UID from the Step 1

Upload to signageOS

// build the project
npm run build-prod

// upload to signageOS
sos applet upload --entry-file-path dist/index.html

If you will get 50x error in the CLI, simply retry the command.

6. Deploy your new SMIL Player Applet to any device

From this point on, you can deploy your new SMIL Player Applet to any device via Timing, or simply build your own Core Apps.

If you are using Timing to deploy your SMIL Player, you can add Timing Configuration smilUrl and as a value pass link to your SMIL playlist. By doing so, the SMIL playlist will be persistent throughout the reboots. And, of course, you can change it from Box anytime in the future.


To be able to deploy your SMIL Player via Timing from Box, you need at least the following version of signageOS Core App installed on your device:

Platform Core App Min. Version
Android 3.3.0
BrightSign 1.2.0
LG webOS 2.2.0
Tizen 2.1.0
RaspberryPi 1.2.0

7. SMIL Player Configuration

You can further configure certain parameters of the SMIL Player using Timing Configuration. Here is the list of built-in options:

  • smilUrl is used for passing URL of the smil file, no default
  • backupImageUrl is used for defining a failover image that will be shown in case the smil file is corrupted or fatal error occurs during playback, default built-in image
  • serialPortDevice is used for defining custom device address used for serial communication (like Nexmosphere sensors), default is /device/ttyUSB0
  • videoBackground this value accepts True and False values, resulting in a video content playing in the background



To get logs from the SMIL Player runtime, add the following record to your browser Local Storage where you are testing SMIL Player:

// Enable debug logs for SMIL Player
localStorage.setItem("debug", "@signageos/smil-player:*");

// Once the debugging is over, disable the logs

In Chrome, press F12 on an active Emulator window. This will open up a Chrome debugger. In the debugger navigate into the Console tab and paste there the two lines of code above. Once done, refresh the Emulator window.

If your want to debug on devices, enable Native debug to access device debug console and apply the code there.

Enabling debug logs might affect device performance for certain tasks. Never keeps debug logs enabled on production device.


CORS settings while developing on Emulator

If you run into issues while developing SMIL Player within Emulator, make sure you add https://2.signageos.io into the whitelisted domains on your server.

Videos are not playing in background

The possibility to play videos in background is currently under review. As of now, you can workaround the missing layering by force all videos to run in background.

  1. Open the parameters.ts file
  2. Change background: false to background: true https://github.com/signageos/smil-player/blob/master/config/parameters.ts#L6
  3. Build and upload this adjusted version

Known limitations:

  • you cannot layer videos


Was this article helpful?
0 out of 0 found this helpful