icecast-monitor v1.0.2

Quickstart

Powerful & handy interface for icecast-kh monitoring & statistics collection (admin access is required).

• Able to collect icecast stats in realtime;
• Provides easy access to all stats, available in web admin;
• Can deal with very large amounts of data in memory-effective way;
• Has only one npm dependency.

To install latest stable version use npm install icecast-monitor command.

• Options
• Methods
  • createFeed
  • getServerInfo
  • getSources
  • getSource
  • getListeners
  • createStatsXmlStream
• Feed
  • Events
  • Methods
• XmlStreamParser
  • Events

Options

To access icecast monitor features create Monitor instance:

var Monitor = require('icecast-monitor');
var monitor = new Monitor({
  host: 'icecast.dev',
  port: 80,
  user: 'admin',
  password: 'hackme'
});

Following constructor parameters are available:

Methods

monitor.createFeed

Creates Monitor.Feed instance, which establishes persistent connection with icecast & processes its events feed.

monitor.createFeed(function(err, feed) {
  if (err) throw err;
  
  // Handle wildcard events
  feed.on('*', function(event, data, raw) {
    console.log(event, data, raw);
  });

  // Handle usual events
  feed.on('mount.listeners', function(listeners, raw) {
    console.log(listeners, raw);
  });
});

monitor.getServerInfo

Returns information about icecast server. Please see Monitor.XmlStreamParser server event data for details.

monitor.getServerInfo(function(err, server) {
  if (err) throw err;
  console.log(server);
});

monitor.getSources

Returns array with all audio sources (without detailed listeners information). Please see Monitor.XmlStreamParser source event for data provided about every source.

monitor.getSources(function(err, sources) {
  if (err) throw err;
  console.log(sources);
});

monitor.getSource

Provides detailed information about specified source & its listeners.

monitor.getSource('/some-mountpoint', function(err, source) {
  if (err) throw err;
  console.log(source);
});

Returns same data as Monitor.XmlStreamParser source event, with one difference: listeners parameter will contain array with information about every listener.

monitor.getListeners

Returns array with all listeners, connected to icecast server. Please see Monitor.XmlStreamParser listener event data for details. Can produce huge amounts of data, use wisely.

monitor.getListeners(function(err, listeners) {
  if (err) throw err;
  console.log(listeners);
});

monitor.createStatsXmlStream

Performs HTTP request to given icecast url path and returns stream for further processing. Can be useful to process large icecast XML output using Monitor.XmlStreamParser.

We use following icecast url paths:

• /admin/stats
  • icecast server information
  • sources detailed information
  • no detailed listeners information
• /admin/stats?mount=/$mount
  • icecast server information
  • specified source information
  • detailed information about connected listeners
• /admin/listmounts?with_listeners
  • no information about icecast server
  • minimal information about sources
  • and detailed information about all icecast listeners

// Collect sources without storing them in a memory
monitor.createStatsXmlStream('/admin/stats', function(err, xmlStream) {
  if (err) throw err;
  
  var xmlParser = new Monitor.XmlStreamParser();
 
  xmlParser.on('error', function(err) {
    console.log('error', err); 
  });
  
  xmlParser.on('source', function(source) {
    // Do work with received source
    console.log('source', source);
  });

  // Finish event is being piped from xmlStream
  xmlParser.on('finish', function() {
    console.log('all sources are processed');
  });

  xmlStream.pipe(xmlParser);
});

Feed

Establishes persistent connection with icecast using STATS HTTP method & processes events feed in realtime. Best way to create is to use monitor.createFeed method, which injects all necessary parameters.

Events

For mount. and server. events user-callback is provided with following parameters:

• Internal events

  • connect: connection with icecast is established
  • disconnect: connection with icecast is closed

• Wildcard events

  • *: groups absolutely all supported events, produces lots of calls
  • mount.*: groups all mount-related events

  • server.*: groups all server-related events

