README.md

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:

Parameter	Type	Required	Description
host	String	Yes	IP or DNS name
port	Integer	No	Port number (defaults to 80)
user	String	Yes	Admin username
password	String	Yes	Admin password

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:

Parameter	Type	Description
event	String	Event name (present only for wildcard events)
data	Mixed	Parsed parameter(s), is described for each event below
raw	String	Raw message received from icecast

• 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

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Audio codec id: 2 for mp3, 10 for aac

mount.audioInfo

Displays audio encoding information.

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

Parameter	Type	Description
mount	String	Mountpoint name
data	Object	Audio channel info
data.channels	Integer	Number of channels
data.sampleRate	Integer	Sample rate
data.bitrate	Integer	Bitrate (kbps)

mount.authenticator

EVENT /test.mp3 authenticator command

Parameter	Type	Description
mount	String	Mountpoint name
data	String	Authenticator type

mount.bitrate

EVENT /test.mp3 bitrate 64

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Bitrate (kbps), used for stats & YP

mount.connected

EVENT /test.mp3 connected 180423

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Connection duration in seconds

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

Parameter	Type	Description
mount	String	Deleted mountpoint name

mount.flush

FLUSH /test.mp3

Parameter	Type	Description
mount	String	Flushed mountpoint name

mount.genre

EVENT /test.mp3 genre Misc

Parameter	Type	Description
mount	String	Mountpoint name
data	String	Genre name, used for stats & YP

mount.incomingBitrate

EVENT /test.mp3 incoming_bitrate 127064

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Source bitrate (bps)

mount.listenerConnections

EVENT /test.mp3 listener_connections 4

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Connections number

mount.listenerPeak

EVENT /test.mp3 listener_peak 2

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Max detected number of simultaneous listeners

mount.listeners

EVENT /test.mp3 listeners 2

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Current listeners number

mount.listenUrl

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

Parameter	Type	Description
mount	String	Mountpoint name
data	String	Audio stream url

mount.maxListeners

EVENT /11-31.mp3 max_listeners -1

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Simultanious listeners limit

mount.metadataUpdated

Is emitted when track is updated.

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

Parameter	Type	Description
mount	String	Mountpoint name
data	String	Date when metadata was updated

mount.mpegChannels

EVENT /test.mp3 mpeg_channels 2

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Number of audio channels

mount.mpegSampleRate

EVENT /test.mp3 mpeg_samplerate 44100

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Sample rate

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

Parameter	Type	Description
mount	String	Mountpoint
data	String	Mime type

mount.outgoingKBitrate

EVENT /test.mp3 outgoing_kbitrate 0

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Outgoing bitrate (kbps)

mount.public

Displays mount visibility (advertisement) setting.

EVENT /test.mp3 public 1

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Possible values: -1 (up to source client / relay) , 0 (disable), 1 (force advertisement)

mount.queueSize

EVENT /test.mp3 queue_size 65828

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Queue size

mount.serverDescription

EVENT /test.mp3 server_description My station description

Parameter	Type	Description
mount	String	Mountpoint name
data	String	User-defined station description

mount.serverName

EVENT /test.mp3 server_name TestFM

Parameter	Type	Description
mount	String	Mountpoint name
data	String	User-defined station name

mount.serverType

EVENT /test.mp3 server_type audio/mpeg

Parameter	Type	Description
mount	String	Mountpoint name
data	String	Mime type

mount.serverUrl

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

Parameter	Type	Description
mount	String	Mountpoint name
data	String	User-defined url

mount.slowListeners

EVENT /test.mp3 slow_listeners 0

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Slow listeners number

mount.sourceIp

EVENT /test.mp3 source_ip icecast.dev

Parameter	Type	Description
mount	String	Mountpoint name
data	String	Mounpoint stream source host or ip address

mount.streamStart

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

Parameter	Type	Description
mount	String	Mountpoint name
data	String	Date, when mount started streaming

mount.title

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

Parameter	Type	Description
mount	String	Mountpoint name
data	String	Track name

mount.totalBytesRead

EVENT /test.mp3 total_bytes_read 1443575627

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Source (incoming) traffic in bytes

mount.totalBytesSent

EVENT /test.mp3 total_bytes_sent 256000

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Source (outgoing) traffic in bytes

mount.totalMBytesSent

EVENT /test.mp3 total_mbytes_sent 0

Parameter	Type	Description
mount	String	Mountpoint name
data	Integer	Source (outgoing) traffic in bytes

mount.ypCurrentlyPlaying

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

Parameter	Type	Description
mount	String	Mountpoint name
data	String	Track, that is displayed in YP

server.admin

Displays administrator's email.

EVENT global admin email@example.com

Parameter	Type	Description
data	String	Administrator email

server.bannedIPs

EVENT global banned_IPs 0

Parameter	Type	Description
data	Integer	Banned ip addresses number

server.build

EVENT global build 20150616004931

Parameter	Type	Description
data	Integer	Build number

server.clientConnections

EVENT global client_connections 1029675

Parameter	Type	Description
data	Integer	Client connections number

server.clients

EVENT global clients 62

Parameter	Type	Description
data	Integer	Connected clients

server.connections

