Steamcast/Icecast2 YP Directory Listing Spec [Technical]

This forum will contain various articles contributed by the team and other invited guest.
Post Reply
User avatar
Jay
Will work for food (Administrator)
Posts: 3020
Joined: Mon Jan 14, 2002 12:48 am
Location: Next Door
Contact:

Steamcast/Icecast2 YP Directory Listing Spec [Technical]

Post by Jay »

Introduction
Following the traditional path of many unicast servers, Steamcast has been designed with the ability to list in central locations. This has the benefit of allowing the deferment of promotion responsibility on third parties, which cuts costs, and it allows listeners to mass themselves in targetted areas of the web without having to be totally loyal to any given station, but perhaps a content type or general interest.

Icecast2
Icecast2's existing yp infrastructure has been utilized as a base for this specification. This helps our community and theirs by giving them more leverage with more content , and by leveraging their already existing standards which means less re-invention on our part. With that said their may be some deviation from their listing spec to add more features and value with backwards compatibility. Their listing spec will be referred to by Icecast revision numbers. YP Icecast 2.2 would be their spec as of Icecast version 2.2. Steamcast will also follow the same revisioning numbering system, where YP Steamcast 0.9.7 was first implemented in Steamcast v0.9.7 The revision number is broken down by Major, Minor and Bugfix numbers.
Major version numbers could potentially but don't neccessarily have to break backwards compatibility. This usually envolves a total code rewrite or specification rewrite. Minor version changes would be the possible addition of new elements but would never break backward compatibility. Bug fix would be no change in specification at all, merely just a fix to the underlying code of the yp.

Icecast2 is by no means tied to this specification as I have defined it. However in the interest of saving time it should be good enough to allow the documentation to be understood and at least enough to raise flags that there could be a revision that may not be compatible with your version of the software or yp. At all times we will try to remain tied to the Icecast2.x specification as long as it is technically feasible. The Icecast2 team has been extremely cooperative with us and have even implemented some of the specs we have defined in our project. Compatibility with their YP project is a high priority. You can read more on Icecast2's YP Directory spec at www.icecast.org/spec.php

Overview
The Steamcast/Icecast2 YP specification demands that the following base functions be performed.
  • Ability to create a new entry in the listing
  • Ability to update an existing entry in the listing
  • Ability to remove an entry from the listing
  • Ability to group related broadcasts
  • Ability to cluster relayed broadcasts into a single listing
  • Support for mountpoints
  • Listing should be done by the streaming server (i.e. no manual effort required)
  • Listings should not require registration or other prior sign-up
Protocol
The HTTP protocol will be used to allow a listing client and a listing server to communicate. The specification will remain in the Request and Response Headers of the client and server. Additionally the data communicated should be between one client and one server script. All actions and functions remain within the one script.

Each directory is only bound to handle a small subset of the specification. This subset will be referred to as required fields. Optional Fields are not required in order to have a working YP directory. How a particular YP handles required fields is up to each YP server.

Parameter information sent by request may be handled in either the HTTP GET or POST methods. Our recommendation is to use POST in Unicast server implementations. This removes parameter data from proxy caches and logs which could be a potential security threat if using cluster passwords.

We also recommend that all Listing clients pass User-Agent fields, this helps the YP owner keep metrics on which listing clients are utilizing their servers and can also help them track down bugs for the developers of the listing client.

Add Server
This function adds a server to a YP Server directory.

The following request fields are required:
  • action: This specifies the type of action we wish to occur, in this case the action is add.
  • sn: The name this streams goes by.
  • type: The data mime type the stream uses (Content-Type)
  • genre: Stream's Genre
  • b: Stream's Bitrate
  • listenurl: Stream's URL
The following request fields are optional:
  • cpswd: Cluster Password (broadcasts with the same Server Name and cluster password will be displayed together in the directory server).
  • user: YP userid - not neccessarily all YP implementations will support users and passwords
  • pass: YP password - not neccessarily all YP implementations will support users and passwords
  • desc: Stream's Description
  • url: Stream's URL (should point to a HTML webpage)
  • stype: Stream's Sub type. Used normally for multi-codec streams (ogg/theora, vp6/aac). Codecs should be separated by a '/' delimiter.
The following response fields will be located in the header. These are all required:
  • YPResponse: The numbered response code (0 = failure, 1 = success)
  • YPMessage: The string interpretation of the YPResponse, this gives the listing client more information about the reasons for the above response.
  • SID: System ID, must be a unique string from any other stream listing in the YP server's database.
  • TouchFreq: The touch frequency in seconds requested from the YP Server. This frequency must be followed to reduce load on the YP Server.
There are no optional fields in the add function's response header.

Example of implemenation using POST method:

Code: Select all

POST /cgi-bin/yp-cgi HTTP/1.0\r\n
Host: example.com\r\n
User-Agent: Steamcast/0.9.7 (Win32)\r\n
Content-Length: 104\r\n
Content-Type: application/x-www-form-urlencoded\r\n\r\n

action=add&sn=Steamcast+Server&listenurl=http://localhost:8000/mount.mp3&genre=Rock&b=64&type=audio/mpeg
Example of Successful YP server response:

Code: Select all