• Mounts events
  • mount.audioCodecId
  • mount.audioInfo
  • mount.authenticator
  • mount.bitrate
  • mount.connected
  • mount.delete
  • mount.flush
  • mount.genre
  • mount.incomingBitrate
  • mount.listenerConnections
  • mount.listenerPeak
  • mount.listeners
  • mount.listenUrl
  • mount.maxListeners
  • mount.metadataUpdated
  • mount.mpegChannels
  • mount.mpegSampleRate
  • mount.new
  • mount.outgoingKBitrate
  • mount.public
  • mount.queueSize
  • mount.serverDescription
  • mount.serverName
  • mount.serverType
  • mount.serverUrl
  • mount.slowListeners
  • mount.sourceIp
  • mount.streamStart
  • mount.title
  • mount.totalBytesRead
  • mount.totalBytesSent
  • mount.totalMBytesSent

  • mount.ypCurrentlyPlaying

• Server events
  • server.admin
  • server.bannedIPs
  • server.build
  • server.clientConnections
  • server.clients
  • server.connections
  • server.fileConnections
  • server.host
  • server.info
  • server.listenerConnections
  • server.listeners
  • server.location
  • server.outgoingKBitrate
  • server.serverId
  • server.serverStart
  • server.sourceClientConnections
  • server.sourceRelayConnections
  • server.sources
  • server.sourceTotalConnections
  • server.stats
  • server.statsConnections
  • server.streamKBytesRead
  • server.streamKBytesSent

mount.audioCodecId

EVENT /test.mp3 audio_codecid 2

mount.audioInfo

Displays audio encoding information.

EVENT /test.mp3 audio_info channels=2;samplerate=44100;bitrate=64

mount.authenticator

EVENT /test.mp3 authenticator command

mount.bitrate

EVENT /test.mp3 bitrate 64

mount.connected

EVENT /test.mp3 connected 180423

mount.delete

Emitted when mount is deleted. Allows to notify relays about deleted source immediately (rather than wait for polling by the slaves).

DELETE /test.mp3

mount.flush

FLUSH /test.mp3

mount.genre

EVENT /test.mp3 genre Misc

mount.incomingBitrate

EVENT /test.mp3 incoming_bitrate 127064

mount.listenerConnections

EVENT /test.mp3 listener_connections 4

mount.listenerPeak

EVENT /test.mp3 listener_peak 2

mount.listeners

EVENT /test.mp3 listeners 2

mount.listenUrl

EVENT /11-31.mp3 listenurl http://icecast.dev:80/test.mp3

mount.maxListeners

EVENT /11-31.mp3 max_listeners -1

mount.metadataUpdated

Is emitted when track is updated.

EVENT /test.mp3 metadata_updated 06/Aug/2015:14:05:05 +0300

mount.mpegChannels

EVENT /test.mp3 mpeg_channels 2

mount.mpegSampleRate

EVENT /test.mp3 mpeg_samplerate 44100

mount.new

Emitted when new mount is created. Allows to notify relays about new source immediately (rather than wait for polling by the slaves).

NEW audio/mpeg /229-682.mp3

mount.outgoingKBitrate

EVENT /test.mp3 outgoing_kbitrate 0

mount.public

Displays mount visibility (advertisement) setting.

EVENT /test.mp3 public 1

mount.queueSize

EVENT /test.mp3 queue_size 65828

mount.serverDescription

EVENT /test.mp3 server_description My station description

mount.serverName

EVENT /test.mp3 server_name TestFM

mount.serverType

EVENT /test.mp3 server_type audio/mpeg

mount.serverUrl

EVENT /test.mp3 server_url http://example.com/

mount.slowListeners

EVENT /test.mp3 slow_listeners 0

mount.sourceIp

EVENT /test.mp3 source_ip icecast.dev

mount.streamStart

EVENT /test.mp3 stream_start 04/Aug/2015:12:00:31 +0300

mount.title

EVENT /test.mp3 title Werkdiscs - Helena Hauff - 'Sworn To Secrecy Part II'

mount.totalBytesRead

EVENT /test.mp3 total_bytes_read 1443575627

mount.totalBytesSent

EVENT /test.mp3 total_bytes_sent 256000

