|
|
| Line 1: |
Line 1: |
| | {{Template:NavBar}} | | {{Template:NavBar}} |
| − | = SHOUTcast Server and YP Documentation =
| |
| | | | |
| − | == SHOUTcast YP1.0 Protocol ==
| + | 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. |
| | | | |
| − | ==== Overview ====
| |
| − | 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 === | + | =SHOUTcast Overview= |
| − | ==== addsrv ====
| + | |
| − | Adds a new server to the database. Servers should make this call when they start up.
| + | |
| | | | |
| − | ''' Parameters ''' | + | 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]]''' |
| | | | |
| − | * v version. Should be set to one.
| |
| − | * 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.
| + | =Getting Started= |
| − | * 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.
| + | |
| | | | |
| | + | 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 ''' → [[SHOUTcast_Getting_Started_Guide|Getting Started Guide]]''' |
| | + | '''Important:''' You need to be happy with the use of command-line tools before attempting to install or run a |
| | + | SHOUTcast system as all versions of the v2 Server and Transcoder are designed to work as command-line tools. |
| | | | |
| − | ==== remsrv ====
| |
| − | Removes a server from the database. Servers should make this call when they shut down.
| |
| | | | |
| − | ''' Parameters '''
| + | ==Core Documentation== |
| − | *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.
| + | Here you can find the core documentation relating to all of the provided SHOUTcast v2 system tools which is the Server, Transcoder and Source DSP plug-in for Winamp. These contain details on the configuration options provided by these tools along with useful information on how the configuration of one tool relates to the other tools along with an specifics which may be experienced whilst using them. |
| | | | |
| − | * icy-response Will have the value 'ack' if successful, otherwise it will contain an error message
| + | ::'''[[SHOUTcast_DNAS_Server_2|SHOUTcast DNAS Server 2 (sc_serv)]]''' |
| − | * icy-error Extended error information
| + | |
| | | | |
| | + | ::'''[[SHOUTcast_DNAS_Transcoder_2|SHOUTcast DNAS Transcoder 2 (sc_trans)]]''' |
| | | | |
| − | ==== tchsrv ====
| + | ::'''[[Source_DSP_Plug-in|Source DSP Plug-in (dsp_sc)]]''' |
| − | Periodic "touch" 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 '''
| |
| − | * 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.
| + | ==Supporting Documentation== |
| | | | |
| − | * icy-response Will have the value 'ack' if succesful, otherwise it will contain an error message.
| + | Here you can find copies of additional documentation which is referenced by the core documentation such as the specific information which can go into the calendar.xml for usage with the Transcoder. |
| − | * icy-error Extended error information.
| + | |
| − | * icy-tchfrq New touch frequency
| + | |
| − | * icy-backup If the server becomes full, clients should be redirected here.
| + | |
| | | | |
| | + | ::'''[[Source_DSP_Plug-in_Configuration_Examples|Source DSP Plug-in Configuration Examples]]''' |
| | | | |
| | + | ::'''[[SHOUTcast_Transcoder_AJAX_api_Specification|SHOUTcast Transcoder AJAX api Specification]]''' |
| | | | |
| − | === YP1 Error List ===
| + | ::'''[[SHOUTcast_Calendar_Event_XML_File_Specification|SHOUTcast Calendar Event XML File Specification]]''' |
| | | | |
| − | # Unable to check stream connection - Cannot see your station/computer (URL: "+streamUrl+") from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
| + | ::'''[[SHOUTcast_XML_Metadata_Specification|SHOUTcast XML Metadata Specification]]''' |
| − | # 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 > 1024 - Bitrate too large.
| + | |
| − | # If bitrate < 8 - Bitrate too small.
| + | |
| − | # touch host, id, port, listeners, alt validation error – 3
| + | |
| − | # listeners > 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 / Ultravox 2.1 Protocol ==
| + | =SHOUTcast Api Documentation= |
| − | ==== 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.
| + | Here you can find some of the technical documentation about some of the SHOUTcast system from accessing the SHOUTcast Radio Directory to the streaming protocol used as well as some legacy information for historical purposes. |
| | | | |
| − | ==== Ultravox Messages ====
| + | ::'''[http://dev.aol.com/SHOUTcast/documentation/ SHOUTcast Radio Directory API Documentation]''' |
| − | 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_2_%28Ultravox_2.1%29_Protocol_Details|SHOUTcast / Ultravox 2.1 Protocol Details]]''' |
| | | | |
| − | 0 1 2 3 4 5
| + | ::'''[[SHOUTcast_YP_1.0_Protocol_Details|SHOUTcast YP 1.0 Protocol Details]]''' |
| − | 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="wikitable"
| + | |
| − | |-
| + | |
| − | !
| + | |
| − | ! 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 > 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
| + | |
| − | | + | |
| − | = SHOUTcast 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 <A HREF= "http://my.host.com:8000/content/song.pls">here</A>
| + | |
| − | :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 DSP Plug-in =
| + | |
| − | | + | |
| − | Information on how to use the Source DSP plug-in and the options it provides can be found [[Source_DSP_Plug-in|here]].
| + | |
| − | | + | |
| − | Additionally if you have installed the plug-in then there is a copy of dsp_sc_config.txt which shows what you need to enter from the v2 DNAS Server or Transcoder configuration files in-order to get the plug-in working with the Server or Transcoder.
| + | |
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.
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
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 → Getting Started Guide
Here you can find the core documentation relating to all of the provided SHOUTcast v2 system tools which is the Server, Transcoder and Source DSP plug-in for Winamp. These contain details on the configuration options provided by these tools along with useful information on how the configuration of one tool relates to the other tools along with an specifics which may be experienced whilst using them.
Here you can find copies of additional documentation which is referenced by the core documentation such as the specific information which can go into the calendar.xml for usage with the Transcoder.
Here you can find some of the technical documentation about some of the SHOUTcast system from accessing the SHOUTcast Radio Directory to the streaming protocol used as well as some legacy information for historical purposes.
