http://wiki.winamp.com/api.php?action=feedcontributions&user=DrO&feedformat=atomWinamp Developer Wiki - User contributions [en]2024-03-29T15:53:48ZUser contributionsMediaWiki 1.22.3http://wiki.winamp.com/wiki/SHOUTcast_DNAS_Server_2SHOUTcast DNAS Server 22015-06-10T18:31:14Z<p>DrO: Update supported comments</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The purpose of this document is to show you the different configuration options supported by sc_serv along with basic and more advanced example configurations to enable you to get started with using sc_serv and the features it can offer.<br />
<br />
The aim of sc_serv is to provide enhanced serving features and also access to the new YP2 infrastructure whilst maintaining as much backward compatibility with previous versions of sc_serv as possible. The new features introduced include:<br />
<br />
# Serving multiple streams from a single server instance<br />
# Relaying multiple streams from a single server instance<br />
# Multiplexing all server activity through a single IP port<br />
# SHOUTcast 2 wire protocol support for sources, relays and clients<br />
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients<br />
# YP2 infrastructure support<br />
# Real-time metadata and statistic reporting<br />
# Static station id support<br />
# In-stream metadata in standardised xml files<br />
# UTF-8 and international character encoding<br />
# Improved server and stream security<br />
<br />
<br />
==Overview of Features==<br />
<br />
To take full advantage of the newer features provided as part of the SHOUTcast 2 and YP2 systems then you will need to ensure you are using a compatible version of sc_serv (any version 2 will work) and that you have the required authorisation key to register as a broadcaster on the YP2 directory (see [[#Getting_Started|section 3.0]]).<br />
<br />
If you were intending on taking full advantage of the multiplexing and multiple stream support offered as part of sc_serv then you would need to make sure you enable the SHOUTcast 2 options (this is enabled by default with server builds from the end of 2010 if the 'yp2' option in the configuration file is not specified [see [[#YP_Server_Behaviour|section 4.14]] ). The reason for needing to enable this support is if you try to do it with the original SHOUTcast 1 protocol then it will not work as the original protocol has no means of expressing multiple streams from a single port due to the lack of an identifier provided for them.<br />
<br />
If you are planning on connecting multiple sc_trans instances to sc_serv then you must use the SHOUTcast 2 protocol support so that each sc_trans instance can have a unique identifier which allows for multiple streams to then be provided from a single server. It is still possible for an older source to connect to the server with a number of config options available to support this though functionality will be limited compared to what can be done with a fully supporting SHOUTcast 2 source.<br />
<br />
Finally clients connecting to your server do not need to directly support SHOUTcast 2 as sc_serv will repackage the stream data and any related metadata into the correct format the client requests (typically based on the user agent detected by the server).<br />
<br />
<br />
==Getting Started==<br />
<br />
One of the key aspects of the new YP2 directory infrastructure is an authorisation key which is used to validate your server when it tries to connect to the YP2 infrastructure for any of the station(s) you run. Once this key is obtained, it will be valid for all root servers of the station being broadcast.<br />
<br />
This can be done by going to the [[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]] page which shows how to do this via the 'Administation Summary' page as long as a valid source has been connected to the server. This process automatically updates your configuration file(s) with the new authhash and if the stream is set to be public then will attempt to get the stream listed in the SHOUTcast Radio Directory.<br />
<br />
When using an older SHOUTcast 1 server then you do not need to do this registration and the server will still be able to be listed on the directory but there is not the same level of protection over the stream as is the case with registering it.<br />
<br />
<br />
===Running the Server===<br />
----<br />
<br />
The server is able to be run either as a console application or it can be run as service (Windows) or daemon (Linux / Mac OS X / BSD). Detailed below is how to get the server running on the different operating systems supported by it.<br />
<br />
<br />
===Windows===<br />
----<br />
<br />
The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.<br />
<br />
Please note that the Windows versions of sc_serv are built with a dependency against the Microsoft Visual C++ 2008 SP1 Redistributable Package. If sc_serv is unable to start due to a dependency issue then you will need to install the correct version of the package so it can run which depends on the version of sc_serv you are attempting to run:<br />
<br />
32-bit version:<br />
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2<br />
<br />
64-bit version:<br />
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e<br />
<br />
<br />
====Install as a Service====<br />
----<br />
<br />
sc_serv.exe install <servicename> <username> <password> <conf><br />
<br />
<servicename> - Name of service<br />
Typically enter this as 'sc_serv' though you can use a different name but you will need<br />
to remember it as it is required to be the same when using the 'uninstall' mode.<br />
<br />
<username> - User under which to run the service as or '0' for the local system<br />
<br />
<password> - Password for user or '0' for the local system or with no password<br />
<br />
<conf> - File path to the configuration file<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
When run as a service there is not a good sense of a current working directory so requires all paths in the configuration and playlist files to be fully qualified otherwise lookups will fail when sc_serv is run.<br />
<br />
To run sc_serv with a configuration file in the same folder as the server as the current system user account you would enter into the console:<br />
<br />
sc_serv.exe install sc_serv 0 0 sc_serv.conf<br />
<br />
<br />
====Uninstall the Service====<br />
----<br />
<br />
sc_serv.exe uninstall <servicename><br />
<br />
<servicename> - Name of service as used when the service was registered<br />
<br />
To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:<br />
<br />
sc_serv.exe uninstall sc_serv<br />
<br />
<br />
====Run as a Non-Service in the Console====<br />
----<br />
<br />
sc_serv.exe <conf><br />
<br />
<conf> - File path to the configuration file (can be relative or absolute)<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
<br />
===Linux / Mac OS X / BSD===<br />
----<br />
<br />
Remember to enable the required access on the sc_trans file by doing 'chmod a+x sc_trans' after extracting it from the distribution file otherwise the OS is likely to not run it and show the error message './sc_serv: Permission denied'.<br />
<br />
====Run as a Daemon====<br />
----<br />
<br />
./sc_serv daemon <conf><br />
<br />
<conf> - File path to the configuration file (required in all cases)<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
'''e.g.'''<br />
./sc_serv daemon ./sc_serv.conf<br />
<br />
When run this should output the following:<br />
<br />
'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.<br />
<br />
<br />
====End a Daemon====<br />
----<br />
<br />
kill -SIGTERM <pid><br />
or<br />
kill -15 <pid><br />
or<br />
kill -s TERM <pid><br />
<br />
<pid> - The PID of the daemon instance (reported when the daemon started or can be found with 'ps ax | grep sc_serv' as long as sc_serv was the file run otherwise you can just use 'ps ax' if the filename isn't known). Additionally the PID of sc_serv is listed in the log file.<br />
<br />
<br />
====Run as a Non-Daemon====<br />
----<br />
<br />
./sc_serv <conf><br />
<br />
<conf> - File path to the configuration file (can be relative or absolute)<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
<br />
===Additional Signals===<br />
----<br />
<br />
When run on Linux / Mac OS X / BSD then some additional signals are supported to allow for additional control over the running daemon instance of sc_serv.<br />
<br />
The following signals can be used with the 'kill' command (in the manner of your choosing for using the kill command) along with the <pid> of the daemon instance to do one of the following actions:<br />
<br />
SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)<br />
SIGHUP - Rotates logfile, w3clog and streamw3clog<br />
<br />
The result of SIGHUP is that the current log file contents will be moved into <logfile>_1 e.g. sc_serv_1.log, <logfile>_1 will be moved into <logfile>_2 e.g. sc_serv_2.log and so on for all log files which can be found which match the current log file's name. This is useful if timed to have it create day specific log files.<br />
<br />
These signals are not supported by the Windows version of sc_serv which will only<br />
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.<br />
<br />
<br />
==Configuration File==<br />
<br />
Here you can find a complete list of all of the configuration options which are provided by sc_serv which ranges from logging to networking configuration and control over the media being used when streaming via the server.<br />
<br />
Configuration entries labelled as ''<MULTI>'' can be used to set up simultaneous connections to the server or allow for multiple connections from various sources. These are specified by adding _# to the end of the option's name as shown below where # begins with one. If you are only working with a single instance then you do not need to add the _# part as any instances of a configuration option will assume it is for _1.<br />
<br />
Note: The ''<MULTI>'' system is not hierarchical and all values beyond the default must be specified for all connections. So for example, if you wanted to connect to two servers on the same port you must do:<br />
<br />
serverport_1=8080<br />
serverport_2=8080<br />
serverip_1=www.server1.com<br />
serverip_2=www.server2.com<br />
<br />
Note that you CANNOT do it like this as it leads to not all values being set:<br />
<br />
serverport=8080<br />
serverip_1=www.server1.com<br />
serverip_2=www.server2.com<br />
<br />
The configuration files also allow for notes or options to be disabled by the use of a semi-colon (''';''') or a left bracket ('''[''') or the hash / pound symbol ('''#''') at the start of a line which can be seen in all of the configuration examples.<br />
<br />
Known options in the configuration files are recognised irrespective of the case they are entered in the configuration file so maxuser and MaXuSer will be handled the same way.<br />
<br />
Any items found in the configuration file which are not known (as detailed in following sections) or is not processed as a comment will be reported in the following manner:<br />
<br />
<date + time> W msg:[CONFIG] Invalid item on line XX<br />
<br />
Where <date + time> is the date and time the event happens at and XX is the line in the configuration file where the error has been found to occur at.<br />
<br />
<br />
===Banning===<br />
----<br />
<br />
'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''<br />
<br />
'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''<br />
<br />
If you are using a folder for saving the file into then you need to ensure that the<br />
folder already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Client Behaviour===<br />
----<br />
<br />
'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''<br />
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the<br />
maximum limit on the number of client connections allowed to connect to the server instance.<br />
<br />
'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''<br />
A value of zero means there will be no time limit.<br />
<br />
'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''<br />
<br />
'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''<br />
<br />
'''dstip''' or '''destip''' : Specify the server side binding address for clients ''[Default = <no value>]''<br />
If 'any' or no value is specified then sc_serv listens to all addresses.<br />
<br />
If you specify a value for 'dstip / destip' then this will be used by the listen feature on the Administration Pages (see section 5.1) so it can provide a valid stream url in the generated playlist. If 'dstip / destip' is not specified then the server will attempt to auto-generate the IP required for the client to be able to connect. If this fails the generated playlist is likely to return a stream url like <nowiki>http://0.0.0.0:<portbase>/<path></nowiki><br />
<br />
The IP provided needs to be in a valid format like <nowiki>http://<my-ip></nowiki> or an address which can be resolved to an IP otherwise the internal lookups done are likely to fail (depends upon the server configuration and OS being used). Also you cannot set srcip and dstip / destip to be the same IP value and if this happens then the server will close. Closing of the server will also happen if the IP cannot be resolved or correctly bound to i.e. server is not there or an invalid value was entered.<br />
<br />
'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''<br />
<br />
'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''<br />
<br />
<br />
===Debugging===<br />
----<br />
<br />
In all cases, the default value is for no debug logging for the options listed below.<br />
<br />
'''yp1debug''' : Enable debug logging of YP connections<br />
<br />
'''yp2debug''' : Enable debug logging of YP2 connections<br />
<br />
'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections<br />
<br />
'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections<br />
<br />
'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients<br />
<br />
'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients<br />
<br />
'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays<br />
<br />
'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays<br />
<br />
'''relaydebug''' : Enable debug logging of common relay code<br />
<br />
'''streamdatadebug''' : Enable debug logging of common streaming code<br />
<br />
'''httpstyledebug''' : Enable debug logging of http style requests<br />
<br />
'''statsdebug''' : Enable debug logging of statistics<br />
<br />
'''microserverdebug''' : Enable debug logging of common server activity<br />
<br />
'''threadrunnerdebug''' : Enable debug logging of the thread manager<br />
<br />
'''rtmpclientdebug''' : Enable debug logging of rtmp clients<br />
<br />
<br />
===Flash Security===<br />
----<br />
<br />
'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''<br />
<br />
<br />
===Introduction and Backup Files===<br />
----<br />
<br />
'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''<br />
<br />
'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''<br />
<br />
'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''<br />
<br />
'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''<br />
<br />
<br />
===Logging===<br />
----<br />
<br />
'''log''' : Enable logging of the servers output ''[Default = 1]''<br />
<br />
'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''<br />
If log=0 then this option is ignored due to no logging happening.<br />
<br />
'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''<br />
<br />
'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''<br />
<br />
If you are using a folder for saving the logs into then you need to ensure that the folder<br />
already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Miscellaneous===<br />
----<br />
<br />
'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''<br />
<br />
'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''<br />
<br />
'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''<br />
<br />
'''unique''' : Specify a substitution string for the '$' character to be used when processing filenames which if specified will set any occurences of '$' to the value set. This will be used in the processing of the following filenames: '''logfile''', '''introfile''', '''streamintrofile''', '''backupfile''', '''streambackupfile''', '''banfile''', '''streambanfile''', '''ripfile''', '''streamripfile''', '''include''', '''w3clog''', '''streamw3clog'''<br />
<br />
So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is<br />
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'<br />
<br />
'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''<br />
<br />
You can do multiple calls of this allowing for a basic configuration file with then 'specific' stream configurations set in individual conf files though you need to ensure not to include a reference to the same file in itself.<br />
<br />
You can also specify a path with a wildcard for sc_serv to use to find multiple configuration files to include '''e.g.''' 'include=stream/*.conf'. This can then be used along with the multiple stream configurations (see section 4.12) and the admin command 'admin.cgi?mode=reload' (see section 5.1) to add / remove / update stream configurations without having to close the server to apply them.<br />
<br />
'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''<br />
<br />
This can accept the following parameters:<br />
<br />
:admincssfile='''v1''' - Uses the v1 DNAS style<br />
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style<br />
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki><br />
<br />
If using a custom css file, if it does not exist on the first try to load it the server will revert to<br />
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.<br />
<br />
'''faviconfile''' : Specify the file to be returned as the favicon.ico when the administration pages are being queried by the client's browser ''[Default = <no value>]''<br />
<br />
The default behaviour is to use a SHOUTcast themed built-in icon file and support / handling the update of this will entirely depend on the browser.<br />
<br />
'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''<br />
<br />
Ensure this is correct for the type of image being used so it is valid.<br />
<br />
'''hidestats''' : Specify if the publically accessible stats?sid=# page can be accessed or if it is only available via the private administration pages ''[Default = 0]''<br />
<br />
'''robotstxtfile''' : Specify the file to be returned as the robots.txt when queried by search engines, etc to attempt to prevent incorrect access to the server's pages which may cause invalid client connections ''[Default = <no value>]''<br />
<br />
The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.<br />
::User-agent:*<br />
::Disallow:/<br />
<br />
<br />
===Networking===<br />
----<br />
<br />
'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''<br />
<br />
'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''<br />
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.<br />
<br />
'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''<br />
A value of zero means there is no timeout of an idle source.<br />
Also if you set this too low then it is likely that valid sources will<br />
fail to connect during the initial stages of a source connection.<br />
<br />
'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''<br />
<br />
'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''<br />
<br />
'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''<br />
<br />
'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''<br />
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).<br />
<br />
<br />
===Network Buffers===<br />
----<br />
<br />
'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''<br />
<br />
'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''<br />
<br />
'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''<br />
<br />
'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''<br />
<br />
<br />
===Relaying===<br />
----<br />
<br />
'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''<br />
<br />
'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''<br />
<br />
'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''<br />
Setting this to 0 will disable attempts for the relay to reconnect.<br />
<br />
'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''<br />
This generally applies only to YP1 connections and is related to the<br />
actual attempts to make and get a http response from the YP server.<br />
<br />
'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''<br />
<br />
<br />
''<Legacy Options>''<br />
<br />
'''relayport''' : Port of the source to use for the relay ''[Default: 80]''<br />
<br />
'''relayserver''' : Url of the source to relay ''[Default = <no value>]''<br />
<br />
Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method<br />
of setting up a relay. These options are only provided as a means for loading<br />
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.<br />
<br />
<br />
===Reserved List===<br />
----<br />
<br />
'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''<br />
<br />
'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''<br />
<br />
'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''<br />
<br />
If you are using a folder for saving the file into then you need to ensure that the folder<br />
already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Stream Configuration===<br />
----<br />
<br />
'''Important Note:''' If you do not specify an identifier (_#) on the end of the above options then it will be treated like _1 (effectively acting like SHOUTcast 1). Additionally, _0 is not a supported identifier and will be mapped to _1.<br />
<br />
'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in our configuration file ''[Default = 0]''<br />
With this enabled, you will need to ensure that any sources have their configuration details<br />
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with<br />
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).<br />
<br />
''<MULTI>'' (one set for each stream configuration):<br />
<br />
'''streamid''' : Specify the numerical identifier of the stream for control or referencing the stream configuration. This can only be a numeric value from 1 to 2147483647.<br />
<br />
If you use multiple stream configurations then you will need to ensure the _X<br />
part is specified and correct for each stream configuration group<br />
e.g.<br />
streamid=1<br />
streampath=random<br />
or<br />
streamid_1=1<br />
streampath_1=random_stream_path<br />
streamid_2=2<br />
streampath_2=another_stream_path<br />
<br />
'''streamauthhash''' : The authorisation key needed for YP2 directory registration.<br />
This is a requirement for using the YP2 system and without it you will not be able to<br />
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).<br />
<br />
This can be used for multiple streams you are providing or can be different (as long<br />
as valid) so you can infact provide multiple stations from the same server if desired.<br />
<br />
'''streampath''' : Specify the path clients need to use to access the stream<br />
If a / is not specified on the start of the string then the server will add<br />
it to the generated path in playlist entries or other places as required so<br />
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.<br />
<br />
If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be<br />
used for client access and in generated playlist entries so that it will<br />
always be possible for clients to connect to the server somehow. See [[SHOUTcast_DNAS_Server_2#Stream_Addresses|section 6.0]] for more information on the<br />
server's stream address support.<br />
<br />
'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).<br />
Make sure if you use this that the full url is entered and that it is<br />
the url which clients would connect to for the stream to be relayed.<br />
<br />
'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''<br />
If set to zero, not specified or higher than 'maxuser' then the value set for 'maxuser' (see [[#Client_Behaviour|section 4.2]]) will be used for all knwon streams.<br />
<br />
Changing this to a value between zero and 'maxuser' will enforce the user connection limit for the specified value in the stream configuration '''e.g.'''<br />
streammaxuser_1 = 8<br />
maxuser = 32<br />
<br />
This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.<br />
<br />
With the following stream configuration<br />
streammaxuser_1 = 64<br />
maxuser = 32<br />
<br />
This allows a total of 32 connections to the server but with a per stream limit above the maximum means the maximum number of connections to the first stream group will be 32. However this also depends upon any other stream configurations and their limits as to whether 32 clients will be able to connect to this stream configuration.<br />
<br />
Finally unless a valid stream configuration is specified then this value will only be applied to the first stream configuration found i.e. there is a need to specify a streamid_XXX for streammaxuser_XXX (where XXX is the stream identifier of the stream configuration group.<br />
<br />
'''streamadminpassword''' : Specify the administrator password for accessing the remote server features for the specified stream configuration group. If this is not specified then 'adminpassword' will be used.<br />
<br />
'''streampassword''' : Specify the password for broadcasters when connecting to the server for the specified stream configuration group. If this is not specified then 'password' will be used.<br />
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).<br />
<br />
'''streampublicserver''' : This allows you to override the public flag received from the source when a connection is being made to the YP directory. If this is not specified or is set to empty then 'publicserver' will be used.<br />
<br />
'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.<br />
<br />
'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.<br />
<br />
'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.<br />
<br />
'''streamautodumpsourcetime''' : Specify how long before an idle source will be dumped from the server (in seconds). A value of zero means there is no timeout of an idle source. If not specified then 'autodumpsourcetime' will be used.<br />
<br />
'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.<br />
<br />
'''streamlistenertime''' : Specify the maximum time in minutes a client is allowed to listen to the stream. A value of zero means there will be no time limit. If not specified then 'listenertime' will be used.<br />
<br />
'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.<br />
<br />
'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.<br />
<br />
'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.<br />
<br />
'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.<br />
<br />
'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.<br />
<br />
<br />
===Web Connection (W3C) Logging===<br />
----<br />
<br />
'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''<br />
<br />
'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''<br />
<br />
If you are using a folder for saving the log into then you need to ensure that the folder<br />
already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''<br />
<br />
<br />
===YP Server Behaviour===<br />
----<br />
<br />
'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''<br />
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans<br />
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).<br />
<br />
Only change this if you really need to do so as not all SHOUTcast 2 clients will allow you to edit this value from the default value. If using the Source DSP plug-in then see [[Source_DSP_Plug-in#SHOUTcast_2_Cipher_Key|dsp_sc.txt - section 5.0]] for details on how to change the plug-in to use a differnet value.<br />
<br />
'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''<br />
YP1 only<br />
<br />
'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''<br />
<br />
If this is enabled and not all of the required values are set then the server will throw an error and will abort from its start-up attempt. It should be indicated what needs to be set to allow the server to start with this set.<br />
<br />
Additionally if there is an issue then the server will report an error in its log ouput of 'Connection attempt failed. YP2 error code is XXX (<message>)' where XXX is one of the following error codes and <message> is a message set in the error response to indicate a bit more what the error relates to. All current error codes can be found [[#YP_Server_Errors|here]].<br />
<br />
'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''<br />
<br />
'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''<br />
<br />
'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''<br />
<br />
'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''<br />
<br />
'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''<br />
This generally applies only to YP1 connections and is related to the<br />
actual attempts to make and get a http response from the YP server.<br />
<br />
'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''<br />
<br />
'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''<br />
<br />
'''publicserver''' : This allows you to override the public flag from the connected source when a connection is being made to the YP directory ''[Default = default]''<br />
This can be one of the following values:<br />
'''default''' - use the flag provided by the source<br />
'''always''' - force the source to be public<br />
'''never''' - never allow the use the flag provided by the source<br />
<br />
When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).<br />
<br />
<br />
===YP Server Errors===<br />
----<br />
<br />
If not all of the required values are set for a public listing then the DNAS server will throw an error and will abort its attempt to be listed in the Directory. It should be indicated the error is with one of the error codes provided below so it can be resolved.<br />
<br />
Additionally if there is an issue during Directory updates or removals, then the server will report an error in its log ouput as one of the following error codes and <message>.<br />
<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Status Code<br />
! Status Message<br />
|-<br />
| 400 || Generic error ''(covers all other cases usually from internal failures)''<br />
|-<br />
| 457 || Unrecoverable error while updating station information - DNAS restart required.<br />
|-<br />
| 470 || Invalid authorization hash<br />
|-<br />
| 471 || Invalid stream type (could be a bad bitrate or mime type)<br />
|-<br />
| 472 || Missing or invalid stream url<br />
|-<br />
| 473 || Server unreachable by YP<br />
|-<br />
| 474 || Relay url does not exist<br />
|-<br />
| 475 || Invalid server ID<br />
|-<br />
| 476 || Invalid max clients (value out of range or missing)<br />
|-<br />
| 477 || Terms of Service violator. You are being reported.<br />
|-<br />
| 478 || Incompatible protocol.<br />
|-<br />
| 479 || Streams requiring authorization are not public and cannot list here.<br />
|-<br />
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.<br />
|-<br />
| 481 || Cannot verify server since all listener slots are full. Please wait.<br />
|-<br />
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service<br />
|-<br />
| 483 || Invalid listeners (value out of range / missing)<br />
|-<br />
| 484 || Invalid avglistentime (value out of range / missing)<br />
|-<br />
| 485 || Invalid newsessions (value out of range / missing)<br />
|-<br />
| 486 || Invalid connects (value out of range / missing)<br />
|-<br />
| 487 || Request & Response objects are null<br />
|-<br />
| 488 || Request xml is null<br />
|-<br />
| 489 || YP command not specified<br />
|-<br />
| 490 || Generic error, while doing xml parsing<br />
|-<br />
| 491 || Generic error, while reading xml request<br />
|-<br />
| 492 || Error closing buffer / HTTP connection<br />
|-<br />
| 493 || Internal error - unable to acquire data source<br />
|-<br />
| 494 || Error updating information - DNAS restart required<br />
|-<br />
| 495 || Error acquiring station ID - DNAS restart required<br />
|-<br />
| 496 || Error converting data type<br />
|-<br />
| 497 || Inconsistent stream behaviour<br />
|-<br />
| 498 || Invalid Request (Invalid request received)<br />
|-<br />
| 499 || Error while getting information<br />
|}<br />
<br />
<br />
==Administration==<br />
<br />
With sc_serv there are administration pages available for accessing and controlling the server remotely which allows you to monitor and control clients connected to the stream (or not if banning them). These pages can now be accessed through a summary page at /index.html which will show a link to any active stream(s) or you explicitly access them via the /index.html?sid=# path where # is the ID of the stream (see [[#Stream_Configuration|section 4.12]] for more about using 'streamid') '''e.g.'''<br />
<streamurl>/index.html?sid=1<br />
<br />
If no sid or an invalid sid is passed then you will be taken to the summary /index.html and this will be applied even if you were on a page with a known ID and then enter an invalid sid or remove it purposefully.<br />
<br />
<br />
===Administration Pages===<br />
----<br />
<br />
As part of the administrative features provided there are the following pages where # is the streamid you want to use). This is not a complete list but should cover all of the pages which allow for a direct http url to be entered to get an administation action to work. The ban and reserve IP actions require input fields and do not map to direct sends.<br />
<br />
<br />
====Public Pages====<br />
----<br />
<br />
'''index.html''' - Shows a summary page with links to get to any active stream(s)<br />
<br />
'''currentsong?sid=#''' - Returns the current song title or a null response<br />
<br />
'''nextsong?sid=#''' - Returns the next song title (if known) or a null response<br />
currentsong and nextsong both provide a UTF-8 encoded string of the song title<br />
otherwise it will return effectively no response (ignoring the http header).<br />
<br />
'''nextsongs?sid=#''' - Returns in an xml format the next song title(s) (if known) to be played when using a compatible v2 stream source. See [[#XML_Responses|section 5.2]] for more details on the format of the xml returned).<br />
<br />
'''index.html?sid=#''' - Shows current status of the specified stream<br />
<br />
'''played.html?sid=#''' - Song history of specified playing history<br />
:or<br />
'''played?sid=#'''<br />
<br />
'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.<br />
:or<br />
'''listen?sid=#'''<br />
<br />
'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.<br />
<br />
'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.<br />
<br />
With the listen pages you either need to have specified an IP with 'dstip / destip'<br />
(see section 4.2) or leave empty and allow the server to attempt to auto-generate<br />
the IP required for the client to be able to connect. If this fails the generated<br />
playlist is likely to return a stream url like <nowiki>http://0.0.0.0:<portbase>/<path></nowiki><br />
<br />
'''home.html?sid=#''' or '''home?sid=#''' - Opens in a new window or tab (depending on the client browser) the 'streamurl' as specified by the stream source. If this is not set then the client will be redirected to the shoutcast.com main page.<br />
<br />
'''stats?sid=#''' - Provides an xml response for public accessibility which matches the private version from admin.cgi?sid=#&mode=viewxml&page=1. This is the modern version of the 7.html page as provided by the legacy v1 servers. See [[#XML_Responses|section 5.2]] for information on what is provided in the xml response.<br />
<br />
<br />
====Private Pages====<br />
----<br />
<br />
By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible<br />
to directly access the administration page(s) required. As well the base64 encoded version of the password<br />
can be passed as long as it is prefixed with ''YWRtaW46''<br />
e.g.<br />
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=<br />
<br />
'''admin.cgi''' - Shows the an overal summary admin page for the streams provided by the server including direct links to certain information pages (see notes about the 'admin.cgi?sid=#&mode=viewxml' command for more info)<br />
:or<br />
'''admin.cgi?sid=0'''<br />
<br />
'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information<br />
<br />
'''admin.cgi?sid=#&mode=updinfo&song=title''' <br />
:or<br />
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml''' <br />
If 'title' is not empty then it will be set as the current song title for the stream<br />
specified until the next use of this action or the next title update is received from<br />
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]<br />
instead of a v1 title.<br />
<br />
'''admin.cgi?sid=#&mode=viewlog''' - View logfile<br />
<br />
'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)<br />
<br />
The tailing option keeps adding additional log entries to the end of the view whilst the view is active.<br />
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped<br />
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.<br />
<br />
'''admin.cgi?sid=#&mode=viewban''' - Ban view which matches the ban file and allows you to ban a single IP or an IP range from it (see [[#Banning|section 4.1]] for more info on the file)<br />
<br />
'''admin.cgi?sid=#&mode=viewrip''' - Reserved IP list that matches the rip file (see [[#Reserved_IP_.28RIP.29|section 4.11]] for more info on the file)<br />
<br />
'''admin.cgi?sid=#&mode=art''' or '''admin.cgi?sid=#&mode=art&art=playing''' - Displays the artwork SHOUTcast v2 compatible clients may be able to display if the SHOUTcast v2 source does provide it.<br />
<br />
The artwork mode is primarily intended as a debugging option to make it possible<br />
to see what (if anything) has been provided by the SHOUTcast v2 source.<br />
<br />
If no '&art=' is specified or not a matching option then the stream artwork (if<br />
available) will be shown. If no '&art=playing' is specified then this will show<br />
the playing file's artwork (if available).<br />
<br />
'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information<br />
<br />
If page is not set or is outside of the range zero to 6 then this will output all of the<br />
information as the standard viewxml action does. Otherwise this only display information<br />
depending on the value assigned to page which can be from 1 to 6 which maps as follows:<br />
<br />
1 - Server Summary (this is the same as using the public stats?sid=# action)<br />
2 - Not used (previously used for Webdata Stats but not in current builds)<br />
3 - Listener Stats<br />
4 - Song History<br />
5 - Stream Metadata (if supported by the source otherwise can just be title)<br />
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)<br />
<br />
If accessing the standard viewxml or the listener stats (page = 3), you can also send<br />
'&iponly=1' which will filter the listener information (if there are any) to just output<br />
the IP instead of the additional information provided normally.<br />
<br />
'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it<br />
<br />
'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.<br />
<br />
'''admin.cgi?sid=#&mode=unripdst&ripdst=<IP>''' - Where <IP> is the IP to reserve (see [[#Reserved_IP_.28RIP.29|section 4.11]] for more information).<br />
<br />
'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.<br />
<br />
'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.<br />
<br />
'''admin.cgi?mode=rotate''' or '''admin.cgi?mode=rotate&files=log|w3c''' - This will rotate the log files set via the 'logfile', 'w3clog' and 'streamw3clog' options.<br />
If &files is specified then passing log or w3c will allow you to only<br />
rotate one type of file otherwise both will be rotated by this command.<br />
<br />
'''admin.cgi?mode=reload''' or '''admin.cgi?mode=reload&force=1''' - This reloads the stream configuration details in the main configuration file the server used when started and is only available on the admin summary page and so can only be run by the master administrator password.<br />
<br />
This command works on the server as a whole (hence no sid parameter) and it will add or<br />
remove or update any stream configuration as applicable which will cause any connected<br />
sources and clients to be kicked as applicable (usually if a stream configuration was removed).<br />
<br />
This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'<br />
in your main configuration file which the server can then use to detect different stream configurations.<br />
<br />
If '&force=1' is passed then the reload will treat the updating of active stream configurations in the<br />
same manner as a stream configuration removal instead of trying to update compatible stream configuration<br />
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.<br />
<br />
The following configuration options are updated when using this command:<br />
<br />
password or streampassword (*) streamadminpassword (#)<br />
requirestreamconfigs streamid<br />
streamauthhash streampath<br />
streamrelayurl streammaxuser<br />
streampublicserver streamallowrelay<br />
streamallowpublicrelay streamriponly<br />
streamautodumpsourcetime streamautodumpusers<br />
streamlistenertime streamintrofile<br />
streambackupfile streambanfile<br />
streamripfile<br />
<br />
(*) This will depend upon the current values versus the new configuration values<br />
(#) The master 'adminpassword' can only be changed after a restart of the server<br />
<br />
<br />
===XML Responses===<br />
----<br />
<br />
As detailed in the previous sections, some of the administration actions will provide the information in an xml response. For information on what is actually returned in these xml responses see [[SHOUTcast_DNAS_Server_2_XML_Reponses|sc_serv2_xml_responses.txt]].<br />
<br />
<br />
==Stream Addresses==<br />
<br />
Clients connecting to the streams provided by sc_serv are able to so in a number of ways depending upon how the streams have been configured and also depending upon the number of streams you have available.<br />
<br />
The two main ways for a client to connect to a stream are as follows:<br />
<br />
<serverurl>/stream/<streamid>/<br />
or<br />
<serverurl>/<streampath><br />
<br />
<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])<br />
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])<br />
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])<br />
<br />
If the client attempting to connect to the server instance does not specify <streampath> or <streamid> in the stream url it attempts to access or if only one stream is provided then the server will usually default to the first stream it knows about and will allow the client to make a valid connection (though this is not guaranteed to happen).<br />
<br />
This handling of the stream addresses provided is something to keep in mind especially if you are providing multiple streams as this will allow you to provide different addresses for certain clients to be able to use a specific stream '''e.g.''' if you wanted to have mobile clients connect to a lower bandwidth stream then you could direct them to '<serverurl>/mobile'<br />
<br />
The server options available for controlling how the stream's path is specified can be seen in [[#Stream_Configuration|section 4.12]] which also details the equivalent values needing to be set in the sc_trans configuration if you use sc_trans to provide a source to sc_serv.<br />
<br />
<br />
==Locale Error (Linux / Mac OS X / BSD)==<br />
<br />
If you receive the following error then you have a locale related issues:<br />
<br />
terminate called after throwing an instance of 'std::runtime_error'<br />
what(): locale::facet::_S_create_c_locale name not valid<br />
Abort trap<br />
<br />
If this happens then you need to set the 'POSIX' locale in your terminal's environment values. If this does not happen then everything is fine or you are using a newer version of sc_serv from the end of 2010 which should no longer exhibit this issue.<br />
<br />
Linux:<br />
export LC_ALL=POSIX<br />
<br />
BSD:<br />
setenv LC_ALL POSIX<br />
<br />
Mac OS X:<br />
export LC_ALL=POSIX<br />
<br />
You can test to see if this has worked by checking the shell command "locale":<br />
<br />
LANG=<br />
LC_COLLATE="POSIX"<br />
LC_CTYPE="POSIX"<br />
LC_MESSAGES="POSIX"<br />
LC_MONETARY="POSIX"<br />
LC_NUMERIC="POSIX"<br />
LC_TIME="POSIX"<br />
LC_ALL="POSIX"<br />
<br />
<br />
==Virtual Memory Footprint (Linux / Mac OS X / BSD)==<br />
<br />
Due to how sc_serv works it will create a large number of threads which may become an issue due to the default virtual memory stack allocation per thread potentially being large (typically 10MB per thread). For most people this should not be an issue as the memory is not really allocated unless it is used. If however if you have a resource constrained system or if you plan on running many copies of sc_trans then you could potentially run out of virtual memory.<br />
<br />
The default thread allocation can be reduced by issuing a "ulimit" command before running sc_trans and in the example reduces it to 512KB per-thread '''e.g.''' ulimit -s 512<br />
<br />
<br />
==Maximum Client Connection Limits==<br />
<br />
In general, there are inherent limits on the maximum number of client connections which may be made to a running instances of sc_serv which can either be set by configuration limits e.g. 'maxuser', Operating System limits or bandwidth limits being reached.<br />
<br />
The first two are easy to resolve whereas the last (bandwidth limits) is something which will usually require obtaining additional hosting or paying for more available bandwidth.<br />
<br />
If reaching the Operating System limit, this is usually indicated by the maximum number of clients never going above a fixed value even if there is the bandwidth and the server has been configured to go higher. This usually appears as around 1016 maximum connections (though this can vary a bit)<br />
<br />
If using a non-Windows Operating System then you can use the 'ulimit -n xxxx' command to change the upper limit from what is already set which can be found from just 'ulimit -n' e.g. to change the limit to 4096 connections you would run ulimit -n 4096<br />
<br />
If using a Windows Operating System then there isn't any real way to change such things due to the OS hopefully being configured with limits that will not be reached when using sc_serv. If in doubt then consult the Microsoft support documentation for the OS used.<br />
<br />
<br />
==Example Configurations==<br />
<br />
Include as part of the sc_serv installation are a number of example configurations to get things started with using some of the features of the server. The provided examples are:<br />
<br />
sc_serv_basic.conf<br />
sc_serv_public.conf<br />
sc_serv_relay.conf<br />
sc_serv_simple.conf<br />
<br />
All of the configuration examples are documented and will relate back to details in this file appropriately. You will need to change some details in these example files or to obtain any applicable authorisation keys for the setup you are making ([[#Getting_Started|see section 3.0]]). In all cases the examples are designed to work from the same install folder as sc_serv.<br />
<br />
Remember these examples are a way to get you up and running faster though you are still likely to have to adjust things depending upon the systems you are using and how you want to manage your sources and server connections which are covered in previous sections.<br />
<br />
Additionally if you are not happy with editing the files or find it still too confusing then you can use the configuration builder which (if installed) can be found in the 'config_builder'. Open 'config_builder.html' in your browser and then use this graphical tool to setup a configuration file for the server (and additionally the transcoder).<br />
<br />
<br />
===sc_serv_basic===<br />
----<br />
<br />
This is the base configuration from which the other configuration examples are based and this will get a sc_serv instance running as a local setup with no connection made to the YP directory.<br />
<br />
<br />
===sc_serv_public===<br />
----<br />
<br />
This configuration file changes the required options in the sc_serv_basic configuration to get a sc_serv instance running as a public setup with a connection made to the YP for listing the stream in the directory. This shows the use of the 'include' option (see section [[#Miscellaneous|4.7]]) and how specifying a configuration option twice uses the last value found.<br />
<br />
<br />
===sc_serv_relay===<br />
----<br />
<br />
This configuration file changes the required options in the sc_serv_public configuration to get a sc_serv instance running as a public setup with a source coming in from a relay server providing a SHOUTcast 2 stream.<br />
<br />
<br />
===sc_serv_debug===<br />
----<br />
<br />
This configuration file can be included in any other configuration files to allow you to get debug logging output when trying to investigate any issues you may be experiencing.<br />
<br />
<br />
===sc_serv_simple===<br />
----<br />
<br />
Use this if you just need to get a very basic server running or are impatient<br />
or are struggling to get it running despite the previous example configurations.<br />
<br />
This configuration file is designed to be used just as is and is the simplest form of the configuration file you can have which will allow you to get a running server to appear on the YP. This works on using the default settings of the server though does change some of the file paths inorder to fit in with the existing setup as used in the other examples.<br />
<br />
All you need to do when using this configuration file is to enter your authorisation key in the 'streamauthhash' line '''e.g.''' if your authorisation key is '''123456789''' then you change ''streamauthhash=<enter_your_auth_key_here>'' to ''streamauthhash='''123456789''''' and save the file.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_Source_SupportSHOUTcast Server Source Support2015-05-27T22:21:20Z<p>DrO: Typo fix</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance. To be able to do this, it has required the source for the stream to be a relay (pulling a copy of the stream from another server) or by using SHOUTcast 2 protocol compatible source client software (where you specify the stream number to connect to as part of the source configuration).<br />
<br />
The downside of this is that unless you are relaying or using an updated source client, existing source client software which is only SHOUTcast 1 protocol compatible has only been able to connect as the source from stream #1 (due to not being able to indicate the required stream number). There was a partial workaround by using the 'streamportlegacy' option but this had issues and was marked as an experimental feature.<br />
<br />
<br />
With the release of the v2.4.7 DNAS server (and future versions), not being able to use multiple SHOUTcast 1 protocol compatible source software to connect as the source for any stream on the DNAS server has now been removed. The changes to support this will typically not require any source client software updates as this is all handled by the DNAS server as long as the correct password is provided.<br />
<br />
<br />
==How It Works==<br />
<br />
With the SHOUTcast 2 protocol, the ability to specify the desired stream for the source client to be used for is a core part of the protocol via the required stream identifier. Whereas the SHOUTcast 1 protocol was designed before it was considered to be able to provide multiple streams from a single DNAS server instance (as the v2.x DNAS server supports) and so there is no direct means in the protocol to specify the stream identifier.<br />
<br />
All SHOUTcast source client connections require a password to be provided irrespective of the SHOUTcast protocol version being used and with the SHOUTcast 1 protocol, this is the first primary piece of information sent to the DNAS server when the source is attempting to connect.<br />
<br />
<br />
By manipulating the password provided from a SHOUTcast 1 protocol compatible source client to also include the intended stream identifier, it is now possible for the DNAS server to know the intended stream the source client is to be used for. This is what will now allow for the v2.4.7 DNAS server (and future versions) to be able to support multiple SHOUTcast 1 protocol compatible source clients along with the added benefit of not requiring source client software updates (though native SHOUTcast 2 protocol support is preferred over SHOUTcast 1 protocol based source clients).<br />
<br />
<br />
==How To Do It==<br />
<br />
To connect a SHOUTcast 1 protocol compatible source client to a specific stream then you can append ''':#<sid>''' to the end of the password to be used so you have '''<password>:#<sid>''' (where ''<password>'' is the configured stream password and ''<sid>'' is the required stream identifier).<br />
<br />
e.g.<br />
<br />
to connect to '''stream #2''' with the configured password as '''bob'''<br />
<br />
the value to enter in the source client password field is: '''bob:#2'''<br />
<br />
stream #1 is the default stream assumed for a SHOUTcast 1 protocol compatible source client<br />
and so it is not necessary to add ''':#1''' to the end of the password, though it is ok to do this<br />
<br />
<br />
The colon character is now a reserved character and cannot be used as a value in passwords. If the DNAS server detects a colon then the password will be rejected and the DNAS server may abort running.<br />
<br />
<br />
===DJ / User ID===<br />
----<br />
In addition to the ability to provide the stream identifier, it is also possible to provide a DJ / User ID for the source connection. This is done in a similar manner but places the DJ / User ID value at the start of the password field<br />
<br />
e.g.<br />
<br />
'''<dj>:<password>'''<br />
<br />
or<br />
<br />
'''<dj>:<password>:#<sid>'''<br />
'''<dj>''' is the value to send<br />
'''<password>''' is the configured stream password<br />
'''<sid>''' is the required stream identifier<br />
<br />
<br />
This support is currently used just to see which DJ / User is connected as the source client for the stream, however in future DNAS releases then this may be used as a way to do additional controlling of the source client connections to the DNAS server.<br />
<br />
<br />
==Is There Anything Else?==<br />
<br />
To ensure that SHOUTcast 1 protocol compatible source clients are able to access the DNAS server, you may need to open an additional port to just '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' to allow the source connection to be made if it is not from the same machine or the same local network as the DNAS server i.e. you are making an external source connection.<br />
If the source is running on the same machine or local network then you<br />
will not need to open any additional ports for the connection to work.<br />
<br />
<br />
How to do this will depend upon your setup but often requires ports to be opened on the router and in the Operating System's firewall. You should be able to find information for your router on how to do port forwarding from [http://www.portforward.com | www.portforward.com] (which only requires TCP connections to be forwarded and not UDP connections).<br />
<br />
<br />
Usually you will be forwarding port 8000 as well as port 8001 (which is the actual port that the SHOUTcast 1 protocol uses for source connections). If you have changed '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' from it's default value then you will need to ensure that '''portbase+1''' is opened so that the external source connection can be made. You can use [http://www.yougetsignal.com/tools/open-ports | www.yougetsignal.com/tools/open-ports] to confirm that the port forwarding is working correctly (just ensure the DNAS server is actually running at the time!).<br />
<br />
If not done correctly then the source connection will fail<br />
either due to a connection timeout or an unknown error code.<br />
<br />
<br />
==Additional Information==<br />
[[Image:View_Source_Login_Details.png|225px|thumb|right|View_Source_Login_Details.png]]<br />
If you are still unsure about what to enter into the source client password field, the '''View Source Login Details''' page (found on the DNAS server admin summary page) which shows the appropriate password to use for the different SHOUTcast protocol source clients via the '''Password''' and '''Legacy Password''' values shown.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_Source_SupportSHOUTcast Server Source Support2015-03-16T01:53:07Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance. To be able to do this, it has required the source for the stream to be a relay (pulling a copy of the stream from another server) or by using SHOUTcast 2 protocol compatible source client software (where you specify the stream number to connect to as part of the source configuration).<br />
<br />
The downside of this is that unless you are relaying or using an updated source client, existing source client software which is only SHOUTcast 1 protocol compatible has only been able to connect as the source from stream #1 (due to not being able to indicate the required stream number). There was a partial workaround by using the 'streamportlegacy' option but this had issues and was marked as an experimental feature.<br />
<br />
<br />
With the release of the v2.4.7 DNAS server (and future versions), not being able to use multiple SHOUTcast 1 protocol compatible source software to connect as the source for any stream on the DNAS server has now been removed. The changes to support this will typically not require any source client software updates as this is all handled by the DNAS server as long as the correct password is provided.<br />
<br />
<br />
==How It Works==<br />
<br />
With the SHOUTcast 2 protocol, the ability to specify the desired stream for the source client to be used for is a core part of the protocol via the required stream identifier. Whereas the SHOUTcast 1 protocol was designed before it was considered to be able to provide multiple streams from a single DNAS server instance (as the v2.x DNAS server supports) and so there is no direct means in the protocol to specify the stream identifier.<br />
<br />
All SHOUTcast source client connections require a password to be provided irrespective of the SHOUTcast protocol version being used and with the SHOUTcast 1 protocol, this is the first primary piece of information sent to the DNAS server when the source is attempting to connect.<br />
<br />
<br />
By manipulating the password provided from a SHOUTcast 1 protocol compatible source client to also include the intended stream identifier, it is now possible for the DNAS server to know the intended stream the source client is to be used for. This is what will now allow for the v2.4.7 DNAS server (and future versions) to be able to support multiple SHOUTcast 1 protocol compatible source clients along with the added benefit of not requiring source client software updates (though native SHOUTcast 2 protocol support is preferred over SHOUTcast 1 protocol based source clients).<br />
<br />
<br />
==How To Do It==<br />
<br />
To connect a SHOUTcast 1 protocol compatible source client to a specific stream then you can append ''':#<sid>''' to the end of the password to be used so you have '''<password>:#<sid>''' (where ''<password>'' is the configured stream password and ''<sid>'' is the required stream identifier).<br />
<br />
e.g.<br />
<br />
to connect to '''stream #2''' with the configured password as '''bob'''<br />
<br />
the value to enter in the source client password field is: '''bob:#2'''<br />
<br />
stream #1 is the default stream assumed for a SHOUTcast 1 protocol compatible source client<br />
and so it is not necessary to add ''':#1''' to the end of the password, though it is ok to do this<br />
<br />
<br />
The colon character is now a reserved character and cannot be used as a value in passwords. If the DNAS server detects a colon then the password will be rejected and the DNAS server may abort running.<br />
<br />
<br />
===DJ / User ID===<br />
----<br />
In addition to the ability to provide the stream identifier, it is also possible to provide a DJ / User ID for the source connection. This is done in a similar manner but places the DJ / User ID value at the start of the password field<br />
<br />
e.g.<br />
<br />
'''<dj>:<password>'''<br />
<br />
or<br />
<br />
'''<dj>:<password>:#<sid>'''<br />
'''<dj>''' is the value to send<br />
'''<password>''' is the configured stream password<br />
'''<sid>''' is the required stream identifier<br />
<br />
<br />
This support is currently used just to see which DJ / User is connected as the source client for the stream, however in future DNAS releases then this may be used as a way to do additional controlling of the source client connections to the DNAS server.<br />
<br />
<br />
==Is There Anything Else?==<br />
<br />
To ensure that SHOUTcast 1 protocol compatible source clients areable to access the DNAS server, you may need to open an additional port to just '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' to allow the source connection to be made if it is not from the same machine or the same local network as the DNAS server i.e. you are making an external source connection.<br />
If the source is running on the same machine or local network then you<br />
will not need to open any additional ports for the connection to work.<br />
<br />
<br />
How to do this will depend upon your setup but often requires ports to be opened on the router and in the Operating System's firewall. You should be able to find information for your router on how to do port forwarding from [http://www.portforward.com | www.portforward.com] (which only requires TCP connections to be forwarded and not UDP connections).<br />
<br />
<br />
Usually you will be forwarding port 8000 as well as port 8001 (which is the actual port that the SHOUTcast 1 protocol uses for source connections). If you have changed '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' from it's default value then you will need to ensure that '''portbase+1''' is opened so that the external source connection can be made. You can use [http://www.yougetsignal.com/tools/open-ports | www.yougetsignal.com/tools/open-ports] to confirm that the port forwarding is working correctly (just ensure the DNAS server is actually running at the time!).<br />
<br />
If not done correctly then the source connection will fail<br />
either due to a connection timeout or an unknown error code.<br />
<br />
<br />
==Additional Information==<br />
[[Image:View_Source_Login_Details.png|225px|thumb|right|View_Source_Login_Details.png]]<br />
If you are still unsure about what to enter into the source client password field, the '''View Source Login Details''' page (found on the DNAS server admin summary page) which shows the appropriate password to use for the different SHOUTcast protocol source clients via the '''Password''' and '''Legacy Password''' values shown.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_Source_SupportSHOUTcast Server Source Support2015-03-15T18:07:18Z<p>DrO: Tweak url formatting</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance. To be able to do this, it has required the source for the stream to be a relay (pulling a copy of the stream from another server) or by using SHOUTcast 2 protocol compatible source client software (where you specify the stream number to connect to as part of the source configuration).<br />
<br />
The downside of this is that unless you are relaying or using an updated source client, existing source client software which is only SHOUTcast 1 protocol compatible has only been able to connect as the source from stream #1 (due to not being able to indicate the required stream number). There was a partial workaround by using the 'streamportlegacy' option but this had issues and was marked as an experimental feature.<br />
<br />
<br />
With the release of the v2.5 DNAS server, not being able to use multiple SHOUTcast 1 protocol compatible source software to connect as the source for any stream on the DNAS server has now been removed. The changes to support this will typically not require any source client software updates as this is all handled by the DNAS server as long as the correct password is provided.<br />
<br />
<br />
==How It Works==<br />
<br />
With the SHOUTcast 2 protocol, the ability to specify the desired stream for the source client to be used for is a core part of the protocol via the required stream identifier. Whereas the SHOUTcast 1 protocol was designed before it was considered to be able to provide multiple streams from a single DNAS server instance (as the v2.x DNAS server supports) and so there is no direct means in the protocol to specify the stream identifier.<br />
<br />
All SHOUTcast source client connections require a password to be provided irrespective of the SHOUTcast protocol version being used and with the SHOUTcast 1 protocol, this is the first primary piece of information sent to the DNAS server when the source is attempting to connect.<br />
<br />
<br />
By manipulating the password provided from a SHOUTcast 1 protocol compatible source client to also include the intended stream identifier, it is now possible for the DNAS server to know the intended stream the source client is to be used for. This is what will now allow for the v2.5 DNAS server to be able to support multiple SHOUTcast 1 protocol compatible source clients along with the added benefit of not requiring source client software updates (though native SHOUTcast 2 protocol support is preferred over SHOUTcast 1 protocol based source clients).<br />
<br />
<br />
==How To Do It==<br />
<br />
To connect a SHOUTcast 1 protocol compatible source client to a specific stream then you can append ''':#<sid>''' to the end of the password to be used so you have '''<password>:#<sid>''' (where ''<password>'' is the configured stream password and ''<sid>'' is the required stream identifier).<br />
<br />
e.g.<br />
<br />
to connect to '''stream #2''' with the configured password as '''bob'''<br />
<br />
the value to enter in the source client password field is: '''bob:#2'''<br />
<br />
stream #1 is the default stream assumed for a SHOUTcast 1 protocol compatible source client<br />
and so it is not necessary to add ''':#1''' to the end of the password, though it is ok to do this<br />
<br />
<br />
The colon character is now a reserved character and cannot be used as a value in passwords. If the DNAS server detects a colon then the password will be rejected and the DNAS server may abort running.<br />
<br />
<br />
===DJ / User ID===<br />
----<br />
In addition to the ability to provide the stream identifier, it is also possible to provide a DJ / User ID for the source connection. This is done in a similar manner but places the DJ / User ID value at the start of the password field<br />
<br />
e.g.<br />
<br />
'''<dj>:<password>'''<br />
<br />
or<br />
<br />
'''<dj>:<password>:#<sid>'''<br />
'''<dj>''' is the value to send<br />
'''<password>''' is the configured stream password<br />
'''<sid>''' is the required stream identifier<br />
<br />
<br />
This support is currently used just to see which DJ / User is connected as the source client for the stream, however in future DNAS releases then this may be used as a way to do additional controlling of the source client connections to the DNAS server.<br />
<br />
<br />
==Is There Anything Else?==<br />
<br />
To ensure that SHOUTcast 1 protocol compatible source clients areable to access the DNAS server, you may need to open an additional port to just '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' to allow the source connection to be made if it is not from the same machine or the same local network as the DNAS server i.e. you are making an external source connection.<br />
If the source is running on the same machine or local network then you<br />
will not need to open any additional ports for the connection to work.<br />
<br />
<br />
How to do this will depend upon your setup but often requires ports to be opened on the router and in the Operating System's firewall. You should be able to find information for your router on how to do port forwarding from [http://www.portforward.com | www.portforward.com] (which only requires TCP connections to be forwarded and not UDP connections).<br />
<br />
<br />
Usually you will be forwarding port 8000 as well as port 8001 (which is the actual port that the SHOUTcast 1 protocol uses for source connections). If you have changed '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' from it's default value then you will need to ensure that '''portbase+1''' is opened so that the external source connection can be made. You can use [http://www.yougetsignal.com/tools/open-ports | www.yougetsignal.com/tools/open-ports] to confirm that the port forwarding is working correctly (just ensure the DNAS server is actually running at the time!).<br />
<br />
If not done correctly then the source connection will fail<br />
either due to a connection timeout or an unknown error code.<br />
<br />
<br />
==Additional Information==<br />
[[Image:View_Source_Login_Details.png|225px|thumb|right|View_Source_Login_Details.png]]<br />
If you are still unsure about what to enter into the source client password field, the '''View Source Login Details''' page (found on the DNAS server admin summary page) which shows the appropriate password to use for the different SHOUTcast protocol source clients via the '''Password''' and '''Legacy Password''' values shown.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_Source_SupportSHOUTcast Server Source Support2015-03-13T20:01:45Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance. To be able to do this, it has required the source for the stream to be a relay (pulling a copy of the stream from another server) or by using SHOUTcast 2 protocol compatible source client software (where you specify the stream number to connect to as part of the source configuration).<br />
<br />
The downside of this is that unless you are relaying or using an updated source client, existing source client software which is only SHOUTcast 1 protocol compatible has only been able to connect as the source from stream #1 (due to not being able to indicate the required stream number). There was a partial workaround by using the 'streamportlegacy' option but this had issues and was marked as an experimental feature.<br />
<br />
<br />
With the release of the v2.5 DNAS server, not being able to use multiple SHOUTcast 1 protocol compatible source software to connect as the source for any stream on the DNAS server has now been removed. The changes to support this will typically not require any source client software updates as this is all handled by the DNAS server as long as the correct password is provided.<br />
<br />
<br />
==How It Works==<br />
<br />
With the SHOUTcast 2 protocol, the ability to specify the desired stream for the source client to be used for is a core part of the protocol via the required stream identifier. Whereas the SHOUTcast 1 protocol was designed before it was considered to be able to provide multiple streams from a single DNAS server instance (as the v2.x DNAS server supports) and so there is no direct means in the protocol to specify the stream identifier.<br />
<br />
All SHOUTcast source client connections require a password to be provided irrespective of the SHOUTcast protocol version being used and with the SHOUTcast 1 protocol, this is the first primary piece of information sent to the DNAS server when the source is attempting to connect.<br />
<br />
<br />
By manipulating the password provided from a SHOUTcast 1 protocol compatible source client to also include the intended stream identifier, it is now possible for the DNAS server to know the intended stream the source client is to be used for. This is what will now allow for the v2.5 DNAS server to be able to support multiple SHOUTcast 1 protocol compatible source clients along with the added benefit of not requiring source client software updates (though native SHOUTcast 2 protocol support is preferred over SHOUTcast 1 protocol based source clients).<br />
<br />
<br />
==How To Do It==<br />
<br />
To connect a SHOUTcast 1 protocol compatible source client to a specific stream then you can append ''':#<sid>''' to the end of the password to be used so you have '''<password>:#<sid>''' (where ''<password>'' is the configured stream password and ''<sid>'' is the required stream identifier).<br />
<br />
e.g.<br />
<br />
to connect to '''stream #2''' with the configured password as '''bob'''<br />
<br />
the value to enter in the source client password field is: '''bob:#2'''<br />
<br />
stream #1 is the default stream assumed for a SHOUTcast 1 protocol compatible source client<br />
and so it is not necessary to add ''':#1''' to the end of the password, though it is ok to do this<br />
<br />
<br />
The colon character is now a reserved character and cannot be used as a value in passwords. If the DNAS server detects a colon then the password will be rejected and the DNAS server may abort running.<br />
<br />
<br />
===DJ / User ID===<br />
----<br />
In addition to the ability to provide the stream identifier, it is also possible to provide a DJ / User ID for the source connection. This is done in a similar manner but places the DJ / User ID value at the start of the password field<br />
<br />
e.g.<br />
<br />
'''<dj>:<password>'''<br />
<br />
or<br />
<br />
'''<dj>:<password>:#<sid>'''<br />
'''<dj>''' is the value to send<br />
'''<password>''' is the configured stream password<br />
'''<sid>''' is the required stream identifier<br />
<br />
<br />
This support is currently used just to see which DJ / User is connected as the source client for the stream, however in future DNAS releases then this may be used as a way to do additional controlling of the source client connections to the DNAS server.<br />
<br />
<br />
==Is There Anything Else?==<br />
<br />
To ensure that SHOUTcast 1 protocol compatible source clients areable to access the DNAS server, you may need to open an additional port to just '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' to allow the source connection to be made if it is not from the same machine or the same local network as the DNAS server i.e. you are making an external source connection.<br />
If the source is running on the same machine or local network then you<br />
will not need to open any additional ports for the connection to work.<br />
<br />
<br />
How to do this will depend upon your setup but often requires ports to be opened on the router and in the Operating System's firewall. You should be able to find information for your router on how to do port forwarding from http://www.portforward.com/ (which only requires TCP connections to be forwarded and not UDP connections).<br />
<br />
<br />
Usually you will be forwarding port 8000 as well as port 8001 (which is the actual port that the SHOUTcast 1 protocol uses for source connections). If you have changed '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' from it's default value then you will need to ensure that '''portbase+1''' is opened so that the external source connection can be made. You can use http://www.yougetsignal.com/tools/open-ports/ to confirm that the port forwarding is working correctly (just ensure the DNAS server is actually running at the time!).<br />
<br />
If not done correctly then the source connection will fail<br />
either due to a connection timeout or an unknown error code.<br />
<br />
<br />
==Additional Information==<br />
[[Image:View_Source_Login_Details.png|225px|thumb|right|View_Source_Login_Details.png]]<br />
If you are still unsure about what to enter into the source client password field, the '''View Source Login Details''' page (found on the DNAS server admin summary page) which shows the appropriate password to use for the different SHOUTcast protocol source clients via the '''Password''' and '''Legacy Password''' values shown.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_Source_SupportSHOUTcast Server Source Support2015-03-13T19:58:42Z<p>DrO: Add info about port forwarding requirements</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance. To be able to do this, it has required the source for the stream to be a relay (pulling a copy of the stream from another server) or by using SHOUTcast 2 protocol compatible source client software (where you specify the stream number to connect to as part of the source configuration).<br />
<br />
The downside of this is that unless you are relaying or using an updated source client, existing source client software which is only SHOUTcast 1 protocol compatible has only been able to connect as the source from stream #1 (due to not being able to indicate the required stream number). There was a partial workaround by using the 'streamportlegacy' option but this had issues and was marked as an experimental feature.<br />
<br />
<br />
With the release of the v2.5 DNAS server, not being able to use multiple SHOUTcast 1 protocol compatible source software to connect as the source for any stream on the DNAS server has now been removed. The changes to support this will typically not require any source client software updates as this is all handled by the DNAS server as long as the correct password is provided.<br />
<br />
<br />
==How It Works==<br />
<br />
With the SHOUTcast 2 protocol, the ability to specify the desired stream for the source client to be used for is a core part of the protocol via the required stream identifier. Whereas the SHOUTcast 1 protocol was designed before it was considered to be able to provide multiple streams from a single DNAS server instance (as the v2.x DNAS server supports) and so there is no direct means in the protocol to specify the stream identifier.<br />
<br />
All SHOUTcast source client connections require a password to be provided irrespective of the SHOUTcast protocol version being used and with the SHOUTcast 1 protocol, this is the first primary piece of information sent to the DNAS server when the source is attempting to connect.<br />
<br />
<br />
By manipulating the password provided from a SHOUTcast 1 protocol compatible source client to also include the intended stream identifier, it is now possible for the DNAS server to know the intended stream the source client is to be used for. This is what will now allow for the v2.5 DNAS server to be able to support multiple SHOUTcast 1 protocol compatible source clients along with the added benefit of not requiring source client software updates (though native SHOUTcast 2 protocol support is preferred over SHOUTcast 1 protocol based source clients).<br />
<br />
<br />
==How To Do It==<br />
<br />
To connect a SHOUTcast 1 protocol compatible source client to a specific stream then you can append ''':#<sid>''' to the end of the password to be used so you have '''<password>:#<sid>''' (where ''<password>'' is the configured stream password and ''<sid>'' is the required stream identifier).<br />
<br />
e.g.<br />
<br />
to connect to '''stream #2''' with the configured password as '''bob'''<br />
<br />
the value to enter in the source client password field is: '''bob:#2'''<br />
<br />
stream #1 is the default stream assumed for a SHOUTcast 1 protocol compatible source client<br />
and so it is not necessary to add ''':#1''' to the end of the password, though it is ok to do this<br />
<br />
<br />
The colon character is now a reserved character and cannot be used as a value in passwords. If the DNAS server detects a colon then the password will be rejected and the DNAS server may abort running.<br />
<br />
<br />
===DJ / User ID===<br />
----<br />
In addition to the ability to provide the stream identifier, it is also possible to provide a DJ / User ID for the source connection. This is done in a similar manner but places the DJ / User ID value at the start of the password field<br />
<br />
e.g.<br />
<br />
'''<dj>:<password>'''<br />
<br />
or<br />
<br />
'''<dj>:<password>:#<sid>'''<br />
'''<dj>''' is the value to send<br />
'''<password>''' is the configured stream password<br />
'''<sid>''' is the required stream identifier<br />
<br />
<br />
This support is currently used just to see which DJ / User is connected as the source client for the stream, however in future DNAS releases then this may be used as a way to do additional controlling of the source client connections to the DNAS server.<br />
<br />
<br />
==Is There Anything Else?==<br />
<br />
To ensure that SHOUTcast 1 protocol compatible source clients areable to access the DNAS server, you may need to open an additional port to just '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' to allow the source connection to be made if it is not from the same machine or the same local network as the DNAS server i.e. you are making an external source connection.<br />
<br />
<br />
How to do this will depend upon your setup but often requires ports to be opened on the router and in the Operating System's firewall. You should be able to find information for your router on how to do port forwarding from http://www.portforward.com/ (which only requires TCP connections to be forwarded and not UDP connections).<br />
<br />
<br />
Usually you will be forwarding port 8000 as well as port 8001 (which is the actual port that the SHOUTcast 1 protocol uses for source connections). If you have changed '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' from it's default value then you will need to ensure that '''portbase+1''' is correctly opened. You can use http://www.yougetsignal.com/tools/open-ports/ to confirm that the port forwarding is working correctly (just ensure the DNAS server is actually running at the time!).<br />
<br />
If not done correctly then the source connection will fail<br />
either due to a connection timeout or an unknown error code.<br />
<br />
<br />
==Additional Information==<br />
[[Image:View_Source_Login_Details.png|225px|thumb|right|View_Source_Login_Details.png]]<br />
If you are still unsure about what to enter into the source client password field, the '''View Source Login Details''' page (found on the DNAS server admin summary page) which shows the appropriate password to use for the different SHOUTcast protocol source clients via the '''Password''' and '''Legacy Password''' values shown.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Listing_RequirementsSHOUTcast Listing Requirements2015-02-12T16:30:15Z<p>DrO: Add clarification of what my prevent an Icecast instance from being listed</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
=How to get listed in the SHOUTcast Directory=<br />
<br />
There are currently a number of ways for a station to be listed in the SHOUTcast Directory (also referred to as the YP) which this document will detail. If you are still uncertain whether your station can be listed in the SHOUTcast Directory, please contact support with information about your existing station and they will be able to advise you.<br />
<br />
<br />
==SHOUTcast DNAS Server==<br />
<br />
This is the primary way for getting your station listed in the SHOUTcast Directory. To do this, you need to ensure the stream is marked as '''public''' and for all 2.x DNAS you have to have a valid authhash (see '''[[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]]''' for what to do if you are having issues obtaining an authhash for your stream(s)).<br />
<br />
<br />
For the legacy 1.x DNAS (using the 2.x DNAS is preferred over the 1.x DNAS), you just need to ensure the stream is marked as '''public'''.<br />
<br />
<br />
Ensuring the stream is correctly marked as '''public''' can be done either via the connected stream source and the options it provides or it can be done by forcing the DNAS via the '''publicserver''' configuration option which if set as '''publicserver=always''' will override what is provided by the the connected stream source (be that a direct source or a relay source).<br />
<br />
<br />
==Icecast Server==<br />
<br />
This is an alternative server to the SHOUTcast DNAS server which can be configured to be able to be listed in the SHOUTcast Directory as a SHOUTcast 1.x DNAS compatible listing. Such listings will work but due to a lower set of information provided by the Icecast server on its communication with the SHOUTcast Directory, some aspects of the listings will not be provided and can only be enabled for native SHOUTcast DNAS servers.<br />
<br />
If an Icecast server instance has been modified so that<br />
it is not reported as being an Icecast server then it<br />
may not be listed. Check the Icecast logs for errors if<br />
you cannot find the listing in the SHOUTcast Directory.<br />
<br />
<br />
To get the Icecast server configured to be listed, the following needs to be added to your Icecast server configuration file:<br />
<br />
<source lang="xml"><br />
<directory><br />
<yp-url-timeout>15</yp-url-timeout><br />
<yp-url>http://yp.shoutcast.com</yp-url><br />
</directory><br />
</source><br />
<br />
<br />
Once the above configuration options are present, as long as the Icecast server is able to see the SHOUTcast Directory server and the information it provides passes validation (as only MP3 and AAC based streams can be listed), then the stream should be listed.<br />
<br />
<br />
If needing to include multiple Icecast servers as part of a clustered stream, the station name, genre and website details all need to be the same, otherwise the SHOUTcast Directory may not cluster them correctly together (which can still happen even if the details are correct due to how 1.x DNAS style clustering works).<br />
<br />
<br />
'''Note:''' We do not support sending manual updates for the Icecast server like is supported by the Icecast Directory. Each Icecast server to be listed in the SHOUTcast Directory needs to directly provide the required information to the SHOUTcast Directory servers and not doing this can lead to you being banned from being listed in the SHOUTcast Directory.<br />
<br />
==Radionomy Group Services / SHOUTcast Streaming Service==<br />
<br />
If using any of these services then your station will either be automatically added into the SHOUTcast Directory or will require you to reach a specific number of total listening hours (TLH) before your station is imported into the SHOUTcast Directory. This depends on the service being used as to whether the TLH requirement needs to be met or whether you are automatically imported into the SHOUTcast Directory.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_Source_SupportSHOUTcast Server Source Support2015-02-12T13:24:46Z<p>DrO: Move image</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance. To be able to do this, it has required the source for the stream to be a relay (pulling a copy of the stream from another server) or by using SHOUTcast 2 protocol compatible source client software (where you specify the stream number to connect to as part of the source configuration).<br />
<br />
The downside of this is that unless you are relaying or using an updated source client, existing source client software which is only SHOUTcast 1 protocol compatible has only been able to connect as the source from stream #1 (due to not being able to indicate the required stream number). There was a partial workaround by using the 'streamportlegacy' option but this had issues and was marked as an experimental feature.<br />
<br />
<br />
With the release of the v2.5 DNAS server, not being able to use multiple SHOUTcast 1 protocol compatible source software to connect as the source for any stream on the DNAS server has now been removed. The changes to support this will typically not require any source client software updates as this is all handled by the DNAS server as long as the correct password is provided.<br />
<br />
<br />
==How It Works==<br />
<br />
With the SHOUTcast 2 protocol, the ability to specify the desired stream for the source client to be used for is a core part of the protocol via the required stream identifier. Whereas the SHOUTcast 1 protocol was designed before it was considered to be able to provide multiple streams from a single DNAS server instance (as the v2.x DNAS server supports) and so there is no direct means in the protocol to specify the stream identifier.<br />
<br />
All SHOUTcast source client connections require a password to be provided irrespective of the SHOUTcast protocol version being used and with the SHOUTcast 1 protocol, this is the first primary piece of information sent to the DNAS server when the source is attempting to connect.<br />
<br />
<br />
By manipulating the password provided from a SHOUTcast 1 protocol compatible source client to also include the intended stream identifier, it is now possible for the DNAS server to know the intended stream the source client is to be used for. This is what will now allow for the v2.5 DNAS server to be able to support multiple SHOUTcast 1 protocol compatible source clients along with the added benefit of not requiring source client software updates (though native SHOUTcast 2 protocol support is preferred over SHOUTcast 1 protocol based source clients).<br />
<br />
<br />
==How To Do It==<br />
<br />
To connect a SHOUTcast 1 protocol compatible source client to a specific stream then you can append ''':#<sid>''' to the end of the password to be used so you have '''<password>:#<sid>''' (where ''<password>'' is the configured stream password and ''<sid>'' is the required stream identifier).<br />
<br />
e.g.<br />
<br />
to connect to '''stream #2''' with the configured password as '''bob'''<br />
<br />
the value to enter in the source client password field is: '''bob:#2'''<br />
<br />
stream #1 is the default stream assumed for a SHOUTcast 1 protocol compatible source client<br />
and so it is not necessary to add ''':#1''' to the end of the password, though it is ok to do this<br />
<br />
<br />
The colon character is now a reserved character and cannot be used as a value in passwords. If the DNAS server detects a colon then the password will be rejected and the DNAS server may abort running.<br />
<br />
<br />
===DJ / User ID===<br />
----<br />
In addition to the ability to provide the stream identifier, it is also possible to provide a DJ / User ID for the source connection. This is done in a similar manner but places the DJ / User ID value at the start of the password field<br />
<br />
e.g.<br />
<br />
'''<dj>:<password>'''<br />
<br />
or<br />
<br />
'''<dj>:<password>:#<sid>'''<br />
'''<dj>''' is the value to send<br />
'''<password>''' is the configured stream password<br />
'''<sid>''' is the required stream identifier<br />
<br />
<br />
This support is currently used just to see which DJ / User is connected as the source client for the stream, however in future DNAS releases then this may be used as a way to do additional controlling of the source client connections to the DNAS server.<br />
<br />
<br />
==Additional Information==<br />
[[Image:View_Source_Login_Details.png|225px|thumb|right|View_Source_Login_Details.png]]<br />
If you are still unsure about what to enter into the source client password field, the '''View Source Login Details''' page (found on the DNAS server admin summary page) which shows the appropriate password to use for the different SHOUTcast protocol source clients via the '''Password''' and '''Legacy Password''' values shown.</div>DrOhttp://wiki.winamp.com/wiki/File:View_Source_Login_Details.pngFile:View Source Login Details.png2015-02-12T13:23:48Z<p>DrO: Protected "File:View Source Login Details.png" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite) [Upload=Allow only administrators] (indefinite))</p>
<hr />
<div>View Source Login Details Page</div>DrOhttp://wiki.winamp.com/wiki/File:View_Source_Login_Details.pngFile:View Source Login Details.png2015-02-12T13:23:35Z<p>DrO: View Source Login Details Page</p>
<hr />
<div>View Source Login Details Page</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_Source_SupportSHOUTcast Server Source Support2015-02-11T21:45:13Z<p>DrO: Add DJ support and some wording tweaks</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance. To be able to do this, it has required the source for the stream to be a relay (pulling a copy of the stream from another server) or by using SHOUTcast 2 protocol compatible source client software (where you specify the stream number to connect to as part of the source configuration).<br />
<br />
The downside of this is that unless you are relaying or using an updated source client, existing source client software which is only SHOUTcast 1 protocol compatible has only been able to connect as the source from stream #1 (due to not being able to indicate the required stream number). There was a partial workaround by using the 'streamportlegacy' option but this had issues and was marked as an experimental feature.<br />
<br />
<br />
With the release of the v2.5 DNAS server, not being able to use multiple SHOUTcast 1 protocol compatible source software to connect as the source for any stream on the DNAS server has now been removed. The changes to support this will typically not require any source client software updates as this is all handled by the DNAS server as long as the correct password is provided.<br />
<br />
<br />
==How It Works==<br />
<br />
With the SHOUTcast 2 protocol, the ability to specify the desired stream for the source client to be used for is a core part of the protocol via the required stream identifier. Whereas the SHOUTcast 1 protocol was designed before it was considered to be able to provide multiple streams from a single DNAS server instance (as the v2.x DNAS server supports) and so there is no direct means in the protocol to specify the stream identifier.<br />
<br />
All SHOUTcast source client connections require a password to be provided irrespective of the SHOUTcast protocol version being used and with the SHOUTcast 1 protocol, this is the first primary piece of information sent to the DNAS server when the source is attempting to connect.<br />
<br />
<br />
By manipulating the password provided from a SHOUTcast 1 protocol compatible source client to also include the intended stream identifier, it is now possible for the DNAS server to know the intended stream the source client is to be used for. This is what will now allow for the v2.5 DNAS server to be able to support multiple SHOUTcast 1 protocol compatible source clients along with the added benefit of not requiring source client software updates (though native SHOUTcast 2 protocol support is preferred over SHOUTcast 1 protocol based source clients).<br />
<br />
<br />
==How To Do It==<br />
<br />
[[Image:View_Source_Login_Details.png|225px|thumb|right|View_Source_Login_Details.png]]<br />
To connect a SHOUTcast 1 protocol compatible source client to a specific stream then you can append ''':#<sid>''' to the end of the password to be used so you have '''<password>:#<sid>''' (where ''<password>'' is the configured stream password and ''<sid>'' is the required stream identifier).<br />
<br />
e.g.<br />
<br />
to connect to '''stream #2''' with the configured password as '''bob'''<br />
<br />
the value to enter in the source client password field is: '''bob:#2'''<br />
<br />
stream #1 is the default stream assumed for a SHOUTcast 1 protocol compatible source client<br />
and so it is not necessary to add ''':#1''' to the end of the password, though it is ok to do this<br />
<br />
<br />
The colon character is now a reserved character and cannot be used as a value in passwords. If the DNAS server detects a colon then the password will be rejected and the DNAS server may abort running.<br />
<br />
<br />
===DJ / User ID===<br />
----<br />
In addition to the ability to provide the stream identifier, it is also possible to provide a DJ / User ID for the source connection. This is done in a similar manner but places the DJ / User ID value at the start of the password field<br />
<br />
e.g.<br />
<br />
'''<dj>:<password>'''<br />
<br />
or<br />
<br />
'''<dj>:<password>:#<sid>'''<br />
'''<dj>''' is the value to send<br />
'''<password>''' is the configured stream password<br />
'''<sid>''' is the required stream identifier<br />
<br />
<br />
This support is currently used just to see which DJ / User is connected as the source client for the stream, however in future DNAS releases then this may be used as a way to do additional controlling of the source client connections to the DNAS server.<br />
<br />
<br />
==Additional Information==<br />
If you are still unsure about what to enter into the source client password field, the '''View Source Login Details''' page (found on the DNAS server admin summary page) which shows the appropriate password to use for the different SHOUTcast protocol source clients via the '''Password''' and '''Legacy Password''' values shown.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_Source_SupportSHOUTcast Server Source Support2015-02-11T17:26:25Z<p>DrO: Protected "SHOUTcast Server Source Support" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite)) [cascading]</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance. To be able to do this, it has required the source for the stream to be a relay (pulling a copy of the stream from another server) or by using SHOUTcast 2 protocol compatible source client software (where you specify the stream number to connect to as part of the source configuration).<br />
<br />
The downside of this is that unless you are relaying or using an updated source client, existing source client software which is only SHOUTcast 1 protocol compatible has only been able to connect as the source from stream #1 (due to not being able to indicate the required stream number). There was a partial workaround by using the 'streamportlegacy' option but this had issues and was marked as an experimental feature.<br />
<br />
<br />
With the release of the v2.5 DNAS server, not being able to use multiple SHOUTcast 1 protocol compatible source software to connect as the source for any stream on the DNAS server has now been removed. The changes to support this will typically not require any source client software updates as this is all handled by the DNAS server as long as the correct password is provided.<br />
<br />
<br />
==How It Works==<br />
<br />
With the SHOUTcast 2 protocol, the ability to specify the desired stream for the source client to be used for is a core part of the protocol via the required stream identifier. Whereas the SHOUTcast 1 protocol was designed before it was considered to be able to provide multiple streams from a single DNAS server instance (as the v2.x DNAS server supports) and so there is no direct means in the protocol to specify the stream identifier.<br />
<br />
All SHOUTcast source client connections require a password to be provided irrespective of the SHOUTcast protocol version being used and with the SHOUTcast 1 protocol, this is the first primary piece of information sent to the DNAS server when the source is attempting to connect.<br />
<br />
<br />
By manipulating the password provided from a SHOUTcast 1 protocol compatible source client to also include the intended stream identifier, it is now possible for the DNAS server to know the intended stream the source client is to be used for. This is what will now allow for the v2.5 DNAS server to be able to support multiple SHOUTcast 1 protocol compatible source clients along with the added benefit of not requiring source client software updates (though native SHOUTcast 2 protocol support is preferred over SHOUTcast 1 protocol based source clients).<br />
<br />
<br />
==How To Do It==<br />
<br />
[[Image:View_Source_Login_Details.png|225px|thumb|right|View_Source_Login_Details.png]]<br />
To connect a SHOUTcast 1 protocol compatible source client to a specific stream then you can append ''':#<sid>''' to the end of the password to be used so you have '''<password>:#<sid>''' (where ''<password>'' is the configured stream password and ''<sid>'' is the required stream identifier).<br />
<br />
e.g.<br />
<br />
to connect to '''stream #2''' with the configured password as '''bob'''<br />
<br />
the value to enter in the source client password field is: '''bob:#2'''<br />
<br />
<br />
'''Note:''' stream #1 is the default stream assumed for a SHOUTcast 1 protocol compatible source client, it is not necessary to add ''':#1''' to the end of the password. There is nothing to stop this from being done especially if it makes source client implementations easier.<br />
<br />
<br />
If you are still unsure about what to enter into the source client password field, the '''View Source Login Details''' page (found on the DNAS server admin summary page) which shows the appropriate password to use for the different SHOUTcast protocol source clients via the '''Password''' and '''Legacy Password''' values shown.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_Source_SupportSHOUTcast Server Source Support2015-02-11T17:26:02Z<p>DrO: Created page with "{{Template:NavBarSC}} ==Introduction== The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance..."</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The SHOUTcast DNAS server since the introduction of v2.0 has been able to provide multiple streams from a single DNAS server instance. To be able to do this, it has required the source for the stream to be a relay (pulling a copy of the stream from another server) or by using SHOUTcast 2 protocol compatible source client software (where you specify the stream number to connect to as part of the source configuration).<br />
<br />
The downside of this is that unless you are relaying or using an updated source client, existing source client software which is only SHOUTcast 1 protocol compatible has only been able to connect as the source from stream #1 (due to not being able to indicate the required stream number). There was a partial workaround by using the 'streamportlegacy' option but this had issues and was marked as an experimental feature.<br />
<br />
<br />
With the release of the v2.5 DNAS server, not being able to use multiple SHOUTcast 1 protocol compatible source software to connect as the source for any stream on the DNAS server has now been removed. The changes to support this will typically not require any source client software updates as this is all handled by the DNAS server as long as the correct password is provided.<br />
<br />
<br />
==How It Works==<br />
<br />
With the SHOUTcast 2 protocol, the ability to specify the desired stream for the source client to be used for is a core part of the protocol via the required stream identifier. Whereas the SHOUTcast 1 protocol was designed before it was considered to be able to provide multiple streams from a single DNAS server instance (as the v2.x DNAS server supports) and so there is no direct means in the protocol to specify the stream identifier.<br />
<br />
All SHOUTcast source client connections require a password to be provided irrespective of the SHOUTcast protocol version being used and with the SHOUTcast 1 protocol, this is the first primary piece of information sent to the DNAS server when the source is attempting to connect.<br />
<br />
<br />
By manipulating the password provided from a SHOUTcast 1 protocol compatible source client to also include the intended stream identifier, it is now possible for the DNAS server to know the intended stream the source client is to be used for. This is what will now allow for the v2.5 DNAS server to be able to support multiple SHOUTcast 1 protocol compatible source clients along with the added benefit of not requiring source client software updates (though native SHOUTcast 2 protocol support is preferred over SHOUTcast 1 protocol based source clients).<br />
<br />
<br />
==How To Do It==<br />
<br />
[[Image:View_Source_Login_Details.png|225px|thumb|right|View_Source_Login_Details.png]]<br />
To connect a SHOUTcast 1 protocol compatible source client to a specific stream then you can append ''':#<sid>''' to the end of the password to be used so you have '''<password>:#<sid>''' (where ''<password>'' is the configured stream password and ''<sid>'' is the required stream identifier).<br />
<br />
e.g.<br />
<br />
to connect to '''stream #2''' with the configured password as '''bob'''<br />
<br />
the value to enter in the source client password field is: '''bob:#2'''<br />
<br />
<br />
'''Note:''' stream #1 is the default stream assumed for a SHOUTcast 1 protocol compatible source client, it is not necessary to add ''':#1''' to the end of the password. There is nothing to stop this from being done especially if it makes source client implementations easier.<br />
<br />
<br />
If you are still unsure about what to enter into the source client password field, the '''View Source Login Details''' page (found on the DNAS server admin summary page) which shows the appropriate password to use for the different SHOUTcast protocol source clients via the '''Password''' and '''Legacy Password''' values shown.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_BroadcasterSHOUTcast Broadcaster2015-02-11T14:49:56Z<p>DrO: Add reference to some additional pages</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
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.<br />
<br />
<br />
=SHOUTcast Overview=<br />
<br />
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 />
<br />
<br />
=Getting Started=<br />
<br />
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]]'''<br />
'''Important:''' You need to be happy with the use of command-line tools before attempting to install or run<br />
a SHOUTcast system as all versions of the 2.x DNAS Server are designed to work as command-line tools.<br />
<br />
Current versions of the SHOUTcast tools can be obtained from:<br />
<br />
::'''[http://www.shoutcast.com/BroadcastNow/ Broadcast Tool Downloads]'''<br />
::or<br />
::'''[http://forums.shoutcast.com/showthread.php?t=324877 Support Forum Current Downloads Summary] (*)'''<br />
<br />
The forum link is a summary page and contains links to the latest versions of the tools such as when a new<br />
release has just happened or is being tested before it is provided via the '''[http://www.shoutcast.com/broadcast-tools/ Broadcast Tool Downloads]''' page.<br />
<br />
<br />
==Core Documentation==<br />
<br />
Here you can find the core documentation relating to all of the provided SHOUTcast 2.x system tools which is the Server 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.<br />
<br />
::'''[[SHOUTcast_DNAS_Server_2|SHOUTcast DNAS Server 2 (sc_serv)]]'''<br />
<br />
::'''[[Source_DSP_Plug-in|SHOUTcast Source DSP Plug-in (dsp_sc)]]'''<br />
<br />
<br />
==Supporting Documentation==<br />
<br />
Here you can find copies of additional documentation which is referenced by the core documentation or helpful for broadcasting setups and related SHOUTcast interactions.<br />
<br />
::'''[[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]]'''<br />
<br />
::'''[[SHOUTcast_Listing_Requirements|SHOUTcast Listing Requirements]]'''<br />
<br />
::'''[[SHOUTcast_Server_CDN_Features|SHOUTcast Server CDN Features]]'''<br />
<br />
::'''[[SHOUTcast_Server_Source_Support|SHOUTcast Server Source Support]]'''<br />
<br />
<br />
::'''[[SHOUTcast_DNAS_Server_2_XML_Reponses|SHOUTcast DNAS Server 2 XML Reponses]]'''<br />
<br />
::'''[[Source_DSP_Plug-in_Configuration_Examples|SHOUTcast Source DSP Plug-in Configuration Examples]]'''<br />
<br />
::'''[[SHOUTcast_YP_Nak_Errors|SHOUTcast YP Nak Error Information]]'''</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_DeveloperSHOUTcast Developer2015-02-05T22:35:55Z<p>DrO: Typo fix</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
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.<br />
<br />
::'''[[SHOUTcast_API_License_Agreement|SHOUTcast API License Agreement]]'''<br />
<br />
::'''[[SHOUTcast_Radio_Directory_API|SHOUTcast Radio Directory Partner API Documentation]]''' - Reference for accessing information from the Radio Directory<br />
<br />
::'''[[SHOUTcast_Radio_Authhash_API|SHOUTcast Radio Authhash Partner API Documentation]]''' - Reference for accessing the SHOUTcast 2 Authhash Management API<br />
<br />
::'''[[SHOUTcast_2_%28Ultravox_2.1%29_Protocol_Details|SHOUTcast / Ultravox 2.1 Protocol Details]]''' - Reference for anyone wanting to implement clients or servers supporting the SHOUTcast 2 protocol<br />
<br />
::'''[[SHOUTcast_XML_Metadata_Specification|SHOUTcast XML Metadata Specification]]'''</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Radio_Directory_APISHOUTcast Radio Directory API2014-12-03T14:29:13Z<p>DrO: Add missing supported parameters from some of the legacy methods</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
=Get Stations on SHOUTcast Radio Directory=<br />
<br />
==Get Top 500 Stations==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get top 500 stations on SHOUTcast Radio directory.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* k - API Dev Key. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* limit - Limit the number of stations to return by passing the limit parameter.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&limit=5</nowiki><br />
<br />
* br - Filter the stations based on bitrate specified.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&br=64</nowiki><br />
<br />
* mt - Filter the stations based on media type specified.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&mt=audio/aacp</nowiki><br />
:MP3 = audio/mpeg and AAC+ = audio/aacp<br />
<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>''' (with limits)<br />
<source lang="xml"><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name=".977 The Hitz Channel-[SHOUTcast.com]" mt="audio/mpeg" id="9907" br="128"<br />
genre="Pop Rock Top 40"ct="The Fray - You Found Me" lc="4670"/><br />
<station name="HOT FM - Lebih Hangat Daripada Biasa : HOT fm-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="120149" br="24" genre="Malaysia<br />
Malay" ct="LELAKI IDAMAN MELLY_GOESLOW " lc="3961"/><br />
<station name="S K Y . F M - Absolutely Smooth Jazz - the world's smoothest jazz 24 hours a day-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="1264" br="96" genre="Soft Smooth Jazz" <br />
ct="Oli Silk - De-stress Signal" lc="3507"/><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]" <br />
mt="audio/mpeg" id="6687" br="128" genre="Ambient Chill"<br />
ct="Verbrilli Sound - Descender" lc="2680"/><br />
<station name=".977 The 80s Channel-[SHOUTcast.com]" mt="audio/mpeg" id="6803" <br />
br="128" genre="80s Pop Rock" ct="Starship - Nothing`s gonna stop us now (1987)" lc="2192"/><br />
<station name="The Alex Jones Show-[SHOUTcast.com]" mt="audio/mpeg" id="5516" br="32" genre="Talk" <br />
ct="Refeed: Hour 1 (Listen by phone 512-646-5000)" lc="1987"/><br />
</stationlist><br />
</source><br />
<br />
<br />
==Get Stations by Keyword Search==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get stations which match the keyword searched on SHOUTcast Radio Directory.<br />
:'''Note:''' This API returns stations which has keyword match in the following fields Station Name, Now Playing info, Genre.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* search - Specify the query to search.<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* limit - Limits the no of results to be returned.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&limit=10</nowiki><br />
<br />
* limit with pagination - Limits the no of results with pagination included.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&limit=X,Y</nowiki><br />
:* Y is the number of results to return and X is the offset. <br />
<br />
* br - Filter the stations based on bitrate specified.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&br=64</nowiki><br />
<br />
* mt - Filter the stations based on media type specified.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&mt=audio/mpeg</nowiki><br />
:MP3 = audio/mpeg and AAC+ = audio/aacp<br />
<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="6687" br="128" genre="Ambient Chill" ct="Audiomontage - Abyss" lc="241"><br />
</station><br />
<station name="((Metaphoric.me))128k Room42, ambient beats and chill grooves-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="8434" br="128" genre="Ambient Chill" ct="Jazz City - La Noche (Smooth Latin Groove Mix)" lc="83"><br />
</station><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="8010" br="24" genre="Ambient Chill" ct="Audiomontage - Abyss" lc="54"><br />
</station><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="9073" br="56" genre="Ambient Chill" ct="Warheads - Daphne" lc="30"><br />
</station><br />
</stationlist><br />
</source><br />
<br />
<br />
==Get Stations by Genre==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get stations which match the genre specified as query.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* k - API Dev ID.<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* limit - Limits the no of results to be returned.<br />
<br />
* limit with pagination - Limits the no of results with pagination included.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&limit=X,Y</nowiki><br />
:* Y is the number of results to return and X is the offset.<br />
<br />
* br - Filter the stations based on bitrate specified.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&br=64</nowiki><br />
<br />
* mt - Filter the stations based on media type specified.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&mt=audio/mpeg</nowiki><br />
:MP3 = audio/mpeg and AAC+ = audio/aacp<br />
<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name=".977 The Hitz Channel-[SHOUTcast.com]" mt="audio/mpeg" id="9907" br="128"<br />
genre="Pop Rock Top 40" ct="The Fray - You Found Me" lc="4670"/><br />
<station name="HOT FM - Lebih Hangat Daripada Biasa : HOT fm-[SHOUTcast.com]" mt="audio/mpeg" <br />
id="120149" br="24" genre="Malaysia Malay"<br />
ct="LELAKI IDAMAN MELLY_GOESLOW " lc="3961"/><br />
<station name="S K Y . F M - Absolutely Smooth Jazz - the world's smoothest jazz 24 hours a day-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="1264" br="96" genre="Softsmooth Jazz"<br />
ct="Oli Silk -De-stress Signal" lc="3507"/><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="6687" br="128" genre="AmbientChill"<br />
ct="Verbrilli Sound - Descender" lc="2680"/><br />
</stationlist><br />
</source><br />
<br />
<br />
==Get Stations Based on Now Playing Info==<br />
'''<span style="color:#FF6600;">Description:</span>''' Return stations which match a specified query in the now playing node.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>'''<br />
<nowiki>http://api.shoutcast.com/station/nowplaying?k=[Your Dev ID]&ct=rihanna&f=xml</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* ct - Query to search in Now Playing node. This parameter also supports querying multiple artists in the same query by using "||". ex: ct=madonna||u2||beyonce up to 10 artists<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only).<br />
* limit - Limits the no of results to be returned in output.<br />
* br - Filter the stations based on bitrate specified.<br />
* mt - Filter the stations based on media type specified.<br />
* genre - Filter stations that match the genre passed. <br />
<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name="Dj Wouner- Radio Fusion-A novidade come?a Aqui!-[SHOUTcast.com]" mt="audio/mpeg" id="139549" <br />
br="64" genre="Various"ct="Rihanna Feat. Chris Brown & Jay-Z - Umbrella" lc="614" ml="2100" nsc="No" cst=""/><br />
<station name="R?dio Stronda [ Digital ] Servidor 4-[SHOUTcast.com]" mt="audio/mpeg" id="998783" br="64" <br />
genre="Pop Top Rock Funk Str"ct="T.I. feat Rihanna -Live Your Life" lc="243" ml="70" nsc="No" cst=""/><br />
.<br />
.<br />
</stationlist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/station/nowplaying?ct=rihanna&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Various","id":"139549","mt":"audio/mpeg","name":"Dj Wouner- <br />
RadioFusion-A novidadecome?a Aqui!-[SHOUTcast.com]","cst":"","lc":"614","ml":"2100","br":"64",<br />
"ct":"Rihanna Feat. Chris Brown& Jay-Z - Umbrella"},<br />
{"nsc":"No","genre":"Pop Top Rock Funk Str","id":"998783",<br />
"mt":"audio/mpeg","name":"R?dio Stronda[ Digital ] Servidor<br />
4-[SHOUTcast.com]","cst":"","lc":"243","ml":"70","br":"64","ct":"T.I. feat Rihanna - Live Your ife"},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Various","id":"139549","mt":"audio/mpeg","name":"Dj Wouner- <br />
RadioFusion-A novidadecome?a Aqui!-[SHOUTcast.com]","cst":"","lc":"614","ml":"2100","br":"64",<br />
"ct":"Rihanna Feat. Chris Brown& Jay-Z - Umbrella"},<br />
{"nsc":"No","genre":"Pop Top Rock Funk Str","id":"998783",<br />
"mt":"audio/mpeg","name":"R?dio Stronda[ Digital ] Servidor<br />
4-[SHOUTcast.com]","cst":"","lc":"243","ml":"70","br":"64","ct":"T.I. feat Rihanna - Live Your ife"},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
==Get Stations by Bitrate or Codec Type or Genre ID==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get stations which match a particular bitrate or codec type.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>'''<br />
:* Stations filtered by bitrate<br />
::<nowiki>http://api.shoutcast.com/station/advancedsearch?br=128&limit=10&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
:* Stations filtered by media type<br />
::<nowiki>http://api.shoutcast.com/station/advancedsearch?mt=audio/mpeg&limit=10&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
:* Stations filtered by Genre ID<br />
::<nowiki>http://api.shoutcast.com/station/advancedsearch?genre_id=1&limit=10&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
:* Stations filtered by bitrate, media type & genre<br />
::<nowiki>http://api.shoutcast.com/station/advancedsearch?mt=audio/mpeg&br=128&search=Trance&&limit=10&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID. <br />
* br - Filter the stations based on bitrate specified.<br />
* mt - Filter the stations based on media type specified.<br />
* genre_id - Genre Id from the genre API<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
* limit - Limits the no of results to be returned in output.<br />
* genre - Filter stations that match the genre passed.<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name=".977 The Hitz Channel" mt="audio/mpeg" id="9907" <br />
br="128" genre="Pop Rock Top 40"<br />
ct="Chingy - Balla Baby" lc="11576"/><br />
<station name="TechnoBase.FM - 24h Techno, Dance, Trance, House and More - 128k MP3-[SHOUTcast.com]"<br />
mt="audio/mpeg"id="7429" br="128"genre="Techno Trance Dance House"<br />
ct="We aRe oNe" lc="8308" ml="8500" nsc="No" cst=""/><br />
<station name="Absolutely Smooth Jazz - S K Y . F M - the world's smoothest<br />
jazz 24 hours a day-[SHOUTcast.com]" mt="audio/mpeg" id="948"br="96" genre="Soft Smooth Jazz"<br />
ct="Jonathan Butler/Kirk Whalum - Dancing on the Shore" lc="6801" ml="10023" nsc="No" cst=""/><br />
.<br />
.<br />
</stationlist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
* Stations based on bitrate<br />
:<nowiki>http://api.shoutcast.com/station/advancedsearch?br=128&limit=3&f=json&k=[Your Dev ID]</nowiki><br />
<br />
* Stations based on media type<br />
:<nowiki>http://api.shoutcast.com/station/advancedsearch?mt=mpeg&limit=3&f=json&k=[Your Dev ID]</nowiki><br />
<br />
* Stations based on genre id<br />
:<nowiki>http://api.shoutcast.com/station/advancedsearch?genre_id=1&limit=3&f=json&k=[Your Dev ID]</nowiki><br />
<br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Pop Rock Top 40","id":"9907",mt":"audio/mpeg","name":".977 The<br />
HitzChannel-[SHOUTcast.com]","cst":"","lc":"11576","ml":"8500","br":"128","ct":"Chingy - Balla Baby"},<br />
{"nsc":"No","genre":"Techno Trance<br />
DanceHouse","id":"7429","mt":"audio/mpeg",<br />
"name":"TechnoBase.FM - 24h<br />
Techno, Dance,Trance, House and More -128kMP3-[SHOUTcast.com]","lc":"8308","ml":"10023",<br />
"br":"128","ct":"We aRe oNe"},<br />
{"nsc":"No","genre":"Soft Smooth Jazz","id":"948","mt":"audio/mpeg",<br />
"name":"Absolutely Smooth Jazz - S K Y . F M - the world's<br />
smoothest jazz 24hours a day-[SHOUTcast.com]","cst":"","lc":"6801","ml":"18600","br":"96",<br />
"ct":"Jonathan Butler/Kirk Whalum - Dancing on the Shore"},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Pop Rock Top 40","id":"9907",mt":"audio/mpeg","name":".977 The<br />
HitzChannel-[SHOUTcast.com]","cst":"","lc":"11576","ml":"8500","br":"128","ct":"Chingy - Balla Baby"},<br />
{"sc":"No","genre":"Techno Trance<br />
DanceHouse","id":"7429","mt":"audio/mpeg",<br />
"name":"TechnoBase.FM - 24h<br />
Techno, Dance,Trance, House and More -128kMP3-[SHOUTcast.com]","lc":"8308",<br />
"ml":"10023","br":"128","ct":"We aRe oNe"},<br />
{"nsc":"No","genre":"Soft Smooth Jazz","id":"948","mt":"audio/mpeg",<br />
"name":"Absolutely Smooth Jazz - S K Y . F M - the world's<br />
smoothest jazz 24hours a day-[SHOUTcast.com]","cst":"","lc":"6801","ml":"18600","br":"96",<br />
"ct":"Jonathan Butler/Kirk Whalum - Dancing on the Shore"},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
==Get Random Stations==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get random stations on SHOUTcast Radio Directory. Random stations can be restricted to the Bitrate/Genre/Media type specified.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>'''<br />
<br />
:* <nowiki>http://api.shoutcast.com/station/randomstations?k=[Your Dev ID]&f=xml</nowiki><br />
::Returns a random station. This API by default returns one random station.<br />
::To get more random stations, set the number of stations to return by passing the limit parameter.<br />
<br />
:* <nowiki>http://api.shoutcast.com/station/randomstations?k=[Your Dev ID]&f=xml&mt=audio/mpeg&br=128&genre=Fresh</nowiki><br />
::Returns a random station. This API by default returns one random station.<br />
::To get more random stations, set the number of stations to return by passing the limit parameter.<br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
* br - Bitrate to filter the station result. <br />
* mt - Media type to filter the station result. <br />
* genre - Genre to filter the station result. <br />
* limit - This API by default returns one station. To get more random stations, set the number of stations to return by passing the limit parameter.<br />
<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''(Parameter Limit)<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name="FreshBakedJams.com-[SHOUTcast.com]" mt="audio/mpeg" id="429395" br="128" genre="Fresh BakedJams"<br />
ct="D-Rellz - Story" lc="0" ml="600" nsc="No"/><br />
</stationlist><br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/station/nowplaying?ct=rihanna&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Turkish TurkTurkce","id":205936,"mt":"audio/mpeg",<br />
"name":"TRD 1 - Turk Radyo Dunyasi - Turkish World<br />
Radio - SMS: +90 544 644 6226- www.trd.com.tr-[SHOUTcast.com]",<br />
"lc":2,"ml":"600","br":32,"ct":"Nalan -Sonunda Bitti"},<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Turkish TurkTurkce","id":205936,"mt":"audio/mpeg",<br />
"name":"TRD 1 - Turk Radyo Dunyasi - Turkish World<br />
Radio - SMS: +90 544 644 6226- www.trd.com.tr-[SHOUTcast.com]",<br />
"lc":2,"ml":"600","br":32,"ct":"Nalan -Sonunda Bitti"}, <br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
=Get Genres on SHOUTcast Radio Directory=<br />
<br />
==Get All Genres==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get all the genres on SHOUTcast Radio Directory<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/genrelist?k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<br />
<source lang="xml"><br />
<genrelist><br />
<genre name="30s"/><br />
<genre name="40s"/><br />
<genre name="50s"/><br />
<genre name="60s"/><br />
<genre name="70s"/><br />
<genre name="80s"/><br />
<genre name="90s"/><br />
.<br />
.<br />
</genrelist><br />
</source><br />
<br />
<br />
==Get Primary Genres==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get only the Primary Genres on SHOUTcast Radio Directory<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/genre/primary?k=[Your Dev ID]&f=xml</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* f - the response format (xml, json,rss). You can choose xml, json or rss based results.<br />
* k - API Dev ID.<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only).<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<genrelist> <br />
<genre name="Alternative" id="1" parentid="0" haschildren="true"/><br />
<genre name="Blues" id="24" parentid="0" haschildren="true"/><br />
.<br />
.<br />
.<br />
</genrelist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},<br />
{"id":24,"haschildren":true,"name":"Blues","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok" <br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},<br />
{"id":24,"haschildren":true,"name":"Blues","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
==Get Secondary Genres==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get secondary genre list (if present) for a specified primary genre.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/genre/secondary?parentid=0&k=[Your Dev ID]&f=xml</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* parentid - Genreid of the primary genre. You can retreive the entire genre set by passing parentid=0.<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID.<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<genrelist><br />
<genre name="Alternative" id="1" parentid="0" haschildren="true"><br />
<genrelist><br />
<genre name="Adult Alternative" id="2" parentid="1" haschildren="false"/><br />
<genre name="Britpop" id="3" parentid="1" haschildren="false"/><br />
<genre name="Classic Alternative" id="4" parentid="1" haschildren="false"/> <br />
.<br />
.<br />
</genrelist><br />
</genre><br />
</genrelist><br />
</data><br />
<response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/genre/secondary?parentid=0&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
"genrelist":{<br />
"genre":[<br />
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},<br />
{"id":24,"haschildren":true,"name":"Blues","parentid":0},<br />
{"id":32,"haschildren":true,"name":"Classical","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
"genrelist":{<br />
"genre":[<br />
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},<br />
{"id":24,"haschildren":true,"name":"Blues","parentid":0},<br />
{"id":32,"haschildren":true,"name":"Classical","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
==Get Genres Details by Passing Genreid==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get details such as Genre Name, Sub Genres (if its a primary genre), has children by passing the genre-id.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/genre/secondary?id=25&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* id - Input respective genre or sub-genre id.<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200 </statusCode><br />
<statusText>Ok </statusText><br />
<data><br />
<genrelist> <br />
<genre name="Acoustic Blues" id="25" parentid="24" haschildren="false"/><br />
</genrelist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/genre/secondary?id=25&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":{<br />
{"id":25,"haschildren":false,"name":"AcousticBlues","parentid":24}<br />
}<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok" <br />
}, <br />
"data":"{<br />
"genrelist":{<br />
"genre":{<br />
{"id":25,"haschildren":false,"name":"AcousticBlues","parentid":24}<br />
}<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
==Get Genres Based on Availability of Sub-Genres==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get genres based on their sub-genre availability at any node level in the genre hierarchy of SHOUTcast.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>'''<br />
:*Genres with sub genres:<br />
::<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=true&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
:*Genres without sub genres:<br />
::<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=false&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* haschildren<br />
:* 'true' to get genre or subgenre which has sub-genres.<br />
:* 'false' to get genre or subgenre which does not have sub-genres.<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID.<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<genrelist> <br />
<genre name="Alternative" id="1" parentid="0" haschildren="true"/><br />
<genrelist><br />
<genre name="Adult Alternative" id="2" parentid="1" haschildren="false"/><br />
<genre name="Britpop" id="3" parentid="1" haschildren="false"/><br />
.<br />
.<br />
</genrelist><br />
</genre><br />
<genre name="Blues" id="24" parentid="0" haschildren="true"/><br />
<genrelist><br />
<genre name="Adult Alternative" id="2" parentid="1" haschildren="false"/><br />
<genre name="Britpop" id="3" parentid="1" haschildren="false"/><br />
.<br />
.<br />
</genrelist><br />
</genre><br />
.<br />
.<br />
</genrelist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=true&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
"genrelist":{<br />
"genre":[<br />
{"id":2,"haschildren":false,"name":"AdultAlternative","parentid":1},<br />
{"id":3,"haschildren":false,"name":"Britpop","parentid":1},<br />
{"id":4,"haschildren":false,"name":"ClassicAlternative","parentid":1},<br />
{"id":205,"haschildren":false,"name":"RapMetal","parentid":195},<br />
{"id":195,"haschildren":true,"name":"Metal","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
"genrelist":{<br />
"genre":[<br />
{"id":2,"haschildren":false,"name":"AdultAlternative","parentid":1},<br />
{"id":3,"haschildren":false,"name":"Britpop","parentid":1},<br />
{"id":4,"haschildren":false,"name":"ClassicAlternative","parentid":1},<br />
{"id":205,"haschildren":false,"name":"RapMetal","parentid":195},<br />
{"id":195,"haschildren":true,"name":"Metal","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
=Other=<br />
<br />
==How To Tune Into A Station==<br />
<br />
To tune into a station, find the "id" of the station from the API results & make a call to <nowiki>http://yp.shoutcast.com<base>?id=[Station_id]</nowiki> by appending the station id.<br />
<br />
The '''<base>''' value is taken from the '''tunein''' node and based on the playlist format required (as PLS, M3U and XSPF formats are supported) you then need to choose the appropriate attribute to get the complete playlist url to use.<br />
<br />
'''Ex:''' If the station id is 1025, Call => <nowiki>http://yp.shoutcast.com/<base>?id=1025</nowiki><br />
<br />
<br />
==XML Caching==<br />
<br />
Do not cache the XML for more than 1 day, as station ID's can and will change.<br />
<br />
<br />
==Error Codes==<br />
<br />
The Error codes encountered when invalid data is input or passed to access the APIs are as below<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!HTTP Error Code<br />
!Error Message<br />
|-<br />
| 400 || Bad Request<br />
|-<br />
| 404 || Page Not Found<br />
|-<br />
| 440 || Invalid Devid<br />
|-<br />
| 460 || Missing required parameter<br />
|-<br />
| 462 || Parameter Error<br />
|-<br />
| 500 || Generic Server Error<br />
|}<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!Business Error Code<br />
!Error Message<br />
|-<br />
| 10001 || Internal Server error<br />
|-<br />
| 10002 || XML Root Element not matching<br />
|-<br />
| 10003 || Error while interacting with private api<br />
|}<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!General Error Code<br />
!Error Message<br />
|-<br />
| 20001 || Unable to find InitialContext<br />
|-<br />
| 20002 || Unable to acquire DataSource<br />
|-<br />
| 20003 || Unable to load SQL query<br />
|-<br />
| 20004 || Unable to load property file<br />
|-<br />
| 20005 || Unable to execute SQL query<br />
|-<br />
| 20006 || Unable to fetch ResultSet<br />
|-<br />
| 20007 || Error in finally block<br />
|-<br />
| 20008 || NullPointer Exception Raised<br />
|-<br />
| 20009 || Error while adding xml element<br />
|-<br />
| 20010 || Number Format Exception<br />
|-<br />
| 20011 || Error in creating xml document<br />
|-<br />
| 20012 || Null object received<br />
|-<br />
| 20012 || XML Data not found in Cache<br />
|-<br />
| 20013 || File not found<br />
|-<br />
| 20014 || Unable to connect to search api<br />
|-<br />
| 20015 || Error while building xml document<br />
|-<br />
| 20016 || Error while encoding url string<br />
|-<br />
| 20017 || Error while connecting to shoutcast api<br />
|-<br />
| 20018 || Error while processing the jsp<br />
|-<br />
| 20019 || Error while reading request object<br />
|-<br />
| 20020 || Error while sending email<br />
|-<br />
| 20021 || Invalid Response Type<br />
|-<br />
| 20022 || Maximum Value Exceeded<br />
|-<br />
| 20023 || Error while connecting to AKES<br />
|-<br />
| 20024 || Error while building AKES response xml document<br />
|-<br />
| 20025 || No Data in AKES response xml document<br />
|-<br />
| 20026 || Missing required parm : (REFERRER)<br />
|-<br />
| 20027 || Invalid key received from<br />
|-<br />
| 20028 || Missing devId= or k= param<br />
|-<br />
| 20029 || Missing required parm : (k)<br />
|-<br />
| 20030 || Missing required parm : (keyType)<br />
|-<br />
| 20027 || Deny - authRequired fail<br />
|-<br />
| 20028 || Deny - usageLimited fail<br />
|-<br />
| 20029 || Deny - rightNotSet fail<br />
|-<br />
| 20030 || Deny - referrerUsageLimited fail<br />
|}</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_CDN_FeaturesSHOUTcast Server CDN Features2014-11-07T16:21:49Z<p>DrO: Protected "SHOUTcast Server CDN Features" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
When running the SHOUTcast DNAS server in a CDN sitatuation, since v2.4.1, there are some additional configuration options which can be used to make it easier to automatically setup CDN master-slave (relay) configurations and allow for streams not listed in the SHOUTcast Directory to still be able to make use of the DNAS+ functionality i.e. the monetisation services when streaming.<br />
<br />
The automatic setup provided is where a CDN slave is able to inherit the authhash of the CDN master when it connects to the CDN master which can make it quicker to create snd update multi-DNAS clusters without having to manually configure all aspects of the DNAS configurations (though you can still do that it you prefer to do so).<br />
<br />
<br />
==Configuration Options==<br />
<br />
The configuration options work in-conjunction with the existing DNAS server configuration options (unless otherwise stated) as detailed in the [[SHOUTcast_DNAS_Server_2#Configuration_File|DNAS Server (section 4.0)]] documentation. It is assumed throughout that the DNAS server has been correctly configured with all applicable passwords, etc as needed so that the DNAS server will allow the YP server, source clients and listener clients to connect as required.<br />
<br />
'''cdn''' : This is used to control whether the DNAS is running in CDN mode or not and the specific level of functionality enabled ''[Default = <no value>]''<br />
<br />
This has to be one of the following values when using the DNAS+ for CDN service:<br />
<br />
:: '''on''' → This enables '''opt-in''' mode where all streams needing CDN behaviour have to be specifically configured to use it<br />
:: '''always''' → This enables '''opt-out''' mode where all streams will by default be able to work as CDN masters and CDN slaves<br />
:: '''master''' → This is a hybrid mode so all streams will by default be able to work as a CDN master but need to be manually configured to work as a CDN slave (if required)<br />
<br />
Using 'cdn=master' is recommended for source DNAS in a master-slave<br />
configuration where it is not needed to have any CDN slave configured.<br />
<br />
<br />
'''<MULTI>''' (one set for each stream configuration as required). See [[SHOUTcast_DNAS_Server_2#Configuration_File|DNAS Server (section 4.0)]] if unsure how to use <MULTI> options.<br />
<br />
In all cases it is possible to override the behaviour (opt-in or opt-out)<br />
on a per-stream basis. If not specified then the global value is used.<br />
<br />
<br />
'''cdnmaster''' : This controls if the stream is allowed to act as a CDN master ''[Default = <automatic>]''<br />
<br />
If not specified then this is assumed as one of the following values based on the ''''cdn'''' mode:<br />
<br />
:: '''cdn=on''' → cdnmaster=0<br />
:: '''cdn=always''' → cdnmaster=1<br />
:: '''cdn=master''' → cdnmaster=1<br />
<br />
<br />
'''cdnslave''' : This controls if the stream is allowed to act as a CDN slave ''[Default = <automatic>]''<br />
<br />
If not specified then this is assumed as one of the following values based on the ''''cdn'''' mode:<br />
<br />
:: '''cdn=on''' → cdnslave=0<br />
:: '''cdn=always''' → cdnslave=1<br />
:: '''cdn=master''' → cdnslave=0<br />
<br />
<br />
The Server Admin Summary page ('''admin.cgi?sid=0''') will show the CDN mode that each of the streams have been configured. Additionally the Admin Summary page ('''admin.cgi?sid=x''' where '''x''' is the stream number) will indicate if a CDN slave is connected to the stream.<br />
<br />
<br />
===Relay Streams===<br />
----<br />
A key feature of the CDN functionality is the ability to make it simpler to create master-slave relay setups and so allow for easier multiple DNAS clustering if such functionality is required for the stream(s). If not required see [[#Standard Streams|Standard Streams]].<br />
<br />
By configuring the DNAS for a stream as master(s) and slave(s) as needed and following the requirements detailed in the following sections, it is possible to have a CDN slave automatically obtain the details needed (via authhash inheritence) to then be listed in the SHOUTcast Directory or to act as an intermediary DNAS server which in-turn is able to provide authhash inheritence to CDN slaves connected to it and so on.<br />
<br />
<br />
====Master====<br />
----<br />
When a stream is configured as a CDN master, it will only allow authhash inheritence for a CDN slave if the connecting CDN slave is correctly reported as one and that the address of the slave is in the [[SHOUTcast_DNAS_Server_2#Reserved_List|Reserved List (section 4.11)]].<br />
<br />
This requirement of the CDN slave being in the Reserved List is force enabled (equivalent of setting ''''riponly=1'''' or ''''streamriponly=1'''') when enabling CDN mode and is done to ensure that only allowed CDN slave connections can join the stream(s) on the CDN master.<br />
<br />
<br />
====Slave====<br />
----<br />
When a stream is configured as a CDN slave, it will only be allowed to connect to a CDN master if the master has been correctly configured to allow connections from the host / IP address reported by the CDN slave on connection.<br />
<br />
If the master is not configured as a valid CDN master then the CDN slave will not inherit the authhash of the CDN master and it also may not be allowed to connect as relay (due to the [[SHOUTcast_DNAS_Server_2#Reserved_List|Reserved List (section 4.11)]] requirement).<br />
<br />
<br />
====Intermediary====<br />
----<br />
When a stream is configured as a CDN intermediary, it will work as both a CDN master and as a CDN slave. This is helpful if wanting to have intermediary layers in a CDN setup whilst still being able to have authhash inheritence to ensure that all of the public facing CDN slaves provide the correct stream details.<br />
<br />
<br />
===Standard Streams===<br />
----<br />
A standard stream is one where you are not needing to have a master-slave pairing (when there is no relaying required) or you do not require authhash inheritence support but still require the monetisation functionality to work.<br />
<br />
For such setups, ensuring you have ''''cdn=on'''' specified in the DNAS server configuration file is all that is needed so the streams are handled in the ''''opt-in'''' mode which will prevent unwanted master-slave relay configurations whilst still allowing all other functionality to work.<br />
<br />
This mode does not prevent you from configuring other streams on the same DNAS server to be able to work as a CDN master or CDN slave which requires specifying the ''''cdnmaster'''' and / or ''''cdnslave'''' configuration options as required for the setup</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Server_CDN_FeaturesSHOUTcast Server CDN Features2014-11-07T16:21:41Z<p>DrO: Created page with "{{Template:NavBarSC}} ==Introduction== When running the SHOUTcast DNAS server in a CDN sitatuation, since v2.4.1, there are some additional configuration options which can ..."</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
When running the SHOUTcast DNAS server in a CDN sitatuation, since v2.4.1, there are some additional configuration options which can be used to make it easier to automatically setup CDN master-slave (relay) configurations and allow for streams not listed in the SHOUTcast Directory to still be able to make use of the DNAS+ functionality i.e. the monetisation services when streaming.<br />
<br />
The automatic setup provided is where a CDN slave is able to inherit the authhash of the CDN master when it connects to the CDN master which can make it quicker to create snd update multi-DNAS clusters without having to manually configure all aspects of the DNAS configurations (though you can still do that it you prefer to do so).<br />
<br />
<br />
==Configuration Options==<br />
<br />
The configuration options work in-conjunction with the existing DNAS server configuration options (unless otherwise stated) as detailed in the [[SHOUTcast_DNAS_Server_2#Configuration_File|DNAS Server (section 4.0)]] documentation. It is assumed throughout that the DNAS server has been correctly configured with all applicable passwords, etc as needed so that the DNAS server will allow the YP server, source clients and listener clients to connect as required.<br />
<br />
'''cdn''' : This is used to control whether the DNAS is running in CDN mode or not and the specific level of functionality enabled ''[Default = <no value>]''<br />
<br />
This has to be one of the following values when using the DNAS+ for CDN service:<br />
<br />
:: '''on''' → This enables '''opt-in''' mode where all streams needing CDN behaviour have to be specifically configured to use it<br />
:: '''always''' → This enables '''opt-out''' mode where all streams will by default be able to work as CDN masters and CDN slaves<br />
:: '''master''' → This is a hybrid mode so all streams will by default be able to work as a CDN master but need to be manually configured to work as a CDN slave (if required)<br />
<br />
Using 'cdn=master' is recommended for source DNAS in a master-slave<br />
configuration where it is not needed to have any CDN slave configured.<br />
<br />
<br />
'''<MULTI>''' (one set for each stream configuration as required). See [[SHOUTcast_DNAS_Server_2#Configuration_File|DNAS Server (section 4.0)]] if unsure how to use <MULTI> options.<br />
<br />
In all cases it is possible to override the behaviour (opt-in or opt-out)<br />
on a per-stream basis. If not specified then the global value is used.<br />
<br />
<br />
'''cdnmaster''' : This controls if the stream is allowed to act as a CDN master ''[Default = <automatic>]''<br />
<br />
If not specified then this is assumed as one of the following values based on the ''''cdn'''' mode:<br />
<br />
:: '''cdn=on''' → cdnmaster=0<br />
:: '''cdn=always''' → cdnmaster=1<br />
:: '''cdn=master''' → cdnmaster=1<br />
<br />
<br />
'''cdnslave''' : This controls if the stream is allowed to act as a CDN slave ''[Default = <automatic>]''<br />
<br />
If not specified then this is assumed as one of the following values based on the ''''cdn'''' mode:<br />
<br />
:: '''cdn=on''' → cdnslave=0<br />
:: '''cdn=always''' → cdnslave=1<br />
:: '''cdn=master''' → cdnslave=0<br />
<br />
<br />
The Server Admin Summary page ('''admin.cgi?sid=0''') will show the CDN mode that each of the streams have been configured. Additionally the Admin Summary page ('''admin.cgi?sid=x''' where '''x''' is the stream number) will indicate if a CDN slave is connected to the stream.<br />
<br />
<br />
===Relay Streams===<br />
----<br />
A key feature of the CDN functionality is the ability to make it simpler to create master-slave relay setups and so allow for easier multiple DNAS clustering if such functionality is required for the stream(s). If not required see [[#Standard Streams|Standard Streams]].<br />
<br />
By configuring the DNAS for a stream as master(s) and slave(s) as needed and following the requirements detailed in the following sections, it is possible to have a CDN slave automatically obtain the details needed (via authhash inheritence) to then be listed in the SHOUTcast Directory or to act as an intermediary DNAS server which in-turn is able to provide authhash inheritence to CDN slaves connected to it and so on.<br />
<br />
<br />
====Master====<br />
----<br />
When a stream is configured as a CDN master, it will only allow authhash inheritence for a CDN slave if the connecting CDN slave is correctly reported as one and that the address of the slave is in the [[SHOUTcast_DNAS_Server_2#Reserved_List|Reserved List (section 4.11)]].<br />
<br />
This requirement of the CDN slave being in the Reserved List is force enabled (equivalent of setting ''''riponly=1'''' or ''''streamriponly=1'''') when enabling CDN mode and is done to ensure that only allowed CDN slave connections can join the stream(s) on the CDN master.<br />
<br />
<br />
====Slave====<br />
----<br />
When a stream is configured as a CDN slave, it will only be allowed to connect to a CDN master if the master has been correctly configured to allow connections from the host / IP address reported by the CDN slave on connection.<br />
<br />
If the master is not configured as a valid CDN master then the CDN slave will not inherit the authhash of the CDN master and it also may not be allowed to connect as relay (due to the [[SHOUTcast_DNAS_Server_2#Reserved_List|Reserved List (section 4.11)]] requirement).<br />
<br />
<br />
====Intermediary====<br />
----<br />
When a stream is configured as a CDN intermediary, it will work as both a CDN master and as a CDN slave. This is helpful if wanting to have intermediary layers in a CDN setup whilst still being able to have authhash inheritence to ensure that all of the public facing CDN slaves provide the correct stream details.<br />
<br />
<br />
===Standard Streams===<br />
----<br />
A standard stream is one where you are not needing to have a master-slave pairing (when there is no relaying required) or you do not require authhash inheritence support but still require the monetisation functionality to work.<br />
<br />
For such setups, ensuring you have ''''cdn=on'''' specified in the DNAS server configuration file is all that is needed so the streams are handled in the ''''opt-in'''' mode which will prevent unwanted master-slave relay configurations whilst still allowing all other functionality to work.<br />
<br />
This mode does not prevent you from configuring other streams on the same DNAS server to be able to work as a CDN master or CDN slave which requires specifying the ''''cdnmaster'''' and / or ''''cdnslave'''' configuration options as required for the setup</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_DNAS_Server_2SHOUTcast DNAS Server 22014-11-07T16:21:14Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The purpose of this document is to show you the different configuration options supported by sc_serv along with basic and more advanced example configurations to enable you to get started with using sc_serv and the features it can offer.<br />
<br />
The aim of sc_serv is to provide enhanced serving features and also access to the new YP2 infrastructure whilst maintaining as much backward compatibility with previous versions of sc_serv as possible. The new features introduced include:<br />
<br />
# Serving multiple streams from a single server instance<br />
# Relaying multiple streams from a single server instance<br />
# Multiplexing all server activity through a single IP port<br />
# SHOUTcast 2 wire protocol support for sources, relays and clients<br />
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients<br />
# YP2 infrastructure support<br />
# Real-time metadata and statistic reporting<br />
# Static station id support<br />
# In-stream metadata in standardised xml files<br />
# UTF-8 and international character encoding<br />
# Improved server and stream security<br />
<br />
<br />
==Overview of Features==<br />
<br />
To take full advantage of the newer features provided as part of the SHOUTcast 2 and YP2 systems then you will need to ensure you are using a compatible version of sc_serv (any version 2 will work) and that you have the required authorisation key to register as a broadcaster on the YP2 directory (see [[#Getting_Started|section 3.0]]).<br />
<br />
If you were intending on taking full advantage of the multiplexing and multiple stream support offered as part of sc_serv then you would need to make sure you enable the SHOUTcast 2 options (this is enabled by default with server builds from the end of 2010 if the 'yp2' option in the configuration file is not specified [see [[#YP_Server_Behaviour|section 4.14]] ). The reason for needing to enable this support is if you try to do it with the original SHOUTcast 1 protocol then it will not work as the original protocol has no means of expressing multiple streams from a single port due to the lack of an identifier provided for them.<br />
<br />
If you are planning on connecting multiple sc_trans instances to sc_serv then you must use the SHOUTcast 2 protocol support so that each sc_trans instance can have a unique identifier which allows for multiple streams to then be provided from a single server. It is still possible for an older source to connect to the server with a number of config options available to support this though functionality will be limited compared to what can be done with a fully supporting SHOUTcast 2 source.<br />
<br />
Finally clients connecting to your server do not need to directly support SHOUTcast 2 as sc_serv will repackage the stream data and any related metadata into the correct format the client requests (typically based on the user agent detected by the server).<br />
<br />
<br />
==Getting Started==<br />
<br />
One of the key aspects of the new YP2 directory infrastructure is an authorisation key which is used to validate your server when it tries to connect to the YP2 infrastructure for any of the station(s) you run. Once this key is obtained, it will be valid for all root servers of the station being broadcast.<br />
<br />
This can be done by going to the [[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]] page which shows how to do this via the 'Administation Summary' page as long as a valid source has been connected to the server. This process automatically updates your configuration file(s) with the new authhash and if the stream is set to be public then will attempt to get the stream listed in the SHOUTcast Radio Directory.<br />
<br />
When using an older SHOUTcast 1 server then you do not need to do this registration and the server will still be able to be listed on the directory but there is not the same level of protection over the stream as is the case with registering it.<br />
<br />
<br />
===Running the Server===<br />
----<br />
<br />
The server is able to be run either as a console application or it can be run as service (Windows) or daemon (Linux / Mac OS X / BSD). Detailed below is how to get the server running on the different operating systems supported by it.<br />
<br />
<br />
===Windows===<br />
----<br />
<br />
The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.<br />
<br />
Please note that the Windows versions of sc_serv are built with a dependency against the Microsoft Visual C++ 2008 SP1 Redistributable Package. If sc_serv is unable to start due to a dependency issue then you will need to install the correct version of the package so it can run which depends on the version of sc_serv you are attempting to run:<br />
<br />
32-bit version:<br />
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2<br />
<br />
64-bit version:<br />
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e<br />
<br />
<br />
====Install as a Service====<br />
----<br />
<br />
sc_serv.exe install <servicename> <username> <password> <conf><br />
<br />
<servicename> - Name of service<br />
Typically enter this as 'sc_serv' though you can use a different name but you will need<br />
to remember it as it is required to be the same when using the 'uninstall' mode.<br />
<br />
<username> - User under which to run the service as or '0' for the local system<br />
<br />
<password> - Password for user or '0' for the local system or with no password<br />
<br />
<conf> - File path to the configuration file<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
When run as a service there is not a good sense of a current working directory so requires all paths in the configuration and playlist files to be fully qualified otherwise lookups will fail when sc_serv is run.<br />
<br />
To run sc_serv with a configuration file in the same folder as the server as the current system user account you would enter into the console:<br />
<br />
sc_serv.exe install sc_serv 0 0 sc_serv.conf<br />
<br />
<br />
====Uninstall the Service====<br />
----<br />
<br />
sc_serv.exe uninstall <servicename><br />
<br />
<servicename> - Name of service as used when the service was registered<br />
<br />
To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:<br />
<br />
sc_serv.exe uninstall sc_serv<br />
<br />
<br />
====Run as a Non-Service in the Console====<br />
----<br />
<br />
sc_serv.exe <conf><br />
<br />
<conf> - File path to the configuration file (can be relative or absolute)<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
<br />
===Linux / Mac OS X / BSD===<br />
----<br />
<br />
Remember to enable the required access on the sc_trans file by doing 'chmod a+x sc_trans' after extracting it from the distribution file otherwise the OS is likely to not run it and show the error message './sc_serv: Permission denied'.<br />
<br />
====Run as a Daemon====<br />
----<br />
<br />
./sc_serv daemon <conf><br />
<br />
<conf> - File path to the configuration file (required in all cases)<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
'''e.g.'''<br />
./sc_serv daemon ./sc_serv.conf<br />
<br />
When run this should output the following:<br />
<br />
'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.<br />
<br />
<br />
====End a Daemon====<br />
----<br />
<br />
kill -SIGTERM <pid><br />
or<br />
kill -15 <pid><br />
or<br />
kill -s TERM <pid><br />
<br />
<pid> - The PID of the daemon instance (reported when the daemon started or can be found with 'ps ax | grep sc_serv' as long as sc_serv was the file run otherwise you can just use 'ps ax' if the filename isn't known). Additionally the PID of sc_serv is listed in the log file.<br />
<br />
<br />
====Run as a Non-Daemon====<br />
----<br />
<br />
./sc_serv <conf><br />
<br />
<conf> - File path to the configuration file (can be relative or absolute)<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
<br />
===Additional Signals===<br />
----<br />
<br />
When run on Linux / Mac OS X / BSD then some additional signals are supported to allow for additional control over the running daemon instance of sc_serv.<br />
<br />
The following signals can be used with the 'kill' command (in the manner of your choosing for using the kill command) along with the <pid> of the daemon instance to do one of the following actions:<br />
<br />
SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)<br />
SIGHUP - Rotates logfile, w3clog and streamw3clog<br />
<br />
The result of SIGHUP is that the current log file contents will be moved into <logfile>_1 e.g. sc_serv_1.log, <logfile>_1 will be moved into <logfile>_2 e.g. sc_serv_2.log and so on for all log files which can be found which match the current log file's name. This is useful if timed to have it create day specific log files.<br />
<br />
These signals are not supported by the Windows version of sc_serv which will only<br />
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.<br />
<br />
<br />
==Configuration File==<br />
<br />
Here you can find a complete list of all of the configuration options which are provided by sc_serv which ranges from logging to networking configuration and control over the media being used when streaming via the server.<br />
<br />
Configuration entries labelled as ''<MULTI>'' can be used to set up simultaneous connections to the server or allow for multiple connections from various sources. These are specified by adding _# to the end of the option's name as shown below where # begins with one. If you are only working with a single instance then you do not need to add the _# part as any instances of a configuration option will assume it is for _1.<br />
<br />
Note: The ''<MULTI>'' system is not hierarchical and all values beyond the default must be specified for all connections. So for example, if you wanted to connect to two servers on the same port you must do:<br />
<br />
serverport_1=8080<br />
serverport_2=8080<br />
serverip_1=www.server1.com<br />
serverip_2=www.server2.com<br />
<br />
Note that you CANNOT do it like this as it leads to not all values being set:<br />
<br />
serverport=8080<br />
serverip_1=www.server1.com<br />
serverip_2=www.server2.com<br />
<br />
The configuration files also allow for notes or options to be disabled by the use of a comma (;) at the start of a line which can be seen in all of the configuration examples.<br />
<br />
Known options in the configuration files are recognised irrespective of the case they are entered in the configuration file so maxuser and MaXuSer will be handled the same way.<br />
<br />
Any items found in the configuration file which are not known (as detailed in following sections) or is not processed as a comment will be reported in the following manner:<br />
<br />
<date + time> W msg:[CONFIG] Invalid item on line XX<br />
<br />
Where <date + time> is the date and time the event happens at and XX is the line in the configuration file where the error has been found to occur at.<br />
<br />
<br />
===Banning===<br />
----<br />
<br />
'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''<br />
<br />
'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''<br />
<br />
If you are using a folder for saving the file into then you need to ensure that the<br />
folder already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Client Behaviour===<br />
----<br />
<br />
'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''<br />
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the<br />
maximum limit on the number of client connections allowed to connect to the server instance.<br />
<br />
'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''<br />
A value of zero means there will be no time limit.<br />
<br />
'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''<br />
<br />
'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''<br />
<br />
'''dstip''' or '''destip''' : Specify the server side binding address for clients ''[Default = <no value>]''<br />
If 'any' or no value is specified then sc_serv listens to all addresses.<br />
<br />
If you specify a value for 'dstip / destip' then this will be used by the listen feature on the Administration Pages (see section 5.1) so it can provide a valid stream url in the generated playlist. If 'dstip / destip' is not specified then the server will attempt to auto-generate the IP required for the client to be able to connect. If this fails the generated playlist is likely to return a stream url like <nowiki>http://0.0.0.0:<portbase>/<path></nowiki><br />
<br />
The IP provided needs to be in a valid format like <nowiki>http://<my-ip></nowiki> or an address which can be resolved to an IP otherwise the internal lookups done are likely to fail (depends upon the server configuration and OS being used). Also you cannot set srcip and dstip / destip to be the same IP value and if this happens then the server will close. Closing of the server will also happen if the IP cannot be resolved or correctly bound to i.e. server is not there or an invalid value was entered.<br />
<br />
'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''<br />
<br />
'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''<br />
<br />
<br />
===Debugging===<br />
----<br />
<br />
In all cases, the default value is for no debug logging for the options listed below.<br />
<br />
'''yp1debug''' : Enable debug logging of YP connections<br />
<br />
'''yp2debug''' : Enable debug logging of YP2 connections<br />
<br />
'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections<br />
<br />
'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections<br />
<br />
'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients<br />
<br />
'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients<br />
<br />
'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays<br />
<br />
'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays<br />
<br />
'''relaydebug''' : Enable debug logging of common relay code<br />
<br />
'''streamdatadebug''' : Enable debug logging of common streaming code<br />
<br />
'''httpstyledebug''' : Enable debug logging of http style requests<br />
<br />
'''statsdebug''' : Enable debug logging of statistics<br />
<br />
'''microserverdebug''' : Enable debug logging of common server activity<br />
<br />
'''threadrunnerdebug''' : Enable debug logging of the thread manager<br />
<br />
'''rtmpclientdebug''' : Enable debug logging of rtmp clients<br />
<br />
<br />
===Flash Security===<br />
----<br />
<br />
'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''<br />
<br />
<br />
===Introduction and Backup Files===<br />
----<br />
<br />
'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''<br />
<br />
'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''<br />
<br />
'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''<br />
<br />
'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''<br />
<br />
<br />
===Logging===<br />
----<br />
<br />
'''log''' : Enable logging of the servers output ''[Default = 1]''<br />
<br />
'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''<br />
If log=0 then this option is ignored due to no logging happening.<br />
<br />
'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''<br />
<br />
'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''<br />
<br />
If you are using a folder for saving the logs into then you need to ensure that the folder<br />
already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Miscellaneous===<br />
----<br />
<br />
'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''<br />
<br />
'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''<br />
<br />
'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''<br />
<br />
'''unique''' : Specify a substitution string for the '$' character to be used when processing filenames which if specified will set any occurences of '$' to the value set. This will be used in the processing of the following filenames: '''logfile''', '''introfile''', '''streamintrofile''', '''backupfile''', '''streambackupfile''', '''banfile''', '''streambanfile''', '''ripfile''', '''streamripfile''', '''include''', '''w3clog''', '''streamw3clog'''<br />
<br />
So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is<br />
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'<br />
<br />
'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''<br />
<br />
You can do multiple calls of this allowing for a basic configuration file with then 'specific' stream configurations set in individual conf files though you need to ensure not to include a reference to the same file in itself.<br />
<br />
You can also specify a path with a wildcard for sc_serv to use to find multiple configuration files to include '''e.g.''' 'include=stream/*.conf'. This can then be used along with the multiple stream configurations (see section 4.12) and the admin command 'admin.cgi?mode=reload' (see section 5.1) to add / remove / update stream configurations without having to close the server to apply them.<br />
<br />
'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''<br />
<br />
This can accept the following parameters:<br />
<br />
:admincssfile='''v1''' - Uses the v1 DNAS style<br />
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style<br />
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki><br />
<br />
If using a custom css file, if it does not exist on the first try to load it the server will revert to<br />
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.<br />
<br />
'''faviconfile''' : Specify the file to be returned as the favicon.ico when the administration pages are being queried by the client's browser ''[Default = <no value>]''<br />
<br />
The default behaviour is to use a SHOUTcast themed built-in icon file and support / handling the update of this will entirely depend on the browser.<br />
<br />
'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''<br />
<br />
Ensure this is correct for the type of image being used so it is valid.<br />
<br />
'''hidestats''' : Specify if the publically accessible stats?sid=# page can be accessed or if it is only available via the private administration pages ''[Default = 0]''<br />
<br />
'''robotstxtfile''' : Specify the file to be returned as the robots.txt when queried by search engines, etc to attempt to prevent incorrect access to the server's pages which may cause invalid client connections ''[Default = <no value>]''<br />
<br />
The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.<br />
::User-agent:*<br />
::Disallow:/<br />
<br />
<br />
===Networking===<br />
----<br />
<br />
'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''<br />
<br />
'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''<br />
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.<br />
<br />
'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''<br />
A value of zero means there is no timeout of an idle source.<br />
Also if you set this too low then it is likely that valid sources will<br />
fail to connect during the initial stages of a source connection.<br />
<br />
'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''<br />
<br />
'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''<br />
<br />
'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''<br />
<br />
'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''<br />
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).<br />
<br />
<br />
===Network Buffers===<br />
----<br />
<br />
'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''<br />
<br />
'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''<br />
<br />
'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''<br />
<br />
'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''<br />
<br />
<br />
===Relaying===<br />
----<br />
<br />
'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''<br />
<br />
'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''<br />
<br />
'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''<br />
Setting this to 0 will disable attempts for the relay to reconnect.<br />
<br />
'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''<br />
This generally applies only to YP1 connections and is related to the<br />
actual attempts to make and get a http response from the YP server.<br />
<br />
'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''<br />
<br />
<br />
''<Legacy Options>''<br />
<br />
'''relayport''' : Port of the source to use for the relay ''[Default: 80]''<br />
<br />
'''relayserver''' : Url of the source to relay ''[Default = <no value>]''<br />
<br />
Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method<br />
of setting up a relay. These options are only provided as a means for loading<br />
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.<br />
<br />
<br />
===Reserved List===<br />
----<br />
<br />
'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''<br />
<br />
'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''<br />
<br />
'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''<br />
<br />
If you are using a folder for saving the file into then you need to ensure that the folder<br />
already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Stream Configuration===<br />
----<br />
<br />
'''Important Note:''' If you do not specify an identifier (_#) on the end of the above options then it will be treated like _1 (effectively acting like SHOUTcast 1). Additionally, _0 is not a supported identifier and will be mapped to _1.<br />
<br />
'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in our configuration file ''[Default = 0]''<br />
With this enabled, you will need to ensure that any sources have their configuration details<br />
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with<br />
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).<br />
<br />
''<MULTI>'' (one set for each stream configuration):<br />
<br />
'''streamid''' : Specify the numerical identifier of the stream for control or referencing the stream configuration. This can only be a numeric value from 1 to 2147483647.<br />
<br />
If you use multiple stream configurations then you will need to ensure the _X<br />
part is specified and correct for each stream configuration group<br />
e.g.<br />
streamid=1<br />
streampath=random<br />
or<br />
streamid_1=1<br />
streampath_1=random_stream_path<br />
streamid_2=2<br />
streampath_2=another_stream_path<br />
<br />
'''streamauthhash''' : The authorisation key needed for YP2 directory registration.<br />
This is a requirement for using the YP2 system and without it you will not be able to<br />
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).<br />
<br />
This can be used for multiple streams you are providing or can be different (as long<br />
as valid) so you can infact provide multiple stations from the same server if desired.<br />
<br />
'''streampath''' : Specify the path clients need to use to access the stream<br />
If a / is not specified on the start of the string then the server will add<br />
it to the generated path in playlist entries or other places as required so<br />
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.<br />
<br />
If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be<br />
used for client access and in generated playlist entries so that it will<br />
always be possible for clients to connect to the server somehow. See [[SHOUTcast_DNAS_Server_2#Stream_Addresses|section 6.0]] for more information on the<br />
server's stream address support.<br />
<br />
'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).<br />
Make sure if you use this that the full url is entered and that it is<br />
the url which clients would connect to for the stream to be relayed.<br />
<br />
'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''<br />
If set to zero, not specified or higher than 'maxuser' then the value set for 'maxuser' (see [[#Client_Behaviour|section 4.2]]) will be used for all knwon streams.<br />
<br />
Changing this to a value between zero and 'maxuser' will enforce the user connection limit for the specified value in the stream configuration '''e.g.'''<br />
streammaxuser_1 = 8<br />
maxuser = 32<br />
<br />
This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.<br />
<br />
With the following stream configuration<br />
streammaxuser_1 = 64<br />
maxuser = 32<br />
<br />
This allows a total of 32 connections to the server but with a per stream limit above the maximum means the maximum number of connections to the first stream group will be 32. However this also depends upon any other stream configurations and their limits as to whether 32 clients will be able to connect to this stream configuration.<br />
<br />
Finally unless a valid stream configuration is specified then this value will only be applied to the first stream configuration found i.e. there is a need to specify a streamid_XXX for streammaxuser_XXX (where XXX is the stream identifier of the stream configuration group.<br />
<br />
'''streamadminpassword''' : Specify the administrator password for accessing the remote server features for the specified stream configuration group. If this is not specified then 'adminpassword' will be used.<br />
<br />
'''streampassword''' : Specify the password for broadcasters when connecting to the server for the specified stream configuration group. If this is not specified then 'password' will be used.<br />
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).<br />
<br />
'''streampublicserver''' : This allows you to override the public flag received from the source when a connection is being made to the YP directory. If this is not specified or is set to empty then 'publicserver' will be used.<br />
<br />
'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.<br />
<br />
'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.<br />
<br />
'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.<br />
<br />
'''streamautodumpsourcetime''' : Specify how long before an idle source will be dumped from the server (in seconds). A value of zero means there is no timeout of an idle source. If not specified then 'autodumpsourcetime' will be used.<br />
<br />
'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.<br />
<br />
'''streamlistenertime''' : Specify the maximum time in minutes a client is allowed to listen to the stream. A value of zero means there will be no time limit. If not specified then 'listenertime' will be used.<br />
<br />
'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.<br />
<br />
'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.<br />
<br />
'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.<br />
<br />
'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.<br />
<br />
'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.<br />
<br />
<br />
===Web Connection (W3C) Logging===<br />
----<br />
<br />
'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''<br />
<br />
'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''<br />
<br />
If you are using a folder for saving the log into then you need to ensure that the folder<br />
already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''<br />
<br />
<br />
===YP Server Behaviour===<br />
----<br />
<br />
'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''<br />
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans<br />
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).<br />
<br />
Only change this if you really need to do so as not all SHOUTcast 2 clients will allow you to edit this value from the default value. If using the Source DSP plug-in then see [[Source_DSP_Plug-in#SHOUTcast_2_Cipher_Key|dsp_sc.txt - section 5.0]] for details on how to change the plug-in to use a differnet value.<br />
<br />
'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''<br />
YP1 only<br />
<br />
'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''<br />
<br />
If this is enabled and not all of the required values are set then the server will throw an error and will abort from its start-up attempt. It should be indicated what needs to be set to allow the server to start with this set.<br />
<br />
Additionally if there is an issue then the server will report an error in its log ouput of 'Connection attempt failed. YP2 error code is XXX (<message>)' where XXX is one of the following error codes and <message> is a message set in the error response to indicate a bit more what the error relates to. All current error codes can be found [[#YP_Server_Errors|here]].<br />
<br />
'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''<br />
<br />
'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''<br />
<br />
'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''<br />
<br />
'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''<br />
<br />
'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''<br />
This generally applies only to YP1 connections and is related to the<br />
actual attempts to make and get a http response from the YP server.<br />
<br />
'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''<br />
<br />
'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''<br />
<br />
'''publicserver''' : This allows you to override the public flag from the connected source when a connection is being made to the YP directory ''[Default = default]''<br />
This can be one of the following values:<br />
'''default''' - use the flag provided by the source<br />
'''always''' - force the source to be public<br />
'''never''' - never allow the use the flag provided by the source<br />
<br />
When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).<br />
<br />
<br />
===YP Server Errors===<br />
----<br />
<br />
If not all of the required values are set for a public listing then the DNAS server will throw an error and will abort its attempt to be listed in the Directory. It should be indicated the error is with one of the error codes provided below so it can be resolved.<br />
<br />
Additionally if there is an issue during Directory updates or removals, then the server will report an error in its log ouput as one of the following error codes and <message>.<br />
<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Status Code<br />
! Status Message<br />
|-<br />
| 400 || Generic error ''(covers all other cases usually from internal failures)''<br />
|-<br />
| 457 || Unrecoverable error while updating station information - DNAS restart required.<br />
|-<br />
| 470 || Invalid authorization hash<br />
|-<br />
| 471 || Invalid stream type (could be a bad bitrate or mime type)<br />
|-<br />
| 472 || Missing or invalid stream url<br />
|-<br />
| 473 || Server unreachable by YP<br />
|-<br />
| 474 || Relay url does not exist<br />
|-<br />
| 475 || Invalid server ID<br />
|-<br />
| 476 || Invalid max clients (value out of range or missing)<br />
|-<br />
| 477 || Terms of Service violator. You are being reported.<br />
|-<br />
| 478 || Incompatible protocol.<br />
|-<br />
| 479 || Streams requiring authorization are not public and cannot list here.<br />
|-<br />
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.<br />
|-<br />
| 481 || Cannot verify server since all listener slots are full. Please wait.<br />
|-<br />
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service<br />
|-<br />
| 483 || Invalid listeners (value out of range / missing)<br />
|-<br />
| 484 || Invalid avglistentime (value out of range / missing)<br />
|-<br />
| 485 || Invalid newsessions (value out of range / missing)<br />
|-<br />
| 486 || Invalid connects (value out of range / missing)<br />
|-<br />
| 487 || Request & Response objects are null<br />
|-<br />
| 488 || Request xml is null<br />
|-<br />
| 489 || YP command not specified<br />
|-<br />
| 490 || Generic error, while doing xml parsing<br />
|-<br />
| 491 || Generic error, while reading xml request<br />
|-<br />
| 492 || Error closing buffer / HTTP connection<br />
|-<br />
| 493 || Internal error - unable to acquire data source<br />
|-<br />
| 494 || Error updating information - DNAS restart required<br />
|-<br />
| 495 || Error acquiring station ID - DNAS restart required<br />
|-<br />
| 496 || Error converting data type<br />
|-<br />
| 497 || Inconsistent stream behaviour<br />
|-<br />
| 498 || Invalid Request (Invalid request received)<br />
|-<br />
| 499 || Error while getting information<br />
|}<br />
<br />
<br />
==Administration==<br />
<br />
With sc_serv there are administration pages available for accessing and controlling the server remotely which allows you to monitor and control clients connected to the stream (or not if banning them). These pages can now be accessed through a summary page at /index.html which will show a link to any active stream(s) or you explicitly access them via the /index.html?sid=# path where # is the ID of the stream (see [[#Stream_Configuration|section 4.12]] for more about using 'streamid') '''e.g.'''<br />
<streamurl>/index.html?sid=1<br />
<br />
If no sid or an invalid sid is passed then you will be taken to the summary /index.html and this will be applied even if you were on a page with a known ID and then enter an invalid sid or remove it purposefully.<br />
<br />
<br />
===Administration Pages===<br />
----<br />
<br />
As part of the administrative features provided there are the following pages where # is the streamid you want to use). This is not a complete list but should cover all of the pages which allow for a direct http url to be entered to get an administation action to work. The ban and reserve IP actions require input fields and do not map to direct sends.<br />
<br />
<br />
====Public Pages====<br />
----<br />
<br />
'''index.html''' - Shows a summary page with links to get to any active stream(s)<br />
<br />
'''currentsong?sid=#''' - Returns the current song title or a null response<br />
<br />
'''nextsong?sid=#''' - Returns the next song title (if known) or a null response<br />
currentsong and nextsong both provide a UTF-8 encoded string of the song title<br />
otherwise it will return effectively no response (ignoring the http header).<br />
<br />
'''nextsongs?sid=#''' - Returns in an xml format the next song title(s) (if known) to be played when using a compatible v2 stream source. See [[#XML_Responses|section 5.2]] for more details on the format of the xml returned).<br />
<br />
'''index.html?sid=#''' - Shows current status of the specified stream<br />
<br />
'''played.html?sid=#''' - Song history of specified playing history<br />
:or<br />
'''played?sid=#'''<br />
<br />
'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.<br />
:or<br />
'''listen?sid=#'''<br />
<br />
'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.<br />
<br />
'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.<br />
<br />
With the listen pages you either need to have specified an IP with 'dstip / destip'<br />
(see section 4.2) or leave empty and allow the server to attempt to auto-generate<br />
the IP required for the client to be able to connect. If this fails the generated<br />
playlist is likely to return a stream url like <nowiki>http://0.0.0.0:<portbase>/<path></nowiki><br />
<br />
'''home.html?sid=#''' or '''home?sid=#''' - Opens in a new window or tab (depending on the client browser) the 'streamurl' as specified by the stream source. If this is not set then the client will be redirected to the shoutcast.com main page.<br />
<br />
'''stats?sid=#''' - Provides an xml response for public accessibility which matches the private version from admin.cgi?sid=#&mode=viewxml&page=1. This is the modern version of the 7.html page as provided by the legacy v1 servers. See [[#XML_Responses|section 5.2]] for information on what is provided in the xml response.<br />
<br />
<br />
====Private Pages====<br />
----<br />
<br />
By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible<br />
to directly access the administration page(s) required. As well the base64 encoded version of the password<br />
can be passed as long as it is prefixed with ''YWRtaW46''<br />
e.g.<br />
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=<br />
<br />
'''admin.cgi''' - Shows the an overal summary admin page for the streams provided by the server including direct links to certain information pages (see notes about the 'admin.cgi?sid=#&mode=viewxml' command for more info)<br />
:or<br />
'''admin.cgi?sid=0'''<br />
<br />
'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information<br />
<br />
'''admin.cgi?sid=#&mode=updinfo&song=title''' <br />
:or<br />
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml''' <br />
If 'title' is not empty then it will be set as the current song title for the stream<br />
specified until the next use of this action or the next title update is received from<br />
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]<br />
instead of a v1 title.<br />
<br />
'''admin.cgi?sid=#&mode=viewlog''' - View logfile<br />
<br />
'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)<br />
<br />
The tailing option keeps adding additional log entries to the end of the view whilst the view is active.<br />
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped<br />
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.<br />
<br />
'''admin.cgi?sid=#&mode=viewban''' - Ban view which matches the ban file and allows you to ban a single IP or an IP range from it (see [[#Banning|section 4.1]] for more info on the file)<br />
<br />
'''admin.cgi?sid=#&mode=viewrip''' - Reserved IP list that matches the rip file (see [[#Reserved_IP_.28RIP.29|section 4.11]] for more info on the file)<br />
<br />
'''admin.cgi?sid=#&mode=art''' or '''admin.cgi?sid=#&mode=art&art=playing''' - Displays the artwork SHOUTcast v2 compatible clients may be able to display if the SHOUTcast v2 source does provide it.<br />
<br />
The artwork mode is primarily intended as a debugging option to make it possible<br />
to see what (if anything) has been provided by the SHOUTcast v2 source.<br />
<br />
If no '&art=' is specified or not a matching option then the stream artwork (if<br />
available) will be shown. If no '&art=playing' is specified then this will show<br />
the playing file's artwork (if available).<br />
<br />
'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information<br />
<br />
If page is not set or is outside of the range zero to 6 then this will output all of the<br />
information as the standard viewxml action does. Otherwise this only display information<br />
depending on the value assigned to page which can be from 1 to 6 which maps as follows:<br />
<br />
1 - Server Summary (this is the same as using the public stats?sid=# action)<br />
2 - Not used (previously used for Webdata Stats but not in current builds)<br />
3 - Listener Stats<br />
4 - Song History<br />
5 - Stream Metadata (if supported by the source otherwise can just be title)<br />
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)<br />
<br />
If accessing the standard viewxml or the listener stats (page = 3), you can also send<br />
'&iponly=1' which will filter the listener information (if there are any) to just output<br />
the IP instead of the additional information provided normally.<br />
<br />
'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it<br />
<br />
'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.<br />
<br />
'''admin.cgi?sid=#&mode=unripdst&ripdst=<IP>''' - Where <IP> is the IP to reserve (see [[#Reserved_IP_.28RIP.29|section 4.11]] for more information).<br />
<br />
'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.<br />
<br />
'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.<br />
<br />
'''admin.cgi?mode=rotate''' or '''admin.cgi?mode=rotate&files=log|w3c''' - This will rotate the log files set via the 'logfile', 'w3clog' and 'streamw3clog' options.<br />
If &files is specified then passing log or w3c will allow you to only<br />
rotate one type of file otherwise both will be rotated by this command.<br />
<br />
'''admin.cgi?mode=reload''' or '''admin.cgi?mode=reload&force=1''' - This reloads the stream configuration details in the main configuration file the server used when started and is only available on the admin summary page and so can only be run by the master administrator password.<br />
<br />
This command works on the server as a whole (hence no sid parameter) and it will add or<br />
remove or update any stream configuration as applicable which will cause any connected<br />
sources and clients to be kicked as applicable (usually if a stream configuration was removed).<br />
<br />
This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'<br />
in your main configuration file which the server can then use to detect different stream configurations.<br />
<br />
If '&force=1' is passed then the reload will treat the updating of active stream configurations in the<br />
same manner as a stream configuration removal instead of trying to update compatible stream configuration<br />
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.<br />
<br />
The following configuration options are updated when using this command:<br />
<br />
password or streampassword (*) streamadminpassword (#)<br />
requirestreamconfigs streamid<br />
streamauthhash streampath<br />
streamrelayurl streammaxuser<br />
streampublicserver streamallowrelay<br />
streamallowpublicrelay streamriponly<br />
streamautodumpsourcetime streamautodumpusers<br />
streamlistenertime streamintrofile<br />
streambackupfile streambanfile<br />
streamripfile<br />
<br />
(*) This will depend upon the current values versus the new configuration values<br />
(#) The master 'adminpassword' can only be changed after a restart of the server<br />
<br />
<br />
===XML Responses===<br />
----<br />
<br />
As detailed in the previous sections, some of the administration actions will provide the information in an xml response. For information on what is actually returned in these xml responses see [[SHOUTcast_DNAS_Server_2_XML_Reponses|sc_serv2_xml_responses.txt]].<br />
<br />
<br />
==Stream Addresses==<br />
<br />
Clients connecting to the streams provided by sc_serv are able to so in a number of ways depending upon how the streams have been configured and also depending upon the number of streams you have available.<br />
<br />
The two main ways for a client to connect to a stream are as follows:<br />
<br />
<serverurl>/stream/<streamid>/<br />
or<br />
<serverurl>/<streampath><br />
<br />
<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])<br />
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])<br />
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])<br />
<br />
If the client attempting to connect to the server instance does not specify <streampath> or <streamid> in the stream url it attempts to access or if only one stream is provided then the server will usually default to the first stream it knows about and will allow the client to make a valid connection (though this is not guaranteed to happen).<br />
<br />
This handling of the stream addresses provided is something to keep in mind especially if you are providing multiple streams as this will allow you to provide different addresses for certain clients to be able to use a specific stream '''e.g.''' if you wanted to have mobile clients connect to a lower bandwidth stream then you could direct them to '<serverurl>/mobile'<br />
<br />
The server options available for controlling how the stream's path is specified can be seen in [[#Stream_Configuration|section 4.12]] which also details the equivalent values needing to be set in the sc_trans configuration if you use sc_trans to provide a source to sc_serv.<br />
<br />
<br />
==Locale Error (Linux / Mac OS X / BSD)==<br />
<br />
If you receive the following error then you have a locale related issues:<br />
<br />
terminate called after throwing an instance of 'std::runtime_error'<br />
what(): locale::facet::_S_create_c_locale name not valid<br />
Abort trap<br />
<br />
If this happens then you need to set the 'POSIX' locale in your terminal's environment values. If this does not happen then everything is fine or you are using a newer version of sc_serv from the end of 2010 which should no longer exhibit this issue.<br />
<br />
Linux:<br />
export LC_ALL=POSIX<br />
<br />
BSD:<br />
setenv LC_ALL POSIX<br />
<br />
Mac OS X:<br />
export LC_ALL=POSIX<br />
<br />
You can test to see if this has worked by checking the shell command "locale":<br />
<br />
LANG=<br />
LC_COLLATE="POSIX"<br />
LC_CTYPE="POSIX"<br />
LC_MESSAGES="POSIX"<br />
LC_MONETARY="POSIX"<br />
LC_NUMERIC="POSIX"<br />
LC_TIME="POSIX"<br />
LC_ALL="POSIX"<br />
<br />
<br />
==Virtual Memory Footprint (Linux / Mac OS X / BSD)==<br />
<br />
Due to how sc_serv works it will create a large number of threads which may become an issue due to the default virtual memory stack allocation per thread potentially being large (typically 10MB per thread). For most people this should not be an issue as the memory is not really allocated unless it is used. If however if you have a resource constrained system or if you plan on running many copies of sc_trans then you could potentially run out of virtual memory.<br />
<br />
The default thread allocation can be reduced by issuing a "ulimit" command before running sc_trans and in the example reduces it to 512KB per-thread '''e.g.''' ulimit -s 512<br />
<br />
<br />
==Maximum Client Connection Limits==<br />
<br />
In general, there are inherent limits on the maximum number of client connections which may be made to a running instances of sc_serv which can either be set by configuration limits e.g. 'maxuser', Operating System limits or bandwidth limits being reached.<br />
<br />
The first two are easy to resolve whereas the last (bandwidth limits) is something which will usually require obtaining additional hosting or paying for more available bandwidth.<br />
<br />
If reaching the Operating System limit, this is usually indicated by the maximum number of clients never going above a fixed value even if there is the bandwidth and the server has been configured to go higher. This usually appears as around 1016 maximum connections (though this can vary a bit)<br />
<br />
If using a non-Windows Operating System then you can use the 'ulimit -n xxxx' command to change the upper limit from what is already set which can be found from just 'ulimit -n' e.g. to change the limit to 4096 connections you would run ulimit -n 4096<br />
<br />
If using a Windows Operating System then there isn't any real way to change such things due to the OS hopefully being configured with limits that will not be reached when using sc_serv. If in doubt then consult the Microsoft support documentation for the OS used.<br />
<br />
<br />
==Example Configurations==<br />
<br />
Include as part of the sc_serv installation are a number of example configurations to get things started with using some of the features of the server. The provided examples are:<br />
<br />
sc_serv_basic.conf<br />
sc_serv_public.conf<br />
sc_serv_relay.conf<br />
sc_serv_simple.conf<br />
<br />
All of the configuration examples are documented and will relate back to details in this file appropriately. You will need to change some details in these example files or to obtain any applicable authorisation keys for the setup you are making ([[#Getting_Started|see section 3.0]]). In all cases the examples are designed to work from the same install folder as sc_serv.<br />
<br />
Remember these examples are a way to get you up and running faster though you are still likely to have to adjust things depending upon the systems you are using and how you want to manage your sources and server connections which are covered in previous sections.<br />
<br />
Additionally if you are not happy with editing the files or find it still too confusing then you can use the configuration builder which (if installed) can be found in the 'config_builder'. Open 'config_builder.html' in your browser and then use this graphical tool to setup a configuration file for the server (and additionally the transcoder).<br />
<br />
<br />
===sc_serv_basic===<br />
----<br />
<br />
This is the base configuration from which the other configuration examples are based and this will get a sc_serv instance running as a local setup with no connection made to the YP directory.<br />
<br />
<br />
===sc_serv_public===<br />
----<br />
<br />
This configuration file changes the required options in the sc_serv_basic configuration to get a sc_serv instance running as a public setup with a connection made to the YP for listing the stream in the directory. This shows the use of the 'include' option (see section [[#Miscellaneous|4.7]]) and how specifying a configuration option twice uses the last value found.<br />
<br />
<br />
===sc_serv_relay===<br />
----<br />
<br />
This configuration file changes the required options in the sc_serv_public configuration to get a sc_serv instance running as a public setup with a source coming in from a relay server providing a SHOUTcast 2 stream.<br />
<br />
<br />
===sc_serv_debug===<br />
----<br />
<br />
This configuration file can be included in any other configuration files to allow you to get debug logging output when trying to investigate any issues you may be experiencing.<br />
<br />
<br />
===sc_serv_simple===<br />
----<br />
<br />
Use this if you just need to get a very basic server running or are impatient<br />
or are struggling to get it running despite the previous example configurations.<br />
<br />
This configuration file is designed to be used just as is and is the simplest form of the configuration file you can have which will allow you to get a running server to appear on the YP. This works on using the default settings of the server though does change some of the file paths inorder to fit in with the existing setup as used in the other examples.<br />
<br />
All you need to do when using this configuration file is to enter your authorisation key in the 'streamauthhash' line '''e.g.''' if your authorisation key is '''123456789''' then you change ''streamauthhash=<enter_your_auth_key_here>'' to ''streamauthhash='''123456789''''' and save the file.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Listing_RequirementsSHOUTcast Listing Requirements2014-10-29T18:28:35Z<p>DrO: Protected "SHOUTcast Listing Requirements" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite)) [cascading]</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
=How to get listed in the SHOUTcast Directory=<br />
<br />
There are currently a number of ways for a station to be listed in the SHOUTcast Directory (also referred to as the YP) which this document will detail. If you are still uncertain whether your station can be listed in the SHOUTcast Directory, please contact support with information about your existing station and they will be able to advise you.<br />
<br />
<br />
==SHOUTcast DNAS Server==<br />
<br />
This is the primary way for getting your station listed in the SHOUTcast Directory. To do this, you need to ensure the stream is marked as '''public''' and for all 2.x DNAS you have to have a valid authhash (see '''[[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]]''' for what to do if you are having issues obtaining an authhash for your stream(s)).<br />
<br />
<br />
For the legacy 1.x DNAS (using the 2.x DNAS is preferred over the 1.x DNAS), you just need to ensure the stream is marked as '''public'''.<br />
<br />
<br />
Ensuring the stream is correctly marked as '''public''' can be done either via the connected stream source and the options it provides or it can be done by forcing the DNAS via the '''publicserver''' configuration option which if set as '''publicserver=always''' will override what is provided by the the connected stream source (be that a direct source or a relay source).<br />
<br />
<br />
==Icecast Server==<br />
<br />
This is an alternative server to the SHOUTcast DNAS server which can be configured to be able to be listed in the SHOUTcast Directory as a SHOUTcast 1.x DNAS compatible listing. Such listings will work but due to a lower set of information provided by the Icecast server on it's communication with the SHOUTcast Directory, some aspects of the listings will not be provided and can only be enabled for native SHOUTcast DNAS servers.<br />
<br />
<br />
To get the Icecast server configured to be listed, the following needs to be added to your Icecast server configuration file:<br />
<br />
<source lang="xml"><br />
<directory><br />
<yp-url-timeout>15</yp-url-timeout><br />
<yp-url>http://yp.shoutcast.com</yp-url><br />
</directory><br />
</source><br />
<br />
<br />
Once the above configuration options are present, as long as the Icecast server is able to see the SHOUTcast Directory server and the information it provides passes validation (as only MP3 and AAC based streams can be listed), then the stream should be listed.<br />
<br />
<br />
If needing to include multiple Icecast servers as part of a clustered stream, the station name, genre and website details all need to be the same, otherwise the SHOUTcast Directory may not cluster them correctly together (which can still happen even if the details are correct due to how 1.x DNAS style clustering works).<br />
<br />
<br />
Note: We do not support sending manual updates for the Icecast server like is supported by the Icecast Directory. Each Icecast server to be listed in the SHOUTcast Directory needs to directly provide the required information to the SHOUTcast Directory servers and not doing this can lead to you being banned from being listed in the SHOUTcast Directory.<br />
<br />
<br />
==Radionomy Group Services / SHOUTcast Streaming Service==<br />
<br />
If using any of these services then your station will either be automatically added into the SHOUTcast Directory or will require you to reach a specific number of total listening hours (TLH) before your station is imported into the SHOUTcast Directory. This depends on the service being used as to whether the TLH requirement needs to be met or whether you are automatically imported into the SHOUTcast Directory.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Listing_RequirementsSHOUTcast Listing Requirements2014-10-29T18:28:12Z<p>DrO: Created page with "{{Template:NavBarSC}} =How to get listed in the SHOUTcast Directory= There are currently a number of ways for a station to be listed in the SHOUTcast Directory (also referr..."</p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
=How to get listed in the SHOUTcast Directory=<br />
<br />
There are currently a number of ways for a station to be listed in the SHOUTcast Directory (also referred to as the YP) which this document will detail. If you are still uncertain whether your station can be listed in the SHOUTcast Directory, please contact support with information about your existing station and they will be able to advise you.<br />
<br />
<br />
==SHOUTcast DNAS Server==<br />
<br />
This is the primary way for getting your station listed in the SHOUTcast Directory. To do this, you need to ensure the stream is marked as '''public''' and for all 2.x DNAS you have to have a valid authhash (see '''[[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]]''' for what to do if you are having issues obtaining an authhash for your stream(s)).<br />
<br />
<br />
For the legacy 1.x DNAS (using the 2.x DNAS is preferred over the 1.x DNAS), you just need to ensure the stream is marked as '''public'''.<br />
<br />
<br />
Ensuring the stream is correctly marked as '''public''' can be done either via the connected stream source and the options it provides or it can be done by forcing the DNAS via the '''publicserver''' configuration option which if set as '''publicserver=always''' will override what is provided by the the connected stream source (be that a direct source or a relay source).<br />
<br />
<br />
==Icecast Server==<br />
<br />
This is an alternative server to the SHOUTcast DNAS server which can be configured to be able to be listed in the SHOUTcast Directory as a SHOUTcast 1.x DNAS compatible listing. Such listings will work but due to a lower set of information provided by the Icecast server on it's communication with the SHOUTcast Directory, some aspects of the listings will not be provided and can only be enabled for native SHOUTcast DNAS servers.<br />
<br />
<br />
To get the Icecast server configured to be listed, the following needs to be added to your Icecast server configuration file:<br />
<br />
<source lang="xml"><br />
<directory><br />
<yp-url-timeout>15</yp-url-timeout><br />
<yp-url>http://yp.shoutcast.com</yp-url><br />
</directory><br />
</source><br />
<br />
<br />
Once the above configuration options are present, as long as the Icecast server is able to see the SHOUTcast Directory server and the information it provides passes validation (as only MP3 and AAC based streams can be listed), then the stream should be listed.<br />
<br />
<br />
If needing to include multiple Icecast servers as part of a clustered stream, the station name, genre and website details all need to be the same, otherwise the SHOUTcast Directory may not cluster them correctly together (which can still happen even if the details are correct due to how 1.x DNAS style clustering works).<br />
<br />
<br />
Note: We do not support sending manual updates for the Icecast server like is supported by the Icecast Directory. Each Icecast server to be listed in the SHOUTcast Directory needs to directly provide the required information to the SHOUTcast Directory servers and not doing this can lead to you being banned from being listed in the SHOUTcast Directory.<br />
<br />
<br />
==Radionomy Group Services / SHOUTcast Streaming Service==<br />
<br />
If using any of these services then your station will either be automatically added into the SHOUTcast Directory or will require you to reach a specific number of total listening hours (TLH) before your station is imported into the SHOUTcast Directory. This depends on the service being used as to whether the TLH requirement needs to be met or whether you are automatically imported into the SHOUTcast Directory.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_BroadcasterSHOUTcast Broadcaster2014-10-28T23:03:52Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
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.<br />
<br />
<br />
=SHOUTcast Overview=<br />
<br />
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 />
<br />
<br />
=Getting Started=<br />
<br />
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]]'''<br />
'''Important:''' You need to be happy with the use of command-line tools before attempting to install or run<br />
a SHOUTcast system as all versions of the 2.x DNAS Server are designed to work as command-line tools.<br />
<br />
Current versions of the SHOUTcast tools can be obtained from:<br />
<br />
::'''[http://www.shoutcast.com/BroadcastNow/ Broadcast Tool Downloads]'''<br />
::or<br />
::'''[http://forums.shoutcast.com/showthread.php?t=324877 Support Forum Current Downloads Summary] (*)'''<br />
<br />
The forum link is a summary page and contains links to the latest versions of the tools such as when a new<br />
release has just happened or is being tested before it is provided via the '''[http://www.shoutcast.com/broadcast-tools/ Broadcast Tool Downloads]''' page.<br />
<br />
<br />
==Core Documentation==<br />
<br />
Here you can find the core documentation relating to all of the provided SHOUTcast 2.x system tools which is the Server 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.<br />
<br />
::'''[[SHOUTcast_DNAS_Server_2|SHOUTcast DNAS Server 2 (sc_serv)]]'''<br />
<br />
::'''[[Source_DSP_Plug-in|SHOUTcast Source DSP Plug-in (dsp_sc)]]'''<br />
<br />
<br />
==Supporting Documentation==<br />
<br />
Here you can find copies of additional documentation which is referenced by the core documentation.<br />
<br />
::'''[[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]]'''<br />
<br />
::'''[[SHOUTcast_DNAS_Server_2_XML_Reponses|SHOUTcast DNAS Server 2 XML Reponses]]'''<br />
<br />
::'''[[Source_DSP_Plug-in_Configuration_Examples|SHOUTcast Source DSP Plug-in Configuration Examples]]'''<br />
<br />
::'''[[SHOUTcast_YP_Nak_Errors|SHOUTcast YP Nak Error Information]]'''</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_YP_Nak_ErrorsSHOUTcast YP Nak Errors2014-10-28T23:01:54Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
=Overview=<br />
<br />
The aim of this page is to provide you with some information about common YP system errors and hints on how to resolve some of them when trying to get your stream(s) listed in the [http://www.shoutcast.com SHOUTcast Radio Directory].<br />
<br />
<br />
==Cannot see your station/computer from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.==<br />
<br />
This is one of the most common errors and if you are seeing this error in the DNAS server's logs, then it means your stream(s) will not be listed in the SHOUTcast Radio Directory. The most common cause of this error is due to your currently running firewall and/or router.<br />
<br />
<br />
The error should appear as '''Cannot see your station/computer (IP: xxx.xxx.xxx.xxx:8000) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache''' where it shows the external IP the YP system has used since that should be what external clients from your network will try to access. A simple test is to copy and paste xxx.xxx.xxx.xxx:8000 into your browser which should then show a DNAS server summary page.<br />
When using a v2 DNAS server, you will also see a 480 error code to identify this error<br />
<br />
<br />
The first thing to do is to ensure you have forwarded the correct ports from the machine the DNAS server is run on to the Internet. Usually this involves forwarding port '''8000''' and (if using external legacy v1 sources) port '''8001'''. If you have changed '''[[SHOUTcast_DNAS_Server_2#Networking|portbase]]''' from it's default value then you will need to use what is specified (and portbase+1 if you need external legacy v1 support). You should be able to find information for your router on how to do this from http://www.portforward.com/<br />
You only need to do the port forwarding on the TCP protocol<br />
<br />
<br />
Once you have changed the port forwarding, you will need to restart the DNAS server (if already running) and usually the YP system should then be able to see your DNAS server. If the issue still happens, you will then need to look at any software firewalls, consulting any documentation relating to the software you are using and for the operating system you are using. You can find information about some software used by other broadcasters having the same issue from '''[http://forums.winamp.com/showpost.php?p=486196&postcount=2 here]'''.<br />
<br />
<br />
Another cause of this issue is when your DNAS server is running but not on the same network adaptor or external IP address as the YP system is trying to test a connection on e.g. when there are multiple external IP addresses or running in a virtualised system. The simplest way to try to resolve this is explicitly to specify the external IP for the DNAS server to bind itself to via '''[[SHOUTcast_DNAS_Server_2#Client_Behaviour|destip]]'''.<br />
<br />
<br />
<br />
If none of the above resolves the issue for you, then please have a look at the following other references which have covered this issue over the years '''[http://forums.winamp.com/showthread.php?threadid=70402 here]'''.<br />
<br />
<br />
==Invalid Authorization Hash==<br />
<br />
This error only relates to v2 DNAS servers and is identified with the 470 error code. This will happen if you have not obtained an authorization hash for your stream as detailed '''[[SHOUTcast_Authhash_Management|here]]''' or if you have an invalid authorization hash e.g. it has been removed / revoked.<br />
<br />
<br />
The detailed error message provided by the YP system to the DNAS will show either '''Authhash not specified''' or '''Authhash not found''' which should make it easier to identify the cause of the problem with your configuration.<br />
<br />
<br />
To start resolving the issue, you can check to see if there is a valid authorization hash specified against the stream on the machine running the DNAS by looking at the Administrator Summary page e.g. via <nowiki>http://127.0.0.1:8000/admin.cgi</nowiki> which will show any connected streams with missing authorization hash(s) or needing to have one created for it. If that is the case then follow the instructions shown or for how to create an authorization hash.<br />
<br />
<br />
Otherwise, you can also try using the Administrator Stream Configurations report e.g. via <nowiki>http://127.0.0.1:8000/admin.cgi?sid=1&mode=viewxml&page=6</nowiki> to check the details the DNAS server currently knows about all stream configurations, looking at the '''streamauthhash''' entry for the stream(s) having issues.<br />
<br />
<br />
If that still does not resolve this error, then please see '''[[SHOUTcast_Authhash_Management#Management_Issues|here]]''' for how to obtain more assistance (paying attention to the information which is required).<br />
<br />
<br />
<br />
==Generic Error==<br />
<br />
If you are seeing this error in the DNAS server's logs, the usual cause is related to an internal error / handling issue within the YP system itself. In most cases this is not something due to how you have setup your DNAS server and can be due to a number of internal YP system issues.<br />
<br />
<br />
Usually this will go away or may intermittently occur. However if it does persist then you should post in the [http://forums.winamp.com/forumdisplay.php?f=86 SHOUTcast Technical Support] forum, providing as much information about your setup, logs and other information which is relevant to your setup.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Calendar_Event_XML_File_SpecificationSHOUTcast Calendar Event XML File Specification2014-10-28T23:01:38Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The purpose of the calendar.xml file is to allow for the scheduling of events in your sc_trans instance such as for specifying a time when a DJ is able to join or when a specific playlist will be used.<br />
<br />
An important thing to note is that sc_trans will only read the settings from your calendar xml file when it is loaded. So if you do change anything in the file externally whilst sc_trans is running then you will need to restart your sc_trans instance for the new values to be read in.<br />
<br />
If you use the AJAX api (see [[SHOUTcast_Transcoder_AJAX_api_Specification|sc_trans_ajax_api.txt]] and [[SHOUTcast_Transcoder_AJAX_api_Specification#AddEvent|Sections 2.14]] to [[SHOUTcast_Transcoder_AJAX_api_Specification#AbortEvent|2.16]]) then you can make changes to the calendar file whilst sc_trans is running but you will need to make sure to have ''''calendarrewrite=1'''' in your sc_trans configuration file so that any live changes made will be saved back into your calender file.<br />
<br />
<br />
==File Layout==<br />
<br />
The following xml file shows the general layout of a calendar.xml file and the options which are available for it for a single entry. The file does allow you to specify more than one event by adding in more <event>...</event> blocks.<br />
<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<eventlist><br />
<event type="playlist|dj|relay"><br />
<!------ control when, how long, how many times the event applies --------><br />
<calendar startdate="yyyy/mm/dd" enddate="yyyy/mm/dd" starttime="hh:mm:ss" duration="hh:mm:ss" repeat="#"/><br />
<br />
<!---------- playlist type ----------><br />
<playlist loopatend="1|0" shuffle="1|0|inherit" priority="#"><br />
playlistname<br />
</playlist><br />
<!-------------------------------------><br />
<br />
<!------------- dj type -------------><br />
<dj archive="1|0|inherit" priority="#">djname</dj><br />
<!-------------------------------------><br />
<br />
<!----------- relay type ------------><br />
<relay url="xxx" priority="#"/><br />
<!-------------------------------------><br />
<br />
</event><br />
</eventlist><br />
<br />
<br />
===Calendar Tag===<br />
----<br />
<br />
The <calendar> tag contains date information about scheduled events and it can contain the following attributes allowing for finer control over the event:<br />
<br />
startdate (specified as yyyy/mm/dd)<br />
enddate (specified as yyyy/mm/dd)<br />
starttime (specified as hh:mm:ss - 24 hour format)<br />
duration (specified as hh:mm:ss - 24 hour format)<br />
timeoffset (specified as hh:mm:ss - 24 hour format)<br />
repeat (numeric value)<br />
<br />
The ''''startdate'''' and ''''enddate'''' attributes indicate the date range the event is valid for otherwise the event will be ignored. Either value can be left out and if so then the event will be unbounded in that direction i.e. specifying no ''''startdate'''' is the way to indicate the event takes effect when sc_trans starts.<br />
<br />
The ''''starttime'''' attribute works in a similar manner to the date ones for the event but are used when the associated ''''startdate'''' is met. So if no ''''starttime'''' is indicated then the event starts immediately on ''''startdate''''. So as you can see this could be left out along with ''''startdate'''' to make events start always when sc_trans is started.<br />
<br />
The ''''duration'''' attribute is the length of the scheduled event and if this is not specified then the event will end when ''''enddate'''' (if specified) is reached.<br />
<br />
The ''''repeat'''' attribute is a numeric code for an event which gives control over how an event will be repeated. The repeat attribute can be one of the following as listed below or a combination to create more complicated repeat patterns e.g. '62' will make an event repeat every day of the week (i.e. 2 + 4 + 8 + 16 + 32)<br />
<br />
1 - Every Sunday<br />
2 - Every Monday<br />
4 - Every Tuesday<br />
8 - Every Wednesday<br />
16 - Every Thursday<br />
32 - Every Friday<br />
64 - Every Saturday<br />
128 - Time periodic<br />
<br />
<br />
====Time Periodic Events====<br />
----<br />
<br />
Time periodic events are those which occur at regular intervals and are defined by the ''''starttime'''', ''''timeoffset'''' and ''''repeat'''' attributes allowing for control over the time interval between the event and the next instance of the event.<br />
<br />
The ''''starttime'''' attribute is used to indicate the interval between this type of event and the next time it will occur. So with a number of these events you can have a jingle play at a specific time during the day at a consistent time.<br />
<br />
The ''''timeoffset'''' atribute is used to indicate an offset from midnight at which the periodic event will be applied relative to the ''''starttime'''' value. This will allow you to specify a specific time during the interval so if you wanted to have an event which is activated every hour but on the half hour you could do:<br />
timeoffset="00:30:00"<br />
starttime="01:00:00"<br />
<br />
If no other repeat field values are specified i.e. repeat isn't 128 then the event will be valid for every day of the week. If other values are specified then the event will be restricted to those days specified<br />
e.g.<br />
repeat=190 repeats the event only during weekdays<br />
<br />
''''Important Note:'''' If you use this on a playlist event then the event will be activated at the specified time period after the last event successfully occurred but the required file(s) will not be played until the currently playing file has completed playing as playlist events add to the main playback queue and do not act as an instant event as the relay and DJ events do.<br />
<br />
<br />
====Event Priorities====<br />
----<br />
<br />
The purpose of event priorities is to allow finer control when multiple events can occur at the same time e.g. multiple DJ's trying to connect at the same time. If not specified, each event is assigned a default priority of 1 and the first matching event will be used. If specified, the event with the highest priority is used when events occur or overlap.<br />
<br />
For example we have the following configuration (assume the events are always allowed):<br />
<br />
DJ1 has a priority of 1<br />
DJ2 has a priority of 2<br />
<br />
DJ1 only connects then it will be allowed to connect.<br />
DJ2 only connects then it will be allowed to connect.<br />
DJ2 connects when DJ1 is already connected, DJ1 is dropped and DJ2 can connect.<br />
DJ1 connects when DJ2 is already connected, DJ2 stays connected and DJ1 is blocked.<br />
<br />
In all cases, if an event is valid and can be activated then it will be used instead of the specified main playlist, which has a priority of zero to keep it below all events.<br />
<br />
<br />
==Supported Events==<br />
<br />
As shown in the previous section, there are 3 types of events supported by the file format which are:<br />
<br />
DJ<br />
Playlist<br />
Relay<br />
<br />
The following sections will detail the options available with each event type.<br />
<br />
<br />
===DJ Events===<br />
----<br />
<br />
The purpose of a DJ event is to control the access a DJ has to the instance of sc_trans for the duration of the specified event. This makes it simple to setup scheduling of access of different DJs at different times of the day or week.<br />
<br />
This is enabled in combination with the settings in the sc_trans configuration file for controlling DJ access. So for this to work you will also need to make sure you enable ''''djport / djport2'''' (depending on you using SHOUTcast 1 or SHOUTcast 2 features) and to set any passwords and names in the sc_trans config file to match the event. See [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.0.3]] for more information setting up DJ support.<br />
<br />
The parameters supported for this event type are:<br />
<br />
archive : Specify if the DJ show will be archived (sc_trans does this normally)<br />
1 - Yes<br />
0 - No<br />
inherit - Use value set for ''''djcapture'''' in the configuration file.<br />
<br />
priority : Specify the priority of the DJ when a DJ event overlaps with that of another event.<br />
<br />
e.g. This would enable archiving of the show made by the DJ identified as 'Bob'<br />
<br />
<dj archive="1" priority="1">Bob</dj><br />
<br />
<br />
===Playlist Events===<br />
----<br />
<br />
This allows you to schedule playlists to be used at the specified time or date thus making it easier to change to a weekend or an evening playlist if needed. The playlists are those defined by the playlistfilename and playlistfilepath entries in you sc_trans configuration file which allows for multiple playlists to be accessed by this event type.<br />
<br />
The event uses the symbolic name of the playlist (set with playlistfilename_X i.e. the name you've given to the playlist, not the actual playlist filename). So if you had 3 playlists and wanted to use the second one then you would set things up as follows (playlistfilepath also needs to be set but is not shown):<br />
<br />
In the sc_trans configuration file:<br />
playlistfilename_1=morning<br />
playlistfilename_2=daytime<br />
playlistfilename_3=evening<br />
<br />
In the calendar xml file:<br />
<playlist loopatend="1" shuffle="inherit" priority="1">daytime</playlist><br />
<br />
<br />
The parameters supported for this event type are:<br />
<br />
loopatend : Specify if the playlist will restart if the end of the playlist is reached before the duration of the event is completely fulfilled.<br />
1 - Yes<br />
0 - No (Default)<br />
<br />
shuffle : Specify if the playlist should be shuffled when being played.<br />
1 - Yes<br />
0 - No<br />
inherit - Use value set for ''''shuffle'''' in the configuration file.<br />
<br />
priority : Specify the priority of the playlist when a playlist event overlaps with that of another event.<br />
<br />
e.g. This would specify the playlist known as 'evening' to loop if needed and to not be shuffled when played<br />
<br />
<playlist loopatend="1" shuffle="0" priority="1">evening</playlist><br />
<br />
''''Important Note:'''' Playlist events are queued up instead of being activated immediately so if you have a 'jingle' playlist then this would not be played until the currently playing file has completed playing and has not been pushed down the queue by a higher priority playlist event. This is something you need to take into account if you want to have a jingle play every 10 minutes but none of the files have a roughly standard duration.<br />
<br />
<br />
===Relay Events===<br />
----<br />
<br />
This allows you to make use of the relaying support within sc_trans and so when used in the event system will allow you to control when a relay is allowed to connect to you sc_trans instance (much like the DJ support mentioned earlier).<br />
<br />
The parameters supported for this event type are:<br />
<br />
url : Specify the url of the source to be relayed.<br />
<br />
priority : Specify the priority of the source when a relay event overlaps with that of another event.<br />
<br />
e.g. This would enable the relaying of the stream on 'my_site' on port 9000<br />
<br />
<nowiki><relay url="http://my_site:9000" priority="1"/></nowiki><br />
<br />
Note: It may be necessary to append ''''/;'''' onto the end of the url as in some cases the wrong mime type will be returned from the server and so causes the relay url fail to be recognised by sc_trans. This depends on the server.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Transcoder_AJAX_api_SpecificationSHOUTcast Transcoder AJAX api Specification2014-10-28T23:01:21Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
All calls to the provided AJAX api are made as POST requests via the 'api' page i.e. <nowiki>http://localhost:4444/api</nowiki> and the parameters are passed in to it as POST parameters (application/x-www-form-urlencoded; charset=UTF-8). If 'charset' is not specified then UTF-8 is assumed and anything else will generate an error.<br />
<br />
All requests require at least two parameters:<br />
<br />
'op' - this indicates the operation to be performed.<br />
'seq' - this is a sequence number used as an identifier.<br />
<br />
The 'seq' parameter is merely an identifier that is returned in the resulting xml as the 'seq' attribute in the <response> tag. This passed value can then be used to align requests and results in an asynchronous application. It is recommended that the value you passed in to the 'seq' parameter be a strictly increasing integer.<br />
<br />
<br />
===Responses===<br />
----<br />
<br />
Responses are returned as xml and all will have the following basic format:<br />
<br />
1 <?xml version="1.0" encoding="UTF-8" ?><br />
2 <response seq="#" badsyntax="1|0"><br />
3 <error>..</error><br />
4 <warning>...</warning><br />
5 <restart/><br />
6 <data><br />
7 </data><br />
8 </response><br />
<br />
'''Line by line explanation:'''<br />
<br />
2. <response> is always the outer most tag. This will always have a 'seq' attribute which will match with the value of the 'seq' parameter passed in for the request. If the 'badsyntax' attribute exists and is set to '1' then the request was rejected because it was badly formed. The only subtag will then be <error> which will contain the error message.<br />
<br />
3. The <error> tag will only appear if an error occurred executing the request. This can be from a completely rejected request due to a bad syntax in which case the 'badsyntax' attribute is set in the <response> tag as previously mentioned or due to a request that failed due to some other problem in which case the other subfields may still exist.<br />
<br />
4. The <warning> tag will appear if there is a warning that must be conveyed to the user.<br />
<br />
5. If the value inside the <restart> tag is one then a restart of sc_trans is required to complete the requested action (see [[#Restart|section 2.25]] for making sc_trans restart itself).<br />
<br />
6. Any returned data will be found inside the <data> tag.<br />
<br />
For simple commands that do not need to return data or do not have any errors or warnings then you will just get the <response> tag<br />
e.g.<br />
<response seq="53">...</response><br />
<br />
<br />
===Calendar Tag===<br />
----<br />
<br />
The <calendar> tag contains date information about scheduled events and it can contain the following attributes allowing for finer control over the event:<br />
<br />
startdate (specified as yyyy/mm/dd)<br />
enddate (specified as yyyy/mm/dd)<br />
starttime (specified as hh:mm:ss - 24 hour format)<br />
duration (specified as hh:mm:ss - 24 hour format)<br />
timeoffset (specified as hh:mm:ss - 24 hour format)<br />
repeat (numeric value)<br />
<br />
<br />
The ''''startdate'''' and ''''enddate'''' attributes indicate the date range the event is valid for otherwise the event will be ignored. Either value can be left out and if so then the event will be unbounded in that direction i.e. specifying no ''''startdate'''' is the way to indicate the event takes effect when sc_trans starts.<br />
<br />
The ''''starttime'''' and ''''endtime'''' attributes work in a similar manner to the date ones for the event but are used when the associated ''''startdate'''' is met. So if no ''''starttime'''' is indicated then the event starts immediately on ''''startdate''''. So as you can see this could be left out along with ''''startdate'''' to make events start always when sc_trans is started.<br />
<br />
The ''''duration'''' attribute is the length of the scheduled event and if this is not specified then the event will end when ''''enddate'''' (if specified) is reached.<br />
<br />
The ''''repeat'''' attribute is a numeric code for an event which gives control over how an event will be repeated. The repeat attribute can be one of the following as listed below or a combination to create more complicated repeat patterns e.g. '62' will make an event repeat every day of the week (i.e. 2 + 4 + 8 + 16 + 32)<br />
<br />
1 - Every Sunday<br />
2 - Every Monday<br />
4 - Every Tuesday<br />
8 - Every Wednesday<br />
16 - Every Thursday<br />
32 - Every Friday<br />
64 - Every Saturday<br />
128 - Time periodic<br />
<br />
<br />
====Time Periodic Events====<br />
----<br />
<br />
Time periodic events are those which occur at regular intervals and are defined by the ''''starttime'''', ''''timeoffset'''' and ''''repeat'''' attributes allowing for control over the time interval between the event and the next instance of the event.<br />
<br />
The ''''starttime'''' attribute is used to indicate the interval between this type of event and the next time it will occur. So with a number of these events you can have a jingle play at a specific time during the day at a consistent time.<br />
<br />
The ''''timeoffset'''' atribute is used to indicate an offset from midnight at which the periodic event will be applied relative to the ''''starttime'''' value. This will allow you to specify a specific time during the interval so if you wanted to have an event which is activated every hour but on the half hour you could do:<br />
<br />
timeoffset="00:30:00"<br />
starttime="01:00:00"<br />
<br />
If no other repeat field values are specified i.e. repeat isn't 128 then the event will be valid for every day of the week. If other values are specified then the event will be restricted to those days specified<br />
e.g.<br />
repeat=190 repeats the event only during weekdays<br />
<br />
'''Important Note:''' If you use this on a playlist event then the event will be activated at the specified time period after the last event successfully occurred but the required file(s) will not be played until the currently playing file has completed playing as playlist events add to the main playback queue and do not act as an instant event as the capture and DJ events do.<br />
<br />
<br />
==Operations / Commands==<br />
<br />
The following sections detail the operations which are supported by the api and will show you what results they will return (where applicable).<br />
<br />
===Test===<br />
----<br />
<br />
The test operation does nothing of importance other than confirming the proper operation of the client and server link. This will return all of the parameters that were passed in to it allowing you to check all was correct if applicable.<br />
<br />
Parameters:<br />
op = "test"<br />
seq = 'any value'<br />
<br />
Result:<br />
<param><br />
<key>....</key><br />
<value>....</value><br />
</param><br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”text”<br />
op="45"<br />
foo=”bar”<br />
go=”away”<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<op>test</op><br />
<seq>45</seq><br />
<foo>bar</foo><br />
<go>away</go><br />
</data><br />
</response><br />
<br />
<br />
===GetStatus===<br />
----<br />
<br />
This will return the running status information about the current sc_trans instance allowing for a detailed look at what sc_trans is setup to be doing.<br />
<br />
Parameters:<br />
op = "getstatus"<br />
seq = 'any value'<br />
<br />
Results:<br />
1 <status><br />
2 <activesource source="playlist|capture|dj|relay"><br />
3 <currenttrack/><br />
4 <nexttrack/><br />
5 <name/><br />
6 <file/><br />
7 <ip/><br />
8 <port/><br />
9 <url/><br />
10 <sourcetype/><br />
11 <bitrate/><br />
12 <device/><br />
13 <input/><br />
14 <samplerate/><br />
15 <channels/><br />
16 </activesource><br />
17 <endpointlist><br />
18 <endpoint><br />
19 <name/><br />
20 <bytessent/><br />
21 <status/><br />
22 </endpoint><br />
23 <endpoint><br />
24 <name/><br />
25 <bytessent/><br />
26 <status/><br />
27 </endpoint><br />
28. <!-- etc ---><br />
29. </endpointlist><br />
30. </status><br />
<br />
'''Line by line explanation:'''<br />
<br />
2. The type of source currently feeding the encoders is indicated by the source attribute which can be one of: 'playlist' or 'capture' or 'dj' or 'relay'.<br />
<br />
3. If the source attribute of the <activesource> tag is 'playlist' then the text inside this tag will be the currently playing track.<br />
<br />
4. If the source attribute of the <activesource> tag is 'playlist' then the text inside this tag is the next track to be played.<br />
<br />
5. The name of either the playlist (logical) or DJ depending on the source attribute in the <activesource> tag.<br />
<br />
6. Contains the filename of the playlist.<br />
<br />
7. Contains an IP address if this is a DJ connection.<br />
<br />
8. Contains the port the DJ is connected on if this is a DJ connection.<br />
<br />
9. Contains the url of a relayed source.<br />
<br />
10. The mime type of the source if it is a DJ or relay source connected.<br />
<br />
11. The bitrate of the stream if this is a relay source.<br />
<br />
12. The capture device being used if the source is capture.<br />
<br />
13. Capture input if source is capture.<br />
<br />
14. The sample rate if source is capture.<br />
<br />
15. The number of channels if the source is of type 'capture'.<br />
<br />
18. There can be zero or more of these <endpoint> tags which will provide some runtime information about the endpoint(s) currently known by sc_trans.<br />
<br />
20. The number of bytes transmitted since the endpoint was started.<br />
<br />
21. The status message for the current endpoint.<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”getstatus”<br />
seq="45"<br />
<br />
Resulting XML:<br />
1 <?xml version="1.0" encoding="UTF-8" ?><br />
2 <response seq="45"><br />
3 <data><br />
4 <status><br />
5 <activesource source="dj"><br />
6 <name>Neil Radisch</name><br />
7 <ip>10.10.70.100</ip><br />
8 <port>1234</port><br />
9 <sourcetype>aacp</sourcetype><br />
10 </activesource><br />
11 <endpointlist><br />
12 <endpoint><br />
13 <name>high bitrate mp3</name><br />
14 <bytessent>123456789</bytessent><br />
15 <status>Online</status><br />
16 </endpoint><br />
17 </endpointlist><br />
18 </status><br />
19 </data><br />
20 </response><br />
<br />
<br />
===GetOptions===<br />
----<br />
<br />
This will return the sc_trans configuration options with each option being represented by its own subtag in the returned output. The following list is all of the options currently supported through GetOptions and SetOptions operations (see [[#SetOptions|section 2.4]] for 'SetOptions' usage). More details about these settings can be found in [[SHOUTcast_DNAS_Transcoder_2|sc_trans.txt]] for each of the entries following:<br />
<br />
::{| class="wikitable" cellpadding="6" cellspacing="3"<br />
|-<br />
| serverintrofile || serverbackupfile || log || screenlog || djdebug || flashpolicyserverdebug<br />
|-<br />
| unlockkeyname || unlockkeycode || capturedebug || shuffledebug || flashpolicyfile || flashpolicyserverport<br />
|-<br />
| shoutcastdebug || uvoxdebug || gaindebug || playlistdebug || mp3encdebug || fileconverterdebug<br />
|-<br />
| mp3decdebug || resamplerdebug || rgcalcdebug || apidebug || calendardebug || sourcerelaydebug<br />
|-<br />
| logfile || streamtitle || streamurl || public || genre || sourceandendpointmanagerdebug<br />
|-<br />
| aim || irc || icq || shuffle || xfade || xfadethreshold<br />
|-<br />
| djport || djport2 || playlists || archive || xfade || autodumpsourcetime<br />
|-<br />
| djcipher || djbroadcasts || djfilepattern || adminport || adminpassword || adminuser<br />
|-<br />
| capturedevice || captureinput || capturesamplerate || capturechannels || usemetadata || metadatapattern<br />
|-<br />
| applyreplaygain || defaultreplaygain || djreplaygain || djcapture || capturereplaygain || calculatereplaygain<br />
|-<br />
| replaygaintmpdir || replaygaindontwrite || enhancereplaygain || configrewrite || replaygainrunahead || uvoxmetadatafudgefactor<br />
|-<br />
| vuimagedirectory || vuimagesuffix || vuimagemimetype || calendarfile || calendarrewrite || shoutcastmetadatafudgefactor<br />
|-<br />
| nextlookahead<br />
|}<br />
<br />
<br />
Parameters:<br />
op = "getoptions"<br />
seq = 'any value'<br />
<br />
Results:<br />
<data><br />
<options><br />
<logfile>/home/nradisch/sc_trans.log</logfile><br />
<streamtitle>...</streamtitle><br />
<public>...</public><br />
<usemetadata>...</usemetadata><br />
<!-- etc ---><br />
</options><br />
</data><br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”getoptions”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<options><br />
<logfile>/home/nradisch/sc_trans.log</logfile><br />
<streamtitle>neil's stream</streamtitle><br />
<public>1</public><br />
<usemetadata>1</usemetadata><br />
<!-- etc ---><br />
</options><br />
</data><br />
</response><br />
<br />
<br />
===SetOptions===<br />
----<br />
<br />
This allows for the setting of any of the sc_trans configuration options as listed in [[#GetOptions|section 2.3]] or see [[SHOUTcast_DNAS_Transcoder_2|sc_trans.txt]] for more detailed information. Each option is it's own input parameter when using this operation.<br />
<br />
Parameters:<br />
op = "setoptions"<br />
seq = 'any value'<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”setoptions”<br />
seq="45"<br />
logfile="/home/nradisch/newlog.log"<br />
streamtitle="neil's crazy stream"<br />
public=0<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===GetEndpoints===<br />
----<br />
<br />
This will return information about the encoder / broadcaster endpoints.<br />
<br />
Parameters:<br />
<br />
op = "getendpoints"<br />
seq = 'any value'<br />
name = logical name of a particular endpoint (optional)<br />
<br />
Results:<br />
<br />
Each combination of encoder and broadcaster target will appear inside an <endpoint> tag. The order in which the endpoint tags appear is significant since it implies the index used to access and modify specific endpoints.<br />
<br />
1. <endpointlist><br />
2. <endpoint><br />
3. <name/><br />
4. <encoder type="aacp|mp3"><br />
5. <bitrate/><br />
6. <samplerate/><br />
7. <channels/><br />
8. <mp3><br />
9. <quality/><br />
10. <mode/><br />
11. </mp3><br />
12. </encoder><br />
13. <network protocol="#"><br />
14. <ip/><br />
15. <port/><br />
16. <uvox><br />
17. <streamid/><br />
18. <userid/><br />
19. <auth/><br />
20. <radiometadata/><br />
21. <newmetadata/><br />
22. </uvox><br />
23. <shoutcast><br />
24. <password/><br />
25. </shoutcast><br />
26. </network><br />
27. </endpoint><br />
28. <endpoint>...</endpoint><br />
29. </endpointlist><br />
<br />
'''Line by line explanation:'''<br />
<br />
3. The name of the endpoint.<br />
<br />
4. The type attribute shows the type of encoder which can be 'mp3' or 'aacp'.<br />
<br />
5. The text of tag is the bitrate value in bps.<br />
<br />
6. The sample rate for encoder.<br />
<br />
7. The number of channels for encoder.<br />
<br />
8. This subtag only exists if the <encoder> attribute type is 'mp3'.<br />
<br />
9. The quality value for mp3 encoder (see 'mp3quality in sc_trans.txt).<br />
<br />
10. The mode value for mp3 encoder (see 'mp3mode' in sc_trans.txt).<br />
<br />
13. The protocol attribute indicates the type of network connection. See [[SHOUTcast_DNAS_Transcoder_2#Network_Options|'outprotocol' in sc_trans.txt]] for possible values.<br />
<br />
14. Contains the IP address for connection (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|'serverip' in sc_trans.txt]]).<br />
<br />
15. Contains the port used to connect on (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|'serverport' in sc_trans.txt]]).<br />
<br />
16. This subtag only exists if the <network> protocol attribute indicates we have a uvox style connection.<br />
<br />
17. Contains the stream id for a uvox connection (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|'uvoxstreamid' in sc_trans.txt]]).<br />
<br />
18. Contains the user ID for a uvox connection (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|'uvoxuserid' in sc_trans.txt]]).<br />
<br />
19. Authentication token for uvox connections (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|'uvoxauth' in sc_trans.txt]]).<br />
<br />
20. Flag indicating if we should send radio style (3901) metadata (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|'uvoxradiometadata' in sc_trans.txt]]).<br />
<br />
21. Flag indicating that we should send net style (3902) metadata (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|'uvoxnewmetadata' in sc_trans.txt]]).<br />
<br />
23. This subtag only exists if the <network> protocol attribute indicates a SHOUTcast 1 connection.<br />
<br />
24. Contains the password for SHOUTcast connection (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|'password' in sc_trans.txt]]).<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”getendpoints”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<endpointlist><br />
<endpoint><br />
<name>high bitrate mp3</name><br />
<encoder type="mp3"><br />
<bitrate>128000</bitrate><br />
<samplerate>44100</samplerate><br />
<channels>2</channels><br />
<mp3><br />
<quality>0</quality><br />
<mode>0</mode><br />
</mp3><br />
</encoder><br />
<network protocol="1"><br />
<ip>neil.radio.com</ip><br />
<port>8989</port><br />
<shoutcast><br />
<password>foobar</password><br />
</shoutcast><br />
</network><br />
</endpoint><br />
<endpoint><br />
<name>aacp endpoint</name><br />
<encoder type="aacp"><br />
<bitrate>96000</bitrate><br />
<samplerate>48000</samplerate><br />
<channels>2</channels><br />
</encoder><br />
<network protocol="2"><br />
<ip>neil.radio.com</ip><br />
<port>7979</port><br />
<uvox><br />
<streamid>1</streamid><br />
<userid>neil</userid><br />
<auth>foobar</auth><br />
<radiometadata>1</radiometadata><br />
<newmetadata>1</newmetadata><br />
</uvox><br />
</network><br />
</endpoint><br />
</endpointslist><br />
</data><br />
</response><br />
<br />
<br />
===SetEndpoint===<br />
----<br />
<br />
This is used to configure (or create) an encoder and network endpoint.<br />
<br />
Parameters:<br />
op = "setendpoint"<br />
seq = 'any value'<br />
name = name of encoder. Created if it does not exist<br />
encoder = type of encoder (mp3 or aacp)<br />
bitrate = encoder bitrate<br />
samplerate = encoder sample rate<br />
channels = encoder channels<br />
quality = quality value for mp3<br />
mode = mode for mp3<br />
protocol = numeric protocol value for network connection<br />
ip = address for network connection<br />
port = port for network connection<br />
password = password for SHOUTcast network connection<br />
streamid = uvox stream id<br />
userid = uvox user id<br />
auth = uvox authorization<br />
radiometadata = radio metadata flag<br />
newmetadata = new metadata flag<br />
<br />
Result:<br />
<br />
The returned xml will contain information about the endpoint (see example).<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”setendpoint”<br />
seq="45"<br />
name="my mp3 encoder"<br />
encoder=mp3<br />
bitrate=96000<br />
samplerate=44100<br />
channels=2<br />
quality=0<br />
mode=0<br />
protocol=1<br />
ip="neil.radisch.com"<br />
port=7979<br />
password="foobar"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<endpoint><br />
<name>my mp3 encoder</name><br />
<encoder type="mp3"><br />
<bitrate>96000</bitrate><br />
<samplerate>44100</samplerate><br />
<channels>2</channels><br />
<mp3><br />
<quality>0</quality><br />
<mode>0</mode><br />
</mp3><br />
</encoder><br />
<network protocol="1"><br />
<ip>neil.radisch.com</ip><br />
<port>7979</port><br />
<password>foobar</password><br />
<shoutcast><br />
<password>foobar</ password ><br />
</shoutcast><br />
</network><br />
</endpoint><br />
</data><br />
</response><br />
<br />
<br />
===DeleteEndpoint===<br />
----<br />
<br />
This will allow you to delete an existing endpoint from those sc_trans knows.<br />
<br />
Parameters:<br />
<br />
op = "deleteendpoint"<br />
seq = 'any value'<br />
name = name of the endpoint<br />
<br />
Result:<br />
<br />
The returned xml contains information about the deleted endpoint (see example).<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”deleteendpoint”<br />
seq="45"<br />
name="my mp3 encoder"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<endpoint><br />
<name>my mp3 encoder</name><br />
<encoder type="mp3"><br />
<bitrate>96000</bitrate><br />
<samplerate>44100</samplerate><br />
<channels>2</channels><br />
<mp3><br />
<quality>0</quality><br />
<mode>0</mode><br />
</mp3><br />
</encoder><br />
<network protocol="1"><br />
<ip>neil.radisch.com</ip><br />
<port>7979</port><br />
<password>foobar</password><br />
<shoutcast><br />
<metadatafudgefactor>0</metadatafudgefactor><br />
</shoutcast><br />
</network><br />
</endpoint><br />
</data><br />
</response><br />
<br />
<br />
===LogData===<br />
----<br />
<br />
This operation returns data from the sc_trans logs for display / processing.<br />
<br />
Parameters:<br />
<br />
op = "logdata"<br />
seq = 'any value'<br />
<br />
Results:<br />
<br />
<data><br />
<logdata><br />
<entry date="yyyy-mm-dd hh:mm:ss" type="W|I|D|E"><br />
message text for the log entry<br />
</entry><br />
</logdata><br />
</data><br />
<br />
Each logdata entry has a date attribute which has a timestamp for the entry. In addition each entry has a type attribute which is one of the following values:<br />
<br />
W - Warning Message<br />
I - Informational Message<br />
D - Debug Message<br />
E - Error Message<br />
<br />
The text of the message is then stored inside of the tag. Note that sc_trans will only hold up to 100 backlogged messages. If there are more than that and these have been queued up since the last logdata request then the first message will indicate a gap in the data.<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
<br />
op=”logdata”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<logdata><br />
<entry date="2008-08-30 11:00:39" type="I"><br />
[MAIN] Broadcast Receiver thread starting<br />
</entry><br />
<entry date="2008-08-30 11:00:39" type="I"><br />
[source] listening for connection on port 10000<br />
</entry><br />
<entry date="2008-08-30 11:00:39" type="D"><br />
[playlistMgr] priority counter is 0<br />
</entry><br />
</logdata><br />
</data><br />
</response><br />
<br />
<br />
===AddPlaylist===<br />
----<br />
<br />
This allows for adding a playlist to those being tracked by sc_trans. They can be added either inline or as a reference to an actual file that is located on a drive which sc_trans can access. Adding additional playlists does not perform any specific scheduling actions. To be able to that you must add or update a scheduled event or set it to the main playlist inorder for sc_trans to use it.<br />
<br />
Parameters:<br />
op = "addplaylist"<br />
seq = 'any value'<br />
name = name for playlist.<br />
format = "list|file"<br />
filename = name of referenced file<br />
calcrg = 1|0<br />
entry### = inline entries<br />
<br />
For a file reference the 'format' parameter needs to be set to 'file' and the 'filename' parameter is set to be the filepath of the file. For an inline submit then the 'format' parameter is set to 'list' and you then need to set some entry parameters to define it in the form of 'entry###'. Finally if the 'calcrg' parameter is set to one then replaygain is calculated against the playlist.<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”addplaylist”<br />
seq="45"<br />
format="list"<br />
name="foolist"<br />
entry0="/home/nradisch/music/groovy.mp3"<br />
entry1="/home/nradisch/music/rockon.mp3"<br />
entry2="/home/nradisch/music/rockoff.mp3"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===ListPlaylists===<br />
----<br />
<br />
This operation will return a list of the playlists registered with sc_trans.<br />
<br />
Parameters:<br />
op = "listplaylists"<br />
seq = 'any value'<br />
<br />
Result:<br />
<currentplaylist/><br />
<masterplaylist/><br />
<playlists><br />
<playlist><br />
<name/><br />
<path/><br />
<playlist/><br />
<!-- etc ---><br />
</playlists><br />
<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”listplaylists”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<currentplaylist>friday night special</currentplaylist><br />
<masterplaylist>main list</masterplaylist><br />
<playlists><br />
<playlist><br />
<name>main list</name><br />
<path>/foo/bar/mainlist.lst</path><br />
</playlist><br />
<playlist><br />
<name>friday night special</name><br />
<path>/neil/radisch/fns.pls</path><br />
</playlist><br />
</playlists><br />
</data><br />
</response><br />
<br />
<br />
===PlaylistData===<br />
----<br />
<br />
This operation allows you to get entries from the specified playlist.<br />
<br />
Parameters:<br />
op = "playlistdata"<br />
seq = 'any value'<br />
name = name of the playlist<br />
max = max # of entries to return (optional)<br />
page = page of data (zero based, requires "max") (optional)<br />
<br />
Result:<br />
<playlist total="#"><br />
<entry/><br />
<entry/><br />
<!-- etc ---><br />
</playlist><br />
<br />
The "total" attribute is the total amount of entries in the entire playlist and is not the number of playlists visible on the page though it can be calculated by using the 'ListPlaylists' operation (see [[#ListPlaylists|section 2.10]]) and working out the number of <entry> tags in the output).<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”playlistdata”<br />
seq="45"<br />
name="neils list"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<playlist total="2"><br />
<entry>groovy.mp3</entry><br />
<entry>rockon.mp3</entry><br />
</playlist><br />
</data><br />
</response><br />
<br />
<br />
===DeletePlaylist===<br />
----<br />
<br />
This operation allows you to delete a playlist from those stored by sc_trans.<br />
<br />
Parameters:<br />
op = "deleteplaylist"<br />
seq = 'any value'<br />
name = name of playlist to delete<br />
deletefile = 1 or 0. If 1 then delete the underlying file (Default is zero)<br />
<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”deleteplaylist”<br />
seq="45"<br />
name="friday night special"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===ListEvents===<br />
----<br />
<br />
This will allow you to get a list of all of the scheduled events known by sc_trans (providing an output much like the calendar.xml file would be).<br />
<br />
Parameters:<br />
op = "listevents"<br />
seq = 'any value'<br />
<br />
Result:<br />
<eventlist><br />
<event type="playlist|dj|relay"><br />
<active/><br />
<id/><br />
<dj/><br />
<playlist loopatend="1|0" shuffle="1|0" priority="#"><br />
nameofplaylist<br />
</playlist><br />
<relay url=""/><br />
<calendar/><br />
</event><br />
<event ... /><br />
<!-- etc ---><br />
</eventlist><br />
<br />
'''Line by line explanation:'''<br />
<br />
2. Each event has an <event> tag where type is 'playlist' or 'relay' or 'dj'.<br />
<br />
3. Returns 1 if the event is currently active otherwise returns 0. More than one event can be active at any time.<br />
<br />
4. Contains the id of the event.<br />
<br />
5. Contains the name of DJ (only applicable for 'dj' events).<br />
<br />
6-8. Contains the logical playlist name and flags (only for 'playlist' events).<br />
<br />
9. Contains the source url of a relay (only for 'relay' events).<br />
<br />
10. Contains the calendar date associated with the event (see [[#Calendar_Tag|section 1.2]] for the format of the time and date parameters).<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”listevents”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<eventlist><br />
<event type="playlist"><br />
<active>1</active><br />
<playlist loopatend="0" shuffle="0" priority="5"><br />
friday night special<br />
</playlist><br />
<calendar starttime="16:00:00" duration="01:00:00" repeat="4"/><br />
</event><br />
<event type="dj"><br />
<active>0</active><br />
<dj>nick the stick</dj><br />
<calendar starttime="18:00:00" duration="01:00:00" repeat="4"/><br />
</event><br />
</eventlist><br />
</data><br />
</response><br />
<br />
<br />
===AddEvent===<br />
----<br />
<br />
This allows you to add a new scheduled event comparable to editing the calendar xml file.<br />
<br />
Parameters:<br />
op = "addevent"<br />
seq = 'any value'<br />
type = 'dj' or 'relay' or 'playlist'<br />
name = name of the dj or playlist<br />
url = url for relay<br />
startdate = startdate for schedule (optional)<br />
enddate = enddate for schedule (optional)<br />
starttime = starttime for schedule (optional)<br />
duration = duration for schedule (optional)<br />
repeat = repeat value for schedule (optional)<br />
loopatend = playlists only. 1 to loop playlist until event is over. Default 0<br />
shuffle = playlists only. 1 - shuffle, 0 - no shuffle, inherit - use config file flag<br />
Default inherit<br />
priority = playlist and relay only number > 0.<br />
Used to resolve conflicting playlist or relay events. Default 1<br />
archive = djs only. 1 - archive 0 - no archive, inherit - use config file flag<br />
<br />
At least one of startdate, enddate, starttime, duration, repeat must appear.<br />
<br />
Result:<br />
<br />
The returned xml contains the id for the added event (see example).<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”addevent”<br />
seq="45"<br />
type="playlist"<br />
name="neils cool show"<br />
starttime="16:00:00"<br />
duration="1:00:00"<br />
repeat=4<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<id>3</id><br />
</data><br />
</response><br />
<br />
<br />
===DeleteEvent===<br />
----<br />
<br />
This operation allows for the removal of an existing scheduled event.<br />
<br />
Parameters:<br />
op = "deleteevent"<br />
seq = 'any value'<br />
id = id of the event<br />
<br />
The 'id' value can be obtained by using 'listevents' (see [[#ListEvents|section 2.13]]) in the <id> tag. Additionally if the event to be deleted is currently active then it will also be cancelled.<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”deleteevent”<br />
seq="45"<br />
id="12"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===AbortEvent===<br />
----<br />
<br />
This operation allows you to halt a scheduled event. If the 'id' parameter is provided then only that event will be aborted if it is currently running. If no 'id' parameter is passed then all active events will be aborted by its usage.<br />
<br />
Parameters:<br />
op = "abortevent"<br />
seq = 'any value'<br />
id = id for the event (optional)<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”abortevent”<br />
seq="45"<br />
id="12"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===ListDJS===<br />
----<br />
<br />
This will return a list of all the DJs on the system and their attributes.<br />
<br />
Parameters:<br />
op = "listdjs"<br />
seq = 'any value'<br />
name = name of specific dj (optional)<br />
<br />
Result:<br />
1. <djlist><br />
2. <dj><br />
3. <name/><br />
4. <password/><br />
5. <priority/><br />
6. <enabled/><br />
7. <banned><br />
8. <year/><br />
9. <month/><br />
10. <day/><br />
11. <hour/><br />
12. <minute/><br />
13. <second/><br />
14. </banned><br />
15. </dj><br />
16. <dj> ... </dj><br />
17. <dj .... </dj><br />
18. <!-- etc ---><br />
19. </djlist><br />
<br />
'''Line by line explanation:'''<br />
<br />
2. Each DJ is represented by a <dj> tag.<br />
<br />
3. Contains the DJ's name.<br />
<br />
4. Contains the password for DJ.<br />
<br />
5. Contains the priority level for the DJ which is used to prioritise one DJ if more than one DJ is connected at the same time.<br />
<br />
6. Contains 1 if enabled (so the DJ can connect) otherwise is 0 if disabled.<br />
<br />
7. If a banned tag appears then the DJ has been banned until the date and time indicated by the subtags as shown in lines 8-13.<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”listdjs”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
<data><br />
<djlist><br />
<dj><br />
<name>Neil</name><br />
<password>foobar</password><br />
<priority>5</level><br />
<enabled>1</enabled><br />
</dj><br />
<dj><br />
<name>Stephen</name><br />
<password>barfoo</password><br />
<level>10</level><br />
<enabled>0</enabled><br />
<banned><br />
<year>2008</year><br />
<month>10</month><br />
<day>14</day><br />
<hour>20</hour><br />
<minute>12</minute><br />
<second>10</second><br />
</banned><br />
</dj><br />
</djlist><br />
</data><br />
</response><br />
<br />
<br />
===DeleteDJ===<br />
----<br />
<br />
This will allow you to deletes a DJ from the system. It will also remove any related calendar events and kicks off the DJ if they are currently active.<br />
<br />
Parameters:<br />
op = "deletedj"<br />
seq = 'any value'<br />
name = name of dj<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”deletedj”<br />
seq="45"<br />
name="neil"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===AddDJ===<br />
----<br />
<br />
This will allow you to add a DJ to the allowed DJ's sc_trans knows about.<br />
<br />
Parameters:<br />
op = "adddj"<br />
seq = any value<br />
name = name<br />
password = dj password<br />
priority = integer priority value<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”adddj”<br />
seq="45"<br />
name="neil"<br />
password="foobar"<br />
priority=5<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===ModifyDJ===<br />
----<br />
<br />
This allows you to change the information relating to a DJ known by sc_trans.<br />
<br />
Parameters:<br />
op = "modifydj"<br />
seq = 'any value'<br />
name = name<br />
password = dj password<br />
priority = integer priority value<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”modifydj”<br />
seq="45"<br />
name="neil"<br />
password="xx45"<br />
priority=8<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===KickDJ===<br />
----<br />
<br />
This allows you to kick an active DJ from the list of ones sc_trans knows and can either be the current DJ or a named DJ when setting 'name'.<br />
<br />
Parameters:<br />
op = "kickdj"<br />
seq = 'any value'<br />
duration = amount of time dj is banned (in hh:mm:ss).<br />
name = name of dj to kick (optional - default is current dj)<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”kickdj”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===UnkickDJ===<br />
----<br />
<br />
This will allow you to cancel the ban set on a DJ known by sc_trans.<br />
<br />
Parameters:<br />
op = "unkickdj"<br />
seq = 'any value'<br />
name = name of the dj to unkick<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”unkickdj”<br />
seq="45"<br />
name="neil"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===NextTrack===<br />
----<br />
<br />
This will make sc_trans advance to the next track in the current playlist.<br />
<br />
Parameters:<br />
op = "nexttrack"<br />
seq = 'any value'<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”nexttrack”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===Capture===<br />
----<br />
<br />
Description:<br />
<br />
This allows you to activate or deactivate the live capture mode. It will also allow you to override the default options for crossfading.<br />
<br />
Parameters:<br />
<br />
op = "capture"<br />
seq = 'any value'<br />
state = "on|off"<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”capture”<br />
seq="45"<br />
state="on"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===Restart===<br />
----<br />
<br />
This allows you to restart sc_trans (often useful if a large number of settings have been changed or if there's an issue and the <restart> tag was returned by another of the apis.<br />
<br />
Parameters:<br />
op = "restart"<br />
seq = 'any value'<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”restart”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
===Quit===<br />
----<br />
<br />
This will make sc_trans completely shutdown.<br />
<br />
Parameters:<br />
op = "quit"<br />
seq = 'any value'<br />
<br />
'''Example:'''<br />
<br />
Request Parameters:<br />
op=”quit”<br />
seq="45"<br />
<br />
Resulting XML:<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<response seq="45"><br />
</response><br />
<br />
<br />
==Notes About Playlist Handling==<br />
<br />
===Using Playlists===<br />
----<br />
<br />
All playlists must first be registered with the system and assigned a symbolic name which is the value set using 'playlistfilename' in the configuration file. These registered playlists are then used as either the main playlist or as a scheduled program. There is no "priority playlist folder" as this is subsumed by scheduling a playlist for "now".<br />
<br />
<br />
===Replacing Playlists===<br />
----<br />
<br />
This has no meaning unless it is relating to the main playlist. If so then you can issue a reload by calling the older /loadplaylist method which will then schedule a main playlist reload after the next track changes.<br />
<br />
<br />
===Displaying Playlists===<br />
----<br />
<br />
All playlists are displayed as a disk view so when a playlist is being played in shuffle mode the pointer into the list will merely jump around. This may appear to be confusing but sc_trans knows what the shuffle order is but if this were to be communicated to the user then editing would become problematic.<br />
<br />
<br />
===Editing Playlists===<br />
----<br />
<br />
Editing playlists will affect the disk view. Since the user is only ever shown the disk view then there will be no ambiguity here. If the playlist is active and is NOT in shuffle mode then the files are loaded into the memory view in the appropriate place. If the playlist IS in shuffle mode then the new files are shuffled amongst themselves and added to the beginning of the memory view.</div>DrOhttp://wiki.winamp.com/wiki/Source_DSP_Plug-in_Configuration_ExamplesSource DSP Plug-in Configuration Examples2014-10-28T23:01:07Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
=Introduction=<br />
<br />
The aim of this document is to show you what needs to be entered in the different options in the plug-ins configuration window to allow it to work with the DNAS server (sc_serv2) and Transcoder (sc_trans) configuration examples. The setups covered are:<br />
<br />
#Connecting as a source to the server in SHOUTcast 2 and SHOUTcast 1 (legacy) modes<br />
#Connecting as a DJ to a transcoder in SHOUTcast 2 and SHOUTcast 1 (legacy) modes<br />
<br />
<br />
=Configurations=<br />
<br />
In all of the example configurations, it is assumed that Winamp has been chosen as the input source for the stream(s) being created and that all of the passwords used are the same as those in the DNAS server and Transcoder example configuration files. Remember that you should change the example passwords when setting up your SHOUTcast system.<br />
<br />
The choice of the encoder used is left as something for you to decide upon considering the DSP plug-in supports MP3 and AAC along with all of the different bitrates, etc. However this should not cause an issue with the example setups used but is something you need to decide upon as part of the general process in setting up a SHOUTcast system.<br />
<br />
Finally the name of the options as shown in the english translation of the plug-in on its 'Output' tab ([[Source_DSP_Plug-in#Output_Tab|see Source DSP - section 3.2]]) will be used in this file to identify the options which need to be entered. This is mentioned incase a localised version of the DSP plug-in is used (a nice feature implemented in version 2 of the plug-in).<br />
<br />
<br />
==Direct Source to a SHOUTcast v2 DNAS Server==<br />
<br />
Connection Tab<br />
----<br />
[[Image:Direct_Source_to_a_SHOUTcast_v2_DNAS_Server.png|200px|thumb|right|Direct Source to a SHOUTcast v2 DNAS Server]]<br />
'''Server Address''' : localhost (or the IP of the server if it is different from the local machine ([[Source_DSP_Plug-in#Connection Tab|see Source DSP - section 3.2.1]] for more information)).<br />
<br />
'''Port''' : 8000 (or the value set for 'portbase' ([[SHOUTcast_DNAS_Server_2#Networking|see DNAS Server - section 4.8]])).<br />
<br />
'''Stream ID''' : 1 (or the value set for 'streamid' for the relevant connection being made to the server ([[SHOUTcast_DNAS_Server_2#Stream_Configuration|see DNAS Server - section 4.12]])).<br />
<br />
'''DJ / User ID''' : this can be left blank and is not used with a source connection.<br />
<br />
'''Password''' : testing (or the value set for 'password' ([[SHOUTcast_DNAS_Server_2#Networking|see DNAS Server - section 4.8]])).<br />
<br />
'''Use SHOUTcast v1 mode (for legacy servers)''' : ensure this is '''UNCHECKED'''.<br />
<br />
<br />
Directory Tab<br />
----<br />
<br />
Here you can enter any details as required to identify or provide contact details for your stream to any clients connecting or when viewed on the SHOUTcast Directory listing.<br />
<br />
'''Make this server public (Recommended)''' : The usage of this setting depends upon the value 'publicserver' in your server configuration. See [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|DNAS Server - section 4.14]] for details.<br />
<br />
<br />
==Direct Source to a SHOUTcast v1 DNAS Server (Legacy)==<br />
<br />
Connection Tab<br />
----<br />
[[Image:Direct_Source_to_a_SHOUTcast_v1_DNAS_Server_(Legacy).png|200px|thumb|right|Direct Source to a SHOUTcast v1 DNAS Server (Legacy)]]<br />
'''Server Address''' : localhost (or the IP of the server if it is different from the local machine ([[Source_DSP_Plug-in#Connection Tab|see Source DSP - section 3.2.1]] for more information)).<br />
<br />
'''Port''' : 8000 (or the value set for 'portbase' for the SHOUTcast v1 DNAS server used).<br />
<br />
'''DJ / User ID''' : this ''must'' be left blank and is not used with a source connection.<br />
<br />
'''Password''' : testing (or the value set for 'password' for the SHOUTcast v1 server used).<br />
<br />
'''Use SHOUTcast v1 mode (for legacy servers)''' : ensure this is '''CHECKED'''.<br />
<br />
<br />
Directory Tab<br />
----<br />
<br />
Here you can enter any details as required to identify or provide contact details for your stream to any clients connecting or when viewed on the SHOUTcast Directory listing.<br />
<br />
<br />
==DJ Source to the Transcoder in SHOUTcast v2 Mode==<br />
<br />
Connection Tab<br />
----<br />
[[Image:DJ_Source_to_the_Transcoder_in_SHOUTcast_v2_Mode.png|200px|thumb|right|DJ Source to the Transcoder in SHOUTcast v2 Mode]]<br />
'''Server Address''' : localhost (or the IP of the server if it is different from the local machine ([[Source_DSP_Plug-in#Connection Tab|see Source DSP - section 3.2.1]] for more information)).<br />
<br />
'''Port''' : 8505 (or the value set for 'djport2' ([[SHOUTcast_DNAS_Transcoder_2#DJ_Support|see Transcoder - section 3.3]])).<br />
<br />
'''Stream ID''' : this can be left as the default value ('1') as the Transcoder effectively ignores this for this connection though may be used in future versions.<br />
<br />
'''DJ / User ID''' : dj (or the value set for 'djlogin' for the respective DJ account setup in the sc_trans configuration ([[SHOUTcast_DNAS_Transcoder_2#DJ_Support|see Transcoder - section 3.3]])).<br />
<br />
'''Password''' : noise (or the value set for 'djpassword' for the respective DJ account setup in the sc_trans configuration ([[SHOUTcast_DNAS_Transcoder_2#DJ_Support|see Transcoder - section 3.3]])).<br />
<br />
'''Use SHOUTcast v1 mode (for legacy servers)''' : ensure this is UNCHECKED.<br />
<br />
<br />
Directory Tab<br />
----<br />
<br />
Here you can enter any details as required to identify or provide contact details for your stream to any clients connecting or when viewed on the SHOUTcast Directory listing.<br />
<br />
Make this server public (Recommended) : The usage of this setting depends upon the value 'publicserver' in your server configuration. See [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|DNAS Server - section 4.14]] for details.<br />
<br />
<br />
==DJ Source to the Transcoder in SHOUTcast v1 Mode (Legacy)==<br />
<br />
Connection Tab<br />
----<br />
[[Image:DJ_Source_to_the_Transcoder_in_SHOUTcast_v1_Mode_(Legacy).png|200px|thumb|right|DJ Source to the Transcoder in SHOUTcast v1 Mode (Legacy)]]<br />
'''Server Address''' : localhost (or the IP of the server if it is different from the local machine ([[Source_DSP_Plug-in#Connection Tab|see Source DSP - section 3.2.1]] for more information)).<br />
<br />
'''Port''' : 8500 (or the value set for 'djport' ([[SHOUTcast_DNAS_Transcoder_2#DJ_Support|see Transcoder - section 3.3]])).<br />
<br />
'''DJ / User ID''' : dj (or the value set for 'djlogin' for the respective DJ account setup in the sc_trans configuration ([[SHOUTcast_DNAS_Transcoder_2#DJ_Support|see Transcoder - section 3.3]])).<br />
<br />
'''Password''' : noise (or the value set for 'djpassword' for the respective DJ account setup in the sc_trans configuration [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|see Transcoder - section 3.3]])).<br />
<br />
'''Use SHOUTcast v1 mode (for legacy servers)''' : ensure this is CHECKED.<br />
<br />
<br />
Directory Tab<br />
----<br />
<br />
Here you can enter any details as required to identify or provide contact details for your stream to any clients connecting or when viewed on the SHOUTcast Directory listing.<br />
<br />
'''Make this server public (Recommended)''' : The usage of this setting depends upon the value 'publicserver' in your server configuration. See [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|DNAS Server - section 4.14]] for details.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_DNAS_Server_2_XML_ReponsesSHOUTcast DNAS Server 2 XML Reponses2014-10-28T23:00:56Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The purpose of this document is to show you the information and format of the different xml responses which the SHOUTcast v2 server is able to generate allowing accessing to the information about the current connections or available stream configurations for example.<br />
<br />
<br />
==How to Access XML Responses==<br />
<br />
Due to the SHOUTcast v2 DNAS being able to support multiple streams, it requires you to specify the stream identifier of the stream that you require information about.<br />
<br />
So to access the General Server Summary ([[#General_Server_Summary|see section 2.2]]) for stream identifier '''1''' then the following would be used:<br />
<br />
http://<serverip>:<port>/admin.cgi?mode=viewxml&page=1&sid='''1'''<br />
or<br />
http://<serverip>:<port>/stats?sid='''1'''<br />
<br />
To access the same for stream identifier then replace '''1''' with '''2''' and so on for any other streams you want to obtain the information from.<br />
<br />
Throughout the rest of this document, it is assumed you know how to specify the stream identifier<br />
you require so only the base part of the url is shown i.e. /stats instead of /stats?sid=#<br />
<br />
<br />
===Full Server Summary===<br />
----<br />
<br />
When using the administrative '''admin.cgi?mode=viewxml''' option the xml response is of the general details about stream as is shown in a dispersed manner over the administration and public summary pages as well as details of the Listener Stats ([[#Listener_Stats|see section 2.3]]) and Song History ([[#Song_History|see section 2.4]]).<br />
<br />
If you only require a specific set of information then you should look at the &page=X parameter when accessing the '''admin.cgi?mode=viewxml''' option as the xml response from this option is a combination of the following responses:<br />
<br />
General Server Summary ([[#General_Server_Summary|section 2.2]])<br />
Listener Stats ([[#Listener_Stats|section 2.3]])<br />
Song History ([[#Song_History|section 2.4]])<br />
<br />
<br />
<br />
===General Server Summary===<br />
----<br />
<br />
When using the administrative '''admin.cgi?mode=viewxml&page=1''' or the public '''/stats''' option the xml response is of the general details about stream as is shown in a dispersed manner over the administration and public summary pages. This is a compact version of what is otherwise shown in the 'Full Server Summary' ([[#Full_Server_Summary|see section 2.1]]) and acts as the equivalent<br />
of 7.html ([[#Equivalent_of_7.html|see section 3.0]]).<br />
<br />
'''Example:'''<br />
<br />
<source lang="xml"><?xml version="1.0" encoding="UTF-8" standalone="yes" ?><br />
<SHOUTCASTSERVER><br />
<CURRENTLISTENERS>0</CURRENTLISTENERS><br />
<PEAKLISTENERS>0</PEAKLISTENERS><br />
<MAXLISTENERS>32</MAXLISTENERS><br />
<UNIQUELISTENERS>0</UNIQUELISTENERS><br />
<!-- average time (seconds) of any active client connections --><br />
<AVERAGETIME>0</AVERAGETIME><br />
<br />
<!-- these are some information about the stream as shown in clients, etc --><br />
<SERVERGENRE>Misc</SERVERGENRE><br />
<SERVERURL>http://my_website.com</SERVERURL><br />
<SERVERTITLE>Test Server</SERVERTITLE><br />
<br />
<!-- if the SHOUTcast source provides current and next song titles then --><br />
<!-- they will be listed. if not known then these will be empty entries --><br />
<SONGTITLE>The Current Song</SONGTITLE><br />
<NEXTTITLE>The Next Song</NEXTTITLE><br />
<br />
<!-- these 3 are only listed if the stream is from a SHOUTcast v1 source --><br />
<!-- otherwise they are not included as v2 sources do not support them --><br />
<IRC></IRC><br />
<ICQ></ICQ><br />
<AIM></AIM><br />
<br />
<!-- cumulative total of any attempts to connect to the stream when it is active --><br />
<STREAMHITS>0</STREAMHITS><br />
<br />
<!-- shows 1 if a source is connected and 0 if there is no source --><br />
<!-- note: if there is no source then no client connections occur --><br />
<STREAMSTATUS>1</STREAMSTATUS><br />
<br />
<!-- infomation about the format of the stream content and access path--><br />
<STREAMPATH>/test.aac</STREAMPATH><br />
<BITRATE>320</BITRATE><br />
<CONTENT>audio/aacp</CONTENT><br />
<br />
<!-- version of the SHOUTcast server being used --><br />
<VERSION>0.2.0.0 0.0.21.0</VERSION><br />
</SHOUTCASTSERVER></source><br />
<br />
<br />
===Listener Stats===<br />
----<br />
<br />
When using the administrative '''admin.cgi?mode=viewxml&page=3''' option the xml response is of the details about currently connected clients to the server for this stream. If there are no clients connected to then there will be no <LISTENER> entries in the xml response.<br />
<br />
'''Example:'''<br />
<br />
<source lang="xml"><?xml version="1.0" encoding="UTF-8" standalone="yes" ?><br />
<SHOUTCASTSERVER><br />
<LISTENERS><br />
<LISTENER><br />
<HOSTNAME>127.0.0.1</HOSTNAME><br />
<USERAGENT>WinampMPEG/5.61</USERAGENT><br />
<CONNECTTIME>1337</CONNECTTIME><br />
<!-- a unique number for the client connection used to determine duplicates --><br />
<UID>01234567</UID><br />
</LISTENER><br />
</LISTENERS><br />
</SHOUTCASTSERVER></source><br />
<br />
<br />
===Song History===<br />
----<br />
<br />
When using the administrative '''admin.cgi?mode=viewxml&page=4''' option the xml response is of the currently stored played song history (if enabled) of the stream. If any song titles have been sent to the server then they will displayed up to the number of songs played as per the 'songhistory' option (see sc_serv2.txt - [[SHOUTcast_DNAS_Server_2#Miscellaneous|section 4.7]]) otherwise there will be no <SONG> entries in the xml response.<br />
<br />
'''Example:'''<br />
<br />
<source lang="xml"><?xml version="1.0" encoding="UTF-8" standalone="yes" ?><br />
<SHOUTCASTSERVER><br />
<SONGHISTORY><br />
<SONG><br />
<!-- PLAYEDAT is a raw time_t (UTC time) value of when the song was started --><br />
<PLAYEDAT>1302180341</PLAYEDAT><br />
<TITLE>The Previous Title</TITLE><br />
</SONG><br />
<SONG><br />
<PLAYEDAT>1302175246</PLAYEDAT><br />
<TITLE>The Current Song</TITLE><br />
</SONG><br />
</SONGHISTORY><br />
</SHOUTCASTSERVER></source><br />
<br />
<br />
===Stream Metadata===<br />
----<br />
<br />
When using the administrative '''admin.cgi?mode=viewxml&page=5''' option the xml response is of the currently stored stream metadata as provided by the connected SHOUTcast source. This can just be a title (typically with a SHOUTcast v1 source) or can be a complete metadata block with a SHOUTcast v2 source which is providing all data from an mp3 file.<br />
<br />
'''Example:'''<br />
<br />
<source lang="xml"><?xml version="1.0" encoding="UTF-8" standalone="yes" ?><br />
<SHOUTCASTSERVER><br />
<SONGMETADATA><br />
<!-- this will be the only entry if a SHOUTcast v1 source is connected --><br />
<TIT2>The Current Title</TIT2><br />
<TALB>The Album Title</TALB><br />
<TPE1>The Artist</TPE1><br />
<TYER>2011</TYER><br />
<TCON>Podcast</TCON><br />
<TENC>SHOUTcast Source DSP Plug-in v2.2.0 BUILD 099</TENC><br />
<TRSN>My SHOUTcast Server</TRSN><br />
<WORS>http://www.shoutcast.com</WORS><br />
</SONGMETADATA><br />
</SHOUTCASTSERVER></source><br />
<br />
Detailed information on the supported fields and also suggested fields to be provided by a SHOUTcast v2 source can be found in the [[SHOUTcast_XML_Metadata_Specification|SHOUTcast XML Metadata Specification]].<br />
<br />
<br />
===Stream Configurations===<br />
----<br />
<br />
When using the administrative '''admin.cgi?mode=viewxml&page=6''' option the xml response is of the currently known stream configuration details (based on the options set in the loaded configuration file) and any global stream configuration options which are applicable.<br />
<br />
This is a global action and when used the stream identifier will not be used but is<br />
still required to be specified and to be a valid stream identifier when requested.<br />
<br />
'''Example:'''<br />
<br />
<source lang="xml"><?xml version="1.0" encoding="UTF-8" standalone="yes" ?><br />
<SHOUTCASTSERVER><br />
<STREAMCONFIGS><br />
<!-- these are global settings / information about the stream configurations --><br />
<!-- if REQUIRECONFIGS is 1 then only source connections matching are allowed --><br />
<REQUIRECONFIGS>0</REQUIRECONFIGS><br />
<SERVERMAXLISTENERS>32</SERVERMAXLISTENERS><br />
<!-- this is the total number of stream configurations known and enabled --><br />
<TOTALCONFIGS>1</TOTALCONFIGS><br />
<br />
<!-- the value of 'id' relates to 'streamid' and is used to identify the group --><br />
<STREAMCONFIG id="1"><br />
<STREAMAUTHHASH>my_aush_hash_if_entered</STREAMAUTHHASH><br />
<STREAMPATH>/listen1</STREAMPATH><br />
<STREAMRELAYURL></STREAMRELAYURL><br />
<!-- if set as SERVERMAXLISTENERS then the global SERVERMAXLISTENERS is in use --><br />
<STREAMMAXLISTENERS>SERVERMAXLISTENERS</STREAMMAXLISTENERS><br />
<STREAMPUBLIC>never</STREAMPUBLIC><br />
<STREAMALLOWRELAY>1</STREAMALLOWRELAY><br />
<STREAMPUBLICRELAY>1</STREAMPUBLICRELAY><br />
</STREAMCONFIG><br />
</STREAMCONFIGS><br />
</SHOUTCASTSERVER></source><br />
<br />
<br />
===Nextsongs===<br />
----<br />
<br />
When using the public '''/nextsongs''' admin option the xml response contains a list of titles (if available from the source) of the songs which are to be played after the currently playing song finishes. The number of song titles returned is determinded by the source so this file can contain no titles or it could contain 10 titles.<br />
<br />
'''Example:'''<br />
<br />
<source lang="xml"><?xml version="1.0" encoding="UTF-8" standalone="yes" ?><br />
<SHOUTCASTSERVER><br />
<NEXTSONGS><br />
<!-- the first title in the list begins at "1" and goes up --><br />
<TITLE seq="1">The Next Song - To Be Played</TITLE><br />
<TITLE seq="2">The Following Song - Or Not To Be Played</TITLE><br />
..<br />
<!-- XX is the last file returned --><br />
<TITLE seq="XX">The Final Song - That Is The Question</TITLE><br />
</NEXTSONGS><br />
</SHOUTCASTSERVER></source><br />
<br />
<br />
<br />
==Equivalent of 7.html==<br />
<br />
In SHOUTcast DNAS v1 servers a 7.html could be accessed to get certain information about the current server instance for reporting and other usage. This is no longer provided in the SHOUTcast v2 DNAS and has been replaced by an equivalent xml response which provides some extra information via the '''/stats''' (public) or '''admin.cgi?mode=viewxml&page=1''' (private) options.<br />
<br />
The following shows the order of and what information was provided by the 7.html response against the xml entry name in the '''/stats''' or '''admin.cgi?mode=viewxml&page=1''' xml response:<br />
<br />
CURRENTLISTENERS STREAMSTATUS PEAKLISTENERS MAXLISTENERS UNIQUELISTENERS BITRATE SONGTITLE</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Authhash_ManagementSHOUTcast Authhash Management2014-10-28T23:00:35Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
One of the key aspects of the new YP2 directory infrastructure is an authorisation key (authhash) which is used to validate your server when it tries to connect to the YP2 infrastructure for any of the station(s) you run. Once this key is obtained, it will be valid for all root servers of the station being broadcast.<br />
<br />
You can obtain multiple authorisation keys if broadcasting the same stream content at different bitrates so they will appear separately in the SHOUTcast Directory listings. This is not needed if broadcasting the same content in MP3 and AAC+ formats as the SHOUTcast Directory will automatically list those streams separately.<br />
<br />
Make sure you are using a version of the DNAS which supports this feature<br />
which can be found at http://www.shoutcast.com/broadcast-tools or [http://forums.winamp.com/showthread.php?t=324877 here].<br />
<br />
<br />
===When is an Authorisation Key needed?===<br />
<br />
The DNAS server can be run in two modes:<br />
*'''Public''' - If you want your station to appear in the SHOUTcast Directory listings<br />
*'''Private''' - If you do not want your station to be listed e.g. an internal company station<br />
<br />
If you want the station to be '''public''' then you will need an authorisation key, otherwise it is not needed for '''private''' stations.<br />
<br />
If you want to run the DNAS privately then you can change the appropriate setting in the stream source being used. Otherwise you can change '''publicserver''' or '''streampublicserver''' (if needing stream specific control) to be ''never'' in the DNAS's configuration file e.g. '''publicserver=never'''.<br />
<br />
<br />
==Management==<br />
[[Image:Summary.png|thumb|right|DNAS Summary Page]][[Image:Starting.png|thumb|right|Administrator Summary Page]]To obtain a unique authentication key you first need to have setup the DNAS and have a source (such as the Source DSP or Transcoder) correctly connected so the stream is recognised by the DNAS. This can be determined from looking at the '''DNAS Summary''' page which will show any active stream(s) - if there are none then you will need to re-check the source is showing it is connected to the DNAS server.<br />
<br />
<br />
The next step is to login to the '''Administrator Summary''' page which is accessed via the '''Administrator Login''' on the '''DNAS Summary''' page (found at the top right as shown in the image of the '''DNAS Summary''' page). If DNAS server is running on the same machine then you can usually access it directly at http://127.0.0.1:8000/admin.cgi. If you have changed 'portbase' then change 8000 to the value specified for 'portbase' in your config file.<br />
<br />
To login, the username is '''admin''' and the password is the configured [[SHOUTcast_DNAS_Server_2#Networking|'''adminpassword''']]<br />
<br />
If you are accessing the DNAS server remotely or on another machine then you will need to change 127.0.0.1 to the appropriate IP address of the machine you are trying to access.<br />
<br />
On the '''Administrator Summary''' page, you will see all streams with a source connected to them, with '''Create Authhash''', '''Update Authhash''' and '''Remove Authhash''' options shown as appropriate beneath the stream number.<br />
<br />
<br />
===Creating===<br />
[[Image:Editing.png|thumb|right|Creating an Authhash]][[Image:Completed.png|thumb|right|Created an Authhash]]To create an authhash for a stream then you need to click the '''Create Authhash''' link. This will take you to another page where you need to fill in the missing fields as applicable for your stream as the DNAS attempts to fill in fields with the information obtained from the connected source. Once all of the required information has been entered then click the '''Create Authhash''' button.<br />
<br />
If there is a missing field or something is not right when attempting to create the authhash, then you will see a message showing what needs to be entered or changed or what to do to get additional help.<br />
<br />
On successful creation, the new authhash will be saved into your configuration file either in the root configuration file or one where there's an empty streamauthhash entry matching the stream identifier. When you go back to the '''Administrator Summary''' page the '''Create Authhash''' link will have changed to '''Update Authhash''' and '''Remove Authhash''' links.<br />
<br />
It can take up to 10 minutes for the new authhash to be fully recognised so if you<br />
have made a mistake or are trying to get listed then you will need to be wait.<br />
<br />
===Updating===<br />
Updating an authhash is the same as creating an authhash just with the existing information of the authhash shown in the fields allowing for them to be edited. If there are no issues and the authhash can be updated from the machine used (with it having the same external IP as used to create the authhash) then any changes made should be updated in the YP system.<br />
<br />
If there is a missing field or something is not right when attempting to create the authhash, then you will see a message showing what needs to be entered or changed or what to do to get additional help.<br />
<br />
It can take up to 10 minutes for changed details to be fully recognised so if<br />
you have made a mistake or are trying to get listed then you will need to wait.<br />
<br />
===Removing===<br />
[[Image:Removed.png|thumb|right|Removed an Authhash]]Removing an authhash is a simple action of clicking the '''Remove Authhash''' link. If there are no issues and the authhash can be removed from the machine used (with it having the same external IP as used to create the authhash) then it will be removed from the YP system and also from your configuration file.<br />
<br />
<br />
===Duplicating===<br />
If you want to use the same authhash on another stream (e.g. if only the stream format is different or you want to group the same stream content) then you will need to manually edit you configuration file by setting the relevant streamauthhash entry for the required stream configuration group and use the '''Reload All Stream Configuration(s)''' option on the '''Administrator Summary''' page.<br />
<br />
<br />
==Management Issues==<br />
<br />
Updating or removing an authhash requires the same external IP of the machine to be found by the YP against what was used when the authhash was created. If this external IP has changed then you will need to contact support via [http://forums.winamp.com/showthread.php?t=331394 this forum thread] ensuring all required information is provided as is detailed.<br />
<br />
If you experience other issues with managing your authhashes via the options provided, make sure you follow any information provided to attempt to resolve the issue. If that still does not work then you will need to contact support via [http://forums.winamp.com/showthread.php?t=331394 this forum thread] ensuring all required information is provided as is detailed.<br />
<br />
<br />
===Supported Browsers===<br />
<br />
The following browsers have been tested and are supported when using the authhash management pages:<br />
<br />
*Firefox 3.6.x to 7.0 (tested on Windows and Linux)<br />
*Internet Explorer 8 & 9<br />
*Google Chrome 12 & 13 (will likely work on older versions)<br />
*Safari 4.x (only tested on Mac)<br />
<br />
<br />
The following are browsers which have been tested and are known to have issues causing reduced functionality (not related to security options which can be changed):<br />
<br />
*Opera (tested on Windows against 11.51)<br />
<br />
<br />
Currently DNAS v2.0.0 Build 29 will show the following message when using this browser:<br />
Problem was experienced retrieving the details for the dropdown options.<br />
<br />
You will need to change your browser's security settings to allow remote<br />
content to be downloadable in this domain. Please fix and refresh this page.<br />
<br />
Future versions of the DNAS will show the more appropriate message of:<br />
Unable to download the details for the dropdown options. You need to<br />
use a browser with 'Cross Origin Resource Sharing' (CORS) support.<br />
<br />
<br />
<br />
===Using Internet Explorer===<br />
<br />
Using a different browser is recommended as changing security levels is not ideal and is done at your own risk.<br />
<br />
If using Internet Explorer (8 or 9), you will need to do the following to allow the browser to access the remote content needed for the drop-down options which the page uses.<br />
<br />
Go to '''Options''' -> '''Security''' -> Select ''''Trusted Sites'''' -> Click ''''Sites'''' and then add the current page to the list (unchecking the HTTPS option). Then change the ''''Trusted Level'''' to Medium-low or Low and refresh the authhash management page.<br />
<br />
Choosing Medium-low will cause a prompt to appear on loading the pages in IE8 (but not normally in IE9) which you will need to choose ''''Yes'''' to allow the page to load. Choosing Low will not show a prompt.</div>DrOhttp://wiki.winamp.com/wiki/Source_DSP_Plug-inSource DSP Plug-in2014-10-28T23:00:17Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction to the Source DSP==<br />
<br />
The aim of this document is to show you the different features offered by the Source DSP plug-in. Version 2 of the plug-in is designed to work only on Winamp 5.5 and higher due to better api usage and integration with the player. If you want to use the Source DSP in an alternative player, then it would need to support all of the required Winamp apis.<br />
<br />
The key feature of the plug-in is the ability to use Winamp as a source to a DNAS server or a Transcoder / AutoDJ instance or any compatible tool which accepts SHOUTcast streams.<br />
<br />
Additionally the plug-in will allow you to capture an audio input from the soundcard and its line-in or microphone inputs ([[#Soundcard Mixer Control|section 3.3.2]]) subject to OS and the audio system.<br />
<br />
<br />
==Getting Started==<br />
<br />
To start using the Source DSP you need a configured and running DNAS server (sc_serv) or an alternative server to connect to like the Transcoder (sc_trans) and to have all of the login details required to connect as a source. The plug-in can be used as either a full full source or it can be used as a DJ connection in the case of being used with sc_trans.<br />
<br />
<br />
===Installing the Plug-in===<br />
----<br />
[[Image:Select_Source_DSP_in_Winamp.png|225px|thumb|right|Select_Source_DSP_in_Winamp.png]]<br />
The installer will detect the Winamp install on your machine and will then install it to the correct location. If the detected Winamp version is prior to v5.5 or if there is no winamp.exe present in the folder chosen then the installer will abort the installation.<br />
<br />
Once installed, if you have not chosen to make the Source DSP the default DSP plug-in, you will need to open Winamp and go to the following location:<br />
<br />
Preferences -> Plug-ins -> DSP/Effect<br />
<br />
follwed by selecting the 'Nullsoft SHOUTcast Source DSP' entry shown in the plug-in list.<br />
<br />
<br />
==Configuration Window==<br />
<br />
The configuration window is the main interface of the plug-in and is where login details for the connection to the server can be changed or the current status viewed.<br />
<br />
When the configuration window is closed then any active connections will be closed. If you want to hide the window then you can click use the minimise button on the window and click on the notification area icon added when the minimise happened.<br />
<br />
<br />
===Summary Tab===<br />
----<br />
<br />
[[Image:Summary_tab.png|100px|thumb|right|SHOUTcast Source Summary Tab]]<br />
'''Status / Info''' : This will show information about the status of the 5 possible outputs the plug-in is able to provide going from not connected to current duration of the connection.<br />
<br />
If you double-click one of the output items you will be taken to the '[[#Output Tab|see section 3.2]]'<br />
(see section 3.2) where it will show the current settings for the output selected.<br />
<br />
'''Active Input Device''' : This allows you to toggle between using Winamp and the configured soundcard input as well seeing the current audio capture mode. For more configuration options go to the 'Input Tab' ([[#Input Tab|see section 3.3]]).<br />
<br />
'''Input Meters''' : These show the current and peak audio level of the left and right channels as is being passed through the plug-ins core. This can aid in seeing if the input source is possibly not working or to check the audio is clipped.<br />
<br />
<br />
===Output Tab===<br />
----<br />
[[Image:Output_tag_configuration_error.png|100px|thumb|right|SHOUTcast Source Output Tab showing password configuration error]]<br />
This tab allows you to configure the 5 separate outputs the plug-in is able to generate where the settings for the output are selected by clicking the required item in the list.<br />
<br />
'''Status''' : This will show the current information about the output source ranging from not being connected to error messages due to invalid passwords to running correctly.<br />
<br />
'''Auto Connect''' : This will make the plug-in attempt to run this output as soon as it is started or when the option is checked if not already running when checked.<br />
<br />
'''Connect / Abort / Disconnect / Kill Button''' : This allows you to start a connection, abort a connection try or kill / disconnect an active connection. If 'Auto Connect' is checked and you click this for a disconnect action then the plug-in automatically re-starts the connection.<br />
<br />
If there is an issue the 'Connect / Abort / Disconnect / Kill Button' will<br />
show the configuration setting which is invalid e.g. 'Set Password' if the<br />
encoder has not been specified. The tab and the title above where the value<br />
is not set will have it's text changed to red to make it easier to identify.<br />
<br />
<br />
====Login Tab====<br />
----<br />
<br />
This tab allows you to specify the details needed for connecting to a DNAS server.<br />
[[Image:Output_tab_login_tab_v1_enabled.png|100px|thumb|right|SHOUTcast Source Output Connection Tab in v1 (Legacy) mode]]<br />
'''Server Address''' : This is the address of the server to connect to and will depend upon the setup which is being used. If the server being connected to is on the same machine then 'localhost' can be entered, otherwise the exact IP or DNS name of the server e.g. myserver.com needs to be entered here.<br />
<br />
'''Port''' : This is the port related to the 'address' of the server to connect to. This needs to match 'portbase' ([[SHOUTcast_DNAS_Server_2#Networking|DNAS Server - section 4.8]]) or 'serverport' ([[SHOUTcast_DNAS_Transcoder_2#Network_Options|Transcoder - section 3.11]]) if connecting to the official tools or the port value given to use.<br />
<br />
'''Stream ID''' : This is the identifier used to identify the source to the server when using a SHOUTcast 2 supporting setup. This needs to match 'streamid' ([[SHOUTcast_DNAS_Server_2#Networking|DNAS Server - section 4.8]]) or 'streamid' ([[SHOUTcast_DNAS_Transcoder_2#Network_Options|Transcoder - section 3.11]]) if connecting to the official tools or the port value given to use.<br />
<br />
This is disabled if 'Use SHOUTcast v1 mode (for legacy servers)' is checked.<br />
<br />
'''DJ / User ID''' : This is the user id as specified on the server for the type of connection the plug-in is being asked to make. Examples of using this would be the 'djlogin' value from [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|Transcoder - section 3.3]] though this depends on the server configuration being used. Most likely you will be provided with a user id only if it is applicable to your setup.<br />
<br />
If using a compatible v2 DNAS server then this can be entered and will<br />
be used as an identifier of the current DJ but it is not used for the login.<br />
<br />
'''Password''' : This is the password required for accessing the server (if set on the server). This needs to match 'password' ([[SHOUTcast_DNAS_Server_2#Networking|DNAS Server - section 4.8]]) or 'password' ([[SHOUTcast_DNAS_Transcoder_2#Network_Options|Transcoder - section 3.11]]) if connecting to the official tools.<br />
<br />
'''Automatic reconnection on connection failure''' : This will make the plug-in attempt to connect back to the server if there is a break in the connection.<br />
<br />
'''Reconnection timeout''' : This is the number of seconds for the plug-in to wait in-between any connection attempts which fail before it will try again.<br />
[[Image:Output_tab_login_tab_v2_enabled.png|100px|thumb|right|SHOUTcast Source Output Connection Tab in v2 mode]]<br />
'''Use SHOUTcast v1 mode (for legacy servers)''' : This controls the mode the plug-in will run as. When checked it will create a SHOUTcast v1 connection otherwise it will create a SHOUTcast v2 connection (this is the default on new installs).<br />
<br />
Not setting the correct mode for the server you want to connect to will cause the connection attempt to fail or enter into what appears to be a hung state where you are likely to see a 'Cipher response received' if connecting in v2 mode to v1 server. If the plug-in determines this is likely to have happened then it will show the following in status area:<br />
Cipher response received<br />
Try enabling 'SHOUTcast v1 mode'.<br />
<br />
<br />
When SHOUTcast v2 mode is enabled the information panel displayed below this option shows the following message:<br />
Connecting to a SHOUTcast v1 server in<br />
non-legacy mode will likely cause the last<br />
status message to remain on "Cipher<br />
response received". To fix this you need to<br />
enable the "SHOUTcast v1 mode" above.<br />
<br />
When SHOUTcast v1 mode is enabled the information panel displayed below this option shows the following message:<br />
When the DJ password is formatted as<br />
<djlogin>:<djpassword> e.g. dj_1:noise<br />
<br />
Enter <djlogin> in 'DJ / User ID' e.g. dj_1<br />
Enter <djpassword> in 'Password' e.g. noise<br />
<br />
<br />
<br />
====Directory Tab====<br />
----<br />
<br />
This tab allows you to specify values specific to the stream for being listed or for what is provided to listeners when they connect to the DNAS server based on the version set.<br />
<br />
[[Image:Output_tab_directory_tab.png|100px|thumb|right|SHOUTcast Source Output Directory Tab]]<br />
'''Make this server public (Recommended)''' : With this enabled, the stream is indicated as being allowed to appear in the SHOUTcast Directory. This will enable options as applicable based also on the mode the plug-in is set to run as.<br />
<br />
'''Name''' : This is the name you want to use for the source (often what will be used in SHOUTcast Directory listing).<br />
<br />
'''URL''' : This is the url for the stream allowing listeners to view or get more information.<br />
<br />
'''Genre''' : This is the genre for the source and is used to categorise the stream if listed on the SHOUTcast Directory listing. Select the genre from the arrow button menu. It is not possible to manually enter the genre and the input field is read-only.<br />
<br />
'''Arrow Button''' : This will show a menu with known genres and sub-genres allowed for any SHOUTcast Directory listings. This will only be enabled if using v1 mode or if using v2 mode and 'Make this server public' is unchecked.<br />
<br />
'''AIM / ICQ / IRC''' : These allow you to specify some contact information for clients though support of these fields is only available when using SHOUTcat v1 mode.<br />
<br />
<br />
====Encoder Tab====<br />
----<br />
<br />
[[Image:Output_tab_encoder_tab.png|100px|thumb|right|SHOUTcast Source Output Encoder Tab]]<br />
This tab allows you to specify the encoder to be used to create the output stream from the input stream the plug-in gets. The following encoders are available with the plug-in:<br />
<br />
MP3 (audio/mpeg)<br />
AAC (audio/aacp)<br />
<br />
The AAC (actually ADTS-AAC) encoding is provided by enc_aacplus.dll (Winamp 5.1 to 5.61) or enc_fhgaac.dll (Winamp 5.62 and up). If this is not detected in the Winamp plug-ins folder then only MP3 encoding is available.<br />
<br />
Based on the encoder selected, the 'encoder settings' section will provide different options for controlling the encoder settings as either a button to open a configuration window or a dropdown list with options to choose from.<br />
<br />
<br />
=====Save Encoded Output=====<br />
----<br />
<br />
This allows you to make a backup of the stream audio data sent to the DNAS server.<br />
<br />
'''Save a copy of the encoded stream audio''' : Enables or disables saving a copy of the audio.<br />
<br />
The extension of the output file is automatically changed based on the selected<br />
encoder option to ensure that the file can be easily played in most media players.<br />
<br />
<br />
====Titles Tab====<br />
----<br />
[[Image:Output_tab_titles_tab.png|100px|thumb|right|SHOUTcast Source Output Titles Tab]]<br />
This tab allows you to specify how the stream metadata is gathered from Winamp or if it is manually entered with the options provided.<br />
<br />
'''Disable title updates''' : This will prevent the Source DSP from sending any title updates.<br />
<br />
'''Follow Winamp's title updates''' : his makes the Source DSP use Winamp's title updates for stream title updates, sent in the format based on the 'Use SHOUTcast v1 mode (for legacy servers)' setting.<br />
<br />
'''Send next track title to the server (if applicable)''' : This sends the next track title to the server when using the v2 mode and if the plug-in can determine the next track.<br />
<br />
The current version of Winamp is always recommended to use<br />
due to the improved support for this feature since Winamp v5.61.<br />
<br />
'''Manual title updates''' : This will only send titles updates when 'Send Update' is pressed which uses the custom title information entered into the 'now' and 'next' fields (which are enabled as applicable to the mode in use).<br />
<br />
The 'Send Update' button is enabled when a title is entered or it is<br />
different from the existing title. When using SHOUTcast v2 mode the<br />
'next' title field will become available as long as title field is not empty.<br />
<br />
<br />
====Artwork====<br />
----<br />
<br />
[[Image:Output_tab_artwork_tab_v2_enabled.png|100px|thumb|right|SHOUTcast Source Output Artwork in v2 mode]]<br />
This tab allows you to specify whether in-stream artwork will be sent to the SHOUTcast server and if so the type of artwork which will be sent which can be for the station in general as well as per file artwork (much like album art display in most media players).<br />
<br />
'''Send in-stream artwork''' : Enables or disables sending of in-stream artwork.<br />
<br />
If this is enabled and then disabled, it is possible that the<br />
plug-in will send some clear artwork messages after disabling<br />
this option to ensure there is no artwork cached by the server.<br />
<br />
'''Send artwork from the playing file (if available)''' : This sends artwork from the currently playing song to the server and acts in the same way as the album art view in most media players.<br />
<br />
If unchecked or there is no artwork for the playing song then the<br />
DNAS server may be sent a clear artwork message as applicable.<br />
<br />
This is sent as a PNG image to the SHOUTcast server.<br />
<br />
'''Send artwork for stream branding''' : This will send the image as selected in the box below to the server to act as the station or stream image.<br />
<br />
If left empty then the DNAS server may be sent a clear artwork message as applicable.<br />
<br />
<br />
[[Image:Output_tab_artwork_tab_v1_enabled.png|100px|thumb|right|SHOUTcast Source Output Artwork in v1 (Legacy) mode]]<br />
Using the plug-in with a connection to a legacy server will cause the following notice to be shown:<br />
<br />
Stream is setup for a SHOUTcast v1 server<br />
which does not support in-stream artwork.<br />
<br />
To send in-stream artwork, uncheck the<br />
"SHOUTcast v1 mode" option and ensure<br />
you connect to a SHOUTcast v2 server.'<br />
<br />
<br />
The plug-in is only able to send in-stream artwork upto 511 KiB (523680 bytes) in size due to the SHOUTcast 2 protocol specification for metadata packets. If this limit is reached then the artwork will not be sent and instead the server will get a clear artwork message. This tab page will show if the artwork cannot be used.<br />
<br />
Viewing the in-stream artwork depends on native playback support of SHOUTcast v2 streams in the player used by the client so without a compatible player the client will not be able to view it is as it is not available with SHOUTcast v1 streams.<br />
<br />
<br />
====Logs====<br />
----<br />
<br />
[[Image:Output_tab_logs_tab.png|100px|thumb|right|SHOUTcast Source Output Logs Tab]]<br />
This tab allows you to specify the logging options of the status messages as shown at the top of this page. Additionally it also provides the means to log the filepath of the next tracks (if known) which are going to be played by Winamp with support for logging of the track titles if using the xml output mode.<br />
<br />
The main logging options are not enabled by default though this can be used<br />
for tracking problems with the plug-in e.g. if you are having connection issues.<br />
<br />
<br />
'''Enable logging of connection status messages''' : Enables or disables connection logging.<br />
<br />
'''Clear log file on logging startup''' : This will reset the log everytime the plug-in starts.<br />
<br />
'''Open log file...''' : This will open the log file in the associated program for .log files.<br />
<br />
'''Clear log file''' : This will clear the log file if it exists. It will not remove the file.<br />
<br />
<br />
'''Enable next track logging''' : This will enable creating a log file (based on the following options) of the known next tracks to be played by Winamp.<br />
<br />
'''Save report as xml instead of plain text''' : Changing this will create the log as an xml file containing filepath and title with each item identified by the 'seq' attribute.<br />
<br />
The next track logging is only updated when the plug-in detects a track<br />
change. If the plain text / xml mode is changed or the plug-in starts then<br />
the file contents will be cleared until the next track title change happens.<br />
<br />
<br />
===Input Tab===<br />
----<br />
[[Image:Input_tab_winamp_input.png|100px|thumb|right|SHOUTcast Source Input Tab in Winamp mode]]<br />
<br />
====Input Configuration====<br />
----<br />
<br />
'''Input Device''' : This allows you to choose between using Winamp or your soundcard (usually the line-in) as the input source for the output stream the plug-in makes. Depending upon the selection made additional options will be shown below.<br />
<br />
'''Input Levels''' : These show the current and peak audio level of the left and right channels as is being passed through the plug-ins core. This can aid in seeing if the input source is possibly not working or to check the audio is clipped.<br />
<br />
'''Input Settings''' : When the soundcard input is selected then this allows for control over the sample rate used on the input source.<br />
<br />
<br />
====Soundcard Mixer Control====<br />
----<br />
<br />
[[Image:Input_tab_soundcard_input.png|100px|thumb|right|SHOUTcast Source Input Tab in soundcard mode]]'''Choose Microphone''' : This will allow you to choose any of the input devices reported by the OS for use with the microphone overlay mode the plug-in provides.<br />
<br />
'''Refresh Button''' : This allows you to refresh the capture device list on Vista / Windows 7 (is disabled otherwise) since the plug-in was started. This is useful if you have connected a device to the machine and now want to use it.<br />
<br />
'''Open Mixer''' : This will open the operating systems recording and playback options (when using Windows 2000 / XP) which will allow you to change any required input and output settings for the system (though the amount you can change does depend upon the operating system being used - ([[#Known Issues|see section 4.0]])).<br />
<br />
'''Music Level''' : This controls the Winamp output level (from no audio to full audio level).<br />
<br />
'''BG Level''' : This controls the Winamp output level when the 'Push to Talk' option is active (from no audio to full audio level).<br />
<br />
'''Mic Level''' : This controls the chosen microphone device's output level when the 'Push to Talk' option is active (from no audio to full audio level).<br />
<br />
'''Fade Time''' : This controls the amount of time it takes for the audio to fade from the non 'Push to Talk' mode to 'Push to Talk' being the active mode in usage (from no fade i.e. instantly changes to 2.5 second fade duration).<br />
<br />
'''Capture Device Fade Time''' : This controls the amount of time it takes for the selected capture device to fade from the non 'Push to Talk' mode to 'Push to Talk' being the active mode in usage (from no fade i.e. instantly changes to 2.5 second fade duration).<br />
<br />
'''Push to Talk''' : When this is pressed then the chosen microphone device becomes the active input source as used by any active output streams ([[#Output Tab|see section 3.2]]). When enabled this button will appear in an activated state.<br />
<br />
'''Lock''' : When this is pressed it will toggle the 'Push to Talk' mode on or off depending on the current state of this option when it pressed. When enabled this will appear in an activated state along with the 'Push to Talk' button.<br />
<br />
'''Arrow Button''' : This will show a menu with the option "Enable 'Push to Talk' on startup" allowing for the mode to be re-enabled when the plug-in is started. This may be of use as the plug-in turns off the mode and sets the system levels back to the non-pushed mode when the plug-in's window is closed.<br />
<br />
<br />
===About Tab===<br />
----<br />
<br />
[[Image:About_tab.png|100px|thumb|right|SHOUTcast Source About Tab]]<br />
This tab provides information about the version of the plug-in you are using - useful for determining if you are using an older version of the plug-in or when reporting issues.<br />
<br />
<br />
====Documentation and Support====<br />
----<br />
<br />
This part of the tab provides links to access the available documentation and also for going to the SHOUTcast support forum if issues are being experienced with the plug-in.<br />
<br />
The documentation is either the current version as shipped with the plug-in if selected during install (stored in '''<winampdir>\Plugins\SHOUTcast Source DSP''') or if not found it directs you to an online copy available at http://wiki.winamp.com/wiki/Source_DSP_Plug-in<br />
<br />
The support forum is accessed via http://forums.winamp.com/forumdisplay.php?f=140<br />
<br />
<br />
==Known Issues==<br />
<br />
The following are currently known issue(s) to affect the currently released build of the Source DSP plug-in:<br />
<br />
<br />
===Soundcard Mixer Control===<br />
----<br />
<br />
'''Issue''': The soundcard mixer control does not work correctly or as expected on Vista / Windows 7 especially with the handling of the selected 'microphone' device due to changes in the audio system which prevent the capture handling from Windows 2000 / XP working in the same way. Windows 2000 / XP should still work as expected.<br />
<br />
'''Workaround''': The only obvious work around is to use the features the OS provides to enable the 'Listen to this device' option via the system's recording devices feature and then mix the levels with the controls the OS provides.<br />
<br />
'''Expected Resolution''': This issue is still being investigated and hopefully a solution will be provided to allow for control of the input device in unison with the selected 'microphone' device with-in the plug-ins interface when using this mode.<br />
<br />
<br />
==SHOUTcast 2 Cipher Key==<br />
<br />
If you find that you do need to change the uvoxcipherkey ([[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|DNAS Server - section 4.14]]) or the djcipher ([[SHOUTcast_DNAS_Transcoder_2#DJ_Support|Transcoder - section 3.3]]) in you sc_serv and / or sc_trans setups then you can change the cipher key the DSP uses. You will only need to do this if you get the following status message when making a connection:<br />
<br />
Authentication Error:<br />
Cipher Does Not Match<br />
<br />
This is done currently via editing 'Cipherkey' entry in dsp_sc.ini in your Winamp config folder where you just need to change the string after the equal sign to the value from 'uvoxcipherkey' or 'djcipher' depending upon what you are trying to connect to.<br />
<br />
The dsp_sc.ini file can usually be found by entering '''%appdata%\Winamp\plugins''' into the address bar in Windows Explorer. If it is not there then you should search for '''dsp_sc.ini''' and make sure to have the search program you are using to look for hidden files (this is just incase the OS is hiding the settings folder).<br />
<br />
<br />
==Example Configurations==<br />
<br />
If you are unsure of what to enter to get the Source DSP connected to the official tools, you should look at the [[Source_DSP_Plug-in_Configuration_Examples|Source DSP Plug-in Example Configurations]]. This shows you where to take configuration values from the official tool configuration file(s) and where in the plug-in configuration you need to enter them for the different operating modes available.<br />
<br />
For 3rd party servers or broadcast tools, you may need to consult their documentation to determine where you need to get the required configuration values from.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_DNAS_Transcoder_2SHOUTcast DNAS Transcoder 22014-10-28T23:00:06Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The purpose of this document is to show you the different configuration options supported by sc_trans along with basic and more advanced example configurations enabling you to get started with using sc_trans and the various features it can offer.<br />
<br />
<br />
==Getting Started==<br />
<br />
To get started using sc_trans you need to have some media to play or to have a stream you want to relay via sc_trans. With a 'source' you can use then you will need to setup your configuration file for the transcoder so it can process the input source and provide an output which can be used by the DNAS server (see [[SHOUTcast_DNAS_Server_2|sc_serv2.txt]] in the sc_serv distribution for more details especially those for stream configurations as non-matching details will prevent sc_trans from being able to connect to it).<br />
<br />
The following sections will show how to get sc_trans up and running along with details on the configuration options it provides for handling different sources and outputs it can support.<br />
<br />
<br />
===Running The Transcoder===<br />
----<br />
<br />
The transcoder is able to be run either as a console application or it can be run as service (Windows) or daemon (Linux / Mac OS X / BSD). Detailed below is how to get the transcoder running on the different operating systems supported by it.<br />
<br />
<br />
===Windows===<br />
----<br />
<br />
The Windows version of sc_trans is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.<br />
<br />
Please note that the Windows versions of sc_trans are built with a dependency against the Microsoft Visual C++ 2008 SP1 Redistributable Package. If sc_trans is unable to start due to a dependency issue then you will need to install the correct version of the package so it can run which depends on the version of sc_trans you are attempting to run:<br />
<br />
32-bit version:<br />
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2<br />
<br />
64-bit version:<br />
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e<br />
<br />
<br />
====Install as a Service====<br />
----<br />
<br />
sc_trans.exe install <servicename> <username> <password> <conf><br />
<br />
<servicename> - Name of service<br />
Typically enter this as 'sc_serv' though you can use a different name but you will need<br />
to remember it as it is required to be the same when using the 'uninstall' mode.<br />
<br />
<username> - User under which to run the service as or '0' for the local system<br />
<br />
<password> - Password for user or '0' for the local system or with no password<br />
<br />
<conf> - File path to the configuration file<br />
If no file / an invalid file is specified then sc_trans will abort loading.<br />
<br />
When run as a service there is not a good sense of a current working directory so requires all paths in the configuration and playlist files to be fully qualified otherwise lookups will fail when sc_serv is run.<br />
<br />
To run sc_serv with a configuration file in the same folder as the server as the current system user account you would enter into the console:<br />
<br />
sc_trans.exe install sc_trans 0 0 sc_trans.conf<br />
<br />
<br />
====Uninstall the Service====<br />
----<br />
<br />
sc_trans.exe uninstall <servicename><br />
<br />
<servicename> - Name of service as used when the service was registered<br />
<br />
To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:<br />
<br />
sc_trans.exe uninstall sc_trans<br />
<br />
<br />
====Run as a Non-Service in the Console====<br />
----<br />
<br />
sc_trans.exe <conf><br />
<br />
<conf> - File path to the configuration file (can be relative or absolute)<br />
If no file / an invalid file is specified then sc_trans will abort loading.<br />
<br />
<br />
===Linux / Mac OS X / BSD===<br />
----<br />
<br />
Remember to enable the required access on the sc_trans file by doing 'chmod a+x sc_trans' after extracting it from the distribution file otherwise the OS is likely to not run it and show the error message './sc_trans: Permission denied'.<br />
<br />
====Run as a Daemon====<br />
----<br />
<br />
./sc_trans daemon <conf><br />
<br />
<conf> - File path to the configuration file (required in all cases)<br />
If no file / an invalid file is specified then sc_trans will abort loading.<br />
<br />
'''e.g.'''<br />
./sc_trans daemon ./sc_trans.conf<br />
<br />
When run this should output the following:<br />
<br />
'sc_trans going daemon with PID [XXXX]' where XXXX is the <pid> of the process.<br />
<br />
<br />
====End a Daemon====<br />
----<br />
<br />
kill -SIGTERM <pid><br />
or<br />
kill -15 <pid><br />
or<br />
kill -s TERM <pid><br />
<br />
<pid> - The PID of the daemon instance (reported when the daemon started or can be found with 'ps ax | grep sc_serv' as long as sc_serv was the file run otherwise you can just use 'ps ax' if the filename isn't known). Additionally the PID of sc_trans is listed in the log file.<br />
<br />
<br />
====Run as a Non-Daemon====<br />
----<br />
<br />
./sc_trans <conf><br />
<br />
<conf> - File path to the configuration file (can be relative or absolute)<br />
If no file / an invalid file is specified then sc_trans will abort loading.<br />
<br />
<br />
===Additional Signals===<br />
----<br />
<br />
When run on Linux / Mac OS X / BSD then some additional signals are supported to allow for additional control over the running daemon instance of sc_trans.<br />
<br />
The following signals can be used with the 'kill' command (in the manner of your choosing for using the kill command) along with the <pid> of the daemon instance to do one of the following actions:<br />
<br />
SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)<br />
SIGHUP - Rotates logfile<br />
SIGWINCH - Skips to next song in playlist<br />
SIGUSR1 - Reload playlist<br />
SIGUSR2 - Toggle playlist shuffle<br />
<br />
The result of SIGHUP is that the current log file contents will be moved into <logfile>_1 '''e.g.''' sc_trans_1.log, <logfile>_1 will be moved into <logfile>_2 '''e.g.''' sc_trans_2.log and so on for all log files which can be found which match the current log file's name. This is useful if timed to have it create day specific log files.<br />
<br />
These signals are not supported by the Windows version of sc_trans which will only<br />
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.<br />
<br />
<br />
===Registering for MP3 Stream Encoding===<br />
----<br />
<br />
In order for compliance with all broadcasting laws there is a legal requirement for the need to purchase an MP3 license key in-order to be able to encode your stream in MP3 (see [[#MP3_Encoding|section 3.10]] for the related configuration entries). The license key should cost $5.<br />
<br />
To obtain the license key you need to go to the following page which will takes you to a secure page for purchasing the MP3 encoding license key:<br />
http://shop.winamp.com/servlet/PromoServlet/promoID.48873700<br />
<br />
Once the license key has been obtained (this should be a quick process only taking a few minutes when done) then you just need to add the 'name' and 'key' you have obtained into the 'unlockkeyname' and 'unlockkeycode' values in your configuration file (see [[#MP3_Encoding|section 3.10]]) and to change the 'encoder' type for the stream(s) you require from 'aacp' to 'mp3' to use it (see [[#Encoder_Options|section 3.4]]).<br />
<br />
So if your key is '123456' and you have used 'Bob Cratchit' as the registered name during the billing process, you would add the following to your configuration file:<br />
unlockkeyname=Bob Cratchit<br />
unlockkeycode=123456<br />
<br />
If the details do not exactly match then the Transcoder will show a message and will not allow the encoding of MP3 streams until the configuration issue has been resolved. The common cause for failure is not entering the '''unlockkeyname''' exactly as specified for the billing name of the method used during the purchase.<br />
<br />
<br />
====Why Does AAC Encoding Not Require a License Key?====<br />
----<br />
<br />
Encoding to an AAC stream does also require a license like the MP3 encoding though this has already been paid for you so there is no need for you to do so yourself when using sc_trans. This setup may seem strange but it is just how things happen with the different nature of licensing encoding of the AAC and MP3 formats.<br />
<br />
<br />
===Supported File Formats===<br />
----<br />
<br />
As sc_trans does transcoding of audio from one format to another for then being fed to a server or another sc_trans instance as a relay, the following file extensions are handled as valid input file sources:<br />
<br />
MP3 + MPEG (treated as mp3)<br />
WAV (uncompressed)<br />
OGG<br />
FLAC<br />
<br />
<br />
==Configuration File==<br />
<br />
Here you can find a complete list of all of the configuration options which are provided by sc_trans which ranges from logging to networking configuration to control over how the media is encoded before transmission to the server.<br />
<br />
The entries stored in the configuration file are processed case insensitively.<br />
<br />
Configuration entries labelled as ''<MULTI>'' can be used to set up specific encoder types or for specifying multiple playlists for use with the calendar system. These are specified by adding _# to the end of the option's name as shown below where # begins with one. If you are only working with a single instance then you do not need to add the _# part as<br />
any instances of a configuration option will assume it is for _1.<br />
<br />
<br />
Note: The ''<MULTI>'' system is not hierarchical and all values beyond the default must be specified for all connections. So for example, if you wanted to connect to two servers on the same port you must do:<br />
<br />
encoder_1=aacp<br />
encoder_2=mp3<br />
bitrate_1=32000<br />
bitrate_2=32000<br />
<br />
Note that you CANNOT do it like this as it leads to not all values being set:<br />
<br />
encoder_1=aacp<br />
encoder_2=mp3<br />
bitrate=32000<br />
<br />
The configuration files also allow for notes or options to be disabled by the use of a comma (;) at the start of a line which can be seen in all of the configuration examples.<br />
<br />
Known options in the configuration files are recognised irrespective of the case they are entered in the configuration file so djport and dJpOrT will be handled the same way.<br />
<br />
Any items found in the configuration file which are not known (as detailed in following sections) or is not processed as a comment will be reported in the following manner:<br />
<br />
<date + time> W msg:[CONFIG] Invalid item on line XX<br />
<br />
Where <date + time> is the date and time the event happens at and XX is the line in the configuration file where the error has been found to occur at.<br />
<br />
<br />
===Administration===<br />
----<br />
<br />
'''adminport''' : Specify the port used to access the administrative control page ''[Default = 0]''<br />
If no valid port is specified (i.e. zero) then this feature is disabled.<br />
<br />
'''adminuser''' : Specify the username used to access the administrative control page ''[Default = admin]''<br />
<br />
'''adminpassword''' : Specify the password to access the administrative control page ''[Default = goaway]''<br />
<br />
<br />
===Calendar Events===<br />
----<br />
<br />
'''calendarfile''' : Specify the path to the xml based calendar file ''[Default = calendar.xml]''<br />
<br />
'''calendarrewrite''' : Re-write the 'calendar file' on exit ''[Default = 1]''<br />
<br />
Note: See [[SHOUTcast_Calendar_Event_XML_File_Specification|calendarxml.txt]] for more information on the event format and what it allows you to do with playlist, DJ and relay access.<br />
<br />
<br />
===DJ Support===<br />
----<br />
<br />
'''djport''' : Specify the port to listen on for DJ access using the SHOUTcast 1 protocol ''[Default = 0 (no listening)]''<br />
This will actually open 'djport + 1' as the listening port.<br />
<br />
'''djport2''' : Specify the port to listen on for DJ access using the SHOUTcast 2 protocol ''[Default = 0 (no listening)]''<br />
<br />
Note: It is possible to use 'djport' and 'djport2' at the same time though you need to ensure that there is no overlap of the ports used in what is specified.<br />
<br />
This is because 'djport2' will open the port specified unlike 'djport' which opens 'djport + 1' (as is the way with SHOUTcast 1 connections). Keep this in mind as you would not be able to do the following as it causes a duplication of the port being opened (901 in this case) :<br />
djport=900 ; i.e. will open port 901<br />
djport2=901<br />
Whereas this would work as we are opening two different ports (901 + 902):<br />
djport=900<br />
djport2=902<br />
<br />
'''djcipher''' : Specify the key used to obfuscate the initial handshaking with the SHOUTcast 2 protocol ''[Default = foobar]''<br />
This is a YP2 feature and it matches the 'uvoxcipherkey' value in<br />
the sc_serv configuration file (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).<br />
<br />
Only change this if you really need to do so as not all SHOUTcast 2 clients will allow you to edit this value from the default value. If using the Source DSP plug-in then see [[Source_DSP_Plug-in#SHOUTcast_2_Cipher_Key|dsp_sc.txt - section 5.0]] for details on how to change the plug-in to use a differnet value.<br />
<br />
'''autodumpsourcetime''' : Specify the maximum idle time for the DJ in seconds before being disconnected ''[Default = 30]''<br />
<br />
'''djbroadcasts''' : Specify the directory in which DJ broadcasts will be recorded into ''[Default = recorded\ or recorded/ - relative to sc_trans[.exe] ]''<br />
<br />
'''djcapture''' : Enable to allow the recording of the DJ broadcast ''[Default = 1]''<br />
<br />
'''djfilepattern''' : Specify how the DJ archive filenames will be created in the form of <djname><date time pattern>suffix ''[Default = _%Y_%m_%d_%H_%M_%S. (year_month_day_hour_minute_second)]''<br />
The date and time information are formatted using strftime().<br />
<br />
''<MULTI>'' (one set for each DJ):<br />
<br />
'''djlogin''' : Specify the username required for the DJ to get access [Default = dj]<br />
When connecting as a SHOUTcast 1 source the password has to be specified as <djlogin>:<djpassword> '''e.g.''' dj:noise<br />
<br />
'''djpassword''' : Specify the password required for the DJ to get access ''[Default = noise]''<br />
<br />
'''djpriority''' : Specify the priority for the DJ when multiple DJ's are connected ''[Default = 1]''<br />
<br />
<br />
===Encoder Options===<br />
----<br />
<br />
''<MULTI>'' (one set for each encoder):<br />
<br />
'''encoder''' : Specify the encoder to use, either (mp3 or aacp) ''[Default = aacp]''<br />
<br />
'''bitrate''' : Specify the encoding bitrate in bits per second ''[Default = 96000]''<br />
<br />
'''samplerate''' : Specify the encoding sample rate to use ''[Default = 44100]''<br />
<br />
'''channels''' : Specify the number of channels to encode ''[Default = 2]''<br />
<br />
'''mp3quality''' : Specify the MP3 encoder quality to use when encoding ''[Default = 0]''<br />
Available options are :<br />
0 - fast (preferred)<br />
1 - high quality (changes sample rate and does additional filtering)<br />
<br />
'''mp3mode''' : Specify the MP3 encoder mode (CBR / VBR) to use when encoding ''[Default = 0]''<br />
Available options are :<br />
0 - CBR<br />
1 - VBR High Quality<br />
2 - <br />
3 - VBR Medium Quality <br />
4 - <br />
5 - VBR Low Quality]<br />
<br />
<br />
===Flash Security===<br />
----<br />
<br />
'''flashpolicyfile''' : Specify the name of file which contains the flash crossdomain policies ''[Default = crossdomain.xml]''<br />
<br />
'''flashpolicyserverport''' : Specify the port used for the flash policy server ''[Default = 0]''<br />
Specify '843' if you want to turn this on.<br />
<br />
<br />
===Live Capture===<br />
----<br />
<br />
'''capture''' : Enable to allow the use of live capture as an input ''[Default = 0]''<br />
<br />
'''capturedevice''' : Specify the OS dependent device used for capture ''[Default = <no value>]''<br />
<br />
'''captureinput''' : Specify the OS dependent input used for capture ''[Default = <no value>]''<br />
<br />
'''capturesamplerate''' : Specify the sample rate used for capture ''[Default = 44100]''<br />
<br />
'''capturechannels''' : Specify the number of channels to capture ''[Default = 2]''<br />
<br />
Note: When run under Windows on an operating system newer than XP there is a possibility for the device name obtained from Windows to be longer than 32 characters. This is a problem as the api's used only support device names upto 31 characters in length so sc_trans will attempt to clip the device name specified with 'capturedevice' to 31 characters to try to get a match with the devices the OS is reporting.<br />
<br />
If you are having issues with the live capture then add 'capturedebug=1' to allow you to see the device names reported back to sc_trans by the OS.<br />
<br />
<br />
===Logging Options===<br />
----<br />
<br />
'''log''' : Enable logging of the transmission output ''[Default = 1]''<br />
<br />
'''screenlog''' : Enable logging of output to the console ''[Default = 1]''<br />
If log=0 or when running this as a daemon / service then this option is ignored as it is not applicable.<br />
<br />
'''logfile''' : Specify a different logfile to save the transmission logs into ''[Default = %temp%\sc_trans.log or /tmp/sc_trans.log]''<br />
<br />
If you are using a folder for saving the logs into then you need to ensure that the<br />
folder already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Metadata Control===<br />
----<br />
<br />
'''streamtitle''' : Specify the general name for the radio station or stream ''[Default - Misc]''<br />
<br />
'''streamurl''' : Specify the url of the radio station or stream ''[Default = <nowiki>http://www.shoutcast.com</nowiki>]''<br />
<br />
'''genre''' : Specify the genre for the radio station or stream ''[Default - N/A]''<br />
<br />
'''aim''' : Specify the AIM contact ID to show for the radio station or stream ''[Default - N/A]''<br />
<br />
'''irc''' : Specify the IRC contact ID to show for the radio station or stream ''[Default - N/A]''<br />
<br />
'''icq''' : Specify the ICQ contact ID to show for the radio station or stream ''[Default - N/A]''<br />
<br />
'''public''' : Enable to register the radio station or stream with the YP (shoutcast.com) ''[Default = 0]''<br />
If connected to sc_serv then this is used by the 'publicserver' value<br />
unless it is being overriden (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).<br />
<br />
'''usemetadata''' : Enable to use use the in file metadata i.e. stored in file tags ''[Default = 1]''<br />
<br />
'''metadatapattern''' : Specify the pattern used for extracting metadata from the filename ''[Default = *\%N.* or */%N.*]''<br />
See [[#Filename_Metadata_Extraction|section 6.0]] for more details about this)<br />
<br />
'''displaymetadatapattern''' : Specify a pattern to use to form the metadata output string for SHOUTcast 1 metadata ''[Default = %R[ - ]%N]''<br />
<br />
'''nextlookahead''' : Specifies the number of tracks ahead of the current track playing to be reported in the stream's metadata to the server ''[Default = 3]''<br />
This is the maximum limit attempted to be reported and will vary based on the source in use<br />
e.g. if there enough entries in the current playlist being played. Setting to zero will disable this.<br />
<br />
<br />
===Miscellaneous===<br />
----<br />
<br />
'''configrewrite''' : Re-write the 'config file' on exit ''[Default = 0]''<br />
<br />
'''timemultiplier''' : Used to shift reported time in certain uses ''[Default = 1]''<br />
<br />
'''inheritconfig''': Specify the path of the sc_serv2 configuration file for the instance you want to use the transcoder with ''[Default = <no value>]''<br />
<br />
The aim of this option is to make it easier to get an instance of sc_trans to run with sc_serv by ensuring that any passwords, etc match up. By using this, option any of the configuration options already set in the sc_trans config file (see below) will be replaced by those found in the sc_serv configuration file.<br />
<br />
The configuration options read from the sc_serv2 configuration file including what they are mapped from in the sc_serv2 value to the sc_trans value are:<br />
<br />
* '''portbase -> serverport'''<br />
* '''password -> password''' - Master source password overriden by streampassword<br />
* '''streampassword -> password'''<br />
* '''uvoxcipherkey -> djcipher'''<br />
* '''srcip -> serverip''' - Will use the ip set unless is empty or srcip=any<br />
* '''yp2 -> outprotocol''' - Sets outprotocol=1 if with yp2=0 otherwise it sets outprotocol=3 as a v2 DNAS is assumed to be used and if found to be v1 configuration then outprotocol=1<br />
<br />
Additionally this mode will attempt to read configurations from a v1 DNAS file.<br />
<br />
<br />
'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''<br />
<br />
Note: You can do multiple calls of this allowing for a basic configuration file with then 'specific' encoder configurations set in individual conf files though you need to ensure not to include a reference to the same file in itself.<br />
<br />
'''serverbackupfile''' : Set the server side file for broken connection playback ''[Default = <no value>]''<br />
<br />
'''serverintrofile''' : Set the server side file that is played when a user connects ''[Default = <no value>]''<br />
<br />
Note: With both of these options, they will override any files specified in the sc_serv's configuration file and also requires 'outprotocol=3' for it to be supported (see [[#Network_Options|section 3.11]] for the options 'outprotocol' supports).<br />
<br />
Additionally when connecting to sc_serv via sc_trans, the server intro and backup files as specified in sc_servs configuration file (see [[SHOUTcast_DNAS_Server_2#Introduction_and_Backup_Files|sc_serv2.txt - section 4.5]]) will not be played so you need to specify them in the sc_trans configuration if required for the stream (this is a quirk of how sc_serv currently works).<br />
<br />
<br />
===MP3 Encoding===<br />
----<br />
<br />
'''unlockkeyname''' : Specify the name to use to unlock mp3 encoding (case sensitive)<br />
<br />
'''unlockkeycode''' : Specify the code associated with name to unlock mp3 encoding<br />
<br />
Due to licensing requirements for MP3 encoding see [[#Registering_for_MP3_Stream_Encoding|section 2.5]]<br />
for how to obtain the key required for unlocking MP3 encoding in sc_trans.<br />
<br />
<br />
===Network Options===<br />
----<br />
<br />
''<MULTI>'' (one set for each connection):<br />
<br />
'''endpointname''' : Specify the name of the endpoint ''[Default - <no value>]''<br />
Note: This is used to identify the encoder such as when using the AJAX api interfaces and if not specified then sc_trans creates a default name as 'endpointX' where 'X' is the encoder index starting at one. See [[SHOUTcast_Transcoder_AJAX_api_Specification|sc_trans_ajax_api.txt]] for more information on the use of this.<br />
<br />
'''outprotocol''' : Specify the server protocol to use ''[Default = 1]''<br />
This can be:<br />
1 = SHOUTcast 1 (Legacy)<br />
2 = Ultravox (Ultravox 2.0)<br />
3 = SHOUTcast 2 (Ultravox 2.1)<br />
<br />
'''serverip''' : Specify the IP address of server to connect to ''[Default - <no value>]''<br />
Note: If 'srcip' has been set to a value other than 'any' in the sc_serv configuration then you need to set it for you sc_trans configuration otherwise sc_serv will not see the sc_trans connection attempts (see [[SHOUTcast_DNAS_Server_2#Client_Behaviour|sc_serv2.txt - section 4.2]]).<br />
<br />
Additionally, you will need to make sure that any IP added is valid and can be fully resolved otherwise the connection to the sc_serv instance is very likely to fail.<br />
<br />
'''serverport''' : Specify the server port used to connect to ''[Default = 8000]''<br />
This should relate to the 'portbase' value set in sc_serv's configuration (see [[SHOUTcast_DNAS_Server_2#Networking|sc_serv2.txt - section 4.8]]).<br />
<br />
'''password''' : Specify the password used to connect to a DNAS server ''[Default = foobar]''<br />
This matches the 'password' value in the sc_serv configuration file (see [[SHOUTcast_DNAS_Server_2#Networking|sc_serv2.txt - section 4.8]]) or 'streampassword' (see [[SHOUTcast_DNAS_Server_2#Stream_Configuration|sc_serv2.txt - section 4.12]] - this only applies for v2 DNAS servers).<br />
<br />
'''streamid''' : Specify the stream identifier for the SHOUTcast 2 connection ''[Default = 1]''<br />
This relates to the 'streamid' value in the sc_serv configuration (see [[SHOUTcast_DNAS_Server_2#Networking|sc_serv2.txt - section 4.8]]).<br />
<br />
'''uvoxuserid''' : Specify the user ID for accessing SHOUTcast 2 (Ultravox 2.1) ''[Default - <no value>]''<br />
This is currently not used and is provided for future usage.<br />
<br />
Note: If ''''requirestreamconfigs'''' is enabled in the sc_serv configuration (see [[SHOUTcast_DNAS_Server_2#Stream_Configuration|sc_serv2.txt - section 4.12]]) then you need to ensure that the 'streamid' value used in your sc_trans configuration exists in the sc_serv configuration along with any endpoint, password and other values appropriate to the 'streamid' matched with the equivalent sc_serv configuration values.<br />
<br />
'''uvoxradiometadata''' : Enable to send the older AOL Radio style metadata to the server ''[Default = 0]''<br />
<br />
'''uvoxnewmetadata''' : Enable to send SHOUTcast 2 style metadata to the server ''[Default = 1]''<br />
<br />
'''uvoxmetadatafudgefactor''' : Specify the delaying factor for Ultravox metadata in seconds ''[Default = 0.0]''<br />
<br />
'''shoutcastmetadatafudgefactor''' : Specify the delaying factor for SHOUTcast metadata in seconds ''[Default = 0.0]''<br />
<br />
<br />
===Playlist Control===<br />
----<br />
<br />
'''playlistfile''' : Specify the name of playlist file to use ''[Default = <no value>]''<br />
<br />
'''shuffle''' : Enable to allow shuffling of the specified playlist ''[Default = 1]''<br />
<br />
'''xfade''' : Specify the number of seconds to do for a crossfade ''[Default = 1]''<br />
Specify xfade=0 to disable crossfade<br />
<br />
'''xfadethreshold''' : Specify the minimum duration in seconds a file must be to allow crossfading in and out on it ''[Default = 10]''<br />
<br />
<br />
Priority playlists are those used to override the playing playlist once the current song has stopped playing. This can be useful if a sudden playlist / announcement is required.<br />
<br />
'''playlists''' : Specify the folder used for priority playlists ''[Default = priority\ or priority/ - relative to sc_trans[.exe]]''<br />
<br />
'''archive''' : Specify the folder used for archiving playlists ''[Default = priority\archived\ or priority/archived/ - relative to sc_trans[.exe]]''<br />
<br />
''<MULTI>'' (one set for each additional playlist):<br />
<br />
'''playlistfilename''' - Used to build named collections of playlists ''[Default = <no value>]''<br />
<br />
'''playlistfilepath''' - Used to build named collections of playlists ''[Default = <no value>]''<br />
<br />
Note: These playlists are used as part of the <playlist> events in calendar.xml where the name set with 'playlistfilename_X' is used in the loading done. See [[SHOUTcast_Calendar_Event_XML_File_Specification#Playlist_Events|calendarxml.txt and section 3.2]] for more information on these events.<br />
<br />
<br />
===Replay Gain Control===<br />
----<br />
<br />
'''applyreplaygain''' : Enable to honour the replay gain values stored in the file ''[Default = 0]''<br />
<br />
'''defaultreplaygain''' : If no replay gain is in the file then apply this adjustment ''[Default = 0.0]''<br />
<br />
'''djreplaygain''' : Specify the replay gain to be applied to DJ streams ''[Default = 0.0]''<br />
<br />
'''capturereplaygain''' : Specify the replay gain to apply to the live capture input ''[Default = 0.0]''<br />
<br />
'''calculatereplaygain''' : Enable to calculate the replay gain on the handled files ''[Default = 0]''<br />
<br />
'''replaygaintmpdir''' : Specify the temporary directory for replay gain calculator to work in ''[Default = (Windows = %TEMP FOLDER% Linux = /tmp/)]''<br />
<br />
'''replaygainrunahead''' : Specify the number of tracks head start to give the replay gain calculator ''[Default = 2]''<br />
<br />
'''replaygaindontwrite''' : Specify if the replay gain values calculated should NOT be written to the file ''[Default = 0]''<br />
<br />
'''enhancereplaygain''' : Specify if the file has replay gain and it is being used, an additional amount of gain to add ''[Default = 6.0]''<br />
Winamp ships with a default value to add -6dB to file which do not have replay gain.<br />
<br />
<br />
===VU Image===<br />
----<br />
<br />
'''vuimagedirectory''' : Specify the folder in which to look for vu images to use ''[Default = ""]''<br />
The image files are named vuimage_XX.<vuimagesuffix> where 'XX' is from 0 to 100<br />
and the path specified will need to be properly terminated to work correctly.<br />
<br />
'''vuimagesuffix''' : Specify the suffix for vu images to be used from the image directory ''[Default = png]''<br />
<br />
'''vuimagemimetype''' : Specify the mime type for vu images to be used ''[Default = image/png]''<br />
<br />
Note: This controls the images available when using the 'vumeterleft' or 'vumeterright' webcommands (see [[#Supported_Weblet_Commands|section 4.1]]). Additionally sc_trans only allows for one active use of each webcommand from the current sc_trans instance with the most current attempt made being the active instance which will be updated.<br />
<br />
<br />
===Debugging===<br />
----<br />
<br />
In all cases, the default value is for no debug logging for the options listed below.<br />
<br />
'''shuffledebug''' : Enable to activate debug logging of playlist shuffling ''[Default = 0]''<br />
<br />
'''shoutcastdebug''' : Enable to activate debug logging for SHOUTcast transmission ''[Default = 0]''<br />
<br />
'''uvoxdebug''' : Enable to activate debug logging for SHOUTcast 2 (Ultravox 2.1) transmissions ''[Default = 0]''<br />
<br />
'''gaindebug''' : Enable to activate debug logging for replay gain on playback ''[Default = 0]''<br />
<br />
'''playlistdebug''' : Enable to activate debug logging for playlists ''[Default = 0]''<br />
<br />
'''mp3encdebug''' : Enable to activate debug logging for MP3 encoding ''[Default = 0]''<br />
<br />
'''mp3decdebug''' : Enable to activate debug logging for MP3 decoder ''[Default = 0]''<br />
<br />
'''resamplerdebug''' : Enable to activate debug logging for the resampler ''[Default = 0]''<br />
<br />
'''rgcalcdebug''' : Enable to activate debug logging for the replay gain calculator ''[Default = 0]''<br />
<br />
'''apidebug''' : Enable to activate debug logging for the AJAX api ''[Default = 0]''<br />
<br />
'''calendardebug''' : Enable to activate debug logging for the calendar events ''[Default = 0]''<br />
<br />
'''capturedebug''' : Enable to activate debug logging for live capture ''[Default = 0]''<br />
<br />
'''djdebug''' : Enable to activate debug logging for DJ management ''[Default = 0]''<br />
<br />
'''flashpolicyserverdebug''' : Enable to activate debug logging for the flash policy server ''[Default = 0]''<br />
<br />
'''fileconverterdebug''' : Enable to activate debug logging for the server side file converter ''[Default = 0]''<br />
<br />
'''sourcerelaydebug''' : Enable to active debug logging for relayed sources ''[Default = 0]''<br />
<br />
'''sourceandendpointmanagerdebug''' : Enable to activate debug logging for endpoint management ''[Default = 0]''<br />
<br />
<br />
==Administration Weblet Commands==<br />
<br />
The transcoder supports web based control of the features it provides allowing for the remote control of sc_trans much like the DNAS (sc_serv2) supports. To enable the use of the administration interface you need to specify a port and related password and username as detailed in the Administration section ([[#Administration|see 3.1]]).<br />
<br />
Once enabled then options detailed in the following sections will become available though the main interface and controlling aspects are available via the 'api' command with more information provided on how to use it in [[SHOUTcast_Transcoder_AJAX_api_Specification|sc_trans_ajax_api.txt]].<br />
<br />
<br />
===Supported Weblet Commands===<br />
----<br />
<br />
The following are the supported commands for the administration weblet the transcoder supports and are used in the following manner:<br />
<nowiki>http://<server_ip>:adminport/<command></nowiki><br />
<br />
'''quit''' : Will make sc_trans quit (equivalent of SIGKILL on non-Windows).<br />
<br />
'''rotatelogs''' : Will rotate the logs (equivalent of SIGHUP).<br />
The result of this is that the current log file contents will be moved into <logfile>_1 '''e.g.''' sc_trans_1.log, <logfile>_1 will be moved into <logfile>_2 '''e.g.''' sc_trans_2.log and so on for all log files which can be found which match the current log file's name. This is useful if timed to have it create day specific log files.<br />
<br />
'''nextsong''' : Will advance to the next song (equivalent of SIGWINCH).<br />
<br />
'''loadplaylist''' : This will re-load the current playlist (equivalent of SIGUSR1).<br />
<br />
'''toggleshuffle''' : Use to toggle the current playlist shuffle state (equivalent of SIGUSR2).<br />
<br />
'''kickdj?duration=hh:mm:ss''' : You can specify an amount of time for how long to kick the current DJ for. If a duration is not set i.e. just using 'kickdj', then this will defaults to 15 minutes (00:15:00). If a duration is specified then all three fields of 'hh:mm:ss' must be specified even if their value is zero (ie 01:30:30).<br />
<br />
'''restart''' : Restart the current sc_trans instance.<br />
<br />
'''vumeterleft''' or '''vumeterright''' : This will initiate a server side image push that represents the vu levels as long as there are images are available to sc_trans to use for this (see [[#VU_Image|section 3.14]]).<br />
<br />
'''vu.bin''' : This will return a continuous stream of type 'misc/sc-vu' as long as sc_trans is transcoding. The format of the stream is:<br />
0xa5 leftVal rightVal 0xa5 leftVal ..... etc<br />
<br />
If the audio signal is mono there is no right val and you get:<br />
0xa5 leftVal 0xa5 leftVal .... etc<br />
<br />
'''writeconfig''' : This will write out the currently stored configuration and event details to the respective configuration and calendar.xml file. You will need to ensure that you have specified valid files in the configuration options for these files otherwise they won't be saved correctly and any changes may be lost.<br />
<br />
'''crossdomain.xml''' : This will return the current copy of crossdomain.xml as set with 'flashPolicyFile' ([[#Flash_Security|see section 3.5]]).<br />
<br />
'''timeshift?t=#''' : [EXPERIMENTAL] This applies a time shift to the audio though the default is to have no shift (i.e. t=0). This should not be used unless you know what it does (added for specific Aol use).<br />
<br />
'''api''' : This is the point from where you can make use of the AJAX api which sc_trans offers and is used as a POST method. For more information on the parameters and options supported see [[SHOUTcast_Transcoder_AJAX_api_Specification|sc_trans_ajax_api.txt]].<br />
<br />
<br />
==Metadata Support==<br />
<br />
As detailed in [[#Metadata_Control|section 3.8]] there are a number of ways to allow for the use of metadata from the files being played though there are certain limits to this support for different file formats currently supported by sc_trans as detailed in the following sections.<br />
<br />
<br />
===MP3 Files===<br />
----<br />
<br />
There is support for ID3v1 and ID3v2 tags. With ID3v2 there is support of version 3 and 4 of the specification though there are the following limitations:<br />
# Unsynch data is not supported<br />
# Compressed frames are not supported<br />
# Encrypted frames are not supported<br />
# Appended v4 frames are not supported<br />
<br />
<br />
===FLAC and OGG Files===<br />
----<br />
<br />
There is support of the native metadata (Vorbis comment tags). Metadata read from these files are mapped to expected values which SHOUTcast expects to get. For more information see [[SHOUTcast_XML_Metadata_Specification|sc2_xml_metadata.txt]] for details on the various field mappings applied.<br />
<br />
<br />
==Filename Metadata Extraction==<br />
<br />
The transcoder along with being able to make use of the metadata from files is also able to attempt to extract metadata from the filepath of the files by use of a template.<br />
<br />
Guessing of the metadata from the filename will happen if 'usemetadata=0' is set in your configuration file (default behaviour is to use the file tag) or if no tag is detected in the file. For the best experience it is always best to ensure any files you use have tags and the required metadata in them.<br />
<br />
<br />
===Filename Metadata Extraction Pattern===<br />
----<br />
<br />
The 'metadataPattern' setting is used to specify the pattern used to extract metadata from a filename if there is no detected metadata or 'usemetadata=0'.<br />
<br />
The default pattern used is *\%N.* (Windows) and */%N.* (all other OSes). The following are the formatting options which are supported in the pattern:<br />
%N = Song name<br />
%G = Genre<br />
%A = Album<br />
%R = Artist<br />
%Y = Four digit year<br />
%# = Sequence of digits<br />
%% = % character<br />
[] = Brackets optional elements (no nesting)<br />
* = String<br />
Other characters are matched exactly as found.<br />
<br />
The pattern matching is done working from the right to the left.<br />
<br />
<br />
===Filename Metadata Extraction Examples===<br />
----<br />
<br />
The following examples show the metadata pattern matching working.<br />
<br />
<br />
====Example #1====<br />
----<br />
<br />
metadataPattern = */%R/%Y%A/Audio/[%#_]%N.*<br />
filepath = /home/songs/Mask and Wig/1969 Irreverance Of Things Past/Audio/03_The Royal Blues.mp3<br />
<br />
Extracted metadata result:<br />
ALBUM = Irreverance Of Things Past<br />
ARTIST = Mask and Wig<br />
SONG = The Royal Blues<br />
YEAR = 1969<br />
<br />
<br />
====Example #2====<br />
----<br />
<br />
metadatapattern = */%A/[%R_]%N<br />
filepath = /home/album/song<br />
<br />
Extracted metadata result:<br />
ALBUM = album<br />
SONG = song<br />
<br />
<br />
====6.2.3 Example #3====<br />
----<br />
<br />
metadatapattern = */%A/%R_%N<br />
filepath = /home/album/artist_song<br />
<br />
Extracted metadata result:<br />
ALBUM = album<br />
ARTIST = artist<br />
SONG = song<br />
<br />
<br />
===File Metadata Construction For SHOUTcast 1===<br />
----<br />
<br />
You can specify how metadata elements are concatenated together to from the SHOUTcast 1 metadata string by specifying the 'displaymetadatapattern' option.<br />
<br />
In a standard Winamp client install then it will expect the data in the equivalent format of '%R[ - ]%A[ - ]%N' and uses that format to parse the data. If you deviate from this or if the user has changed settings in their Winamp client then the results may not display properly with what is expected to be shown.<br />
<br />
The following token substitutions are made with 'displaymetadatapattern':<br />
<br />
%N = Song name<br />
%A = Album name<br />
%R = Artist<br />
%G = Song genre<br />
%Y = song year<br />
%t = Station name (a.k.a. stream title a.k.a. icy-name)<br />
%u = Station url (a.k.a. icy-url)<br />
%g = Station genre (a.k.a. icy-genre)<br />
<br />
Characters in brackets are only displayed if the token substitution to the left of them did not result in the insertion of an empty string.<br />
<br />
<br />
==Playlists Support==<br />
<br />
The transcoder supports a playlist file to specify the file(s) to use when it is working and is a file with the .lst extension with one file per line. The file may be encoded in UTF-8 to allow for the support of non-english filenames, etc.<br />
<br />
Lines in the playlist beginning with a # will be ignored which allows you to disable a specific file or script in the playlist or comments on what is done.<br />
<br />
The playlist file will be processed until the end of the file is reached or until the parser comes across a line containing ###!EOF is detected.<br />
<br />
With versions of sc_trans prior to those from the end of 2010 there was a need to have a line break after the last entry in the playlist for them to be correctly recognised. This is no longer a requirement of the playlist format.<br />
<br />
Wildcards are supported in the processing of the folder contents though this will not do a recursion of any sub-folders within the specified folder '''e.g.''' c:\music\*.mp3<br />
<br />
This will only find mp3 files in the 'music' folder and will not look in any sub-folders which may be inside the 'music' folder. For sub-folders to be included then you will need to explicitly specify the sub-folder for it to be recognised by the playlist loader.<br />
<br />
Additionally these entries can be intermixed with regular explicit entries '''e.g.'''<br />
c:\music\foo.mp3<br />
c:\music\otherstuff\*.mp3<br />
c:\music\bar.mp3<br />
<br />
Any entries which relate to file formats not supported (determined by the file extension) will be ignored from the playlist stored e.g. test.aac would not be used if read.<br />
<br />
<br />
===Supported Playlist Formats===<br />
----<br />
<br />
The transcoder supports the following playlist file formats though is limited to use only the filepaths from the playlist formats which also provide additional title / metadata information in them:<br />
<br />
Plain text file - this is the equivalent of a commentless M3U / M3U8 file<br />
PLS<br />
M3U<br />
M3U8 (UTF-8 encoded version of the M3U format)<br />
<br />
If a loaded playlist contains any entries with wildcards in them then the playlist loader will only attempt to find the matching files in the base folder specified and will not recurse into any sub-folders found. This is different to how Winamp for example (and any other programs) handles the loading of such entries where it would then recurse through any sub-folders found. This behaviour may change at a future time but is not guaranteed.<br />
<br />
<br />
===Remote Applications===<br />
----<br />
<br />
An additional feature of the transcoders playlist support is the ability to run remote applications in place of a fixed playlist line. This is done by starting a line with #! '''e.g.'''<br />
/music/foo.mp3<br />
#!/bin/perl /home/user/songfromDB.pl<br />
/music/bar.mp3<br />
<br />
The script run in this case should return the entry in the playlist to run at this point. The script is also passed an integer parameter indicating how many tracks ahead must also be returned by the script.<br />
<br />
By returning these extra tracks as well as the first one expected then this information will be used by YP2 to refine searching and also to establish a "coming soon" track which will be shown to clients or on the SHOUTcast site.<br />
<br />
So with this style of playlist handling, it is possible to have an external app running which will provide all of the files for sc_trans to process which could be of use if you have a specific requirement for when and how files are played.<br />
<br />
Additionally you can pair remote application actions together in such a manner:<br />
#!php call track script<br />
#!php call commercial script<br />
<br />
where this will alternate between the first and second scripts returning the file to be processed through sc_trans.<br />
<br />
<br />
===Additional Information===<br />
----<br />
<br />
Every entry in the playlist is run through a wildcard expander specific to the operating system the transcoder is being run on. Under *nix systems then glob() is used and for Windows systems FindFirstFile() is used to handle the wildcard.<br />
<br />
There are a number of scenarios to be considered for remote application entries in a playlist as detailed in the following list:<br />
<br />
# The standard out from the command is used as the name of the file to open.<br />
# If the standard out is empty then the entry will be skipped.<br />
# If the command returns an error code (non zero) then the entire playlist of which the entry is a member off will be considered to be finished.<br />
# The data written to standard out should be encoded in the UTF-8 format and if returning multiple entries needs to be separated by a newline character.<br />
# If only a single track name is returned by the remote application then the following values in the playlist will be used for "coming soon" calculations.<br />
# If you return the requested number of additional tracks (passed in when it is run) then these will be used for "coming soon" calculations.<br />
# If there are [ or ] in the filepath then for them to appear instead of being used as a filter, you will need to escape them normally as \[ and \] else it is often likely that the files will fail to load. This is more of an issue on non-Windows versions due to how the shell and expansion works.<br />
<br />
<br />
==DJing Information==<br />
<br />
The DJ port (configuration option 'djport' or 'djport2') mimics the behaviour of sc_serv by allowing someone running another copy of sc_trans (or the Winamp DSP plug-in) to connect to your sc_trans and then to broadcast through it which effectively turns your sc_trans into a relay.<br />
<br />
The 'djport' or 'djport2' value (see [[#DJ_Support|section 3.3]] for more details setting this up) is the IP port you choose to have your sc_trans to listen on for an inbound DJ connection (by default this feature is not enabled).<br />
<br />
A simple example of this feature is if you have a friend who wants to do a show on your station. At the appropriate time they would start their own instance of sc_trans which will then connect to your instance as if it was a server. When the connection happens then your sc_trans instance will stop the current playlist playback and will crossfade into your friends show. Then when the show is over and the friend disconnects then your instance of sc_trans will crossfade back into the playlist from the point when the friend had connected.<br />
<br />
The DJ broadcast will also be copied to disk for later playback assuming that 'djcapture' has not been changed from the default settings though you can turn this feature off if required. See [[#DJ_Support|section 3.3]] for more available options.<br />
<br />
<br />
===Setting Up DJs In The New Scheme===<br />
----<br />
<br />
DJ accounts are set up by using the 'djlogin', 'djpassword' and 'djpriority' options as shown in <MULTI> options under [[#DJ_Support|section 3.3]].<br />
<br />
If we have two DJs who we want to allow access into our system then we would have the following in our main configuration file (obviously in real use change the names and passwords to what you need):<br />
<br />
djlogin_1=peter<br />
djpassword_1=foobar<br />
djpriority_1=4<br />
<br />
djlogin_2=paul<br />
djpassword_2=goaway <br />
djpriority_2=2<br />
<br />
The priority value is used if the scheduling allows for two different DJs to connect into the instance of sc_trans at the same time. If this did happen then the DJ with the higher priority will take precedence on the access made.<br />
<br />
Now that we have setup the DJs in our main configuration, we will need to setup access for them via the calendar.xml file scheduler ([[SHOUTcast_Calendar_Event_XML_File_Specification|see calendarxml.txt]]). In this example Peter is allowed access to sc_trans at any time whereas Paul is only allowed a connection to sc_trans on Tuesdays at 2am for an hour. Finally the shows Peter makes will not be saved whilst Paul's ones will be archived.<br />
<br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<eventlist><br />
<event type="dj"><br />
<dj archive="0">peter</dj><br />
<calendar/><br />
</event><br />
<event type="dj"><br />
<dj archive="1">paul</dj><br />
<calendar starttime="02:00:00" duration="01:00:00" repeat="4"/><br />
</event><br />
</eventlist><br />
<br />
Now everything is setup, all that is needed is to run sc_trans and for Peter and Paul to setup their setups (either via another sc_trans or Winamp + Source DSP for example) with the required login details and then they will be able to connect as set in the schedule.<br />
<br />
Note: When connecting as a SHOUTcast 1 source, the DJ must specify the login password in the form of <djlogin>:<djpassword> '''e.g.''' paul:goaway If not done correctly then the DJ will not be able to connect. [[#DJ_Support|Section 3.3]] provides more information on the configuration values required.<br />
<br />
<br />
==Virtual Memory Footprint (Linux / Mac OS X / BSD)==<br />
<br />
Due to how sc_trans works it will create a large number of threads which may become an issue due to the default virtual memory stack allocation per thread potentially being large (typically 10MB per thread). For most people this should not be an issue as the memory is not really allocated unless it is used. If however if you have a resource constrained system or if you plan on running many copies of sc_trans then you could potentially run out of virtual memory.<br />
<br />
The default thread allocation can be reduced by issuing a "ulimit" command before running sc_trans and in the example reduces it to 512KB per-thread '''e.g.''' ulimit -s 512<br />
<br />
<br />
==Locale Error (Linux / Mac OS X / BSD)==<br />
<br />
If you receive the following error then you have a locale related issues:<br />
<br />
terminate called after throwing an instance of 'std::runtime_error'<br />
what(): locale::facet::_S_create_c_locale name not valid<br />
Abort trap<br />
<br />
If this happens then you need to set the 'POSIX' locale in your terminal's environment values. If this does not happen then everything is fine or you are using a newer version of sc_trans from the end of 2010 which should no longer exhibit this issue.<br />
<br />
Linux:<br />
export LC_ALL=POSIX<br />
<br />
BSD:<br />
setenv LC_ALL POSIX<br />
<br />
Mac OS X:<br />
export LC_ALL=POSIX<br />
<br />
You can test to see if this has worked by checking the shell command "locale":<br />
<br />
LANG=<br />
LC_COLLATE="POSIX"<br />
LC_CTYPE="POSIX"<br />
LC_MESSAGES="POSIX"<br />
LC_MONETARY="POSIX"<br />
LC_NUMERIC="POSIX"<br />
LC_TIME="POSIX"<br />
LC_ALL="POSIX"<br />
<br />
<br />
==Example Configurations==<br />
<br />
Include as part of the sc_serv installation are a number of example configurations to get things started with using some of the features of the transcoder. The provided examples are:<br />
<br />
sc_trans_basic.conf<br />
sc_trans_capture.conf<br />
sc_trans_dj.conf<br />
sc_trans_playlist.conf<br />
sc_trans_simple.conf<br />
<br />
All of the configuration examples are documented and will relate back to details in this file as appropriate. You will need to change some details in these example files or to obtain any applicable license keys for the setup you are making (see [[#Registering_for_MP3_Stream_Encoding|section 2.5]]).<br />
<br />
In all cases the examples are designed to work from the same install folder as sc_trans. <br />
<br />
Remember these examples are a way to get you up and running faster though you are still likely to have to adjust things depending upon the systems you are using and how you want to manage your sources and server connections which are covered in previous sections.<br />
<br />
Additionally if you are not happy with editing the files or find it still too confusing then you can use the configuration builder which (if installed) can be found in the 'config_builder'. Open 'config_builder.html' in your browser and then use this graphical tool to setup a configuration file for the transcoder (and additionally the server).<br />
<br />
<br />
===sc_trans_basic===<br />
----<br />
<br />
This is the base configuration from which the other configuration examples are based and this will get a sc_trans instance running and making a connection to a local instance of sc_serv (see [[SHOUTcast_DNAS_Server_2#sc_serv_basic|sc_serv2.txt - section 9.1]] about the sc_serv_basic configuration file).<br />
<br />
<br />
===sc_trans_capture===<br />
----<br />
<br />
This configuration file changes the required options in the sc_trans_basic configuration to get a sc_trans instance running as a capture device '''e.g.''' from a microphone. This shows the use of the 'include' option ([[#Miscellaneous|see section 3.9]]).<br />
<br />
<br />
===sc_trans_dj===<br />
----<br />
<br />
This configuration file changes the required options in the sc_trans_basic configuration to get a sc_trans instance running with the ability to accept DJ connections using both a SHOUTcast 2 source and a legacy SHOUTcast 1 source in addition to how calendar.xml files are used to control DJ access.<br />
<br />
<br />
===sc_trans_playlist===<br />
----<br />
<br />
This configuration file changes the required options in the sc_trans_basic configuration to get a sc_trans instance running with the ability to schedule a jingle to play around 20 minutes and 40 minutes past the hour as well as to schedule a different playlists to be played in the evening and also on the weekend. This example shows of some of the features of the event system and how it is possible to automate playlist changes.<br />
<br />
<br />
===sc_trans_debug===<br />
----<br />
<br />
This configuration file can be included in any other configuration files to allow you to get debug logging output when trying to investigate any issues you may be experiencing.<br />
<br />
<br />
===sc_trans_simple===<br />
----<br />
<br />
Use this if you just need to get a very basic transcoder running or are impatient<br />
or are struggling to get it running despite the previous example configurations.<br />
<br />
This configuration file is designed to be used just as is and is the simplest form of the configuration file you can have which will allow you to get a running transcoder to work with an instance of the server on the same machine.<br />
<br />
This works by assuming default settings of the transcoder and that the server has been properly configured to work as this configuration uses the 'inheritconfig' option to get some of the passwords and other configuration details directly needed for the transcoder to work with the server instance by using sc_serv_simple.conf (see [[SHOUTcast_DNAS_Server_2#sc_serv_simple|sc_serv2.txt - section 9.5]]) or change this to reference a known server configuration you want to use this with.<br />
<br />
All you need to do when using this configuration file is to:<br />
<br />
* Edit the playlist file to be used (as referenced in the playlistfile entry)<br />
* Setup the required encoder options including entering the MP3 unlock code by filling in 'unlockkeyname' and 'unlockkeycode' entries if using MP3 decoding ([[#Registering_for_MP3_Stream_Encoding|section 2.5]] has details on why this is required and how to obtain the unlock key and code)<br />
* Change the stream information details as appropriate</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_DNAS_Server_2SHOUTcast DNAS Server 22014-10-28T22:59:45Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The purpose of this document is to show you the different configuration options supported by sc_serv along with basic and more advanced example configurations to enable you to get started with using sc_serv and the features it can offer.<br />
<br />
The aim of sc_serv is to provide enhanced serving features and also access to the new YP2 infrastructure whilst maintaining as much backward compatibility with previous versions of sc_serv as possible. The new features introduced include:<br />
<br />
# Serving multiple streams from a single server instance<br />
# Relaying multiple streams from a single server instance<br />
# Multiplexing all server activity through a single IP port<br />
# SHOUTcast 2 wire protocol support for sources, relays and clients<br />
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients<br />
# YP2 infrastructure support<br />
# Real-time metadata and statistic reporting<br />
# Static station id support<br />
# In-stream metadata in standardised xml files<br />
# UTF-8 and international character encoding<br />
# Improved server and stream security<br />
<br />
<br />
==Overview of Features==<br />
<br />
To take full advantage of the newer features provided as part of the SHOUTcast 2 and YP2 systems then you will need to ensure you are using a compatible version of sc_serv (any version 2 will work) and that you have the required authorisation key to register as a broadcaster on the YP2 directory (see [[#Getting_Started|section 3.0]]).<br />
<br />
If you were intending on taking full advantage of the multiplexing and multiple stream support offered as part of sc_serv then you would need to make sure you enable the SHOUTcast 2 options (this is enabled by default with server builds from the end of 2010 if the 'yp2' option in the configuration file is not specified [see [[#YP_Server_Behaviour|section 4.14]] ). The reason for needing to enable this support is if you try to do it with the original SHOUTcast 1 protocol then it will not work as the original protocol has no means of expressing multiple streams from a single port due to the lack of an identifier provided for them.<br />
<br />
If you are planning on connecting multiple sc_trans instances to sc_serv then you must use the SHOUTcast 2 protocol support so that each sc_trans instance can have a unique identifier which allows for multiple streams to then be provided from a single server. It is still possible for an older source to connect to the server with a number of config options available to support this though functionality will be limited compared to what can be done with a fully supporting SHOUTcast 2 source.<br />
<br />
Finally clients connecting to your server do not need to directly support SHOUTcast 2 as sc_serv will repackage the stream data and any related metadata into the correct format the client requests (typically based on the user agent detected by the server).<br />
<br />
<br />
==Getting Started==<br />
<br />
One of the key aspects of the new YP2 directory infrastructure is an authorisation key which is used to validate your server when it tries to connect to the YP2 infrastructure for any of the station(s) you run. Once this key is obtained, it will be valid for all root servers of the station being broadcast.<br />
<br />
This can be done by going to the [[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]] page which shows how to do this via the 'Administation Summary' page as long as a valid source has been connected to the server. This process automatically updates your configuration file(s) with the new authhash and if the stream is set to be public then will attempt to get the stream listed in the SHOUTcast Radio Directory.<br />
<br />
When using an older SHOUTcast 1 server then you do not need to do this registration and the server will still be able to be listed on the directory but there is not the same level of protection over the stream as is the case with registering it.<br />
<br />
<br />
===Running the Server===<br />
----<br />
<br />
The server is able to be run either as a console application or it can be run as service (Windows) or daemon (Linux / Mac OS X / BSD). Detailed below is how to get the server running on the different operating systems supported by it.<br />
<br />
<br />
===Windows===<br />
----<br />
<br />
The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.<br />
<br />
Please note that the Windows versions of sc_serv are built with a dependency against the Microsoft Visual C++ 2008 SP1 Redistributable Package. If sc_serv is unable to start due to a dependency issue then you will need to install the correct version of the package so it can run which depends on the version of sc_serv you are attempting to run:<br />
<br />
32-bit version:<br />
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2<br />
<br />
64-bit version:<br />
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e<br />
<br />
<br />
====Install as a Service====<br />
----<br />
<br />
sc_serv.exe install <servicename> <username> <password> <conf><br />
<br />
<servicename> - Name of service<br />
Typically enter this as 'sc_serv' though you can use a different name but you will need<br />
to remember it as it is required to be the same when using the 'uninstall' mode.<br />
<br />
<username> - User under which to run the service as or '0' for the local system<br />
<br />
<password> - Password for user or '0' for the local system or with no password<br />
<br />
<conf> - File path to the configuration file<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
When run as a service there is not a good sense of a current working directory so requires all paths in the configuration and playlist files to be fully qualified otherwise lookups will fail when sc_serv is run.<br />
<br />
To run sc_serv with a configuration file in the same folder as the server as the current system user account you would enter into the console:<br />
<br />
sc_serv.exe install sc_serv 0 0 sc_serv.conf<br />
<br />
<br />
====Uninstall the Service====<br />
----<br />
<br />
sc_serv.exe uninstall <servicename><br />
<br />
<servicename> - Name of service as used when the service was registered<br />
<br />
To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:<br />
<br />
sc_serv.exe uninstall sc_serv<br />
<br />
<br />
====Run as a Non-Service in the Console====<br />
----<br />
<br />
sc_serv.exe <conf><br />
<br />
<conf> - File path to the configuration file (can be relative or absolute)<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
<br />
===Linux / Mac OS X / BSD===<br />
----<br />
<br />
Remember to enable the required access on the sc_trans file by doing 'chmod a+x sc_trans' after extracting it from the distribution file otherwise the OS is likely to not run it and show the error message './sc_serv: Permission denied'.<br />
<br />
====Run as a Daemon====<br />
----<br />
<br />
./sc_serv daemon <conf><br />
<br />
<conf> - File path to the configuration file (required in all cases)<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
'''e.g.'''<br />
./sc_serv daemon ./sc_serv.conf<br />
<br />
When run this should output the following:<br />
<br />
'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.<br />
<br />
<br />
====End a Daemon====<br />
----<br />
<br />
kill -SIGTERM <pid><br />
or<br />
kill -15 <pid><br />
or<br />
kill -s TERM <pid><br />
<br />
<pid> - The PID of the daemon instance (reported when the daemon started or can be found with 'ps ax | grep sc_serv' as long as sc_serv was the file run otherwise you can just use 'ps ax' if the filename isn't known). Additionally the PID of sc_serv is listed in the log file.<br />
<br />
<br />
====Run as a Non-Daemon====<br />
----<br />
<br />
./sc_serv <conf><br />
<br />
<conf> - File path to the configuration file (can be relative or absolute)<br />
If no file / an invalid file is specified then sc_serv will abort loading.<br />
<br />
<br />
===Additional Signals===<br />
----<br />
<br />
When run on Linux / Mac OS X / BSD then some additional signals are supported to allow for additional control over the running daemon instance of sc_serv.<br />
<br />
The following signals can be used with the 'kill' command (in the manner of your choosing for using the kill command) along with the <pid> of the daemon instance to do one of the following actions:<br />
<br />
SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)<br />
SIGHUP - Rotates logfile, w3clog and streamw3clog<br />
<br />
The result of SIGHUP is that the current log file contents will be moved into <logfile>_1 e.g. sc_serv_1.log, <logfile>_1 will be moved into <logfile>_2 e.g. sc_serv_2.log and so on for all log files which can be found which match the current log file's name. This is useful if timed to have it create day specific log files.<br />
<br />
These signals are not supported by the Windows version of sc_serv which will only<br />
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.<br />
<br />
<br />
==Configuration File==<br />
<br />
Here you can find a complete list of all of the configuration options which are provided by sc_serv which ranges from logging to networking configuration and control over the media being used when streaming via the server.<br />
<br />
Configuration entries labelled as ''<MULTI>'' can be used to set up simultaneous connections to the server or allow for multiple connections from various sources. These are specified by adding _# to the end of the option's name as shown below where # begins with one. If you are only working with a single instance then you do not need to add the _# part as any instances of a configuration option will assume it is for _1.<br />
<br />
Note: The ''<MULTI>'' system is not hierarchical and all values beyond the default must be specified for all connections. So for example, if you wanted to connect to two servers on the same port you must do:<br />
<br />
serverport_1=8080<br />
serverport_2=8080<br />
serverip_1=www.server1.com<br />
serverip_2=www.server2.com<br />
<br />
Note that you CANNOT do it like this as it leads to not all values being set:<br />
<br />
serverport=8080<br />
serverip_1=www.server1.com<br />
serverip_2=www.server2.com<br />
<br />
The configuration files also allow for notes or options to be disabled by the use of a comma (;) at the start of a line which can be seen in all of the configuration examples.<br />
<br />
Known options in the configuration files are recognised irrespective of the case they are entered in the configuration file so maxuser and MaXuSer will be handled the same way.<br />
<br />
Any items found in the configuration file which are not known (as detailed in following sections) or is not processed as a comment will be reported in the following manner:<br />
<br />
<date + time> W msg:[CONFIG] Invalid item on line XX<br />
<br />
Where <date + time> is the date and time the event happens at and XX is the line in the configuration file where the error has been found to occur at.<br />
<br />
<br />
===Banning===<br />
----<br />
<br />
'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''<br />
<br />
'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''<br />
<br />
If you are using a folder for saving the file into then you need to ensure that the<br />
folder already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Client Behaviour===<br />
----<br />
<br />
'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''<br />
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the<br />
maximum limit on the number of client connections allowed to connect to the server instance.<br />
<br />
'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''<br />
A value of zero means there will be no time limit.<br />
<br />
'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''<br />
<br />
'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''<br />
<br />
'''dstip''' or '''destip''' : Specify the server side binding address for clients ''[Default = <no value>]''<br />
If 'any' or no value is specified then sc_serv listens to all addresses.<br />
<br />
If you specify a value for 'dstip / destip' then this will be used by the listen feature on the Administration Pages (see section 5.1) so it can provide a valid stream url in the generated playlist. If 'dstip / destip' is not specified then the server will attempt to auto-generate the IP required for the client to be able to connect. If this fails the generated playlist is likely to return a stream url like <nowiki>http://0.0.0.0:<portbase>/<path></nowiki><br />
<br />
The IP provided needs to be in a valid format like <nowiki>http://<my-ip></nowiki> or an address which can be resolved to an IP otherwise the internal lookups done are likely to fail (depends upon the server configuration and OS being used). Also you cannot set srcip and dstip / destip to be the same IP value and if this happens then the server will close. Closing of the server will also happen if the IP cannot be resolved or correctly bound to i.e. server is not there or an invalid value was entered.<br />
<br />
'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''<br />
<br />
'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''<br />
<br />
<br />
===Debugging===<br />
----<br />
<br />
In all cases, the default value is for no debug logging for the options listed below.<br />
<br />
'''yp1debug''' : Enable debug logging of YP connections<br />
<br />
'''yp2debug''' : Enable debug logging of YP2 connections<br />
<br />
'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections<br />
<br />
'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections<br />
<br />
'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients<br />
<br />
'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients<br />
<br />
'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays<br />
<br />
'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays<br />
<br />
'''relaydebug''' : Enable debug logging of common relay code<br />
<br />
'''streamdatadebug''' : Enable debug logging of common streaming code<br />
<br />
'''httpstyledebug''' : Enable debug logging of http style requests<br />
<br />
'''statsdebug''' : Enable debug logging of statistics<br />
<br />
'''microserverdebug''' : Enable debug logging of common server activity<br />
<br />
'''threadrunnerdebug''' : Enable debug logging of the thread manager<br />
<br />
'''rtmpclientdebug''' : Enable debug logging of rtmp clients<br />
<br />
<br />
===Flash Security===<br />
----<br />
<br />
'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''<br />
<br />
<br />
===Introduction and Backup Files===<br />
----<br />
<br />
'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''<br />
<br />
'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''<br />
<br />
'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''<br />
<br />
'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''<br />
<br />
<br />
===Logging===<br />
----<br />
<br />
'''log''' : Enable logging of the servers output ''[Default = 1]''<br />
<br />
'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''<br />
If log=0 then this option is ignored due to no logging happening.<br />
<br />
'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''<br />
<br />
'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''<br />
<br />
If you are using a folder for saving the logs into then you need to ensure that the folder<br />
already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Miscellaneous===<br />
----<br />
<br />
'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''<br />
<br />
'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''<br />
<br />
'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''<br />
<br />
'''unique''' : Specify a substitution string for the '$' character to be used when processing filenames which if specified will set any occurences of '$' to the value set. This will be used in the processing of the following filenames: '''logfile''', '''introfile''', '''streamintrofile''', '''backupfile''', '''streambackupfile''', '''banfile''', '''streambanfile''', '''ripfile''', '''streamripfile''', '''include''', '''w3clog''', '''streamw3clog'''<br />
<br />
So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is<br />
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'<br />
<br />
'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''<br />
<br />
You can do multiple calls of this allowing for a basic configuration file with then 'specific' stream configurations set in individual conf files though you need to ensure not to include a reference to the same file in itself.<br />
<br />
You can also specify a path with a wildcard for sc_serv to use to find multiple configuration files to include '''e.g.''' 'include=stream/*.conf'. This can then be used along with the multiple stream configurations (see section 4.12) and the admin command 'admin.cgi?mode=reload' (see section 5.1) to add / remove / update stream configurations without having to close the server to apply them.<br />
<br />
'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''<br />
<br />
This can accept the following parameters:<br />
<br />
:admincssfile='''v1''' - Uses the v1 DNAS style<br />
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style<br />
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki><br />
<br />
If using a custom css file, if it does not exist on the first try to load it the server will revert to<br />
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.<br />
<br />
'''faviconfile''' : Specify the file to be returned as the favicon.ico when the administration pages are being queried by the client's browser ''[Default = <no value>]''<br />
<br />
The default behaviour is to use a SHOUTcast themed built-in icon file and support / handling the update of this will entirely depend on the browser.<br />
<br />
'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''<br />
<br />
Ensure this is correct for the type of image being used so it is valid.<br />
<br />
'''hidestats''' : Specify if the publically accessible stats?sid=# page can be accessed or if it is only available via the private administration pages ''[Default = 0]''<br />
<br />
'''robotstxtfile''' : Specify the file to be returned as the robots.txt when queried by search engines, etc to attempt to prevent incorrect access to the server's pages which may cause invalid client connections ''[Default = <no value>]''<br />
<br />
The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.<br />
::User-agent:*<br />
::Disallow:/<br />
<br />
<br />
===Networking===<br />
----<br />
<br />
'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''<br />
<br />
'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''<br />
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.<br />
<br />
'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''<br />
A value of zero means there is no timeout of an idle source.<br />
Also if you set this too low then it is likely that valid sources will<br />
fail to connect during the initial stages of a source connection.<br />
<br />
'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''<br />
<br />
'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''<br />
<br />
'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''<br />
<br />
'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''<br />
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).<br />
<br />
<br />
===Network Buffers===<br />
----<br />
<br />
'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''<br />
<br />
'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''<br />
<br />
'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''<br />
<br />
'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''<br />
<br />
<br />
===Relaying===<br />
----<br />
<br />
'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''<br />
<br />
'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''<br />
<br />
'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''<br />
Setting this to 0 will disable attempts for the relay to reconnect.<br />
<br />
'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''<br />
This generally applies only to YP1 connections and is related to the<br />
actual attempts to make and get a http response from the YP server.<br />
<br />
'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''<br />
<br />
<br />
''<Legacy Options>''<br />
<br />
'''relayport''' : Port of the source to use for the relay ''[Default: 80]''<br />
<br />
'''relayserver''' : Url of the source to relay ''[Default = <no value>]''<br />
<br />
Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method<br />
of setting up a relay. These options are only provided as a means for loading<br />
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.<br />
<br />
<br />
===Reserved IP (RIP)===<br />
----<br />
<br />
'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''<br />
<br />
'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''<br />
<br />
'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''<br />
<br />
If you are using a folder for saving the file into then you need to ensure that the folder<br />
already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
<br />
===Stream Configuration===<br />
----<br />
<br />
'''Important Note:''' If you do not specify an identifier (_#) on the end of the above options then it will be treated like _1 (effectively acting like SHOUTcast 1). Additionally, _0 is not a supported identifier and will be mapped to _1.<br />
<br />
'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in our configuration file ''[Default = 0]''<br />
With this enabled, you will need to ensure that any sources have their configuration details<br />
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with<br />
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).<br />
<br />
''<MULTI>'' (one set for each stream configuration):<br />
<br />
'''streamid''' : Specify the numerical identifier of the stream for control or referencing the stream configuration. This can only be a numeric value from 1 to 2147483647.<br />
<br />
If you use multiple stream configurations then you will need to ensure the _X<br />
part is specified and correct for each stream configuration group<br />
e.g.<br />
streamid=1<br />
streampath=random<br />
or<br />
streamid_1=1<br />
streampath_1=random_stream_path<br />
streamid_2=2<br />
streampath_2=another_stream_path<br />
<br />
'''streamauthhash''' : The authorisation key needed for YP2 directory registration.<br />
This is a requirement for using the YP2 system and without it you will not be able to<br />
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).<br />
<br />
This can be used for multiple streams you are providing or can be different (as long<br />
as valid) so you can infact provide multiple stations from the same server if desired.<br />
<br />
'''streampath''' : Specify the path clients need to use to access the stream<br />
If a / is not specified on the start of the string then the server will add<br />
it to the generated path in playlist entries or other places as required so<br />
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.<br />
<br />
If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be<br />
used for client access and in generated playlist entries so that it will<br />
always be possible for clients to connect to the server somehow. See [[SHOUTcast_DNAS_Server_2#Stream_Addresses|section 6.0]] for more information on the<br />
server's stream address support.<br />
<br />
'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).<br />
Make sure if you use this that the full url is entered and that it is<br />
the url which clients would connect to for the stream to be relayed.<br />
<br />
'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''<br />
If set to zero, not specified or higher than 'maxuser' then the value set for 'maxuser' (see [[#Client_Behaviour|section 4.2]]) will be used for all knwon streams.<br />
<br />
Changing this to a value between zero and 'maxuser' will enforce the user connection limit for the specified value in the stream configuration '''e.g.'''<br />
streammaxuser_1 = 8<br />
maxuser = 32<br />
<br />
This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.<br />
<br />
With the following stream configuration<br />
streammaxuser_1 = 64<br />
maxuser = 32<br />
<br />
This allows a total of 32 connections to the server but with a per stream limit above the maximum means the maximum number of connections to the first stream group will be 32. However this also depends upon any other stream configurations and their limits as to whether 32 clients will be able to connect to this stream configuration.<br />
<br />
Finally unless a valid stream configuration is specified then this value will only be applied to the first stream configuration found i.e. there is a need to specify a streamid_XXX for streammaxuser_XXX (where XXX is the stream identifier of the stream configuration group.<br />
<br />
'''streamadminpassword''' : Specify the administrator password for accessing the remote server features for the specified stream configuration group. If this is not specified then 'adminpassword' will be used.<br />
<br />
'''streampassword''' : Specify the password for broadcasters when connecting to the server for the specified stream configuration group. If this is not specified then 'password' will be used.<br />
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).<br />
<br />
'''streampublicserver''' : This allows you to override the public flag received from the source when a connection is being made to the YP directory. If this is not specified or is set to empty then 'publicserver' will be used.<br />
<br />
'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.<br />
<br />
'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.<br />
<br />
'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.<br />
<br />
'''streamautodumpsourcetime''' : Specify how long before an idle source will be dumped from the server (in seconds). A value of zero means there is no timeout of an idle source. If not specified then 'autodumpsourcetime' will be used.<br />
<br />
'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.<br />
<br />
'''streamlistenertime''' : Specify the maximum time in minutes a client is allowed to listen to the stream. A value of zero means there will be no time limit. If not specified then 'listenertime' will be used.<br />
<br />
'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.<br />
<br />
'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.<br />
<br />
'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.<br />
<br />
'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.<br />
<br />
'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.<br />
<br />
<br />
===Web Connection (W3C) Logging===<br />
----<br />
<br />
'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''<br />
<br />
'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''<br />
<br />
If you are using a folder for saving the log into then you need to ensure that the folder<br />
already exists as sc_serv will not attempt to the create the folder for you.<br />
<br />
'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''<br />
<br />
<br />
===YP Server Behaviour===<br />
----<br />
<br />
'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''<br />
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans<br />
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).<br />
<br />
Only change this if you really need to do so as not all SHOUTcast 2 clients will allow you to edit this value from the default value. If using the Source DSP plug-in then see [[Source_DSP_Plug-in#SHOUTcast_2_Cipher_Key|dsp_sc.txt - section 5.0]] for details on how to change the plug-in to use a differnet value.<br />
<br />
'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''<br />
YP1 only<br />
<br />
'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''<br />
<br />
If this is enabled and not all of the required values are set then the server will throw an error and will abort from its start-up attempt. It should be indicated what needs to be set to allow the server to start with this set.<br />
<br />
Additionally if there is an issue then the server will report an error in its log ouput of 'Connection attempt failed. YP2 error code is XXX (<message>)' where XXX is one of the following error codes and <message> is a message set in the error response to indicate a bit more what the error relates to. All current error codes can be found [[#YP_Server_Errors|here]].<br />
<br />
'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''<br />
<br />
'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''<br />
<br />
'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''<br />
<br />
'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''<br />
<br />
'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''<br />
This generally applies only to YP1 connections and is related to the<br />
actual attempts to make and get a http response from the YP server.<br />
<br />
'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''<br />
<br />
'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''<br />
<br />
'''publicserver''' : This allows you to override the public flag from the connected source when a connection is being made to the YP directory ''[Default = default]''<br />
This can be one of the following values:<br />
'''default''' - use the flag provided by the source<br />
'''always''' - force the source to be public<br />
'''never''' - never allow the use the flag provided by the source<br />
<br />
When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).<br />
<br />
<br />
===YP Server Errors===<br />
----<br />
<br />
If not all of the required values are set for a public listing then the DNAS server will throw an error and will abort its attempt to be listed in the Directory. It should be indicated the error is with one of the error codes provided below so it can be resolved.<br />
<br />
Additionally if there is an issue during Directory updates or removals, then the server will report an error in its log ouput as one of the following error codes and <message>.<br />
<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Status Code<br />
! Status Message<br />
|-<br />
| 400 || Generic error ''(covers all other cases usually from internal failures)''<br />
|-<br />
| 457 || Unrecoverable error while updating station information - DNAS restart required.<br />
|-<br />
| 470 || Invalid authorization hash<br />
|-<br />
| 471 || Invalid stream type (could be a bad bitrate or mime type)<br />
|-<br />
| 472 || Missing or invalid stream url<br />
|-<br />
| 473 || Server unreachable by YP<br />
|-<br />
| 474 || Relay url does not exist<br />
|-<br />
| 475 || Invalid server ID<br />
|-<br />
| 476 || Invalid max clients (value out of range or missing)<br />
|-<br />
| 477 || Terms of Service violator. You are being reported.<br />
|-<br />
| 478 || Incompatible protocol.<br />
|-<br />
| 479 || Streams requiring authorization are not public and cannot list here.<br />
|-<br />
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.<br />
|-<br />
| 481 || Cannot verify server since all listener slots are full. Please wait.<br />
|-<br />
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service<br />
|-<br />
| 483 || Invalid listeners (value out of range / missing)<br />
|-<br />
| 484 || Invalid avglistentime (value out of range / missing)<br />
|-<br />
| 485 || Invalid newsessions (value out of range / missing)<br />
|-<br />
| 486 || Invalid connects (value out of range / missing)<br />
|-<br />
| 487 || Request & Response objects are null<br />
|-<br />
| 488 || Request xml is null<br />
|-<br />
| 489 || YP command not specified<br />
|-<br />
| 490 || Generic error, while doing xml parsing<br />
|-<br />
| 491 || Generic error, while reading xml request<br />
|-<br />
| 492 || Error closing buffer / HTTP connection<br />
|-<br />
| 493 || Internal error - unable to acquire data source<br />
|-<br />
| 494 || Error updating information - DNAS restart required<br />
|-<br />
| 495 || Error acquiring station ID - DNAS restart required<br />
|-<br />
| 496 || Error converting data type<br />
|-<br />
| 497 || Inconsistent stream behaviour<br />
|-<br />
| 498 || Invalid Request (Invalid request received)<br />
|-<br />
| 499 || Error while getting information<br />
|}<br />
<br />
<br />
==Administration==<br />
<br />
With sc_serv there are administration pages available for accessing and controlling the server remotely which allows you to monitor and control clients connected to the stream (or not if banning them). These pages can now be accessed through a summary page at /index.html which will show a link to any active stream(s) or you explicitly access them via the /index.html?sid=# path where # is the ID of the stream (see [[#Stream_Configuration|section 4.12]] for more about using 'streamid') '''e.g.'''<br />
<streamurl>/index.html?sid=1<br />
<br />
If no sid or an invalid sid is passed then you will be taken to the summary /index.html and this will be applied even if you were on a page with a known ID and then enter an invalid sid or remove it purposefully.<br />
<br />
<br />
===Administration Pages===<br />
----<br />
<br />
As part of the administrative features provided there are the following pages where # is the streamid you want to use). This is not a complete list but should cover all of the pages which allow for a direct http url to be entered to get an administation action to work. The ban and reserve IP actions require input fields and do not map to direct sends.<br />
<br />
<br />
====Public Pages====<br />
----<br />
<br />
'''index.html''' - Shows a summary page with links to get to any active stream(s)<br />
<br />
'''currentsong?sid=#''' - Returns the current song title or a null response<br />
<br />
'''nextsong?sid=#''' - Returns the next song title (if known) or a null response<br />
currentsong and nextsong both provide a UTF-8 encoded string of the song title<br />
otherwise it will return effectively no response (ignoring the http header).<br />
<br />
'''nextsongs?sid=#''' - Returns in an xml format the next song title(s) (if known) to be played when using a compatible v2 stream source. See [[#XML_Responses|section 5.2]] for more details on the format of the xml returned).<br />
<br />
'''index.html?sid=#''' - Shows current status of the specified stream<br />
<br />
'''played.html?sid=#''' - Song history of specified playing history<br />
:or<br />
'''played?sid=#'''<br />
<br />
'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.<br />
:or<br />
'''listen?sid=#'''<br />
<br />
'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.<br />
<br />
'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.<br />
<br />
With the listen pages you either need to have specified an IP with 'dstip / destip'<br />
(see section 4.2) or leave empty and allow the server to attempt to auto-generate<br />
the IP required for the client to be able to connect. If this fails the generated<br />
playlist is likely to return a stream url like <nowiki>http://0.0.0.0:<portbase>/<path></nowiki><br />
<br />
'''home.html?sid=#''' or '''home?sid=#''' - Opens in a new window or tab (depending on the client browser) the 'streamurl' as specified by the stream source. If this is not set then the client will be redirected to the shoutcast.com main page.<br />
<br />
'''stats?sid=#''' - Provides an xml response for public accessibility which matches the private version from admin.cgi?sid=#&mode=viewxml&page=1. This is the modern version of the 7.html page as provided by the legacy v1 servers. See [[#XML_Responses|section 5.2]] for information on what is provided in the xml response.<br />
<br />
<br />
====Private Pages====<br />
----<br />
<br />
By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible<br />
to directly access the administration page(s) required. As well the base64 encoded version of the password<br />
can be passed as long as it is prefixed with ''YWRtaW46''<br />
e.g.<br />
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=<br />
<br />
'''admin.cgi''' - Shows the an overal summary admin page for the streams provided by the server including direct links to certain information pages (see notes about the 'admin.cgi?sid=#&mode=viewxml' command for more info)<br />
:or<br />
'''admin.cgi?sid=0'''<br />
<br />
'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information<br />
<br />
'''admin.cgi?sid=#&mode=updinfo&song=title''' <br />
:or<br />
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml''' <br />
If 'title' is not empty then it will be set as the current song title for the stream<br />
specified until the next use of this action or the next title update is received from<br />
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]<br />
instead of a v1 title.<br />
<br />
'''admin.cgi?sid=#&mode=viewlog''' - View logfile<br />
<br />
'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)<br />
<br />
The tailing option keeps adding additional log entries to the end of the view whilst the view is active.<br />
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped<br />
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.<br />
<br />
'''admin.cgi?sid=#&mode=viewban''' - Ban view which matches the ban file and allows you to ban a single IP or an IP range from it (see [[#Banning|section 4.1]] for more info on the file)<br />
<br />
'''admin.cgi?sid=#&mode=viewrip''' - Reserved IP list that matches the rip file (see [[#Reserved_IP_.28RIP.29|section 4.11]] for more info on the file)<br />
<br />
'''admin.cgi?sid=#&mode=art''' or '''admin.cgi?sid=#&mode=art&art=playing''' - Displays the artwork SHOUTcast v2 compatible clients may be able to display if the SHOUTcast v2 source does provide it.<br />
<br />
The artwork mode is primarily intended as a debugging option to make it possible<br />
to see what (if anything) has been provided by the SHOUTcast v2 source.<br />
<br />
If no '&art=' is specified or not a matching option then the stream artwork (if<br />
available) will be shown. If no '&art=playing' is specified then this will show<br />
the playing file's artwork (if available).<br />
<br />
'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information<br />
<br />
If page is not set or is outside of the range zero to 6 then this will output all of the<br />
information as the standard viewxml action does. Otherwise this only display information<br />
depending on the value assigned to page which can be from 1 to 6 which maps as follows:<br />
<br />
1 - Server Summary (this is the same as using the public stats?sid=# action)<br />
2 - Not used (previously used for Webdata Stats but not in current builds)<br />
3 - Listener Stats<br />
4 - Song History<br />
5 - Stream Metadata (if supported by the source otherwise can just be title)<br />
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)<br />
<br />
If accessing the standard viewxml or the listener stats (page = 3), you can also send<br />
'&iponly=1' which will filter the listener information (if there are any) to just output<br />
the IP instead of the additional information provided normally.<br />
<br />
'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it<br />
<br />
'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.<br />
<br />
'''admin.cgi?sid=#&mode=unripdst&ripdst=<IP>''' - Where <IP> is the IP to reserve (see [[#Reserved_IP_.28RIP.29|section 4.11]] for more information).<br />
<br />
'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.<br />
<br />
'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.<br />
<br />
'''admin.cgi?mode=rotate''' or '''admin.cgi?mode=rotate&files=log|w3c''' - This will rotate the log files set via the 'logfile', 'w3clog' and 'streamw3clog' options.<br />
If &files is specified then passing log or w3c will allow you to only<br />
rotate one type of file otherwise both will be rotated by this command.<br />
<br />
'''admin.cgi?mode=reload''' or '''admin.cgi?mode=reload&force=1''' - This reloads the stream configuration details in the main configuration file the server used when started and is only available on the admin summary page and so can only be run by the master administrator password.<br />
<br />
This command works on the server as a whole (hence no sid parameter) and it will add or<br />
remove or update any stream configuration as applicable which will cause any connected<br />
sources and clients to be kicked as applicable (usually if a stream configuration was removed).<br />
<br />
This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'<br />
in your main configuration file which the server can then use to detect different stream configurations.<br />
<br />
If '&force=1' is passed then the reload will treat the updating of active stream configurations in the<br />
same manner as a stream configuration removal instead of trying to update compatible stream configuration<br />
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.<br />
<br />
The following configuration options are updated when using this command:<br />
<br />
password or streampassword (*) streamadminpassword (#)<br />
requirestreamconfigs streamid<br />
streamauthhash streampath<br />
streamrelayurl streammaxuser<br />
streampublicserver streamallowrelay<br />
streamallowpublicrelay streamriponly<br />
streamautodumpsourcetime streamautodumpusers<br />
streamlistenertime streamintrofile<br />
streambackupfile streambanfile<br />
streamripfile<br />
<br />
(*) This will depend upon the current values versus the new configuration values<br />
(#) The master 'adminpassword' can only be changed after a restart of the server<br />
<br />
<br />
===XML Responses===<br />
----<br />
<br />
As detailed in the previous sections, some of the administration actions will provide the information in an xml response. For information on what is actually returned in these xml responses see [[SHOUTcast_DNAS_Server_2_XML_Reponses|sc_serv2_xml_responses.txt]].<br />
<br />
<br />
==Stream Addresses==<br />
<br />
Clients connecting to the streams provided by sc_serv are able to so in a number of ways depending upon how the streams have been configured and also depending upon the number of streams you have available.<br />
<br />
The two main ways for a client to connect to a stream are as follows:<br />
<br />
<serverurl>/stream/<streamid>/<br />
or<br />
<serverurl>/<streampath><br />
<br />
<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])<br />
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])<br />
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])<br />
<br />
If the client attempting to connect to the server instance does not specify <streampath> or <streamid> in the stream url it attempts to access or if only one stream is provided then the server will usually default to the first stream it knows about and will allow the client to make a valid connection (though this is not guaranteed to happen).<br />
<br />
This handling of the stream addresses provided is something to keep in mind especially if you are providing multiple streams as this will allow you to provide different addresses for certain clients to be able to use a specific stream '''e.g.''' if you wanted to have mobile clients connect to a lower bandwidth stream then you could direct them to '<serverurl>/mobile'<br />
<br />
The server options available for controlling how the stream's path is specified can be seen in [[#Stream_Configuration|section 4.12]] which also details the equivalent values needing to be set in the sc_trans configuration if you use sc_trans to provide a source to sc_serv.<br />
<br />
<br />
==Locale Error (Linux / Mac OS X / BSD)==<br />
<br />
If you receive the following error then you have a locale related issues:<br />
<br />
terminate called after throwing an instance of 'std::runtime_error'<br />
what(): locale::facet::_S_create_c_locale name not valid<br />
Abort trap<br />
<br />
If this happens then you need to set the 'POSIX' locale in your terminal's environment values. If this does not happen then everything is fine or you are using a newer version of sc_serv from the end of 2010 which should no longer exhibit this issue.<br />
<br />
Linux:<br />
export LC_ALL=POSIX<br />
<br />
BSD:<br />
setenv LC_ALL POSIX<br />
<br />
Mac OS X:<br />
export LC_ALL=POSIX<br />
<br />
You can test to see if this has worked by checking the shell command "locale":<br />
<br />
LANG=<br />
LC_COLLATE="POSIX"<br />
LC_CTYPE="POSIX"<br />
LC_MESSAGES="POSIX"<br />
LC_MONETARY="POSIX"<br />
LC_NUMERIC="POSIX"<br />
LC_TIME="POSIX"<br />
LC_ALL="POSIX"<br />
<br />
<br />
==Virtual Memory Footprint (Linux / Mac OS X / BSD)==<br />
<br />
Due to how sc_serv works it will create a large number of threads which may become an issue due to the default virtual memory stack allocation per thread potentially being large (typically 10MB per thread). For most people this should not be an issue as the memory is not really allocated unless it is used. If however if you have a resource constrained system or if you plan on running many copies of sc_trans then you could potentially run out of virtual memory.<br />
<br />
The default thread allocation can be reduced by issuing a "ulimit" command before running sc_trans and in the example reduces it to 512KB per-thread '''e.g.''' ulimit -s 512<br />
<br />
<br />
==Maximum Client Connection Limits==<br />
<br />
In general, there are inherent limits on the maximum number of client connections which may be made to a running instances of sc_serv which can either be set by configuration limits e.g. 'maxuser', Operating System limits or bandwidth limits being reached.<br />
<br />
The first two are easy to resolve whereas the last (bandwidth limits) is something which will usually require obtaining additional hosting or paying for more available bandwidth.<br />
<br />
If reaching the Operating System limit, this is usually indicated by the maximum number of clients never going above a fixed value even if there is the bandwidth and the server has been configured to go higher. This usually appears as around 1016 maximum connections (though this can vary a bit)<br />
<br />
If using a non-Windows Operating System then you can use the 'ulimit -n xxxx' command to change the upper limit from what is already set which can be found from just 'ulimit -n' e.g. to change the limit to 4096 connections you would run ulimit -n 4096<br />
<br />
If using a Windows Operating System then there isn't any real way to change such things due to the OS hopefully being configured with limits that will not be reached when using sc_serv. If in doubt then consult the Microsoft support documentation for the OS used.<br />
<br />
<br />
==Example Configurations==<br />
<br />
Include as part of the sc_serv installation are a number of example configurations to get things started with using some of the features of the server. The provided examples are:<br />
<br />
sc_serv_basic.conf<br />
sc_serv_public.conf<br />
sc_serv_relay.conf<br />
sc_serv_simple.conf<br />
<br />
All of the configuration examples are documented and will relate back to details in this file appropriately. You will need to change some details in these example files or to obtain any applicable authorisation keys for the setup you are making ([[#Getting_Started|see section 3.0]]). In all cases the examples are designed to work from the same install folder as sc_serv.<br />
<br />
Remember these examples are a way to get you up and running faster though you are still likely to have to adjust things depending upon the systems you are using and how you want to manage your sources and server connections which are covered in previous sections.<br />
<br />
Additionally if you are not happy with editing the files or find it still too confusing then you can use the configuration builder which (if installed) can be found in the 'config_builder'. Open 'config_builder.html' in your browser and then use this graphical tool to setup a configuration file for the server (and additionally the transcoder).<br />
<br />
<br />
===sc_serv_basic===<br />
----<br />
<br />
This is the base configuration from which the other configuration examples are based and this will get a sc_serv instance running as a local setup with no connection made to the YP directory.<br />
<br />
<br />
===sc_serv_public===<br />
----<br />
<br />
This configuration file changes the required options in the sc_serv_basic configuration to get a sc_serv instance running as a public setup with a connection made to the YP for listing the stream in the directory. This shows the use of the 'include' option (see section [[#Miscellaneous|4.7]]) and how specifying a configuration option twice uses the last value found.<br />
<br />
<br />
===sc_serv_relay===<br />
----<br />
<br />
This configuration file changes the required options in the sc_serv_public configuration to get a sc_serv instance running as a public setup with a source coming in from a relay server providing a SHOUTcast 2 stream.<br />
<br />
<br />
===sc_serv_debug===<br />
----<br />
<br />
This configuration file can be included in any other configuration files to allow you to get debug logging output when trying to investigate any issues you may be experiencing.<br />
<br />
<br />
===sc_serv_simple===<br />
----<br />
<br />
Use this if you just need to get a very basic server running or are impatient<br />
or are struggling to get it running despite the previous example configurations.<br />
<br />
This configuration file is designed to be used just as is and is the simplest form of the configuration file you can have which will allow you to get a running server to appear on the YP. This works on using the default settings of the server though does change some of the file paths inorder to fit in with the existing setup as used in the other examples.<br />
<br />
All you need to do when using this configuration file is to enter your authorisation key in the 'streamauthhash' line '''e.g.''' if your authorisation key is '''123456789''' then you change ''streamauthhash=<enter_your_auth_key_here>'' to ''streamauthhash='''123456789''''' and save the file.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_BroadcasterSHOUTcast Broadcaster2014-10-28T22:59:19Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
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.<br />
<br />
<br />
=SHOUTcast Overview=<br />
<br />
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 />
<br />
<br />
=Getting Started=<br />
<br />
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]]'''<br />
'''Important:''' You need to be happy with the use of command-line tools before attempting to install or run a<br />
SHOUTcast system as all versions of the v2 Server and Transcoder are designed to work as command-line tools.<br />
<br />
Current versions of the SHOUTcast tools can be obtained from:<br />
<br />
::'''[http://www.shoutcast.com/BroadcastNow/ Broadcast Tool Downloads]'''<br />
::or<br />
::'''[http://forums.shoutcast.com/showthread.php?t=324877 Support Forum Current Downloads Summary] (*)'''<br />
<br />
The forum link is a summary page and contains links to the latest versions of the tools such as when a new<br />
release has just happened or is being tested before it is provided via the '''[http://www.shoutcast.com/broadcast-tools/ Broadcast Tool Downloads]''' page.<br />
<br />
<br />
==Core Documentation==<br />
<br />
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.<br />
<br />
::'''[[SHOUTcast_DNAS_Server_2|SHOUTcast DNAS Server 2 (sc_serv)]]'''<br />
<br />
::'''[[SHOUTcast_DNAS_Transcoder_2|SHOUTcast DNAS Transcoder 2 (sc_trans)]]'''<br />
<br />
::'''[[Source_DSP_Plug-in|SHOUTcast Source DSP Plug-in (dsp_sc)]]'''<br />
<br />
<br />
==Supporting Documentation==<br />
<br />
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.<br />
<br />
::'''[[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]]'''<br />
<br />
::'''[[SHOUTcast_DNAS_Server_2_XML_Reponses|SHOUTcast DNAS Server 2 XML Reponses]]'''<br />
<br />
::'''[[Source_DSP_Plug-in_Configuration_Examples|SHOUTcast Source DSP Plug-in Configuration Examples]]'''<br />
<br />
::'''[[SHOUTcast_Transcoder_AJAX_api_Specification|SHOUTcast Transcoder AJAX api Specification]]'''<br />
<br />
::'''[[SHOUTcast_Calendar_Event_XML_File_Specification|SHOUTcast Calendar Event XML File Specification]]'''<br />
<br />
::'''[[SHOUTcast_YP_Nak_Errors|SHOUTcast YP Nak Error Information]]'''</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Getting_Started_GuideSHOUTcast Getting Started Guide2014-10-28T22:58:40Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The aim of this page is to help guide you through the process of getting a SHOUTcast 2 system installed and broadcasting so people can connect to it through the SHOUTcast Radio Directory and hear the great content you have and want to provide to the world.<br />
<br />
It is assumed throughout the documentation that you have a basic knowledge of how to use the command-line console for the platform you decide to install the tools on i.e. how to run and control a program via the command-line console including being able to pass to it commands and the sending of signals as is appropriate to the platform being used. Windows users see [[#Windows_Users|section 1.2]].<br />
<br />
Additionally it is assumed you know how to setup your network connection and router to allow your server instance to be visible when broadcasting i.e. being able to open up and forward any required ports to allow your server instance to be visible to other machines on the internet as well as so the SHOUTcast Radio Directory can see you.<br />
<br />
This guide will refer you to other places in the documentation provided with the tools by showing references to the relevant file and section in the documentation files e.g. [[Source_DSP_Plug-in#Encoder_Tab|dsp_sc.txt - section 3.2.3]]. These referenced sections generally provide a lot more detail on the option or feature such as what would need to be set in the Transcoder configuration to allow for it to work with the DNAS Server being setup and so on.<br />
<br />
<br />
===What is SHOUTcast?===<br />
----<br />
<br />
If you are new to SHOUTcast then this is probably something you may have already asked or you are trying to find out.<br />
<br />
At its most basic, the SHOUTcast system is based around a ''''client + server'''' configuration which allows you to run a server (either directly or via a hosted service) which can then provide a stream or streams of the 'source' connected to the server to any clients which are connected to the server.<br />
<br />
The clients connect via a direct connection i.e. '''server <->> client''' where the main flow of data (the stream data) will go from the server to the client.<br />
<br />
So a simple SHOUTcast setup would consist of the following:<br />
<br />
Winamp + DSP ? DNAS [sc_serv] ? Winamp<br />
(Source) (Server) (Client)<br />
<br />
This is not the only way to setup a SHOUTcast system and more examples can be seen in the [[SHOUTcast_System_Overview|shoutcast_system_overview.txt]] which goes into more detail about the way SHOUTcast works as well as other ways of setting up a SHOUTcast system (see [[SHOUTcast_System_Overview#Example_SHOUTcast_System_Setups|section 2.0]]).<br />
<br />
<br />
===Windows Users===<br />
----<br />
<br />
The SHOUTcast DNAS Server and Transcoder are both built to be run from the command-line console (or as a native service if using this mode) which may appear to be daunting when most interaction done with the operating system is done via a graphical interface (GUI).<br />
<br />
If you are not acquainted with using the command-line console then you will need to find a guide which shows you the basics of using the command-line console along with getting you familiar with using it before trying to get any of the SHOUTcast tools running. If you search for 'how to use the command prompt' then you should find a guide which you can follow to help get you knowledgeable enough with using the command-line console.<br />
<br />
This may appear to be a step backwards if you previously used the v1 DNAS Server with its very basic GUI wrapper which otherwise was acting in the same manner as the command-line console just without the look of the operating system. However the v1 DNAS Server was at its core a command-line tool just like the v2 DNAS Server is now.<br />
<br />
<br />
===Windows Vista / 7 Specifics===<br />
----<br />
<br />
Due to the UAC feature (http://en.wikipedia.org/wiki/User_Account_Control) of these OSes you will need to remember the effect that this will have on editing and saving of files.<br />
<br />
By default the Windows versions of the installer will choose the native 'Program Files' folder '''(*)''' but unless you have disabled UAC or do not have full access to the folder then you will find attempts to save and edit any configuration files will not work.<br />
<br />
If this is an issue then you should either choose a different folder of all of the files or change where the tools are trying to save files and also to save any changes in your configuration files with a text editor which is running with administrator permissions.<br />
<br />
This is an unfortunate inconvenience though for making it easier to known where all of the configuration examples and documentation can be found is better. Finally there is no reason not to choose a different folder when installing the tools if you experience this.<br />
<br />
<br />
'''(*)''' This will be slightly different depending on if you are using the 32-bit or 64-bit version of the OS as well as the language of the OS. As well the installer will pick the native 'Program Files' folder so installing the 32-bit version on the 64-bit OS will use 'Program Files (x86)' whereas installing the 64-bit version on the same OS will use 'Program Files'.<br />
<br />
<br />
<br />
==What is Required?==<br />
<br />
To make your SHOUTcast system you will need the following software tools and hardware:<br />
<br />
:*A computer running on a supported operating system ([[#Supported_Operating_Systems|see section 2.1]])<br />
:*SHOUTcast DNAS Server<br />
:*An input source (Transcoder or Winamp plus Source DSP plug-in)<br />
:*Media or DJ's or a Capture device i.e. the content you want to provide to people<br />
<br />
<br />
===Supported Operating Systems===<br />
----<br />
<br />
There are versions of the DNAS Server and Transcoder available on the following operating systems:<br />
<br />
:*Windows 32-bit Windows 2000, XP, Vista, Windows 7<br />
:*Windows 64-bit 64-bit versions of Windows XP, Vista, Windows 7<br />
:*Linux 32-bit<br />
:*Linux 64-bit<br />
:*BSD 8.x<br />
:*Mac OS X (Intel) Should work on 10.4.4 and up though is only tested against 10.5.5<br />
<br />
Remember to download the version of the tools which fits the operating system of the machine you will be installing the tools onto e.g. you could install the 32-bit Windows version on Windows 7 64-bit but could not install the 64-bit Windows version on Windows XP 32-bit.<br />
<br />
If using machines with different operating systems for different tasks then there should not be any problems with them working together e.g. Windows for the source and Linux for the server. This is due to the tools using the same communication style irrespective of the platform which they being run upon. If you do find an incompatibility then report it.<br />
<br />
<br />
<br />
==Getting Installed==<br />
<br />
When following the steps listed remember to only follow the parts which are applicable to the operating system and the tool or tools which you are attempting to install. If you do want to install multiple tools then it is better to work through the guide for one tool and then to do the same for the other one otherwise it may become confusing especially if you are new to command-line console tools and manual editting of configuration files.<br />
<br />
If you are not happy with manual editting of configuration files then there is also a configuration builder included as part of the Server and Transcoder distribution - see [[#Configuration_Builder|section 4.2]]. The aim of the configuration builder is to aid in the creation of matching configuration files for both tools which should work. It is still recommended that you do read the accompanying documentation so you can understand what it is that you are doing.<br />
<br />
<br />
===Download the Correct Version===<br />
----<br />
<br />
To begin with you will need to download the correct version of the tools you are going to use for the operating system you are setting up your SHOUTcast system on. See [[#Supported_Operating_Systems|see section 2.1]] for clarification of the supported operating systems for the tools.<br />
<br />
Current versions of the SHOUTcast tools can be obtained from:<br />
<br />
:*http://www.shoutcast.com/broadcast-tools<br />
:*http://forums.winamp.com/showthread.php?t=324877 '''(*)'''<br />
<br />
Remember you will need to download a Server (sc_serv) and a source for the server which can be the Transcoder (sc_trans) or if using Windows then you can also use the Source DSP plug-in (dsp_sc) for Winamp (which may work on non-Windows systems using WINE but is not guaranteed and no support is offered with such a setup).<br />
<br />
Additionally there are a number of third party programs which can act as a source for a server instance. These are not covered as part of this guide and if you decide you want to use one of these programs then you will need to consult their help for getting it to work with the server instance.<br />
<br />
'''(*)''' This is a summary page and contains links to the latest versions of the tools such as when a new release has just been released or is being tested before it is provided via the main SHOUTcast site download page at http://www.shoutcast.com/broadcast-tools<br />
<br />
<br />
===Choose an Install Location===<br />
----<br />
<br />
Choose an install location for the tool you want to install (be it the Server, Transcoder or the source plug-in for Winamp) as is applicable for the SHOUTcast setup you are making on the machine.<br />
<br />
On Windows this choice is handled via the installer which selects a sensible new location or it re-uses the previous install location if doing an upgrade of an install which was previously made with a v2 tool installer. This can be changed if wanted during install.<br />
<br />
On Windows this choice is handled via the installer which selects a sensible new location or it re-uses the previous install location if doing an upgrade of an install which was previously made with a v2 tool installer. This can be changed if wanted during install and will be needed if you are running on a Windows system with UAC enabled ([[#Windows_Vista_.2F_7_Specifics|section 1.3]]).<br />
<br />
On non-Windows operating systems you can choose any location for the extracted location as long as you have the correct permission and access to the folder chosen.<br />
<br />
<br />
===Installation===<br />
----<br />
<br />
On Windows you now need to run the installer, using the folder you have decided upon for the install location along with ensuring the option to install the documentation has been checked. Doing this will install the documentation and example configuration files which are included in the installer and referenced in later stages of this guide.<br />
<br />
Note: If using Windows Vista / 7 then make sure to install into a location which allows you to save and edit the configuration files and to save any log files into. More information can be found on what is required in [[#Windows_Vista_.2F_7_Specifics|see section 1.3]].<br />
<br />
<br />
On non-Windows you now need to extract the files for the tool(s) you have downloaded and ensure that you extract all contents of the archive into the install location decided on.<br />
<br />
<br />
===Setting Up The Tools===<br />
----<br />
<br />
The following sections are grouped together for what needs to be done in configuring and getting ready to start one or more of the officially provided tools. If you are not using one or more of them then you can skip the section as appropriate. Remember that you will need to have a valid source for use with the DNAS in order to have a listenable stream.<br />
<br />
Ensuring the Server is properly configured is the most important thing as unless it<br />
is and running then none of the tools will be able to connect to it successfully.<br />
<br />
<br />
===Server===<br />
----<br />
<br />
====Server Configuration Setup====<br />
----<br />
<br />
Getting the Server started you first need to open up the '''sc_serv_simple.conf''' example file in the root of the install location. Work through the file's contents and then fill in or change any of the values required for how you want to use the server.<br />
<br />
The provided example will create a simple server configuration and contains the basic settings needed to allow for the server to work so it will appear in the SHOUTcast lists.<br />
<br />
The only thing missing from the example is an authhash which is required for a stream to be listed in the SHOUTcast Radio Directory when using the SHOUTcast 2 system. This needs to be obtained once the Server is running and a source has correctly connected to it. See [[#Obtaining_An_Authhash|section 3.5.4]] for how to do this one all other stages have been completed.<br />
<br />
Additionally there are example configuration files for the following scenarios:<br />
<br />
::'''sc_serv_basic''' - shows how to get a more multi-stream setup working<br />
::'''sc_serv_public''' - shows how to make a public server from sc_serv_basic<br />
::'''sc_serv_relay''' - shows how to relay another source<br />
<br />
There is more information about these example configurations in sc_serv2.txt - [[SHOUTcast_DNAS_Server_2#Example_Configurations|section 10]]<br />
<br />
<br />
====Starting the Server====<br />
----<br />
<br />
For simplicity we will only run the Server in the command-line console though when your Server setup is completed and everything is known to be working correctly then running as a service (Windows) or as a daemon (non-Windows) can be done to automate loading of the Server.<br />
<br />
<br />
To start the Server instance you now need to enter the correct command string for the operating system you are using in the command-line console like the following which assumes using the base example configuration file in the same directory as the Server program file:<br />
<br />
::For Windows - '''sc_serv.exe sc_serv_simple.conf'''<br />
::For non-Window - '''./sc_serv sc_serv_simple.conf'''<br />
<br />
If you use one of the other example configuration files or a different one then you can just change '''sc_serv_simple.conf''' to the name or full path to the configuration file.<br />
<br />
<br />
For more information on running the Server see [[SHOUTcast_DNAS_Server_2|sc_serv2.txt]] and the relevant section for the operating system you are using:<br />
<br />
::Windows - [[SHOUTcast_DNAS_Server_2#Run_as_a_Non-Service_in_the_Console|3.2.3]] (or [[SHOUTcast_DNAS_Server_2#Windows|3.2]] for more advanced options)<br />
::Linux / Mac OS X / BSD - [[SHOUTcast_DNAS_Server_2#Run_as_a_Non-Daemon|3.3.3]] (or [[SHOUTcast_DNAS_Server_2#Linux_.2F_Mac_OS_X_.2F_BSD|3.3]] for more advanced options)<br />
<br />
<br />
====Errors Running the Server====<br />
----<br />
<br />
Skip this if you experience no error reports when trying to run the Server.<br />
<br />
If an issue is reported in the console output from the Server then you first need to look at the actual issue being reported which will be prefixed with an 'E' at the start of the message in the console output.<br />
<br />
The error message shown should make it clear as to what is wrong e.g. passing an invalid or missing configuration file passed would cause an error along with closing the server instance.<br />
<br />
If the error message still does not make any sense then either double-check [[SHOUTcast_DNAS_Server_2|sc_serv2.txt]] or goto the SHOUTcast support forums http://forums.winamp.com/forumdisplay.php?f=140 and post the question along with a copy of the log including the error message.<br />
<br />
<br />
====Obtaining An Authhash====<br />
----<br />
<br />
With the Server now running, you will need to obtain an authhash for any stream(s) you want to be listed in the SHOUTcast Radio Directory. This is done via the '''Administation Summary''' page the Server provides as long as a valid source has been connected to the Server. See [[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]] for how to do this.<br />
<br />
<br />
===Transcoder===<br />
----<br />
<br />
<br />
====MP3 Streaming License====<br />
----<br />
<br />
Skip this if you are not setting up the Transcoder for MP3 streaming.<br />
<br />
If you want to provide an MP3 stream and are going to use the Transcoder then you will need to obtain a license key in-order to unlock the support to do this in the tool. Details on how to obtain this can be found in [[SHOUTcast_DNAS_Transcoder_2#Registering_for_MP3_Stream_Encoding|sc_trans.txt - section 2.5]].<br />
<br />
AAC encoding does not need you to purchase a license as one has<br />
already been paid for you as detailed in [[SHOUTcast_DNAS_Transcoder_2#Why_Does_AAC_Encoding_Not_Require_a_License_Key.3F|sc_trans.txt - section 2.5.1]].<br />
<br />
Once the key has been obtained you need to add the key and your name into the 'unlockkeyname' and 'unlockkeycode' values in you configuration file exactly as they have been received. So if your key is '123456' and you have used 'Bob' as the registered name, you would add the following to your Transcoder configuration file:<br />
<br />
unlockkeyname=Bob<br />
unlockkeycode=123456<br />
<br />
<br />
====Transcoder Configuration Setup====<br />
----<br />
<br />
Getting the Transcoder started you first need to open up the sc_trans_simple.conf example file in the root of the install location. Work through the file's contents and then fill in or change any of the values required for how you want to use the server.<br />
<br />
If you are wanting to use MP3 encoding then make sure you have followed '[[#MP3_Streaming_License|section 3.6.1]]' and entered the required 'unlockkeyname' and 'unlockkeycode' values in you configuration file exactly as they have been received. You will be informed when later running the Transcoder if there is an issue with the MP3 license details.<br />
<br />
<br />
Additionally there are example configuration files for the following scenarios:<br />
<br />
::'''sc_trans_basic''' - shows how to get a basic setup without relying on the Server<br />
::'''sc_trans_capture''' - shows how to use a capture device<br />
::'''sc_trans_dj''' - shows how to setup a DJ connection<br />
::'''sc_trans_playlist''' - shows how to use scheduled playlists<br />
<br />
There is more information about these example configurations in [[SHOUTcast_DNAS_Transcoder_2#Example_Configurations|sc_trans.txt - section 11]]<br />
<br />
<br />
====Starting the Transcoder====<br />
----<br />
<br />
For simplicity we will only run the Transcoder in the command-line console though when your Transcoder setup is completed and everything is known to be working correctly then running as a service (Windows) or as a daemon (non-Windows) can be done to automate loading of the Transcoder.<br />
<br />
<br />
To start the Transcoder instance you now need to enter the correct command string for the operating system you are using into the command-line console like the following which assumes using the base example configuration file in the same directory as the Transcoder program file:<br />
<br />
::For Windows - '''sc_trans.exe sc_trans_simple.conf'''<br />
::For non-Window - '''./sc_trans sc_trans_simple.conf'''<br />
<br />
If you use one of the other example configuration files or a different one then you can just change '''sc_trans_simple.conf''' to the name or full path to the configuration file.<br />
<br />
<br />
For more information on running the Transcoder see [[SHOUTcast_DNAS_Transcoder_2|sc_trans.txt]] and the relevant section for the operating system you are using:<br />
<br />
::Windows - [[SHOUTcast_DNAS_Transcoder_2#Run_as_a_Non-Service_in_the_Console|2.2.3]] (or [[SHOUTcast_DNAS_Transcoder_2#Windows|2.2]] for more advanced options)<br />
::Linux / Mac OS X / BSD - [[SHOUTcast_DNAS_Transcoder_2#Run_as_a_Non-Daemon|2.3.3]] (or [[SHOUTcast_DNAS_Transcoder_2#Linux_.2F_Mac_OS_X_.2F_BSD|2.3]] for more advanced options)<br />
<br />
<br />
====Errors Running the Transcoder====<br />
----<br />
<br />
Skip this if you experience no error reports when trying to run the Transcoder.<br />
<br />
If an issue is reported in the console output from the Server then you first need to look at the actual issue being reported which will be prefixed with an 'E' at the start of the message in the console output.<br />
<br />
The error message shown should make it clear as to what is wrong e.g. passing an invalid or missing configuration file passed would cause an error along with closing the server instance.<br />
<br />
If the error message still does not make any sense then either double-check [[SHOUTcast_DNAS_Transcoder_2|sc_trans.txt]] or goto the SHOUTcast support forums http://forums.winamp.com/forumdisplay.php?f=140 and post the question along with a copy of the log including the error message.<br />
<br />
<br />
===Source DSP===<br />
----<br />
<br />
<br />
====Install Source DSP====<br />
----<br />
<br />
Skip this if you are not setting up the Source DSP plug-in for MP3 streaming.<br />
<br />
If you want to provide an MP3 stream and are going to use Winamp and the Source DSP then you just need to make sure to install the Source DSP plug-in and select the MP3 encoder on the 'Output -> Encoder' tab (as detailed in [[Source_DSP_Plug-in#Encoder_Tab|dsp_sc.txt - section 3.2.3]]).<br />
<br />
<br />
====Configuring the Source DSP====<br />
----<br />
<br />
For getting Winamp and the Source DSP plug-in setup look through the [[Source_DSP_Plug-in_Configuration_Examples|dsp_sc_config.txt]] file and enter in the relevant values as described in it once you have setup:<br />
<br />
::the Server (from [[#Server_Configuration_Setup|section 3.5.1]]) if you are going to use the plug-in as the only source<br />
:and / or<br />
::the Transcoder (from [[#Transcoder_Configuration_Setup|section 3.6.2]]) if it is to act as a DJ source<br />
<br />
<br />
====Starting the Source DSP====<br />
----<br />
<br />
Using the Source DSP plug-in requires the plug-in to be set as the current DSP plug-in which is done by going to 'Winamp Preferences -> Plug-ins -> DSP/Effect' and selecting 'Nullsoft SHOUTcast Source DSP <version>' (*) from the plug-in's list.<br />
<br />
When this entry in the list is selected then the plug-in's configuration window will be opened and from there the plug-in will be in a state where a connection can be started via the 'Connect' button on the 'Output' tab.<br />
<br />
(*) The string <version> would be the actual version of the plug-in which is installed.<br />
<br />
<br />
<br />
===Completion===<br />
----<br />
<br />
You should now be up and running with a working SHOUTcast system. Happy broadcasting!<br />
<br />
If things are still not running then go back over the section(s) relating to the tool(s) you are having issues with and make sure that you have followed things otherwise please see the next section ([[#Further Information|section 4.0]]) on what you can do to get help in trying to resolve the issues you are experiencing.<br />
<br />
<br />
==Further Information==<br />
<br />
If you have followed the setup steps detailed in [[#Getting_Installed|section 3]] and are still having issues with getting the tools running or working together to achieve a certain result then first make sure you have the currently supported version of the tool(s) in case it is a bug in the tool(s) which has already been fixed. You can check this via the links referenced in [[#Download_the_Correct_Version|3.1]] and especially the forum link of the most current versions available.<br />
<br />
<br />
If installing the latest version does not help or if you already are using the latest version of the tool(s) or if the feature is not available then please goto the SHOUTcast support forums: http://forums.winamp.com/forumdisplay.php?f=140<br />
<br />
Make sure if you are reporting issues to provide as much information as possible for the SHOUTcast users who use the tools including the following information:<br />
<br />
:*Your SHOUTcast setup including all versions of the tools being used<br />
:*The issue you are experiencing<br />
:*The steps needed to reproduce the issue<br />
:*Anything else useful especially if you have been tinkering with options before the issue appeared<br />
<br />
Remember when you post an issue that providing as much information in a clear and concise manner will make it easier for anyone who can help to be able to understand the issue you have. This is important as not everyone visiting the forum are native English speakers.<br />
<br />
Finally you must remain civil to other users (however annoying or frustrating the issue is that you are experiencing) as most users will not want to make a reply to someone who does not appear to be civil - if you think about it from the other view of what you would think when looking at such a post then this should make sense to keep things civil.<br />
<br />
<br />
===Related Documentation===<br />
----<br />
<br />
All documentation can be found online - http://wiki.winamp.com/wiki/SHOUTcast_Broadcaster which will contain the documentation for the currently released versions of the tools.<br />
<br />
Additionally, in the install location there will be a 'docs' folder (as long as it has been chosen to be installed [Windows] or extracted [non-Windows] which contains text only versions of the main documentation relating to the SHOUTcast tool(s) installed as well as any related documentation to the other tools which may be of use in getting a SHOUTcast system configured and running<br />
e.g. the docs\dsp_sc folder contains information on the Source DSP plug-in so you can use it to setup the plug-in as a source or so you can know what to tell a DJ so they can connect to your SHOUTcast system.<br />
<br />
Please remember that with the SHOUTcast tools being designed to work on both the Windows and non-Windows operating systems, there is information included in the documentation which relates to either of these platforms. So when reading through the documentation, only follow the information which relates to the operating system you are using<br />
<br />
<br />
===Configuration Builder===<br />
----<br />
<br />
Included in the SHOUTcast DNAS Server and Transcoder installers / archives (depending on the operating system you are using) include a Configuration Builder which create a paired configuration file for the Server and the Transcoder. This can be found in the folder 'config_builder'.<br />
<br />
This is a very useful tool especially when making a new setup or if you find you are not happy with manually editing configuration files. Do remember that this will help to make configuration files which will work as long as the details you enter are correct and are correctly passed to the Server and Transcoder instances when run.<br />
<br />
Due to security issues when running web pages locally on the machine, you may find it is easier to use the externally hosted version on of the configuration builder which can be found at <nowiki>http://bogproghome.hopto.org/config_builder/config_builder.html</nowiki> (this will use the latest version of the configuration builder).<br />
<br />
<br />
==Glossary==<br />
<br />
<br />
'''Client''' - This is a program run which will connect to the Server e.g. Winamp.<br />
<br />
'''DNAS''' - This is an abbreviation of Distributed Network Audio Server and refers to the way SHOUTcast systems are intended in providing a Stream to multiple Clients.<br />
<br />
'''Server''' - This is the program which is run on a machine to provide to Clients the Stream.<br />
<br />
'''Source''' - This is a program or an input device e.g. the line-in connection on the Server which is providing the data for the Stream.<br />
'''<br />
Stream''' - This is the data which is provided from the Server to the connected Client and is best thought of like the flow of water in a stream in how it goes from the Server (up stream) to the Client (down stream).<br />
<br />
'''Transcoder''' - This is the software which can take taken different media files and convert them to a different format which is then compatible what the Stream wanted.<br />
<br />
'''YP''' - This is an abbreviation of YellowPages and refers to the SHOUTcast Radio Directory listing which makes it easier for Clients to search for and then find your Stream.<br />
<br />
'''dsp_sc''' - This is the name the SHOUTcast Source DSP plug-in is otherwise known as.<br />
<br />
'''sc_trans''' - This is the name the SHOUTcast Transcoder is otherwise known as.<br />
<br />
'''sc_serv''' or '''sc_serv2''' - This is the name the SHOUTcast DNAS Server is otherwise known as.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_System_OverviewSHOUTcast System Overview2014-10-28T22:58:19Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
__FORCETOC__<br />
==Overview of the SHOUTcast System==<br />
<br />
The SHOUTcast system is based around a ''''client + server'''' configuration which allows you to run a server (either directly or via a hosted service) which can provide a stream or streams (if using a v2 server) of the 'source' connected to it to any clients which then connect to the server.<br />
<br />
The clients connect via a direct connection i.e. '''server <->> client''' where the main flow of data (the stream data) will go from the server to the client.<br />
<br />
The server itself will take a source for the stream which can be from the Transcoder (sc_trans) or Winamp + Source DSP (dsp_sc) or any other program which is able to provide the stream data to the server in the required format (depending upon the mode the server is being run in). Additionally the source could even be another server which then makes our server into a relay server.<br />
<br />
Once a source is connected to the server, the server will then allow clients to connect to it and so the SHOUTcast system is running. An additional feature provided is the means to list the stream in the SHOUTcast Radio Directory (otherwise known as the YP from its earlier days which stands for YellowPages) which does as it is named by providing a directory listing of streams which makes it easier for any clients to find your stream and so be able to listen to it.<br />
<br />
Important to note is that the YP will not do anything else other than providing some information to the client such as a title, contact information i.e. a website to go to, the genre of the stream (used for categorising the stream for easier finding) and so on as provided to the YP from the server as well as providing the required url address of your stream. This is no more different than placing a link on your own site to the url address of your stream, it just happens to be listed in one place which makes it easier for clients to find yours and other peoples streams.<br />
<br />
<br />
==Example SHOUTcast System Setups==<br />
<br />
Based on what we now know about the SHOUTcast system you could have one of the following setups of tools to have a working SHOUTcast system.<br />
Legend<br />
<br />
«~» - A query made about the stream i.e. obtaining an url for it.<br />
→ or ← or ↑ - A direct connection where the direction of the arrow shows the<br />
direction the connection happens e.g. from a source to the server.<br />
<br />
<br />
'''Example 1:''' Source connected to a Server and listing on the YP for client connections<br />
<br />
Winamp + DSP → DNAS [sc_serv] → YP «~» Winamp<br />
(Source) (Server) (Radio Directory) (Client)<br />
↑ |<br />
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯<br />
<br />
<br />
'''Example 2:''' Source connected to a Server with a client using a direct url e.g. via website<br />
Winamp + DSP → DNAS [sc_serv] ← Winamp<br />
(Source) (Server) (Client)<br />
<br />
<br />
'''Example 3:''' Source connected to a Server with a client using a direct url<br />
Transcoder → DNAS [sc_serv] ← Winamp<br />
(Source) (Server) (Client)<br />
Note: This shows how the source can be different but the client will not know.<br />
<br />
<br />
'''Example 4:''' Relaying a Server via your Server and listing on the YP for client connections<br />
DNAS [sc_serv] → DNAS [sc_serv] → YP «~» Winamp<br />
(Source) (Server) (Radio Directory) (Client)<br />
↑ |<br />
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯<br />
<br />
<br />
===Summary===<br />
----<br />
<br />
As can be seen from these examples there are a number of ways to provide a source to the server (not accounting for 3rd party source programs) and for a client to connect to the server. In all cases the connection from the client to the server is direct even if the stream is listed on the YP and the client 'connects' to the stream via the YP entry.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_XML_Metadata_SpecificationSHOUTcast XML Metadata Specification2014-10-28T22:57:42Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
The aim of this file is to show the different aspects of metadata which can be obtained as part of the SHOUTcast 2.0 system. This aims to be a complete list of what is provided in the xml file which the server will provide and is based on the metadata obtained from the media being played (directly or guessed). As a result, not all fields will be filled in though this depends on the setup being used and what the SHOUTcast source implements.<br />
<br />
<br />
==Specification Details==<br />
<br />
The following is an example xml file output showing the different aspects of the metadata which could be returned along with specific notes about certain fields i.e. those which can appear multiple times or those from older mappings. One thing to notice is that this is somewhat similar to the ID3v2.3 tag as well as some aspects of the ID3v2.4 tag.<br />
<br />
Actual SHOUTcast 2 sources are not guaranteed to return the majority of the fields<br />
shown but provision is provided for them to be sent if detected from source media.<br />
<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<metadata><br />
<br />
<!-- ALBUM --><br />
<TALB>The Blue Album</TALB><br />
<br />
<!-- GENRE (Content type). The v1 value is the ID3V1 genre code.<br />
The text is a genre refinement --><br />
<TCON v1="24">Subgenre</TCON><br />
<br />
<!-- Note that code or subgenre may be missing.<br />
There can be more than one of these present --><br />
<TCON v1="RX"></TCON><br />
<br />
<!-- The genre code can also be RX (remix) or CR (cover) --><br />
<TCON>Death Metal</TCON><br />
<br />
<!-- Song TITLE --><br />
<TIT2>Back In the U.S.S.R.</TIT2><br />
<br />
<!-- ARTIST. There can be more than one of these present --><br />
<TPE1>The Beatles</TPE1><br />
<br />
<!-- Recording time --><br />
<TDRC><br />
<!-- YEAR --><br />
<year>2008</year><br />
<month>12</month><br />
<day>25</day><br />
<hour>13</hour><br />
<minute>24</minute><br />
<!-- If this is missing then assume it is UTC --><br />
<zone>Z</zone><br />
</TDRC><br />
<br />
<!-- COMMENT. There can be more than one of these present --><br />
<COMM language="eng" id="whatever"><br />
This is a comment<br />
</COMM><br />
.<br />
<COMM language="eng" id="more"><br />
This is another comment<br />
</COMM><br />
<br />
<!-- Universal file identifier. The content is base64 encoded binary data --><br />
<UFID id="http://www.neil.com">00000003f32f17</UFID><br />
<br />
<!-- Beats per minute. Numeric --><br />
<TBPM>60</TBPM><br />
<br />
<!-- Composer. There can be more than one of these present --><br />
<TCOM>Paul McCartney</TCOM><br />
.<br />
<TCOM>John Lennon</TCOM><br />
<br />
<!-- Copyright message --><br />
<TCOP>2008 Neil Radisch</TCOP><br />
<br />
<!-- Playlist delay (milliseconds between songs in playlist) --><br />
<TDLY>45</TDLY><br />
<br />
<!-- Identifier of the program providing the source audio --><br />
<TENC>My SHOUTcast Source v3.L337</TENC><br />
<br />
<!-- Provides name of the DJ connection if changed whilst streaming is active --><br />
<!-- This is primarily for the Transcoder to pass on DJ information to the server --><br />
<DJ>Super</DJ><br />
<br />
<!-- A related page which a client can use to get or show additional information --><br />
<!-- about the currently playing song as v1 clients were able to access previously --><br />
<URL>http://www.aol.com/backinussr.html</URL><br />
<br />
<!-- Lyricist and / or text writer. There can be more than one of these present --><br />
<TEXT>Oscar Hammerstein</TEXT><br />
.<br />
<TEXT>Lorenz Hart</TEXT><br />
<br />
<!-- Content group description --><br />
<TIT1>Concept Album</TIT1><br />
<br />
<!-- Subtitle --><br />
<TIT3>Those Ukraine Girls</TIT3><br />
<br />
<!-- Musical key of song --><br />
<TKEY>C#</TKEY> <br />
<!-- Language in audio described as 3 letter code based on the ISO-639-2 format.<br />
There can be more than one of these present --><br />
<TLAN>eng</TLAN><br />
.<br />
<TLAN>sve</TLAN><br />
<br />
<!-- Length of the audio in milliseconds --><br />
<TLEN>60000</TLEN><br />
<br />
<!-- Information about the source media type --><br />
<TMED>(VID/PAL) four channel</TMED><br />
<br />
<!-- Original album, movie or show --><br />
<TOAL>The White Album</TOAL><br />
<br />
<!-- Original file name --><br />
<TOFN>bit_ussr.mp3</TOFN><br />
<br />
<!-- Original lyricists / text writers. There can be more than one of these present --><br />
<TOLY>Jean Paul Satre</TOLY><br />
.<br />
<TOLY>Ayn Rand</TOLY><br />
<br />
<!-- Original artist. There can be more than one of these present --><br />
<TOPE>Bruce Springstein</TOPE><br />
.<br />
<TOPE>E Street Band</TOPE><br />
<br />
<!-- Original release time --><br />
<TDOR><br />
<year>2008</year><br />
<month>12</month><br />
<day>25</day><br />
<hour>13</hour><br />
<minute>24</minute><br />
<!-- If this is missing then assume it is UTC --><br />
<zone>Z</zone><br />
</TDOR><br />
<br />
<!-- Owner or licensee of the file --><br />
<TOWN>Ascap</TOWN><br />
<br />
<!-- Additional performer information --><br />
<TPE2>Featuring Yoko Ono</TPE2><br />
<br />
<!-- Name of conductor --><br />
<TPE3>Zubin Mehta</TPE3><br />
<br />
<!-- Who did the remix or other interpretation of the original --><br />
<TPE4>Sonic cleanup corp</TPE4><br />
<br />
<!-- Part number (2 of 4 discs) Note: total is optional --><br />
<TPOS total="4">2</TPOS><br />
<br />
<!-- Name of label or publisher --><br />
<TPUB>Capitol Records</TPUB><br />
<br />
<!-- Track number (e.g. 6 of 24 tracks). Note: total is optional --><br />
<TRCK total="24">6</TRCK><br />
<br />
<!-- Name of the internet radio station from where this is being broadcast --><br />
<TRSN>Neils Radio Station</TRSN><br />
<br />
<!-- Owner of the source internet radio station --><br />
<TRSO>Neil Radisch</TRSO><br />
<br />
<!-- Size of the audio in bytes (excluding ID3v2 tag) --><br />
<TSIZ>3456627</TSIZ><br />
<br />
<!-- International Standard Recording Code (ISRC) (12 characters) --><br />
<TSRC>FRZ039800212</TSRC><br />
<br />
<!-- Settings used for encoding --><br />
<TSSE>Profile 16</TSSE><br />
<br />
<!-- Custom text field. There can be more than one of these<br />
present but each must have a unique id attribute --><br />
<TXXX id="contents of neils garden"><br />
Roses, grapes, raspberries, blackberries<br />
</TXXX><br />
.<br />
<TXXX id="contents of peters garden"><br />
beans, kale, raspberries, blackberries<br />
</TXXX><br />
<br />
<!-- Commercial information url of where the thing can be bought from.<br />
There can be more than one of these present --><br />
<WCOM>http://www.aol.com/getstuff.cgi</WCOM><br />
.<br />
<WCOM>http://capitol.com/store.cgi</WCOM><br />
<br />
<!-- Website with copyright and terms of use information --><br />
<WCOP>http://www.aol.com/dontstealmusic.html</WCOP><br />
<br />
<!-- Website specific to the audio track --><br />
<WOAF>http://www.aol.com/backinussr.html</WOAF><br />
<br />
<!-- Artist / performer webpages. There can be more than one of these present --><br />
<WOAR>http://www.aol.com/paulmccartney.html</WOAR><br />
<WOAR>http://www.aol.com/johnlennon.html</WOAR><br />
.<br />
.<br />
<!-- Audio source web page --><br />
<WOAS>http://www.aol.com/beatles.html</WOAS><br />
<br />
<!-- Radio station web page --><br />
<WORS>http://shoutcast.com/search.cgi?Neil</WORS><br />
<br />
<!-- Website that allows you to pay for the file --><br />
<WPAY>http://get.com/pay.cgi?backinussr</WPAY><br />
<br />
<!-- Publishers web page --><br />
<WPUB>http://ascap.com</WPUB><br />
<br />
<!-- Custom url field. There can be more than one of these<br />
present but each must have a unique id attribute --><br />
<WXXX id="backup singers">http://yoko_ono.com</WXXX><br />
.<br />
<WXXX id="engineers">http://george_martin.com</WXXX><br />
<br />
<!-- List of people involved in audio track.<br />
There can be more than one of these present --><br />
<IPLS role="drummer">Ringo Starr</IPLS><br />
.<br />
<IPLS role="janitor">John Smith</IPLS><br />
<br />
<!-- Table of contents from the CD. The content is base64 encoded --><br />
<MCDI>000000000......</MCDI><br />
<br />
<!-- Lyrics. There can be more than one of these present --><br />
<USLT language="eng" id="verse 1"><br />
yeah yeah yeah oh baby yeah yeah yeah<br />
</USLT><br />
.<br />
<USLT language="eng" id="verse 2"><br />
oh oh oh baby baby baby<br />
</USLT><br />
<br />
<!-- General binary encapsulated object.<br />
There can be more than one of these present --><br />
<GEOB mime="application/octet" filename="foo.bar" id="whatever">02305310</GEOB><br />
.<br />
<GEOB mime="virus/binary" filename="kill.computer" id="die kitty">02305310</GEOB><br />
<br />
<!-- Play counter --><br />
<PCNT>45678</PCNT><br />
<br />
<!-- Popularimeter --><br />
<POPM><br />
<email>nradisch@panix.com</email><br />
<rating>35</rating><br />
<counter>5463767</counter><br />
</POPM><br />
<br />
<!-- Binary private data. The content is base64 encoded.<br />
There can be more than one of these present --><br />
<PRIV id="huh">2342512370</PRIV><br />
.<br />
<PRIV id="huh2">34343434</PRIV><br />
<br />
</metadata><br />
</source><br />
<br />
<br />
===Extended Specification Details===<br />
----<br />
<br />
The main section of the xml file is to provide metadata information from the source media<br />
as has been shown in the previous section. In additon to this, there is an extension for<br />
the information provided which is optional and is for providing title information for the<br />
media to follow the currently playing source media.<br />
<br />
The extended section goes instead the <metadata/> block and is formatted as follows:<br />
<br />
<source lang="xml"><br />
<extension><br />
<!-- Title of the currently playing media --><br />
<title seq="1">Artist - Title</title><br />
<title seq="2">The Next Artist - The Next Title</title><br />
.<br />
<!-- Titles go upto the maximum number of titles the source knows off --><br />
<title seq="XX">The Last Artist - The Last Title</title><br />
<br />
<!-- Title of the next item to be played --><br />
<soon>The Next Artist - The Next Title</soon><br />
</extension><br />
</source><br />
<br />
<br />
There is not a limit on how many titles can be sent though there is not much benefit of sending many titles as the SHOUTcast server is unlikely to use more than the current and the next titles. However the means to provide more titles is provided if there is a need.<br />
<br />
The format of the titles after '''seq=1''' need to be in the form of ''''artist - title'''' where it is possible to format and provide the titles in this manner, otherwise just ''''title'''' will suffice.<br />
<br />
Where possible titles for seq=1 also need to be provided in the same manner as ''''artist - title'''' though the DNAS will typically ignore this and generate the title to show clients based on the actual metadata passed. However it may resort to using this if there is an issue with the metadata provided, so ideally this title should be providing the fully formed version as well as for all other titles provided (as mentioned previously).<br />
<br />
The '''<soon/>''' block must correctly report the title of the next item to be played otherwise it must be not specified in the xml if it is not known or cannot be reliably obtained e.g. <br />
::Using older versions of Winamp (prior to v5.61) in shuffle mode, there is no ability to query the next item to be played and so <soon/> would not be set.<br />
::Using any Winamp version not in shuffle mode, then it is possible to calculate the next item and so <soon/> can be set.<br />
<br />
<br />
===Additional Notes===<br />
----<br />
<br />
The TDRC (recording time) field is used to replace the following date specifiers from the ID3v2.3 tag if found - TDAT, TYER and TIME. This is done to form 'yyyy-MM-ddTHH:mm:ss'. Additionally, if no TYER is found but TRDC is then the TYER field will be generated from the TRDC field for backwards compatibility.<br />
<br />
The TDOR (original release time) will be created from the TORY (original release year) if the TORY field is read from the file, otherwise no other mapping of these fields happens.<br />
<br />
<br />
===Suggested Fields To Support===<br />
----<br />
<br />
If an xml file is able to be created, then the minimum which can be provided is the TIT2 entry due to this being the most important information used throughout the SHOUTcast 2.0 system especially when working with legacy client connections. The following example xml shows the minimum which can be provided and is equivalent of the typical v1 style of the metadata formatted as 'artist - title' :<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<metadata><br />
<TIT2>Song Title - Song Artist</TIT2><br />
</metadata><br />
</source><br />
<br />
<br />
The typical metadata fields expected to be available from sources, though not guaranteed as the information may not be available from the source media are as follows:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Tag Name<br />
! Description<br />
|-<br />
| TIT2 || Title<br />
|-<br />
| TALB || Album<br />
|-<br />
| TPE1 || Artist<br />
|-<br />
| TYER || Year<br />
|-<br />
| COMM || Comment<br />
|-<br />
| TCON || Genre<br />
|-<br />
| TRSN || Stream Title<br />
|-<br />
| WORS || Station Website<br />
|-<br />
| TENC || Identifier for the Source e.g. SHOUTcast Source DSP Plug-in v2.1.3 042<br />
|}<br />
<br />
<br />
It can be noted that this is similar to the information available from an ID3v1 tag with some stream related additions. However this is just a recommendation which provides the client some greater flexibility over the handling of the stream metadata. If not then the least number of fields to support should ideally be TIT2, TCON, TRSN, WORS and TENC.<br />
<br />
<br />
The following example shows a complete xml metadata response with the suggested fields (excluding the [[#Extended_Specification_Details|Extended Specification Details]]):<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8" ?><br />
<metadata><br />
<TIT2>I Was Made For Lovin&apos; You</TIT2><br />
<TALB>The Very Best Of KISS</TALB><br />
<TPE1>Kiss</TPE1><br />
<TYER>2002</TYER><br />
<COMM></COMM><br />
<TCON>Hard Rock</TCON><br />
<TRSN>My Radio Station</TRSN><br />
<WORS>http://www.shoutcast.com</WORS><br />
<TENC>SHOUTcast Source DSP v2.3.1.182</TENC><br />
</metadata><br />
</source><br />
<br />
<br />
==General Comments==<br />
<br />
Anyone using the xml file should not fail if tags appear in it which have not been listed in this document. In situations where this does happen then these extra tags should just be ignored. Some of the tags not considered in this version are:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Tag Name<br />
! Description<br />
|-<br />
| MLLT || MPEG audio lookup tables for seeking<br />
|-<br />
| SYTC || Synchronized tempo codes (table of tempo changes in music and how)<br />
|-<br />
| SYLT || Synchronized lyrics<br />
|-<br />
| RVAD || Relative volume adjustment<br />
|-<br />
| EQUA || Equalization<br />
|-<br />
| RVRB || Reverb<br />
|-<br />
| RBUF || Recommended buffer size<br />
|-<br />
| AENC || Audio encryption<br />
|-<br />
| LINK || Linked ID3v2 data<br />
|-<br />
| OWNE || Date of purchase<br />
|-<br />
| COMR || Commercial purchase offers<br />
|-<br />
| ENCR || Encryption method registration<br />
|-<br />
| GRID || Group identification registration<br />
|}<br />
<br />
<br />
===GEOB - General Binary Glob===<br />
----<br />
<br />
Properties:<br />
mime - mime type<br />
filename - associated filename<br />
id = text identifier<br />
Data is base64 encoded<br />
<br />
<br />
===APIC - Picture Data===<br />
----<br />
<br />
IMPORTANT NOTE: Support of APIC in the xml file is now deprecated as of March 2011 and is instead provided as an in-stream packet of its own instead of in this.<br />
<br />
<br />
===ETCO - Event Code Field===<br />
----<br />
<br />
The ETCO tag has a format property where the supported values are:<br />
<br />
0 - absolute time in MPEG frames<br />
1 - absolute time in milliseconds<br />
<br />
The ETCO tag can have one or more event sub-tags. The type property for the event tag is the type of event we're interested in (see ID3v2 docs for list of codes). The time property is the time the event occurs in units indicated by the format property of the outer ETCO tag.<br />
<br />
<br />
===TCON - Genre Field===<br />
----<br />
<br />
TCON has a complicated internal format which consists of a series of optional genre codes stored in parenthesis which are followed by subgenre clarification strings (though everything is optional)<br />
e.g.<br />
<br />
(24)Death Metal<br />
(12)(24)Cuban<br />
(15)<br />
Die Kitty Die<br />
(24)Death Metal(12)Cuban<br />
<br />
There are also two special 'codes' where 'RX' means remix and 'CR' means cover.<br />
<br />
(24)(MX)DeathMetal<br />
(CR)Whatever<br />
<br />
Due to genre being something we care about it is parsed as indicated in the example xml.<br />
<br />
<br />
===TMED - Media Type Field===<br />
----<br />
<br />
The TMED field has a somewhat complicated internal format in that it can be just a string or it can be a media reference from a predefined list with a refinement<br />
e.g.<br />
<br />
From my album collection<br />
(VID)<br />
(VID)Stereo<br />
(TT/45)From my old 45 collection<br />
<br />
This field is not currently as important to be parsed out as with the genre (TCON) field but is provided for a more complete set of information.<br />
<br />
<br />
==Non-MP3 Field Mapping==<br />
<br />
This section covers the mapping of metadata for files other than MP3 as is supported by the the SHOUTcast 2.0 tools.<br />
<br />
<br />
===AAC===<br />
----<br />
<br />
If an ID3v2 tag is found then handling will follow the standard MP3 handling. If there is no tag then metadata guessing will be used as appropriately.<br />
<br />
<br />
===FLAC===<br />
----<br />
<br />
If there are any Vorbis comment are found in the FLAC file then the following mappings will be used to get an equivalent complement of metadata to match what is read from an ID3v2 tag:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Vorbis Comment<br />
! ID3v2 Entry<br />
! style="border-bottom-color:white; border-top-color:white; border-style:solid;" width="50" | <br />
! Vorbis Comment<br />
! ID3v2 Entry<br />
|-<br />
| TITLE || TIT2 || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || VERSION || TPE4<br />
|-<br />
| ALBUM || TALB || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || TRACKNUMBER || TRCK<br />
|-<br />
| TRACK || TRCK || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || TOTALTRACKS || TRCK<br />
|-<br />
| ARTIST || TPE1 || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || PERFORMER || TPE2<br />
|-<br />
| COPYRIGHT || TCOP || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || LICENSE || TOWN<br />
|-<br />
| ORGANIZATION || TPUB || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || ORGANISATION || TPUB<br />
|-<br />
| GENRE || TCON || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || DATE || TDRC<br />
|-<br />
| ISRC || TSRC || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || ALBUMARTIST || TPE2<br />
|-<br />
| ALBUM ARTIST || TPE2 || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || COMMENT || COMM<br />
|-<br />
| COMPOSER || TCOM || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || PUBLISHER || TPUB<br />
|-<br />
| DISCNUMBER || TPOS || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || DISKNUMBER || TPOS<br />
|-<br />
| DISC || TPOS || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || DISK || TPOS<br />
|-<br />
| TOTALDISKS || TPOS || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || TOTALDISCS || TPOS<br />
|-<br />
| BAND || TPE2 || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || LYRICS || USLT<br />
|-<br />
| CONDUCTOR || TPE3 || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || ENCODING SETTINGS || TSSE<br />
|-<br />
| ENCODER SETTINGS || TSSE || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || ENCODERSETTINGS || TSSE<br />
|-<br />
| BPM || TBPM || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || RATING || POPM<br />
|-<br />
| COVERARTMIME || APIC || style="border-bottom-color:white; border-top-color:white; border-style:solid;" | || COVERART || APIC<br />
|}<br />
<br />
<br />
Fields which are not in this list are then mapped to the custom text (TXXX) field with the key being the "description". Any picture metadata in the file will be mapped to the APIC field which is then transmitted in its own in-stream packet instead of in the xml.<br />
<br />
<br />
===OGG===<br />
----<br />
<br />
OGG files are handled in a similar manner to FLAC files though there are some differences with the them. As there is no picture metadata in OGG files the COVERARTMIME and COVERART fields will be mapped to the APIC field due to a number of programmes which generate and adding artwork to OGG files in this way.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_2_(Ultravox_2.1)_Protocol_DetailsSHOUTcast 2 (Ultravox 2.1) Protocol Details2014-10-28T22:57:21Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Overview==<br />
<br />
The SHOUTcast 2 / Ultravox 2.1 Protocol is an application level streaming protocol that will encapsulate 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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
<br />
==Ultravox Messages==<br />
<br />
The mechanism by which Ultravox is able to abstract the underlying stream encoding is to use 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.<br />
<br />
The basic Ultravox message format is:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! 1<br />
! 2<br />
! 3<br />
! 4<br />
! 5<br />
! 5<br />
! 6<br />
! 7<br />
|- align="center"<br />
| 0101 1010 || AAAA BBBB || CCCC DDDD || DDDD DDDD || EEEE EEEE || EEEE EEEE || F…………...F || 0000 0000<br />
|- align="center"<br />
| Sync || Res QoS || Class Type || || Payload Length || Payload Length || Payload || 0x00<br />
|- align="center"<br />
| [Sync byte 0x5A] || [Reserved/QoS] || [4 bit msg class] || [12 bit msg type] || [16 bit msg length - first half] || [16 bit msg length - second half] || [N byte payload] || [0x00 byte]<br />
|}<br />
<br />
Note: All values of the message are network byte order.<br />
<br />
<br />
===Sync Byte (0x5A)===<br />
----<br />
<br />
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.<br />
<br />
<br />
===Reserved (A) and QoS (B)===<br />
----<br />
<br />
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.<br />
<br />
<br />
===Message Class (C)===<br />
----<br />
<br />
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:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! scope="col" width="80" | Class<br />
! scope="col" width="150" | Type<br />
! Description<br />
|- align="center"<br />
| 0x0 || Operations || align="left" | Not Defined<br />
|- align="center"<br />
| 0x1 || Broadcaster || align="left" | Broadcaster Distribution Point<br />
|- align="center"<br />
| 0x2 || Listener || align="left" | Distribution Point Listener<br />
|- align="center"<br />
| 0x3 || Cacheable Metadata || align="left" | Broadcaster Listener via Distribution Point<br />
|- align="center"<br />
| 0x4 || Cacheable Metadata || align="left" | Broadcaster Listener via Distribution Point<br />
|- align="center"<br />
| 0x5 || Pass-through Metadata || align="left" | Broadcaster Listener via Distribution Point<br />
|- align="center"<br />
| 0x6 || Pass-through Metadata || align="left" | Broadcaster Listener via Distribution Point<br />
|- align="center"<br />
| 0x7 || Data || align="left" | Encoded data (ex: 0x7000 is MP3)<br />
|- align="center"<br />
| 0x8 || Data || align="left" | Encoded data (ex: 0x8003 is AACP)<br />
|- align="center"<br />
| 0x9 || Framed Data || align="left" | Encoded data (ex: 0x9000 is Headerless AACP)<br />
|- align="center"<br />
| 0xA || Cacheable Binary Metadata || align="left" | (Reserved for use with 0x9 if implemented)<br />
|- align="center"<br />
| 0xB-0xF || N/D || align="left" | Not Defined<br />
|}<br />
<br />
<br />
See '[[#Known_Message_Types|Known Message Types]]' for a complete list of supported or reserved message classes as well as the types related to them.<br />
<br />
<br />
===Message Type (D)===<br />
----<br />
<br />
The message type is 12 bits in the message header that specify the type of data encapsulated in the message. See 'Broadcast Messages Table' for details about the specific message types supported.<br />
<br />
<br />
===Message Length (E)===<br />
----<br />
<br />
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.<br />
The message length does not include the trailer 0x00 byte.<br />
<br />
<br />
===Payload (F)===<br />
----<br />
<br />
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.<br />
<br />
<br />
===Trailing 0x00===<br />
----<br />
<br />
The trailing 0x00 in the payload is used by the listener to determine if a message is malformed.<br />
<br />
<br />
==Broadcast Messages==<br />
<br />
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.<br />
<br />
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.<br />
<br />
The message types shown require a payload formatted according to the following criteria:<br />
* The existence of payload data is indicated by a message length > 0<br />
* All payloads for broadcaster messages are ASCIIZ strings (i.e. ASCII-encoded and terminated by a ‘\0’).<br />
* Parameters within the payload are separated by a single colon (“:”) character<br />
<br />
<br />
===Broadcast Messages Table===<br />
----<br />
<br />
Broadcast messages are defined as a 12 bit request desired to be performed:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! scope="col" width="70" | Class<br />
! scope="col" width="70" | Type<br />
! Description<br />
! scope="col" width="70" | Required?<br />
! scope="col" width="70" | Payload?<br />
! scope="col" width="70" | Response?<br />
|- align="center"<br />
| 0x1 || 0x000 || N/D || N/A || N/A || N/A<br />
|- align="center"<br />
| 0x1 || 0x001 || Authenticate Broadcast || Yes || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x002 || Setup Broadcast || Yes || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x003 || Negotiate Buffer Size || Yes || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x004 || Standby || Yes || No || Yes<br />
|- align="center"<br />
| 0x1 || 0x005 || Terminate || No || No || No<br />
|- align="center"<br />
| 0x1 || 0x006 || Flush Cached Metadata || No || No || No<br />
|- align="center"<br />
| 0x1 || 0x007 || Require Listener Auth || No || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x008 || Negotiate Max Payload Size || Yes || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x009 || Request Cipher || Yes || No || Yes<br />
|- align="center"<br />
| 0x1 || 0x040 || Stream Mime Type || Yes || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x050 || File Transfer Begin || No || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x051 || File Transfer Begin || No || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x100 || Configure ICY-NAME || No || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x101 || Configure ICYGENRE || No || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x102 || Configure ICYURL || No || Yes || Yes<br />
|- align="center"<br />
| 0x1 || 0x103 || Configure ICYPUB || No || Yes || Yes<br />
|}<br />
<br />
Message types 0x100 to 0x103 are used to configure properties for a SHOUTcast<br />
1.8 stream, should the distribution point support SHOUTcast listeners.<br />
<br />
<br />
==Communication Stages==<br />
<br />
There are six major phases of broadcaster communication with the distribution point:<br />
<br />
* Cipher Key Exchange<br />
* Connect / Authentication<br />
* Stream Configuration<br />
* Intro / Backup File Transfer<br />
* Standby / Data Transfer<br />
* Broadcast Termination<br />
<br />
<br />
===Cipher Key Exchange===<br />
----<br />
<br />
In Ultravox 2.1, the UID and Auth-Blob fields of message type 0x1001 (Authenticate Broadcast) are encrypted using the XTEA algorithm. When the broadcaster and server connect, the broadcaster requests the cipher by sending the 0x1009 message. This allows the server to distinguish between Ultravox 2.0 and Ultravox 2.1 (Ultravox 2 begins with the Authenticate message - 0x1001) the server response message contains a null terminated string of a maximum length of 16 bytes (128 bits). This is the cipher key, and is used to encrypt the UID and Auth-Blob fields of message type 0x1001.<br />
<br />
Because the UID and Auth-blob fields are colon seperated, we do not use the result of the XTEA algorithm directly. It is possible that the direct output of the XTEA algorithm could have a colon in it, which would cause a parsing error of message 0x1001. Instead we use the result of the XTEA algorithm as a series of 32 bit hex digits.<br />
<br />
<br />
C++ code for encoding and decoding:<br />
<br />
<source lang="cpp"><br />
// from wikipedia. Slightly modified to be 32/64 bit clean<br />
static void XTEA_encipher(__uint32* v, __uint32* k,unsigned int num_rounds = 32) <br />
{<br />
__uint32 v0=v[0], v1=v[1], i;<br />
__uint32 sum=0, delta=0x9E3779B9;<br />
for(i=0; i<num_rounds; i++) <br />
{<br />
v0 += (((v1 << 4) ^ (v1 >> 5)) + v1) ^ (sum + k[sum & 3]);<br />
sum += delta;<br />
v1 += (((v0 << 4) ^ (v0 >> 5)) + v0) ^ (sum + k[(sum>>11) & 3]);<br />
}<br />
v[0]=v0; v[1]=v1;<br />
}<br />
<br />
static void XTEA_decipher(__uint32* v, __uint32* k,unsigned int num_rounds = 32) <br />
{<br />
__uint32 v0=v[0], v1=v[1], i;<br />
__uint32 delta=0x9E3779B9, sum=delta*num_rounds;<br />
<br />
for(i=0; i<num_rounds; i++) <br />
{<br />
v1 -= (((v0 << 4) ^ (v0 >> 5)) + v0) ^ (sum + k[(sum>>11) & 3]);<br />
sum -= delta;<br />
v0 -= (((v1 << 4) ^ (v1 >> 5)) + v1) ^ (sum + k[sum & 3]);<br />
}<br />
v[0]=v0; v[1]=v1;<br />
}<br />
<br />
static __uint32 fourCharsToLong(__uint8 *s)<br />
{<br />
__uint32 l = 0;<br />
l |= s[0]; l <<= 8;<br />
l |= s[1]; l <<= 8;<br />
l |= s[2]; l <<= 8;<br />
l |= s[3];<br />
return l;<br />
}<br />
<br />
static void longToFourChars(__uint32 l,__uint8 *r)<br />
{<br />
r[3] = l & 0xff; l >>= 8;<br />
r[2] = l & 0xff; l >>= 8;<br />
r[1] = l & 0xff; l >>= 8;<br />
r[0] = l & 0xff; l >>= 8;<br />
}<br />
<br />
#define XTEA_KEY_PAD 0<br />
#define XTEA_DATA_PAD 0<br />
<br />
static string XTEA_encipher(const __uint8* c_data,size_t c_data_cnt,<br />
const __uint8* c_key,size_t c_key_cnt) throw()<br />
{<br />
ostringstream oss;<br />
<br />
vector<__uint8> key(c_key,c_key + c_key_cnt);<br />
vector<__uint8> data(c_data,c_data + c_data_cnt);<br />
<br />
// key is always 128 bits<br />
if(key.size() < 16) key.resize(16, XTEA_KEY_PAD); // pad key with zero<br />
__uint32 k[4] = { fourCharsToLong(&key[0]),fourCharsToLong(&key[4]),<br />
fourCharsToLong(&key[8]),fourCharsToLong(&key[12])<br />
};<br />
<br />
// data is multiple of 64 bits<br />
size_t siz = data.size();<br />
if(siz % 8) { siz+= 8 - siz % 8; data.resize(siz, XTEA_DATA_PAD);} // pad data with zero<br />
<br />
for(size_t x = 0; x < siz; x+=8)<br />
{<br />
__uint32 v[2];<br />
v[0] = fourCharsToLong(&data[x]);<br />
v[1] = fourCharsToLong(&data[x+4]);<br />
XTEA_encipher(v,k);<br />
oss << setw(8) << setfill('0') << hex << v[0];<br />
oss << setw(8) << setfill('0') << hex << v[1]; // hex values.<br />
// uvox uses colon as separator so we can't use chars for fear of collision<br />
}<br />
return oss.str();<br />
}<br />
<br />
static utf8 XTEA_decipher(const __uint8* c_data,size_t c_data_cnt,<br />
const __uint8* c_key,size_t c_key_cnt) throw()<br />
{<br />
utf8 result;<br />
<br />
vector<__uint8> key(c_key,c_key + c_key_cnt);<br />
vector<__uint8> data(c_data,c_data + c_data_cnt);<br />
<br />
// key is always 128 bits<br />
if(key.size() < 16) key.resize(16, XTEA_KEY_PAD); // pad key with zero<br />
__uint32 k[4] = { fourCharsToLong(&key[0]),fourCharsToLong(&key[4]),<br />
fourCharsToLong(&key[8]),fourCharsToLong(&key[12])<br />
};<br />
<br />
// data is multiple of 16 hex digits<br />
size_t siz = data.size();<br />
assert(!(siz % 16)); // should never happen if data is good<br />
if(siz % 16) { siz+= 8 - siz % 8; data.resize(siz, '0');} // pad data with zero<br />
<br />
for(size_t x = 0; x < siz; x+=16)<br />
{<br />
__uint32 v[2];<br />
<br />
sscanf((const char *)&data[x],"%8x",&v[0]);<br />
sscanf((const char *)&data[x+8],"%8x",&v[1]);<br />
XTEA_decipher(v,k);<br />
__uint8 ur[5] = {0,0,0,0,0 };<br />
longToFourChars(v[0],ur);<br />
result += ur;<br />
longToFourChars(v[1],ur);<br />
result += ur;<br />
}<br />
return result;<br />
}<br />
</source><br />
<br />
<br />
===Connect / Authentication===<br />
----<br />
<br />
====Request Cipher====<br />
----<br />
<br />
The broadcaster makes a connection to the distribution point and requests the cipher key.<br />
<br />
Message Class – 0x1<br />
Message Type – 0x009<br />
Payload – <Version><NUL><br />
<Version> - 2.1.<br />
<NUL> - ASCII 0x00<br />
<br />
Reponses are:<br />
<br />
ACK:<cipherkey>\0<br />
or:<br />
NAK:<Reason>\0<br />
<br />
<br />
====Broadcast Authentication Request====<br />
----<br />
<br />
The broadcaster makes a connection to the distribution point and must issue an authentication request. The authentication request payload looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x001<br />
Payload – <Version>:<SID>:<UID>:<AuthBlob><NUL><br />
<Version> - protocol version number (required, numeric, non-zero, maximum 255). The current version is 2.1.<br />
<SID> - stream identifier (required, numeric, non-zero, maximum 2147483647).<br />
<UID> - user identifier (required, XTEA encoded).<br />
<AuthBlob> - authentication information (required, XTEA encoded).<br />
<NUL> - ASCII 0x00<br />
<br />
Since this is the first message required by the distribution point, it contains a version number that can be used by the distribution point to handle future versions of the protocol specification. The distribution point will disconnect the broadcaster if the version is not supported. <br />
<br />
The distribution point also has the possibility of using the provided authentication credentials to verify the authenticity of the broadcaster. If the broadcaster is successfully authenticated, the distribution point responds with an Authenticate Broadcast message with a payload that looks like:<br />
<br />
ACK:<Version>:Allow\0<br />
<br />
If the broadcaster fails authentication, the distribution point responds with an Authenticate Broadcast message that looks like:<br />
<br />
NAK:<Version>:<Reason>\0<br />
<br />
<br />
Valid reasons for a failed authentication are as follows:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Deny” || Broadcaster denied by authentication service.<br />
|-<br />
| “Sequence Error” || The message was received out of sequence.<br />
|-<br />
| “Parse Error” || The payload could not be parsed successfully.<br />
|-<br />
| “Version Error” || The version is greater than what is supported.<br />
|-<br />
| “Stream ID Error” || The stream identifier is out of the supported range (1 - 2147483647).<br />
|-<br />
| “Stream Moved” || The stream is configured as having been moved from the server.<br />
|}<br />
<br />
Following a NAK response to a Broadcast Authenticate response, the distribution point should terminate the connection.<br />
<br />
The completion of the authentication request and response signals moving onto the stream configuration phase.<br />
<br />
<br />
===Stream Configuration===<br />
----<br />
<br />
The stream configuration requests sent by the broadcaster can come in any sequence with the restrictions listed above in 'Broadcast Messages Table'.<br />
<br />
<br />
====Stream Mime Type====<br />
----<br />
<br />
This message indicates the mime type of the stream that will be transmitted in this session.<br />
<br />
Message Class – 0x1<br />
Message Type – 0x040<br />
Payload – <mimetype><NUL><br />
Possible mime types are<br />
audio/mpeg<br />
audio/aacp<br />
audio/aac<br />
audio/ogg<br />
<NUL> - ASCII 0x00<br />
<br />
If the mime type is valid, the distribution point sends a Stream Mime Type message back to the broadcaster with a message payload of “ACK\0” (Length=4). However if the distribution point rejects the broadcaster information it may respond with a Stream Mime Type message with a message payload of “NAK:<Reason>\0” <br />
<br />
<br />
====Setup Broadcast====<br />
----<br />
<br />
The setup broadcast message contains details about the stream that the broadcaster will feed through the distribution point. It includes the Content-Type of the stream. It is the responsibility of the distribution point to pass this information to listeners during a listener request for this stream. It also contains the average bitrate and maximum bitrate of the stream, allowing for the possibility of variable bitrate streams. For fixed bitrate streams, the average bitrate will equal the maximum bitrate.<br />
<br />
The setup broadcast request looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x002<br />
Payload – <Avg Bit Rate>:<Max Bit Rate><NUL><br />
<Avg Bit Rate> – average bit rate (required, numeric, maximum 320, kbps).<br />
<Max Bit Rate> – maximum bit rate (required, numeric, maximum 320, kbps).<br />
<NUL> - ASCII 0x00<br />
<br />
If the broadcast setup is successfully configured with the given values, the distribution point sends a Broadcast Setup message back to the broadcaster with a message payload of “ACK\0” (Length=4). However if the broadcaster rejects the broadcaster information it may respond with a Broadcast Setup message with a message payload of “NAK:<Reason>\0” (with the corresponding Length) where the reasons are:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Sequence Error” || The message was received out of sequence.<br />
|-<br />
| “Parse Error” || The payload could not be parsed successfully.<br />
|-<br />
| “Bit Rate Error” || The bit rate is not valid or not supported.<br />
|}<br />
<br />
<br />
====Negotiate Buffer Size====<br />
----<br />
<br />
Inherently, the distribution point will have some internal buffer for Ultravox Messages that it uses to source listener streams. The Negotiate Buffer Size message allows the broadcaster and distribution point to communicate some properties of that buffering mechanism. The broadcaster can ask the distribution point to setup a buffer of a specific size with a minimum threshold. The distribution point could otherwise have an internal buffer size defined that is too small for the amount of stream data, making it very likely that listeners of the stream will receive a poor experience.<br />
<br />
The Negotiate Buffer Size message looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x003<br />
Payload – <Desired Buffer Size>:<Minimum Buffer Size><NUL><br />
<Desired Buffer Size> – desired buffer size (required, numeric, in units of KB).<br />
<Minimum Buffer Size> – minimum buffer size (required, numeric, in units of KB).<br />
<NUL> - ASCII 0x00<br />
<br />
If the distribution point supports a buffer size greater than the minimum buffer size, it responds with a Negotiate Buffer size message with payload “ACK:<negotiated buffer size>\0”. The negotiated buffer size value is in units of KB. However, a failure to be able to provide an adequate buffer size results in the distribution point responding with a Negotiate buffer size message with payload “NAK:<Reason>\0”. Possible reasons are:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Sequence Error.” || The message was received out of sequence.<br />
|-<br />
| “Parse Error.” || The payload could not be parsed successfully.<br />
|-<br />
| “Buffer Size Error.” || The buffer size is not valid or not supported.<br />
|}<br />
<br />
The return string consists of the trail period ‘.’<br />
<br />
<br />
====Configure ICY-NAME====<br />
----<br />
<br />
In order to support SHOUTcast 1.8.x audio streams the protocol has adapted to give the distribution point the necessary information. The first of these messages allows the broadcaster the ability to configure the “icy-name” variable. This message is optional and doesn’t apply to distribution points that are not concerned with SHOUTcast 1.8.x compatibility for audio streams. The payload of the Configure ICY-NAME message looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x100<br />
Payload – <ICYNAME><NUL><br />
<ICY-NAME> - value (no limit, utf8 encoded).<br />
<NUL> - ASCII 0x00<br />
<br />
If the Distribution point successfully sets the value, it replies to the broadcaster by sending the ICY-NAME message with a payload of “ACK\0” (Length=4). Otherwise, it replies by sending the ICY-NAME message with a payload of “NAK:<Reason>\0”. Possible reasons for a NAK are:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Sequence Error” || The message was not received during the configuration phase.<br />
|-<br />
| “Parse Error” || The payload could not be parsed successfully.<br />
|-<br />
| “Compatibility mode not enabled” || SHOUTcast compatibility-mode is not enabled.<br />
|}<br />
<br />
<br />
====Configure ICYGENRE====<br />
----<br />
<br />
In order to support SHOUTcast 1.8.x audio streams the protocol has adapted to give the distribution point the necessary information. The first of these messages allows the broadcaster the ability to configure the “icy-genre” variable. This message is optional and doesn’t apply to distribution points that are not concerned with SHOUTcast 1.8.x compatibility for audio streams. The payload of the Configure ICY-GENRE message looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x101<br />
Payload – <ICYGENRE><NUL><br />
<ICY-GENRE> - value (no limit. utf8 encoded).<br />
<NUL> - ASCII 0x00<br />
<br />
If the distribution point successfully sets the value, it replies to the broadcaster by sending the Configure ICYGENRE message with a payload of “ACK\0” (Length=4). Otherwise, it replies by sending the Configure ICYGENRE message with a payload of “NAK:<Reason>\0”. Possible reasons for a NAK are:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Sequence Error” || The message was not received during the configuration phase.<br />
|-<br />
| “Parse Error” || The payload could not be parsed successfully.<br />
|-<br />
| “Compatibility mode not enabled” || SHOUTcast compatibility-mode is not enabled.<br />
|}<br />
<br />
<br />
====Configure ICYURL====<br />
----<br />
<br />
In order to support SHOUTcast 1.8.x audio streams the protocol has adapted to give the distribution point the necessary information. The first of these messages allows the broadcaster the ability to configure the “icy-url” variable. This message is optional and doesn’t apply to distribution points that are not concerned with SHOUTcast 1.8.x compatibility for audio streams. The payload of the Configure ICY-URL message looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x102<br />
Payload – <ICYURL><NUL><br />
<ICY-URL> - value (no limit, utf8 encoded).<br />
<NUL> - ASCII 0x00<br />
<br />
If the distribution point successfully sets the value, it replies to the broadcaster by sending the Configure ICYURL message with a payload of “ACK\0” (Length=4). Otherwise, it replies by sending the Configure ICYURL message with a payload of “NAK:<Reason>\0” (with the corresponding Length):<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Sequence Error” || The message was not received during the configuration phase.<br />
|-<br />
| “Parse Error” || The payload could not be parsed successfully.<br />
|-<br />
| “Compatibility mode not enabled” || SHOUTcast compatibility-mode is not enabled.<br />
|}<br />
<br />
<br />
====Configure ICYPUB====<br />
----<br />
<br />
In order to support SHOUTcast 1.8.x audio streams the protocol has adapted to give the distribution point the necessary information. The first of these messages allows the broadcaster the ability to configure the “icy-pub” variable. This message is optional and doesn’t apply to distribution points that are not concerned with SHOUTcast 1.8.x compatibility for audio streams. The payload of the Configure ICY-PUB message looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x103<br />
Payload – <ICYPUB><NUL><br />
<ICY-PUB> - value (required, numeric, either 0 or 1).<br />
<NUL> - ASCII 0x00<br />
<br />
If the distribution point successfully sets the value, it replies to the broadcaster by sending the Configure ICYPUB message with a payload of “ACK\0” (Length=4). Otherwise, it replies by sending the Configure ICYPUB message with a payload of “NAK:<Reason>\0” (with the corresponding Length):<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Sequence Error” || The message was not received during the configuration phase.<br />
|-<br />
| “Parse Error” || The payload could not be parsed successfully.<br />
|-<br />
| “Compatibility mode not enabled” || SHOUTcast compatibility-mode is not enabled.<br />
|}<br />
<br />
<br />
===Intro / Backup File Transfer===<br />
----<br />
<br />
The distribution point can contain special files. "Intro" files are played whenever a listener connects to the station. "Backup" files are played if contact with the broadcaster is lost. These files can be transfered to the distribution point using the File Transfer Begin / Data messages. The mime-type and bitrate for the file must match the configuration for streaming. These messages may appear at any point once streaming begins.<br />
<br />
<br />
====File Transfer Begin====<br />
----<br />
<br />
When the broadcaster is ready to send one of the special files, it starts by sending the File transfer begin message, which indicates what type of file is being sent.<br />
<br />
Message Class - 0x1<br />
Message Type - 0x050<br />
Payload - <type>:<size in bytes>NUL<br />
Type is one of:<br />
intro<br />
backup<br />
Size in bytes is the number of bytes in the file that is to be transmitted.<br />
<br />
The distribution point responds with ACK\0 or NAK:<reason>\0<br />
If a File transfer begin message is received before all the data for a prior begin has been received, then the prior transfer is considered corrupt and should be ignored.<br />
<br />
<br />
====File Transfer Data====<br />
----<br />
<br />
One or more of these messages follow a successful File transfer begin message. The payload of the message is the data of the file being transfered. More than one of these messages are required if the file contents do not fit in the payload limits negotiated during the stream configuration phase.<br />
<br />
Message Class - 0x1<br />
Message Type - 0x051<br />
Payload - binary data<br />
<br />
The distribution does not send a response to this message<br />
<br />
<br />
===Standby / Data transfer===<br />
----<br />
<br />
<br />
====Standby====<br />
----<br />
<br />
When the broadcaster is done sending configuration requests and is ready to begin streaming, it sends Standby message to the distribution point. This message has no payload and looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x004<br />
Payload - <empty><br />
<br />
It is the responsibility of the distribution point to make sure all required configuration and authentication messages have been processed successfully. If the distribution point has completed setup successfully and is ready to accept stream data from the broadcaster, it responds with a Standby message with payload “ACK:Data transfer mode\0”. If the setup of the broadcaster has not been completed or there is a problem the distribution point responds “NAK:<Reason>\0”. Possible reasons are:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Sequence Error” || The message was received out of sequence.<br />
|-<br />
| “Parse Error” || The payload could not be parsed successfully.<br />
|-<br />
| “Configuration Error” || The configuration is not complete.<br />
|-<br />
| “Stream In Use” || The distribution point cannot accept the broadcaster.<br />
|}<br />
<br />
<br />
====Flush Cached Metadata====<br />
----<br />
<br />
Information associated with a stream may be passed in metadata messages through the distribution point. Some of these messages may be cached in the distribution point. This message informs the distribution point to throw out existing cached metadata messages. This message has no payload and looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x006<br />
Payload - <empty><br />
<br />
The distribution point responds with a Flush Cached Metadata message with payload “ACK\0” or if there is a problem the distribution point responds “NAK:<Reason>\0”.<br />
<br />
Please refer to the Metadata Message section for full details on how the distribution point will handle metadata.<br />
<br />
<br />
====Require Listener Authentication====<br />
----<br />
<br />
The disctribution point and the broadcaster need to agree on a maximum payload size. This message allows the broadcaster to specify it’s desired Max message and a lower-limit:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x007<br />
Payload - <Ultravox Requirement >:<SHOUTcast Requirement ><NULL><br />
<Ultravox Requirement > – (required, character, ‘Y’, ‘N’, or ‘D’).<br />
<SHOUTcast Requirement> – (required, character, ‘Y’, ‘N’, or ‘D’).<br />
<NUL> - ASCII 0x00<br />
<br />
This request provides the broadcaster with the ability to specify an authentication requirement different from the configured default. If the distribution point successfully sets the authentication requirements, it replies to the broadcaster by sending the Error! Reference source not found. message with a payload of “ACK\0”. Otherwise, it replies by sending the Error! Reference source not found. message with a payload of “NAK:<Reason>\0” (with the corresponding Length):<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Sequence Error” || The message was received out of sequence.<br />
|-<br />
| “Parse Error” || The payload could not be parsed successfully.<br />
|}<br />
<br />
<br />
====Negotiate Max Payload Size====<br />
----<br />
<br />
The distribution point and the broadcaster need to agree on a maximum payload size. This message allows the broadcaster to specify it’s desired Max message and a lower-limit:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x008<br />
Payload - <desired max-payload size>:<minimum acceptable max-payload size><NUL><br />
<br />
If the Max Payload Size negotiation is successfully configured with the given values, the distribution point sends a Broadcast Setup message back to the broadcaster with a message payload of “ACK:<negotiated max-payload size>\0”.<br />
<br />
However if the broadcaster rejects the broadcaster information it may respond with a Negotiate Max Payload Size message with a message payload of “NAK:<Reason>\0” (with the corresponding Length) where the reasons are:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Reason<br />
! Description<br />
|-<br />
| “Sequence Error” || The message was received out of sequence.<br />
|-<br />
| “Parse Error” || The payload could not be parsed successfully.<br />
|-<br />
| “Payload Size Error” || The minimum acceptable max-payload size is not supported<br />
|}<br />
<br />
The maximum acceptable payload size is 16377 bytes. The value is derived from 16 * 1024 – 6 – 1, which translated to 16k minus 6, the number of header bytes and 1, the null terminator byte.<br />
<br />
<br />
===Broadcast Termination===<br />
----<br />
<br />
<br />
====Terminate Broadcast Message====<br />
----<br />
<br />
During Data Transfer Mode the broadcaster may decide to close the connection to the distribution point. For clean handling of a disconnect the broadcaster will send a Terminate Broadcast message. The distribution point will not expect any messages following a Terminate Broadcast message and will unsubscribe any listeners and terminate the stream, freeing its resources. The message looks like:<br />
<br />
Message Class – 0x1<br />
Message Type – 0x005<br />
Payload - <empty><br />
<br />
<br />
===Listener Messages===<br />
----<br />
<br />
Listener messages are messages originating from the distribution point and received by the listener. These messages are often informative and the listener does not send responses. The messages of this class do not have any payload, however it is possible that future messages in this class could.<br />
<br />
<br />
====Temporary Broadcast Interruption====<br />
----<br />
<br />
There are other circumstances that may cause the broadcast to become unavailable. The distribution point may detect these occurrences. If broadcast unavailability is detected, the distribution point can send a Temporary Broadcast Interruption message to the listener while it attempts to recover the broadcast. The Temporary Broadcast Interruption message looks like:<br />
<br />
Message Class – 0x2<br />
Message Type – 0x001<br />
Payload - <empty><br />
<br />
<br />
====Broadcast Termination====<br />
----<br />
<br />
This message is sent to a listener when the stream they are subscribed is terminating. The distribution point sends the message to all listeners subscribed to the terminating stream and then closes the connection. The broadcast termination message looks like:<br />
<br />
Message Class – 0x2<br />
Message Type – 0x002<br />
Payload - <empty><br />
<br />
<br />
====Broadcast Failover====<br />
----<br />
<br />
When a listener fails over to a new stream, it will receive an indication that they have failed over. This indication includes the operating parameters of the new stream, and the cacheable metadata from the new stream as if they have just joined.<br />
<br />
Here is the sent data after a broadcast failover:<br />
<br />
* An indication that a broadcast fail condition has occurred (0x2003)<br />
<br />
* Stream parameters:<br />
Avg BPS - As the new broadcaster may be broadcasting at a different rate.<br />
Max BPS – As the new broadcaster may be broadcasting at a different rate.<br />
Ultravox-Max-Msg value - Since this is used for reset detection and recovery, and is<br />
set by the broadcaster; this can change from broadcaster to broadcaster.<br />
<br />
* The next message follow should be a cacheable metadata as if it were joining a new stream.<br />
Message Class – 0x2<br />
Message Type – 0x003<br />
Payload - <New SID>:music/ultravox:<Avg BPS>:<Max BPS>:<Ultravox-Max-Msg><br />
<br />
<br />
==Metadata==<br />
<br />
Metadata is any information associated with a stream to be interpreted by the listener. Examples of metadata include Stream-Title, Stream-URL (web-site content related to the streamed content), Stream-Image(binary data), etc. Metadata information should flow over the same data path as stream data. The reason for this is that web proxies and firewalls often prevent for easy management of multiple data connections. It is the responsibility of the broadcaster not to saturate a stream with too much metadata. Doing so will create a poor listener experience that could be avoided by intelligent management of metadata.<br />
<br />
Metadata originates from a broadcaster and is passed through the distribution point for handling by the listener. It is sent relatively rarely in comparison to the stream data. For example, an audio stream might have a metadata message that indicates a change in the song title. If a listener subscribes to the stream just after the song-change metadata has passed, the listener won’t know the name of the song they are listening to until the next song change. Therefore the protocol distinguishes two types of metadata.<br />
<br />
Cachable metadata is vital to the stream and the listener should always have the most recent cachable metadata. Pass-thru metadata is stream-associated data that is nice to have and that the listener won’t mind waiting for.<br />
<br />
<br />
===Cachable Metadata===<br />
----<br />
<br />
Cachable metadata requires the distribution point to cache metadata messages and pass them down to the listener upon listener connects. Therefore, the point in the stream buffer at which data is cached should coincide with where a listener is placed in the stream buffer on a listener connect. Cached metadata messages are also included in the data stream to the listener during normal streaming. This ensures that listeners have the most recent cached metadata both at the beginning of a streaming session and at all times afterward. Metadata messages looks like:<br />
<br />
Message Class – 0x3 or 0x4<br />
Message Type - <metadata type><br />
Payload – [Metadata ID][Metadata Span][Metadata Index][metadata]<br />
[Metadata ID] (16bits) - Used to identify a metadata set for when metadata is split across multiple Ultravox messages (numeric, minimum 1, maximum 32).<br />
[Metadata Span] (16 bits) - the number of messages comprising the complete metadata package (numeric, minimum 1, maximum 32).<br />
[Metadata Index] (16 bits) - the ordinal identification of this message within the metadata package (numeric, minimum 1, maximum 32).<br />
[Metadata] – the metadata information.<br />
<br />
As you can see from the sequencing system, metadata may be split into multiple messages. Multiple metadata messages of the same type and metadata ID can be combined and interpreted by a listener as a single piece of metadata. Similarly the distribution point will need to understand this in order to properly cache fragmented metadata. If for a given message type, a message is received whose index is already cached, the distribution point should remove all the messages it has cached for that message type and then caches the new message.<br />
<br />
<br />
===Pass-thru Metadata===<br />
----<br />
<br />
These messages take the same form as Cachable metadata with message classes of either 0x5 or 0x6. However, the distribution point simply treats these messages like data messages and passes them directly to the listeners.<br />
<br />
<br />
==Broadcast Connection Handling==<br />
<br />
<br />
The following connection handling support is recommended:<br />
<br />
===Normal Termination===<br />
----<br />
<br />
Normally, the broadcaster stops providing a stream by sending the Terminate message to the distribution point, thereby making the stream no longer available for subscription by listeners. All other circumstances (specifically idle-timeout and reconnect-timeout) that result in the termination of a stream are considered abnormal. <br />
<br />
When a stream terminates normally, the distribution point informs all listeners currently subscribed to the stream that the stream is terminated by sending them a Broadcast Terminate message.<br />
<br />
<br />
===Idle Timeout===<br />
----<br />
<br />
If the distribution point does not receive either a data or metadata message while in Data Streaming mode for some time, it may enforce an Idle Timeout. Idle timeout occurs and the distribution point disconnects the broadcaster and abnormally terminates the stream it was providing. This is a recommendation for connection handling and not a requirement for protocol compatability.<br />
<br />
<br />
===Reconnect Timeout===<br />
----<br />
<br />
If the TCP connection to a broadcaster is unexpectedly lost, the distribution point may allow the broadcaster an interval of time to reconnect and re-establish the stream. Any number of reasons might cause this to happen including network glitch, software error, etc. The broadcaster has the option to re-establish the stream by sending the Authenticate Broadcast (0x1001) message. However if the distribution point detects that the broadcaster is reconnecting, it can choose to respond with an ACK message for the Standby(0x1004) message. The configuration phase will be skipped and the broadcaster can resume streaming in data transfer mode. The distribution point should only send 0x1004 if the previous broadcast had completed its configuration phase.<br />
<br />
If the broadcaster does not reconnect and re-establish the stream, reconnect timeout occurs and the distribution point abnormally terminates the stream the broadcaster was providing. This is a suggested feature for the distribution point but should be handled by broadcasters.<br />
<br />
<br />
<br />
==Ultravox Listener Protocol==<br />
<br />
The Ultravox Listener Protocol is the handshaking necessary for an Ultravox listener to connect, setup, and terminate a streaming session. The protocol is based on the HTTP protocol to allow listeners behind firewalls and proxies to make a request without additional configuration or security clearance. The Ultravox listener represents a new type of software that can interpret and properly handle Ultravox messages. Ultravox listeners are recognized by the presence of the sub-string “ultravox/1.0” in the “UserAgent” header of the initial HTTP GET request.<br />
<br />
<br />
===Listen Request===<br />
----<br />
<br />
As part of the protocol, a listener supplies the SID to identify the stream of interest to the distribution point. An Ultravox Listen request looks like:<br />
<br />
GET /{path} HTTP/1.0\r\n<br />
Host: ultravox.aol.com\r\n<br />
UserAgent: Ultravox/2.1\r\n<br />
Accept: */*\r\n<br />
…<br />
\r\n<br />
<br />
The user agent is important. The version of sc_serv that supports Shoutcast 2.0, looks for the string "Ultravox/2.1" in the user agent. If the string is found anywhere in the user agent, then Shoutcast 2.0 is assumed, otherwise the server will downgrade to Shoutcast 1.<br />
<br />
If the distribution point accepts the connection, authenticates the listener, and sets up a streaming session for the listener, it responds with:<br />
<br />
HTTP/1.1 200 OK\r\n<br />
Server:Ultravox/2.1 SHOUTcast v2.0.0.29\r\n<br />
ContentType:misc/ultravox\r\n<br />
icy-pub:<public flag>\r\n<br />
Ultravox-Bitrate:<stream bitrate>\r\n<br />
Ultravox-Title:<stream title>\r\n<br />
Ultravox-Genre:<stream genre>\r\n<br />
Ultravox-URL:<broadcaster url>\r\n<br />
Ultravox-Max-Msg:<negotiated max payload size>\r\n<br />
Ultravox-Class-Type:<class-type>\r\n<br />
<br />
where the “negotiated max payload size”, “stream title”, “stream bitrate”, and “class-type” are populated based on the values provided during broadcast negotiation.<br />
<br />
“server” returns at least 'Ultravox/2.1' but usually also includes the version of the server or any other information which is deemed of use to provide to the listener.<br />
<br />
class-type is a hexadecimal representation like “7000” for an MP3 (audio/mpeg) stream.<br />
<br />
The following are a list of possible responses for a Listen connection:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! Response<br />
! Description<br />
|-<br />
| “HTTP/1.1 200 OK” || Authentication allowed<br />
|-<br />
| “HTTP/1.1 400 Bad Request” || Request can not be parsed<br />
|-<br />
| “HTTP/1.1 403 Forbidden” || Authentication denied<br />
|-<br />
| “HTTP/1.1 404 Not Found” || Stream not available<br />
|}<br />
<br />
<br />
===Prebuffering===<br />
----<br />
<br />
Prebuffering is the mechanism by which the listener is ensured a smooth streaming experience. Since network conditions may change quickly and fluctuate over the duration of a streaming session, the distribution point sends some data to the listener at the beginning of the streaming session to be used to pad the listening experience. Stream data is then inserted behind the buffered data while the listener reads data from the front of the buffer. To setup the listen session more quickly, the prebuffer data can be sent at an accelerated rate. However, the distribution point should respect the listener’s TCP window when sending at an accelerated rate and make sure to account for TCP slow start. The amount of data sent in the prebuffer phase is determined by the number of seconds specified by the prebuffer time argument in the HTTP GET request. If the prebuffertime is not provided the distribution point will make an assumption about the prebuffersize. A prebuffer time of zero means that no data is prebuffered.<br />
<br />
<br />
===Resetting===<br />
----<br />
<br />
If the listener is not able to keep up with the bitrate of the stream, it falls behind. If the listener falls far behind, the distribution point must overwrite stream data that the listener has not yet received. It is at this time that the distribution point must reset the listener, skipping them ahead in the stream data.<br />
<br />
It is possible (depending on implementation) that Ultravox message boundaries could be corrupted while moving the listener’s pointer inside of the buffer such that the listener receives corrupt data on a reset. The distribution point is not required to abide by message boundaries when moving the listener, however it’s recommended.<br />
<br />
The mechanism for resynchronization is handled entirely by the client based on the following:<br />
* Ultravox-Max-Msg value<br />
* Message length<br />
* Trailing 0x00 byte<br />
* 5A sync byte<br />
<br />
The methodology is as follows:<br />
# If message starts with 0x5A, read payload length.<br />
# If length is greater than Ultravox-Max-Msg, then search for next 5A sync byte and start over.<br />
# Read in enough bytes to check the trailer 0x00 after the payload<br />
# If 0x00 is not present, search from the beginning of the bogus message to the next 5A and start over.<br />
# Otherwise, extract the payload and continue reading and extracting ultravox messages.<br />
<br />
<br />
==Known Message Types==<br />
<br />
The following is the listing of known messages (split into class and type) which are either in active usage with currently implemented versions of the protocol or have been specified as reserved to enable future usage or expansion of the protocol usage.<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
! scope="col" width="70" | Class<br />
! scope="col" width="70" | Type<br />
! Description<br />
|- align="center" style="background:#efefef;"<br />
| 0x0 || || align="left" | Operations<br />
|- align="center" style="background:#efefef;"<br />
| 0x1 || || align="left" | Broadcaster<br />
|- align="center"<br />
| 0x1 || 0x001 || align="left" | Authenticate Broadcast<br />
|- align="center"<br />
| 0x1 || 0x002 || align="left" | Setup Broadcast<br />
|- align="center"<br />
| 0x1 || 0x003 || align="left" | Negotiate Buffer Size<br />
|- align="center"<br />
| 0x1 || 0x004 || align="left" | Standby<br />
|- align="center"<br />
| 0x1 || 0x005 || align="left" | Terminate<br />
|- align="center"<br />
| 0x1 || 0x006 || align="left" | Flush Cached Metadata<br />
|- align="center"<br />
| 0x1 || 0x007 || align="left" | Require Listener Auth<br />
|- align="center"<br />
| 0x1 || 0x008 || align="left" | Negotiate Max Payload Size<br />
|- align="center"<br />
| 0x1 || 0x009 || align="left" | Request Cipher<br />
|- align="center"<br />
| 0x1 || 0x040 || align="left" | Stream mime type<br />
|- align="center"<br />
| 0x1 || 0x050 || align="left" | File transfer begin<br />
|- align="center"<br />
| 0x1 || 0x051 || align="left" | File transfer data<br />
|- align="center"<br />
| 0x1 || 0x100 || align="left" | Configure ICY-NAME<br />
|- align="center"<br />
| 0x1 || 0x101 || align="left" | Configure ICYGENRE<br />
|- align="center"<br />
| 0x1 || 0x102 || align="left" | Configure ICYURL<br />
|- align="center"<br />
| 0x1 || 0x103 || align="left" | Configure ICYPUB<br />
|- align="center" style="background:#efefef;"<br />
| 0x2 || || align="left" | Listener<br />
|- align="center"<br />
| 0x2 || 0x001 || align="left" | Temporary Broadcast Interruption<br />
|- align="center"<br />
| 0x2 || 0x002 || align="left" | Broadcast Termination<br />
|- align="center" style="background:#efefef;"<br />
| 0x3 || || align="left" | Cacheable Metadata<br />
|- align="center"<br />
| 0x3 || 0x000 || align="left" | Content Info Metadata (unused)<br />
|- align="center"<br />
| 0x3 || 0x001 || align="left" | Url Metadata (unused)<br />
|- align="center"<br />
| 0x3 || 0x901 || align="left" | XML Metadata (Aol Radio format)<br />
|- align="center"<br />
| 0x3 || 0x902 || align="left" | XML Metadata (SHOUTcast 2.0 format)<br />
|- align="center" style="background:#efefef;"<br />
| 0x4 || || align="left" | Cacheable Binary Metadata (reserved)<br />
|- align="center"<br />
| 0x4 || 0x0xx || align="left" | Station logo (see 'Image Notes' for xx details)<br />
|- align="center"<br />
| 0x4 || 0x1xx || align="left" | Album art (see 'Image Notes' for xx details)<br />
|- align="center" style="background:#efefef;"<br />
| 0x5 || || align="left" | Pass-through Metadata<br />
|- align="center"<br />
| 0x5 || 0x001 || align="left" | Time Remaining (reserved)<br />
|- align="center" style="background:#efefef;"<br />
| 0x6 || || align="left" | Pass-through Metadata (unused)<br />
|- align="center"<br />
| 0x7 || 0x000 || align="left" | Data - MP3<br />
|- align="center"<br />
| 0x8 || 0x000 || align="left" | Data - VLB<br />
|- align="center"<br />
| 0x8 || 0x001 || align="left" | Data - AAC LC<br />
|- align="center"<br />
| 0x8 || 0x003 || align="left" | Data - AACP<br />
|- align="center"<br />
| 0x8 || 0x004 || align="left" | Data - Vorbis (reserved)<br />
|- align="center"<br />
| 0x9 || 0x000 || align="left" | Data - Headerless AACP (reserved) (see 'Framed Data' for details)<br />
|- align="center"<br />
| 0x9 || 0x001 || align="left" | Data - Headerless Vorbis (reserved) (see 'Framed Data' for details)<br />
|- align="center" style="background:#efefef;"<br />
| 0xA || || align="left" | Cacheable Binary Metadata (reserved for use with 0x9 if implemented)<br />
|}<br />
<br />
<br />
====Image Notes====<br />
----<br />
<br />
When these are received, the xx of the type is used to specify the image mime type where:<br />
<br />
::{| class="wikitable" cellpadding="2" cellspacing="0"<br />
|-<br />
| width="40" | 00 || image/jpeg<br />
|-<br />
| 01 || image/png<br />
|-<br />
| 02 || image/bmp<br />
|-<br />
| 03 || image/gif<br />
|}<br />
<br />
<br />
====Framed Data====<br />
----<br />
<br />
This is a potential extension intended to provide encoded data using just the Ultravox frame instead of the usual overhead required when streaming existing formats. The aim of this if implemented (currently a proposed feature) is it can help reduce the overhead of streaming at lower bitrates where this is more noticeable e.g. the potential of saving 7 bytes per audio frame for AAC streaming. However this would also require the listener to be compatible and be able to cope otherwise the distribution point would need to convert the frames back to ones containing a header.<br />
<br />
<br />
==Conclusion==<br />
<br />
Using the Ultravox Broadcast and Listener Protocol will make it possible stream data of different types (audio, video, animation codecs) to an end user. This protocol gives specific information for building these services as well as recommendations for managing the system. The fact that the broadcaster has complete control over the desired bitrate makes this possible along with the logic to generalize a stream in the distribution point.<br />
<br />
<br />
==Glossary==<br />
<br />
'''Authentication Server''' – a service that the distribution point may use to authenticate broadcasters and listeners when they initiate a connection to the distribution point.<br />
<br />
'''Auth-Blob''' – a character string (ASCIIZ), no longer than 1200 bytes, sent to an authentication server with a UID as authentication credentials.<br />
<br />
'''Broadcaster''' – a process that implements the Ultravox Broadcaster Protocol of the distribution point providing a media stream using the Ultravox Broadcaster Protocol across a connection. <br />
<br />
'''Idle-timeout''' – the maximum time interval that the Distribution point allows between messages received from a broadcaster before it disconnects the broadcaster and considers the stream it was providing to be abnormally terminated.<br />
<br />
'''Listener''' – a network client of the Distribution point subscribing to a media stream using either the Ultravox Listener Protocol or the SHOUTcast Listener Protocol across a TCP connection.<br />
<br />
'''Media''' – the encoded audio/video data (e.g., MP3) which is the essential content of a stream. Media is “streamed” from the broadcaster to be “played” by a listener.<br />
<br />
'''Metadata''' – data associated with a stream that is not media, but contains information that is pertinent to the media being provided (e.g., titles, advertisements, graphics, etc…).<br />
<br />
'''Prebuffering''' - the process by which the Distribution point fills the listener’s stream data buffer as quickly as possible in order allow a continuous playback even when there are minor variations in network latency.<br />
<br />
'''Reconnect-timeout''' – the maximum time interval that the Distribution point allows a broadcaster to reconnect and re-establish a stream when a broadcaster unexpectedly disconnects.<br />
<br />
'''SHOUTcast''' – the streaming media protocol used by an installed base of broadcasters and listeners.<br />
<br />
'''SID (Stream IDentifier)''' – a non-zero integer (32-bit unsigned) value that uniquely identifies a particular media stream within a Distribution point. The association of SIDs with streams is managed operationally outside of the Distribution point.<br />
<br />
'''Stream''' – a continuous sequence of media and associated metadata provided to the Distribution point by a broadcaster.<br />
<br />
'''Termination''' – the condition of a stream whereby it is no longer available for subscription by listeners. Normal termination of a stream occurs when the broadcaster providing it makes a specific request to terminate. All other circumstances (specifically idle-timeout and reconnect-timeout) that result in the termination of a stream are considered abnormal.<br />
<br />
'''UID (User IDentifier)''' – a character string (ASCIIZ), no longer than 64 bytes, that identifies a particular broadcaster or listener for the purpose of authentication.<br />
<br />
'''Ultravox Protocol''' - the streaming media protocol(s) intended to supercede the SHOUTcast protocol.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Radio_Authhash_APISHOUTcast Radio Authhash API2014-10-28T22:57:00Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
==Introduction==<br />
<br />
A key aspect of the SHOUTcast 2.0 system is the usage of authorisation keys to control the listing of stations within the SHOUTcast Radio Directory (otherwise known as the YP).<br />
<br />
The API which is documented here is provided as a means for registered developers to be able to obtain and manage any authorisation keys for the station(s) they are providing.<br />
<br />
<br />
==API Overview==<br />
<br />
There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):<br />
<br />
:[[#Create_Authorisation_Key|Create]]<br />
:[[#Check_Authorisation_Key|Check]]<br />
:[[#Update_Authorisation_Key|Update]]<br />
:[[#Remove_Authorisation_Key|Remove]]<br />
<br />
The authorisation key APIs are xml based responses which provide information and status details of the provided API methods in a common style to ease implementation and usage.<br />
<br />
The API methods are called by passing parameters to the required YP site url.<br />
<br />
When the API methods are called then the status code of the method response is set to the status code of the API method so it is easy to detect errors from calling the API method.<br />
<br />
<br />
===Successful Response===<br />
----<br />
<br />
If there are no issues with the API method call then one of the following responses will be received as the response generated.<br />
<br />
<br />
The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
</response><br />
</source><br />
<br />
The second response is the '''full''' success response and is provided when the API method needs to return additional information such as the authorisation key when a new one is created or the details of the authorisation key when using the ''''check'''' method:<br />
<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<!-- information is found here --><br />
</data><br />
</response><br />
</source><br />
<br />
===Error Response===<br />
----<br />
<br />
If there are issues experienced during the API method call then an error response will be received which takes the following form:<br />
<br />
<source lang="xml"><br />
<response><br />
<statusCode>440</statusCode><br />
<statusText>Invalid devId</statusText><br />
<!-- the following is optional dependent upon the error --><br />
<statusDetailText>Invalid parameter k</statusDetailText><br />
</response><br />
</source><br />
<br />
In all uses of the API methods, the ''''statusCode'''' and ''''statusText'''' elements are provided when an error occurs. The ''''statusDetailText'''' value is an optional element and is only provided if the internal error handling is able to provide additional information. This will usually be present for errors relating to parameter issues i.e. missing parameters.<br />
<br />
See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.<br />
<br />
<br />
==API Usage==<br />
<br />
The following sections detail how to use the four authorisation key API methods.<br />
<br />
Importantly, once an authorisation key has been created then it will be locked to the Developer ID used so you can only check, update or remove authorisation keys against that Developer ID.<br />
<br />
<br />
===Create Authorisation Key===<br />
----<br />
<br />
This will create an authorisation key and will return it in the xml response on success.<br />
<br />
Any parameters which are not specified and do not cause an error will be left at their default values which will be indicated by empty xml elements when using the ''''check'''' API.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Misc&[Optional Parameters To Set]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* k - Developer ID for accessing the API<br />
* stationname - name of the station as listed in the YP listings up to 100 characters<br />
* genre - genre describing the station (see [[#Additional_Resources|section 4.0]] for getting supported genres or [[#Supported_Genres|section 4.2]] for list of supported genre values)<br />
* email - contact address for the station up to 255 characters (this is so we can contact you easily in-case of an issue with your listing or needing to inform you of a required DNAS update)<br />
<br />
'''<span style="color:#FF6600;">Recommended Optional Parameters:</span>'''<br />
''(These are marked as optional but are likely to be made required in a future update)''<br />
<br />
* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)<br />
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
<br />
* website - related url for station up to 128 characters<br />
* description - brief description about the station up to 65535 characters<br />
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)<br />
* city - more specific place where the stream is based or related up to 128 characters<br />
* keywords - separated tag words about the stream up to 120 characters<br />
* private - determine if the primary server should be public (0 - default) or not (1)<br />
<br />
It is recommended to fill in as many of these optional details where possible<br />
to improve usability with any future YP features which may be introduced.<br />
<br />
'''<span style="color:#FF6600;">Response:</span>'''<br />
<br />
Returns a '''full''' success response containing the new authorisation key or the standard error response.<br />
<br />
'''<span style="color:#FF6600;">Example Response</span>'''<br />
<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<authhash>An_Authorisation_Key</authhash><br />
</data><br />
</response><br />
</source><br />
<br />
<br />
===Check Authorisation Key===<br />
----<br />
<br />
This will remove an authorisation key as long as it was created by the Developer ID used.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* k - Developer ID for accessing the API<br />
* authhash - Authorisation Key to check<br />
<br />
'''<span style="color:#FF6600;">Response:</span>'''<br />
<br />
Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.<br />
<br />
'''<span style="color:#FF6600;">Example Response</span>'''<br />
<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<stationname>The Station Name</stationname><br />
<genre>Misc</genre><br />
<website>www.shoutcast.com</website><br />
<description>The Best Station Ever...!</description><br />
<langid>EN</langid><br />
<countryiso>US</countryiso><br />
<stateiso>00</stateiso><br />
<city></city><br />
<keywords>Greatest Web Station</keywords><br />
<private>0</private><br />
</data><br />
</response><br />
</source><br />
<br />
The <stateiso> element will only be returned if the <countryiso> element is 'US'.<br />
<br />
<br />
===Update Authorisation Key===<br />
----<br />
<br />
This will update an authorisation key as long as it was created by the Developer ID used.<br />
<br />
Any parameters which are not specified and do not cause an error when making an update are reset to their default value when this completes. Otherwise this acts the same as the ''''create'''' API with the addition of specifying the authorisation key to update.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://yp.shoutcast.com/updateauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]&stationname=The Station Name&genre=Misc&[Other Parameters To Update]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* k - Developer ID for accessing the API<br />
* authhash - Authorisation Key to update<br />
* stationname - name of the station as listed in the YP listings up to 100 characters<br />
* genre - genre describing the station (see [[#Additional_Resources|section 4.0]] for getting supported genres or [[#Supported_Genres|section 4.2]] for list of supported genre values)<br />
* email - contact address for the station up to 255 characters (this is so we can contact you easily in-case of an issue with your listing or needing to inform you of a required DNAS update)<br />
<br />
'''<span style="color:#FF6600;">Recommended Optional Parameters:</span>'''<br />
''(These are marked as optional but are likely to be made required in a future update)''<br />
<br />
* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)<br />
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
<br />
* website - related url for station up to 128 characters<br />
* description - brief description about the station up to 65535 characters<br />
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)<br />
* city - more specific place where the stream is based or related up to 128 characters<br />
* keywords - separated tag words about the stream up to 120 characters<br />
* private - determine if the primary server should be public (0 - default) or not (1)<br />
<br />
It is recommended to fill in as many of these optional details where possible<br />
to improve usability with any future YP features which may be introduced.<br />
<br />
'''<span style="color:#FF6600;">Response:</span>'''<br />
<br />
Returns a '''basic''' success response or the standard error response.<br />
<br />
<br />
===Remove Authorisation Key===<br />
----<br />
<br />
This will remove an authorisation key as long as it was created by the Developer ID used.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* k - Developer ID for accessing the API<br />
* authhash - Authorisation Key to remove<br />
<br />
'''<span style="color:#FF6600;">Response:</span>'''<br />
<br />
Returns a '''basic''' success response or the standard error response.<br />
<br />
<br />
<br />
==Additional Resources==<br />
<br />
In addition to the core API methods, some additional methods are provided for accessing the supported primary and secondary genres, country, state and language codes. These are provided as a means to check you are using the correct values or to use if creating your own interface around the core authorisation key APIs.<br />
<br />
<br />
These additional methods are accessed via <nowiki>http://yp.shoutcast.com/authutil_*</nowiki> where '''*''' is then replaced with one of the following to get the required information:<br />
<br />
* '''country''' - provides provides a html select control containing the ISO 3166-1-alpha-2 code and a displayable string for each option in the control<br />
<br />
* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control<br />
<br />
* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control<br />
<br />
* '''primarygenre''' - provides a html select control of the primary genre's recognised<br />
<br />
* '''secondarygenre?primarygenre=<genre>''' - provides a html select control of the secondary genre's related to the primary genre passed or an empty response if there is no genres found<br />
<br />
* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre<br />
<br />
<br />
All additional methods (excluding the ''''parentgenre'''' method) provide a fully formed html select control which is filled with relevent values based on the parameter passed to the method (if applicable). These are done like this to allow for ease of insertion into a<br />
<div> element for example with an interface used to control the APIs.<br />
<br />
Calling these additional methods (excluding the ''''parentgenre'''' method) with ''''&raw=1'''' in the url will output the result (if applicable) as plain text instead of as a html select control. The values returned are separated by a comma and each data pair is then placed on a new line. This is provided as a quick way of getting the recognised values if the html select control is not suitable.<br />
<br />
<br />
===User Interface Versions===<br />
----<br />
<br />
In addition to the core API methods, specifying ''''ui_'''' on the front of the API method e.g. <nowiki>http://yp.shoutcast.com/ui_checkauthhash</nowiki> for the ''''check'''' method provides a pre-built interface pages which can be used as a base point for making your own interface for the authorisation key APIs or to use as is as long as you have the required developer access.<br />
<br />
<br />
===Supported Genres===<br />
----<br />
<br />
The genre specified for an authhash can only be a primary genre (e.g. Misc) or it can be a secondary genre related to a chosen primary genre (e.g. House from Electronic). The following lists the supported primary genres and the associated secondary genres to them.<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!Primary Genre<br />
!Associated Secondary Genres<br />
|-<br />
| Alternative || Adult Alternative, Britpop, Classic Alternative, College, Dancepunk, Dream Pop, Emo, Goth, Grunge, Hardcore, Indie Pop, Indie Rock, Industrial, LoFi, Modern Rock, New Wave, Noise Pop, Post Punk, Power Pop, Punk, Ska, Xtreme<br />
|-<br />
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues<br />
|-<br />
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony<br />
|-<br />
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western<br />
|-<br />
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s<br />
|-<br />
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop<br />
|-<br />
| Electronic || Acid House, Ambient, Big Beat, Breakbeat, Dance, Demo, Disco, Downtempo, Drum and Bass, Dubstep, Electro, Garage, Hard House, House, IDM, Jungle, Progressive, Techno, Trance, Tribal, Trip Hop<br />
|-<br />
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk<br />
|-<br />
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel<br />
|-<br />
| International || African, Afrikaans, Arabic, Asian, Bollywood, Brazilian, Caribbean, Celtic, Chinese, Creole, European, Filipino, French, German, Greek, Hawaiian and Pacific, Hebrew, Hindi, Indian, Islamic, Japanese, Klezmer, Korean, Mediterranean, Middle Eastern, North American, Russian, Soca, South American, Tamil, Turkish, Worldbeat, Zouk<br />
|-<br />
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion<br />
|-<br />
| Latin || Bachata, Banda, Bossa Nova, Cumbia, Flamenco, Latin Dance, Latin Pop, Latin Rap and Hip Hop, Latin Rock, Mariachi, Merengue, Ranchera, Reggaeton, Regional Mexican, Salsa, Samba, Tango, Tejano, Tropicalia<br />
|-<br />
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal<br />
|-<br />
| Misc || <br />
|-<br />
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual<br />
|-<br />
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop<br />
|-<br />
| Public Radio || College, News, Sports, Talk, Weather<br />
|-<br />
| R&B and Urban || <br />
|-<br />
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap<br />
|-<br />
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady<br />
|-<br />
| Rock || Adult Album Alternative, British Invasion, Celtic Rock, Classic Rock, Garage Rock, Glam, Hard Rock, Jam Bands, JROCK, Piano Rock, Prog Rock, Psychedelic, Rock & Roll, Rockabilly, Singer and Songwriter, Surf<br />
|-<br />
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter<br />
|-<br />
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music<br />
|-<br />
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology<br />
|-<br />
| Themes || Adult, Best Of, Chill, Eclectic, Experimental, Female, Heartache, Instrumental, LGBT, Love and Romance, Party Mix, Patriotic, Rainy Day Mix, Reality, Se xy ''(remove space for actual word - spam filter display issue)'', Shuffle, Travel Mix, Tribute, Trippy, Work Mix<br />
|}<br />
<br />
===Illegal Input Values===<br />
----<br />
<br />
The following values are not allowed when entered as the stationname (case insensitively) and will cause a 456 error response to be received when an authorisation key is created or updated as they are not easily found when multiple other listings are also using the same stationame.<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
| 127.0.0.1 || admin || auto dj || auto jedi<br />
|-<br />
| auto pj || auto-dj || autodj || autopj<br />
|-<br />
| demo || dj || internet radio || live<br />
|-<br />
| local server || localhost || localserver || music<br />
|-<br />
| my radio || my server || my station name || my test server<br />
|-<br />
| n/a || pj || playlist || radio<br />
|-<br />
| radio station || test || test server || unnamed server<br />
|-<br />
| virtual dj || virtualdj || web rdio || web radio<br />
|-<br />
| song || teste || default stream || radio stream<br />
|}<br />
<br />
Additionally, stationnames just containing punctuation are not allowed as well as any which specify a name which matches with the supported genres (see [[SHOUTcast_Radio_Authhash_API#Supported_Genres|section 4.2]]).<br />
<br />
<br />
==Status Codes==<br />
<br />
The following status codes are returned on success or error when using the provided APIs:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!Code<br />
!Status Text<br />
!Detailed Text (if available)<br />
|-<br />
| 200 || Ok || n/a<br />
|-<br />
| 400 || Generic Error || n/a<br />
|-<br />
| 404 || Page Not Found || n/a<br />
|-<br />
| 440 || Invalid devId || Invalid parameter k<br />
|-<br />
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed<br />
|-<br />
| 458 || Building internal value failure || n/a<br />
|-<br />
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'<br />
|-<br />
| 460 || Missing required parameter || Missing ''<variable>''<br />
|-<br />
| 461 || Error while updating authhash || n/a<br />
|-<br />
| 462 || Parameter error || Invalid parameter <variable><br />
|-<br />
| 463 || Invalid station result returned || n/a<br />
|-<br />
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'<br />
|-<br />
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter<br />
|-<br />
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long<br />
|-<br />
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized<br />
|-<br />
| 468 || Error creating intended xml response || n/a<br />
|-<br />
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'<br />
|-<br />
| 470 || Invalid authorization hash || n/a<br />
|-<br />
| 500 || Generic Server Error || n/a<br />
|}<br />
<br />
Note: The ''<variable>'' value in the detailed text will be replaced with the parameter name which the error relates to. The ''<value>'' value in the detailed text will be replaced with the parameter value which the error relates to.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Radio_Directory_APISHOUTcast Radio Directory API2014-10-28T22:56:34Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
=Get Stations on SHOUTcast Radio Directory=<br />
<br />
==Get Top 500 Stations==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get top 500 stations on SHOUTcast Radio directory.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* k - API Dev Key. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* limit - Limit the number of stations to return by passing the limit parameter.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&limit=5</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>''' (with limits)<br />
<source lang="xml"><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name=".977 The Hitz Channel-[SHOUTcast.com]" mt="audio/mpeg" id="9907" br="128"<br />
genre="Pop Rock Top 40"ct="The Fray - You Found Me" lc="4670"/><br />
<station name="HOT FM - Lebih Hangat Daripada Biasa : HOT fm-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="120149" br="24" genre="Malaysia<br />
Malay" ct="LELAKI IDAMAN MELLY_GOESLOW " lc="3961"/><br />
<station name="S K Y . F M - Absolutely Smooth Jazz - the world's smoothest jazz 24 hours a day-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="1264" br="96" genre="Soft Smooth Jazz" <br />
ct="Oli Silk - De-stress Signal" lc="3507"/><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]" <br />
mt="audio/mpeg" id="6687" br="128" genre="Ambient Chill"<br />
ct="Verbrilli Sound - Descender" lc="2680"/><br />
<station name=".977 The 80s Channel-[SHOUTcast.com]" mt="audio/mpeg" id="6803" <br />
br="128" genre="80s Pop Rock" ct="Starship - Nothing`s gonna stop us now (1987)" lc="2192"/><br />
<station name="The Alex Jones Show-[SHOUTcast.com]" mt="audio/mpeg" id="5516" br="32" genre="Talk" <br />
ct="Refeed: Hour 1 (Listen by phone 512-646-5000)" lc="1987"/><br />
</stationlist><br />
</source><br />
<br />
<br />
==Get Stations by Keyword Search==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get stations which match the keyword searched on SHOUTcast Radio Directory.<br />
:'''Note:''' This API returns stations which has keyword match in the following fields Station Name, Now Playing info, Genre.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* search - Specify the query to search.<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* limit - Limits the no of results to be returned.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&limit=10</nowiki><br />
<br />
* limit with pagination - Limits the no of results with pagination included.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&limit=X,Y</nowiki><br />
:* Y is the number of results to return and X is the offset. <br />
<br />
* Filter by Codec type - Get stations which match the codec type requested.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&mt=audio/mpeg</nowiki><br />
:MP3 = audio/mpeg and AAC+ = audio/aacp<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"></tunein><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="6687" br="128" genre="Ambient Chill" ct="Audiomontage - Abyss" lc="241"><br />
</station><br />
<station name="((Metaphoric.me))128k Room42, ambient beats and chill grooves-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="8434" br="128" genre="Ambient Chill" ct="Jazz City - La Noche (Smooth Latin Groove Mix)" lc="83"><br />
</station><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="8010" br="24" genre="Ambient Chill" ct="Audiomontage - Abyss" lc="54"><br />
</station><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="9073" br="56" genre="Ambient Chill" ct="Warheads - Daphne" lc="30"><br />
</station><br />
</stationlist><br />
</source><br />
<br />
<br />
==Get Stations by Genre==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get stations which match the genre specified as query.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* k - API Dev ID.<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* limit - Limits the no of results to be returned.<br />
<br />
* limit with pagination - Limits the no of results with pagination included.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&limit=X,Y</nowiki><br />
:* Y is the number of results to return and X is the offset.<br />
<br />
* Filter by Codec type - Get stations which match the codec type requested.<br />
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&&mt=audio/aacp</nowiki><br />
:MP3 = audio/mpeg and AAC+ = audio/aacp.<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name=".977 The Hitz Channel-[SHOUTcast.com]" mt="audio/mpeg" id="9907" br="128"<br />
genre="Pop Rock Top 40" ct="The Fray - You Found Me" lc="4670"/><br />
<station name="HOT FM - Lebih Hangat Daripada Biasa : HOT fm-[SHOUTcast.com]" mt="audio/mpeg" <br />
id="120149" br="24" genre="Malaysia Malay"<br />
ct="LELAKI IDAMAN MELLY_GOESLOW " lc="3961"/><br />
<station name="S K Y . F M - Absolutely Smooth Jazz - the world's smoothest jazz 24 hours a day-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="1264" br="96" genre="Softsmooth Jazz"<br />
ct="Oli Silk -De-stress Signal" lc="3507"/><br />
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"<br />
mt="audio/mpeg" id="6687" br="128" genre="AmbientChill"<br />
ct="Verbrilli Sound - Descender" lc="2680"/><br />
</stationlist><br />
</source><br />
<br />
<br />
==Get Stations Based on Now Playing Info==<br />
'''<span style="color:#FF6600;">Description:</span>''' Return stations which match a specified query in the now playing node.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>'''<br />
<nowiki>http://api.shoutcast.com/station/nowplaying?k=[Your Dev ID]&ct=rihanna&f=xml</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* ct - Query to search in Now Playing node. This parameter also supports querying multiple artists in the same query by using "||". ex: ct=madonna||u2||beyonce up to 10 artists<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only).<br />
* limit - Limits the no of results to be returned in output.<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name="Dj Wouner- Radio Fusion-A novidade come?a Aqui!-[SHOUTcast.com]" mt="audio/mpeg" id="139549" <br />
br="64" genre="Various"ct="Rihanna Feat. Chris Brown & Jay-Z - Umbrella" lc="614" ml="2100" nsc="No" cst=""/><br />
<station name="R?dio Stronda [ Digital ] Servidor 4-[SHOUTcast.com]" mt="audio/mpeg" id="998783" br="64" <br />
genre="Pop Top Rock Funk Str"ct="T.I. feat Rihanna -Live Your Life" lc="243" ml="70" nsc="No" cst=""/><br />
.<br />
.<br />
</stationlist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/station/nowplaying?ct=rihanna&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Various","id":"139549","mt":"audio/mpeg","name":"Dj Wouner- <br />
RadioFusion-A novidadecome?a Aqui!-[SHOUTcast.com]","cst":"","lc":"614","ml":"2100","br":"64",<br />
"ct":"Rihanna Feat. Chris Brown& Jay-Z - Umbrella"},<br />
{"nsc":"No","genre":"Pop Top Rock Funk Str","id":"998783",<br />
"mt":"audio/mpeg","name":"R?dio Stronda[ Digital ] Servidor<br />
4-[SHOUTcast.com]","cst":"","lc":"243","ml":"70","br":"64","ct":"T.I. feat Rihanna - Live Your ife"},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Various","id":"139549","mt":"audio/mpeg","name":"Dj Wouner- <br />
RadioFusion-A novidadecome?a Aqui!-[SHOUTcast.com]","cst":"","lc":"614","ml":"2100","br":"64",<br />
"ct":"Rihanna Feat. Chris Brown& Jay-Z - Umbrella"},<br />
{"nsc":"No","genre":"Pop Top Rock Funk Str","id":"998783",<br />
"mt":"audio/mpeg","name":"R?dio Stronda[ Digital ] Servidor<br />
4-[SHOUTcast.com]","cst":"","lc":"243","ml":"70","br":"64","ct":"T.I. feat Rihanna - Live Your ife"},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
==Get Stations by Bitrate or Codec Type or Genre ID==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get stations which match a particular bitrate or codec type.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>'''<br />
:* Stations filtered by bitrate<br />
::<nowiki>http://api.shoutcast.com/station/advancedsearch?br=128&limit=10&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
:* Stations filtered by media type<br />
::<nowiki>http://api.shoutcast.com/station/advancedsearch?mt=audio/mpeg&limit=10&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
:* Stations filtered by Genre ID<br />
::<nowiki>http://api.shoutcast.com/station/advancedsearch?genre_id=1&limit=10&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
:* Stations filtered by bitrate, media type & genre<br />
::<nowiki>http://api.shoutcast.com/station/advancedsearch?mt=audio/mpeg&br=128&search=Trance&&limit=10&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID. <br />
* br - Filter the stations based on bitrate specified.<br />
* mt - Filter the stations based on media type specified.<br />
* genre_id - Genre Id from the genre API<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
* limit - Limits the no of results to be returned in output.<br />
* genre - Filter stations that match the genre passed.<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name=".977 The Hitz Channel" mt="audio/mpeg" id="9907" <br />
br="128" genre="Pop Rock Top 40"<br />
ct="Chingy - Balla Baby" lc="11576"/><br />
<station name="TechnoBase.FM - 24h Techno, Dance, Trance, House and More - 128k MP3-[SHOUTcast.com]"<br />
mt="audio/mpeg"id="7429" br="128"genre="Techno Trance Dance House"<br />
ct="We aRe oNe" lc="8308" ml="8500" nsc="No" cst=""/><br />
<station name="Absolutely Smooth Jazz - S K Y . F M - the world's smoothest<br />
jazz 24 hours a day-[SHOUTcast.com]" mt="audio/mpeg" id="948"br="96" genre="Soft Smooth Jazz"<br />
ct="Jonathan Butler/Kirk Whalum - Dancing on the Shore" lc="6801" ml="10023" nsc="No" cst=""/><br />
.<br />
.<br />
</stationlist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
* Stations based on bitrate<br />
:<nowiki>http://api.shoutcast.com/station/advancedsearch?br=128&limit=3&f=json&k=[Your Dev ID]</nowiki><br />
<br />
* Stations based on media type<br />
:<nowiki>http://api.shoutcast.com/station/advancedsearch?mt=mpeg&limit=3&f=json&k=[Your Dev ID]</nowiki><br />
<br />
* Stations based on genre id<br />
:<nowiki>http://api.shoutcast.com/station/advancedsearch?genre_id=1&limit=3&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Pop Rock Top 40","id":"9907",mt":"audio/mpeg","name":".977 The<br />
HitzChannel-[SHOUTcast.com]","cst":"","lc":"11576","ml":"8500","br":"128","ct":"Chingy - Balla Baby"},<br />
{"nsc":"No","genre":"Techno Trance<br />
DanceHouse","id":"7429","mt":"audio/mpeg",<br />
"name":"TechnoBase.FM - 24h<br />
Techno, Dance,Trance, House and More -128kMP3-[SHOUTcast.com]","lc":"8308","ml":"10023",<br />
"br":"128","ct":"We aRe oNe"},<br />
{"nsc":"No","genre":"Soft Smooth Jazz","id":"948","mt":"audio/mpeg",<br />
"name":"Absolutely Smooth Jazz - S K Y . F M - the world's<br />
smoothest jazz 24hours a day-[SHOUTcast.com]","cst":"","lc":"6801","ml":"18600","br":"96",<br />
"ct":"Jonathan Butler/Kirk Whalum - Dancing on the Shore"},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Pop Rock Top 40","id":"9907",mt":"audio/mpeg","name":".977 The<br />
HitzChannel-[SHOUTcast.com]","cst":"","lc":"11576","ml":"8500","br":"128","ct":"Chingy - Balla Baby"},<br />
{"sc":"No","genre":"Techno Trance<br />
DanceHouse","id":"7429","mt":"audio/mpeg",<br />
"name":"TechnoBase.FM - 24h<br />
Techno, Dance,Trance, House and More -128kMP3-[SHOUTcast.com]","lc":"8308",<br />
"ml":"10023","br":"128","ct":"We aRe oNe"},<br />
{"nsc":"No","genre":"Soft Smooth Jazz","id":"948","mt":"audio/mpeg",<br />
"name":"Absolutely Smooth Jazz - S K Y . F M - the world's<br />
smoothest jazz 24hours a day-[SHOUTcast.com]","cst":"","lc":"6801","ml":"18600","br":"96",<br />
"ct":"Jonathan Butler/Kirk Whalum - Dancing on the Shore"},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
==Get Random Stations==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get random stations on SHOUTcast Radio Directory. Random stations can be restricted to the Bitrate/Genre/Media type specified.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>'''<br />
<br />
:* <nowiki>http://api.shoutcast.com/station/randomstations?k=[Your Dev ID]&f=xml</nowiki><br />
::Returns a random station. This API by default returns one random station.<br />
::To get more random stations, set the number of stations to return by passing the limit parameter.<br />
<br />
:* <nowiki>http://api.shoutcast.com/station/randomstations?k=[Your Dev ID]&f=xml&mt=audio/mpeg&br=128&genre=Fresh</nowiki><br />
::Returns a random station. This API by default returns one random station.<br />
::To get more random stations, set the number of stations to return by passing the limit parameter.<br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
* br - Bitrate to filter the station result. <br />
* mt - Media type to filter the station result. <br />
* genre - Genre to filter the station result. <br />
* limit - This API by default returns one station. To get more random stations, set the number of stations to return by passing the limit parameter.<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''(Parameter Limit)<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<stationlist><br />
<tunein base="/sbin/tunein-station.pls"/><br />
<station name="FreshBakedJams.com-[SHOUTcast.com]" mt="audio/mpeg" id="429395" br="128" genre="Fresh BakedJams"<br />
ct="D-Rellz - Story" lc="0" ml="600" nsc="No"/><br />
</stationlist><br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/station/nowplaying?ct=rihanna&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Turkish TurkTurkce","id":205936,"mt":"audio/mpeg",<br />
"name":"TRD 1 - Turk Radyo Dunyasi - Turkish World<br />
Radio - SMS: +90 544 644 6226- www.trd.com.tr-[SHOUTcast.com]",<br />
"lc":2,"ml":"600","br":32,"ct":"Nalan -Sonunda Bitti"},<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"stationlist":{<br />
"station":[<br />
"tunein":{<br />
"base":"/sbin/tunein-station.pls"<br />
}<br />
{"nsc":"No","genre":"Turkish TurkTurkce","id":205936,"mt":"audio/mpeg",<br />
"name":"TRD 1 - Turk Radyo Dunyasi - Turkish World<br />
Radio - SMS: +90 544 644 6226- www.trd.com.tr-[SHOUTcast.com]",<br />
"lc":2,"ml":"600","br":32,"ct":"Nalan -Sonunda Bitti"}, <br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
=Get Genres on SHOUTcast Radio Directory=<br />
<br />
==Get All Genres==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get all the genres on SHOUTcast Radio Directory<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/genrelist?k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<br />
<source lang="xml"><br />
<genrelist><br />
<genre name="30s"/><br />
<genre name="40s"/><br />
<genre name="50s"/><br />
<genre name="60s"/><br />
<genre name="70s"/><br />
<genre name="80s"/><br />
<genre name="90s"/><br />
.<br />
.<br />
</genrelist><br />
</source><br />
<br />
<br />
==Get Primary Genres==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get only the Primary Genres on SHOUTcast Radio Directory<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/genre/primary?k=[Your Dev ID]&f=xml</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* f - the response format (xml, json,rss). You can choose xml, json or rss based results.<br />
* k - API Dev ID.<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only).<br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<genrelist> <br />
<genre name="Alternative" id="1" parentid="0" haschildren="true"/><br />
<genre name="Blues" id="24" parentid="0" haschildren="true"/><br />
.<br />
.<br />
.<br />
</genrelist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},<br />
{"id":24,"haschildren":true,"name":"Blues","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok" <br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},<br />
{"id":24,"haschildren":true,"name":"Blues","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
==Get Secondary Genres==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get secondary genre list (if present) for a specified primary genre.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/genre/secondary?parentid=0&k=[Your Dev ID]&f=xml</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* parentid - Genreid of the primary genre. You can retreive the entire genre set by passing parentid=0.<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID.<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<genrelist><br />
<genre name="Alternative" id="1" parentid="0" haschildren="true"><br />
<genrelist><br />
<genre name="Adult Alternative" id="2" parentid="1" haschildren="false"/><br />
<genre name="Britpop" id="3" parentid="1" haschildren="false"/><br />
<genre name="Classic Alternative" id="4" parentid="1" haschildren="false"/> <br />
.<br />
.<br />
</genrelist><br />
</genre><br />
</genrelist><br />
</data><br />
<response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/genre/secondary?parentid=0&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
"genrelist":{<br />
"genre":[<br />
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},<br />
{"id":24,"haschildren":true,"name":"Blues","parentid":0},<br />
{"id":32,"haschildren":true,"name":"Classical","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
"genrelist":{<br />
"genre":[<br />
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},<br />
{"id":24,"haschildren":true,"name":"Blues","parentid":0},<br />
{"id":32,"haschildren":true,"name":"Classical","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
==Get Genres Details by Passing Genreid==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get details such as Genre Name, Sub Genres (if its a primary genre), has children by passing the genre-id.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/genre/secondary?id=25&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* id - Input respective genre or sub-genre id.<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID. <br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200 </statusCode><br />
<statusText>Ok </statusText><br />
<data><br />
<genrelist> <br />
<genre name="Acoustic Blues" id="25" parentid="24" haschildren="false"/><br />
</genrelist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/genre/secondary?id=25&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":{<br />
{"id":25,"haschildren":false,"name":"AcousticBlues","parentid":24}<br />
}<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok" <br />
}, <br />
"data":"{<br />
"genrelist":{<br />
"genre":{<br />
{"id":25,"haschildren":false,"name":"AcousticBlues","parentid":24}<br />
}<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
==Get Genres Based on Availability of Sub-Genres==<br />
'''<span style="color:#FF6600;">Description:</span>''' Get genres based on their sub-genre availability at any node level in the genre hierarchy of SHOUTcast.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>'''<br />
:*Genres with sub genres:<br />
::<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=true&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
:*Genres without sub genres:<br />
::<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=false&f=xml&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
* haschildren<br />
:* 'true' to get genre or subgenre which has sub-genres.<br />
:* 'false' to get genre or subgenre which does not have sub-genres.<br />
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.<br />
* k - API Dev ID.<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
* c - The callback function to invoke in the response (appropriate for JSON responses only). <br />
<br />
'''<span style="color:#FF6600;">Sample XML Response:</span>'''<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<genrelist> <br />
<genre name="Alternative" id="1" parentid="0" haschildren="true"/><br />
<genrelist><br />
<genre name="Adult Alternative" id="2" parentid="1" haschildren="false"/><br />
<genre name="Britpop" id="3" parentid="1" haschildren="false"/><br />
.<br />
.<br />
</genrelist><br />
</genre><br />
<genre name="Blues" id="24" parentid="0" haschildren="true"/><br />
<genrelist><br />
<genre name="Adult Alternative" id="2" parentid="1" haschildren="false"/><br />
<genre name="Britpop" id="3" parentid="1" haschildren="false"/><br />
.<br />
.<br />
</genrelist><br />
</genre><br />
.<br />
.<br />
</genrelist> <br />
</data><br />
</response><br />
</source><br />
<br />
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''<br />
<br />
<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=true&f=json&k=[Your Dev ID]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''<br />
<source lang="javascript"><br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
"genrelist":{<br />
"genre":[<br />
{"id":2,"haschildren":false,"name":"AdultAlternative","parentid":1},<br />
{"id":3,"haschildren":false,"name":"Britpop","parentid":1},<br />
{"id":4,"haschildren":false,"name":"ClassicAlternative","parentid":1},<br />
{"id":205,"haschildren":false,"name":"RapMetal","parentid":195},<br />
{"id":195,"haschildren":true,"name":"Metal","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
]<br />
}<br />
}<br />
}<br />
</source><br />
<br />
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''<br />
<source lang="javascript"><br />
callbackfunctionname(<br />
{"response":{<br />
"statusCode":200,<br />
"statusText":"Ok"<br />
},<br />
"data":"{<br />
"genrelist":{<br />
"genre":[<br />
"genrelist":{<br />
"genre":[<br />
{"id":2,"haschildren":false,"name":"AdultAlternative","parentid":1},<br />
{"id":3,"haschildren":false,"name":"Britpop","parentid":1},<br />
{"id":4,"haschildren":false,"name":"ClassicAlternative","parentid":1},<br />
{"id":205,"haschildren":false,"name":"RapMetal","parentid":195},<br />
{"id":195,"haschildren":true,"name":"Metal","parentid":0},<br />
.<br />
.<br />
]<br />
}<br />
]<br />
}<br />
}<br />
}<br />
)<br />
</source><br />
<br />
<br />
=Other=<br />
<br />
==How To Tune Into A Station==<br />
<br />
To tune into a station, find the "id" of the station from the API results & make a call to <nowiki>http://yp.shoutcast.com/sbin/tunein-station.pls?id=[Station_id]</nowiki> by appending the station id.<br />
<br />
'''Ex:''' If the station id is 1025, Call => <nowiki>http://yp.shoutcast.com/sbin/tunein-station.pls?id=1025</nowiki><br />
<br />
<br />
==XML Caching==<br />
<br />
Do not cache the XML for more than 1 day, as station ID's can and will change.<br />
<br />
<br />
==Error Codes==<br />
<br />
The Error codes encountered when invalid data is input or passed to access the APIs are as below<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!HTTP Error Code<br />
!Error Message<br />
|-<br />
| 400 || Bad Request<br />
|-<br />
| 404 || Page Not Found<br />
|-<br />
| 440 || Invalid Devid<br />
|-<br />
| 460 || Missing required parameter<br />
|-<br />
| 462 || Parameter Error<br />
|-<br />
| 500 || Generic Server Error<br />
|}<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!Business Error Code<br />
!Error Message<br />
|-<br />
| 10001 || Internal Server error<br />
|-<br />
| 10002 || XML Root Element not matching<br />
|-<br />
| 10003 || Error while interacting with private api<br />
|}<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!General Error Code<br />
!Error Message<br />
|-<br />
| 20001 || Unable to find InitialContext<br />
|-<br />
| 20002 || Unable to acquire DataSource<br />
|-<br />
| 20003 || Unable to load SQL query<br />
|-<br />
| 20004 || Unable to load property file<br />
|-<br />
| 20005 || Unable to execute SQL query<br />
|-<br />
| 20006 || Unable to fetch ResultSet<br />
|-<br />
| 20007 || Error in finally block<br />
|-<br />
| 20008 || NullPointer Exception Raised<br />
|-<br />
| 20009 || Error while adding xml element<br />
|-<br />
| 20010 || Number Format Exception<br />
|-<br />
| 20011 || Error in creating xml document<br />
|-<br />
| 20012 || Null object received<br />
|-<br />
| 20012 || XML Data not found in Cache<br />
|-<br />
| 20013 || File not found<br />
|-<br />
| 20014 || Unable to connect to search api<br />
|-<br />
| 20015 || Error while building xml document<br />
|-<br />
| 20016 || Error while encoding url string<br />
|-<br />
| 20017 || Error while connecting to shoutcast api<br />
|-<br />
| 20018 || Error while processing the jsp<br />
|-<br />
| 20019 || Error while reading request object<br />
|-<br />
| 20020 || Error while sending email<br />
|-<br />
| 20021 || Invalid Response Type<br />
|-<br />
| 20022 || Maximum Value Exceeded<br />
|-<br />
| 20023 || Error while connecting to AKES<br />
|-<br />
| 20024 || Error while building AKES response xml document<br />
|-<br />
| 20025 || No Data in AKES response xml document<br />
|-<br />
| 20026 || Missing required parm : (REFERRER)<br />
|-<br />
| 20027 || Invalid key received from<br />
|-<br />
| 20028 || Missing devId= or k= param<br />
|-<br />
| 20029 || Missing required parm : (k)<br />
|-<br />
| 20030 || Missing required parm : (keyType)<br />
|-<br />
| 20027 || Deny - authRequired fail<br />
|-<br />
| 20028 || Deny - usageLimited fail<br />
|-<br />
| 20029 || Deny - rightNotSet fail<br />
|-<br />
| 20030 || Deny - referrerUsageLimited fail<br />
|}</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Client_Metadata_DetailsSHOUTcast Client Metadata Details2014-10-08T17:46:17Z<p>DrO: Protected "SHOUTcast Client Metadata Details" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))</p>
<hr />
<div>Details to follow...</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Client_Metadata_DetailsSHOUTcast Client Metadata Details2014-10-08T17:46:05Z<p>DrO: Created page with "Details to follow..."</p>
<hr />
<div>Details to follow...</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcastSHOUTcast2014-10-06T17:30:35Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
Here you can find information ahout the different products that make up SHOUTcast... more details to come.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_BroadcasterSHOUTcast Broadcaster2014-10-06T17:29:44Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
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.<br />
<br />
<br />
=SHOUTcast Overview=<br />
<br />
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 />
<br />
<br />
=Getting Started=<br />
<br />
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]]'''<br />
'''Important:''' You need to be happy with the use of command-line tools before attempting to install or run a<br />
SHOUTcast system as all versions of the v2 Server and Transcoder are designed to work as command-line tools.<br />
<br />
Current versions of the SHOUTcast tools can be obtained from:<br />
<br />
::'''[http://www.shoutcast.com/broadcast-tools/ Broadcast Tool Downloads]'''<br />
::or<br />
::'''[http://forums.winamp.com/showthread.php?t=324877 Support Forum Current Downloads Summary] (*)'''<br />
<br />
The forum link is a summary page and contains links to the latest versions of the tools such as when a new<br />
release has just happened or is being tested before it is provided via the '''[http://www.shoutcast.com/broadcast-tools/ Broadcast Tool Downloads]''' page.<br />
<br />
<br />
==Core Documentation==<br />
<br />
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.<br />
<br />
::'''[[SHOUTcast_DNAS_Server_2|SHOUTcast DNAS Server 2 (sc_serv)]]'''<br />
<br />
::'''[[SHOUTcast_DNAS_Transcoder_2|SHOUTcast DNAS Transcoder 2 (sc_trans)]]'''<br />
<br />
::'''[[Source_DSP_Plug-in|SHOUTcast Source DSP Plug-in (dsp_sc)]]'''<br />
<br />
<br />
==Supporting Documentation==<br />
<br />
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.<br />
<br />
::'''[[SHOUTcast_Authhash_Management|SHOUTcast Authhash Management]]'''<br />
<br />
::'''[[SHOUTcast_DNAS_Server_2_XML_Reponses|SHOUTcast DNAS Server 2 XML Reponses]]'''<br />
<br />
::'''[[Source_DSP_Plug-in_Configuration_Examples|SHOUTcast Source DSP Plug-in Configuration Examples]]'''<br />
<br />
::'''[[SHOUTcast_Transcoder_AJAX_api_Specification|SHOUTcast Transcoder AJAX api Specification]]'''<br />
<br />
::'''[[SHOUTcast_Calendar_Event_XML_File_Specification|SHOUTcast Calendar Event XML File Specification]]'''<br />
<br />
::'''[[SHOUTcast_YP_Nak_Errors|SHOUTcast YP Nak Error Information]]'''</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Streaming_ServiceSHOUTcast Streaming Service2014-10-06T17:29:24Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
Here you can find information ahout the SHOUTcast Streaming Service... more details to come.</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_DeveloperSHOUTcast Developer2014-10-06T17:28:54Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
<br />
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.<br />
<br />
::'''[[SHOUTcast_Radio_Directory_API|SHOUTcast Radio Directory Partner API Documentation]]''' - Reference for accessing information from the Radio Directory<br />
<br />
::'''[[SHOUTcast_Radio_Authhash_API|SHOUTcast Radio Authhash Partner API Documentation]]''' - Reference for accessing the SHOUTcast 2 Authhash Management API<br />
<br />
::'''[[SHOUTcast_2_%28Ultravox_2.1%29_Protocol_Details|SHOUTcast / Ultravox 2.1 Protocol Details]]''' - Reference for anyone wanting to implement clients or servers supporting the SHOUTcast 2 protocol<br />
<br />
::'''[[SHOUTcast_XML_Metadata_Specification|SHOUTcast XML Metadata Specification]]'''</div>DrOhttp://wiki.winamp.com/wiki/Template:NavBarTemplate:NavBar2014-10-06T17:15:34Z<p>DrO: </p>
<hr />
<div>[[Main_Page|Wiki Main]] | [[Skin Developer]] | [[Visual Developer]] | [[Plug-in Developer]] | [[Online Service Developer]] | [[SHOUTcast Broadcaster|SHOUTcast Tools & Services]] | [[Articles|Articles Page]] | [[Developers FAQ|FAQ]] | [[Glossary]]</div>DrOhttp://wiki.winamp.com/wiki/Template:NavBarSCTemplate:NavBarSC2014-10-06T17:14:00Z<p>DrO: </p>
<hr />
<div>[[SHOUTcast|SHOUTcast Home]] | [[SHOUTcast Broadcaster]] | [[SHOUTcast Developer]] | [[SHOUTcast Streaming Service]]</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_DeveloperSHOUTcast Developer2014-10-06T12:33:28Z<p>DrO: </p>
<hr />
<div>{{Template:NavBarSC}}<br />
<br />
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.<br />
<br />
::'''[[SHOUTcast_Radio_Directory_API|SHOUTcast Radio Directory Partner API Documentation]]''' - Reference for accessing information from the Radio Directory<br />
<br />
::'''[[SHOUTcast_Radio_Authhash_API|SHOUTcast Radio Authhash Partner API Documentation]]''' - Reference for accessing the SHOUTcast 2 Authhash Management API<br />
<br />
::'''[[SHOUTcast_2_%28Ultravox_2.1%29_Protocol_Details|SHOUTcast / Ultravox 2.1 Protocol Details]]''' - Reference for anyone wanting to implement clients or servers supporting the SHOUTcast 2 protocol<br />
<br />
::'''[[SHOUTcast_XML_Metadata_Specification|SHOUTcast XML Metadata Specification]]'''</div>DrOhttp://wiki.winamp.com/wiki/SHOUTcast_Radio_Authhash_APISHOUTcast Radio Authhash API2014-09-18T14:32:10Z<p>DrO: Update required fields change + increase of the description field size</p>
<hr />
<div>==Introduction==<br />
<br />
A key aspect of the SHOUTcast 2.0 system is the usage of authorisation keys to control the listing of stations within the SHOUTcast Radio Directory (otherwise known as the YP).<br />
<br />
The API which is documented here is provided as a means for registered developers to be able to obtain and manage any authorisation keys for the station(s) they are providing.<br />
<br />
<br />
==API Overview==<br />
<br />
There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):<br />
<br />
:[[#Create_Authorisation_Key|Create]]<br />
:[[#Check_Authorisation_Key|Check]]<br />
:[[#Update_Authorisation_Key|Update]]<br />
:[[#Remove_Authorisation_Key|Remove]]<br />
<br />
The authorisation key APIs are xml based responses which provide information and status details of the provided API methods in a common style to ease implementation and usage.<br />
<br />
The API methods are called by passing parameters to the required YP site url.<br />
<br />
When the API methods are called then the status code of the method response is set to the status code of the API method so it is easy to detect errors from calling the API method.<br />
<br />
<br />
===Successful Response===<br />
----<br />
<br />
If there are no issues with the API method call then one of the following responses will be received as the response generated.<br />
<br />
<br />
The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:<br />
<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
</response><br />
</source><br />
<br />
The second response is the '''full''' success response and is provided when the API method needs to return additional information such as the authorisation key when a new one is created or the details of the authorisation key when using the ''''check'''' method:<br />
<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<!-- information is found here --><br />
</data><br />
</response><br />
</source><br />
<br />
<br />
===Error Response===<br />
----<br />
<br />
If there are issues experienced during the API method call then an error response will be received which takes the following form:<br />
<br />
<source lang="xml"><br />
<response><br />
<statusCode>440</statusCode><br />
<statusText>Invalid devId</statusText><br />
<!-- the following is optional dependent upon the error --><br />
<statusDetailText>Invalid parameter k</statusDetailText><br />
</response><br />
</source><br />
<br />
In all uses of the API methods, the ''''statusCode'''' and ''''statusText'''' elements are provided when an error occurs. The ''''statusDetailText'''' value is an optional element and is only provided if the internal error handling is able to provide additional information. This will usually be present for errors relating to parameter issues i.e. missing parameters.<br />
<br />
See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.<br />
<br />
<br />
==API Usage==<br />
<br />
The following sections detail how to use the four authorisation key API methods.<br />
<br />
Importantly, once an authorisation key has been created then it will be locked to the Developer ID used so you can only check, update or remove authorisation keys against that Developer ID.<br />
<br />
<br />
===Create Authorisation Key===<br />
----<br />
<br />
This will create an authorisation key and will return it in the xml response on success.<br />
<br />
Any parameters which are not specified and do not cause an error will be left at their default values which will be indicated by empty xml elements when using the ''''check'''' API.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Misc&[Optional Parameters To Set]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* k - Developer ID for accessing the API<br />
* stationname - name of the station as listed in the YP listings up to 100 characters<br />
* genre - genre describing the station (see [[#Additional_Resources|section 4.0]] for getting supported genres or [[#Supported_Genres|section 4.2]] for list of supported genre values)<br />
* email - contact address for the station up to 255 characters (this is so we can contact you easily in-case of an issue with your listing or needing to inform you of a required DNAS update)<br />
<br />
'''<span style="color:#FF6600;">Recommended Optional Parameters:</span>'''<br />
''(These are marked as optional but are likely to be made required in a future update)''<br />
<br />
* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)<br />
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
<br />
* website - related url for station up to 128 characters<br />
* description - brief description about the station up to 65535 characters<br />
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)<br />
* city - more specific place where the stream is based or related up to 128 characters<br />
* keywords - separated tag words about the stream up to 120 characters<br />
* private - determine if the primary server should be public (0 - default) or not (1)<br />
<br />
It is recommended to fill in as many of these optional details where possible<br />
to improve usability with any future YP features which may be introduced.<br />
<br />
'''<span style="color:#FF6600;">Response:</span>'''<br />
<br />
Returns a '''full''' success response containing the new authorisation key or the standard error response.<br />
<br />
'''<span style="color:#FF6600;">Example Response</span>'''<br />
<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<authhash>An_Authorisation_Key</authhash><br />
</data><br />
</response><br />
</source><br />
<br />
<br />
===Check Authorisation Key===<br />
----<br />
<br />
This will remove an authorisation key as long as it was created by the Developer ID used.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* k - Developer ID for accessing the API<br />
* authhash - Authorisation Key to check<br />
<br />
'''<span style="color:#FF6600;">Response:</span>'''<br />
<br />
Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.<br />
<br />
'''<span style="color:#FF6600;">Example Response</span>'''<br />
<br />
<source lang="xml"><br />
<response><br />
<statusCode>200</statusCode><br />
<statusText>Ok</statusText><br />
<data><br />
<stationname>The Station Name</stationname><br />
<genre>Misc</genre><br />
<website>www.shoutcast.com</website><br />
<description>The Best Station Ever...!</description><br />
<langid>EN</langid><br />
<countryiso>US</countryiso><br />
<stateiso>00</stateiso><br />
<city></city><br />
<keywords>Greatest Web Station</keywords><br />
<private>0</private><br />
</data><br />
</response><br />
</source><br />
<br />
The <stateiso> element will only be returned if the <countryiso> element is 'US'.<br />
<br />
<br />
===Update Authorisation Key===<br />
----<br />
<br />
This will update an authorisation key as long as it was created by the Developer ID used.<br />
<br />
Any parameters which are not specified and do not cause an error when making an update are reset to their default value when this completes. Otherwise this acts the same as the ''''create'''' API with the addition of specifying the authorisation key to update.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://yp.shoutcast.com/updateauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]&stationname=The Station Name&genre=Misc&[Other Parameters To Update]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* k - Developer ID for accessing the API<br />
* authhash - Authorisation Key to update<br />
* stationname - name of the station as listed in the YP listings up to 100 characters<br />
* genre - genre describing the station (see [[#Additional_Resources|section 4.0]] for getting supported genres or [[#Supported_Genres|section 4.2]] for list of supported genre values)<br />
* email - contact address for the station up to 255 characters (this is so we can contact you easily in-case of an issue with your listing or needing to inform you of a required DNAS update)<br />
<br />
'''<span style="color:#FF6600;">Recommended Optional Parameters:</span>'''<br />
''(These are marked as optional but are likely to be made required in a future update)''<br />
<br />
* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)<br />
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)<br />
<br />
'''<span style="color:#FF6600;">Optional Parameters:</span>'''<br />
<br />
* website - related url for station up to 128 characters<br />
* description - brief description about the station up to 65535 characters<br />
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)<br />
* city - more specific place where the stream is based or related up to 128 characters<br />
* keywords - separated tag words about the stream up to 120 characters<br />
* private - determine if the primary server should be public (0 - default) or not (1)<br />
<br />
It is recommended to fill in as many of these optional details where possible<br />
to improve usability with any future YP features which may be introduced.<br />
<br />
'''<span style="color:#FF6600;">Response:</span>'''<br />
<br />
Returns a '''basic''' success response or the standard error response.<br />
<br />
<br />
===Remove Authorisation Key===<br />
----<br />
<br />
This will remove an authorisation key as long as it was created by the Developer ID used.<br />
<br />
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki><br />
<br />
'''<span style="color:#FF6600;">Required Parameters:</span>'''<br />
<br />
* k - Developer ID for accessing the API<br />
* authhash - Authorisation Key to remove<br />
<br />
'''<span style="color:#FF6600;">Response:</span>'''<br />
<br />
Returns a '''basic''' success response or the standard error response.<br />
<br />
<br />
<br />
==Additional Resources==<br />
<br />
In addition to the core API methods, some additional methods are provided for accessing the supported primary and secondary genres, country, state and language codes. These are provided as a means to check you are using the correct values or to use if creating your own interface around the core authorisation key APIs.<br />
<br />
<br />
These additional methods are accessed via <nowiki>http://yp.shoutcast.com/authutil_*</nowiki> where '''*''' is then replaced with one of the following to get the required information:<br />
<br />
* '''country''' - provides provides a html select control containing the ISO 3166-1-alpha-2 code and a displayable string for each option in the control<br />
<br />
* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control<br />
<br />
* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control<br />
<br />
* '''primarygenre''' - provides a html select control of the primary genre's recognised<br />
<br />
* '''secondarygenre?primarygenre=<genre>''' - provides a html select control of the secondary genre's related to the primary genre passed or an empty response if there is no genres found<br />
<br />
* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre<br />
<br />
<br />
All additional methods (excluding the ''''parentgenre'''' method) provide a fully formed html select control which is filled with relevent values based on the parameter passed to the method (if applicable). These are done like this to allow for ease of insertion into a<br />
<div> element for example with an interface used to control the APIs.<br />
<br />
Calling these additional methods (excluding the ''''parentgenre'''' method) with ''''&raw=1'''' in the url will output the result (if applicable) as plain text instead of as a html select control. The values returned are separated by a comma and each data pair is then placed on a new line. This is provided as a quick way of getting the recognised values if the html select control is not suitable.<br />
<br />
<br />
===User Interface Versions===<br />
----<br />
<br />
In addition to the core API methods, specifying ''''ui_'''' on the front of the API method e.g. <nowiki>http://yp.shoutcast.com/ui_checkauthhash</nowiki> for the ''''check'''' method provides a pre-built interface pages which can be used as a base point for making your own interface for the authorisation key APIs or to use as is as long as you have the required developer access.<br />
<br />
<br />
===Supported Genres===<br />
----<br />
<br />
The genre specified for an authhash can only be a primary genre (e.g. Misc) or it can be a secondary genre related to a chosen primary genre (e.g. House from Electronic). The following lists the supported primary genres and the associated secondary genres to them.<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!Primary Genre<br />
!Associated Secondary Genres<br />
|-<br />
| Alternative || Adult Alternative, Britpop, Classic Alternative, College, Dancepunk, Dream Pop, Emo, Goth, Grunge, Hardcore, Indie Pop, Indie Rock, Industrial, LoFi, Modern Rock, New Wave, Noise Pop, Post Punk, Power Pop, Punk, Ska, Xtreme<br />
|-<br />
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues<br />
|-<br />
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony<br />
|-<br />
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western<br />
|-<br />
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s<br />
|-<br />
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop<br />
|-<br />
| Electronic || Acid House, Ambient, Big Beat, Breakbeat, Dance, Demo, Disco, Downtempo, Drum and Bass, Dubstep, Electro, Garage, Hard House, House, IDM, Jungle, Progressive, Techno, Trance, Tribal, Trip Hop<br />
|-<br />
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk<br />
|-<br />
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel<br />
|-<br />
| International || African, Afrikaans, Arabic, Asian, Bollywood, Brazilian, Caribbean, Celtic, Chinese, Creole, European, Filipino, French, German, Greek, Hawaiian and Pacific, Hebrew, Hindi, Indian, Islamic, Japanese, Klezmer, Korean, Mediterranean, Middle Eastern, North American, Russian, Soca, South American, Tamil, Turkish, Worldbeat, Zouk<br />
|-<br />
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion<br />
|-<br />
| Latin || Bachata, Banda, Bossa Nova, Cumbia, Flamenco, Latin Dance, Latin Pop, Latin Rap and Hip Hop, Latin Rock, Mariachi, Merengue, Ranchera, Reggaeton, Regional Mexican, Salsa, Samba, Tango, Tejano, Tropicalia<br />
|-<br />
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal<br />
|-<br />
| Misc || <br />
|-<br />
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual<br />
|-<br />
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop<br />
|-<br />
| Public Radio || College, News, Sports, Talk, Weather<br />
|-<br />
| R&B and Urban || <br />
|-<br />
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap<br />
|-<br />
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady<br />
|-<br />
| Rock || Adult Album Alternative, British Invasion, Celtic Rock, Classic Rock, Garage Rock, Glam, Hard Rock, Jam Bands, JROCK, Piano Rock, Prog Rock, Psychedelic, Rock & Roll, Rockabilly, Singer and Songwriter, Surf<br />
|-<br />
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter<br />
|-<br />
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music<br />
|-<br />
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology<br />
|-<br />
| Themes || Adult, Best Of, Chill, Eclectic, Experimental, Female, Heartache, Instrumental, LGBT, Love and Romance, Party Mix, Patriotic, Rainy Day Mix, Reality, Se xy ''(remove space for actual word - spam filter display issue)'', Shuffle, Travel Mix, Tribute, Trippy, Work Mix<br />
|}<br />
<br />
===Illegal Input Values===<br />
----<br />
<br />
The following values are not allowed when entered as the stationname (case insensitively) and will cause a 456 error response to be received when an authorisation key is created or updated as they are not easily found when multiple other listings are also using the same stationame.<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
| 127.0.0.1 || admin || auto dj || auto jedi<br />
|-<br />
| auto pj || auto-dj || autodj || autopj<br />
|-<br />
| demo || dj || internet radio || live<br />
|-<br />
| local server || localhost || localserver || music<br />
|-<br />
| my radio || my server || my station name || my test server<br />
|-<br />
| n/a || pj || playlist || radio<br />
|-<br />
| radio station || test || test server || unnamed server<br />
|-<br />
| virtual dj || virtualdj || web rdio || web radio<br />
|-<br />
| song || teste || default stream || radio stream<br />
|}<br />
<br />
Additionally, stationnames just containing punctuation are not allowed as well as any which specify a name which matches with the supported genres (see [[SHOUTcast_Radio_Authhash_API#Supported_Genres|section 4.2]]).<br />
<br />
<br />
==Status Codes==<br />
<br />
The following status codes are returned on success or error when using the provided APIs:<br />
<br />
::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"<br />
|-<br />
!Code<br />
!Status Text<br />
!Detailed Text (if available)<br />
|-<br />
| 200 || Ok || n/a<br />
|-<br />
| 400 || Generic Error || n/a<br />
|-<br />
| 404 || Page Not Found || n/a<br />
|-<br />
| 440 || Invalid devId || Invalid parameter k<br />
|-<br />
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed<br />
|-<br />
| 458 || Building internal value failure || n/a<br />
|-<br />
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'<br />
|-<br />
| 460 || Missing required parameter || Missing ''<variable>''<br />
|-<br />
| 461 || Error while updating authhash || n/a<br />
|-<br />
| 462 || Parameter error || Invalid parameter <variable><br />
|-<br />
| 463 || Invalid station result returned || n/a<br />
|-<br />
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'<br />
|-<br />
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter<br />
|-<br />
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long<br />
|-<br />
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized<br />
|-<br />
| 468 || Error creating intended xml response || n/a<br />
|-<br />
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'<br />
|-<br />
| 470 || Invalid authorization hash || n/a<br />
|-<br />
| 500 || Generic Server Error || n/a<br />
|}<br />
<br />
Note: The ''<variable>'' value in the detailed text will be replaced with the parameter name which the error relates to. The ''<value>'' value in the detailed text will be replaced with the parameter value which the error relates to.</div>DrOhttp://wiki.winamp.com/wiki/Template:NavBarSCTemplate:NavBarSC2014-09-08T16:24:59Z<p>DrO: </p>
<hr />
<div>[[SHOUTcast|SHOUTcast Home]] : [[SHOUTcast Broadcaster]] : [[SHOUTcast Developer]] : [[SHOUTcast Streaming Service]]</div>DrOhttp://wiki.winamp.com/wiki/Template:NavBarSCTemplate:NavBarSC2014-09-08T16:24:37Z<p>DrO: </p>
<hr />
<div>[[Main_Page|Winamp Home]] : [[SHOUTcast|SHOUTcast Home]] : [[SHOUTcast Broadcaster]] : [[SHOUTcast Developer]] : [[SHOUTcast Streaming Service]]</div>DrOhttp://wiki.winamp.com/wiki/Template:NavBarSCTemplate:NavBarSC2014-09-08T16:24:08Z<p>DrO: </p>
<hr />
<div>[[Main_Page|Wiki Main & Winamp]] : [[SHOUTcast|SHOUTcast Home]] : [[SHOUTcast Broadcaster]] : [[SHOUTcast Developer]] : [[SHOUTcast Streaming Service]]</div>DrO