mount.totalMBytesSent

EVENT /test.mp3 total_mbytes_sent 0

mount.ypCurrentlyPlaying

EVENT /test.mp3 yp_currently_playing Nickelback - How You Remind Me

server.admin

Displays administrator's email.

EVENT global admin email@example.com

server.bannedIPs

EVENT global banned_IPs 0

server.build

EVENT global build 20150616004931

server.clientConnections

EVENT global client_connections 1029675

server.clients

EVENT global clients 62

server.connections

EVENT global connections 1178553

server.fileConnections

EVENT global file_connections 3534

server.host

Configuration icecast.hostname setting value. Is used for the stream directory lookups or playlist generation possibily if a Host header is not provided.

EVENT global host icecast.dev

server.info

Identifies the end of the big list at the beginning. When initially connected, you get a snapshot (a blast of content), and this just marks the end of it. After this then the stats are generated since the snapshot.

INFO full list end

server.listenerConnections

EVENT global listener_connections 220589

server.listeners

EVENT global listeners 16

server.location

Configuration icecast.location setting value, is also displayed in web interface.

EVENT global location RU

server.outgoingKBitrate

EVENT global outgoing_kbitrate 4411

server.serverId

Icecast server identifier. Can be overrided in config file.

EVENT global server_id Icecast 2.4.0-kh1

server.serverStart

EVENT global server_start 06/Jul/2015:00:19:34 +0300

server.sourceClientConnections

EVENT global source_client_connections 0

server.sourceRelayConnections

EVENT global source_relay_connections 1317

server.sources

EVENT global sources 45

server.sourceTotalConnections

EVENT global source_total_connections 1318

server.stats

EVENT global stats 0

server.statsConnections

EVENT global stats_connections 2

server.streamKBytesRead

EVENT global stream_kbytes_read 2414225600

server.streamKBytesSent

EVENT global stream_kbytes_sent 1102687068

Methods

feed.connect

Establishes connection, once connected emits connect event. If you use createFeed method, it will call feed.connect automatically, so this method can be used to handle disconnects like shown below:

monitor.createFeed(function(err, feed) {
  if (err) throw err;
  
  // Handle disconnects
  feed.on('disconnect', function() {
    feed.connect();
  });
});

feed.disconnect

Closes icecast connection, once disconnected emits disconnect event.

monitor.createFeed(function(err, feed) {
  if (err) throw err;
  feed.on('connect', function() {
    
    // Disconnect with 5 seconds delay
    setTimeout(feed.disconnect, 5000);
  });
});

XmlStreamParser

Writeable stream, that allows to retrieve sources, listeners & server information from icecast xml stream. Icecast xml stream can be retrieved using monitor.createStatsXmlStream method.

Using XmlStreamParser directly can be more memory-effective when dealing with large icecast output, then using monitor.getServerInfo, monitor.getSources, monitor.getSource and monitor.getListeners methods, because those methods have to store information in memory before it is returned in callback.

// Collect sources without storing them in a memory
monitor.createStatsXmlStream('/admin/stats', function(err, xmlStream) {
  if (err) throw err;

  var xmlParser = new Monitor.XmlStreamParser();

  // Handle errors
  xmlParser.on('error', function(err) {
    console.log('error', err); 
  });
  
  // Handle server info
  xmlParser.on('server', function(server) {
    console.log('server', server);
  });
  
  // Handle sources
  xmlParser.on('source', function(source) {
    console.log('source', source);
  });

  // Handle listeners
  xmlParser.on('listener', function(listener) {
    console.log('listener', listener);
  });

  // Xml stream finished
  xmlParser.on('finish', function() {
    console.log('data is finished');
  });

  xmlStream.pipe(xmlParser);
});

Events

• error
• server
• source
• listener
• finish

error

Represents error, that happened while parsing xml stream.

server

Is emitted when xml stream processing is finished. Returns following information about icecast server:

source

Is emitted when source processing is finished. Returns following information for every source:

listener

Is emitted when listener processing is finished. Returns following information for every listener: