Winamp Developer Wiki - User contributions [en]

SHOUTcast Getting Started Guide

2022-10-06T10:48:15Z

Djegg: /* Transcoder */

{{Template:NavBarSC}}

==Introduction==

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.

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]].

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.

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.

===What is SHOUTcast?===
----

If you are new to SHOUTcast then this is probably something you may have already asked or you are trying to find out.

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.

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.

So a simple SHOUTcast setup would consist of the following:

Winamp + DSP ? DNAS [sc_serv] ? Winamp
(Source) (Server) (Client)

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]]).

===Windows Users===
----

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).

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.

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.

===Windows Vista / 7 Specifics===
----

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.

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.

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.

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.

'''(*)''' 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'.

==What is Required?==

To make your SHOUTcast system you will need the following software tools and hardware:

:*A computer running on a supported operating system ([[#Supported_Operating_Systems|see section 2.1]])
:*SHOUTcast DNAS Server
:*An input source (Transcoder or Winamp plus Source DSP plug-in)
:*Media or DJ's or a Capture device i.e. the content you want to provide to people

===Supported Operating Systems===
----

There are versions of the DNAS Server and Transcoder available on the following operating systems:

:*Windows 32-bit     Windows 2000, XP, Vista, Windows 7, 8, 10
:*Windows 64-bit     64-bit versions of Windows XP, Vista, Windows 7, 8, 10
:*Linux 32-bit
:*Linux 64-bit
:*BSD 8.x                 v2.4.7 only, not higher
:*Mac OS X (Intel)   Should work on 10.4.4 and up though is only tested against 10.5.5 (DNAS v2.4.7 only, not higher)

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.

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.

==Getting Installed==

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.

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.

===Download the Correct Version===
----

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.

Current versions of the SHOUTcast tools can be obtained from:

:*http://www.shoutcast.com/pricing
:*http://forums.winamp.com/showthread.php?t=324877 '''(*)'''

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).

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.

'''(*)''' 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.

===Choose an Install Location===
----

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.

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.

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]]).

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.

===Installation===
----

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.

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]].

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.

===Setting Up The Tools===
----

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.

Ensuring the Server is properly configured is the most important thing as unless it
is and running then none of the tools will be able to connect to it successfully.

===Server===
----

====Server Configuration Setup====
----

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.

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_serv_basic''' - shows how to get a more multi-stream setup working
::'''sc_serv_public''' - shows how to make a public server from sc_serv_basic
::'''sc_serv_relay''' - shows how to relay another source

There is more information about these example configurations in sc_serv2.txt - [[SHOUTcast_DNAS_Server_2#Example_Configurations|section 10]]

====Starting the Server====
----

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.

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:

::For Windows - '''sc_serv.exe sc_serv_simple.conf'''
::For non-Windows - '''./sc_serv sc_serv_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Server====
----

Skip this if you experience no error reports when trying to run the Server.

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.

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.

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.

====Obtaining An Authhash====
----

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 [https://radiomanager.shoutcast.com/ RadioManager]. See [[SHOUTcast_Authhash_Management|Shoutcast Authhash Management]] for further details.

===Transcoder===
----

'''Note: The Transcoder is no longer maintained or supported.'''

'''This documentation remains here solely for legacy purposes.'''

====MP3 Streaming License====
----

'''Note: All mp3 patents have now expired so an encoding licence is no longer required.'''

Skip this if you are not setting up the Transcoder for MP3 streaming.

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]].

AAC encoding does not need you to purchase a license as one has
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]].

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:

unlockkeyname=Bob
unlockkeycode=123456

====Transcoder Configuration Setup====
----

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_trans_basic''' - shows how to get a basic setup without relying on the Server
::'''sc_trans_capture''' - shows how to use a capture device
::'''sc_trans_dj''' - shows how to setup a DJ connection
::'''sc_trans_playlist''' - shows how to use scheduled playlists

There is more information about these example configurations in [[SHOUTcast_DNAS_Transcoder_2#Example_Configurations|sc_trans.txt - section 11]]

====Starting the Transcoder====
----

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.

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:

::For Windows - '''sc_trans.exe sc_trans_simple.conf'''
::For non-Window - '''./sc_trans sc_trans_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Transcoder====
----

Skip this if you experience no error reports when trying to run the Transcoder.

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.

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.

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.

===Source DSP===
----

====Install Source DSP====
----

Skip this if you are not setting up the Source DSP plug-in for MP3 streaming.

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]]).

====Configuring the Source DSP====
----

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:

::the Server (from [[#Server_Configuration_Setup|section 3.5.1]]) if you are going to use the plug-in as the only source
:and / or
::the Transcoder (from [[#Transcoder_Configuration_Setup|section 3.6.2]]) if it is to act as a DJ source

====Starting the Source DSP====
----

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.

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.

(*) The string <version> would be the actual version of the plug-in which is installed.

===Completion===
----

You should now be up and running with a working SHOUTcast system. Happy broadcasting!

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.

==Further Information==

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.

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

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:

:*Your SHOUTcast setup including all versions of the tools being used
:*The issue you are experiencing
:*The steps needed to reproduce the issue
:*Anything else useful especially if you have been tinkering with options before the issue appeared

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.

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.

===Related Documentation===
----

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.

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
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.

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

===Configuration Builder===
----

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'.

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.

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).

==Glossary==

'''Client''' - This is a program run which will connect to the Server e.g. Winamp.

'''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.

'''Server''' - This is the program which is run on a machine to provide to Clients the Stream.

'''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.
'''
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).

'''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.

'''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.

'''dsp_sc''' - This is the name the SHOUTcast Source DSP plug-in is otherwise known as.

'''sc_trans''' - This is the name the SHOUTcast Transcoder is otherwise known as.

'''sc_serv''' or '''sc_serv2''' - This is the name the SHOUTcast DNAS Server is otherwise known as.

SHOUTcast Getting Started Guide

2022-10-06T10:47:47Z

Djegg: /* MP3 Streaming License */

SHOUTcast Getting Started Guide

2022-10-06T10:47:22Z

Djegg: /* Transcoder */

{{Template:NavBarSC}}

==Introduction==

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.

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]].

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.

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.

===What is SHOUTcast?===
----

If you are new to SHOUTcast then this is probably something you may have already asked or you are trying to find out.

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.

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.

So a simple SHOUTcast setup would consist of the following:

Winamp + DSP ? DNAS [sc_serv] ? Winamp
(Source) (Server) (Client)

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]]).

===Windows Users===
----

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).

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.

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.

===Windows Vista / 7 Specifics===
----

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.

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.

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.

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.

'''(*)''' 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'.

==What is Required?==

To make your SHOUTcast system you will need the following software tools and hardware:

:*A computer running on a supported operating system ([[#Supported_Operating_Systems|see section 2.1]])
:*SHOUTcast DNAS Server
:*An input source (Transcoder or Winamp plus Source DSP plug-in)
:*Media or DJ's or a Capture device i.e. the content you want to provide to people

===Supported Operating Systems===
----

There are versions of the DNAS Server and Transcoder available on the following operating systems:

:*Windows 32-bit     Windows 2000, XP, Vista, Windows 7, 8, 10
:*Windows 64-bit     64-bit versions of Windows XP, Vista, Windows 7, 8, 10
:*Linux 32-bit
:*Linux 64-bit
:*BSD 8.x                 v2.4.7 only, not higher
:*Mac OS X (Intel)   Should work on 10.4.4 and up though is only tested against 10.5.5 (DNAS v2.4.7 only, not higher)

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.

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.

==Getting Installed==

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.

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.

===Download the Correct Version===
----

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.

Current versions of the SHOUTcast tools can be obtained from:

:*http://www.shoutcast.com/pricing
:*http://forums.winamp.com/showthread.php?t=324877 '''(*)'''

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).

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.

'''(*)''' 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.

===Choose an Install Location===
----

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.

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.

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]]).

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.

===Installation===
----

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.

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]].

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.

===Setting Up The Tools===
----

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.

Ensuring the Server is properly configured is the most important thing as unless it
is and running then none of the tools will be able to connect to it successfully.

===Server===
----

====Server Configuration Setup====
----

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.

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_serv_basic''' - shows how to get a more multi-stream setup working
::'''sc_serv_public''' - shows how to make a public server from sc_serv_basic
::'''sc_serv_relay''' - shows how to relay another source

There is more information about these example configurations in sc_serv2.txt - [[SHOUTcast_DNAS_Server_2#Example_Configurations|section 10]]

====Starting the Server====
----

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.

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:

::For Windows - '''sc_serv.exe sc_serv_simple.conf'''
::For non-Windows - '''./sc_serv sc_serv_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Server====
----

Skip this if you experience no error reports when trying to run the Server.

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.

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.

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.

====Obtaining An Authhash====
----

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 [https://radiomanager.shoutcast.com/ RadioManager]. See [[SHOUTcast_Authhash_Management|Shoutcast Authhash Management]] for further details.

===Transcoder===
----

'''Note: The Transcoder is no longer maintained or supported.'''

'''This documentation remains here solely for legacy purposes.'''

====MP3 Streaming License====
----

'''Note: All mp3 patents have expired so an encoding licence is no longer required.'''

Skip this if you are not setting up the Transcoder for MP3 streaming.

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]].

AAC encoding does not need you to purchase a license as one has
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]].

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:

unlockkeyname=Bob
unlockkeycode=123456

====Transcoder Configuration Setup====
----

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_trans_basic''' - shows how to get a basic setup without relying on the Server
::'''sc_trans_capture''' - shows how to use a capture device
::'''sc_trans_dj''' - shows how to setup a DJ connection
::'''sc_trans_playlist''' - shows how to use scheduled playlists

There is more information about these example configurations in [[SHOUTcast_DNAS_Transcoder_2#Example_Configurations|sc_trans.txt - section 11]]

====Starting the Transcoder====
----

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.

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:

::For Windows - '''sc_trans.exe sc_trans_simple.conf'''
::For non-Window - '''./sc_trans sc_trans_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Transcoder====
----

Skip this if you experience no error reports when trying to run the Transcoder.

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.

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.

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.

===Source DSP===
----

====Install Source DSP====
----

Skip this if you are not setting up the Source DSP plug-in for MP3 streaming.

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]]).

====Configuring the Source DSP====
----

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:

::the Server (from [[#Server_Configuration_Setup|section 3.5.1]]) if you are going to use the plug-in as the only source
:and / or
::the Transcoder (from [[#Transcoder_Configuration_Setup|section 3.6.2]]) if it is to act as a DJ source

====Starting the Source DSP====
----

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.

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.

(*) The string <version> would be the actual version of the plug-in which is installed.

===Completion===
----

You should now be up and running with a working SHOUTcast system. Happy broadcasting!

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.

==Further Information==

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.

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

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:

:*Your SHOUTcast setup including all versions of the tools being used
:*The issue you are experiencing
:*The steps needed to reproduce the issue
:*Anything else useful especially if you have been tinkering with options before the issue appeared

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.

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.

===Related Documentation===
----

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.

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
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.

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

===Configuration Builder===
----

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'.

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.

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).

==Glossary==

'''Client''' - This is a program run which will connect to the Server e.g. Winamp.

'''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.

'''Server''' - This is the program which is run on a machine to provide to Clients the Stream.

'''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.
'''
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).

'''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.

'''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.

'''dsp_sc''' - This is the name the SHOUTcast Source DSP plug-in is otherwise known as.

'''sc_trans''' - This is the name the SHOUTcast Transcoder is otherwise known as.

'''sc_serv''' or '''sc_serv2''' - This is the name the SHOUTcast DNAS Server is otherwise known as.

SHOUTcast Getting Started Guide

2022-10-06T10:45:31Z

Djegg: /* Obtaining An Authhash */

{{Template:NavBarSC}}

==Introduction==

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.

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]].

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.

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.

===What is SHOUTcast?===
----

If you are new to SHOUTcast then this is probably something you may have already asked or you are trying to find out.

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.

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.

So a simple SHOUTcast setup would consist of the following:

Winamp + DSP ? DNAS [sc_serv] ? Winamp
(Source) (Server) (Client)

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]]).

===Windows Users===
----

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).

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.

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.

===Windows Vista / 7 Specifics===
----

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.

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.

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.

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.

'''(*)''' 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'.

==What is Required?==

To make your SHOUTcast system you will need the following software tools and hardware:

:*A computer running on a supported operating system ([[#Supported_Operating_Systems|see section 2.1]])
:*SHOUTcast DNAS Server
:*An input source (Transcoder or Winamp plus Source DSP plug-in)
:*Media or DJ's or a Capture device i.e. the content you want to provide to people

===Supported Operating Systems===
----

There are versions of the DNAS Server and Transcoder available on the following operating systems:

:*Windows 32-bit     Windows 2000, XP, Vista, Windows 7, 8, 10
:*Windows 64-bit     64-bit versions of Windows XP, Vista, Windows 7, 8, 10
:*Linux 32-bit
:*Linux 64-bit
:*BSD 8.x                 v2.4.7 only, not higher
:*Mac OS X (Intel)   Should work on 10.4.4 and up though is only tested against 10.5.5 (DNAS v2.4.7 only, not higher)

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.

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.

==Getting Installed==

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.

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.

===Download the Correct Version===
----

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.

Current versions of the SHOUTcast tools can be obtained from:

:*http://www.shoutcast.com/pricing
:*http://forums.winamp.com/showthread.php?t=324877 '''(*)'''

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).

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.

'''(*)''' 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.

===Choose an Install Location===
----

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.

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.

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]]).

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.

===Installation===
----

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.

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]].

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.

===Setting Up The Tools===
----

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.

Ensuring the Server is properly configured is the most important thing as unless it
is and running then none of the tools will be able to connect to it successfully.

===Server===
----

====Server Configuration Setup====
----

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.

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_serv_basic''' - shows how to get a more multi-stream setup working
::'''sc_serv_public''' - shows how to make a public server from sc_serv_basic
::'''sc_serv_relay''' - shows how to relay another source

There is more information about these example configurations in sc_serv2.txt - [[SHOUTcast_DNAS_Server_2#Example_Configurations|section 10]]

====Starting the Server====
----

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.

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:

::For Windows - '''sc_serv.exe sc_serv_simple.conf'''
::For non-Windows - '''./sc_serv sc_serv_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Server====
----

Skip this if you experience no error reports when trying to run the Server.

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.

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.

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.

====Obtaining An Authhash====
----

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 [https://radiomanager.shoutcast.com/ RadioManager]. See [[SHOUTcast_Authhash_Management|Shoutcast Authhash Management]] for further details.

===Transcoder===
----

====MP3 Streaming License====
----

Skip this if you are not setting up the Transcoder for MP3 streaming.

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]].

AAC encoding does not need you to purchase a license as one has
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]].

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:

unlockkeyname=Bob
unlockkeycode=123456

====Transcoder Configuration Setup====
----

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_trans_basic''' - shows how to get a basic setup without relying on the Server
::'''sc_trans_capture''' - shows how to use a capture device
::'''sc_trans_dj''' - shows how to setup a DJ connection
::'''sc_trans_playlist''' - shows how to use scheduled playlists

There is more information about these example configurations in [[SHOUTcast_DNAS_Transcoder_2#Example_Configurations|sc_trans.txt - section 11]]

====Starting the Transcoder====
----

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.

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:

::For Windows - '''sc_trans.exe sc_trans_simple.conf'''
::For non-Window - '''./sc_trans sc_trans_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Transcoder====
----

Skip this if you experience no error reports when trying to run the Transcoder.

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.

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.

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.

===Source DSP===
----

====Install Source DSP====
----

Skip this if you are not setting up the Source DSP plug-in for MP3 streaming.

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]]).

====Configuring the Source DSP====
----

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:

::the Server (from [[#Server_Configuration_Setup|section 3.5.1]]) if you are going to use the plug-in as the only source
:and / or
::the Transcoder (from [[#Transcoder_Configuration_Setup|section 3.6.2]]) if it is to act as a DJ source

====Starting the Source DSP====
----

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.

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.

(*) The string <version> would be the actual version of the plug-in which is installed.

===Completion===
----

You should now be up and running with a working SHOUTcast system. Happy broadcasting!

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.

==Further Information==

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.

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

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:

:*Your SHOUTcast setup including all versions of the tools being used
:*The issue you are experiencing
:*The steps needed to reproduce the issue
:*Anything else useful especially if you have been tinkering with options before the issue appeared

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.

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.

===Related Documentation===
----

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.

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
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.

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

===Configuration Builder===
----

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'.

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.

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).

==Glossary==

'''Client''' - This is a program run which will connect to the Server e.g. Winamp.

'''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.

'''Server''' - This is the program which is run on a machine to provide to Clients the Stream.

'''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.
'''
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).

'''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.

'''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.

'''dsp_sc''' - This is the name the SHOUTcast Source DSP plug-in is otherwise known as.

'''sc_trans''' - This is the name the SHOUTcast Transcoder is otherwise known as.

'''sc_serv''' or '''sc_serv2''' - This is the name the SHOUTcast DNAS Server is otherwise known as.

SHOUTcast Getting Started Guide

2022-10-06T10:41:52Z

Djegg: /* Obtaining An Authhash */

{{Template:NavBarSC}}

==Introduction==

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.

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]].

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.

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.

===What is SHOUTcast?===
----

If you are new to SHOUTcast then this is probably something you may have already asked or you are trying to find out.

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.

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.

So a simple SHOUTcast setup would consist of the following:

Winamp + DSP ? DNAS [sc_serv] ? Winamp
(Source) (Server) (Client)

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]]).

===Windows Users===
----

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).

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.

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.

===Windows Vista / 7 Specifics===
----

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.

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.

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.

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.

'''(*)''' 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'.

==What is Required?==

To make your SHOUTcast system you will need the following software tools and hardware:

:*A computer running on a supported operating system ([[#Supported_Operating_Systems|see section 2.1]])
:*SHOUTcast DNAS Server
:*An input source (Transcoder or Winamp plus Source DSP plug-in)
:*Media or DJ's or a Capture device i.e. the content you want to provide to people

===Supported Operating Systems===
----

There are versions of the DNAS Server and Transcoder available on the following operating systems:

:*Windows 32-bit     Windows 2000, XP, Vista, Windows 7, 8, 10
:*Windows 64-bit     64-bit versions of Windows XP, Vista, Windows 7, 8, 10
:*Linux 32-bit
:*Linux 64-bit
:*BSD 8.x                 v2.4.7 only, not higher
:*Mac OS X (Intel)   Should work on 10.4.4 and up though is only tested against 10.5.5 (DNAS v2.4.7 only, not higher)

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.

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.

==Getting Installed==

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.

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.

===Download the Correct Version===
----

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.

Current versions of the SHOUTcast tools can be obtained from:

:*http://www.shoutcast.com/pricing
:*http://forums.winamp.com/showthread.php?t=324877 '''(*)'''

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).

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.

'''(*)''' 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.

===Choose an Install Location===
----

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.

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.

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]]).

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.

===Installation===
----

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.

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]].

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.

===Setting Up The Tools===
----

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.

Ensuring the Server is properly configured is the most important thing as unless it
is and running then none of the tools will be able to connect to it successfully.

===Server===
----

====Server Configuration Setup====
----

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.

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_serv_basic''' - shows how to get a more multi-stream setup working
::'''sc_serv_public''' - shows how to make a public server from sc_serv_basic
::'''sc_serv_relay''' - shows how to relay another source

There is more information about these example configurations in sc_serv2.txt - [[SHOUTcast_DNAS_Server_2#Example_Configurations|section 10]]

====Starting the Server====
----

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.

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:

::For Windows - '''sc_serv.exe sc_serv_simple.conf'''
::For non-Windows - '''./sc_serv sc_serv_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Server====
----

Skip this if you experience no error reports when trying to run the Server.

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.

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.

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.

====Obtaining An Authhash====
----

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 [https://radiomanager.shoutcast.com/|RadioManager]. See [[SHOUTcast_Authhash_Management|Shoutcast Authhash Management]] for further details.

===Transcoder===
----

====MP3 Streaming License====
----

Skip this if you are not setting up the Transcoder for MP3 streaming.

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]].

AAC encoding does not need you to purchase a license as one has
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]].

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:

unlockkeyname=Bob
unlockkeycode=123456

====Transcoder Configuration Setup====
----

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_trans_basic''' - shows how to get a basic setup without relying on the Server
::'''sc_trans_capture''' - shows how to use a capture device
::'''sc_trans_dj''' - shows how to setup a DJ connection
::'''sc_trans_playlist''' - shows how to use scheduled playlists

There is more information about these example configurations in [[SHOUTcast_DNAS_Transcoder_2#Example_Configurations|sc_trans.txt - section 11]]

====Starting the Transcoder====
----

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.

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:

::For Windows - '''sc_trans.exe sc_trans_simple.conf'''
::For non-Window - '''./sc_trans sc_trans_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Transcoder====
----

Skip this if you experience no error reports when trying to run the Transcoder.

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.

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.

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.

===Source DSP===
----

====Install Source DSP====
----

Skip this if you are not setting up the Source DSP plug-in for MP3 streaming.

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]]).

====Configuring the Source DSP====
----

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:

::the Server (from [[#Server_Configuration_Setup|section 3.5.1]]) if you are going to use the plug-in as the only source
:and / or
::the Transcoder (from [[#Transcoder_Configuration_Setup|section 3.6.2]]) if it is to act as a DJ source

====Starting the Source DSP====
----

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.

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.

(*) The string <version> would be the actual version of the plug-in which is installed.

===Completion===
----

You should now be up and running with a working SHOUTcast system. Happy broadcasting!

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.

==Further Information==

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.

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

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:

:*Your SHOUTcast setup including all versions of the tools being used
:*The issue you are experiencing
:*The steps needed to reproduce the issue
:*Anything else useful especially if you have been tinkering with options before the issue appeared

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.

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.

===Related Documentation===
----

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.

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
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.

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

===Configuration Builder===
----

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'.

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.

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).

==Glossary==

'''Client''' - This is a program run which will connect to the Server e.g. Winamp.

'''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.

'''Server''' - This is the program which is run on a machine to provide to Clients the Stream.

'''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.
'''
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).

'''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.

'''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.

'''dsp_sc''' - This is the name the SHOUTcast Source DSP plug-in is otherwise known as.

'''sc_trans''' - This is the name the SHOUTcast Transcoder is otherwise known as.

'''sc_serv''' or '''sc_serv2''' - This is the name the SHOUTcast DNAS Server is otherwise known as.

SHOUTcast Getting Started Guide

2022-10-06T10:40:10Z

Djegg: /* Obtaining An Authhash */

{{Template:NavBarSC}}

==Introduction==

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.

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]].

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.

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.

===What is SHOUTcast?===
----

If you are new to SHOUTcast then this is probably something you may have already asked or you are trying to find out.

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.

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.

So a simple SHOUTcast setup would consist of the following:

Winamp + DSP ? DNAS [sc_serv] ? Winamp
(Source) (Server) (Client)

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]]).

===Windows Users===
----

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).

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.

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.

===Windows Vista / 7 Specifics===
----

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.

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.

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.

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.

'''(*)''' 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'.

==What is Required?==

To make your SHOUTcast system you will need the following software tools and hardware:

:*A computer running on a supported operating system ([[#Supported_Operating_Systems|see section 2.1]])
:*SHOUTcast DNAS Server
:*An input source (Transcoder or Winamp plus Source DSP plug-in)
:*Media or DJ's or a Capture device i.e. the content you want to provide to people

===Supported Operating Systems===
----

There are versions of the DNAS Server and Transcoder available on the following operating systems:

:*Windows 32-bit     Windows 2000, XP, Vista, Windows 7, 8, 10
:*Windows 64-bit     64-bit versions of Windows XP, Vista, Windows 7, 8, 10
:*Linux 32-bit
:*Linux 64-bit
:*BSD 8.x                 v2.4.7 only, not higher
:*Mac OS X (Intel)   Should work on 10.4.4 and up though is only tested against 10.5.5 (DNAS v2.4.7 only, not higher)

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.

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.

==Getting Installed==

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.

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.

===Download the Correct Version===
----

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.

Current versions of the SHOUTcast tools can be obtained from:

:*http://www.shoutcast.com/pricing
:*http://forums.winamp.com/showthread.php?t=324877 '''(*)'''

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).

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.

'''(*)''' 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.

===Choose an Install Location===
----

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.

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.

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]]).

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.

===Installation===
----

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.

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]].

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.

===Setting Up The Tools===
----

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.

Ensuring the Server is properly configured is the most important thing as unless it
is and running then none of the tools will be able to connect to it successfully.

===Server===
----

====Server Configuration Setup====
----

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.

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_serv_basic''' - shows how to get a more multi-stream setup working
::'''sc_serv_public''' - shows how to make a public server from sc_serv_basic
::'''sc_serv_relay''' - shows how to relay another source

There is more information about these example configurations in sc_serv2.txt - [[SHOUTcast_DNAS_Server_2#Example_Configurations|section 10]]

====Starting the Server====
----

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.

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:

::For Windows - '''sc_serv.exe sc_serv_simple.conf'''
::For non-Windows - '''./sc_serv sc_serv_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Server====
----

Skip this if you experience no error reports when trying to run the Server.

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.

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.

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.

====Obtaining An Authhash====
----

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 [[https://radiomanager.shoutcast.com/|Shoutcast RadioManager]]. See [[SHOUTcast_Authhash_Management|Shoutcast Authhash Management]] for further details.

===Transcoder===
----

====MP3 Streaming License====
----

Skip this if you are not setting up the Transcoder for MP3 streaming.

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]].

AAC encoding does not need you to purchase a license as one has
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]].

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:

unlockkeyname=Bob
unlockkeycode=123456

====Transcoder Configuration Setup====
----

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_trans_basic''' - shows how to get a basic setup without relying on the Server
::'''sc_trans_capture''' - shows how to use a capture device
::'''sc_trans_dj''' - shows how to setup a DJ connection
::'''sc_trans_playlist''' - shows how to use scheduled playlists

There is more information about these example configurations in [[SHOUTcast_DNAS_Transcoder_2#Example_Configurations|sc_trans.txt - section 11]]

====Starting the Transcoder====
----

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.

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:

::For Windows - '''sc_trans.exe sc_trans_simple.conf'''
::For non-Window - '''./sc_trans sc_trans_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Transcoder====
----

Skip this if you experience no error reports when trying to run the Transcoder.

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.

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.

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.

===Source DSP===
----

====Install Source DSP====
----

Skip this if you are not setting up the Source DSP plug-in for MP3 streaming.

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]]).

====Configuring the Source DSP====
----

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:

::the Server (from [[#Server_Configuration_Setup|section 3.5.1]]) if you are going to use the plug-in as the only source
:and / or
::the Transcoder (from [[#Transcoder_Configuration_Setup|section 3.6.2]]) if it is to act as a DJ source

====Starting the Source DSP====
----

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.

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.

(*) The string <version> would be the actual version of the plug-in which is installed.

===Completion===
----

You should now be up and running with a working SHOUTcast system. Happy broadcasting!

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.

==Further Information==

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.

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

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:

:*Your SHOUTcast setup including all versions of the tools being used
:*The issue you are experiencing
:*The steps needed to reproduce the issue
:*Anything else useful especially if you have been tinkering with options before the issue appeared

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.

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.

===Related Documentation===
----

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.

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
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.

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

===Configuration Builder===
----

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'.

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.

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).

==Glossary==

'''Client''' - This is a program run which will connect to the Server e.g. Winamp.

'''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.

'''Server''' - This is the program which is run on a machine to provide to Clients the Stream.

'''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.
'''
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).

'''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.

'''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.

'''dsp_sc''' - This is the name the SHOUTcast Source DSP plug-in is otherwise known as.

'''sc_trans''' - This is the name the SHOUTcast Transcoder is otherwise known as.

'''sc_serv''' or '''sc_serv2''' - This is the name the SHOUTcast DNAS Server is otherwise known as.

SHOUTcast Getting Started Guide

2022-10-06T10:39:20Z

Djegg: /* Obtaining An Authhash */

{{Template:NavBarSC}}

==Introduction==

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.

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]].

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.

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.

===What is SHOUTcast?===
----

If you are new to SHOUTcast then this is probably something you may have already asked or you are trying to find out.

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.

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.

So a simple SHOUTcast setup would consist of the following:

Winamp + DSP ? DNAS [sc_serv] ? Winamp
(Source) (Server) (Client)

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]]).

===Windows Users===
----

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).

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.

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.

===Windows Vista / 7 Specifics===
----

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.

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.

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.

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.

'''(*)''' 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'.

==What is Required?==

To make your SHOUTcast system you will need the following software tools and hardware:

:*A computer running on a supported operating system ([[#Supported_Operating_Systems|see section 2.1]])
:*SHOUTcast DNAS Server
:*An input source (Transcoder or Winamp plus Source DSP plug-in)
:*Media or DJ's or a Capture device i.e. the content you want to provide to people

===Supported Operating Systems===
----

There are versions of the DNAS Server and Transcoder available on the following operating systems:

:*Windows 32-bit     Windows 2000, XP, Vista, Windows 7, 8, 10
:*Windows 64-bit     64-bit versions of Windows XP, Vista, Windows 7, 8, 10
:*Linux 32-bit
:*Linux 64-bit
:*BSD 8.x                 v2.4.7 only, not higher
:*Mac OS X (Intel)   Should work on 10.4.4 and up though is only tested against 10.5.5 (DNAS v2.4.7 only, not higher)

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.

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.

==Getting Installed==

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.

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.

===Download the Correct Version===
----

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.

Current versions of the SHOUTcast tools can be obtained from:

:*http://www.shoutcast.com/pricing
:*http://forums.winamp.com/showthread.php?t=324877 '''(*)'''

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).

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.

'''(*)''' 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.

===Choose an Install Location===
----

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.

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.

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]]).

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.

===Installation===
----

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.

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]].

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.

===Setting Up The Tools===
----

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.

Ensuring the Server is properly configured is the most important thing as unless it
is and running then none of the tools will be able to connect to it successfully.

===Server===
----

====Server Configuration Setup====
----

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.

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_serv_basic''' - shows how to get a more multi-stream setup working
::'''sc_serv_public''' - shows how to make a public server from sc_serv_basic
::'''sc_serv_relay''' - shows how to relay another source

There is more information about these example configurations in sc_serv2.txt - [[SHOUTcast_DNAS_Server_2#Example_Configurations|section 10]]

====Starting the Server====
----

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.

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:

::For Windows - '''sc_serv.exe sc_serv_simple.conf'''
::For non-Windows - '''./sc_serv sc_serv_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Server====
----

Skip this if you experience no error reports when trying to run the Server.

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.

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.

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.

====Obtaining An Authhash====
----

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 [https://radiomanager.shoutcast.com/|Shoutcast RadioManager]. See [[SHOUTcast_Authhash_Management|Shoutcast Authhash Management]] for further details.

===Transcoder===
----

====MP3 Streaming License====
----

Skip this if you are not setting up the Transcoder for MP3 streaming.

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]].

AAC encoding does not need you to purchase a license as one has
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]].

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:

unlockkeyname=Bob
unlockkeycode=123456

====Transcoder Configuration Setup====
----

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.

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.

Additionally there are example configuration files for the following scenarios:

::'''sc_trans_basic''' - shows how to get a basic setup without relying on the Server
::'''sc_trans_capture''' - shows how to use a capture device
::'''sc_trans_dj''' - shows how to setup a DJ connection
::'''sc_trans_playlist''' - shows how to use scheduled playlists

There is more information about these example configurations in [[SHOUTcast_DNAS_Transcoder_2#Example_Configurations|sc_trans.txt - section 11]]

====Starting the Transcoder====
----

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.

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:

::For Windows - '''sc_trans.exe sc_trans_simple.conf'''
::For non-Window - '''./sc_trans sc_trans_simple.conf'''

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.

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:

::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)
::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)

====Errors Running the Transcoder====
----

Skip this if you experience no error reports when trying to run the Transcoder.

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.

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.

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.

===Source DSP===
----

====Install Source DSP====
----

Skip this if you are not setting up the Source DSP plug-in for MP3 streaming.

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]]).

====Configuring the Source DSP====
----

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:

::the Server (from [[#Server_Configuration_Setup|section 3.5.1]]) if you are going to use the plug-in as the only source
:and / or
::the Transcoder (from [[#Transcoder_Configuration_Setup|section 3.6.2]]) if it is to act as a DJ source

====Starting the Source DSP====
----

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.

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.

(*) The string <version> would be the actual version of the plug-in which is installed.

===Completion===
----

You should now be up and running with a working SHOUTcast system. Happy broadcasting!

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.

==Further Information==

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.

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

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:

:*Your SHOUTcast setup including all versions of the tools being used
:*The issue you are experiencing
:*The steps needed to reproduce the issue
:*Anything else useful especially if you have been tinkering with options before the issue appeared

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.

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.

===Related Documentation===
----

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.

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
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.

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

===Configuration Builder===
----

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'.

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.

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).

==Glossary==

'''Client''' - This is a program run which will connect to the Server e.g. Winamp.

'''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.

'''Server''' - This is the program which is run on a machine to provide to Clients the Stream.

'''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.
'''
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).

'''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.

'''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.

'''dsp_sc''' - This is the name the SHOUTcast Source DSP plug-in is otherwise known as.

'''sc_trans''' - This is the name the SHOUTcast Transcoder is otherwise known as.

'''sc_serv''' or '''sc_serv2''' - This is the name the SHOUTcast DNAS Server is otherwise known as.

SHOUTcast DNAS Transcoder 2

2022-10-06T10:36:09Z

Djegg: /* Registering for MP3 Stream Encoding */

{{Template:NavBarSC}}

==Introduction==

'''The Shoutcast Transcoder (sc_trans) is no longer maintained or supported.'''

'''This documentation remains here for legacy purposes only.'''

----

This document shows 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.

==Getting Started==

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).

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.

===Running The Transcoder===
----

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.

===Windows===
----

The Windows version of sc_trans is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_trans.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_trans will abort loading.

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.

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:

sc_trans.exe install sc_trans 0 0 sc_trans.conf

====Uninstall the Service====
----

sc_trans.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_trans.exe uninstall sc_trans

====Run as a Non-Service in the Console====
----

sc_trans.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_trans daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_trans will abort loading.

'''e.g.'''
./sc_trans daemon ./sc_trans.conf

When run this should output the following:

'sc_trans going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_trans <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile
SIGWINCH - Skips to next song in playlist
SIGUSR1 - Reload playlist
SIGUSR2 - Toggle playlist shuffle

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.

These signals are not supported by the Windows version of sc_trans which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

===Registering for MP3 Stream Encoding===
----

'''Note: This section is deprecated.'''

'''All mp3 encoding patents have expired and a licence is therefore no longer required.'''

----

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.

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:
[dead link removed]

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]]).

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:
unlockkeyname=Bob Cratchit
unlockkeycode=123456

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.

====Why Does AAC Encoding Not Require a License Key?====
----

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.

===Supported File Formats===
----

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:

MP3 + MPEG (treated as mp3)
WAV (uncompressed)
OGG
FLAC

==Configuration File==

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.

The entries stored in the configuration file are processed case insensitively.

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
any instances of a configuration option will assume it is for _1.

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:

encoder_1=aacp
encoder_2=mp3
bitrate_1=32000
bitrate_2=32000

Note that you CANNOT do it like this as it leads to not all values being set:

encoder_1=aacp
encoder_2=mp3
bitrate=32000

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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Administration===
----

'''adminport''' : Specify the port used to access the administrative control page ''[Default = 0]''
If no valid port is specified (i.e. zero) then this feature is disabled.

'''adminuser''' : Specify the username used to access the administrative control page ''[Default = admin]''

'''adminpassword''' : Specify the password to access the administrative control page ''[Default = goaway]''

===Calendar Events===
----

'''calendarfile''' : Specify the path to the xml based calendar file ''[Default = calendar.xml]''

'''calendarrewrite''' : Re-write the 'calendar file' on exit ''[Default = 1]''

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.

===DJ Support===
----

'''djport''' : Specify the port to listen on for DJ access using the SHOUTcast 1 protocol ''[Default = 0 (no listening)]''
This will actually open 'djport + 1' as the listening port.

'''djport2''' : Specify the port to listen on for DJ access using the SHOUTcast 2 protocol ''[Default = 0 (no listening)]''

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.

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) :
djport=900 ; i.e. will open port 901
djport2=901
Whereas this would work as we are opening two different ports (901 + 902):
djport=900
djport2=902

'''djcipher''' : Specify the key used to obfuscate the initial handshaking with the SHOUTcast 2 protocol ''[Default = foobar]''
This is a YP2 feature and it matches the 'uvoxcipherkey' value in
the sc_serv configuration file (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

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.

'''autodumpsourcetime''' : Specify the maximum idle time for the DJ in seconds before being disconnected ''[Default = 30]''

'''djbroadcasts''' : Specify the directory in which DJ broadcasts will be recorded into ''[Default = recorded\ or recorded/ - relative to sc_trans[.exe] ]''

'''djcapture''' : Enable to allow the recording of the DJ broadcast ''[Default = 1]''

'''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)]''
The date and time information are formatted using strftime().

''<MULTI>'' (one set for each DJ):

'''djlogin''' : Specify the username required for the DJ to get access [Default = dj]
When connecting as a SHOUTcast 1 source the password has to be specified as <djlogin>:<djpassword> '''e.g.''' dj:noise

'''djpassword''' : Specify the password required for the DJ to get access ''[Default = noise]''

'''djpriority''' : Specify the priority for the DJ when multiple DJ's are connected ''[Default = 1]''

===Encoder Options===
----

''<MULTI>'' (one set for each encoder):

'''encoder''' : Specify the encoder to use, either (mp3 or aacp) ''[Default = aacp]''

'''bitrate''' : Specify the encoding bitrate in bits per second ''[Default = 96000]''

'''samplerate''' : Specify the encoding sample rate to use ''[Default = 44100]''

'''channels''' : Specify the number of channels to encode ''[Default = 2]''

'''mp3quality''' : Specify the MP3 encoder quality to use when encoding ''[Default = 0]''
Available options are :
0 - fast (preferred)
1 - high quality (changes sample rate and does additional filtering)

'''mp3mode''' : Specify the MP3 encoder mode (CBR / VBR) to use when encoding ''[Default = 0]''
Available options are :
0 - CBR
1 - VBR High Quality
2 -
3 - VBR Medium Quality
4 -
5 - VBR Low Quality]

===Flash Security===
----

'''flashpolicyfile''' : Specify the name of file which contains the flash crossdomain policies ''[Default = crossdomain.xml]''

'''flashpolicyserverport''' : Specify the port used for the flash policy server ''[Default = 0]''
Specify '843' if you want to turn this on.

===Live Capture===
----

'''capture''' : Enable to allow the use of live capture as an input ''[Default = 0]''

'''capturedevice''' : Specify the OS dependent device used for capture ''[Default = <no value>]''

'''captureinput''' : Specify the OS dependent input used for capture ''[Default = <no value>]''

'''capturesamplerate''' : Specify the sample rate used for capture ''[Default = 44100]''

'''capturechannels''' : Specify the number of channels to capture ''[Default = 2]''

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.

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.

===Logging Options===
----

'''log''' : Enable logging of the transmission output ''[Default = 1]''

'''screenlog''' : Enable logging of output to the console ''[Default = 1]''
If log=0 or when running this as a daemon / service then this option is ignored as it is not applicable.

'''logfile''' : Specify a different logfile to save the transmission logs into ''[Default = %temp%\sc_trans.log or /tmp/sc_trans.log]''

If you are using a folder for saving the logs into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Metadata Control===
----

'''streamtitle''' : Specify the general name for the radio station or stream ''[Default - Misc]''

'''streamurl''' : Specify the url of the radio station or stream ''[Default = <nowiki>http://www.shoutcast.com</nowiki>]''

'''genre''' : Specify the genre for the radio station or stream ''[Default - N/A]''

'''aim''' : Specify the AIM contact ID to show for the radio station or stream ''[Default - N/A]''

'''irc''' : Specify the IRC contact ID to show for the radio station or stream ''[Default - N/A]''

'''icq''' : Specify the ICQ contact ID to show for the radio station or stream ''[Default - N/A]''

'''public''' : Enable to register the radio station or stream with the YP (shoutcast.com) ''[Default = 0]''
If connected to sc_serv then this is used by the 'publicserver' value
unless it is being overriden (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

'''usemetadata''' : Enable to use use the in file metadata i.e. stored in file tags ''[Default = 1]''

'''metadatapattern''' : Specify the pattern used for extracting metadata from the filename ''[Default = *\%N.* or */%N.*]''
See [[#Filename_Metadata_Extraction|section 6.0]] for more details about this)

'''displaymetadatapattern''' : Specify a pattern to use to form the metadata output string for SHOUTcast 1 metadata ''[Default = %R[ - ]%N]''

'''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]''
This is the maximum limit attempted to be reported and will vary based on the source in use
e.g. if there enough entries in the current playlist being played. Setting to zero will disable this.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on exit ''[Default = 0]''

'''timemultiplier''' : Used to shift reported time in certain uses ''[Default = 1]''

'''inheritconfig''': Specify the path of the sc_serv2 configuration file for the instance you want to use the transcoder with ''[Default = <no value>]''

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.

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:

* '''portbase -> serverport'''
* '''password -> password''' - Master source password overriden by streampassword
* '''streampassword -> password'''
* '''uvoxcipherkey -> djcipher'''
* '''srcip -> serverip''' - Will use the ip set unless is empty or srcip=any
* '''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

Additionally this mode will attempt to read configurations from a v1 DNAS file.

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

'''serverbackupfile''' : Set the server side file for broken connection playback ''[Default = <no value>]''

'''serverintrofile''' : Set the server side file that is played when a user connects ''[Default = <no value>]''

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).

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).

===MP3 Encoding===
----

'''unlockkeyname''' : Specify the name to use to unlock mp3 encoding (case sensitive)

'''unlockkeycode''' : Specify the code associated with name to unlock mp3 encoding

Due to licensing requirements for MP3 encoding see [[#Registering_for_MP3_Stream_Encoding|section 2.5]]
for how to obtain the key required for unlocking MP3 encoding in sc_trans.

===Network Options===
----

''<MULTI>'' (one set for each connection):

'''endpointname''' : Specify the name of the endpoint ''[Default - <no value>]''
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.

'''outprotocol''' : Specify the server protocol to use ''[Default = 1]''
This can be:
1 = SHOUTcast 1 (Legacy)
2 = Ultravox (Ultravox 2.0)
3 = SHOUTcast 2 (Ultravox 2.1)

'''serverip''' : Specify the IP address of server to connect to ''[Default - <no value>]''
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]]).

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.

'''serverport''' : Specify the server port used to connect to ''[Default = 8000]''
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]]).

'''password''' : Specify the password used to connect to a DNAS server ''[Default = foobar]''
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).

'''streamid''' : Specify the stream identifier for the SHOUTcast 2 connection ''[Default = 1]''
This relates to the 'streamid' value in the sc_serv configuration (see [[SHOUTcast_DNAS_Server_2#Networking|sc_serv2.txt - section 4.8]]).

'''uvoxuserid''' : Specify the user ID for accessing SHOUTcast 2 (Ultravox 2.1) ''[Default - <no value>]''
This is currently not used and is provided for future usage.

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.

'''uvoxradiometadata''' : Enable to send the older AOL Radio style metadata to the server ''[Default = 0]''

'''uvoxnewmetadata''' : Enable to send SHOUTcast 2 style metadata to the server ''[Default = 1]''

'''uvoxmetadatafudgefactor''' : Specify the delaying factor for Ultravox metadata in seconds ''[Default = 0.0]''

'''shoutcastmetadatafudgefactor''' : Specify the delaying factor for SHOUTcast metadata in seconds ''[Default = 0.0]''

===Playlist Control===
----

'''playlistfile''' : Specify the name of playlist file to use ''[Default = <no value>]''

'''shuffle''' : Enable to allow shuffling of the specified playlist ''[Default = 1]''

'''xfade''' : Specify the number of seconds to do for a crossfade ''[Default = 1]''
Specify xfade=0 to disable crossfade

'''xfadethreshold''' : Specify the minimum duration in seconds a file must be to allow crossfading in and out on it ''[Default = 10]''

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.

'''playlists''' : Specify the folder used for priority playlists ''[Default = priority\ or priority/ - relative to sc_trans[.exe]]''

'''archive''' : Specify the folder used for archiving playlists ''[Default = priority\archived\ or priority/archived/ - relative to sc_trans[.exe]]''

''<MULTI>'' (one set for each additional playlist):

'''playlistfilename''' - Used to build named collections of playlists ''[Default = <no value>]''

'''playlistfilepath''' - Used to build named collections of playlists ''[Default = <no value>]''

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.

===Replay Gain Control===
----

'''applyreplaygain''' : Enable to honour the replay gain values stored in the file ''[Default = 0]''

'''defaultreplaygain''' : If no replay gain is in the file then apply this adjustment ''[Default = 0.0]''

'''djreplaygain''' : Specify the replay gain to be applied to DJ streams ''[Default = 0.0]''

'''capturereplaygain''' : Specify the replay gain to apply to the live capture input ''[Default = 0.0]''

'''calculatereplaygain''' : Enable to calculate the replay gain on the handled files ''[Default = 0]''

'''replaygaintmpdir''' : Specify the temporary directory for replay gain calculator to work in ''[Default = (Windows = %TEMP FOLDER% Linux = /tmp/)]''

'''replaygainrunahead''' : Specify the number of tracks head start to give the replay gain calculator ''[Default = 2]''

'''replaygaindontwrite''' : Specify if the replay gain values calculated should NOT be written to the file ''[Default = 0]''

'''enhancereplaygain''' : Specify if the file has replay gain and it is being used, an additional amount of gain to add ''[Default = 6.0]''
Winamp ships with a default value to add -6dB to file which do not have replay gain.

===VU Image===
----

'''vuimagedirectory''' : Specify the folder in which to look for vu images to use ''[Default = ""]''
The image files are named vuimage_XX.<vuimagesuffix> where 'XX' is from 0 to 100
and the path specified will need to be properly terminated to work correctly.

'''vuimagesuffix''' : Specify the suffix for vu images to be used from the image directory ''[Default = png]''

'''vuimagemimetype''' : Specify the mime type for vu images to be used ''[Default = image/png]''

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.

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''shuffledebug''' : Enable to activate debug logging of playlist shuffling ''[Default = 0]''

'''shoutcastdebug''' : Enable to activate debug logging for SHOUTcast transmission ''[Default = 0]''

'''uvoxdebug''' : Enable to activate debug logging for SHOUTcast 2 (Ultravox 2.1) transmissions ''[Default = 0]''

'''gaindebug''' : Enable to activate debug logging for replay gain on playback ''[Default = 0]''

'''playlistdebug''' : Enable to activate debug logging for playlists ''[Default = 0]''

'''mp3encdebug''' : Enable to activate debug logging for MP3 encoding ''[Default = 0]''

'''mp3decdebug''' : Enable to activate debug logging for MP3 decoder ''[Default = 0]''

'''resamplerdebug''' : Enable to activate debug logging for the resampler ''[Default = 0]''

'''rgcalcdebug''' : Enable to activate debug logging for the replay gain calculator ''[Default = 0]''

'''apidebug''' : Enable to activate debug logging for the AJAX api ''[Default = 0]''

'''calendardebug''' : Enable to activate debug logging for the calendar events ''[Default = 0]''

'''capturedebug''' : Enable to activate debug logging for live capture ''[Default = 0]''

'''djdebug''' : Enable to activate debug logging for DJ management ''[Default = 0]''

'''flashpolicyserverdebug''' : Enable to activate debug logging for the flash policy server ''[Default = 0]''

'''fileconverterdebug''' : Enable to activate debug logging for the server side file converter ''[Default = 0]''

'''sourcerelaydebug''' : Enable to active debug logging for relayed sources ''[Default = 0]''

'''sourceandendpointmanagerdebug''' : Enable to activate debug logging for endpoint management ''[Default = 0]''

==Administration Weblet Commands==

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]]).

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]].

===Supported Weblet Commands===
----

The following are the supported commands for the administration weblet the transcoder supports and are used in the following manner:
<nowiki>http://<server_ip>:adminport/<command></nowiki>

'''quit''' : Will make sc_trans quit (equivalent of SIGKILL on non-Windows).

'''rotatelogs''' : Will rotate the logs (equivalent of SIGHUP).
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.

'''nextsong''' : Will advance to the next song (equivalent of SIGWINCH).

'''loadplaylist''' : This will re-load the current playlist (equivalent of SIGUSR1).

'''toggleshuffle''' : Use to toggle the current playlist shuffle state (equivalent of SIGUSR2).

'''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).

'''restart''' : Restart the current sc_trans instance.

'''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]]).

'''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:
0xa5 leftVal rightVal 0xa5 leftVal ..... etc

If the audio signal is mono there is no right val and you get:
0xa5 leftVal 0xa5 leftVal .... etc

'''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.

'''crossdomain.xml''' : This will return the current copy of crossdomain.xml as set with 'flashPolicyFile' ([[#Flash_Security|see section 3.5]]).

'''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).

'''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]].

==Metadata Support==

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.

===MP3 Files===
----

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:
# Unsynch data is not supported
# Compressed frames are not supported
# Encrypted frames are not supported
# Appended v4 frames are not supported

===FLAC and OGG Files===
----

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.

==Filename Metadata Extraction==

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.

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.

===Filename Metadata Extraction Pattern===
----

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'.

The default pattern used is *\%N.* (Windows) and */%N.* (all other OSes). The following are the formatting options which are supported in the pattern:
%N = Song name
%G = Genre
%A = Album
%R = Artist
%Y = Four digit year
%# = Sequence of digits
%% = % character
[] = Brackets optional elements (no nesting)
* = String
Other characters are matched exactly as found.

The pattern matching is done working from the right to the left.

===Filename Metadata Extraction Examples===
----

The following examples show the metadata pattern matching working.

====Example #1====
----

metadataPattern = */%R/%Y%A/Audio/[%#_]%N.*
filepath = /home/songs/Mask and Wig/1969 Irreverance Of Things Past/Audio/03_The Royal Blues.mp3

Extracted metadata result:
ALBUM = Irreverance Of Things Past
ARTIST = Mask and Wig
SONG = The Royal Blues
YEAR = 1969

====Example #2====
----

metadatapattern = */%A/[%R_]%N
filepath = /home/album/song

Extracted metadata result:
ALBUM = album
SONG = song

====6.2.3 Example #3====
----

metadatapattern = */%A/%R_%N
filepath = /home/album/artist_song

Extracted metadata result:
ALBUM = album
ARTIST = artist
SONG = song

===File Metadata Construction For SHOUTcast 1===
----

You can specify how metadata elements are concatenated together to from the SHOUTcast 1 metadata string by specifying the 'displaymetadatapattern' option.

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.

The following token substitutions are made with 'displaymetadatapattern':

%N = Song name
%A = Album name
%R = Artist
%G = Song genre
%Y = song year
%t = Station name (a.k.a. stream title a.k.a. icy-name)
%u = Station url (a.k.a. icy-url)
%g = Station genre (a.k.a. icy-genre)

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.

==Playlists Support==

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.

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.

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.

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.

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

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.

Additionally these entries can be intermixed with regular explicit entries '''e.g.'''
c:\music\foo.mp3
c:\music\otherstuff\*.mp3
c:\music\bar.mp3

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.

===Supported Playlist Formats===
----

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:

Plain text file - this is the equivalent of a commentless M3U / M3U8 file
PLS
M3U
M3U8 (UTF-8 encoded version of the M3U format)

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.

===Remote Applications===
----

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.'''
/music/foo.mp3
#!/bin/perl /home/user/songfromDB.pl
/music/bar.mp3

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.

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.

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.

Additionally you can pair remote application actions together in such a manner:
#!php call track script
#!php call commercial script

where this will alternate between the first and second scripts returning the file to be processed through sc_trans.

===Additional Information===
----

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.

There are a number of scenarios to be considered for remote application entries in a playlist as detailed in the following list:

# The standard out from the command is used as the name of the file to open.
# If the standard out is empty then the entry will be skipped.
# 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.
# 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.
# 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.
# If you return the requested number of additional tracks (passed in when it is run) then these will be used for "coming soon" calculations.
# 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.

==DJing Information==

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.

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).

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.

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.

===Setting Up DJs In The New Scheme===
----

DJ accounts are set up by using the 'djlogin', 'djpassword' and 'djpriority' options as shown in <MULTI> options under [[#DJ_Support|section 3.3]].

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):

djlogin_1=peter
djpassword_1=foobar
djpriority_1=4

djlogin_2=paul
djpassword_2=goaway
djpriority_2=2

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.

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.

<?xml version="1.0" encoding="UTF-8" ?>
<eventlist>
<event type="dj">
<dj archive="0">peter</dj>
<calendar/>
</event>
<event type="dj">
<dj archive="1">paul</dj>
<calendar starttime="02:00:00" duration="01:00:00" repeat="4"/>
</event>
</eventlist>

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.

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.

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Example Configurations==

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:

sc_trans_basic.conf
sc_trans_capture.conf
sc_trans_dj.conf
sc_trans_playlist.conf
sc_trans_simple.conf

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]]).

In all cases the examples are designed to work from the same install folder as sc_trans.

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.

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).

===sc_trans_basic===
----

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).

===sc_trans_capture===
----

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]]).

===sc_trans_dj===
----

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.

===sc_trans_playlist===
----

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.

===sc_trans_debug===
----

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.

===sc_trans_simple===
----

Use this if you just need to get a very basic transcoder running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

All you need to do when using this configuration file is to:

* Edit the playlist file to be used (as referenced in the playlistfile entry)
* 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)
* Change the stream information details as appropriate

SHOUTcast DNAS Transcoder 2

2022-10-06T10:33:02Z

Djegg: /* Introduction */

{{Template:NavBarSC}}

==Introduction==

'''The Shoutcast Transcoder (sc_trans) is no longer maintained or supported.'''

'''This documentation remains here for legacy purposes only.'''

----

This document shows 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.

==Getting Started==

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).

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.

===Running The Transcoder===
----

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.

===Windows===
----

The Windows version of sc_trans is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_trans.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_trans will abort loading.

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.

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:

sc_trans.exe install sc_trans 0 0 sc_trans.conf

====Uninstall the Service====
----

sc_trans.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_trans.exe uninstall sc_trans

====Run as a Non-Service in the Console====
----

sc_trans.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_trans daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_trans will abort loading.

'''e.g.'''
./sc_trans daemon ./sc_trans.conf

When run this should output the following:

'sc_trans going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_trans <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile
SIGWINCH - Skips to next song in playlist
SIGUSR1 - Reload playlist
SIGUSR2 - Toggle playlist shuffle

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.

These signals are not supported by the Windows version of sc_trans which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

===Registering for MP3 Stream Encoding===
----

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.

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:
http://shop.winamp.com/servlet/PromoServlet/promoID.48873700

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]]).

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:
unlockkeyname=Bob Cratchit
unlockkeycode=123456

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.

====Why Does AAC Encoding Not Require a License Key?====
----

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.

===Supported File Formats===
----

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:

MP3 + MPEG (treated as mp3)
WAV (uncompressed)
OGG
FLAC

==Configuration File==

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.

The entries stored in the configuration file are processed case insensitively.

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
any instances of a configuration option will assume it is for _1.

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:

encoder_1=aacp
encoder_2=mp3
bitrate_1=32000
bitrate_2=32000

Note that you CANNOT do it like this as it leads to not all values being set:

encoder_1=aacp
encoder_2=mp3
bitrate=32000

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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Administration===
----

'''adminport''' : Specify the port used to access the administrative control page ''[Default = 0]''
If no valid port is specified (i.e. zero) then this feature is disabled.

'''adminuser''' : Specify the username used to access the administrative control page ''[Default = admin]''

'''adminpassword''' : Specify the password to access the administrative control page ''[Default = goaway]''

===Calendar Events===
----

'''calendarfile''' : Specify the path to the xml based calendar file ''[Default = calendar.xml]''

'''calendarrewrite''' : Re-write the 'calendar file' on exit ''[Default = 1]''

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.

===DJ Support===
----

'''djport''' : Specify the port to listen on for DJ access using the SHOUTcast 1 protocol ''[Default = 0 (no listening)]''
This will actually open 'djport + 1' as the listening port.

'''djport2''' : Specify the port to listen on for DJ access using the SHOUTcast 2 protocol ''[Default = 0 (no listening)]''

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.

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) :
djport=900 ; i.e. will open port 901
djport2=901
Whereas this would work as we are opening two different ports (901 + 902):
djport=900
djport2=902

'''djcipher''' : Specify the key used to obfuscate the initial handshaking with the SHOUTcast 2 protocol ''[Default = foobar]''
This is a YP2 feature and it matches the 'uvoxcipherkey' value in
the sc_serv configuration file (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

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.

'''autodumpsourcetime''' : Specify the maximum idle time for the DJ in seconds before being disconnected ''[Default = 30]''

'''djbroadcasts''' : Specify the directory in which DJ broadcasts will be recorded into ''[Default = recorded\ or recorded/ - relative to sc_trans[.exe] ]''

'''djcapture''' : Enable to allow the recording of the DJ broadcast ''[Default = 1]''

'''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)]''
The date and time information are formatted using strftime().

