-----------------------------------------------
SWAMP MP3: The mIRC's Sonique/WinAmp Controller! v1.0beta
---------------------------------------------------------------
Author: LightStrike
e-mail: LightStrike@mail.pt
----------------------------------------------------------
Questions, doubts, bug reports, insults, feedback, may all be sent
to my mail-box.
-----------------------------------------------------------------------


Table of contents:

  1. - What is this shit ?
  2. - Why this ?
  3. - Which are phuckin' functions in the DLL ?
  4. - How do I use this thing ?
  5. - Which are the CommandTags ?
  6. - Which are the InfoTags ?
  7. - Which are the SetTags ?
  8. - Tips/Tricks.
  9. - Anything else ?





1.) What is this shit ?

    SWAMP MP3 is a new version of WAMP.DLL enhanced with Sonique support, and with
    some additional functions. It's intended for use with mIRC, and, it it *not* a
    plug-in neither for WinAmp nor Sonique!



2.) Why this ?

    Well... I came with the Idea of making an mp3 player for mIRC, in Delphi,
    using DDE, but it was taking too much work, and, because I am too lazy :), 
    I came up with WAMP.DLL. Then, when I released it to public domain, a mIRC
    scripter ('novahak') came with an idea about adding Sonique support, and
    here it is, fresh, clean, and written from scratch: SWAMP MP3.
    You can only use it in mIRC Scripts, because, the functions are mIRC specific.
    With this baby you can retrieve information from WinAmp and Sonique, for example,
    the title of the song playing... Well... use your brain :)



3.) Which are the phukin' functions in the DLL ?

    There are 7 functions in the DLL. They are:
    
       ID3Tag     - Used to extract the ID3Tag from MP3 files. Returns information in the
                    artist/album/title/genre/year/comment sequence separated by the ascii char number 12.

                    Example: %id3 = $dll(swamp.dll, ID3Tag, c:\fodilhao69.mp3)


       WinAmpRun  - Used to run WinAmp with or without parameters. 

                    Example: /dll swamp.dll WinAmpRun "c:\fodilhao69.mp3"


       WinAmpGet  - Used to get some values about WinAmp, designated by me as 'InfoTags'.

                    Example: %x = $dll(swamp.dll, WinAmpGet, running)


       WinAmpSet  - Used to set some values in WinAmp, designated by me as 'SetTags'.

                    Example: /dll swamp.dll WinAmpSet Volume 255

   
       WinAmpCmd  - Used to control WinAmp, pressing buttons, opening dialogs, starting things...
                    Used parameters designated by me as 'CommandTags'.
 
                    Example: /dll swamp.dll WinAmpCmd fadeout


       SoniqueRun - Used to run Sonique with or without parameters. Please consult the file 'cmdline.html'
                    located on your Sonique's directory to know about every command line option supported
                    by Sonique!

                    Example /dll swamp.dll SoniqueRun -startsong c:\fodilhao69.mp3


       SoniqueGet - Used to get information about Sonique. Also uses 'InfoTags'.




4.) How do I use this thing ?    

    Well... Er... Hmm... Check the examples on last topic! They're pretty good teachers :)

    Easy huh ? If you are confused about the $dll identifier and the /dll command
    please read mIRC's Help File before boring me with stupid questions :|



5.) Which are the CommandTags?

    They're:

    PLAY            - Presses the play button in WinAmp.
    STOP            - Presses the stop button in WinAmp.
    PAUSE           - Presses the pause button in WinAmp.
    NEXTTRACK       - Presses the next track button in WinAmp.
    PREVTRACK       - Presses the previous track button in WinAmp.
    FADEOUT         - Fades volume out and stops playback.
    STOPONOVER      - Stops playback when current track is over.
    FASTFORWARD     - Presses the fast-forward button.
    FASTREWIND      - Presses the fast-rewind button.
    FIRSTTRACK      - Plays first track in playlist.
    LASTTRACK       - Plays last track in playlist.
    TOGGLEREPEAT    - Presses the repeat button in WinAmp.
    TOGGLESHUFFLE   - Presses the shuffle button in WinAmp.
    RAISEVOLUME     - Raises volume by 1%
    LOWERVOLUME     - Lowers volume by 1%.
    SAVEPLAYLIST    - Saves current WinAmp playlist to <WinAmpdir>\WinAmp.m3u
    CLEARPLAYLIST   - Clears WinAmp internal playlist.
    OPENFILEDIALOG  - Opens the WinAmp's "Open File Dialog".
    OPENURLDIALOG   - Opens the WinAmp's "Open Location Dialog".
    RELOADSKIN      - Makes WinAmp reload it's current skin.
    STARTVISPLUGIN  - Makes WinAmp start current selected Visualization Plug-In. Same as [CTRL+Shift+K].
    CLOSEWINAMP     - Closes WinAmp.
    RESTARTWINAMP   - Restarts WinAmp.



