Source DSP Plug-in

From Winamp Developer Wiki
Jump to: navigation, search

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


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


Select Source DSP plug-in in Winamp

The DSP plugin can be downloaded for free at shoutcast.com

Shoutcast DSP for Winamp 5.6 | 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


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


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' (DNAS Server - section 4.8) or 'serverport' (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' (DNAS Server - section 4.8) or 'streamid' (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 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' (DNAS Server - section 4.8) or 'password' (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.

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


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


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


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


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


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


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 - (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 (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: 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 (DNAS Server - section 4.14) or the djcipher (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 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.