HTTP/1.0 200 OK\r\n
YPResponse: 1\r\n
YPMessage: Add Successful\r\n
SID: 84040293-239405\r\n
TouchFreq: 60\r\n\r\n
Example of Failed YP server response:

Code: Select all

HTTP/1.0 200 OK\r\n
YPResponse: 0\r\n
YPMessage: An error occured... (more information about the error)\r\n\r\n
Touch Server
This function updates the YP database with statistical information and informs the YP that the server is still active.

The following request fields are required:
  • action: This specifies the type of action we wish to occur, in this case the action is touch.
  • sid: This is the SID recieved from the YP server in the Add Sequence.
The following request fields are optional:
  • st: Currently Playing Track Title
  • listeners: Number of Listeners on this stream
  • max_listeners: The maximum capacity of this mount/stream.
  • alt: Average Listening Time on this mount/stream.
  • ht: Tune-In count for this stream.
  • cm: 5 Minute Tune-In count.
  • stype: Stream Sub Type. Used to identify codec information for a container stream such as OGG or NSV. Fields delimited by a / much like a mime type.
The following response fields will be located in the header. These are all required:
  • YPResponse: The numbered response code (0 = failure, 1 = success)
  • YPMessage: The string interpretation of the YPResponse, this gives the listing client more information about the reasons for the above response.
The following are optional responses (Icecast2 does not recognize this capability).
  • TouchFreq: The touch frequency in seconds requested from the YP Server. This frequency must be followed to reduce load on the YP Server. This response header may or may not be present. Icecast2 spec does not allow for this response under this action type.
Example of implemenation using POST method:

Code: Select all

POST /cgi-bin/yp-cgi HTTP/1.0\r\n
Host: example.com\r\n
User-Agent: Steamcast/0.9.7 (Win32)\r\n
Content-Length: 66\r\n
Content-Type: application/x-www-form-urlencoded\r\n\r\n

action=touch&sid=84040293-239405&st=Jay+Krivanek+-+Sings+the+Blues
Example of Successful YP server response:

Code: Select all

HTTP/1.0 200 OK\r\n
YPResponse: 1\r\n
YPMessage: Touch Successful\r\n
TouchFreq: 300\r\n\r\n
Example of Failed YP server response:

Code: Select all

HTTP/1.0 200 OK\r\n
YPResponse: 0\r\n
YPMessage: An error occured... (more information about the error)\r\n\r\n
Remove Server
This function updates the YP database with statistical information and informs the YP that the server is still active.

The following request fields are required:
  • action: This specifies the type of action we wish to occur, in this case the action is remove.
  • sid: This is the SID recieved from the YP server in the Add Sequence.
There are no optional request fields.

The following response fields will be located in the header. These are all required:
  • YPResponse: The numbered response code (0 = failure, 1 = success)
  • YPMessage: The string interpretation of the YPResponse, this gives the listing client more information about the reasons for the above response.
There are no optional Response Headers.

Example of implemenation using POST method:

Code: Select all

POST /cgi-bin/yp-cgi HTTP/1.0\r\n
Host: example.com\r\n
User-Agent: Steamcast/0.9.7 (Win32)\r\n
Content-Length: 33\r\n
Content-Type: application/x-www-form-urlencoded\r\n\r\n

action=remove&sid=84040293-239405
Example of Successful YP server response:

Code: Select all

HTTP/1.0 200 OK\r\n
YPResponse: 1\r\n
YPMessage: Remove Successful\r\n\r\n
Example of Failed YP server response:

Code: Select all

HTTP/1.0 200 OK\r\n
YPResponse: 0\r\n
YPMessage: An error occured... (more information about the error)\r\n\r\n
Extra Fields
In the interest of cross-compatibility of standards, in the event that our project or any project for that matter needs to extend the capabilities of this system. The extended capability fields must be prepended with 'x-'. For example:

Code: Select all

POST /cgi-bin/yp-cgi HTTP/1.0\r\n
Host: example.com\r\n
User-Agent: Steamcast/0.9.7 (Win32)\r\n
Content-Length: 57\r\n
Content-Type: application/x-www-form-urlencoded\r\n\r\n

action=remove&sid=84040293-239405&x-reason=because+I+died
This also extends to the YP End. If the YP would like to pass more information to the client lister. They may do so by prepending all extra headers with 'X-'

Code: Select all

HTTP/1.0 200 OK\r\n
YPResponse: 1
YPMessage: Touch Successful
X-Sent-Tune-Ins: 612\r\n\r\n
In Closing
If you find anything incorrect in this article, or any oversights, then please email me

Feel free to leave a comment if you feel that I have missed something. Do not reply with questions. Questions should go in the Steamcast forum. Questions will be split from this thread and moved to appropriate forums.
User avatar
schrikg
Posts: 12
Joined: Wed Aug 31, 2005 10:46 am
Location: The Netherlands

Post by schrikg »

Very interesting article.
I play a little with it.

It succesfully answered a steamcast server when it add itself but now it asks a answer for a action "touch"
What does it expect yp-list server to answer ?

Hw does that work ?
User avatar
schrikg
Posts: 12
Joined: Wed Aug 31, 2005 10:46 am
Location: The Netherlands

Post by schrikg »

Never mind
I found the link in your article ;)
Post Reply