6.) Which are the InfoTags ?

    They're:
   
    RUNNING         - Returns $true if WinAmp/Sonique is running and $false if not.
    INSTALLED       - Returns $true if a valid WinAmp/Sonique installation exists.
    EXEFILENAME     - Retruns path to WinAmp.exe/Sonique.exe
    DIRECTORY       - Returns WinAmp/Sonique directory.

    ------------------- The following 'InfoTags' are WinAmp specific -------------------------

    VERSION         - Returns currently running WinAmp version.
    STATE           - Returns WinAmp's state: playing, paused, stopped
    PLAYEDTIME      - Returns current played time in miliseconds or -1 if stopped.
    TRACKTIME       - Returns current track total time in seconds.
    PLAYLISTLENGTH  - Returns WinAmp's current playlist length.
    TRACKNUMBER     - Returns current track number in playlist.
    TRACKFILENAME   - Returns current track's full path and name.
    SAMPERATE       - Returns current track's sample rate. 44 = 44100; 22 = 22150; ...
    BITRATE         - Returns current track's bit rate in Kbps.
    CHANNELS        - Returns current track's number of channels. 1 for mono, 2 for stereo...
    ID3TAG          - Returns the ID3 TAG separated by the ascii char number 12 in the sequence:
                      artist/album/title/genre/year/comment

    ------------------- The following 'InfoTags' are WinAmp specific -------------------------

    TRACKARTIST     - Returns the track's artist.
    TRACKTITLE      - Returns the track's title.
    TRACKFILENAME   - Returns the track's filename. Sometimes it returns $null due to
                      a setable options in Sonique, and it doesn't include the path.
                      Sorry.. not my fault :\



7.) Which are the SetTags ?

    They're:

    TRACK           - Sets current track in playlist. You must then send a PLAY instrution to WinAmp
                      if you wanna start playing the track.
    VOLUME          - Sets WinAmp's output volume (mute=0, loud=255)
    PAN             - Sets WinAmp's output pan (left=-255, center=0, right=255)
    OFFSET	    - Sets current track offset, in milliseconds. If you specify a numer higher than track's
                      length, WiNAmp will start the next track.


8.) Tips/Tricks


      - You could make 2 popup menus, one for Sonique and the other for WinAmp, then, you use an 'on START' event,
        the INSTALLED InfoTag and the RUNNING InfoTag to define wich popup menu to enable. The popup menus should be
        written in a remote script and using #groups.
      
      - You could use the $isid identifier to make your life easier. Take a look at the following aliases.

        winamp {
          if ($isid) return $dll( [ $shortfn($mircdirsystem\swamp.dll) ] , WinAmpGet, [ $1 ] )
          else {
            if ($1 == -r) .dll [ $shortfn($mircdirsystem\swamp.dll) ] WinAmpRun $2-
            elseif ($1 == -s) .dll [ $shortfn($mircdirsystem\swamp.dll) ] WinAmpSet $2-
            else .dll [ $shortfn($mircdirsystem\swamp.dll) ] WinAmpCmd $1-
          }
        }


        sonique {
          if ($isid) return $dll( [ $shortfn($mircdirsystem\swamp.dll) ] , SoniqueGet, [ $1 ] )
          else .dll [ $shortfn($mircdirsystem\swamp.dll) ] SoniqueRun - $+ $1-
        }

      - You can add folders and files to your WinAmp playlist by using the /ADD command line option. But, remember
        that files and folders must be beetwen "" and folders must no have the final \ except if its a drive like "D:\".

      - Don't forget to read the cmdline.html file located on your Sonique's directory.


9.) Anything else ?

    Er... well... yes, just to remember you that you can only distribute this package, and *I MEAN THE WHOLE PACKAGE*,
    to your friends and enemies. Be sure to send-me an e-mail if you feel so.


--------------------------------
Author: LightStrike
e-mail: LightStrike@mail.pt
---------------------------------------------------------------------------------
Questions, doubts, bug reports, insults, feedback, may all be sent
to my mail-box.
-------------------