''<MULTI>'' (one set for each DJ):

'''djlogin''' : Specify the username required for the DJ to get access [Default = dj]
When connecting as a SHOUTcast 1 source the password has to be specified as <djlogin>:<djpassword> '''e.g.''' dj:noise

'''djpassword''' : Specify the password required for the DJ to get access ''[Default = noise]''

'''djpriority''' : Specify the priority for the DJ when multiple DJ's are connected ''[Default = 1]''

===Encoder Options===
----

''<MULTI>'' (one set for each encoder):

'''encoder''' : Specify the encoder to use, either (mp3 or aacp) ''[Default = aacp]''

'''bitrate''' : Specify the encoding bitrate in bits per second ''[Default = 96000]''

'''samplerate''' : Specify the encoding sample rate to use ''[Default = 44100]''

'''channels''' : Specify the number of channels to encode ''[Default = 2]''

'''mp3quality''' : Specify the MP3 encoder quality to use when encoding ''[Default = 0]''
Available options are :
0 - fast (preferred)
1 - high quality (changes sample rate and does additional filtering)

'''mp3mode''' : Specify the MP3 encoder mode (CBR / VBR) to use when encoding ''[Default = 0]''
Available options are :
0 - CBR
1 - VBR High Quality
2 -
3 - VBR Medium Quality
4 -
5 - VBR Low Quality]

===Flash Security===
----

'''flashpolicyfile''' : Specify the name of file which contains the flash crossdomain policies ''[Default = crossdomain.xml]''

'''flashpolicyserverport''' : Specify the port used for the flash policy server ''[Default = 0]''
Specify '843' if you want to turn this on.

===Live Capture===
----

'''capture''' : Enable to allow the use of live capture as an input ''[Default = 0]''

'''capturedevice''' : Specify the OS dependent device used for capture ''[Default = <no value>]''

'''captureinput''' : Specify the OS dependent input used for capture ''[Default = <no value>]''

'''capturesamplerate''' : Specify the sample rate used for capture ''[Default = 44100]''

'''capturechannels''' : Specify the number of channels to capture ''[Default = 2]''

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.

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.

===Logging Options===
----

'''log''' : Enable logging of the transmission output ''[Default = 1]''

'''screenlog''' : Enable logging of output to the console ''[Default = 1]''
If log=0 or when running this as a daemon / service then this option is ignored as it is not applicable.

'''logfile''' : Specify a different logfile to save the transmission logs into ''[Default = %temp%\sc_trans.log or /tmp/sc_trans.log]''

If you are using a folder for saving the logs into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Metadata Control===
----

'''streamtitle''' : Specify the general name for the radio station or stream ''[Default - Misc]''

'''streamurl''' : Specify the url of the radio station or stream ''[Default = <nowiki>http://www.shoutcast.com</nowiki>]''

'''genre''' : Specify the genre for the radio station or stream ''[Default - N/A]''

'''aim''' : Specify the AIM contact ID to show for the radio station or stream ''[Default - N/A]''

'''irc''' : Specify the IRC contact ID to show for the radio station or stream ''[Default - N/A]''

'''icq''' : Specify the ICQ contact ID to show for the radio station or stream ''[Default - N/A]''

'''public''' : Enable to register the radio station or stream with the YP (shoutcast.com) ''[Default = 0]''
If connected to sc_serv then this is used by the 'publicserver' value
unless it is being overriden (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

'''usemetadata''' : Enable to use use the in file metadata i.e. stored in file tags ''[Default = 1]''

'''metadatapattern''' : Specify the pattern used for extracting metadata from the filename ''[Default = *\%N.* or */%N.*]''
See [[#Filename_Metadata_Extraction|section 6.0]] for more details about this)

'''displaymetadatapattern''' : Specify a pattern to use to form the metadata output string for SHOUTcast 1 metadata ''[Default = %R[ - ]%N]''

'''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]''
This is the maximum limit attempted to be reported and will vary based on the source in use
e.g. if there enough entries in the current playlist being played. Setting to zero will disable this.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on exit ''[Default = 0]''

'''timemultiplier''' : Used to shift reported time in certain uses ''[Default = 1]''

'''inheritconfig''': Specify the path of the sc_serv2 configuration file for the instance you want to use the transcoder with ''[Default = <no value>]''

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.

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:

* '''portbase -> serverport'''
* '''password -> password''' - Master source password overriden by streampassword
* '''streampassword -> password'''
* '''uvoxcipherkey -> djcipher'''
* '''srcip -> serverip''' - Will use the ip set unless is empty or srcip=any
* '''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

Additionally this mode will attempt to read configurations from a v1 DNAS file.

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

'''serverbackupfile''' : Set the server side file for broken connection playback ''[Default = <no value>]''

'''serverintrofile''' : Set the server side file that is played when a user connects ''[Default = <no value>]''

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).

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).

===MP3 Encoding===
----

'''unlockkeyname''' : Specify the name to use to unlock mp3 encoding (case sensitive)

'''unlockkeycode''' : Specify the code associated with name to unlock mp3 encoding

Due to licensing requirements for MP3 encoding see [[#Registering_for_MP3_Stream_Encoding|section 2.5]]
for how to obtain the key required for unlocking MP3 encoding in sc_trans.

===Network Options===
----

''<MULTI>'' (one set for each connection):

'''endpointname''' : Specify the name of the endpoint ''[Default - <no value>]''
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.

'''outprotocol''' : Specify the server protocol to use ''[Default = 1]''
This can be:
1 = SHOUTcast 1 (Legacy)
2 = Ultravox (Ultravox 2.0)
3 = SHOUTcast 2 (Ultravox 2.1)

'''serverip''' : Specify the IP address of server to connect to ''[Default - <no value>]''
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]]).

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.

'''serverport''' : Specify the server port used to connect to ''[Default = 8000]''
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]]).

'''password''' : Specify the password used to connect to a DNAS server ''[Default = foobar]''
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).

'''streamid''' : Specify the stream identifier for the SHOUTcast 2 connection ''[Default = 1]''
This relates to the 'streamid' value in the sc_serv configuration (see [[SHOUTcast_DNAS_Server_2#Networking|sc_serv2.txt - section 4.8]]).

'''uvoxuserid''' : Specify the user ID for accessing SHOUTcast 2 (Ultravox 2.1) ''[Default - <no value>]''
This is currently not used and is provided for future usage.

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.

'''uvoxradiometadata''' : Enable to send the older AOL Radio style metadata to the server ''[Default = 0]''

'''uvoxnewmetadata''' : Enable to send SHOUTcast 2 style metadata to the server ''[Default = 1]''

'''uvoxmetadatafudgefactor''' : Specify the delaying factor for Ultravox metadata in seconds ''[Default = 0.0]''

'''shoutcastmetadatafudgefactor''' : Specify the delaying factor for SHOUTcast metadata in seconds ''[Default = 0.0]''

===Playlist Control===
----

'''playlistfile''' : Specify the name of playlist file to use ''[Default = <no value>]''

'''shuffle''' : Enable to allow shuffling of the specified playlist ''[Default = 1]''

'''xfade''' : Specify the number of seconds to do for a crossfade ''[Default = 1]''
Specify xfade=0 to disable crossfade

'''xfadethreshold''' : Specify the minimum duration in seconds a file must be to allow crossfading in and out on it ''[Default = 10]''

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.

'''playlists''' : Specify the folder used for priority playlists ''[Default = priority\ or priority/ - relative to sc_trans[.exe]]''

'''archive''' : Specify the folder used for archiving playlists ''[Default = priority\archived\ or priority/archived/ - relative to sc_trans[.exe]]''

''<MULTI>'' (one set for each additional playlist):

'''playlistfilename''' - Used to build named collections of playlists ''[Default = <no value>]''

'''playlistfilepath''' - Used to build named collections of playlists ''[Default = <no value>]''

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.

===Replay Gain Control===
----

'''applyreplaygain''' : Enable to honour the replay gain values stored in the file ''[Default = 0]''

'''defaultreplaygain''' : If no replay gain is in the file then apply this adjustment ''[Default = 0.0]''

'''djreplaygain''' : Specify the replay gain to be applied to DJ streams ''[Default = 0.0]''

'''capturereplaygain''' : Specify the replay gain to apply to the live capture input ''[Default = 0.0]''

'''calculatereplaygain''' : Enable to calculate the replay gain on the handled files ''[Default = 0]''

'''replaygaintmpdir''' : Specify the temporary directory for replay gain calculator to work in ''[Default = (Windows = %TEMP FOLDER% Linux = /tmp/)]''

'''replaygainrunahead''' : Specify the number of tracks head start to give the replay gain calculator ''[Default = 2]''

'''replaygaindontwrite''' : Specify if the replay gain values calculated should NOT be written to the file ''[Default = 0]''

'''enhancereplaygain''' : Specify if the file has replay gain and it is being used, an additional amount of gain to add ''[Default = 6.0]''
Winamp ships with a default value to add -6dB to file which do not have replay gain.

===VU Image===
----

'''vuimagedirectory''' : Specify the folder in which to look for vu images to use ''[Default = ""]''
The image files are named vuimage_XX.<vuimagesuffix> where 'XX' is from 0 to 100
and the path specified will need to be properly terminated to work correctly.

'''vuimagesuffix''' : Specify the suffix for vu images to be used from the image directory ''[Default = png]''

'''vuimagemimetype''' : Specify the mime type for vu images to be used ''[Default = image/png]''

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.

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''shuffledebug''' : Enable to activate debug logging of playlist shuffling ''[Default = 0]''

'''shoutcastdebug''' : Enable to activate debug logging for SHOUTcast transmission ''[Default = 0]''

'''uvoxdebug''' : Enable to activate debug logging for SHOUTcast 2 (Ultravox 2.1) transmissions ''[Default = 0]''

'''gaindebug''' : Enable to activate debug logging for replay gain on playback ''[Default = 0]''

'''playlistdebug''' : Enable to activate debug logging for playlists ''[Default = 0]''

'''mp3encdebug''' : Enable to activate debug logging for MP3 encoding ''[Default = 0]''

'''mp3decdebug''' : Enable to activate debug logging for MP3 decoder ''[Default = 0]''

'''resamplerdebug''' : Enable to activate debug logging for the resampler ''[Default = 0]''

'''rgcalcdebug''' : Enable to activate debug logging for the replay gain calculator ''[Default = 0]''

'''apidebug''' : Enable to activate debug logging for the AJAX api ''[Default = 0]''

'''calendardebug''' : Enable to activate debug logging for the calendar events ''[Default = 0]''

'''capturedebug''' : Enable to activate debug logging for live capture ''[Default = 0]''

'''djdebug''' : Enable to activate debug logging for DJ management ''[Default = 0]''

'''flashpolicyserverdebug''' : Enable to activate debug logging for the flash policy server ''[Default = 0]''

'''fileconverterdebug''' : Enable to activate debug logging for the server side file converter ''[Default = 0]''

'''sourcerelaydebug''' : Enable to active debug logging for relayed sources ''[Default = 0]''

'''sourceandendpointmanagerdebug''' : Enable to activate debug logging for endpoint management ''[Default = 0]''

==Administration Weblet Commands==

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]]).

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]].

===Supported Weblet Commands===
----

The following are the supported commands for the administration weblet the transcoder supports and are used in the following manner:
<nowiki>http://<server_ip>:adminport/<command></nowiki>

'''quit''' : Will make sc_trans quit (equivalent of SIGKILL on non-Windows).

'''rotatelogs''' : Will rotate the logs (equivalent of SIGHUP).
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.

'''nextsong''' : Will advance to the next song (equivalent of SIGWINCH).

'''loadplaylist''' : This will re-load the current playlist (equivalent of SIGUSR1).

'''toggleshuffle''' : Use to toggle the current playlist shuffle state (equivalent of SIGUSR2).

'''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).

'''restart''' : Restart the current sc_trans instance.

'''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]]).

'''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:
0xa5 leftVal rightVal 0xa5 leftVal ..... etc

If the audio signal is mono there is no right val and you get:
0xa5 leftVal 0xa5 leftVal .... etc

'''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.

'''crossdomain.xml''' : This will return the current copy of crossdomain.xml as set with 'flashPolicyFile' ([[#Flash_Security|see section 3.5]]).

'''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).

'''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]].

==Metadata Support==

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.

===MP3 Files===
----

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:
# Unsynch data is not supported
# Compressed frames are not supported
# Encrypted frames are not supported
# Appended v4 frames are not supported

===FLAC and OGG Files===
----

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.

==Filename Metadata Extraction==

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.

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.

===Filename Metadata Extraction Pattern===
----

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'.

The default pattern used is *\%N.* (Windows) and */%N.* (all other OSes). The following are the formatting options which are supported in the pattern:
%N = Song name
%G = Genre
%A = Album
%R = Artist
%Y = Four digit year
%# = Sequence of digits
%% = % character
[] = Brackets optional elements (no nesting)
* = String
Other characters are matched exactly as found.

The pattern matching is done working from the right to the left.

===Filename Metadata Extraction Examples===
----

The following examples show the metadata pattern matching working.

====Example #1====
----

metadataPattern = */%R/%Y%A/Audio/[%#_]%N.*
filepath = /home/songs/Mask and Wig/1969 Irreverance Of Things Past/Audio/03_The Royal Blues.mp3

Extracted metadata result:
ALBUM = Irreverance Of Things Past
ARTIST = Mask and Wig
SONG = The Royal Blues
YEAR = 1969

====Example #2====
----

metadatapattern = */%A/[%R_]%N
filepath = /home/album/song

Extracted metadata result:
ALBUM = album
SONG = song

====6.2.3 Example #3====
----

metadatapattern = */%A/%R_%N
filepath = /home/album/artist_song

Extracted metadata result:
ALBUM = album
ARTIST = artist
SONG = song

===File Metadata Construction For SHOUTcast 1===
----

You can specify how metadata elements are concatenated together to from the SHOUTcast 1 metadata string by specifying the 'displaymetadatapattern' option.

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.

The following token substitutions are made with 'displaymetadatapattern':

%N = Song name
%A = Album name
%R = Artist
%G = Song genre
%Y = song year
%t = Station name (a.k.a. stream title a.k.a. icy-name)
%u = Station url (a.k.a. icy-url)
%g = Station genre (a.k.a. icy-genre)

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.

==Playlists Support==

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.

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.

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.

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.

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

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.

Additionally these entries can be intermixed with regular explicit entries '''e.g.'''
c:\music\foo.mp3
c:\music\otherstuff\*.mp3
c:\music\bar.mp3

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.

===Supported Playlist Formats===
----

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:

Plain text file - this is the equivalent of a commentless M3U / M3U8 file
PLS
M3U
M3U8 (UTF-8 encoded version of the M3U format)

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.

===Remote Applications===
----

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.'''
/music/foo.mp3
#!/bin/perl /home/user/songfromDB.pl
/music/bar.mp3

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.

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.

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.

Additionally you can pair remote application actions together in such a manner:
#!php call track script
#!php call commercial script

where this will alternate between the first and second scripts returning the file to be processed through sc_trans.

===Additional Information===
----

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.

There are a number of scenarios to be considered for remote application entries in a playlist as detailed in the following list:

# The standard out from the command is used as the name of the file to open.
# If the standard out is empty then the entry will be skipped.
# 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.
# 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.
# 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.
# If you return the requested number of additional tracks (passed in when it is run) then these will be used for "coming soon" calculations.
# 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.

==DJing Information==

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.

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).

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.

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.

===Setting Up DJs In The New Scheme===
----

DJ accounts are set up by using the 'djlogin', 'djpassword' and 'djpriority' options as shown in <MULTI> options under [[#DJ_Support|section 3.3]].

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):

djlogin_1=peter
djpassword_1=foobar
djpriority_1=4

djlogin_2=paul
djpassword_2=goaway
djpriority_2=2

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.

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.

<?xml version="1.0" encoding="UTF-8" ?>
<eventlist>
<event type="dj">
<dj archive="0">peter</dj>
<calendar/>
</event>
<event type="dj">
<dj archive="1">paul</dj>
<calendar starttime="02:00:00" duration="01:00:00" repeat="4"/>
</event>
</eventlist>

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.

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.

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Example Configurations==

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:

sc_trans_basic.conf
sc_trans_capture.conf
sc_trans_dj.conf
sc_trans_playlist.conf
sc_trans_simple.conf

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]]).

In all cases the examples are designed to work from the same install folder as sc_trans.

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.

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).

===sc_trans_basic===
----

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).

===sc_trans_capture===
----

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]]).

===sc_trans_dj===
----

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.

===sc_trans_playlist===
----

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.

===sc_trans_debug===
----

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.

===sc_trans_simple===
----

Use this if you just need to get a very basic transcoder running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

All you need to do when using this configuration file is to:

* Edit the playlist file to be used (as referenced in the playlistfile entry)
* 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)
* Change the stream information details as appropriate

SHOUTcast DNAS Transcoder 2

2022-10-06T10:32:50Z

Djegg: /* Introduction */

{{Template:NavBarSC}}

==Introduction==

'''The Shoutcast Transcoder (sc_trans) is no longer maintained or supported.'''

'''This documentation remains here for legacy purposes only.'''

----

This document shows 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.

==Getting Started==

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).

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.

===Running The Transcoder===
----

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.

===Windows===
----

The Windows version of sc_trans is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_trans.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_trans will abort loading.

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.

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:

sc_trans.exe install sc_trans 0 0 sc_trans.conf

====Uninstall the Service====
----

sc_trans.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_trans.exe uninstall sc_trans

====Run as a Non-Service in the Console====
----

sc_trans.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_trans daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_trans will abort loading.

'''e.g.'''
./sc_trans daemon ./sc_trans.conf

When run this should output the following:

'sc_trans going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_trans <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile
SIGWINCH - Skips to next song in playlist
SIGUSR1 - Reload playlist
SIGUSR2 - Toggle playlist shuffle

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.

These signals are not supported by the Windows version of sc_trans which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

===Registering for MP3 Stream Encoding===
----

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.

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:
http://shop.winamp.com/servlet/PromoServlet/promoID.48873700

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]]).

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:
unlockkeyname=Bob Cratchit
unlockkeycode=123456

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.

====Why Does AAC Encoding Not Require a License Key?====
----

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.

===Supported File Formats===
----

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:

MP3 + MPEG (treated as mp3)
WAV (uncompressed)
OGG
FLAC

==Configuration File==

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.

The entries stored in the configuration file are processed case insensitively.

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
any instances of a configuration option will assume it is for _1.

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:

encoder_1=aacp
encoder_2=mp3
bitrate_1=32000
bitrate_2=32000

Note that you CANNOT do it like this as it leads to not all values being set:

encoder_1=aacp
encoder_2=mp3
bitrate=32000

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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Administration===
----

'''adminport''' : Specify the port used to access the administrative control page ''[Default = 0]''
If no valid port is specified (i.e. zero) then this feature is disabled.

'''adminuser''' : Specify the username used to access the administrative control page ''[Default = admin]''

'''adminpassword''' : Specify the password to access the administrative control page ''[Default = goaway]''

===Calendar Events===
----

'''calendarfile''' : Specify the path to the xml based calendar file ''[Default = calendar.xml]''

'''calendarrewrite''' : Re-write the 'calendar file' on exit ''[Default = 1]''

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.

===DJ Support===
----

'''djport''' : Specify the port to listen on for DJ access using the SHOUTcast 1 protocol ''[Default = 0 (no listening)]''
This will actually open 'djport + 1' as the listening port.

'''djport2''' : Specify the port to listen on for DJ access using the SHOUTcast 2 protocol ''[Default = 0 (no listening)]''

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.

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) :
djport=900 ; i.e. will open port 901
djport2=901
Whereas this would work as we are opening two different ports (901 + 902):
djport=900
djport2=902

'''djcipher''' : Specify the key used to obfuscate the initial handshaking with the SHOUTcast 2 protocol ''[Default = foobar]''
This is a YP2 feature and it matches the 'uvoxcipherkey' value in
the sc_serv configuration file (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

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.

'''autodumpsourcetime''' : Specify the maximum idle time for the DJ in seconds before being disconnected ''[Default = 30]''

'''djbroadcasts''' : Specify the directory in which DJ broadcasts will be recorded into ''[Default = recorded\ or recorded/ - relative to sc_trans[.exe] ]''

'''djcapture''' : Enable to allow the recording of the DJ broadcast ''[Default = 1]''

'''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)]''
The date and time information are formatted using strftime().

''<MULTI>'' (one set for each DJ):

'''djlogin''' : Specify the username required for the DJ to get access [Default = dj]
When connecting as a SHOUTcast 1 source the password has to be specified as <djlogin>:<djpassword> '''e.g.''' dj:noise

'''djpassword''' : Specify the password required for the DJ to get access ''[Default = noise]''

'''djpriority''' : Specify the priority for the DJ when multiple DJ's are connected ''[Default = 1]''

===Encoder Options===
----

''<MULTI>'' (one set for each encoder):

'''encoder''' : Specify the encoder to use, either (mp3 or aacp) ''[Default = aacp]''

'''bitrate''' : Specify the encoding bitrate in bits per second ''[Default = 96000]''

'''samplerate''' : Specify the encoding sample rate to use ''[Default = 44100]''

'''channels''' : Specify the number of channels to encode ''[Default = 2]''

'''mp3quality''' : Specify the MP3 encoder quality to use when encoding ''[Default = 0]''
Available options are :
0 - fast (preferred)
1 - high quality (changes sample rate and does additional filtering)

'''mp3mode''' : Specify the MP3 encoder mode (CBR / VBR) to use when encoding ''[Default = 0]''
Available options are :
0 - CBR
1 - VBR High Quality
2 -
3 - VBR Medium Quality
4 -
5 - VBR Low Quality]

===Flash Security===
----

'''flashpolicyfile''' : Specify the name of file which contains the flash crossdomain policies ''[Default = crossdomain.xml]''

'''flashpolicyserverport''' : Specify the port used for the flash policy server ''[Default = 0]''
Specify '843' if you want to turn this on.

===Live Capture===
----

'''capture''' : Enable to allow the use of live capture as an input ''[Default = 0]''

'''capturedevice''' : Specify the OS dependent device used for capture ''[Default = <no value>]''

'''captureinput''' : Specify the OS dependent input used for capture ''[Default = <no value>]''

'''capturesamplerate''' : Specify the sample rate used for capture ''[Default = 44100]''

'''capturechannels''' : Specify the number of channels to capture ''[Default = 2]''

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.

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.

===Logging Options===
----

'''log''' : Enable logging of the transmission output ''[Default = 1]''

'''screenlog''' : Enable logging of output to the console ''[Default = 1]''
If log=0 or when running this as a daemon / service then this option is ignored as it is not applicable.

'''logfile''' : Specify a different logfile to save the transmission logs into ''[Default = %temp%\sc_trans.log or /tmp/sc_trans.log]''

If you are using a folder for saving the logs into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Metadata Control===
----

'''streamtitle''' : Specify the general name for the radio station or stream ''[Default - Misc]''

'''streamurl''' : Specify the url of the radio station or stream ''[Default = <nowiki>http://www.shoutcast.com</nowiki>]''

'''genre''' : Specify the genre for the radio station or stream ''[Default - N/A]''

'''aim''' : Specify the AIM contact ID to show for the radio station or stream ''[Default - N/A]''

'''irc''' : Specify the IRC contact ID to show for the radio station or stream ''[Default - N/A]''

'''icq''' : Specify the ICQ contact ID to show for the radio station or stream ''[Default - N/A]''

'''public''' : Enable to register the radio station or stream with the YP (shoutcast.com) ''[Default = 0]''
If connected to sc_serv then this is used by the 'publicserver' value
unless it is being overriden (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

'''usemetadata''' : Enable to use use the in file metadata i.e. stored in file tags ''[Default = 1]''

'''metadatapattern''' : Specify the pattern used for extracting metadata from the filename ''[Default = *\%N.* or */%N.*]''
See [[#Filename_Metadata_Extraction|section 6.0]] for more details about this)

'''displaymetadatapattern''' : Specify a pattern to use to form the metadata output string for SHOUTcast 1 metadata ''[Default = %R[ - ]%N]''

'''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]''
This is the maximum limit attempted to be reported and will vary based on the source in use
e.g. if there enough entries in the current playlist being played. Setting to zero will disable this.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on exit ''[Default = 0]''

'''timemultiplier''' : Used to shift reported time in certain uses ''[Default = 1]''

'''inheritconfig''': Specify the path of the sc_serv2 configuration file for the instance you want to use the transcoder with ''[Default = <no value>]''

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.

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:

* '''portbase -> serverport'''
* '''password -> password''' - Master source password overriden by streampassword
* '''streampassword -> password'''
* '''uvoxcipherkey -> djcipher'''
* '''srcip -> serverip''' - Will use the ip set unless is empty or srcip=any
* '''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

Additionally this mode will attempt to read configurations from a v1 DNAS file.

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

'''serverbackupfile''' : Set the server side file for broken connection playback ''[Default = <no value>]''

'''serverintrofile''' : Set the server side file that is played when a user connects ''[Default = <no value>]''

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).

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).

===MP3 Encoding===
----

'''unlockkeyname''' : Specify the name to use to unlock mp3 encoding (case sensitive)

'''unlockkeycode''' : Specify the code associated with name to unlock mp3 encoding

Due to licensing requirements for MP3 encoding see [[#Registering_for_MP3_Stream_Encoding|section 2.5]]
for how to obtain the key required for unlocking MP3 encoding in sc_trans.

===Network Options===
----

''<MULTI>'' (one set for each connection):

'''endpointname''' : Specify the name of the endpoint ''[Default - <no value>]''
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.

'''outprotocol''' : Specify the server protocol to use ''[Default = 1]''
This can be:
1 = SHOUTcast 1 (Legacy)
2 = Ultravox (Ultravox 2.0)
3 = SHOUTcast 2 (Ultravox 2.1)

'''serverip''' : Specify the IP address of server to connect to ''[Default - <no value>]''
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]]).

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.

'''serverport''' : Specify the server port used to connect to ''[Default = 8000]''
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]]).

'''password''' : Specify the password used to connect to a DNAS server ''[Default = foobar]''
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).

'''streamid''' : Specify the stream identifier for the SHOUTcast 2 connection ''[Default = 1]''
This relates to the 'streamid' value in the sc_serv configuration (see [[SHOUTcast_DNAS_Server_2#Networking|sc_serv2.txt - section 4.8]]).

'''uvoxuserid''' : Specify the user ID for accessing SHOUTcast 2 (Ultravox 2.1) ''[Default - <no value>]''
This is currently not used and is provided for future usage.

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.

'''uvoxradiometadata''' : Enable to send the older AOL Radio style metadata to the server ''[Default = 0]''

'''uvoxnewmetadata''' : Enable to send SHOUTcast 2 style metadata to the server ''[Default = 1]''

'''uvoxmetadatafudgefactor''' : Specify the delaying factor for Ultravox metadata in seconds ''[Default = 0.0]''

'''shoutcastmetadatafudgefactor''' : Specify the delaying factor for SHOUTcast metadata in seconds ''[Default = 0.0]''

===Playlist Control===
----

'''playlistfile''' : Specify the name of playlist file to use ''[Default = <no value>]''

'''shuffle''' : Enable to allow shuffling of the specified playlist ''[Default = 1]''

'''xfade''' : Specify the number of seconds to do for a crossfade ''[Default = 1]''
Specify xfade=0 to disable crossfade

'''xfadethreshold''' : Specify the minimum duration in seconds a file must be to allow crossfading in and out on it ''[Default = 10]''

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.

'''playlists''' : Specify the folder used for priority playlists ''[Default = priority\ or priority/ - relative to sc_trans[.exe]]''

'''archive''' : Specify the folder used for archiving playlists ''[Default = priority\archived\ or priority/archived/ - relative to sc_trans[.exe]]''

''<MULTI>'' (one set for each additional playlist):

'''playlistfilename''' - Used to build named collections of playlists ''[Default = <no value>]''

'''playlistfilepath''' - Used to build named collections of playlists ''[Default = <no value>]''

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.

===Replay Gain Control===
----

'''applyreplaygain''' : Enable to honour the replay gain values stored in the file ''[Default = 0]''

'''defaultreplaygain''' : If no replay gain is in the file then apply this adjustment ''[Default = 0.0]''

'''djreplaygain''' : Specify the replay gain to be applied to DJ streams ''[Default = 0.0]''

'''capturereplaygain''' : Specify the replay gain to apply to the live capture input ''[Default = 0.0]''

'''calculatereplaygain''' : Enable to calculate the replay gain on the handled files ''[Default = 0]''

'''replaygaintmpdir''' : Specify the temporary directory for replay gain calculator to work in ''[Default = (Windows = %TEMP FOLDER% Linux = /tmp/)]''

'''replaygainrunahead''' : Specify the number of tracks head start to give the replay gain calculator ''[Default = 2]''

'''replaygaindontwrite''' : Specify if the replay gain values calculated should NOT be written to the file ''[Default = 0]''

'''enhancereplaygain''' : Specify if the file has replay gain and it is being used, an additional amount of gain to add ''[Default = 6.0]''
Winamp ships with a default value to add -6dB to file which do not have replay gain.

===VU Image===
----

'''vuimagedirectory''' : Specify the folder in which to look for vu images to use ''[Default = ""]''
The image files are named vuimage_XX.<vuimagesuffix> where 'XX' is from 0 to 100
and the path specified will need to be properly terminated to work correctly.

'''vuimagesuffix''' : Specify the suffix for vu images to be used from the image directory ''[Default = png]''

'''vuimagemimetype''' : Specify the mime type for vu images to be used ''[Default = image/png]''

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.

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''shuffledebug''' : Enable to activate debug logging of playlist shuffling ''[Default = 0]''

'''shoutcastdebug''' : Enable to activate debug logging for SHOUTcast transmission ''[Default = 0]''

'''uvoxdebug''' : Enable to activate debug logging for SHOUTcast 2 (Ultravox 2.1) transmissions ''[Default = 0]''

'''gaindebug''' : Enable to activate debug logging for replay gain on playback ''[Default = 0]''

'''playlistdebug''' : Enable to activate debug logging for playlists ''[Default = 0]''

'''mp3encdebug''' : Enable to activate debug logging for MP3 encoding ''[Default = 0]''

'''mp3decdebug''' : Enable to activate debug logging for MP3 decoder ''[Default = 0]''

'''resamplerdebug''' : Enable to activate debug logging for the resampler ''[Default = 0]''

'''rgcalcdebug''' : Enable to activate debug logging for the replay gain calculator ''[Default = 0]''

'''apidebug''' : Enable to activate debug logging for the AJAX api ''[Default = 0]''

'''calendardebug''' : Enable to activate debug logging for the calendar events ''[Default = 0]''

'''capturedebug''' : Enable to activate debug logging for live capture ''[Default = 0]''

'''djdebug''' : Enable to activate debug logging for DJ management ''[Default = 0]''

'''flashpolicyserverdebug''' : Enable to activate debug logging for the flash policy server ''[Default = 0]''

'''fileconverterdebug''' : Enable to activate debug logging for the server side file converter ''[Default = 0]''

'''sourcerelaydebug''' : Enable to active debug logging for relayed sources ''[Default = 0]''

'''sourceandendpointmanagerdebug''' : Enable to activate debug logging for endpoint management ''[Default = 0]''

==Administration Weblet Commands==

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]]).

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]].

===Supported Weblet Commands===
----

The following are the supported commands for the administration weblet the transcoder supports and are used in the following manner:
<nowiki>http://<server_ip>:adminport/<command></nowiki>

'''quit''' : Will make sc_trans quit (equivalent of SIGKILL on non-Windows).

'''rotatelogs''' : Will rotate the logs (equivalent of SIGHUP).
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.

'''nextsong''' : Will advance to the next song (equivalent of SIGWINCH).

'''loadplaylist''' : This will re-load the current playlist (equivalent of SIGUSR1).

'''toggleshuffle''' : Use to toggle the current playlist shuffle state (equivalent of SIGUSR2).

'''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).

'''restart''' : Restart the current sc_trans instance.

'''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]]).

'''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:
0xa5 leftVal rightVal 0xa5 leftVal ..... etc

If the audio signal is mono there is no right val and you get:
0xa5 leftVal 0xa5 leftVal .... etc

'''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.

'''crossdomain.xml''' : This will return the current copy of crossdomain.xml as set with 'flashPolicyFile' ([[#Flash_Security|see section 3.5]]).

'''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).

'''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]].

==Metadata Support==

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.

===MP3 Files===
----

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:
# Unsynch data is not supported
# Compressed frames are not supported
# Encrypted frames are not supported
# Appended v4 frames are not supported

===FLAC and OGG Files===
----

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.

==Filename Metadata Extraction==

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.

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.

===Filename Metadata Extraction Pattern===
----

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'.

The default pattern used is *\%N.* (Windows) and */%N.* (all other OSes). The following are the formatting options which are supported in the pattern:
%N = Song name
%G = Genre
%A = Album
%R = Artist
%Y = Four digit year
%# = Sequence of digits
%% = % character
[] = Brackets optional elements (no nesting)
* = String
Other characters are matched exactly as found.

The pattern matching is done working from the right to the left.

===Filename Metadata Extraction Examples===
----

The following examples show the metadata pattern matching working.

====Example #1====
----

metadataPattern = */%R/%Y%A/Audio/[%#_]%N.*
filepath = /home/songs/Mask and Wig/1969 Irreverance Of Things Past/Audio/03_The Royal Blues.mp3

Extracted metadata result:
ALBUM = Irreverance Of Things Past
ARTIST = Mask and Wig
SONG = The Royal Blues
YEAR = 1969

====Example #2====
----

metadatapattern = */%A/[%R_]%N
filepath = /home/album/song

Extracted metadata result:
ALBUM = album
SONG = song

====6.2.3 Example #3====
----

metadatapattern = */%A/%R_%N
filepath = /home/album/artist_song

Extracted metadata result:
ALBUM = album
ARTIST = artist
SONG = song

===File Metadata Construction For SHOUTcast 1===
----

You can specify how metadata elements are concatenated together to from the SHOUTcast 1 metadata string by specifying the 'displaymetadatapattern' option.

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.

The following token substitutions are made with 'displaymetadatapattern':

%N = Song name
%A = Album name
%R = Artist
%G = Song genre
%Y = song year
%t = Station name (a.k.a. stream title a.k.a. icy-name)
%u = Station url (a.k.a. icy-url)
%g = Station genre (a.k.a. icy-genre)

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.

==Playlists Support==

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.

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.

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.

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.

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

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.

Additionally these entries can be intermixed with regular explicit entries '''e.g.'''
c:\music\foo.mp3
c:\music\otherstuff\*.mp3
c:\music\bar.mp3

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.

===Supported Playlist Formats===
----

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:

Plain text file - this is the equivalent of a commentless M3U / M3U8 file
PLS
M3U
M3U8 (UTF-8 encoded version of the M3U format)

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.

===Remote Applications===
----

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.'''
/music/foo.mp3
#!/bin/perl /home/user/songfromDB.pl
/music/bar.mp3

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.

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.

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.

Additionally you can pair remote application actions together in such a manner:
#!php call track script
#!php call commercial script

where this will alternate between the first and second scripts returning the file to be processed through sc_trans.

===Additional Information===
----

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.

There are a number of scenarios to be considered for remote application entries in a playlist as detailed in the following list:

# The standard out from the command is used as the name of the file to open.
# If the standard out is empty then the entry will be skipped.
# 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.
# 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.
# 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.
# If you return the requested number of additional tracks (passed in when it is run) then these will be used for "coming soon" calculations.
# 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.

==DJing Information==

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.

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).

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.

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.

===Setting Up DJs In The New Scheme===
----

DJ accounts are set up by using the 'djlogin', 'djpassword' and 'djpriority' options as shown in <MULTI> options under [[#DJ_Support|section 3.3]].

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):

djlogin_1=peter
djpassword_1=foobar
djpriority_1=4

djlogin_2=paul
djpassword_2=goaway
djpriority_2=2

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.

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.

<?xml version="1.0" encoding="UTF-8" ?>
<eventlist>
<event type="dj">
<dj archive="0">peter</dj>
<calendar/>
</event>
<event type="dj">
<dj archive="1">paul</dj>
<calendar starttime="02:00:00" duration="01:00:00" repeat="4"/>
</event>
</eventlist>

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.

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.

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Example Configurations==

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:

sc_trans_basic.conf
sc_trans_capture.conf
sc_trans_dj.conf
sc_trans_playlist.conf
sc_trans_simple.conf

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]]).

In all cases the examples are designed to work from the same install folder as sc_trans.

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.

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).

===sc_trans_basic===
----

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).

===sc_trans_capture===
----

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]]).

===sc_trans_dj===
----

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.

===sc_trans_playlist===
----

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.

===sc_trans_debug===
----

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.

===sc_trans_simple===
----

Use this if you just need to get a very basic transcoder running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

All you need to do when using this configuration file is to:

* Edit the playlist file to be used (as referenced in the playlistfile entry)
* 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)
* Change the stream information details as appropriate

SHOUTcast DNAS Transcoder 2

2022-10-06T10:32:30Z

Djegg: /* Introduction */

{{Template:NavBarSC}}

==Introduction==

'''The Shoutcast Transcoder (sc_trans) is no longer maintained or supported.'''

'''This documentation remains here for legacy purposes only.'''

----

This document shows 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.

==Getting Started==

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).

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.

===Running The Transcoder===
----

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.

===Windows===
----

The Windows version of sc_trans is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_trans.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_trans will abort loading.

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.

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:

sc_trans.exe install sc_trans 0 0 sc_trans.conf

====Uninstall the Service====
----

sc_trans.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_trans.exe uninstall sc_trans

====Run as a Non-Service in the Console====
----

sc_trans.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_trans daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_trans will abort loading.

'''e.g.'''
./sc_trans daemon ./sc_trans.conf

When run this should output the following:

'sc_trans going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_trans <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile
SIGWINCH - Skips to next song in playlist
SIGUSR1 - Reload playlist
SIGUSR2 - Toggle playlist shuffle

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.

These signals are not supported by the Windows version of sc_trans which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

===Registering for MP3 Stream Encoding===
----

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.

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:
http://shop.winamp.com/servlet/PromoServlet/promoID.48873700

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]]).

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:
unlockkeyname=Bob Cratchit
unlockkeycode=123456

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.

====Why Does AAC Encoding Not Require a License Key?====
----

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.

===Supported File Formats===
----

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:

MP3 + MPEG (treated as mp3)
WAV (uncompressed)
OGG
FLAC

==Configuration File==

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.

The entries stored in the configuration file are processed case insensitively.

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
any instances of a configuration option will assume it is for _1.

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:

encoder_1=aacp
encoder_2=mp3
bitrate_1=32000
bitrate_2=32000

Note that you CANNOT do it like this as it leads to not all values being set:

encoder_1=aacp
encoder_2=mp3
bitrate=32000

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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Administration===
----

'''adminport''' : Specify the port used to access the administrative control page ''[Default = 0]''
If no valid port is specified (i.e. zero) then this feature is disabled.

'''adminuser''' : Specify the username used to access the administrative control page ''[Default = admin]''

'''adminpassword''' : Specify the password to access the administrative control page ''[Default = goaway]''

===Calendar Events===
----

'''calendarfile''' : Specify the path to the xml based calendar file ''[Default = calendar.xml]''

'''calendarrewrite''' : Re-write the 'calendar file' on exit ''[Default = 1]''

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.

===DJ Support===
----

'''djport''' : Specify the port to listen on for DJ access using the SHOUTcast 1 protocol ''[Default = 0 (no listening)]''
This will actually open 'djport + 1' as the listening port.

'''djport2''' : Specify the port to listen on for DJ access using the SHOUTcast 2 protocol ''[Default = 0 (no listening)]''

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.

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) :
djport=900 ; i.e. will open port 901
djport2=901
Whereas this would work as we are opening two different ports (901 + 902):
djport=900
djport2=902

'''djcipher''' : Specify the key used to obfuscate the initial handshaking with the SHOUTcast 2 protocol ''[Default = foobar]''
This is a YP2 feature and it matches the 'uvoxcipherkey' value in
the sc_serv configuration file (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

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.

'''autodumpsourcetime''' : Specify the maximum idle time for the DJ in seconds before being disconnected ''[Default = 30]''

'''djbroadcasts''' : Specify the directory in which DJ broadcasts will be recorded into ''[Default = recorded\ or recorded/ - relative to sc_trans[.exe] ]''

'''djcapture''' : Enable to allow the recording of the DJ broadcast ''[Default = 1]''

'''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)]''
The date and time information are formatted using strftime().

''<MULTI>'' (one set for each DJ):

'''djlogin''' : Specify the username required for the DJ to get access [Default = dj]
When connecting as a SHOUTcast 1 source the password has to be specified as <djlogin>:<djpassword> '''e.g.''' dj:noise

'''djpassword''' : Specify the password required for the DJ to get access ''[Default = noise]''

'''djpriority''' : Specify the priority for the DJ when multiple DJ's are connected ''[Default = 1]''

===Encoder Options===
----

''<MULTI>'' (one set for each encoder):

'''encoder''' : Specify the encoder to use, either (mp3 or aacp) ''[Default = aacp]''

'''bitrate''' : Specify the encoding bitrate in bits per second ''[Default = 96000]''

'''samplerate''' : Specify the encoding sample rate to use ''[Default = 44100]''

'''channels''' : Specify the number of channels to encode ''[Default = 2]''

'''mp3quality''' : Specify the MP3 encoder quality to use when encoding ''[Default = 0]''
Available options are :
0 - fast (preferred)
1 - high quality (changes sample rate and does additional filtering)

'''mp3mode''' : Specify the MP3 encoder mode (CBR / VBR) to use when encoding ''[Default = 0]''
Available options are :
0 - CBR
1 - VBR High Quality
2 -
3 - VBR Medium Quality
4 -
5 - VBR Low Quality]

===Flash Security===
----

'''flashpolicyfile''' : Specify the name of file which contains the flash crossdomain policies ''[Default = crossdomain.xml]''

'''flashpolicyserverport''' : Specify the port used for the flash policy server ''[Default = 0]''
Specify '843' if you want to turn this on.

===Live Capture===
----

'''capture''' : Enable to allow the use of live capture as an input ''[Default = 0]''

'''capturedevice''' : Specify the OS dependent device used for capture ''[Default = <no value>]''

'''captureinput''' : Specify the OS dependent input used for capture ''[Default = <no value>]''

'''capturesamplerate''' : Specify the sample rate used for capture ''[Default = 44100]''

'''capturechannels''' : Specify the number of channels to capture ''[Default = 2]''

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.

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.

===Logging Options===
----

'''log''' : Enable logging of the transmission output ''[Default = 1]''

'''screenlog''' : Enable logging of output to the console ''[Default = 1]''
If log=0 or when running this as a daemon / service then this option is ignored as it is not applicable.

'''logfile''' : Specify a different logfile to save the transmission logs into ''[Default = %temp%\sc_trans.log or /tmp/sc_trans.log]''

If you are using a folder for saving the logs into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Metadata Control===
----

'''streamtitle''' : Specify the general name for the radio station or stream ''[Default - Misc]''

'''streamurl''' : Specify the url of the radio station or stream ''[Default = <nowiki>http://www.shoutcast.com</nowiki>]''

'''genre''' : Specify the genre for the radio station or stream ''[Default - N/A]''

'''aim''' : Specify the AIM contact ID to show for the radio station or stream ''[Default - N/A]''

'''irc''' : Specify the IRC contact ID to show for the radio station or stream ''[Default - N/A]''

'''icq''' : Specify the ICQ contact ID to show for the radio station or stream ''[Default - N/A]''

'''public''' : Enable to register the radio station or stream with the YP (shoutcast.com) ''[Default = 0]''
If connected to sc_serv then this is used by the 'publicserver' value
unless it is being overriden (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

'''usemetadata''' : Enable to use use the in file metadata i.e. stored in file tags ''[Default = 1]''

'''metadatapattern''' : Specify the pattern used for extracting metadata from the filename ''[Default = *\%N.* or */%N.*]''
See [[#Filename_Metadata_Extraction|section 6.0]] for more details about this)

'''displaymetadatapattern''' : Specify a pattern to use to form the metadata output string for SHOUTcast 1 metadata ''[Default = %R[ - ]%N]''

'''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]''
This is the maximum limit attempted to be reported and will vary based on the source in use
e.g. if there enough entries in the current playlist being played. Setting to zero will disable this.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on exit ''[Default = 0]''

'''timemultiplier''' : Used to shift reported time in certain uses ''[Default = 1]''

'''inheritconfig''': Specify the path of the sc_serv2 configuration file for the instance you want to use the transcoder with ''[Default = <no value>]''

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.

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:

* '''portbase -> serverport'''
* '''password -> password''' - Master source password overriden by streampassword
* '''streampassword -> password'''
* '''uvoxcipherkey -> djcipher'''
* '''srcip -> serverip''' - Will use the ip set unless is empty or srcip=any
* '''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

Additionally this mode will attempt to read configurations from a v1 DNAS file.

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

'''serverbackupfile''' : Set the server side file for broken connection playback ''[Default = <no value>]''

'''serverintrofile''' : Set the server side file that is played when a user connects ''[Default = <no value>]''

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).

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).

===MP3 Encoding===
----

'''unlockkeyname''' : Specify the name to use to unlock mp3 encoding (case sensitive)

'''unlockkeycode''' : Specify the code associated with name to unlock mp3 encoding

Due to licensing requirements for MP3 encoding see [[#Registering_for_MP3_Stream_Encoding|section 2.5]]
for how to obtain the key required for unlocking MP3 encoding in sc_trans.

===Network Options===
----

''<MULTI>'' (one set for each connection):

'''endpointname''' : Specify the name of the endpoint ''[Default - <no value>]''
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.

'''outprotocol''' : Specify the server protocol to use ''[Default = 1]''
This can be:
1 = SHOUTcast 1 (Legacy)
2 = Ultravox (Ultravox 2.0)
3 = SHOUTcast 2 (Ultravox 2.1)

'''serverip''' : Specify the IP address of server to connect to ''[Default - <no value>]''
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]]).

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.

'''serverport''' : Specify the server port used to connect to ''[Default = 8000]''
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]]).

'''password''' : Specify the password used to connect to a DNAS server ''[Default = foobar]''
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).

'''streamid''' : Specify the stream identifier for the SHOUTcast 2 connection ''[Default = 1]''
This relates to the 'streamid' value in the sc_serv configuration (see [[SHOUTcast_DNAS_Server_2#Networking|sc_serv2.txt - section 4.8]]).

'''uvoxuserid''' : Specify the user ID for accessing SHOUTcast 2 (Ultravox 2.1) ''[Default - <no value>]''
This is currently not used and is provided for future usage.

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.

'''uvoxradiometadata''' : Enable to send the older AOL Radio style metadata to the server ''[Default = 0]''

'''uvoxnewmetadata''' : Enable to send SHOUTcast 2 style metadata to the server ''[Default = 1]''

'''uvoxmetadatafudgefactor''' : Specify the delaying factor for Ultravox metadata in seconds ''[Default = 0.0]''

'''shoutcastmetadatafudgefactor''' : Specify the delaying factor for SHOUTcast metadata in seconds ''[Default = 0.0]''

===Playlist Control===
----

'''playlistfile''' : Specify the name of playlist file to use ''[Default = <no value>]''

'''shuffle''' : Enable to allow shuffling of the specified playlist ''[Default = 1]''

'''xfade''' : Specify the number of seconds to do for a crossfade ''[Default = 1]''
Specify xfade=0 to disable crossfade

'''xfadethreshold''' : Specify the minimum duration in seconds a file must be to allow crossfading in and out on it ''[Default = 10]''

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.

'''playlists''' : Specify the folder used for priority playlists ''[Default = priority\ or priority/ - relative to sc_trans[.exe]]''

'''archive''' : Specify the folder used for archiving playlists ''[Default = priority\archived\ or priority/archived/ - relative to sc_trans[.exe]]''

''<MULTI>'' (one set for each additional playlist):

'''playlistfilename''' - Used to build named collections of playlists ''[Default = <no value>]''

'''playlistfilepath''' - Used to build named collections of playlists ''[Default = <no value>]''

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.

===Replay Gain Control===
----

'''applyreplaygain''' : Enable to honour the replay gain values stored in the file ''[Default = 0]''

'''defaultreplaygain''' : If no replay gain is in the file then apply this adjustment ''[Default = 0.0]''

'''djreplaygain''' : Specify the replay gain to be applied to DJ streams ''[Default = 0.0]''

'''capturereplaygain''' : Specify the replay gain to apply to the live capture input ''[Default = 0.0]''

'''calculatereplaygain''' : Enable to calculate the replay gain on the handled files ''[Default = 0]''

'''replaygaintmpdir''' : Specify the temporary directory for replay gain calculator to work in ''[Default = (Windows = %TEMP FOLDER% Linux = /tmp/)]''

'''replaygainrunahead''' : Specify the number of tracks head start to give the replay gain calculator ''[Default = 2]''

'''replaygaindontwrite''' : Specify if the replay gain values calculated should NOT be written to the file ''[Default = 0]''

'''enhancereplaygain''' : Specify if the file has replay gain and it is being used, an additional amount of gain to add ''[Default = 6.0]''
Winamp ships with a default value to add -6dB to file which do not have replay gain.

===VU Image===
----

'''vuimagedirectory''' : Specify the folder in which to look for vu images to use ''[Default = ""]''
The image files are named vuimage_XX.<vuimagesuffix> where 'XX' is from 0 to 100
and the path specified will need to be properly terminated to work correctly.

'''vuimagesuffix''' : Specify the suffix for vu images to be used from the image directory ''[Default = png]''

'''vuimagemimetype''' : Specify the mime type for vu images to be used ''[Default = image/png]''

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.

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''shuffledebug''' : Enable to activate debug logging of playlist shuffling ''[Default = 0]''

'''shoutcastdebug''' : Enable to activate debug logging for SHOUTcast transmission ''[Default = 0]''

'''uvoxdebug''' : Enable to activate debug logging for SHOUTcast 2 (Ultravox 2.1) transmissions ''[Default = 0]''

'''gaindebug''' : Enable to activate debug logging for replay gain on playback ''[Default = 0]''

'''playlistdebug''' : Enable to activate debug logging for playlists ''[Default = 0]''

'''mp3encdebug''' : Enable to activate debug logging for MP3 encoding ''[Default = 0]''

'''mp3decdebug''' : Enable to activate debug logging for MP3 decoder ''[Default = 0]''

'''resamplerdebug''' : Enable to activate debug logging for the resampler ''[Default = 0]''

'''rgcalcdebug''' : Enable to activate debug logging for the replay gain calculator ''[Default = 0]''

'''apidebug''' : Enable to activate debug logging for the AJAX api ''[Default = 0]''

'''calendardebug''' : Enable to activate debug logging for the calendar events ''[Default = 0]''

'''capturedebug''' : Enable to activate debug logging for live capture ''[Default = 0]''

'''djdebug''' : Enable to activate debug logging for DJ management ''[Default = 0]''

'''flashpolicyserverdebug''' : Enable to activate debug logging for the flash policy server ''[Default = 0]''

'''fileconverterdebug''' : Enable to activate debug logging for the server side file converter ''[Default = 0]''

'''sourcerelaydebug''' : Enable to active debug logging for relayed sources ''[Default = 0]''

'''sourceandendpointmanagerdebug''' : Enable to activate debug logging for endpoint management ''[Default = 0]''

==Administration Weblet Commands==

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]]).

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]].

===Supported Weblet Commands===
----

The following are the supported commands for the administration weblet the transcoder supports and are used in the following manner:
<nowiki>http://<server_ip>:adminport/<command></nowiki>

'''quit''' : Will make sc_trans quit (equivalent of SIGKILL on non-Windows).

'''rotatelogs''' : Will rotate the logs (equivalent of SIGHUP).
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.

'''nextsong''' : Will advance to the next song (equivalent of SIGWINCH).

'''loadplaylist''' : This will re-load the current playlist (equivalent of SIGUSR1).

'''toggleshuffle''' : Use to toggle the current playlist shuffle state (equivalent of SIGUSR2).

'''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).

'''restart''' : Restart the current sc_trans instance.

'''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]]).

'''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:
0xa5 leftVal rightVal 0xa5 leftVal ..... etc

If the audio signal is mono there is no right val and you get:
0xa5 leftVal 0xa5 leftVal .... etc

'''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.

'''crossdomain.xml''' : This will return the current copy of crossdomain.xml as set with 'flashPolicyFile' ([[#Flash_Security|see section 3.5]]).

'''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).

'''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]].

==Metadata Support==

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.

===MP3 Files===
----

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:
# Unsynch data is not supported
# Compressed frames are not supported
# Encrypted frames are not supported
# Appended v4 frames are not supported

===FLAC and OGG Files===
----

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.

==Filename Metadata Extraction==

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.

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.

===Filename Metadata Extraction Pattern===
----

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'.

The default pattern used is *\%N.* (Windows) and */%N.* (all other OSes). The following are the formatting options which are supported in the pattern:
%N = Song name
%G = Genre
%A = Album
%R = Artist
%Y = Four digit year
%# = Sequence of digits
%% = % character
[] = Brackets optional elements (no nesting)
* = String
Other characters are matched exactly as found.

The pattern matching is done working from the right to the left.

===Filename Metadata Extraction Examples===
----

The following examples show the metadata pattern matching working.

====Example #1====
----

metadataPattern = */%R/%Y%A/Audio/[%#_]%N.*
filepath = /home/songs/Mask and Wig/1969 Irreverance Of Things Past/Audio/03_The Royal Blues.mp3

Extracted metadata result:
ALBUM = Irreverance Of Things Past
ARTIST = Mask and Wig
SONG = The Royal Blues
YEAR = 1969

====Example #2====
----

metadatapattern = */%A/[%R_]%N
filepath = /home/album/song

Extracted metadata result:
ALBUM = album
SONG = song

====6.2.3 Example #3====
----

metadatapattern = */%A/%R_%N
filepath = /home/album/artist_song

Extracted metadata result:
ALBUM = album
ARTIST = artist
SONG = song

===File Metadata Construction For SHOUTcast 1===
----

You can specify how metadata elements are concatenated together to from the SHOUTcast 1 metadata string by specifying the 'displaymetadatapattern' option.

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.

The following token substitutions are made with 'displaymetadatapattern':

%N = Song name
%A = Album name
%R = Artist
%G = Song genre
%Y = song year
%t = Station name (a.k.a. stream title a.k.a. icy-name)
%u = Station url (a.k.a. icy-url)
%g = Station genre (a.k.a. icy-genre)

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.

==Playlists Support==

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.

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.

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.

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.

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

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.

Additionally these entries can be intermixed with regular explicit entries '''e.g.'''
c:\music\foo.mp3
c:\music\otherstuff\*.mp3
c:\music\bar.mp3

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.

===Supported Playlist Formats===
----

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:

Plain text file - this is the equivalent of a commentless M3U / M3U8 file
PLS
M3U
M3U8 (UTF-8 encoded version of the M3U format)

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.

===Remote Applications===
----

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.'''
/music/foo.mp3
#!/bin/perl /home/user/songfromDB.pl
/music/bar.mp3

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.

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.

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.

Additionally you can pair remote application actions together in such a manner:
#!php call track script
#!php call commercial script

where this will alternate between the first and second scripts returning the file to be processed through sc_trans.

===Additional Information===
----

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.

There are a number of scenarios to be considered for remote application entries in a playlist as detailed in the following list:

# The standard out from the command is used as the name of the file to open.
# If the standard out is empty then the entry will be skipped.
# 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.
# 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.
# 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.
# If you return the requested number of additional tracks (passed in when it is run) then these will be used for "coming soon" calculations.
# 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.

==DJing Information==

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.

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).

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.

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.

