Source DSP Plug-in

From Winamp Developer Wiki
Revision as of 18:50, 15 December 2010 by DrO (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Introduction to dsp_sc

The aim of this document is to show you the different features offered by the SHOUTcast Source DSP plug-in. The v2 of the plug-in is designed to work only on Winamp 5.5 and up due to better api usage and integration with the player. If you want to use it with an alternative player, then this will need to support all of the apis the plug-in may use.

The key feature of the plug-in is the ability to use Winamp as a source to a sc_serv or sc_trans instance (or any other compatible tool which can accept SHOUTcast 1 or 2 data).

Additionally the plug-in will allow you to capture an audio input from the soundcard and its line-in or microphone inputs (as shown in section 3.3.2).


Getting Started

To get going with dsp_sc you will need to have already setup either a server (sc_serv) or an alternative source to feed (like sc_trans which then feeds an sc_serv instance) and to have all access enabled to allow a source to connect. The plug-in can be used as either a full source or it can be used as a DJ connection in the case of being used with sc_trans.


Installing the Plug-in


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

Once installed then you will need to open Winamp and go to the following location:

   Preferences -> Plug-ins -> DSP/Effect

and select the 'Nullsoft SHOUTcast Source DSP' entry shown in the list of plug-ins.


Configuration Window

The configuration window is the main part of the plug-in and is where all information for the connection to the server or the current status of the connection can be changed and viewed.

Please note that 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 event occurs.


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.

Note: If you double-click one of the output items you will be taken to the 'Output Tab' (see section 3.3) where the view will be changed to view the current settings for for output item picked.

Input Meters : This will show the left and right channel audio levels as is being passed through the plug-ins core which allows you to see if the input source is possibly not working or just to check the volume level on the source, etc.

Additionally, to the right is shown the currently selected input device (as chosen on the 'Input Tab' (see section 3.3)


Output Tab


This tab allows you to configure the 5 possible outputs the plug-in is able to generate where the settings for each output are selected by clicking the 'Output X' item in the list (where X is from 1 to 5).

Status : This will show the current information about the output source ranging from not being connected to error messages due to invalid passwords, etc.

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.


Connection Tab


address : This is the address of the server to connect to and will depend upon the setup which is being used. For example if the server or transcoder being connected to are on the same machine then 'localhost' can be entered or the exact IP of the machine for the DSP to attempt a connection to.

port : This is the port related to the 'address' of the server to connect to. This needs to match 'portbase' (sc_serv.txt - section 4.0.8) or 'serverport' (sc_trans.txt - section 3.0.11).

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' (sc_serv.txt - section 4.0.8) or 'uvoxstreamid' (sc_trans.txt - section 3.0.11).

Note: This is disabled if 'Use SHOUTcast v1 mode (for legacy servers)' is checked.

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 sc_trans.txt - section 3.0.3 though this will all depend on the server configuration being used so if you have to connect to a server then you will most likely be provided with a user id to use in this.

Note: This is disabled if 'Use SHOUTcast v1 mode (for legacy servers)' is checked.

Password : This is the password required for accessing the server (if set on the server). This needs to match 'password' (sc_serv.txt - section 4.0.8) or 'uvoxauth' (sc_trans.txt - section 3.0.11).

Automatic reconnection on : This will make the plug-in attempt to connect back to the server if there is a break in the connection. connection failure

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 type of source the plug-in will try to create. With this checked then it will making an SHOUTcast 1 connection otherwise it will attempt to make a SHOUTcast 2 connection (this is the default behaviour on new installs of the plug-in).

Not setting the correct mode for the server you are attempting to connect to will cause the connection attempt to fail or enter into what appears to be a hung state where you are like to see a 'Cipher response received' if connecting in SHOUTcast 2 mode to a SHOUTcast 1 server.


When the SHOUTcast 1 mode is enabled then an information panel is displayed below these options which shows the following message:

 The DJ connection password format is <djlogin>:<djpassword>  e.g.  dj:noise

When the SHOUTcast 2 mode is enabled then an information panel is displayed below these which 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'.


Yellowpages Tab


Make this server public (Recommended) : With this enabled, the plug-in will report that it wants to appear on the YP directory listing.

Description : This is the name you want to use for the source (often what will be used in YP 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 YP directory listing.

AIM / ICQ / IRC : These allow you to specify some contact information for clients though support of these fields depends on the server platform being used.

Track Title : This allows you to either use the title information obtained from Winamp or you can specify custom information about the 'now' and 'next' titles which is then sent with the source metadata when using the 'Send Update' button.


Encoder Tab


This tab allows you to specify the encoder to be used to create the output stream based on the input data obtained by the plug-in. The following encoders are available with the plug-in:

   MP3     (audio/mpeg)
   AAC+    (audio/aacp)
   AAC LC  (audio/aacp)

The AAC encoding is dependant upon enc_aacplus.dll being present in your Winamp plug-in folder. If not detected then the AAC encoding will be disabled. Both AAC+ and AAC LC are reported as audio/aacp due to how the YP2 directory works where only 'audio/mpeg' and 'audio/aacp' are accepted as supported mime types for a stream.

Depending upon the encoder selected the 'encoder settings' section will provide different options for controlling the settings of the encoder (usually a button to open an extra configuration window or a dropdown list with fixed options to choose from).


Input Tab



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 : This will show the left and right channel audio levels as is being passed through the plug-ins core which allows you to see if the input source is possibly not working or just to check the volume level on the source, etc.

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


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.

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.


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 online documentation and also for going to the SHOUTcast support forum if issues are being experienced with the plug-in's usage.

The online documentation is typically the most current version of this file in an online form as available via http://dev.winamp.com/wiki/SHOUTcast_Broadcaster

The support forum is accessed via http://forums.winamp.com/forumdisplay.php?f=140


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.