Installation for Ubuntu
The following instructions are for Ubuntu 16.04 LTS.
StreamMachine is built using Node.js and has 3 possible running modes:
- standalone
- master
- slave
Both standalone and master/slave modes can be run with or without Redis to store the configuration.
Start with a fully updated environment:
apt-get update
apt-get upgrade
apt-get install -y aptitude
aptitude install -y build-essential gitWe'll need Node.js, npm, git command:
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo aptitude install -y nodejsLet's now deploy the current StreamMachine master branch from git under /srv:
cd /srv
git clone https://github.com/mediainbox/StreamMachine.gitMake sure you're running the master branch:
# git branch
* masterInstall the dependencies:
cd /srv/StreamMachine
npm installCreate a folder to store the logs. If you want to use a dedicated user, chown the folder appropriately.
mkdir -p /var/log/streammachineHere's a simple configuration file for a standalone mode (adapt ports, names and credentials as required):
{
"port": 8001,
"source_port": 8002,
"log": {
"stdout": true
},
"streams": {
"test": {
"key": "test",
"root_route": true,
"format": "mp3",
"seconds": 3600,
"metaTitle": "Testing",
"host": "localhost",
"source_password": "testing"
}
}
}It's basically:
- configuring a "test" stream in mp3 with a "testing" password
- listening on TCP/8002 for incoming audio (master)
- listening on TCP/8001 for streaming clients (HLS, icecast, raw...) (slave)
- logging on
stdouteverything
Now launch manually StreamMachine with the above configuration file:
./streammachine-cmd --config ./config/standalone.jsonYou can now broadcast to the server's IP on port 8002 with corresponding credentials, and listen on port 8001 with your player:
- http://a.b.c.d:8001/test for icecast
- http://a.b.c.d.:8001/test.m3u8 for HLS
- A playlist is available at http://a.b.c.d:8001/test.pls
Note that navigating over to http://a.b.c.d:8001/index.html should display "OK" if everything goes well.
The master does 3 things:
- it is the entry point for the audio source (Nicecast, Airtime, whatever you're using)
- it serves and operates the API
- sends master stream to the slave
The slave is where clients connect to listen to the stream.
Here's a working configuration file for a master (master.json):
{
"mode": "master",
"source_port": 8002,
"master": {
"port": 8020,
"password": "super_secure_password"
},
"log": {
"stdout": true,
"json": {
"file": "/var/log/streammachine/streammachine.log",
"level": "info"
}
},
"streams": {
"test": {
"key": "test",
"root_route": true,
"format": "mp3",
"seconds": 3600,
"metaTitle": "Testing",
"host": "localhost",
"source_password": "testing"
}
}
}This will activate the master mode, listen on port 8020 for slaves with a defined password and create a test stream. Feel free to use whatever configuration is best for you.
Now launch manually a StreamMachine master with the above configuration file:
cd /srv/StreamMachine
./streammachine-cmd --config ./config/master.jsonIf all goes well you can request some information from the API:
curl http://a.b.c.d:8020/api/configNote your StreamMachine master IP address, port and password and fill them in the configuration below.
Here's a working slave configuration file:
{
"mode": "slave",
"slave": {
"master": "ws://a.b.c.d:8020?password=super_secure_password"
},
"cluster": 1,
"port": 8017,
"log": {
"stdout": true,
"json": {
"file": "/var/log/streammachine/streammachine.log",
"level": "info"
}
}
}This will launch a StreamMaster instance in slave mode, point to its master, listen to port 8017 and log. Feel free to adapt.
Note that the cluster configuration number matches the amount of workers you need, and the number shouldn't exceed the amount of CPU cores available.
Now launch manually a StreamMachine slave with the above configuration file:
cd /srv/StreamMachine
./streammachine-cmd --config ./config/slave.jsonYou should now be able to listen to a stream at http://a.b.c.d:8017/<stream_name>
Instead of relying on JSON configuration files, StreamMachine can store and manage its configuration on Redis. This removes the dependency on JSON files, offers live configuration updating, redundancy, and overall a better experience.
You can use a dedicated host for Redis or not, use Redis replication or anything you might think is relevant for your use case.
TODO: Better hints at how an initial configuration can be made with a Redis backed.
In this case, no stream configuration is explicitly needed to start.
- An example configuration file can be:
{
"port": 8001,
"source_port": 8002,
"log": {
"stdout": true
},
"redis": {
"server": "redis://a.b.c.d:6379"
}
}- Start your StreamMachine instance:
./streammachine-cmd --config /srv/config/standalone-redis.jsonIt shouldn't find any configuration available on Redis or anywhere.
- Create a new stream named
my_new_streamusing the API (there might be a better way but that's how I did it)
curl -F 'key=my_new_stream' http://a.b.c.d:8001/api/streams- You can check there's a initial basic configuration by requesting the API:
curl http://a.b.c.d:8001/api/streams/my_new_stream/config- Create a JSON file containing the initial configuration for your stream (ie.:
my_new_stream.json):
{
"key": "my_new_stream",
"root_route": true,
"format": "mp3",
"seconds": 3600,
"metaTitle": "Testing",
"host": "localhost",
"source_password": "testing"
}- Send the configuration to Redis:
$ curl -H "Content-Type: application/json" -H 'Accept: application/json' -X PUT --data @config/my_new_stream.json http://a.b.c.d:8001/api/streams/my_new_stream/configNote: you could as well have updated each entry manually, but it's a bit longer.
You should now be able to stream to your master StreamMachine host with the proper credentials and information.
Now, configuration will survive crashes and other daily casualties.