Create broadcast graphics using Node.js and a browser
JavaScript HTML Other
Latest commit 52a603f Aug 5, 2018
Permalink
Failed to load latest commit information.
.idea feat: add support for zeit pkg builds (#362) Jan 18, 2018
build/src fix(dashboard): also target root html for theme import Aug 5, 2018
bundles Seriously, how do I .gitignore Sep 11, 2014
db Seriously, how do I .gitignore Sep 11, 2014
lib feat(dashboard): implement redesigned graphics tab with refresh butto… Jul 19, 2018
media docs(media): update splash Jul 19, 2018
schemas feat(dashboard): implement redesigned graphics tab with refresh butto… Jul 19, 2018
scripts docs(site): add favicon Aug 28, 2017
src fix(dashboard): also target root html for theme import Aug 5, 2018
test feat(dashboard): implement redesigned graphics tab with refresh butto… Jul 19, 2018
tutorials docs: fix comment syntax Jul 12, 2018
.dockerignore update dockerfile Jun 11, 2017
.editorconfig docs: add minimal documentation for workspaces and fullbleed panels May 23, 2017
.eslintignore refactor: move all client-side files into `src` dir (#284) May 22, 2017
.eslintrc fix(assets): improve appearance of dialogs. refactor back and fronten… Aug 23, 2017
.gitattributes feat(api): add nodecg.bundleGit object (#418) Jul 14, 2018
.gitignore test: improve coverage of graphics lib Jul 9, 2018
.jsdoc.json docs(site): add link to github repo in top right corner Jul 14, 2018
.travis.yml build: remove redundant cache folder Jul 11, 2018
AUTHORS add matt's homepage url to AUTHORS Jan 28, 2015
CHANGELOG.md chore(release): 1.1.3 Aug 5, 2018
CODE_OF_CONDUCT.md add second email to code of conduct May 20, 2017
CONTRIBUTING.md docs(README): note Java requirement for Selenium, remind users to ins… Feb 16, 2018
Dockerfile feat(docker): build images with Node 8 Aug 25, 2017
LICENSE docs(LICENSE): bump year Feb 13, 2018
README.md docs(README): install tweaks Jul 16, 2018
bower.json chore(release): 1.1.3 Aug 5, 2018
gulpfile.js chore(package): update all bower & npm deps Aug 25, 2017
index.js feat: add support for zeit pkg builds (#362) Jan 18, 2018
package-lock.json chore(release): 1.1.3 Aug 5, 2018
package.json chore(release): 1.1.3 Aug 5, 2018
polymer.json perf: implement polymer-build (#286) Jun 7, 2017
selenium-setup.sh test: ditch sauce labs; always use selenium-standalone locally Jul 10, 2018

README.md

NodeCG

NodeCG

Discord Build Status Coverage Status Docker Build Status Twitter

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:

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?

NodeCG is a programming framework. As such, it's most useful to developers capable of creating their own graphics using HTML, CSS, and JavaScript. NodeCG's ecosystem of bundles is quite small. Those expecting to download NodeCG and use off-the-shelf bundles to get a complete stream overlay without writing any code may be disappointed.

Table of Contents

Install

Install Node.js (version 8 or greater) & npm (version 2 or greater).

Then, run the following commands from a terminal (command prompt):

npm install -g bower
git clone https://github.com/nodecg/nodecg.git
cd nodecg
npm install --production
bower install
node index.js

Looking to get started developing bundles? Check out the Quick Start tutorial.

To run NodeCG in production, pm2 is recommended.

Installing bundles

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 ./bundles directory.

The easiest way to install bundles is via the command-line using nodecg-cli. You will need to install nodecg-cli before you can use the nodecg terminal commands.

(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 bitbucket:

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 ./bundles folder. 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.

Usage

  • Install a bundle to the bundles folder.
  • Start NodeCG (node index.js or nodecg start if you have nodecg-cli installed).
  • Open the dashboard (http://localhost:9090 by default).
  • Open a graphic from the "Graphics" menu.
  • You can configure NodeCG by creating and editing cfg/nodecg.json.

Configuration

./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.

Bundles

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.

Maintainers

Designers

Acknowledgements

Contribute

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:

  1. Fork it (http://github.com/nodecg/nodecg/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. 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:

  1. Ensure your code matches our existing style using our provided EditorConfig options.
  2. Ensure the existing tests pass, or are updated appropriately, with npm test.
  3. 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 install):

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

  1. Install selenium-standalone (npm install --global selenium-standalone), then run the installer (selenium-standalone install)
  2. Open one terminal and start Selenium: selenium-standalone start
  3. Open a second terminal, navigate to the NodeCG root and run npm test

Note: Selenium requires Java.

Code of Conduct

Note that all contributions and discussions around NodeCG take place under our Code of Conduct.