===Setting Up DJs In The New Scheme===
----

DJ accounts are set up by using the 'djlogin', 'djpassword' and 'djpriority' options as shown in <MULTI> options under [[#DJ_Support|section 3.3]].

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):

djlogin_1=peter
djpassword_1=foobar
djpriority_1=4

djlogin_2=paul
djpassword_2=goaway
djpriority_2=2

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.

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.

<?xml version="1.0" encoding="UTF-8" ?>
<eventlist>
<event type="dj">
<dj archive="0">peter</dj>
<calendar/>
</event>
<event type="dj">
<dj archive="1">paul</dj>
<calendar starttime="02:00:00" duration="01:00:00" repeat="4"/>
</event>
</eventlist>

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.

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.

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Example Configurations==

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:

sc_trans_basic.conf
sc_trans_capture.conf
sc_trans_dj.conf
sc_trans_playlist.conf
sc_trans_simple.conf

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]]).

In all cases the examples are designed to work from the same install folder as sc_trans.

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.

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).

===sc_trans_basic===
----

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).

===sc_trans_capture===
----

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]]).

===sc_trans_dj===
----

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.

===sc_trans_playlist===
----

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.

===sc_trans_debug===
----

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.

===sc_trans_simple===
----

Use this if you just need to get a very basic transcoder running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

All you need to do when using this configuration file is to:

* Edit the playlist file to be used (as referenced in the playlistfile entry)
* 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)
* Change the stream information details as appropriate

SHOUTcast DNAS Transcoder 2

2022-10-06T10:31:58Z

Djegg: /* Introduction */

{{Template:NavBarSC}}

==Introduction==

'''The Shoutcast Transcoder (sc_trans) is no longer maintained or supported.'''
'''This documentation remains here for legacy purposes only.'''

----

This document shows 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.

==Getting Started==

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).

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.

===Running The Transcoder===
----

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.

===Windows===
----

The Windows version of sc_trans is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_trans.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_trans will abort loading.

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.

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:

sc_trans.exe install sc_trans 0 0 sc_trans.conf

====Uninstall the Service====
----

sc_trans.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_trans.exe uninstall sc_trans

====Run as a Non-Service in the Console====
----

sc_trans.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_trans daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_trans will abort loading.

'''e.g.'''
./sc_trans daemon ./sc_trans.conf

When run this should output the following:

'sc_trans going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_trans <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile
SIGWINCH - Skips to next song in playlist
SIGUSR1 - Reload playlist
SIGUSR2 - Toggle playlist shuffle

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.

These signals are not supported by the Windows version of sc_trans which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

===Registering for MP3 Stream Encoding===
----

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.

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:
http://shop.winamp.com/servlet/PromoServlet/promoID.48873700

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]]).

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:
unlockkeyname=Bob Cratchit
unlockkeycode=123456

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.

====Why Does AAC Encoding Not Require a License Key?====
----

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.

===Supported File Formats===
----

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:

MP3 + MPEG (treated as mp3)
WAV (uncompressed)
OGG
FLAC

==Configuration File==

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.

The entries stored in the configuration file are processed case insensitively.

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
any instances of a configuration option will assume it is for _1.

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:

encoder_1=aacp
encoder_2=mp3
bitrate_1=32000
bitrate_2=32000

Note that you CANNOT do it like this as it leads to not all values being set:

encoder_1=aacp
encoder_2=mp3
bitrate=32000

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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Administration===
----

'''adminport''' : Specify the port used to access the administrative control page ''[Default = 0]''
If no valid port is specified (i.e. zero) then this feature is disabled.

'''adminuser''' : Specify the username used to access the administrative control page ''[Default = admin]''

'''adminpassword''' : Specify the password to access the administrative control page ''[Default = goaway]''

===Calendar Events===
----

'''calendarfile''' : Specify the path to the xml based calendar file ''[Default = calendar.xml]''

'''calendarrewrite''' : Re-write the 'calendar file' on exit ''[Default = 1]''

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.

===DJ Support===
----

'''djport''' : Specify the port to listen on for DJ access using the SHOUTcast 1 protocol ''[Default = 0 (no listening)]''
This will actually open 'djport + 1' as the listening port.

'''djport2''' : Specify the port to listen on for DJ access using the SHOUTcast 2 protocol ''[Default = 0 (no listening)]''

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.

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) :
djport=900 ; i.e. will open port 901
djport2=901
Whereas this would work as we are opening two different ports (901 + 902):
djport=900
djport2=902

'''djcipher''' : Specify the key used to obfuscate the initial handshaking with the SHOUTcast 2 protocol ''[Default = foobar]''
This is a YP2 feature and it matches the 'uvoxcipherkey' value in
the sc_serv configuration file (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

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.

'''autodumpsourcetime''' : Specify the maximum idle time for the DJ in seconds before being disconnected ''[Default = 30]''

'''djbroadcasts''' : Specify the directory in which DJ broadcasts will be recorded into ''[Default = recorded\ or recorded/ - relative to sc_trans[.exe] ]''

'''djcapture''' : Enable to allow the recording of the DJ broadcast ''[Default = 1]''

'''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)]''
The date and time information are formatted using strftime().

''<MULTI>'' (one set for each DJ):

'''djlogin''' : Specify the username required for the DJ to get access [Default = dj]
When connecting as a SHOUTcast 1 source the password has to be specified as <djlogin>:<djpassword> '''e.g.''' dj:noise

'''djpassword''' : Specify the password required for the DJ to get access ''[Default = noise]''

'''djpriority''' : Specify the priority for the DJ when multiple DJ's are connected ''[Default = 1]''

===Encoder Options===
----

''<MULTI>'' (one set for each encoder):

'''encoder''' : Specify the encoder to use, either (mp3 or aacp) ''[Default = aacp]''

'''bitrate''' : Specify the encoding bitrate in bits per second ''[Default = 96000]''

'''samplerate''' : Specify the encoding sample rate to use ''[Default = 44100]''

'''channels''' : Specify the number of channels to encode ''[Default = 2]''

'''mp3quality''' : Specify the MP3 encoder quality to use when encoding ''[Default = 0]''
Available options are :
0 - fast (preferred)
1 - high quality (changes sample rate and does additional filtering)

'''mp3mode''' : Specify the MP3 encoder mode (CBR / VBR) to use when encoding ''[Default = 0]''
Available options are :
0 - CBR
1 - VBR High Quality
2 -
3 - VBR Medium Quality
4 -
5 - VBR Low Quality]

===Flash Security===
----

'''flashpolicyfile''' : Specify the name of file which contains the flash crossdomain policies ''[Default = crossdomain.xml]''

'''flashpolicyserverport''' : Specify the port used for the flash policy server ''[Default = 0]''
Specify '843' if you want to turn this on.

===Live Capture===
----

'''capture''' : Enable to allow the use of live capture as an input ''[Default = 0]''

'''capturedevice''' : Specify the OS dependent device used for capture ''[Default = <no value>]''

'''captureinput''' : Specify the OS dependent input used for capture ''[Default = <no value>]''

'''capturesamplerate''' : Specify the sample rate used for capture ''[Default = 44100]''

'''capturechannels''' : Specify the number of channels to capture ''[Default = 2]''

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.

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.

===Logging Options===
----

'''log''' : Enable logging of the transmission output ''[Default = 1]''

'''screenlog''' : Enable logging of output to the console ''[Default = 1]''
If log=0 or when running this as a daemon / service then this option is ignored as it is not applicable.

'''logfile''' : Specify a different logfile to save the transmission logs into ''[Default = %temp%\sc_trans.log or /tmp/sc_trans.log]''

If you are using a folder for saving the logs into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Metadata Control===
----

'''streamtitle''' : Specify the general name for the radio station or stream ''[Default - Misc]''

'''streamurl''' : Specify the url of the radio station or stream ''[Default = <nowiki>http://www.shoutcast.com</nowiki>]''

'''genre''' : Specify the genre for the radio station or stream ''[Default - N/A]''

'''aim''' : Specify the AIM contact ID to show for the radio station or stream ''[Default - N/A]''

'''irc''' : Specify the IRC contact ID to show for the radio station or stream ''[Default - N/A]''

'''icq''' : Specify the ICQ contact ID to show for the radio station or stream ''[Default - N/A]''

'''public''' : Enable to register the radio station or stream with the YP (shoutcast.com) ''[Default = 0]''
If connected to sc_serv then this is used by the 'publicserver' value
unless it is being overriden (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

'''usemetadata''' : Enable to use use the in file metadata i.e. stored in file tags ''[Default = 1]''

'''metadatapattern''' : Specify the pattern used for extracting metadata from the filename ''[Default = *\%N.* or */%N.*]''
See [[#Filename_Metadata_Extraction|section 6.0]] for more details about this)

'''displaymetadatapattern''' : Specify a pattern to use to form the metadata output string for SHOUTcast 1 metadata ''[Default = %R[ - ]%N]''

'''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]''
This is the maximum limit attempted to be reported and will vary based on the source in use
e.g. if there enough entries in the current playlist being played. Setting to zero will disable this.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on exit ''[Default = 0]''

'''timemultiplier''' : Used to shift reported time in certain uses ''[Default = 1]''

'''inheritconfig''': Specify the path of the sc_serv2 configuration file for the instance you want to use the transcoder with ''[Default = <no value>]''

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.

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:

* '''portbase -> serverport'''
* '''password -> password''' - Master source password overriden by streampassword
* '''streampassword -> password'''
* '''uvoxcipherkey -> djcipher'''
* '''srcip -> serverip''' - Will use the ip set unless is empty or srcip=any
* '''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

Additionally this mode will attempt to read configurations from a v1 DNAS file.

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

'''serverbackupfile''' : Set the server side file for broken connection playback ''[Default = <no value>]''

'''serverintrofile''' : Set the server side file that is played when a user connects ''[Default = <no value>]''

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).

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).

===MP3 Encoding===
----

'''unlockkeyname''' : Specify the name to use to unlock mp3 encoding (case sensitive)

'''unlockkeycode''' : Specify the code associated with name to unlock mp3 encoding

Due to licensing requirements for MP3 encoding see [[#Registering_for_MP3_Stream_Encoding|section 2.5]]
for how to obtain the key required for unlocking MP3 encoding in sc_trans.

===Network Options===
----

''<MULTI>'' (one set for each connection):

'''endpointname''' : Specify the name of the endpoint ''[Default - <no value>]''
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.

'''outprotocol''' : Specify the server protocol to use ''[Default = 1]''
This can be:
1 = SHOUTcast 1 (Legacy)
2 = Ultravox (Ultravox 2.0)
3 = SHOUTcast 2 (Ultravox 2.1)

'''serverip''' : Specify the IP address of server to connect to ''[Default - <no value>]''
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]]).

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.

'''serverport''' : Specify the server port used to connect to ''[Default = 8000]''
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]]).

'''password''' : Specify the password used to connect to a DNAS server ''[Default = foobar]''
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).

'''streamid''' : Specify the stream identifier for the SHOUTcast 2 connection ''[Default = 1]''
This relates to the 'streamid' value in the sc_serv configuration (see [[SHOUTcast_DNAS_Server_2#Networking|sc_serv2.txt - section 4.8]]).

'''uvoxuserid''' : Specify the user ID for accessing SHOUTcast 2 (Ultravox 2.1) ''[Default - <no value>]''
This is currently not used and is provided for future usage.

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.

'''uvoxradiometadata''' : Enable to send the older AOL Radio style metadata to the server ''[Default = 0]''

'''uvoxnewmetadata''' : Enable to send SHOUTcast 2 style metadata to the server ''[Default = 1]''

'''uvoxmetadatafudgefactor''' : Specify the delaying factor for Ultravox metadata in seconds ''[Default = 0.0]''

'''shoutcastmetadatafudgefactor''' : Specify the delaying factor for SHOUTcast metadata in seconds ''[Default = 0.0]''

===Playlist Control===
----

'''playlistfile''' : Specify the name of playlist file to use ''[Default = <no value>]''

'''shuffle''' : Enable to allow shuffling of the specified playlist ''[Default = 1]''

'''xfade''' : Specify the number of seconds to do for a crossfade ''[Default = 1]''
Specify xfade=0 to disable crossfade

'''xfadethreshold''' : Specify the minimum duration in seconds a file must be to allow crossfading in and out on it ''[Default = 10]''

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.

'''playlists''' : Specify the folder used for priority playlists ''[Default = priority\ or priority/ - relative to sc_trans[.exe]]''

'''archive''' : Specify the folder used for archiving playlists ''[Default = priority\archived\ or priority/archived/ - relative to sc_trans[.exe]]''

''<MULTI>'' (one set for each additional playlist):

'''playlistfilename''' - Used to build named collections of playlists ''[Default = <no value>]''

'''playlistfilepath''' - Used to build named collections of playlists ''[Default = <no value>]''

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.

===Replay Gain Control===
----

'''applyreplaygain''' : Enable to honour the replay gain values stored in the file ''[Default = 0]''

'''defaultreplaygain''' : If no replay gain is in the file then apply this adjustment ''[Default = 0.0]''

'''djreplaygain''' : Specify the replay gain to be applied to DJ streams ''[Default = 0.0]''

'''capturereplaygain''' : Specify the replay gain to apply to the live capture input ''[Default = 0.0]''

'''calculatereplaygain''' : Enable to calculate the replay gain on the handled files ''[Default = 0]''

'''replaygaintmpdir''' : Specify the temporary directory for replay gain calculator to work in ''[Default = (Windows = %TEMP FOLDER% Linux = /tmp/)]''

'''replaygainrunahead''' : Specify the number of tracks head start to give the replay gain calculator ''[Default = 2]''

'''replaygaindontwrite''' : Specify if the replay gain values calculated should NOT be written to the file ''[Default = 0]''

'''enhancereplaygain''' : Specify if the file has replay gain and it is being used, an additional amount of gain to add ''[Default = 6.0]''
Winamp ships with a default value to add -6dB to file which do not have replay gain.

===VU Image===
----

'''vuimagedirectory''' : Specify the folder in which to look for vu images to use ''[Default = ""]''
The image files are named vuimage_XX.<vuimagesuffix> where 'XX' is from 0 to 100
and the path specified will need to be properly terminated to work correctly.

'''vuimagesuffix''' : Specify the suffix for vu images to be used from the image directory ''[Default = png]''

'''vuimagemimetype''' : Specify the mime type for vu images to be used ''[Default = image/png]''

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.

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''shuffledebug''' : Enable to activate debug logging of playlist shuffling ''[Default = 0]''

'''shoutcastdebug''' : Enable to activate debug logging for SHOUTcast transmission ''[Default = 0]''

'''uvoxdebug''' : Enable to activate debug logging for SHOUTcast 2 (Ultravox 2.1) transmissions ''[Default = 0]''

'''gaindebug''' : Enable to activate debug logging for replay gain on playback ''[Default = 0]''

'''playlistdebug''' : Enable to activate debug logging for playlists ''[Default = 0]''

'''mp3encdebug''' : Enable to activate debug logging for MP3 encoding ''[Default = 0]''

'''mp3decdebug''' : Enable to activate debug logging for MP3 decoder ''[Default = 0]''

'''resamplerdebug''' : Enable to activate debug logging for the resampler ''[Default = 0]''

'''rgcalcdebug''' : Enable to activate debug logging for the replay gain calculator ''[Default = 0]''

'''apidebug''' : Enable to activate debug logging for the AJAX api ''[Default = 0]''

'''calendardebug''' : Enable to activate debug logging for the calendar events ''[Default = 0]''

'''capturedebug''' : Enable to activate debug logging for live capture ''[Default = 0]''

'''djdebug''' : Enable to activate debug logging for DJ management ''[Default = 0]''

'''flashpolicyserverdebug''' : Enable to activate debug logging for the flash policy server ''[Default = 0]''

'''fileconverterdebug''' : Enable to activate debug logging for the server side file converter ''[Default = 0]''

'''sourcerelaydebug''' : Enable to active debug logging for relayed sources ''[Default = 0]''

'''sourceandendpointmanagerdebug''' : Enable to activate debug logging for endpoint management ''[Default = 0]''

==Administration Weblet Commands==

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]]).

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]].

===Supported Weblet Commands===
----

The following are the supported commands for the administration weblet the transcoder supports and are used in the following manner:
<nowiki>http://<server_ip>:adminport/<command></nowiki>

'''quit''' : Will make sc_trans quit (equivalent of SIGKILL on non-Windows).

'''rotatelogs''' : Will rotate the logs (equivalent of SIGHUP).
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.

'''nextsong''' : Will advance to the next song (equivalent of SIGWINCH).

'''loadplaylist''' : This will re-load the current playlist (equivalent of SIGUSR1).

'''toggleshuffle''' : Use to toggle the current playlist shuffle state (equivalent of SIGUSR2).

'''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).

'''restart''' : Restart the current sc_trans instance.

'''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]]).

'''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:
0xa5 leftVal rightVal 0xa5 leftVal ..... etc

If the audio signal is mono there is no right val and you get:
0xa5 leftVal 0xa5 leftVal .... etc

'''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.

'''crossdomain.xml''' : This will return the current copy of crossdomain.xml as set with 'flashPolicyFile' ([[#Flash_Security|see section 3.5]]).

'''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).

'''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]].

==Metadata Support==

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.

===MP3 Files===
----

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:
# Unsynch data is not supported
# Compressed frames are not supported
# Encrypted frames are not supported
# Appended v4 frames are not supported

===FLAC and OGG Files===
----

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.

==Filename Metadata Extraction==

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.

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.

===Filename Metadata Extraction Pattern===
----

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'.

The default pattern used is *\%N.* (Windows) and */%N.* (all other OSes). The following are the formatting options which are supported in the pattern:
%N = Song name
%G = Genre
%A = Album
%R = Artist
%Y = Four digit year
%# = Sequence of digits
%% = % character
[] = Brackets optional elements (no nesting)
* = String
Other characters are matched exactly as found.

The pattern matching is done working from the right to the left.

===Filename Metadata Extraction Examples===
----

The following examples show the metadata pattern matching working.

====Example #1====
----

metadataPattern = */%R/%Y%A/Audio/[%#_]%N.*
filepath = /home/songs/Mask and Wig/1969 Irreverance Of Things Past/Audio/03_The Royal Blues.mp3

Extracted metadata result:
ALBUM = Irreverance Of Things Past
ARTIST = Mask and Wig
SONG = The Royal Blues
YEAR = 1969

====Example #2====
----

metadatapattern = */%A/[%R_]%N
filepath = /home/album/song

Extracted metadata result:
ALBUM = album
SONG = song

====6.2.3 Example #3====
----

metadatapattern = */%A/%R_%N
filepath = /home/album/artist_song

Extracted metadata result:
ALBUM = album
ARTIST = artist
SONG = song

===File Metadata Construction For SHOUTcast 1===
----

You can specify how metadata elements are concatenated together to from the SHOUTcast 1 metadata string by specifying the 'displaymetadatapattern' option.

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.

The following token substitutions are made with 'displaymetadatapattern':

%N = Song name
%A = Album name
%R = Artist
%G = Song genre
%Y = song year
%t = Station name (a.k.a. stream title a.k.a. icy-name)
%u = Station url (a.k.a. icy-url)
%g = Station genre (a.k.a. icy-genre)

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.

==Playlists Support==

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.

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.

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.

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.

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

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.

Additionally these entries can be intermixed with regular explicit entries '''e.g.'''
c:\music\foo.mp3
c:\music\otherstuff\*.mp3
c:\music\bar.mp3

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.

===Supported Playlist Formats===
----

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:

Plain text file - this is the equivalent of a commentless M3U / M3U8 file
PLS
M3U
M3U8 (UTF-8 encoded version of the M3U format)

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.

===Remote Applications===
----

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.'''
/music/foo.mp3
#!/bin/perl /home/user/songfromDB.pl
/music/bar.mp3

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.

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.

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.

Additionally you can pair remote application actions together in such a manner:
#!php call track script
#!php call commercial script

where this will alternate between the first and second scripts returning the file to be processed through sc_trans.

===Additional Information===
----

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.

There are a number of scenarios to be considered for remote application entries in a playlist as detailed in the following list:

# The standard out from the command is used as the name of the file to open.
# If the standard out is empty then the entry will be skipped.
# 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.
# 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.
# 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.
# If you return the requested number of additional tracks (passed in when it is run) then these will be used for "coming soon" calculations.
# 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.

==DJing Information==

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.

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).

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.

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.

===Setting Up DJs In The New Scheme===
----

DJ accounts are set up by using the 'djlogin', 'djpassword' and 'djpriority' options as shown in <MULTI> options under [[#DJ_Support|section 3.3]].

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):

djlogin_1=peter
djpassword_1=foobar
djpriority_1=4

djlogin_2=paul
djpassword_2=goaway
djpriority_2=2

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.

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.

<?xml version="1.0" encoding="UTF-8" ?>
<eventlist>
<event type="dj">
<dj archive="0">peter</dj>
<calendar/>
</event>
<event type="dj">
<dj archive="1">paul</dj>
<calendar starttime="02:00:00" duration="01:00:00" repeat="4"/>
</event>
</eventlist>

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.

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.

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Example Configurations==

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:

sc_trans_basic.conf
sc_trans_capture.conf
sc_trans_dj.conf
sc_trans_playlist.conf
sc_trans_simple.conf

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]]).

In all cases the examples are designed to work from the same install folder as sc_trans.

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.

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).

===sc_trans_basic===
----

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).

===sc_trans_capture===
----

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]]).

===sc_trans_dj===
----

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.

===sc_trans_playlist===
----

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.

===sc_trans_debug===
----

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.

===sc_trans_simple===
----

Use this if you just need to get a very basic transcoder running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

All you need to do when using this configuration file is to:

* Edit the playlist file to be used (as referenced in the playlistfile entry)
* 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)
* Change the stream information details as appropriate

SHOUTcast DNAS Transcoder 2

2022-10-06T10:31:17Z

Djegg: /* Introduction */

{{Template:NavBarSC}}

==Introduction==
'''
The Shoutcast Transcoder (sc_trans) is no longer maintained or supported.
This documentation remains here for legacy purposes only.'''

----

This document shows 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.

==Getting Started==

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).

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.

===Running The Transcoder===
----

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.

===Windows===
----

The Windows version of sc_trans is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_trans.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_trans will abort loading.

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.

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:

sc_trans.exe install sc_trans 0 0 sc_trans.conf

====Uninstall the Service====
----

sc_trans.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_trans.exe uninstall sc_trans

====Run as a Non-Service in the Console====
----

sc_trans.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_trans daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_trans will abort loading.

'''e.g.'''
./sc_trans daemon ./sc_trans.conf

When run this should output the following:

'sc_trans going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_trans <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_trans will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile
SIGWINCH - Skips to next song in playlist
SIGUSR1 - Reload playlist
SIGUSR2 - Toggle playlist shuffle

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.

These signals are not supported by the Windows version of sc_trans which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

===Registering for MP3 Stream Encoding===
----

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.

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:
http://shop.winamp.com/servlet/PromoServlet/promoID.48873700

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]]).

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:
unlockkeyname=Bob Cratchit
unlockkeycode=123456

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.

====Why Does AAC Encoding Not Require a License Key?====
----

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.

===Supported File Formats===
----

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:

MP3 + MPEG (treated as mp3)
WAV (uncompressed)
OGG
FLAC

==Configuration File==

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.

The entries stored in the configuration file are processed case insensitively.

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
any instances of a configuration option will assume it is for _1.

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:

encoder_1=aacp
encoder_2=mp3
bitrate_1=32000
bitrate_2=32000

Note that you CANNOT do it like this as it leads to not all values being set:

encoder_1=aacp
encoder_2=mp3
bitrate=32000

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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Administration===
----

'''adminport''' : Specify the port used to access the administrative control page ''[Default = 0]''
If no valid port is specified (i.e. zero) then this feature is disabled.

'''adminuser''' : Specify the username used to access the administrative control page ''[Default = admin]''

'''adminpassword''' : Specify the password to access the administrative control page ''[Default = goaway]''

===Calendar Events===
----

'''calendarfile''' : Specify the path to the xml based calendar file ''[Default = calendar.xml]''

'''calendarrewrite''' : Re-write the 'calendar file' on exit ''[Default = 1]''

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.

===DJ Support===
----

'''djport''' : Specify the port to listen on for DJ access using the SHOUTcast 1 protocol ''[Default = 0 (no listening)]''
This will actually open 'djport + 1' as the listening port.

'''djport2''' : Specify the port to listen on for DJ access using the SHOUTcast 2 protocol ''[Default = 0 (no listening)]''

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.

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) :
djport=900 ; i.e. will open port 901
djport2=901
Whereas this would work as we are opening two different ports (901 + 902):
djport=900
djport2=902

'''djcipher''' : Specify the key used to obfuscate the initial handshaking with the SHOUTcast 2 protocol ''[Default = foobar]''
This is a YP2 feature and it matches the 'uvoxcipherkey' value in
the sc_serv configuration file (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

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.

'''autodumpsourcetime''' : Specify the maximum idle time for the DJ in seconds before being disconnected ''[Default = 30]''

'''djbroadcasts''' : Specify the directory in which DJ broadcasts will be recorded into ''[Default = recorded\ or recorded/ - relative to sc_trans[.exe] ]''

'''djcapture''' : Enable to allow the recording of the DJ broadcast ''[Default = 1]''

'''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)]''
The date and time information are formatted using strftime().

