Icecast Server/YP-protocol-v2

From XiphWiki
Jump to navigation Jump to search

This page is to document and help collaborate on drafting and later finalizing a complete revision of the Icecast YP protocol and YP server behaviour.

Overview

There continues to be a demand for listings of online radio stations. Especially player software likes to present the user with easy accessible station listings.

The Icecast stream directory at dir.xiph.org has been fulfilling those needs for years, along with some other directories. For players there is a machine readable XML export.

Over the years some deficiencies have become apparent. This revised protocol will try to address those, as well as aim to provide a structured specification to enable alternative implementations.

Known deficiencies of the old protocol

  • No defined way to send warnings to the submitting server, only failures
  • No contact details in case directory operators need to reach a server administrator
  • Multiple hacks in the POST request
  • No good way to revise/extend the protocol without affecting backwards compatibility

New to be introduced features

  • Verification of stream availability through handshake

Design goals for the new revision

Old protocol - factual characteristics

This is based on current Icecast server code and the current php implementation of dir.xiph.org

Transport

The streaming server to directory communication happens over HTTP POST. Originally GET was used, but was deprecated 10 years ago and the directory stopped supporting it later on.

POST /cgi-bin/yp-cgi HTTP/1.1
User-Agent: Icecast 2.4.1
Host: dir.xiph.org
Accept: */*
Content-Length: 133
Content-Type: application/x-www-form-urlencoded

The directory request is contained in the message body as form-urlencoded data, see RFC 1866, Section 8.2.1.

Request types

There are 3 defined request types:

Add

This type of request will add a new server entry to the directory.

The request MUST have the following parameters :

parameter value explanation
action add The YP protocol request type
sn string The name of the stream
type string content type
genre string genre, space delimited(?)
b string(!?) The expected average bitrate for the stream
listenurl URL the URL of the actual stream, as used by player clients

The URL call will have the following *optional* parameters :

parameter value explanation
cpswd string Cluster Password (broadcasts with the same Server Name and cluster password will be displayed together in the directory server).
user string never implemented YP userid
pass string never implemented YP password
desc string Server Description
url url Stream URL (not the listen url, usually a link to the broadcasters website)
stype string Server Sub type. Used normally for multi-codec streams (ogg/theora, vp6/aac). Codecs should be separated by a '/' delimiter.verify

The listing scripts will respond with the following HTTP headers

header value explanation
YPResponse: 0;1 0-failure or 1-success
YPMessage: string Any error message
SID: string System Identifier which represents the unique identifier for the new listing entry. All futher communications must be made using this SID - the SID can be any alpha numeric string
TouchFreq: The frequency (in seconds) in which the listing client needs to touch the server in order to prevent a stale record

Attention: Even though HTTP headers are specified to be case-insensitive, Icecast versions prior to 2.4.0 and Icecast-kh do not handle them properly and will fail to parse the server response properly if the header names do not match the exact case as written above!

Touch

This type of request will update a server entry with new information. This request will also cause the listing server to acknowledge this server as one that is still valid. Periodic cleanups of inactive servers will be performed on the listing server.

The URL call will have the following mandatory parameters :

parameter value explanation
action touch The YP protocol request type
sid string session ID

The URL call will have the following *optional* parameters :

parameter value explanation
st string Song title
listeners string Current number of listeners
max_listeners string max listener limit for this stream
alt string average listening time [not implemented]
ht string hits / tune ins
cm string 5min average tune ins
stype string Server Sub type. Used normally for multi-codec streams (ogg/theora, vp6/aac). Codecs should be separated by a '/' delimiter. - Note that since it is possible to change codecs mid stream in some container formats, so this field is updatable on a touch.

The listing scripts will respond with the following HTTP headers

header value explanation
YPResponse: 0;1 0-failure or 1-success
YPMessage: string Any error message

Remove

This type of request will remove a server entry. This request should be done when either the broadcast has stopped, or the icecast2 server is shutting down.

The URL call will have the following mandatory parameters :

parameter value explanation
action remove The YP protocol request type
sid string session ID

The URL call does NOT have *optional* parameters!

The listing scripts will respond with the following HTTP headers

header value explanation
YPResponse: 0;1 0-failure or 1-success
YPMessage: string Any error message