Many streaming servers are exposing a public or private interface to gather real-time usage statistics, for example the number of users connected; with or without full details such as the IP Address.
There is no unified interface and they are not usually optimized for performance.
CasterStats.Proxy aims to remedy these shortfalls. It acts as a streaming server proxy, and is designed with performance and ease of use in mind.
It consists of a preconfigured HTTP Proxy application to relay real-time usage data with intelligence, including the following:
- compression - data is compressed saving up to 90% of bandwidth
- aggregation - data can be aggregated by country, city or player
- paging - data can be paged to save additional bandwidth
- geolocation - data is geolocated server-side
- increased security - queries are signed to ensure better security
- caching - responses are cached server-side to limit the load on your streaming servers
Each streaming server proxy exposes its own interface, with the following features per stream or per mount point:
- Status (Up, Down, Unreachable or Unknown)
- User list
- IP Address
- Time connected in seconds
- Player
- Name
- Version
- Type
- Platform
- Location
- Latitude
- Longitude
- Postal (Zip) Code
- City
- Region (Code & Name)
- Country
- Current Users (count)
- Other stream specific properties (depends on the server queried)
- Average time spent
- Peak (maximum concurrent since start up)
- Current played media
- Played media history
- Content type (audio/mpeg, etc)
- Content genre (Rock, Pop....)
Technical Details
The HTTP Proxy will provide this information using REST API with the two most used web standards: XML and JSON. We will provide an XSD for the XML, this is missing in all streaming servers providing XML based interfaces.
The queries can be parameterized to specify the data to be retrieved and its form.
Once a mount has been properly configured, it will be accessible through HTTP GET or POST requests like this:
http://[ip-host]:[port]/[route]/[mount]/
Mount is the specified mount for which the information is required. Mount can be omitted to retrieve all the information the user has access to.
Supported Stream Servers
- SHOUTcast
- IceCast
- Wowza Media Server
- Windows Media Services (does not provide user agent and time connected)
API Routes
All routes accept the following parameters:
Format: can be either XML or JSON. JSON by default
Username: the user name
Password: the password
Sign: as a replacement of user & password in clear, request + time component is hash with the combination of username/password and session token using SHA1 (see below).
User List
/stats/userlist/{stream}/
This gets the detailed list of the users. Optional parameters: page, page size, player, country code, city name, showproperties & geolocate (yes if omitted, required if country or city filter)
To use paging, simply specify page size & current page and the server will do the rest.
If you want to limit the data to a specific country or city name, you can specify those parameters.
It is also possible to disable geolocation by specifying no in geolocate parameter.
Countries
/stats/countries/{stream}/
This returns the aggregated country information from the specified stream
Cities
/stats/cities/{stream}/
This returns the aggregated country and city information from the specified stream
Players
/stats/players/{stream}/
This returns the aggregated player information from the specified stream. Code, Type, Platform
Status
/status/{stream}/
This gets the status of the given stream. If no mount is specified, the summary is provided for all mounts accessible by the user.
Authentication & Authorization
Unless a mount has been specifically granted public access, API consumers must provide a valid username and password in the parameters.
Example:
http://example.org:9000/stats/tophits/userlist?username=marco&password=hU5lD5f
This approach is not safe as each request sends the username and password in clear on the network, regardless of the method used (POST or GET). To increase security, installing CasterStats Proxy in IIS or Apache using proper SSL encryption will help a lot. However, CasterStats Proxy provides the user with a strong authentication technique based on hashing.
You must pass a MD5 signature with the following string:
[username][password][ticks]
So if your username is marco, your password hU5lD5f and ticks (see below), we will create an MD5 hash of the following string:
marcohU5lD5f53435322
...and pass it with the parameter sign.
The process is not completely secure as there is a tolerance for ticks of +-3 minutes. Also content is still passed, so it will only prevent unauthorized usage. If security is critical, install CasterStats Proxy as an IIS or Apache web application with SSL.
Ticks are the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001. For example, you can obtain it in .NET by calling DateTime.Now.Ticks.
Caching
Data is cached server side. This means that if you expose one Wowza HTTP provider page for many customers, it will be called only once every X seconds, as defined in the configuration.
Compression
Compression is automatic. When a client (most browsers) is compatible with gzip and/or deflate, the response sent is automatically compressed. This can reduce the size of the response by 90%.
Compatibility with CasterStats.Dashboard
Our Dashboard product can take advantage of the features included in CasterStats.Proxy. By using the proxy you will reduce bandwidth significantly thanks to the compression and reduce refresh time in the dashboard thanks to pre-enrichment of the data server side.
If you have a lot of concurrent users, CasterStats.Proxy is what you need.
Application Configuration
The Proxy can be easily configured using XML.
<proxyConfig>Caching is the number of seconds stream info should be cached.
Port is the tcp port the proxy should listen requests on.
AcceptedIpAddresses is used to specify which IPs are allowed to access the data. Empty = All.
DisableTicks, when set to true, lets user authenticate without the signature.
<streams>
Name should contains only letters and numbers. No special characters,
Host should be a valid host name or ip address.
Port should be the server's or stream's API port.
Username is required except for SHOUTcast.
Password is required for IceCast, Wowza & SHOUTcast.
Mount is required except for SHOUTcast. For Windows Media, it's the publishing point. For Wowza it's the vhost/application/applicationInstance.
Type is required. Accepted values: shoutcast, icecast, wowzamediaserver & windowsmedia.
UserAccesses let you specify which user (defined later) can access the data from that stream.
<stream name="video" port="8002" host="video.example.org" type="wowzamediaserver" mount="video" username="providerlogin" password="mypass" useraccesses="admin" />
</streams>
<users>
<user name="admin" password="changeme" memberof="def"/>
<user name="seconduser" password="changeme" memberof="def"/>
</users>
<groups>
<group name="def" />
</groups>
</proxyConfig>
