Components
The blue dotted line shows the approximate path of audio through StreamMachine. Master and slave could be running in one process when StreamMachine is running in standalone mode, or in different processes in a master-slave setup.
StreamMachine is divided into two major areas of functionality: Master and Slave.
StreamMachine Master is in charge of coordinating the system as a whole, taking in source audio, handling configuration and hosting the admin interface.
Master's Stream is primarily concerned with source management. It maintains a RewindBuffer that can be used for bringing new slaves up to speed.
StreamProxy takes the master stream's "data" events and broadcasts them to all connected slaves.
StreamTransport is an Express endpoint that allows slaves to load in a full RewindBuffer at startup.
The SourceIn module is the point-of-entry for new Icecast-compatible sources. It implements a basic parser that understands the "ICE/1.0" protocol that sources send, and understands how to validate the basic authorization header against the stream's password. Once a new source connection is validated, it sets up a new IcecastSource object and connects it to the stream.
Despite the name, there's nothing especially Icecast about the handling of source audio. A parser is loaded, either MP3 or AAC depending on the stream's format setting. The incoming source audio is passed through the parser to break the stream into audio frames. Those frames are then queued into chunks of approximately the same duration (half a second, in the stock configuration) before being emitted as data events.
This is more of a development feature, but could be used in certain production setups. ProxyRoom is a source that connects to an existing Icecast stream, making the StreamMachine system into a proxy / multiplier. A ProxyRoom instance is created if a URL is filled in to the stream's "Fallback Source" setting.
Currently, configuration information is persisted JSON-encoded into a single key in Redis. This will likely change in future versions of StreamMachine.
StreamMachine's Logger wraps the functionality of Winston, the logging framework from Flatiron. We implement some custom logging levels, a method for creating "child" logger instances that add parameters to the log message, and a few custom outputs. See the Logging page for full information.
The admin provides a basic UI and API for managing stream information. It also implements a simple user system for authentication.
StreamMachine Slave is the user-facing side of the system, handling all aspects of user connections and output.
Slave's Stream extends the RewindBuffer and adds functionality for tracking listener connections, disconnecting slow listeners and aggregating stats.
Server is an Express endpoint that handles the gruntwork of taking listener connections and determining what output to route them to. See the Outputs page for discussion of the different output options.
It is common in radio contexts to want to play a preroll clip to new listeners, often either an ad or a stream identifier. The Preroller module proxies a connection to an instance of StreamMachine's accompanying Preroller project, delivering the preroll audio before passing the user on to the output handling.