Create broadcast graphics using Node.js and a browser
NodeCG is a broadcast graphics framework and application. It enables you to write complex, dynamic broadcast graphics using the web platform. NodeCG has no graphics or drawing primitives of its own. Instead, NodeCG provides a structure for your code and an API to facilitate moving data between the dashboard, the server, and your graphics. It makes no assumptions about how to best code a graphic, and gives you complete freedom to use whatever libraries, frameworks, tools, and methodologies you want. As such, NodeCG graphics can be rendered in any environment that can render HTML, including:
- OBS Studio (via the obs-browser plugin)
- CasparCG (v2.2.0 test builds only, at this time)
Don't see your preferred streaming software on this list? NodeCG graphics require Chrome 49 or newer. If your streaming software's implementation of browser source uses a build of CEF that is based on at least Chrome 49, chances are that NodeCG graphics will work in it. You can check what version of Chrome your streaming software uses for its browser sources by opening whatversion.net/chrome as a browser source.
Looking for a list of NodeCG bundles and resources? Check out awesome-nodecg.
Have questions about NodeCG, or just want to say 'hi'? Join our Discord server!
Who should use NodeCG?
Table of Contents
- Concepts and Terminology
Then, run the following commands from a terminal (command prompt):
git clone https://github.com/nodecg/nodecg.git cd nodecg npm install --production node index.js
Looking to get started developing bundles? Check out the Quick Start tutorial.
To run NodeCG in production, pm2 is recommended.
NodeCG's individual graphics packages are called bundles. They can be installed either from the command-line
(via nodecg-cli), or by simply placing the folder into the
(Once you have nodecg-cli installed) To install a bundle from Github, enter the owner and repository name:
nodecg install lange/lange-notify
... to install a bundle from Bitbucket, enter the owner and repository name prefixed with
nodecg install bitbucket:username/repo-name
... to install a bundle from any other git provider, enter the git URL:
nodecg install https://gitlab.com/username/repo-name.git
Bundles are just directories inside the
They can always be added and removed by simply moving them into or out of that folder.
Avoid installing or uninstalling bundles while NodeCG is running.
- Install a bundle to the
- Start NodeCG (
nodecg startif you have nodecg-cli installed).
- Open the dashboard (
- Open a graphic from the "Graphics" menu.
- You can configure NodeCG by creating and editing cfg/nodecg.json.
./cfg/nodecg.json is an optional file that you can create to configure NodeCG.
See the NodeCG Configuration tutorial for more information on configuring NodeCG.
Each NodeCG graphic is called a bundle. A bundle has one or more of the following:
- Graphics: Visual elements to render and broadcast.
- Dashboard Panels: Controls used to manipulate and manage the bundle.
- Extension: Server-side code.
A bundle can have multiple graphics and dashboard panels, and an extension can be split up into multiple files.
If you wish to quickly start a new bundle from a template, check out the Quick Start tutorial.
Concepts and Terminology
A breakdown of the terminology and concepts used inside NodeCG can be found here, on the NodeCG website.
The NodeCG project exists to accomplish the following goals:
- Make broadcast graphics (also known as "character generation" or "CG") more accessible.
- Remain as close to the web platform as possible.
- Support broadcasts of any size and ambition.
Let's unpack what these statements mean:
> Make broadcast graphics (also known as "character generation" or "CG") more accessible.
Historically, broadcast graphics have been expensive. They either required expensive hardware, expensive software, or both. NodeCG was originally created to provide real-time broadcast graphics for Tip of the Hats, which is an all-volunteer charity fundraiser that had a budget of $0 for its first several years.
Now, it is possible to create an ambitious broadcast using entirely free software and consumer hardware. The NodeCG project embraces this democratization of broadcast technology.
> Remain as close to the web platform as possible.
NodeCG graphics are just webpages. There is absolutely nothing special or unique about them. This is their greatest strength.
By building on the web platform, and not building too many abstractions on top of it, people developing broadcast graphics with NodeCG have access to the raw potential of the web. New APIs and capabilities are continually being added to the web platform, and NodeCG developers should have access to the entirety of what the web can offer.
> Support broadcasts of any size and ambition.
NodeCG's roots are in small broadcasts with no budget. More recently, NodeCG has begun seeing use in increasingly elaborate productions. We believe that one set of tools can and should be able to scale up from the smallest show all the way to the biggest fathomable show. Whether you're using OBS for everything, or a hardware switcher with a traditional key/fill workflow, NodeCG can be a part of any broadcast graphics system.
- Atmo, original dashboard concept and code, the inspiration for toth-overlay
- Alex "Lange" Van Camp, designer & developer of toth-overlay, the base on which NodeCG was built
Please contribute! This is an open source project. If you would like to report a bug or suggest a feature, open an issue. Or, to open a Pull Request:
- Fork it (http://github.com/nodecg/nodecg/fork)
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create a new Pull Request
Note: Make sure you run
npm install in the root directory without the
--production flag to ensure all
devDependencies are installed.
Before creating your pull request:
- Ensure your code matches our existing style using our provided EditorConfig options.
- Ensure the existing tests pass, or are updated appropriately, with
- For new features, you should add new tests.
Building and viewing the docs locally
Documentation contributions are always welcome and very appreciated!
NodeCG's documentation site, nodecg.com, is automatically generated based on NodeCG's JSDoc comments and the markdown files in the
tutorials folder. The table of contents in this README is also automatically generated.
To build the docs, run the following commands (after you have cloned NodeCG and installed its dependencies via
npm run docs:build
After that, you can open
docs/index.html directly in your web browser.
Once you've made your changes, follow the steps above in the Contribute section to open a pull request.
Running tests locally
You no longer need Selenium to run browser integration tests. Chromium is installed with
npm ci, and that's all required for tests.
Then just run
Code of Conduct
Note that all contributions and discussions around NodeCG take place under our Code of Conduct.