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 protected]

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