''<MULTI>'' (one set for each DJ):

'''djlogin''' : Specify the username required for the DJ to get access [Default = dj]
When connecting as a SHOUTcast 1 source the password has to be specified as <djlogin>:<djpassword> '''e.g.''' dj:noise

'''djpassword''' : Specify the password required for the DJ to get access ''[Default = noise]''

'''djpriority''' : Specify the priority for the DJ when multiple DJ's are connected ''[Default = 1]''

===Encoder Options===
----

''<MULTI>'' (one set for each encoder):

'''encoder''' : Specify the encoder to use, either (mp3 or aacp) ''[Default = aacp]''

'''bitrate''' : Specify the encoding bitrate in bits per second ''[Default = 96000]''

'''samplerate''' : Specify the encoding sample rate to use ''[Default = 44100]''

'''channels''' : Specify the number of channels to encode ''[Default = 2]''

'''mp3quality''' : Specify the MP3 encoder quality to use when encoding ''[Default = 0]''
Available options are :
0 - fast (preferred)
1 - high quality (changes sample rate and does additional filtering)

'''mp3mode''' : Specify the MP3 encoder mode (CBR / VBR) to use when encoding ''[Default = 0]''
Available options are :
0 - CBR
1 - VBR High Quality
2 -
3 - VBR Medium Quality
4 -
5 - VBR Low Quality]

===Flash Security===
----

'''flashpolicyfile''' : Specify the name of file which contains the flash crossdomain policies ''[Default = crossdomain.xml]''

'''flashpolicyserverport''' : Specify the port used for the flash policy server ''[Default = 0]''
Specify '843' if you want to turn this on.

===Live Capture===
----

'''capture''' : Enable to allow the use of live capture as an input ''[Default = 0]''

'''capturedevice''' : Specify the OS dependent device used for capture ''[Default = <no value>]''

'''captureinput''' : Specify the OS dependent input used for capture ''[Default = <no value>]''

'''capturesamplerate''' : Specify the sample rate used for capture ''[Default = 44100]''

'''capturechannels''' : Specify the number of channels to capture ''[Default = 2]''

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.

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.

===Logging Options===
----

'''log''' : Enable logging of the transmission output ''[Default = 1]''

'''screenlog''' : Enable logging of output to the console ''[Default = 1]''
If log=0 or when running this as a daemon / service then this option is ignored as it is not applicable.

'''logfile''' : Specify a different logfile to save the transmission logs into ''[Default = %temp%\sc_trans.log or /tmp/sc_trans.log]''

If you are using a folder for saving the logs into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Metadata Control===
----

'''streamtitle''' : Specify the general name for the radio station or stream ''[Default - Misc]''

'''streamurl''' : Specify the url of the radio station or stream ''[Default = <nowiki>http://www.shoutcast.com</nowiki>]''

'''genre''' : Specify the genre for the radio station or stream ''[Default - N/A]''

'''aim''' : Specify the AIM contact ID to show for the radio station or stream ''[Default - N/A]''

'''irc''' : Specify the IRC contact ID to show for the radio station or stream ''[Default - N/A]''

'''icq''' : Specify the ICQ contact ID to show for the radio station or stream ''[Default - N/A]''

'''public''' : Enable to register the radio station or stream with the YP (shoutcast.com) ''[Default = 0]''
If connected to sc_serv then this is used by the 'publicserver' value
unless it is being overriden (see [[SHOUTcast_DNAS_Server_2#YP_Server_Behaviour|sc_serv2.txt - section 4.14]]).

'''usemetadata''' : Enable to use use the in file metadata i.e. stored in file tags ''[Default = 1]''

'''metadatapattern''' : Specify the pattern used for extracting metadata from the filename ''[Default = *\%N.* or */%N.*]''
See [[#Filename_Metadata_Extraction|section 6.0]] for more details about this)

'''displaymetadatapattern''' : Specify a pattern to use to form the metadata output string for SHOUTcast 1 metadata ''[Default = %R[ - ]%N]''

'''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]''
This is the maximum limit attempted to be reported and will vary based on the source in use
e.g. if there enough entries in the current playlist being played. Setting to zero will disable this.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on exit ''[Default = 0]''

'''timemultiplier''' : Used to shift reported time in certain uses ''[Default = 1]''

'''inheritconfig''': Specify the path of the sc_serv2 configuration file for the instance you want to use the transcoder with ''[Default = <no value>]''

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.

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:

* '''portbase -> serverport'''
* '''password -> password''' - Master source password overriden by streampassword
* '''streampassword -> password'''
* '''uvoxcipherkey -> djcipher'''
* '''srcip -> serverip''' - Will use the ip set unless is empty or srcip=any
* '''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

Additionally this mode will attempt to read configurations from a v1 DNAS file.

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

'''serverbackupfile''' : Set the server side file for broken connection playback ''[Default = <no value>]''

'''serverintrofile''' : Set the server side file that is played when a user connects ''[Default = <no value>]''

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).

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).

===MP3 Encoding===
----

'''unlockkeyname''' : Specify the name to use to unlock mp3 encoding (case sensitive)

'''unlockkeycode''' : Specify the code associated with name to unlock mp3 encoding

Due to licensing requirements for MP3 encoding see [[#Registering_for_MP3_Stream_Encoding|section 2.5]]
for how to obtain the key required for unlocking MP3 encoding in sc_trans.

===Network Options===
----

''<MULTI>'' (one set for each connection):

'''endpointname''' : Specify the name of the endpoint ''[Default - <no value>]''
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.

'''outprotocol''' : Specify the server protocol to use ''[Default = 1]''
This can be:
1 = SHOUTcast 1 (Legacy)
2 = Ultravox (Ultravox 2.0)
3 = SHOUTcast 2 (Ultravox 2.1)

'''serverip''' : Specify the IP address of server to connect to ''[Default - <no value>]''
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]]).

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.

'''serverport''' : Specify the server port used to connect to ''[Default = 8000]''
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]]).

'''password''' : Specify the password used to connect to a DNAS server ''[Default = foobar]''
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).

'''streamid''' : Specify the stream identifier for the SHOUTcast 2 connection ''[Default = 1]''
This relates to the 'streamid' value in the sc_serv configuration (see [[SHOUTcast_DNAS_Server_2#Networking|sc_serv2.txt - section 4.8]]).

'''uvoxuserid''' : Specify the user ID for accessing SHOUTcast 2 (Ultravox 2.1) ''[Default - <no value>]''
This is currently not used and is provided for future usage.

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.

'''uvoxradiometadata''' : Enable to send the older AOL Radio style metadata to the server ''[Default = 0]''

'''uvoxnewmetadata''' : Enable to send SHOUTcast 2 style metadata to the server ''[Default = 1]''

'''uvoxmetadatafudgefactor''' : Specify the delaying factor for Ultravox metadata in seconds ''[Default = 0.0]''

'''shoutcastmetadatafudgefactor''' : Specify the delaying factor for SHOUTcast metadata in seconds ''[Default = 0.0]''

===Playlist Control===
----

'''playlistfile''' : Specify the name of playlist file to use ''[Default = <no value>]''

'''shuffle''' : Enable to allow shuffling of the specified playlist ''[Default = 1]''

'''xfade''' : Specify the number of seconds to do for a crossfade ''[Default = 1]''
Specify xfade=0 to disable crossfade

'''xfadethreshold''' : Specify the minimum duration in seconds a file must be to allow crossfading in and out on it ''[Default = 10]''

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.

'''playlists''' : Specify the folder used for priority playlists ''[Default = priority\ or priority/ - relative to sc_trans[.exe]]''

'''archive''' : Specify the folder used for archiving playlists ''[Default = priority\archived\ or priority/archived/ - relative to sc_trans[.exe]]''

''<MULTI>'' (one set for each additional playlist):

'''playlistfilename''' - Used to build named collections of playlists ''[Default = <no value>]''

'''playlistfilepath''' - Used to build named collections of playlists ''[Default = <no value>]''

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.

===Replay Gain Control===
----

'''applyreplaygain''' : Enable to honour the replay gain values stored in the file ''[Default = 0]''

'''defaultreplaygain''' : If no replay gain is in the file then apply this adjustment ''[Default = 0.0]''

'''djreplaygain''' : Specify the replay gain to be applied to DJ streams ''[Default = 0.0]''

'''capturereplaygain''' : Specify the replay gain to apply to the live capture input ''[Default = 0.0]''

'''calculatereplaygain''' : Enable to calculate the replay gain on the handled files ''[Default = 0]''

'''replaygaintmpdir''' : Specify the temporary directory for replay gain calculator to work in ''[Default = (Windows = %TEMP FOLDER% Linux = /tmp/)]''

'''replaygainrunahead''' : Specify the number of tracks head start to give the replay gain calculator ''[Default = 2]''

'''replaygaindontwrite''' : Specify if the replay gain values calculated should NOT be written to the file ''[Default = 0]''

'''enhancereplaygain''' : Specify if the file has replay gain and it is being used, an additional amount of gain to add ''[Default = 6.0]''
Winamp ships with a default value to add -6dB to file which do not have replay gain.

===VU Image===
----

'''vuimagedirectory''' : Specify the folder in which to look for vu images to use ''[Default = ""]''
The image files are named vuimage_XX.<vuimagesuffix> where 'XX' is from 0 to 100
and the path specified will need to be properly terminated to work correctly.

'''vuimagesuffix''' : Specify the suffix for vu images to be used from the image directory ''[Default = png]''

'''vuimagemimetype''' : Specify the mime type for vu images to be used ''[Default = image/png]''

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.

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''shuffledebug''' : Enable to activate debug logging of playlist shuffling ''[Default = 0]''

'''shoutcastdebug''' : Enable to activate debug logging for SHOUTcast transmission ''[Default = 0]''

'''uvoxdebug''' : Enable to activate debug logging for SHOUTcast 2 (Ultravox 2.1) transmissions ''[Default = 0]''

'''gaindebug''' : Enable to activate debug logging for replay gain on playback ''[Default = 0]''

'''playlistdebug''' : Enable to activate debug logging for playlists ''[Default = 0]''

'''mp3encdebug''' : Enable to activate debug logging for MP3 encoding ''[Default = 0]''

'''mp3decdebug''' : Enable to activate debug logging for MP3 decoder ''[Default = 0]''

'''resamplerdebug''' : Enable to activate debug logging for the resampler ''[Default = 0]''

'''rgcalcdebug''' : Enable to activate debug logging for the replay gain calculator ''[Default = 0]''

'''apidebug''' : Enable to activate debug logging for the AJAX api ''[Default = 0]''

'''calendardebug''' : Enable to activate debug logging for the calendar events ''[Default = 0]''

'''capturedebug''' : Enable to activate debug logging for live capture ''[Default = 0]''

'''djdebug''' : Enable to activate debug logging for DJ management ''[Default = 0]''

'''flashpolicyserverdebug''' : Enable to activate debug logging for the flash policy server ''[Default = 0]''

'''fileconverterdebug''' : Enable to activate debug logging for the server side file converter ''[Default = 0]''

'''sourcerelaydebug''' : Enable to active debug logging for relayed sources ''[Default = 0]''

'''sourceandendpointmanagerdebug''' : Enable to activate debug logging for endpoint management ''[Default = 0]''

==Administration Weblet Commands==

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]]).

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]].

===Supported Weblet Commands===
----

The following are the supported commands for the administration weblet the transcoder supports and are used in the following manner:
<nowiki>http://<server_ip>:adminport/<command></nowiki>

'''quit''' : Will make sc_trans quit (equivalent of SIGKILL on non-Windows).

'''rotatelogs''' : Will rotate the logs (equivalent of SIGHUP).
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.

'''nextsong''' : Will advance to the next song (equivalent of SIGWINCH).

'''loadplaylist''' : This will re-load the current playlist (equivalent of SIGUSR1).

'''toggleshuffle''' : Use to toggle the current playlist shuffle state (equivalent of SIGUSR2).

'''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).

'''restart''' : Restart the current sc_trans instance.

'''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]]).

'''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:
0xa5 leftVal rightVal 0xa5 leftVal ..... etc

If the audio signal is mono there is no right val and you get:
0xa5 leftVal 0xa5 leftVal .... etc

'''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.

'''crossdomain.xml''' : This will return the current copy of crossdomain.xml as set with 'flashPolicyFile' ([[#Flash_Security|see section 3.5]]).

'''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).

'''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]].

==Metadata Support==

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.

===MP3 Files===
----

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:
# Unsynch data is not supported
# Compressed frames are not supported
# Encrypted frames are not supported
# Appended v4 frames are not supported

===FLAC and OGG Files===
----

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.

==Filename Metadata Extraction==

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.

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.

===Filename Metadata Extraction Pattern===
----

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'.

The default pattern used is *\%N.* (Windows) and */%N.* (all other OSes). The following are the formatting options which are supported in the pattern:
%N = Song name
%G = Genre
%A = Album
%R = Artist
%Y = Four digit year
%# = Sequence of digits
%% = % character
[] = Brackets optional elements (no nesting)
* = String
Other characters are matched exactly as found.

The pattern matching is done working from the right to the left.

===Filename Metadata Extraction Examples===
----

The following examples show the metadata pattern matching working.

====Example #1====
----

metadataPattern = */%R/%Y%A/Audio/[%#_]%N.*
filepath = /home/songs/Mask and Wig/1969 Irreverance Of Things Past/Audio/03_The Royal Blues.mp3

Extracted metadata result:
ALBUM = Irreverance Of Things Past
ARTIST = Mask and Wig
SONG = The Royal Blues
YEAR = 1969

====Example #2====
----

metadatapattern = */%A/[%R_]%N
filepath = /home/album/song

Extracted metadata result:
ALBUM = album
SONG = song

====6.2.3 Example #3====
----

metadatapattern = */%A/%R_%N
filepath = /home/album/artist_song

Extracted metadata result:
ALBUM = album
ARTIST = artist
SONG = song

===File Metadata Construction For SHOUTcast 1===
----

You can specify how metadata elements are concatenated together to from the SHOUTcast 1 metadata string by specifying the 'displaymetadatapattern' option.

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.

The following token substitutions are made with 'displaymetadatapattern':

%N = Song name
%A = Album name
%R = Artist
%G = Song genre
%Y = song year
%t = Station name (a.k.a. stream title a.k.a. icy-name)
%u = Station url (a.k.a. icy-url)
%g = Station genre (a.k.a. icy-genre)

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.

==Playlists Support==

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.

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.

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.

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.

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

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.

Additionally these entries can be intermixed with regular explicit entries '''e.g.'''
c:\music\foo.mp3
c:\music\otherstuff\*.mp3
c:\music\bar.mp3

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.

===Supported Playlist Formats===
----

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:

Plain text file - this is the equivalent of a commentless M3U / M3U8 file
PLS
M3U
M3U8 (UTF-8 encoded version of the M3U format)

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.

===Remote Applications===
----

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.'''
/music/foo.mp3
#!/bin/perl /home/user/songfromDB.pl
/music/bar.mp3

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.

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.

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.

Additionally you can pair remote application actions together in such a manner:
#!php call track script
#!php call commercial script

where this will alternate between the first and second scripts returning the file to be processed through sc_trans.

===Additional Information===
----

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.

There are a number of scenarios to be considered for remote application entries in a playlist as detailed in the following list:

# The standard out from the command is used as the name of the file to open.
# If the standard out is empty then the entry will be skipped.
# 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.
# 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.
# 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.
# If you return the requested number of additional tracks (passed in when it is run) then these will be used for "coming soon" calculations.
# 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.

==DJing Information==

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.

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).

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.

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.

===Setting Up DJs In The New Scheme===
----

DJ accounts are set up by using the 'djlogin', 'djpassword' and 'djpriority' options as shown in <MULTI> options under [[#DJ_Support|section 3.3]].

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):

djlogin_1=peter
djpassword_1=foobar
djpriority_1=4

djlogin_2=paul
djpassword_2=goaway
djpriority_2=2

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.

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.

<?xml version="1.0" encoding="UTF-8" ?>
<eventlist>
<event type="dj">
<dj archive="0">peter</dj>
<calendar/>
</event>
<event type="dj">
<dj archive="1">paul</dj>
<calendar starttime="02:00:00" duration="01:00:00" repeat="4"/>
</event>
</eventlist>

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.

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.

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Example Configurations==

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:

sc_trans_basic.conf
sc_trans_capture.conf
sc_trans_dj.conf
sc_trans_playlist.conf
sc_trans_simple.conf

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]]).

In all cases the examples are designed to work from the same install folder as sc_trans.

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.

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).

===sc_trans_basic===
----

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).

===sc_trans_capture===
----

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]]).

===sc_trans_dj===
----

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.

===sc_trans_playlist===
----

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.

===sc_trans_debug===
----

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.

===sc_trans_simple===
----

Use this if you just need to get a very basic transcoder running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

All you need to do when using this configuration file is to:

* Edit the playlist file to be used (as referenced in the playlistfile entry)
* 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)
* Change the stream information details as appropriate

Source DSP Plug-in

2022-09-02T11:48:13Z

Djegg: /* Installing the Plug-in */

{{Template:NavBarSC}}

==Introduction to the Source DSP==

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.

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.

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.

==Getting Started==

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.

===Installing the Plug-in===
----
[[Image:Select_Source_DSP_plugin_in_Winamp.png|225px|thumb|right|Select Source DSP plug-in in Winamp]]

The DSP plugin can be downloaded for free at shoutcast.com

[https://download.nullsoft.com/shoutcast/tools/shoutcast-dsp-2-3-5-windows.exe Shoutcast DSP for Winamp 5.6] | [https://download.nullsoft.com/shoutcast/tools/shoutcast-dsp-2-4-1-windows.exe Shoutcast DSP for Winamp 5.9]

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.

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:

Preferences -> Plug-ins -> DSP/Effect

follwed by selecting the 'Nullsoft SHOUTcast Source DSP' entry shown in the plug-in list.

==Configuration Window==

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.

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.

===Summary Tab===
----

[[Image:Summary_tab_1.png|100px|thumb|right|SHOUTcast Source Summary Tab]]
'''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.

If you double-click one of the output items you will be taken to the '[[#Output Tab|see section 3.2]]'
(see section 3.2) where it will show the current settings for the output selected.

'''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]]).

'''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.

===Output Tab===
----
[[Image:Output_tab_configuration.png|100px|thumb|right|SHOUTcast Source Output Tab - Login settings]]
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.

'''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.

'''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.

'''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.

If there is an issue the 'Connect / Abort / Disconnect / Kill Button' will
show the configuration setting which is invalid e.g. 'Set Password' if the
encoder has not been specified. The tab and the title above where the value
is not set will have it's text changed to red to make it easier to identify.

====Login Tab====
----

This tab allows you to specify the details needed for connecting to a DNAS server.

'''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.

'''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.

'''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.

This is disabled if 'Use SHOUTcast v1 mode (for legacy servers)' is checked.

'''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.

If using a compatible v2 DNAS server then this can be entered and will
be used as an identifier of the current DJ but it is not used for the login.

'''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.

'''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.

'''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.

'''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).

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:
Cipher response received
Try enabling 'SHOUTcast v1 mode'.

When SHOUTcast v2 mode is enabled the information panel displayed below this option shows the following message:
Connecting to a SHOUTcast v1 server in
non-legacy mode will likely cause the last
status message to remain on "Cipher
response received". To fix this you need to
enable the "SHOUTcast v1 mode" above.

When SHOUTcast v1 mode is enabled the information panel displayed below this option shows the following message:
When the DJ password is formatted as
<djlogin>:<djpassword> e.g. dj_1:noise

Enter <djlogin> in 'DJ / User ID' e.g. dj_1
Enter <djpassword> in 'Password' e.g. noise

====Directory Tab====
----

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.

[[Image:Output_tab_Directory.png|100px|thumb|right|SHOUTcast Source Output Directory Tab]]
'''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.

'''Name''' : This is the name you want to use for the source (often what will be used in SHOUTcast Directory listing).

'''URL''' : This is the url for the stream allowing listeners to view or get more information.

'''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.

'''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.

'''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.

====Encoder Tab====
----

[[Image:Output_tab_Encoder.png|100px|thumb|right|SHOUTcast Source Output Encoder Tab]]
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:

MP3 (audio/mpeg)
AAC (audio/aacp)

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.

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.

=====Save Encoded Output=====
----

This allows you to make a backup of the stream audio data sent to the DNAS server.

'''Save a copy of the encoded stream audio''' : Enables or disables saving a copy of the audio.

The extension of the output file is automatically changed based on the selected
encoder option to ensure that the file can be easily played in most media players.

====Titles Tab====
----
[[Image:Output_tab_Titles.png|100px|thumb|right|SHOUTcast Source Output Titles Tab]]
This tab allows you to specify how the stream metadata is gathered from Winamp or if it is manually entered with the options provided.

'''Disable title updates''' : This will prevent the Source DSP from sending any title updates.

'''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.

'''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.

The current version of Winamp is always recommended to use
due to the improved support for this feature since Winamp v5.61.

'''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).

The 'Send Update' button is enabled when a title is entered or it is
different from the existing title. When using SHOUTcast v2 mode the
'next' title field will become available as long as title field is not empty.

====Artwork====
----

[[Image:Output_tab_Artwork.png|100px|thumb|right|SHOUTcast Source Output Artwork in v2 mode]]
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).

'''Send in-stream artwork''' : Enables or disables sending of in-stream artwork.

If this is enabled and then disabled, it is possible that the
plug-in will send some clear artwork messages after disabling
this option to ensure there is no artwork cached by the server.

'''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.

If unchecked or there is no artwork for the playing song then the
DNAS server may be sent a clear artwork message as applicable.

This is sent as a PNG image to the SHOUTcast server.

'''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.

If left empty then the DNAS server may be sent a clear artwork message as applicable.

Using the plug-in with a connection to a legacy server will cause the following notice to be shown:

Stream is setup for a SHOUTcast v1 server
which does not support in-stream artwork.

To send in-stream artwork, uncheck the
"SHOUTcast v1 mode" option and ensure
you connect to a SHOUTcast v2 server.'

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.

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.

====Logs====
----

[[Image:Output_tab_Logs.png|100px|thumb|right|SHOUTcast Source Output Logs Tab]]
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.

The main logging options are not enabled by default though this can be used
for tracking problems with the plug-in e.g. if you are having connection issues.

'''Enable logging of connection status messages''' : Enables or disables connection logging.

'''Clear log file on logging startup''' : This will reset the log everytime the plug-in starts.

'''Open log file...''' : This will open the log file in the associated program for .log files.

'''Clear log file''' : This will clear the log file if it exists. It will not remove the file.

'''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.

'''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.

The next track logging is only updated when the plug-in detects a track
change. If the plain text / xml mode is changed or the plug-in starts then
the file contents will be cleared until the next track title change happens.

===Input Tab===
----
[[Image:Input_tab_Winamp.png|100px|thumb|right|SHOUTcast Source Input Tab in Winamp mode]]

====Input Configuration====
----

'''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.

'''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.

'''Input Settings''' : When the soundcard input is selected then this allows for control over the sample rate used on the input source.

====Soundcard Mixer Control====
----

[[Image:Input_tab_Soundcard.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.

'''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.

'''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]])).

'''Music Level''' : This controls the Winamp output level (from no audio to full audio level).

'''BG Level''' : This controls the Winamp output level when the 'Push to Talk' option is active (from no audio to full audio level).

'''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).

'''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).

'''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).

'''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.

'''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.

'''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.

===About Tab===
----

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.

====Documentation and Support====
----

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.

The documentation is either the current version as shipped with the plug-in if selected during install (stored in '''<winampdir>\Plugins\SHOUTcast Source DSP''').

The support forums is accessed via http://forums.shoutcast.com/forumdisplay.php?f=140

Additional documentation is available here: '''[[Source_DSP_Plug-in_Configuration_Examples|SHOUTcast Source DSP Plug-in Configuration Examples]]'''

==Known Issues==

The following are currently known issue(s) to affect the currently released build of the Source DSP plug-in:

===Soundcard Mixer Control===
----

'''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.

'''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.

'''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.

==SHOUTcast 2 Cipher Key==

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:

Authentication Error:
Cipher Does Not Match

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.

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).

==Example Configurations==

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.

For 3rd party servers or broadcast tools, you may need to consult their documentation to determine from where you get the required configuration values.

Source DSP Plug-in

2022-07-28T16:58:13Z

Djegg: /* Installing the Plug-in */

{{Template:NavBarSC}}

==Introduction to the Source DSP==

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.

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.

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.

==Getting Started==

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.

===Installing the Plug-in===
----
[[Image:Select_Source_DSP_plugin_in_Winamp.png|225px|thumb|right|Select Source DSP plug-in in Winamp]]

The DSP plugin can be downloaded for free at shoutcast.com

[https://download.nullsoft.com/shoutcast/tools/shoutcast-dsp-2-3-5-windows.exe Shoutcast DSP for Winamp 5.6] | [https://download.nullsoft.com/shoutcast/tools/shoutcast-dsp-2-4-0-windows.exe Shoutcast DSP for Winamp 5.9]

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.

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:

Preferences -> Plug-ins -> DSP/Effect

follwed by selecting the 'Nullsoft SHOUTcast Source DSP' entry shown in the plug-in list.

==Configuration Window==

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.

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.

===Summary Tab===
----

[[Image:Summary_tab_1.png|100px|thumb|right|SHOUTcast Source Summary Tab]]
'''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.

If you double-click one of the output items you will be taken to the '[[#Output Tab|see section 3.2]]'
(see section 3.2) where it will show the current settings for the output selected.

'''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]]).

'''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.

===Output Tab===
----
[[Image:Output_tab_configuration.png|100px|thumb|right|SHOUTcast Source Output Tab - Login settings]]
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.

'''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.

'''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.

'''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.

If there is an issue the 'Connect / Abort / Disconnect / Kill Button' will
show the configuration setting which is invalid e.g. 'Set Password' if the
encoder has not been specified. The tab and the title above where the value
is not set will have it's text changed to red to make it easier to identify.

====Login Tab====
----

This tab allows you to specify the details needed for connecting to a DNAS server.

'''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.

'''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.

'''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.

This is disabled if 'Use SHOUTcast v1 mode (for legacy servers)' is checked.

'''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.

If using a compatible v2 DNAS server then this can be entered and will
be used as an identifier of the current DJ but it is not used for the login.

'''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.

'''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.

'''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.

'''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).

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:
Cipher response received
Try enabling 'SHOUTcast v1 mode'.

When SHOUTcast v2 mode is enabled the information panel displayed below this option shows the following message:
Connecting to a SHOUTcast v1 server in
non-legacy mode will likely cause the last
status message to remain on "Cipher
response received". To fix this you need to
enable the "SHOUTcast v1 mode" above.

When SHOUTcast v1 mode is enabled the information panel displayed below this option shows the following message:
When the DJ password is formatted as
<djlogin>:<djpassword> e.g. dj_1:noise

Enter <djlogin> in 'DJ / User ID' e.g. dj_1
Enter <djpassword> in 'Password' e.g. noise

====Directory Tab====
----

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.

[[Image:Output_tab_Directory.png|100px|thumb|right|SHOUTcast Source Output Directory Tab]]
'''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.

'''Name''' : This is the name you want to use for the source (often what will be used in SHOUTcast Directory listing).

'''URL''' : This is the url for the stream allowing listeners to view or get more information.

'''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.

'''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.

'''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.

====Encoder Tab====
----