EVENT global connections 1178553

Parameter	Type	Description
data	Integer	Connections number

server.fileConnections

EVENT global file_connections 3534

Parameter	Type	Description
data	Integer	File connections number

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

Parameter	Type	Description
data	String	Server DNS name or IP address

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

Parameter	Type	Description
data	Integer	Listener connections number

server.listeners

EVENT global listeners 16

Parameter	Type	Description
data	Integer	Current listeners number

server.location

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

EVENT global location RU

Parameter	Type	Description
data	String	Server location

server.outgoingKBitrate

EVENT global outgoing_kbitrate 4411

Parameter	Type	Description
data	Integer	Outgoing bitrate (kbps)

server.serverId

Icecast server identifier. Can be overrided in config file.

EVENT global server_id Icecast 2.4.0-kh1

Parameter	Type	Description
data	String	Server identifier (icecast followed by a version number or user-defined value)

server.serverStart

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

Parameter	Type	Description
data	String	Server start date

server.sourceClientConnections

EVENT global source_client_connections 0

Parameter	Type	Description
data	Integer	Source client connections number

server.sourceRelayConnections

EVENT global source_relay_connections 1317

Parameter	Type	Description
data	Integer	Source relay connections number

server.sources

EVENT global sources 45

Parameter	Type	Description
data	Integer	Sources number

server.sourceTotalConnections

EVENT global source_total_connections 1318

Parameter	Type	Description
data	Integer	Source total connections number

server.stats

EVENT global stats 0

Parameter	Type	Description
data	Integer	?

server.statsConnections

EVENT global stats_connections 2

Parameter	Type	Description
data	Integer	?

server.streamKBytesRead

EVENT global stream_kbytes_read 2414225600

Parameter	Type	Description
data	Integer	Stream incoming traffic (kbytes)

server.streamKBytesSent

EVENT global stream_kbytes_sent 1102687068

Parameter	Type	Description
data	Integer	Stream outgoing traffic (kbytes)

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:

Parameter	Type	Description
admin	String	Administrator's email
bannedIPs	Integer	Banned ip addresses number
build	Integer	Build number
clientConnections	Integer	Total client (sources, listeners, web requests, etc) connections number
clients	Integer	Current clients (sources, listeners, web requests, etc) number
connections	Integer	?
fileConnections	Integer	File connections number
host	String	Host DNS or IP address (is defined by hostname setting in icecast config)
listenerConnections	Integer	Listeners connections number
listeners	Integer	Listeners number
location	String	Server location (is defined by location setting in icecast config)
outgoingKBitrate	Integer	Outgoing bitrate in Kbps
serverId	String	Server identifier (is defined by server-id setting in icecast config)
serverStart	String	Server start date
sourceClientConnections	Integer	Source clients connections number
sourceRelayConnections	Integer	Source relays connections number
sources	Integer	Sources (mountpoints) number
sourceTotalConnections	Integer	Total connections number
stats	Integer	Number currently connected clients using STATS HTTP method (like Monitor.Feed
statsConnections	Integer	STATS HTTP method total connections number
streamKBytesRead	Integer	Streaming incoming traffic (KB)
streamKBytesSent	Integer	Streaming outgoing traffic (KB)

source

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

Parameter	Type	Description
mount	String	Mountpoint
audioCodecId	Integer	Audio codec id: 2 for mp3, 10 for aac
audioInfo	String	Audio encoding information
authenticator	String	Authentication scheme
bitrate	Integer	User-defined bitrate (Kbps)
connected	Integer	Connected time in seconds
genre	String	User-defined genre
incomingBitrate	Integer	Source stream bitrate (bps)
listenerConnections	Integer	Listener connections number
listenerPeak	Integer	Maximum detected number of simultaneous users
listeners	Integer	Current listeners number
listenUrl	String	Audio stream url
maxListeners	Integer	Listeners limit
metadataUpdated	String	Last metadata update date
mpegChannels	Integer	Mpeg channels number
mpegSampleRate	Integer	Mpeg sample rate
outputKBitrate	Integer	Outgoing bitrate for all listeners (Kbps)
public	Integer	Source advertisement: -1 - source client or relay determines if mountpoint should be advertised, 0 - disables advertisement, 1 - forces advertisement
queueSize	Integer	Can vary (typically) because lagging clients cause the size to increase until they either get kicked off or they catch up
serverDescription	String	User-defined description
serverName	String	User-defined name
serverType	String	Mime type
serverUrl	String	User-defined url
slowListeners	Integer	Slow listeners number
sourceIp	String	Source ip address
streamStart	String	Date, when stream started
title	String	Track name
totalBytesRead	Integer	Incoming traffic
totalBytesSent	Integer	Outgoing traffic (Bytes)
totalMBytesSent	Integer	Outgoing traffic (MBytes)
ypCurrentlyPlaying	String	YP track title

listener

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

Parameter	Type	Description
id	Integer	Icecast internal id, can be used to kick listeners, move them between mounts, etc.
ip	String	Listener's ip address
userAgent	String	Listener's user agent
referrer	String	Url, where listener came from
lag	Integer	?
connected	Integer	Connected time in seconds
mount	String	Source mounpoint