Icecast Server/YP-protocol-v2: Difference between revisions

Latest revision as of 17:33, 19 June 2020

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
Touch
Remove

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

@@ Line 1: / Line 1: @@
-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. It will also explain what 'YP' is.
+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.
+<code>POST /cgi-bin/yp-cgi HTTP/1.1<br>
+User-Agent: Icecast 2.4.1<br>
+Host: dir.xiph.org<br>
+Accept: */*<br>
+Content-Length: 133<br>
+Content-Type: application/x-www-form-urlencoded</code>
+The directory request is contained in the message body as form-urlencoded data, see [https://tools.ietf.org/html/rfc1866#section-8.2.1 RFC 1866, Section 8.2.1].
+=== Request types ===
+There are 3 defined request types:
+* [[#Add|Add]]
+* [[#Touch|Touch]]
+* [[#Remove|Remove]]
+==== Add ====
+This type of request will add a new server entry to the directory.
+The request MUST have the following parameters :
+{| class="wikitable"
+|-
+!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 :
+{| class="wikitable"
+|-
+!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
+{| class="wikitable"
+|-
+!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 :
+{| class="wikitable"
+|-
+!parameter !! value !! explanation
+|-
+|action || '''touch''' || The YP protocol request type
+|-
+|sid || string || session ID
+|}
+The URL call will have the following *optional* parameters :
+{| class="wikitable"
+|-
+!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
+{| class="wikitable"
+|-
+!header !! value !! explanation
+|-
+|YPResponse:	||0;1||0-failure or 1-success
+|-
+|YPMessage:	||string||Any error message
+|}
+==== Remove ====
-== New to be introduced features ==
+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 :
+{| class="wikitable"
+|-
+!parameter !! value !! explanation
+|-
+|action || '''remove''' || The YP protocol request type
+|-
+|sid || string || session ID
+|}
+The URL call does NOT have *optional* parameters!
-== Design goals for the new revision ==
+The listing scripts will respond with the following HTTP headers
+{| class="wikitable"
+|-
+!header !! value !! explanation
+|-
+|YPResponse:	||0;1||0-failure or 1-success
+|-
+|YPMessage:	||string||Any error message
+|}

Icecast Server/YP-protocol-v2: Difference between revisions

Latest revision as of 17:33, 19 June 2020

Contents

Overview

Known deficiencies of the old protocol

New to be introduced features

Design goals for the new revision

Old protocol - factual characteristics

Transport

Request types

Add

Touch

Remove

Navigation menu