[[Image:Output_tab_Encoder.png|100px|thumb|right|SHOUTcast Source Output Encoder Tab]]
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:

MP3 (audio/mpeg)
AAC (audio/aacp)

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.

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.

=====Save Encoded Output=====
----

This allows you to make a backup of the stream audio data sent to the DNAS server.

'''Save a copy of the encoded stream audio''' : Enables or disables saving a copy of the audio.

The extension of the output file is automatically changed based on the selected
encoder option to ensure that the file can be easily played in most media players.

====Titles Tab====
----
[[Image:Output_tab_Titles.png|100px|thumb|right|SHOUTcast Source Output Titles Tab]]
This tab allows you to specify how the stream metadata is gathered from Winamp or if it is manually entered with the options provided.

'''Disable title updates''' : This will prevent the Source DSP from sending any title updates.

'''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.

'''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.

The current version of Winamp is always recommended to use
due to the improved support for this feature since Winamp v5.61.

'''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).

The 'Send Update' button is enabled when a title is entered or it is
different from the existing title. When using SHOUTcast v2 mode the
'next' title field will become available as long as title field is not empty.

====Artwork====
----

[[Image:Output_tab_Artwork.png|100px|thumb|right|SHOUTcast Source Output Artwork in v2 mode]]
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).

'''Send in-stream artwork''' : Enables or disables sending of in-stream artwork.

If this is enabled and then disabled, it is possible that the
plug-in will send some clear artwork messages after disabling
this option to ensure there is no artwork cached by the server.

'''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.

If unchecked or there is no artwork for the playing song then the
DNAS server may be sent a clear artwork message as applicable.

This is sent as a PNG image to the SHOUTcast server.

'''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.

If left empty then the DNAS server may be sent a clear artwork message as applicable.

Using the plug-in with a connection to a legacy server will cause the following notice to be shown:

Stream is setup for a SHOUTcast v1 server
which does not support in-stream artwork.

To send in-stream artwork, uncheck the
"SHOUTcast v1 mode" option and ensure
you connect to a SHOUTcast v2 server.'

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.

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.

====Logs====
----

[[Image:Output_tab_Logs.png|100px|thumb|right|SHOUTcast Source Output Logs Tab]]
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.

The main logging options are not enabled by default though this can be used
for tracking problems with the plug-in e.g. if you are having connection issues.

'''Enable logging of connection status messages''' : Enables or disables connection logging.

'''Clear log file on logging startup''' : This will reset the log everytime the plug-in starts.

'''Open log file...''' : This will open the log file in the associated program for .log files.

'''Clear log file''' : This will clear the log file if it exists. It will not remove the file.

'''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.

'''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.

The next track logging is only updated when the plug-in detects a track
change. If the plain text / xml mode is changed or the plug-in starts then
the file contents will be cleared until the next track title change happens.

===Input Tab===
----
[[Image:Input_tab_Winamp.png|100px|thumb|right|SHOUTcast Source Input Tab in Winamp mode]]

====Input Configuration====
----

'''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.

'''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.

'''Input Settings''' : When the soundcard input is selected then this allows for control over the sample rate used on the input source.

====Soundcard Mixer Control====
----

[[Image:Input_tab_Soundcard.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.

'''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.

'''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]])).

'''Music Level''' : This controls the Winamp output level (from no audio to full audio level).

'''BG Level''' : This controls the Winamp output level when the 'Push to Talk' option is active (from no audio to full audio level).

'''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).

'''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).

'''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).

'''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.

'''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.

'''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.

===About Tab===
----

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.

====Documentation and Support====
----

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.

The documentation is either the current version as shipped with the plug-in if selected during install (stored in '''<winampdir>\Plugins\SHOUTcast Source DSP''').

The support forums is accessed via http://forums.shoutcast.com/forumdisplay.php?f=140

Additional documentation is available here: '''[[Source_DSP_Plug-in_Configuration_Examples|SHOUTcast Source DSP Plug-in Configuration Examples]]'''

==Known Issues==

The following are currently known issue(s) to affect the currently released build of the Source DSP plug-in:

===Soundcard Mixer Control===
----

'''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.

'''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.

'''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.

==SHOUTcast 2 Cipher Key==

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:

Authentication Error:
Cipher Does Not Match

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.

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).

==Example Configurations==

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.

For 3rd party servers or broadcast tools, you may need to consult their documentation to determine from where you get the required configuration values.

SHOUTcast News

2022-07-22T19:44:37Z

Djegg: 2.6.1

{{Template:NavBarSC}}

'''Free Download: New Shoutcast version 2.6.1'''

Shoutcast, the largest streaming audio software platform and worldwide radio station directory has released an update to its industry-standard streaming software.

The new Shoutcast Suite of Streaming Products includes free streaming, powerful revenue generating tools, and the latest version adds:
* SSL support
* Improved scalability (up to 12,000 unique listeners supported)
* Improved ad support and revenue tracking
* Powerful analytics
* Even better stability for reliable streaming 24/7
* Improved processor management saves energy
* Better memory usage for stations with big audiences
* [https://yp.shoutcast.com/v/2_6_1 Full 2.6.1 changelog]
* [http://forums.winamp.com/showthread.php?t=453775 Info about v2.6.1 changes]

'''Effortless Upgrade'''

Broadcasters who run their own servers should download the updated version of the DNAS for free via the [https://radiomanager.shoutcast.com/RMO/user/your-plan/your-plan Shoutcast RMO]

Stations using a CDN (hosting service) should ask their provider to make sure their server gets updated to at least [http://forums.shoutcast.com/showthread.php?t=451412 Shoutcast version 2.5.5] (v2.6.1 recommended)

'''Technical Details'''

Read more on the [http://forums.shoutcast.com/showthread.php?t=453775 Shoutcast Forum]

SHOUTcast

2022-07-22T19:39:31Z

Djegg: /* Shoutcast releases version 2.6! */

{{Template:NavBarSC}}

== Shoutcast releases version 2.6.1 ==

'''[[SHOUTcast_News | Latest Shoutcast News]]''' - The latest developments from the leader in streaming audio.

== Shoutcast Offers a Full Suite of Streaming Products ==

Shoutcast has you covered when it comes to broadcasting audio online.

- '''Shoutcast.com''' [http://www.shoutcast.com] - the hugely popular online directory of radio stations (sometimes called the YP - Yellow Pages - for online radio).

- [[SHOUTcast Broadcaster|'''Shoutcast Server (DNAS)''']] - The most popular online streaming server software on the planet, used by over 50,000 broadcasters.

- [[Source_DSP_Plug-in|'''Shoutcast DSP''']] - The Shoutcast DSP is an encoder plug-in for Winamp which encodes your audio and sends it to a streaming server such as the Shoutcast DNAS.

- [[SHOUTcast Streaming Service|'''Shoutcast For Business & Revenue Generation''']] - Our hosting solution allows broadcasters to stream and/or generate revenue from their listeners with audio ads.

- [[SHOUTcast_Developer|'''The Shoutcast API''']] offers developers the chance to integrate thousands of stations into their apps and products for free.

SHOUTcast

2022-07-22T19:38:34Z

Djegg: /* Shoutcast Offers a Full Suite of Streaming Products */

{{Template:NavBarSC}}

== Shoutcast releases version 2.6! ==

'''[[SHOUTcast_News | Latest Shoutcast News]]''' - The latest developments from the leader in streaming audio.

== Shoutcast Offers a Full Suite of Streaming Products ==

Shoutcast has you covered when it comes to broadcasting audio online.

- '''Shoutcast.com''' [http://www.shoutcast.com] - the hugely popular online directory of radio stations (sometimes called the YP - Yellow Pages - for online radio).

- [[SHOUTcast Broadcaster|'''Shoutcast Server (DNAS)''']] - The most popular online streaming server software on the planet, used by over 50,000 broadcasters.

- [[Source_DSP_Plug-in|'''Shoutcast DSP''']] - The Shoutcast DSP is an encoder plug-in for Winamp which encodes your audio and sends it to a streaming server such as the Shoutcast DNAS.

- [[SHOUTcast Streaming Service|'''Shoutcast For Business & Revenue Generation''']] - Our hosting solution allows broadcasters to stream and/or generate revenue from their listeners with audio ads.

- [[SHOUTcast_Developer|'''The Shoutcast API''']] offers developers the chance to integrate thousands of stations into their apps and products for free.

SHOUTcast DNAS Server 2

2022-02-04T13:15:28Z

Djegg: /* Stream Configuration */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

portbase_1=8080
portbase_2=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

portbase=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6.1 feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=/live
or
streamid_1=1
streampath_1=/random_mountpoint
streamid_2=2
streampath_2=/another_mountpoint

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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 server's stream address support.

Note: streampath is the mountpoint, e.g. streampath_1=/mystation would result in ip:port/mystation
Do NOT specify a streamurl as streampath as this will result in an error.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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 known streams.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6.1 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

Note: SSL Support is for Linux-only, not Windows.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2022-02-04T12:27:39Z

Djegg: /* Stream Configuration */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

portbase_1=8080
portbase_2=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

portbase=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6.1 feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=/live
or
streamid_1=1
streampath_1=/random_mountpoint
streamid_2=2
streampath_2=/another_mountpoint

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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 server's stream address support.

Note: streampath is the mountpoint, e.g. streampath_1=/mystation would result in ip:port/mystation
Do NOT specify a streamurl as streampath as this will result in an error.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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 known streams.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6.1 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

Note: SSL Support is a Linux-only feature. It will not work on Windows.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2022-02-01T13:51:23Z

Djegg: /* Stream Configuration */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

portbase_1=8080
portbase_2=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

portbase=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6.1 feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=/live
or
streamid_1=1
streampath_1=/random_mountpoint
streamid_2=2
streampath_2=/another_mountpoint

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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 server's stream address support.

Note: streampath is the mountpoint, e.g. streampath_1=/mystation would result in ip:port/mystation
Do NOT specify a streamurl as streampath as this will result in an error.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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 known streams.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6.1 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2022-02-01T13:49:28Z

Djegg: /* Introduction and Backup Files */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

portbase_1=8080
portbase_2=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

portbase=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6.1 feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=/live
or
streamid_1=1
streampath_1=/random_mountpoint
streamid_2=2
streampath_2=/another_mountpoint

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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 server's stream address support.

Note: streampath is the mountpoint, e.g. streampath_1=/mystation would result in ip:port/mystation
Do NOT specify a streamurl as streampath as this will result in an error.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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 known streams.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast Radio Authhash API

2021-11-29T16:31:42Z

Djegg: /* Update Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

The API works for generating and editing a 20 character v2.x authhash for DNAS v2.5.5 and earlier.
It will not work for editing the 32 character GUID-style authhash used in DNAS v2.6, although v2.6.0.753 does now accept a v2.5x authhash.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents, e.g. & = %26)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* logo - full url of jpg or png station logo. Previously used for Radionomy listings (limited to 2mb or 800x800 px).
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* logo - full url of jpg or png station logo. Previously used for Radionomy listings (limited to 2mb or 800x800 px).
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genres recognised

* '''secondarygenre?primarygenre=<genre>''' - provides a html select control of the secondary genres related to the primary genre passed or an empty response if there are no genres found

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2021-11-29T16:31:22Z

Djegg: /* Create Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

The API works for generating and editing a 20 character v2.x authhash for DNAS v2.5.5 and earlier.
It will not work for editing the 32 character GUID-style authhash used in DNAS v2.6, although v2.6.0.753 does now accept a v2.5x authhash.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents, e.g. & = %26)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* logo - full url of jpg or png station logo. Previously used for Radionomy listings (limited to 2mb or 800x800 px).
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* logo - full url of jpg or png station logo (limited to 2mb or 800x800 px). Previously used for Radionomy listings.
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genres recognised

* '''secondarygenre?primarygenre=<genre>''' - provides a html select control of the secondary genres related to the primary genre passed or an empty response if there are no genres found

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2021-11-29T16:25:44Z

Djegg: /* Update Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

The API works for generating and editing a 20 character v2.x authhash for DNAS v2.5.5 and earlier.
It will not work for editing the 32 character GUID-style authhash used in DNAS v2.6, although v2.6.0.753 does now accept a v2.5x authhash.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents, e.g. & = %26)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* logo - full url of jpg or png station logo (limited to 2mb or 800x800 px). Previously used for Radionomy listings.
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genres recognised

* '''secondarygenre?primarygenre=<genre>''' - provides a html select control of the secondary genres related to the primary genre passed or an empty response if there are no genres found

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2021-11-29T16:25:26Z

Djegg: /* Update Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

The API works for generating and editing a 20 character v2.x authhash for DNAS v2.5.5 and earlier.
It will not work for editing the 32 character GUID-style authhash used in DNAS v2.6, although v2.6.0.753 does now accept a v2.5x authhash.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents, e.g. & = %26)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* logo - full url of jpeg or png station logo (limited to 2mb or 800x800 px). Previously used for Radionomy listings.
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genres recognised

* '''secondarygenre?primarygenre=<genre>''' - provides a html select control of the secondary genres related to the primary genre passed or an empty response if there are no genres found

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Developer

2021-11-29T13:39:17Z

Djegg: Fixed old link

{{Template:NavBarSC}}

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.

::'''[[SHOUTcast_API_License_Agreement|Shoutcast API Usage Restrictions and Logos]]'''

::'''[https://www.shoutcast.com/Partners API Partner Applications (How and Where to Request a DevID Key)]'''

::'''[[SHOUTcast_Radio_Directory_API|Shoutcast Radio Directory Partner API Documentation]]''' - Reference for accessing information from the Radio Directory

::'''[[SHOUTcast_Radio_Authhash_API|Shoutcast Radio Authhash Partner API Documentation]]''' - Reference for accessing the Shoutcast 2 Authhash Management API

::'''[[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

::'''[[SHOUTcast_XML_Metadata_Specification|Shoutcast XML Metadata Specification]]'''

SHOUTcast API License Agreement

2020-06-06T10:57:50Z

Djegg:

{{Template:NavBarSC}}

'''Shoutcast API Usage Restrictions'''
 
By using our API, you agree to the following restrictions which are in place to protect the SHOUTcast brand and ServiceMark.

* Please do not hammer the servers. We request reasonable usage and recommend that you utilize local caching.

* Do not copy the shoutcast.com design, make your design as original as possible.

* We reserve the right to revoke access for DevIDs which abuse the system.

* We have included official logos for your usage below (with more to follow later).

'''API License Terms''' 
[https://shoutcast.com/Legal/LicenseAPI https://shoutcast.com/Legal/LicenseAPI]

'''Shoutcast Logos'''
 
Here are the Shoutcast logos which can be used according to the above guidelines

[[File:shoutcast.png|thumb|left|alt=Shoutcast Logo 1]]

[[File:Logo_shoutcast.png|thumb|left|alt=Shoutcast Logo 2]]

SHOUTcast API License Agreement

2020-06-06T10:57:23Z

Djegg:

{{Template:NavBarSC}}

'''SHOUTcast API Usage Restrictions'''
 
By using our API, you agree to the following restrictions which are in place to protect the SHOUTcast brand and ServiceMark.

* Please do not hammer the servers. We request reasonable usage and recommend that you utilize local caching.

* Do not copy the shoutcast.com design, make your design as original as possible.

* We reserve the right to revoke access for DevIDs which abuse the system.

* We have included official logos for your usage below (with more to follow later).

'''API License Terms''' 
[https://shoutcast.com/Legal/LicenseAPI https://shoutcast.com/Legal/LicenseAPI]

'''SHOUTcast Logos'''
 
Here are the Shoutcast logos which can be used according to the above guidelines

[[File:shoutcast.png|thumb|left|alt=Shoutcast Logo 1]]

[[File:Logo_shoutcast.png|thumb|left|alt=Shoutcast Logo 2]]

SHOUTcast Radio Authhash API

2020-05-27T12:14:11Z

Djegg: /* Supported Genres */

{{Template:NavBarSC}}

==Introduction==

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).

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.

The API works for generating and editing a 20 character v2.x authhash for DNAS v2.5.5 and earlier.
It will not work for editing the 32 character GUID-style authhash used in DNAS v2.6, although v2.6.0.753 does now accept a v2.5x authhash.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents, e.g. & = %26)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genres recognised

* '''secondarygenre?primarygenre=<genre>''' - provides a html select control of the secondary genres related to the primary genre passed or an empty response if there are no genres found

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-05-27T12:13:20Z

Djegg: /* Additional Resources */

{{Template:NavBarSC}}

==Introduction==

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).

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.

The API works for generating and editing a 20 character v2.x authhash for DNAS v2.5.5 and earlier.
It will not work for editing the 32 character GUID-style authhash used in DNAS v2.6, although v2.6.0.753 does now accept a v2.5x authhash.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents, e.g. & = %26)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genres recognised

* '''secondarygenre?primarygenre=<genre>''' - provides a html select control of the secondary genres related to the primary genre passed or an empty response if there are no genres found

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-05-27T12:12:23Z

Djegg: /* Additional Resources */

{{Template:NavBarSC}}

==Introduction==

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).

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.

The API works for generating and editing a 20 character v2.x authhash for DNAS v2.5.5 and earlier.
It will not work for editing the 32 character GUID-style authhash used in DNAS v2.6, although v2.6.0.753 does now accept a v2.5x authhash.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents, e.g. & = %26)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genres recognised

* '''secondarygenre?primarygenre=<genre>''' - provides a html select control of the secondary genres related to the primary genre passed or an empty response if there is no genres found

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-05-26T14:05:56Z

Djegg: /* Create Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

The API works for generating and editing a 20 character v2.x authhash for DNAS v2.5.5 and earlier.
It will not work for editing the 32 character GUID-style authhash used in DNAS v2.6, although v2.6.0.753 does now accept a v2.5x authhash.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents, e.g. & = %26)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-04-25T15:29:16Z

Djegg: /* Introduction */

{{Template:NavBarSC}}

==Introduction==

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).

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.

The API works for generating and editing a 20 character v2.x authhash for DNAS v2.5.5 and earlier.
It will not work for editing the 32 character GUID-style authhash used in DNAS v2.6, although v2.6.0.753 does now accept a v2.5x authhash.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-04-24T12:23:33Z

Djegg: /* Update Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-04-24T12:21:43Z

Djegg: /* Check Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will return all values for an existing authorisation key.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* private - determine if the primary server should be public (0 - default) or not (1)

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-04-24T12:17:22Z

Djegg: /* Create Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key (authhash) and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* private - determine if the primary server should be public (0 - default) or not (1)

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-04-24T12:01:28Z

Djegg: /* Create Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters (replace non-latin/non-alphanumeric characters with [https://www.degraeve.com/reference/urlencoding.php url-encoded] equivalents)
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* private - determine if the primary server should be public (0 - default) or not (1)

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-04-24T11:58:12Z

Djegg: /* Create Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* email - contact address for the station up to 255 characters (preferably use Shoutcast RadioManager email, if account exists, though any will suffice)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* private - determine if the primary server should be public (0 - default) or not (1)

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-04-24T11:56:15Z

Djegg: /* Create Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Rock&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* private - determine if the primary server should be public (0 - default) or not (1)

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-04-24T11:55:40Z

Djegg: /* Create Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Misc&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* private - determine if the primary server should be public (0 - default) or not (1)

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast Radio Authhash API

2020-04-24T11:55:23Z

Djegg: /* Create Authorisation Key */

{{Template:NavBarSC}}

==Introduction==

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).

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.

==API Overview==

There are four core parts of the authorisation key APIs (usage details are in [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|Remove]]

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.

The API methods are called by passing parameters to the required YP site url.

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.

===Successful Response===
----

If there are no issues with the API method call then one of the following responses will be received as the response generated.

The first response is the '''basic''' success response and is provided if there is no extra information to be returned by the API method:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

If there are issues experienced during the API method call then an error response will be received which takes the following form:

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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.

