README
node-vmix
NodeJS vMix API utility to enable easy setup to communicate with vMix instance via TCP socket or HTTP alternatively.
It is recommended to use TCP, however, there is currently not implemented feedback/response. It is possible to implement this yourself if necessary, by analysing the responses, but it is not supported out of the box.
This code previously were found in the vmix-js-utils but are now branched out in its own package to enable usage of the vmix-js-utils to be used in a clean frontend environment (non-NodeJS), and also to give a better experience for the users. Are you looking for vMix utility for your js frontend? Take a look at vmix-js-utils for more info. Both packages are available with npm - see my npm profile.
Purpose
node-vmix consists of two modules - one for TCP connection, one for HTTP. Each can be used on its own, but usually it makes more sense to make it interplay with some of the other modules. The modules are coded as classes, meaning that they are constructed with specific parameters, e.g. that the instanciation of a connection needs a host and a port.
Quick start
const { ConnectionTCP } = require('node-vmix')
const connection = new ConnectionTCP('localhost')
// Listener for xml state data
connection.on('xml', xmlData => {
// Your logic here!
// See example to parse the XML correctly
})
// Listener for tally
connection.on('tally', tally => {
// Your logic here!
})
// Listener for data such as tally
connection.on('data', data => {
// Your logic here!
})
connection.on('connect', () => {
// Request vMix API XML state by sending message 'XML'
connection.send('XML')
// Request vMix tally info by sending message 'TALLY'
connection.send('TALLY')
})
Note: One should check whether the connection is actually established before attempting sending message to the socket.
Documentation
Please visit the documentation here: https://jensstigaard.github.io/node-vmix/.
The documentation includes definition and description of classes and type.
Installation and use
NPM
The utilities are published at npmjs as a package for NodeJS, meaning that you can easily add the utilities as a dependency in your project using npm.
npm install node-vmix --save
# or 'yarn add node-vmix'
In your code the simplest way to import the modules is the following:
const { Connection } = require('node-vmix')
// or ES6 import syntax: import { Connection } from 'node-vmix'
const connection1 = new Connection('localhost')
const connection2 = new Connection('192.168.1.50')
connection1.send({ Function: 'Cut' })
connection2.send({ Function: 'Merge' })
You are also able to import all of the modules as a gathered variable, less elegant way:
const vMix = require('node-vmix')
const connection1 = new vMix.Connection('localhost')
const connection2 = new vMix.Connection('192.168.1.50')
connection1.send({ Function: 'Cut' })
connection2.send({ Function: 'Merge' })
Examples and use
Electron example
Looking for a full blown example project? See the repositories:
- audio-matrix-vmix-electron
- simple-vmix-switcher-electron
- vinproma (vMix Input Progress Monitor App)
These apps are using this library for vMix connection. They are built with ElectronJS and can be compiled for both Windows, Mac or Linux platforms.
Code snippet examples
Here are some basic example of how to use the library
Connection TCP
- Send API commands (functions)
- Read XML API
- Misc
Legacy:
Standalone project / Fork
The code can be cloned and tested as needed from the source code.
Clone repository and go into directory
git clone https://github.com/jensstigaard/node-vmix.git
cd node-vmix
Install dependencies
npm install # or 'yarn'
Compile TypeScript source code to JavaScript
npm install # or 'yarn'
Run tests
npm test # or 'yarn test'
Contribution
You are more than welcome to contribute to the repository. Fork the repo and make a pull request with the changes.
As you can see in the list on the right side, others have done it already!
Roadmap
- TCP command sender: feedback/responses on commands sent
- More tests
- Perhaps more functionality