Difference between revisions of "SHOUTcast Broadcaster"

From Winamp Developer Wiki
Jump to: navigation, search
(Getting Started)
 
(41 intermediate revisions by 4 users not shown)
Line 1: Line 1:
=[http://ynodyky.co.cc Page Is Unavailable Due To Site Maintenance, Please Visit Reserve Copy Page]=
+
{{Template:NavBarSC}}
{{Template:NavBar}}
+
= SHOUTcast Server and YP Documentation =
+
  
== SHOUTcast YP1.0 Protocol ==
 
  
==== Overview ====
+
Here you can find copies of the Shoutcast tools documentation and other information relating to using the Shoutcast v2 system from the tools to details about the the SHOUTcast Radio Directory API. Most of the documentation is also provided in the installers / distribution files of the different Shoutcast v2 system tools though the versions provided here should typically contain the most up-to-date version of the documentation relating to the currently provided version of the tools.
The YP protocol provides a way for shoutcast servers and relays to register themselves so they are searchable on the shoutcast.com web page and directory. The API is a collection of HTTP GET requests, which provide the necessary functionality.
+
  
=== Functions ===
 
==== addsrv ====
 
Adds a new server to the database. Servers should make this call when they start up.
 
  
''' Parameters '''
+
=Shoutcast Overview=
  
* v version. Should be set to one.
+
This provides a look at how the Shoutcast v2 system is designed to work along with some examples on different configurations of the Shoutcast tools for getting a valid Shoutcast system ''' → [[SHOUTcast_System_Overview|Shoutcast System Overview]]'''
* br bitrate. Bitrate in kbs
+
* p IP port for client connections
+
* m maximum client connections
+
* r This parameter is only provided if this server is relaying another server. If so, the value is <addr>:<port> of the relayed server.
+
* t Name or title of stream
+
* g Station genre
+
* url URL of broadcaster
+
* content   Mime-type for content (audio/mpeg or audio/aacp)
+
* irc IRC address of broadcaster
+
* icq ICQ address of broadcaster
+
* aim AIM id of broadcaster
+
* sid Stream id if relevant
+
  
An HTTP response of 200 indicates the possibility of success. Further information is available in the response headers.
 
* icy-response Will have the value 'ack' if successful, otherwise it will contain an error message.
 
* icy-id ID assigned to the server. Value should be checked for zero, which is invalid.
 
* icy-error Extended error information.
 
* icy-tchfrq Touch frequency in minutes. The server should call the YP function tchsrv at this interval.
 
  
 +
=Getting Started=
  
==== remsrv ====
+
''' → [[SHOUTcast_Getting_Started_Guide|Getting Started Guide]]'''<br/>
Removes a server from the database. Servers should make this call when they shut down.
+
This is a step by step guide for how to get going with creating a Shoutcast v2 system based around the provided example configuration files included with the current versions of the Shoutcast tools and the Core documentation also provided
  
''' Parameters '''
+
'''Important:''' You need to be comfortable with the use of command-line tools before attempting to install or run a Shoutcast server since the software is designed to be run using command-line tools. (HTML management is supported once the server is running)
*id ID provided in response to addsrv function
+
* p IP port for client connections
+
  
An HTTP response of 200 indicates the possibility of success. Further information is available in the response headers.
+
Current versions of Shoutcast can be obtained from:
  
* icy-response Will have the value 'ack' if successful, otherwise it will contain an error message
+
::'''[https://shoutcast.com/Pricing  Shoutcast Downloads]'''
* icy-error Extended error information
+
::or
 +
::'''[https://radiomanager.shoutcast.com/RMO/user/your-plan RadioManager Profile]''' (requires account)
  
  
==== tchsrv ====
+
==Documentation / Help Files==
Periodic &quot;touch&quot; function that updates various information about the server. This function should be called at an interval as indicated by the icy-tchfrq response field to '''addsrv'''
+
  
''' Parameters '''
+
::'''[[SHOUTcast_DNAS_Server_2|Shoutcast DNAS Server v2 Core Documentation]]'''
* id Server ID as provided by the addsrv function
+
* p IP port for client connections
+
* li Number of listeners currently connected.
+
* alt Average user listen time in seconds
+
* ct Current song title
+
* cm Number of clients connected more than 5 minutes since last tchsrv
+
* ht Number of client connects since last tchsrv
+
  
An HTTP response of 200 indicates the possibility of success. Further information is available in the response headers.
+
This link contains detailed documentation relating to the Shoutcast 2.x DNAS software. These documents contain details on the configuration options provided along with useful information on the configuration along with specifics situations which may be experienced.
  
* icy-response Will have the value 'ack' if succesful, otherwise it will contain an error message.
+
==Supporting Documentation==
* icy-error Extended error information.
+
* icy-tchfrq New touch frequency
+
* icy-backup If the server becomes full, clients should be redirected here.
+
  
 +
Here you can find additional documentation which is helpful for many broadcasting setups:
  
  
=== YP1 Error List ===
+
::'''[[SHOUTcast_Authhash_Management|Shoutcast Authhash Management]]'''
  
# Unable to check stream connection - Cannot see your station/computer (URL: &quot;+streamUrl+&quot;) from the Internet, disable Internet Sharing/NAT/firewall/ISP  cache.
+
::'''[[SHOUTcast_Listing_Requirements|Shoutcast Listing Requirements]]'''
# If we find ‘Location:’ string in the stream content - Terms of Service violator.  You are being reported.
+
# If we find ‘SlamCast’ string in the stream content - Incompatible protocol.
+
# If we find ‘HTTP/1.0 401 Unauthorized’ string in the stream content - Streams requiring authorization are not public and cannot list here.
+
# If we found ‘ICY 400 Server Full’ or ‘HTTP/1.0 400 Server Full’ string in the stream content - Cannot verify server since all listener slots are full.  Please wait.
+
# If we found ‘icecast’ string in the stream content - Icecast too easy to hack YP, use SHOUTcast instead.
+
# IP ban - This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service.
+
# If website contains ‘hTtP’ - We no longer list stations utilizing the auto-popup url option
+
# Improper version - Upgrade to SHOUTcast 1.8 or newer.
+
# No station name validation - Please give your station a name (in the dsp plugin YP tab).
+
# No Genre - Please identify this station's genre (in the dsp plugin YP tab).
+
# Capacity 0 - You must have at least 1 maxuser.
+
# Improper bitrate - Invalid bitrate.
+
# Port cannot be zero.
+
# If station name contains either ‘mp3pro’ or ‘mp3 pro’ - Mp3pro format must be nsv-encapsulated to list here.
+
# Content type - We do not currently list servers not streaming AAC+, MP3, or NSV.
+
# Video streams must be at least 64kbps to list here.
+
# If bitrate &gt; 1024 - Bitrate too large.
+
# If bitrate &lt; 8 - Bitrate too small.
+
# touch host, id, port, listeners, alt validation error – 3
+
# listeners &gt; 5000, host not set in the request – 99
+
# if touch filed to update DB – 100 if update count is 0, else 100 + count of updated records.
+
# If primary is not public or relay could not register for some reason - Relay url could not register. Try by making primary source public or wait till primary registers.
+
  
 +
::'''[[SHOUTcast_Server_CDN_Features|Shoutcast Server CDN Features]]'''
  
== SHOUTcast / Ultravox 2.1 Protocol ==
+
::'''[[SHOUTcast_Server_Source_Support|Shoutcast Server Source (Encoder) Support]]'''
==== Overview ====
+
The SHOUTcast / Ultravox Protocol is an application level streaming protocol that encapsulates stream data in order to abstract the underlying data encoding.  The protocol defines the structure of the encapsulation as well as the series of handshakes necessary for setting up a streaming session.  It describes the handshaking necessary between the broadcaster and the distribution point as well as the handshaking necessary between the listener and the distribution point.  At this time the protocol is not codec dependent, nor is it transport dependent.  The protocol is designed with network performance, compatibility, and simplicity in mind. 
+
  
At a high level, the broadcaster opens a connection to the distribution point.  It provides authentication information and stream details to the distribution point.  The distribution point parses the provided information, authenticates the user and then either sets up for streaming the broadcast feed, or denies the broadcaster access.  Similarly, a listener may connect to the distribution point, provide authentication information, and request a particular stream.  The distribution point will either allow or deny the listener and if allowed will start sending stream data to the listener from it’s internal stream buffer.  Recommendations for features of the distribution point buffering scheme and connection handling are also mentioned here, but are an implementation detail and the protocol may lend itself for better solutions based on the streaming architecture.
+
::'''[[SHOUTcast_DNAS_Server_2_XML_Reponses|Shoutcast DNAS Server 2 XML Reponses]]'''
  
==== Ultravox Messages ====
+
::'''[[SHOUTcast_YP_Nak_Errors|Shoutcast YP Nak Error Information]]'''
The mechanism by which Ultravox is able to abstract the underlying stream encoding is encapsulation within a simple message structure.  Once a broadcaster or listener is connected to the distribution point, Ultravox messages will be the sole communication mechanism.
+
  
The basic Ultravox message format is:
+
::'''[[SHOUTcast_DNAS_Upgrade|Updating a Shoutcast v1 server]]'''
 
+
0          1          2          3          4          5     
+
0101 1010  AAAA BBBB  CCCC DDDD  DDDD DDDD  EEEE EEEE  EEEE EEEE  F…………...F 0000 0000
+
Sync      Res  QoS  Class Type            PayLoad Length        Payload  0x00
+
 
+
[Sync byte5A][reserved/QoS][4 bit msg class][12 bit msg type][16 bit msg length][N byte payload][0x00 byte]
+
 
+
Note: All values of the message are network byte order.
+
 
+
Sync Byte (0x5A)
+
 
+
:The sync byte is used to distinguish the beginning of an ultravox message.  It allows the listener to seek to a potential valid frame if data gets corrupted between the distribution point and the listener.
+
 
+
Reserved (A)
+
QoS (B)
+
 
+
:QoS information may be passed in the low 4 bits of the reserve byte.  The QoS is a four bit value whose high bit specifies whether this packet has to be delivered (useful for UDP).  The other 3 bits are the relative priority for send queue.  The high 4 bits are currently unused.
+
 
+
Message Class (C)
+
 
+
:The message class is used in combination with the message type to uniquely identify an Ultravox message.  The reason for separating the unique identifier into two units is for performance reasons.  The message classes are defined so that the distribution point can look at the message class and decide whether it needs to examine the payload.  Examining the payload requires extra parsing on the part of the distribution point and so will affect the performance when we talk about heavy load.  The message classes are defined as:
+
 
+
{| class=&quot;wikitable&quot;
+
|-
+
!
+
! class
+
! description
+
|-
+
| 0x0
+
| Operations
+
| Not Defined
+
|-
+
| 0x1
+
| Broadcaster
+
| BroadcasterDistribution point
+
|-
+
| 0x2
+
| Listener
+
| Distribution pointListener
+
|-
+
| 0x3
+
| Cacheable Metadata
+
| BroadcasterListener via distribution point
+
|-
+
| 0x4
+
| Cacheable Metadata
+
| BroadcasterListener via distribution point
+
|-
+
| 0x5
+
| Pass-through Metadata
+
| BroadcasterListener via distribution point
+
|-
+
| 0x6
+
| Pass-through Metadata
+
| BroadcasterListener via distribution point
+
|-
+
| 0x7
+
| Data
+
| Encoded data (ex: 0x7000 is MP3)
+
|-
+
| 0x8
+
| Data
+
| Encoded data (ex: 0x8003 is aac/aacplus, 0x8001 is ogg vorbis, 0x7777 is nsv)
+
|}
+
 
+
 
+
Message Type (D)
+
 
+
:The message type is 12 bits in the message header that specify the type of data encapsulated in the message. See Table 1 for details on specific message types.
+
 
+
Message Length (E)
+
 
+
:The message length is the fifth and the sixth byte of the message header.  It specifies the length of the payload following the message header.
+
Note: The message length does not include the trailer 0x00 byte.
+
 
+
Payload (F)
+
 
+
:The payload contains the data for each message.  The payload size is not restricted by the protocol.  However, the protocol specifies how a broadcaster, distribution point, and listener need to negotiate and report the maximum size message that will be sent in a single datastream.  Some implementations may require that the messages stay under MTU, in which case the distribution point could enforce this during max-payload-size negotiation.
+
 
+
Trailing 0x00
+
 
+
:The trailing 0x00 in the payload is used by the listener to determine if a message is malformed.  See the Stream Syncing section to learn about how a client finds their place in the datastream if corrupted messages are encountered.
+
 
+
==== Broadcast Messages ====
+
 
+
The broadcast protocol describes the message requests from the broadcaster to the distribution point and responses by the distribution point.  The messages are used to authenticate the broadcaster, deliver details about the stream to be broadcasted, manage the stream, and terminate the stream.
+
For most requests made by a broadcaster, the distribution point normally sends the same message class and type back to the broadcaster as a response, indicating success or failure of the request in the encapsulated payload.
+
 
+
The message types shown below require a payload formatted according to the following criteria:
+
# The existence of payload data is indicated by a message length &gt; 0
+
# All payloads for broadcaster messages are ASCIIZ strings (i.e., ASCII-encoded and terminated by a ‘\0’). 
+
# Parameters within the payload are separated by a single colon (“:”) character
+
 
+
Broadcast messages are defined as:
+
 
+
Class
+
Type
+
Description
+
Required?
+
Payload?
+
Response?
+
0x1
+
0x000
+
N/D
+
N/A
+
N/A
+
N/A
+
0x1
+
0x001
+
Authenticate Broadcast
+
Yes
+
Yes
+
Yes
+
0x1
+
0x002
+
Setup Broadcast
+
Yes
+
Yes
+
Yes
+
0x1
+
0x003
+
Negotiate Buffer Size
+
Yes
+
Yes
+
Yes
+
0x1
+
0x004
+
Standby
+
Yes
+
No
+
Yes
+
0x1
+
0x005
+
Terminate
+
No
+
No
+
No
+
0x1
+
0x006
+
Flush Cached Metadata
+
No
+
No
+
No
+
0x1
+
0x007
+
Require Listener Auth
+
No
+
Yes
+
Yes
+
0x1
+
0x008
+
Negotiate Max Payload Size
+
Yes
+
Yes
+
Yes
+
0x1
+
0x009
+
Request Cipher
+
Yes
+
No
+
Yes
+
0x1
+
0x040
+
Stream mime type
+
Yes
+
Yes
+
Yes
+
0x1
+
0x050
+
File transfer begin
+
No
+
Yes
+
Yes
+
0x1
+
0x051
+
File transfer data
+
No
+
Yes
+
Yes
+
0x1
+
0x100
+
Configure ICY-NAME
+
No
+
Yes
+
Yes
+
0x1
+
0x101
+
Configure ICYGENRE
+
No
+
Yes
+
Yes
+
0x1
+
0x102
+
Configure ICYURL
+
No
+
Yes
+
Yes
+
0x1
+
0x103
+
Configure ICYPUB
+
No
+
Yes
+
Yes
+
 
+
 
+
There are six major phases of broadcaster communication with the distribution point:
+
# Cipher key exchange
+
# Connect/Authentication
+
# Stream Configuration
+
# Intro/backup file transfer
+
# Standby/Data transfer
+
# Broadcast termination
+
 
+
= SHOUTcas DNAS / SC_SERV =
+
 
+
;1. How do I use the on-demand content features of the DNAS?
+
:Answer: The DNAS installs with a folder called content/. Place any MP3 files inside this directory, and they're ready to be streamed on-demand. The server will even automatically generate a playlist for any individual item of content so you can have browsers automatically pass the content off to a player without having to make playlists yourself.
+
 
+
:Example: Your server has a file called song.mp3 in the content/ folder. Your SHOUTcast Radio DNAS is running on port 8000 at my.host.com.
+
:You can listen to my song &lt;A HREF= &quot;http://my.host.com:8000/content/song.pls&quot;&gt;here&lt;/A&gt;
+
:NOTE: The file song.pls DOES NOT EXIST in your content directory! If a file with the same name exists with the .mp3 extension, the DNAS will automatically generate the .pls file.
+
:NOTE: Subdirectories DO NOT work for the content section, to help prevent malicious users from tramping around your filesystem.
+
 
+
;2. Why does the SHOUTcast Radio directory think I'm at a different IP than I really am?
+
:Answer: The SHOUTcast Radio directory used to run on the honor system. That was, it took you at your word on what IP you were broadcasting at. Since about twenty billion people abused that to send people to not-so-friendly sites, now the directory forces the listed IP to the same IP that sends it the info. Since many ISPs now use content caching on port 80 (the same port that directory data comes from), a different IP address can sometimes appear in the directory. There isn't any solution for this at the moment, save having your ISP disable forced proxying of your address.
+
 
+
;3. I'm behind a firewall/proxy. Can I still use the DNAS to broadcast?
+
:Answer: Tricky question. Users behind proxies cannot. Users behind NAT devices can, *provided* the same port the SHOUTcast Radio server runs on is set up to forward from the NAT device to the SHOUTcast Radio server. Users behind firewalls can also get a hole punched so listeners can penetrate. If broadcasters also need to get in from the outside world, you should open the hole for PortBase + 1 (i.e. id SHOUTcast Radio runs on 8000, 8001 should be open for broadcasters to get through as well.)
+
 
+
= SOURCE PLUG-IN =
+
 
+
;1. How do I use advanced mode?
+
:Answer: Read the README that comes with the plug-in. It explains how to make things like crossfading, cd-audio, and voiceovers work. Also, there's a ScreenCam guide which will show exactly what to do.
+

Latest revision as of 15:42, 4 November 2018

Shoutcast Home | Shoutcast Server (DNAS) | Shoutcast Developer (API) | Shoutcast For Business & Revenue Generation | Shoutcast DSP (encoder Plug-In for Winamp)


Here you can find copies of the Shoutcast tools documentation and other information relating to using the Shoutcast v2 system from the tools to details about the the SHOUTcast Radio Directory API. Most of the documentation is also provided in the installers / distribution files of the different Shoutcast v2 system tools though the versions provided here should typically contain the most up-to-date version of the documentation relating to the currently provided version of the tools.


Shoutcast Overview

This provides a look at how the Shoutcast v2 system is designed to work along with some examples on different configurations of the Shoutcast tools for getting a valid Shoutcast system Shoutcast System Overview


Getting Started

Getting Started Guide
This is a step by step guide for how to get going with creating a Shoutcast v2 system based around the provided example configuration files included with the current versions of the Shoutcast tools and the Core documentation also provided

Important: You need to be comfortable with the use of command-line tools before attempting to install or run a Shoutcast server since the software is designed to be run using command-line tools. (HTML management is supported once the server is running)

Current versions of Shoutcast can be obtained from:

Shoutcast Downloads
or
RadioManager Profile (requires account)


Documentation / Help Files

Shoutcast DNAS Server v2 Core Documentation

This link contains detailed documentation relating to the Shoutcast 2.x DNAS software. These documents contain details on the configuration options provided along with useful information on the configuration along with specifics situations which may be experienced.

Supporting Documentation

Here you can find additional documentation which is helpful for many broadcasting setups:


Shoutcast Authhash Management
Shoutcast Listing Requirements
Shoutcast Server CDN Features
Shoutcast Server Source (Encoder) Support
Shoutcast DNAS Server 2 XML Reponses
Shoutcast YP Nak Error Information
Updating a Shoutcast v1 server