See [[#Status_Codes|section 5]] for the status codes and messages returned when using the API methods.

==API Usage==

The following sections detail how to use the four authorisation key API methods.

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.

===Create Authorisation Key===
----

This will create an authorisation key and will return it in the xml response on success.

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.

'''URL:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Misc&[Optional Parameters To Set]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
& genre2 genre3 genre4 genre5 - specify up to 4 additional genres
* private - determine if the primary server should be public (0 - default) or not (1)
* admode - determine whether monetization support is enabled for DNAS v2.4.7 and later (0=off, 1=on)
* callsign - the GUID of station if registered in the Shoutcast RadioManager

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''full''' success response containing the new authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to check

'''Response:'''

Returns a '''full''' success response containing the found details of the authorisation key or the standard error response.

'''Example Response'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationname>The Station Name</stationname>
<genre>Misc</genre>
<website>www.shoutcast.com</website>
<description>The Best Station Ever...!</description>
<langid>EN</langid>
<countryiso>US</countryiso>
<stateiso>00</stateiso>
<city></city>
<keywords>Greatest Web Station</keywords>
<private>0</private>
</data>
</response>
</source>

The <stateiso> element will only be returned if the <countryiso> element is 'US'.

===Update Authorisation Key===
----

This will update an authorisation key as long as it was created by the Developer ID used.

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.

'''URL:''' <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>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to update
* stationname - name of the station as listed in the YP listings up to 100 characters
* 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)
* 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)

'''Recommended Optional Parameters:'''
''(These are marked as optional but are likely to be made required in a future update)''

* langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
* countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

'''Optional Parameters:'''

* website - related url for station up to 128 characters
* description - brief description about the station up to 65535 characters
* stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
* city - more specific place where the stream is based or related up to 128 characters
* keywords - separated tag words about the stream up to 120 characters
* private - determine if the primary server should be public (0 - default) or not (1)

It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

'''Response:'''

Returns a '''basic''' success response or the standard error response.

===Remove Authorisation Key===
----

This will remove an authorisation key as long as it was created by the Developer ID used.

'''URL:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''Required Parameters:'''

* k - Developer ID for accessing the API
* authhash - Authorisation Key to remove

'''Response:'''

Returns a '''basic''' success response or the standard error response.

==Additional Resources==

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.

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:

* '''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

* '''languages''' - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control

* '''states''' - provides provides a html select control containing the USPO state code and a displayable string for each option in the control

* '''primarygenre''' - provides a html select control of the primary genre's recognised

* '''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

* '''parentgenre?genre=<genre>''' - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre

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
<div> element for example with an interface used to control the APIs.

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.

===User Interface Versions===
----

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.

===Supported Genres===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Primary Genre
!Associated Secondary Genres
|-
| 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
|-
| Blues || Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
|-
| Classical || Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
|-
| Country || Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
|-
| Decades || 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
|-
| Easy Listening || Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
|-
| 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
|-
| Folk || Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
|-
| Inspirational || Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
|-
| 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
|-
| Jazz || Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
|-
| 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
|-
| Metal || Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
|-
| Misc ||
|-
| New Age || Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
|-
| Pop || Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
|-
| Public Radio || College, News, Sports, Talk, Weather
|-
| R&B and Urban ||
|-
| Rap || Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
|-
| Reggae || Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
|-
| 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
|-
| Seasonal and Holiday || Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
|-
| Soundtracks || Anime, Kids, Original Score, Showtunes, Video Game Music
|-
| Talk || BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
|-
| 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
|}

===Illegal Input Values===
----

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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 127.0.0.1 || admin || auto dj || auto jedi
|-
| auto pj || auto-dj || autodj || autopj
|-
| demo || dj || internet radio || live
|-
| local server || localhost || localserver || music
|-
| my radio || my server || my station name || my test server
|-
| n/a || pj || playlist || radio
|-
| radio station || test || test server || unnamed server
|-
| virtual dj || virtualdj || web rdio || web radio
|-
| song || teste || default stream || radio stream
|}

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]]).

==Status Codes==

The following status codes are returned on success or error when using the provided APIs:

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!Code
!Status Text
!Detailed Text (if available)
|-
| 200 || Ok || n/a
|-
| 400 || Generic Error || n/a
|-
| 404 || Page Not Found || n/a
|-
| 440 || Invalid devId || Invalid parameter k
|-
| 456 || Parameter value not allowed || ''<variable>=<value>'' not allowed
|-
| 458 || Building internal value failure || n/a
|-
| 459 || Authhash could not be found for reading || Authhash does not exist or was not created by this 'devID'
|-
| 460 || Missing required parameter || Missing ''<variable>''
|-
| 461 || Error while updating authhash || n/a
|-
| 462 || Parameter error || Invalid parameter <variable>
|-
| 463 || Invalid station result returned || n/a
|-
| 464 || Authhash could not be found or removed || Authhash does not exist or was not created by this 'devID'
|-
| 465 || Required parameter missing for registration || ''<variable>'' is a required parameter
|-
| 466 || Parameter outside of allowed range || ''<variable>'' parameter too long
|-
| 467 || Parameter value not recognized in stored values || ''<variable>'' value not recognized
|-
| 468 || Error creating intended xml response || n/a
|-
| 469 || Authhash could not be updated as not found || Authhash does not exist or was not created by this 'devID'
|-
| 470 || Invalid authorization hash || n/a
|-
| 500 || Generic Server Error || n/a
|}

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.

SHOUTcast DNAS Server 2

2020-03-12T12:45:08Z

Djegg: /* Stream Configuration */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

portbase_1=8080
portbase_2=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

portbase=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6 Premium feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=/live
or
streamid_1=1
streampath_1=/random_mountpoint
streamid_2=2
streampath_2=/another_mountpoint

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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 server's stream address support.

Note: streampath is the mountpoint, e.g. streampath_1=/mystation would result in ip:port/mystation
Do NOT specify a streamurl as streampath as this will result in an error.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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 known streams.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2020-03-12T12:31:37Z

Djegg: /* Stream Configuration */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

portbase_1=8080
portbase_2=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

portbase=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6 Premium feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=/live
or
streamid_1=1
streampath_1=/random_mountpoint
streamid_2=2
streampath_2=/another_mountpoint

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.
streampath is the mountpoint, e.g. streampath_1=/mystation would result in ip:port/mystation

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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
server's stream address support.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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 known streams.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2020-03-12T12:28:26Z

Djegg: /* Configuration File */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

portbase_1=8080
portbase_2=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

portbase=8080
destip_1=stream.server1.com
destip_2=stream.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6 Premium feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=random
or
streamid_1=1
streampath_1=random_stream_path
streamid_2=2
streampath_2=another_stream_path

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.
streampath is the mountpoint, e.g. streampath_1=mystation would result in ip:port/mystation

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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
server's stream address support.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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 known streams.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2020-03-12T12:25:41Z

Djegg: /* Configuration File */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

portbase_1=8080
portbase_2=8080
destip_1=www.server1.com
destip_2=www.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

portbase=8080
destip_1=www.server1.com
destip_2=www.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6 Premium feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=random
or
streamid_1=1
streampath_1=random_stream_path
streamid_2=2
streampath_2=another_stream_path

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.
streampath is the mountpoint, e.g. streampath_1=mystation would result in ip:port/mystation

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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
server's stream address support.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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 known streams.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2020-01-28T16:16:23Z

Djegg: /* Stream Configuration */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

serverport_1=8080
serverport_2=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

serverport=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6 Premium feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=random
or
streamid_1=1
streampath_1=random_stream_path
streamid_2=2
streampath_2=another_stream_path

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.
streampath is the mountpoint, e.g. streampath_1=mystation would result in ip:port/mystation

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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
server's stream address support.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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 known streams.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2019-10-29T02:25:16Z

Djegg: /* Stream Configuration */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

serverport_1=8080
serverport_2=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

serverport=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6 Premium feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=random
or
streamid_1=1
streampath_1=random_stream_path
streamid_2=2
streampath_2=another_stream_path

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.
streampath is the mountpoint, e.g. streampath_1=mystation would result in ip:port/mystation

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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
server's stream address support.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and/or publicip= and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2019-10-21T02:43:27Z

Djegg: /* Client Behaviour */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

serverport_1=8080
serverport_2=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

serverport=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6 Premium feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=random
or
streamid_1=1
streampath_1=random_stream_path
streamid_2=2
streampath_2=another_stream_path

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.
streampath is the mountpoint, e.g. streampath_1=mystation would result in ip:port/mystation

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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
server's stream address support.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2019-10-21T02:43:03Z

Djegg: /* Client Behaviour */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

serverport_1=8080
serverport_2=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

serverport=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''
''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6 Premium feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=random
or
streamid_1=1
streampath_1=random_stream_path
streamid_2=2
streampath_2=another_stream_path

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.
streampath is the mountpoint, e.g. streampath_1=mystation would result in ip:port/mystation

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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
server's stream address support.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.

SHOUTcast DNAS Server 2

2019-10-21T02:42:31Z

Djegg: /* Client Behaviour */

{{Template:NavBarSC}}

==Introduction==

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.

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:

# Serving multiple streams from a single server instance
# Relaying multiple streams from a single server instance
# Multiplexing all server activity through a single IP port
# SHOUTcast 2 wire protocol support for sources, relays and clients
# Repackaging of SHOUTcast 1 and SHOUTcast 2 data as needed for connected clients
# YP2 infrastructure support
# Real-time metadata and statistic reporting
# Static station id support
# In-stream metadata in standardised xml files
# UTF-8 and international character encoding
# Improved server and stream security

==Overview of Features==

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]]).

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.

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.

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).

==Getting Started==

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.

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.

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.

===Running the Server===
----

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.

===Windows===
----

The Windows version of sc_serv is designed to run on fully updated and patched versions of Windows 2000, XP, Vista and Windows 7, 8 & 10.

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:

32-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2

64-bit version:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ba9257ca-337f-4b40-8c14-157cfdffee4e

====Install as a Service====
----

sc_serv.exe install <servicename> <username> <password> <conf>

<servicename> - Name of service
Typically enter this as 'sc_serv' though you can use a different name but you will need
to remember it as it is required to be the same when using the 'uninstall' mode.

<username> - User under which to run the service as or '0' for the local system

<password> - Password for user or '0' for the local system or with no password

<conf> - File path to the configuration file
If no file / an invalid file is specified then sc_serv will abort loading.

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.

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:

sc_serv.exe install sc_serv 0 0 sc_serv.conf

====Uninstall the Service====
----

sc_serv.exe uninstall <servicename>

<servicename> - Name of service as used when the service was registered

To uninstall sc_serv assuming it was installed as detailed in the install section above then you would enter into the console:

sc_serv.exe uninstall sc_serv

====Run as a Non-Service in the Console====
----

sc_serv.exe <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Linux / Mac OS X / BSD===
----

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'.

====Run as a Daemon====
----

./sc_serv daemon <conf>

<conf> - File path to the configuration file (required in all cases)
If no file / an invalid file is specified then sc_serv will abort loading.

'''e.g.'''
./sc_serv daemon ./sc_serv.conf

When run this should output the following:

'sc_serv going daemon with PID [XXXX]' where XXXX is the <pid> of the process.

====End a Daemon====
----

kill -SIGTERM <pid>
or
kill -15 <pid>
or
kill -s TERM <pid>

<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.

====Run as a Non-Daemon====
----

./sc_serv <conf>

<conf> - File path to the configuration file (can be relative or absolute)
If no file / an invalid file is specified then sc_serv will abort loading.

===Additional Signals===
----

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.

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:

SIGKILL - Stops sc_trans (also SIGTERM, SIGINT and SIGQUIT will work)
SIGHUP - Rotates logfile, w3clog and streamw3clog

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.

These signals are not supported by the Windows version of sc_serv which will only
respond to the Ctrl + C / Ctrl + Break / console close commands the OS provides.

==Configuration File==

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.

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.

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:

serverport_1=8080
serverport_2=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

Note that you CANNOT do it like this as it leads to not all values being set:

serverport=8080
serverip_1=www.server1.com
serverip_2=www.server2.com

The configuration files also allow for comments/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.

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.

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:

<date + time> W msg:[CONFIG] Invalid item on line XX

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.

===Banning===
----

'''banfile''' : File to store the list of banned IP addresses ''[Default = sc_serv.ban]''

'''savebanlistonexit''' : Re-write the 'banfile' on server exit ''[Default = 1]''

If you are using a folder for saving the file into then you need to ensure that the
folder already exists as sc_serv will not attempt to the create the folder for you.

===Client Behaviour===
----

'''maxuser''' : Specify the maximum number of clients allowed to connect to the server ''[Default = 32]''
This is used in conjunction with 'streammaxuser' (see [[#Stream_Configuration|section 4.12]]) to control the
maximum limit on the number of client connections allowed to connect to the server instance.

'''listenertime''' : Specify the maximum time in minutes a client can listen to the stream ''[Default = 0]''
A value of zero means there will be no time limit.

'''autodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects ''[Default = 0]''

'''srcip''' : Specify the server side binding address for sources to connect on ''[Default = <no value>]''

'''dstip''' or '''destip''' or '''publicip''' : Specify the server side binding address for clients ''[Default = <no value>]''
If 'any' or no value is specified then sc_serv listens to all addresses.

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>

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.

'''titleformat''' : Specify a string to be used in-place of the default icy-name string being used ''[Default = <no value>]''

'''urlformat''' : Specify a string to be used in-place of the default icy-url string being used ''[Default = <no value>]''

''' '''

===Debugging===
----

In all cases, the default value is for no debug logging for the options listed below.

'''yp1debug''' : Enable debug logging of YP connections

'''yp2debug''' : Enable debug logging of YP2 connections

'''shoutcastsourcedebug''' : Enable debug logging of SHOUTcast source connections

'''uvox2sourcedebug''' : Enable debug logging of SHOUTcast 2 source connections

'''shoutcast1clientdebug''' : Enable debug logging of SHOUTcast streaming clients

'''shoutcast2clientdebug''' : Enable debug logging of SHOUTcast 2 streaming clients

'''relayshoutcastdebug''' : Enable debug logging for SHOUTcast relays

'''relayuvoxdebug''' : Enable debug logging for SHOUTcast 2 relays

'''relaydebug''' : Enable debug logging of common relay code

'''streamdatadebug''' : Enable debug logging of common streaming code

'''httpstyledebug''' : Enable debug logging of http style requests

'''statsdebug''' : Enable debug logging of statistics

'''microserverdebug''' : Enable debug logging of common server activity

'''threadrunnerdebug''' : Enable debug logging of the thread manager

'''rtmpclientdebug''' : Enable debug logging of rtmp clients

'''admetricsdebug''' : Enable debug logging of ad metrics (v2.5 and newer)

''' '''
''' '''

===Flash Security===
----

'''flashpolicyfile''' : Name of file containing flash crossdomain policies on the server ''[Default = crossdomain.xml]''

===Introduction and Backup Files===
----

Note that intro and backup audio files must precisely match the format and bitrate for the stream! If they do not match, there will be a break in the stream and the listener will be disconnected.

'''introfile''' : File to play when a client first connects to the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific intro file to a stream, use streamintrofile_X.

'''streamintrofile_X''' : File to play when a client first connects to the server ''[Default = <no value>]''

'''backupfile''' : File to play if the source disconnects from the server ''[Default = <no value>]''
Note: This is used globally and also is default for stream #1 on DNAS versions greater than 2.0. To apply a specific backup file to a stream, use streambackupfile_X.

'''streambackupfile_X''' : assigns a specific backup file to a streamID X [Default = <no value>]''

'''streambackupurl_X''' : assigns a specific backup stream to a streamID X (v2.6 Premium feature)''

'''specialfiletmpdir''' : place to store intro and backup files uploaded by sc_trans ''[Default = /tmp/ (*nix only)]''

'''maxspecialfilesize''' : Change the maximum size in bytes of the backup and intro files ''[Default = 30000000]''
 

===Logging===
----

'''log''' : Enable logging of the servers output ''[Default = 1]''

'''screenlog''' : Enable logging of servers output to the console ''[Default = 1]''
If log=0 then this option is ignored due to no logging happening.

'''logfile''' : Specify a different logfile to save the logs into ''[Default = %temp%\sc_serv.log or /tmp/sc_serv.log]''

'''logclients''' : Enable logging of details about client connections and disconnections made ''[Default = 1]''

If you are using a folder for saving the logs into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Miscellaneous===
----

'''configrewrite''' : Re-write the 'config file' on server exit ''[Default = 0]''

'''songhistory''' : Specify the maximum song history to preserve ''[Default = 10]''

'''cpucount''' : Specify the number of cpu's present instead of the calculated number if non-zero ''[Default = 0]''

'''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'''

So when 'unique' is changed from '$' to say 'test' then the following happens if 'logfile' is
set to '/usr/local/shoutcast/$.log' then this would be converted to '/usr/local/shoutcast/test.log'

'''include''' : Specify an additional include file containing settings to be processed from the current point in the main configuration file ''[Default = <no value>]''

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.

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.

'''admincssfile''' : Specify the css styling to be used on the index.html and admin pages ''[Default = v2]''

This can accept the following parameters:

:admincssfile='''v1''' - Uses the v1 DNAS style
:admincssfile='''v2''' - Uses the newer SHOUTcast 2 style
:admincssfile='''path_to_local_css_file''' e.g. my_index.css</nowiki>

If using a custom css file, if it does not exist on the first try to load it the server will revert to
the default css style. As well the style is cached once loaded so changes require a restart of sc_serv.

'''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>]''

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.

'''faviconmimetype''' : Specify the mime type for actual file to be served in the favicon.ico response ''[Default = image/x-icon]''

Ensure this is correct for the type of image being used so it is valid.

'''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]''

'''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>]''

The default behaviour is to return a robots.txt reponse indicating not to look at any of the server's pages i.e.
::User-agent:*
::Disallow:/

===Networking===
----

'''namelookups''' : Enable to allow reverse DNS look-ups on incoming IP addresses ''[Default = 0]''

'''portbase''' : Specify the port which clients and sources need to use to connect to the server ''[Default = 8000]''
SHOUTcast 1 sources are only able to connect to 'portbase + 1'.

'''autodumpsourcetime''' : Specify how long before an idle source is dumped from the server (in seconds) ''[Default: 30]''
A value of zero means there is no timeout of an idle source.
Also if you set this too low then it is likely that valid sources will
fail to connect during the initial stages of a source connection.

'''maxheaderlinesize''' : Specify the maximum size of an HTTP header line ''[Default = 2048]''

'''maxheaderlinecount''' : Specify the maximum header lines in an HTTP style exchange ''[Default = 100]''

'''adminpassword''' : Specify the administrator password for accessing the remote server features ''[Default = <no value>]''

'''password''' : Specify the password for broadcasters when connecting to the server ''[Default = <no value>]''
This matches the 'uvoxauth' value in the sc_trans configuration file (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

===Network Buffers===
----

'''buffertype''' : Specify whether the buffer size is fixed [0] or adaptive [1] ''[Default = 0]''

'''adaptivebuffersize''' : Specify the buffer size in seconds if buffer is set to adaptive ''[Default = 1]''

'''fixedbuffersize''' : Specify the buffer size in bytes if the buffer is set to fixed ''[Default = 1048576]''

'''bufferhardlimit''' : Specify the maximum buffer size in bytes which it can never go above ''[Default = 16777216]''

===Relaying===
----

'''allowrelay''' : Enable to allow a relay to connect to the server ''[Default = 1]''

'''allowpublicrelay''' : Enable to allow relays to list themselves in the YP directory ''[Default = 1]''

'''relayreconnecttime''' : Specify how many seconds to wait to reconnect on a relay failure ''[Default = 30]''
Setting this to 0 will disable attempts for the relay to reconnect.

'''relayconnectretries''' : Specify the number of times relays are attempted to be connected to if it is initially unable to connect ''[Default = 3]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''maxhttpredirects''' : Specify the maximum number of times we can redirect when relaying ''[Default = 5]''

''<Legacy Options>''

'''relayport''' : Port of the source to use for the relay ''[Default: 80]''

'''relayserver''' : Url of the source to relay ''[Default = <no value>]''

Using the stream configuration options (see [[#Stream_Configuration|section 4.12]]) is the preferred method
of setting up a relay. These options are only provided as a means for loading
legacy configuration files. If found then these are mapped to 'streamrelayurl_1'.

===Reserved List===
----

'''ripfile''' : File to store the list of reserved IP addresses ''[Default = sc_serv.rip]''

'''saveriplistonexist''' : Re-write the 'ripfile' on server exit ''[Default = 1]''

'''riponly''' : Only allow connections to be made from reserved IP addresses ''[Default = 0]''

If you are using a folder for saving the file into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

===Stream Configuration===
----

'''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.

'''requirestreamconfigs''' : Only allow sources to connect if a stream configuration has been set in your configuration file ''[Default = 0]''
With this enabled, you will need to ensure that any sources have their configuration details
setup to match those in sc_trans's configuration, in particular the 'uvoxstreamid' value with
sc_trans (see [[SHOUTcast_DNAS_Transcoder_2#Network_Options|sc_trans.txt - section 3.11]]).

''<MULTI>'' (one set for each stream configuration):

'''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.

If you use multiple stream configurations then you will need to ensure the _X
part is specified and correct for each stream configuration group
e.g.
streamid=1
streampath=random
or
streamid_1=1
streampath_1=random_stream_path
streamid_2=2
streampath_2=another_stream_path

'''streamauthhash''' : The authorisation key needed for YP2 directory registration.
This is a requirement for using the YP2 system and without it you will not be able to
successfully connect to the YP2 directory (see [[#Getting_Started|section 3.0]]).

This can be used for multiple streams you are providing or can be different (as long
as valid) so you can infact provide multiple stations from the same server if desired.

'''streampath''' : Specify the path clients need to use to access the stream
If a / is not specified on the start of the string then the server will add
it to the generated path in playlist entries or other places as required so
<nowiki>http://<serverurl>/<streampath></nowiki> will work so clients are able to connect.
streampath is the mountpoint, e.g. streampath_1=mystation would result in ip:port/mystation

If this is not specified then <nowiki>http://<serverurl>/stream/<streamid>/</nowiki> will be
used for client access and in generated playlist entries so that it will
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
server's stream address support.

'''streamrelayurl''' : Specify the full url of source to relay (if this is a relay).
Make sure if you use this that the full url is entered and that it is
the url which clients would connect to for the stream to be relayed.

'''streammaxuser''' : Specify the maximum number of clients allowed to connect to the stream ''[Default = 0]''
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.

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.'''
streammaxuser_1 = 8
maxuser = 32

This allows a total of 32 connections to the server but specifies the maximum number of connections to the first stream configuration is 8.

With the following stream configuration
streammaxuser_1 = 64
maxuser = 32

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.

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.

'''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.

'''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.
This matches the 'uvoxauth' value in the sc_trans configuration file (see sc_trans.txt - section 3.11).

'''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.

'''streamallowrelay''' : Enable to allow a relay to connect to the server. If this is not specified then 'allowrelay' will be used.

'''streamallowpublicrelay''' : Enable to allow relays to list themselves in the YP directory. If this is not specified then 'allowpublicrelay' will be used.

'''streamriponly''' : Enable to only allow connections to be made from reserved IP addresses. If this is not specified then 'riponly' will be used.

'''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.

'''streamautodumpusers''' : Enable to allow the server to disconnect clients if the source disconnects. If not specified then 'autodumpusers' will be used.

'''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.

'''streamintrofile''' : File to play when a client first connects to the server. If this is not specified then 'introfile' will be used.

'''streambackupfile''' : File to play if the source disconnects from the server. If this is not specified then 'backupfile' will be used.

'''streammovedurl_X''' : redirects a permanently stopped or moved stream to a different working stream url.

'''streambanfile''' : File to store the list of banned IP addresses. If this is not specified then 'banfile' will be used.

'''streamripfile''' : File to store the list of banned IP addresses. If this is not specified then 'ripfile' will be used.

'''streamw3clog''' : File to store the web connections logs into. If this is not specified then 'w3clog' will be used.

'''DNAS v2.6 and newer'''

'''sslCertificateFile''' : For https:// streams, specify .crt file e.g. sslCertificateFile=/path/to/ssl.crt

'''sslCertificateKeyFile''' : specify key file, e.g. sslCertificateKeyFile=/path/to/key.pem

Put the whole certificate chain in the .crt file, and only the key in the .key file
Note: Requires Premium subscription to unlock Premium features.
SSL Cert needs to be assigned to a DNS e.g. stream.mysite.com
Be sure to also add destip=stream.mysite.com and alternateports=443 lines to DNAS config file.

''' '''

===Web Connection (W3C) Logging===
----

'''w3cenable''' : Enable logging of web connections to describe the duration a client has listened to a specific title ''[Default = 1]''

'''w3clog''' : File to store the web connections logs into ''[Default = sc_w3c.log]''

If you are using a folder for saving the log into then you need to ensure that the folder
already exists as sc_serv will not attempt to the create the folder for you.

'''webclientdebug''' : Enable logging of web client connections ''[Default = 0]''

===YP Server Behaviour===
----

'''uvoxcipherkey''' : Specify the key used to obfuscate the initial handshaking with the source ''[Default = foobar]''
This is a SHOUTcast 2 only feature and it matches the 'djcipher' value in the sc_trans
configuration file (see [[SHOUTcast_DNAS_Transcoder_2#DJ_Support|sc_trans.txt - section 3.3]]).

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.

'''metainterval''' : Specify the metadata transmission interval in bytes ''[Default = 8192]''
YP1 only

'''yp2''' : Enable to use the SHOUTcast 2 protocol and related server features for access to the YP2 directory ''[Default = 1]''

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.

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]].

'''ypaddr''' : Allows you to specify a different YP server if required ''[Default = yp.shoutcast.com]''

'''ypport''' : Allows you to specify the port of the YP server if required ''[Default = 80]''

'''ypPath''' : Allows you to specify the path to YP2 services on the server ''[Default = /yp2]''

'''ypTimeout''' : Specify the timeout interval in seconds for requests made to the YP server ''[Default = 60]''

'''ypmaxretries''' : Specify the maximum number of times a YP request will be attempted ''[Default = 10]''
This generally applies only to YP1 connections and is related to the
actual attempts to make and get a http response from the YP server.

'''ypreportinterval''' : Specify the maximum time in which the YP must have contacted our server in seconds ''[Default = 300]''

'''ypminreportinterval''' : Specify the minimum time in which the YP can contact our server in seconds ''[Default = 10]''

'''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]''
This can be one of the following values:
'''default''' - use the flag provided by the source
'''always''' - force the source to be public
'''never''' - never allow the use the flag provided by the source

When using sc_trans this would match with the 'public' value (see [[SHOUTcast_DNAS_Transcoder_2#Metadata_Control|sc_trans.txt - section 3.8]]).

===YP Server Errors===
----

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.

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>.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
! Status Code
! Status Message
|-
| 400 || Generic error ''(covers all other cases usually from internal failures)''
|-
| 457 || Unrecoverable error while updating station information - DNAS restart required.
|-
| 470 || Invalid authorization hash
|-
| 471 || Invalid stream type (could be a bad bitrate or mime type)
|-
| 472 || Missing or invalid stream url
|-
| 473 || Server unreachable by YP
|-
| 474 || Relay url does not exist
|-
| 475 || Invalid server ID
|-
| 476 || Invalid max clients (value out of range or missing)
|-
| 477 || Terms of Service violator. You are being reported.
|-
| 478 || Incompatible protocol.
|-
| 479 || Streams requiring authorization are not public and cannot list here.
|-
| 480 || Cannot see your station/computer (URL: <streamurl>) from the Internet, disable Internet Sharing/NAT/firewall/ISP cache.
|-
| 481 || Cannot verify server since all listener slots are full. Please wait.
|-
| 482 || This network has been permanently banned due to a previous violation of the SHOUTcast directory terms of service
|-
| 483 || Invalid listeners (value out of range / missing)
|-
| 484 || Invalid avglistentime (value out of range / missing)
|-
| 485 || Invalid newsessions (value out of range / missing)
|-
| 486 || Invalid connects (value out of range / missing)
|-
| 487 || Request & Response objects are null
|-
| 488 || Request xml is null
|-
| 489 || YP command not specified
|-
| 490 || Generic error, while doing xml parsing
|-
| 491 || Generic error, while reading xml request
|-
| 492 || Error closing buffer / HTTP connection
|-
| 493 || Internal error - unable to acquire data source
|-
| 494 || Error updating information - DNAS restart required
|-
| 495 || Error acquiring station ID - DNAS restart required
|-
| 496 || Error converting data type
|-
| 497 || Inconsistent stream behaviour
|-
| 498 || Invalid Request (Invalid request received)
|-
| 499 || Error while getting information
|}

==Administration==

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.'''
<streamurl>/index.html?sid=1

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.

===Administration Pages===
----

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.

====Public Pages====
----

'''index.html''' - Shows a summary page with links to get to any active stream(s)

'''currentsong?sid=#''' - Returns the current song title or a null response

'''nextsong?sid=#''' - Returns the next song title (if known) or a null response
currentsong and nextsong both provide a UTF-8 encoded string of the song title
otherwise it will return effectively no response (ignoring the http header).

'''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).

'''index.html?sid=#''' - Shows current status of the specified stream

'''played.html?sid=#''' - Song history of specified playing history
:or
'''played?sid=#'''

'''listen.pls?sid=#''' - Provides a PLS for file clients to use to connect to the stream.
:or
'''listen?sid=#'''

'''listen.m3u?sid=#''' - Provides a M3U file for clients to use to connect to the stream.

'''listen.asx?sid=#''' - Provides a ASX file for clients to use to connect to the stream.

With the listen pages you either need to have specified an IP with 'dstip / destip'
(see section 4.2) or leave empty and allow the server to 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>

'''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.

'''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.

====Private Pages====
----

By passing &pass=password where password is the 'adminpassword' (see section [[#Networking|4.8]]) then it is possible
to directly access the administration page(s) required. As well the base64 encoded version of the password
can be passed as long as it is prefixed with ''YWRtaW46''
e.g.
&pass=changeme is the same as &pass=YWRtaW46Y2hhbmdlbWU=

'''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)
:or
'''admin.cgi?sid=0'''

'''admin.cgi?sid=#''' - Shows the base admin page for the stream and information

'''admin.cgi?sid=#&mode=updinfo&song=title'''
:or
'''admin.cgi?sid=#&mode=updinfo&type=xml&song=xml'''
If 'title' is not empty then it will be set as the current song title for the stream
specified until the next use of this action or the next title update is received from
the source. Specifying '&type=xml' will process the value of 'song' as [[SHOUTcast_XML_Metadata_Specification|v2 XML metadata]]
instead of a v1 title.

'''admin.cgi?sid=#&mode=viewlog''' - View logfile

'''admin.cgi?sid=#&mode=viewlog&viewlog=tail''' - View logfile (tailing)

The tailing option keeps adding additional log entries to the end of the view whilst the view is active.
As well any html or xml data in the log will not be shown correctly in the view as < > & are not escaped
to their html entities. See [[#Logging|section 4.6]] for more information on the log file.

'''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)

'''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)

'''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.

The artwork mode is primarily intended as a debugging option to make it possible
to see what (if anything) has been provided by the SHOUTcast v2 source.

If no '&art=' is specified or not a matching option then the stream artwork (if
available) will be shown. If no '&art=playing' is specified then this will show
the playing file's artwork (if available).

'''admin.cgi?sid=#&mode=viewxml''' or '''admin.cgi?sid=#&mode=viewxml&page=#''' - Returns an xml output of the current stream information

If page is not set or is outside of the range zero to 6 then this will output all of the
information as the standard viewxml action does. Otherwise this only display information
depending on the value assigned to page which can be from 1 to 6 which maps as follows:

1 - Server Summary (this is the same as using the public stats?sid=# action)
2 - Not used (previously used for Webdata Stats but not in current builds)
3 - Listener Stats
4 - Song History
5 - Stream Metadata (if supported by the source otherwise can just be title)
6 - Stream Configurations (displays all of the known stream configurations though this is only available on admin.cgi)

If accessing the standard viewxml or the listener stats (page = 3), you can also send
'&iponly=1' which will filter the listener information (if there are any) to just output
the IP instead of the additional information provided normally.

'''admin.cgi?mode=resetxml&sid=#''' - Will flush the held stream information to refresh it

'''admin.cgi?sid=#&mode=kicksrc''' - Will allow you to kick the currently connected source for the specified stream.

'''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).

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>.0&banmsk=0''' - Where <IP> is the first 3 parts of a subnet IP to unban.

'''admin.cgi?sid=#&mode=unbandst&bandst=<IP>&banmsk=255''' - Where <IP> is that of a single IP to unban.

'''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.
If &files is specified then passing log or w3c will allow you to only
rotate one type of file otherwise both will be rotated by this command.

'''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.

This command works on the server as a whole (hence no sid parameter) and it will add or
remove or update any stream configuration as applicable which will cause any connected
sources and clients to be kicked as applicable (usually if a stream configuration was removed).

This will recognise any configurations included via 'include' entries so you can have 'include=stream/*.conf'
in your main configuration file which the server can then use to detect different stream configurations.

If '&force=1' is passed then the reload will treat the updating of active stream configurations in the
same manner as a stream configuration removal instead of trying to update compatible stream configuration
details without resetting the stream '''e.g.''' not increasing the 'streammaxuser' when it could be increased.

The following configuration options are updated when using this command:

password or streampassword (*) streamadminpassword (#)
requirestreamconfigs streamid
streamauthhash streampath
streamrelayurl streammaxuser
streampublicserver streamallowrelay
streamallowpublicrelay streamriponly
streamautodumpsourcetime streamautodumpusers
streamlistenertime streamintrofile
streambackupfile streambanfile
streamripfile

(*) This will depend upon the current values versus the new configuration values
(#) The master 'adminpassword' can only be changed after a restart of the server

===XML Responses===
----

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]].

==Stream Addresses==

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.

The two main ways for a client to connect to a stream are as follows:

<serverurl>/stream/<streamid>/
or
<serverurl>/<streampath>

<serverurl> is typically formed as <nowiki>http://dstip:portbase</nowiki> (see sections [[#Client_Behaviour|4.2]] and [[#Networking|4.8]])
<streamid> is the 'streamid' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])
<streampath> is the 'streampath' set from the stream configuration (see [[#Stream_Configuration|section 4.12]])

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).

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'

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.

==Locale Error (Linux / Mac OS X / BSD)==

If you receive the following error then you have a locale related issues:

terminate called after throwing an instance of 'std::runtime_error'
what(): locale::facet::_S_create_c_locale name not valid
Abort trap

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.

Linux:
export LC_ALL=POSIX

BSD:
setenv LC_ALL POSIX

Mac OS X:
export LC_ALL=POSIX

You can test to see if this has worked by checking the shell command "locale":

LANG=
LC_COLLATE="POSIX"
LC_CTYPE="POSIX"
LC_MESSAGES="POSIX"
LC_MONETARY="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL="POSIX"

==Virtual Memory Footprint (Linux / Mac OS X / BSD)==

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.

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

==Maximum Client Connection Limits==

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.

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.

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)

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

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.

==Example Configurations==

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:

sc_serv_basic.conf
sc_serv_public.conf
sc_serv_relay.conf
sc_serv_simple.conf

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.

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.

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).

===sc_serv_basic===
----

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.

===sc_serv_public===
----

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.

===sc_serv_relay===
----

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.

===sc_serv_debug===
----

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.

===sc_serv_simple===
----

Use this if you just need to get a very basic server running or are impatient
or are struggling to get it running despite the previous example configurations.

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.

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.