WinAmp Plugin Utilizer DLL for mIRC, v1.07 (c) 1999-2000 DragonZap,
        dragonzap1@aol.com

WinAmp is (tm) NullSoft, www.winamp.com

This DLL is provided as-is. I'm not responsible if it causes your
sound card to become engulfed in a seven-color fireball. Hopeully it won't.

You are free to use this DLL in any scripts you happen to make so
long as they are not "negative" scripts (like war scripts or
backdoor scripts or whatever).

When I'm showing the parameter lists, parameters enclosed in [] mean
those parameters are optional, and parameters enclosed in <> mean
those parameters are mandatory.

All responses from this DLL will be prefixed with "OK" (indicating success)
or "ERROR <code>" (indicating failure) -- if you are having trouble, please
look at these messages using $dll. If you expect succcess every time,
you must use $gettok($dll(amp_in.dll,...,...),2-,32) to cut off the
"OK".

The DLL includes these functions:

PluginManager
        Parameters: <subcommand> [parameters]

        This function has several subcommands, all dealing with
        the management, loading, information, and use of plugins:

        load <type> [DSP module number] <filename>
                Loads a plugin, which can be of type "input", "output",
                or "dsp". DSP plugins must be unloaded before a new
                one can be loaded. If you are loading a DSP plugin,
                you must give [DSP module number], which can be from
                1 to dspcount. Loading a new output plugin stops
                any currently playing music.
        unload <type>
                Unloads a plugin. Currently, you can only unload the
                DSP plugin, using "dsp" as your <type>.
        inputcount
                Retrieves a count of the loaded input plugins.
        about <type or input number>
                Opens up the "about" box for the given loaded plugin
                if no other about/config/file info box is already open.
                <type> can be "output" or a number from 1 to whatever
                "inputcount" returns.
        config <type or input number>
                Opens up the "config" box for the given loaded plugin
                if no other about/config/file info box is already open.
                <type> can be "output", "dsp", or a number from 1 to
                whatever "inputcount" returns.
        description <type or input number>
                Retrieves the plugin description of <type>, which
                can be "output", "dsp", "dspmod" (for a description 
                of the currently loaded DSP module in use in the
                plugin), or a number from 1 to "inputcount".
        typecount <input plugin number>
                Returns a count of the file type sets the input
                plugin given supports.
        typelist <input plugin number> <type set>
                Returns a list of the file types the input plugin
                supports in the set given by <type set>, separated
                by a semicolon. (;)
        typedesc <input plugin number> <type set>
                Returns a text description of the <type set> in the
                input plugin given.
        alltypes [input plugin number]
                Returns a list of all the types supported, or all the
                types supported by the given plugin, separated by a
                semicolon. (;)
        uinfo <type> <info> [modnumber] <filename>
                Returns information on the plugin specified in <filename>,
                which does not actually have to be loaded. The plugin's
                type must match <type>, which can be "output", "input", or
                "dsp", for output, input, or DSP plugins, respectively.
                <info> can be:
                name    - (any plugin) Returns the plugin's description.
                modname - (DSP only) Returns the name of one of the modules
                          in the DSP plugin, starting from 1. A count of
                          the modules can be retrieved "uinfo dsp modcount".
                version - (any plugin) Retrieves the version number for
                          the plugin. Unless the plugin is some version
                          that this DLL cannot handle, the output will be
                          "1.0" for output plugins, "1.00" for input plugins,
                          and "2.0" for DSP plugins.
                modcount- (DSP only) Retrieves a count of the individual
                          DSP modules in the given DSP plugin.
                id      - (output only) Returns the output plugin's id
                          number. Not all that useful.

        Examples:

        //echo I have loaded $dll(amp_in.dll,PluginManager,load input
                c:\program files\winamp\plugins\in_mp3.dll)

        //echo I want to know about input plugin 2: $dll(amp_in.dll,
                PluginManager,about 4)

        //echo The name of the waveOut plugin is: $dll(amp_in.dll,
                PluginManager,uinfo output name out_wave.dll)

Queue
        Parameters: <subcommand> [parameters]

        This DLL stores its own queue, also known as a playlist, much
        like WinAmp does. You can control the queue by using this function.
        Available commands are as follows:

        add <filename>
                Adds the given filename to the end of the queue.
                <filename> can also be a URL or other type of format
                that any of the input plugins might support.
        count
                Returns a count of the total number of tracks in the
                queue.
        insert <position> <filename>
                Inserts a filename before position <position> in the
                middle of the queue. If the position is too far out
                of bounds (i.e. if it is less than 1 or greater than
                the queue length), the filename will be added at the
                beginning of the queue or at the end of the queue,
                depending on which end you were out of bounds on.
        remove <position>
                Removes the track at position <position> from the
                queue. If this is the track that is currently playing,
                playback will stop and continue with the next track if
                possible.
        clear
                Clears the entire playlist and halts playback if
                playing from the queue.
        looping <setting>
                Enables or disables automatic queue looping, or checks
                the current setting.

                Settings:
                on  - Turn looping on
                off - Turn looping off
                get - Get current looping mode
        shuffle <command>
                Shuffles the playlist or manipulates AutoShuffle.
                AutoShuffle causes the DLL to automatically shuffle the
                playlist whenever it plays all the way through. When paired
                with automatic queue looping, this can be quite useful.

                Commands are:
                now      - Shuffles the playlist immediately. If a track is
                           playing, the track pointer will move with it.
                           This means that if the current track is moved to
                           the last position in the queue and then ends, the
                           queue will be considered to have finished a pass.
                auto-on  - Enables AutoShuffle. (see above)
                auto-off - Disables AutoShuffle. (see above)
                auto?    - Returns "on" if AutoShuffle is enabled or "off"
                           if it is not.
        filename <position>
                Returns the filename/URL/etc. of the track at position
                <position>.
        title <position>
                Retrieves the title of the track at position <position>.
                If no title exists, the filename is returned.
        length <position>
                Retrieves the length, in milliseconds, of the track
                at position <position>. If the length is unknown or
                infinite, the value -1000 will be returned.
        setcurrent <position>
                Set the current queue position to <position>. This is
                what track playback will start on. If playback
                has already been started, playback will immediately start
                from the new position.
        getcurrent
                Gets the current track position in the queue, or -1
                if the queue is not being used for playback.
        saveM3U <filename>
                Saves the playlist in .m3u format to the given filename.
                The file will be overwritten.
        loadM3U <filename>
                Clears the current playlist and loads a new playlist in
                .m3u format into the queue. If an error occurs in loading,
                the current queue is still lost. All playback is stopped
                if playback was using the queue.


        In addition to numeric values for <position> wherever it's
        applicable, you can also use some relative keywords:

        current - The currently playing track.
        previous- The track before the current one.
        next    - The track after the current one.
        last    - The last entry in the queue.

        Examples:

        //echo Adding a file: $dll(amp_in.dll,Queue,add
                c:\windows\desktop\1- Stuff I like.mp3)

        //echo There are $gettok($dll(amp_in.dll,Queue,count),2,32) files
                in the playlist

        //echo I'm skipping this song. $dll(amp_in.dll,Queue,setcurrent next)

        //echo Shuffle! $dll(amp_in.dll,Queue,shuffle now)

Play
        Parameters: <filename>

        Plays a given filename. If the filename given is the string
        "<QUEUE>" (no quotes), then playback will take place using the
        queue/playlist. If you want to set where playback will begin
        in the queue, use the "setcurrent" function of "Queue".

        Examples:

        //echo I am playing a wave file: $dll(amp_in.dll,Play,
                c:\windows\ding.wav)

        //echo I am playing from the queue: $dll(amp_in.dll,Play,<QUEUE>)


Stop
        Parameters: none

        Stops any music currently playing.

        Example:

        //echo Stopping: $dll(amp_in.dll,Stop,.)

Info
        Parameters: <subcommand> <filename>

        Retrieves information on a specific filename or URL. If a URL
        requires a connection somewhere (rather than something which
        can find out the information immediately), you may not get
        the correct info -- use the functions of "CurrentMusic" when
        that file is playing. Subcommands are:

        title <filename>
                Retrieves the title of <filename>, or just the filename
                if the title cannot be determined.
        length <filename>
                Retrieves the length, in milliseconds, of <filename>,
                or -1000 if it cannot be determined.
        info <filename>
                Opens up an information dialog box about the specified
                file. Only one such information box can be open at a
                time, and the user must close one box before another
                can be opened.

        Examples:

        //echo Some file runs for $dll(amp_in.dll,Info,length
                c:\MP3s\bleh.mp3) milliseconds

        //echo All you ever wanted to know about this ScreamTracker module
                is... $dll(amp_in.dll,Info,info c:\S3Ms\muzak.s3m)

CurrentMusic
        Parameters: <subcommand> [parameters]

        Returns information about the currently playing music. Most
        subcommands will fail if there is no music playing. The
        available subcommands are:

        status
                Returns the status of the currently playing music.
                More specifically, it will return "stopped" if no
                music is playing, "playing" if there is music playing,
                and "paused" if the music is paused. This is the
                only "CurrentMusic" subcommand that will not fail
                if the music is not playing.
        pause
                Pauses the music.
        unpause
                Unpauses the music.
        title
                Retrieves the title of the currently playing music.
                This can change during the song's playback, so check
                it frequently.
        filename
                Returns the filename or URL of the currently playing
                music.
        length
                Returns the length, in milliseconds, of the currently
                playing music, or -1000 if the length cannot be
                determined.
        position
                Returns the playback position in the currently playing file,
                in milliseconds. Be warned that some plugins may cause this
                value to go beyond the length of the song, and your script
                will have to account for that.
        seek <position>
                Seeks to <position> milliseconds in the current music.
                Will fail if the media being played is not seekable
                (such as from a ShoutCast stream)
        bitrate
                Returns the outputting bit rate.
        samplerate
                Returns the currently outputting sample rate.
        stereo
                Returns the number of output channels in use (will
                generally be 2 for stereo or 1 for mono)
        synched
                Returns "yes" if the sound is synchronized or
                "no" if it is not.
        info
                Opens an information dialog box about the current music.
                Fails if there is a similar dialog box already open.

        Examples:

        //echo Jump to 10 seconds into a song: $dll(amp_in.dll,CurrentMusic,
                seek 10000)

        //echo Music is currently $gettok($dll(amp_in.dll,CurrentMusic,
                status),2,32)

Misc
        Parameters: <subcommand> [parameters]

        All other functions that didn't have a place somewhere else
        go here. They are:

        getvolume
                Retrieves the volume (ranges from 0 to 255).
        setvolume <new volume>
                Sets the volume.
        getpan
                Retrieves the panning (also known as balance).
                Ranges from -127 to 127. Negative values are for
                the left speaker, and positive values are for the
                right. 0 is balanced exactly.
        setpan <new panning>
                Sets the panning.
        equalizer enable
                Enable the equalizer sound modification.
        equalizer disable
                Disable the equalizer sound modification.
        equalizer enabled?
                Returns "yes" if the equalizer is enabled, and
                "no" if not.
        equalizer preamp-set <value>
                Sets the pre-amplification (range from 0 to 63).
        equalizer preamp-get
                Retrieves the current pre-amplification setting.
        equalizer get
                Retrieves all 10 equalizer values.
        equalizer set <v1> <v2> <v3> <v4> <v5> <v6> <v7> <v8> <v9> <v10>
                Sets the equalizer values. All 10 must be set at once.
                Range is from 0 to 63 for each one.
        box
                Retrieves the type of the current open dialog box, if
                any:

                none              - No dialog open.
                info <filename>   - Information about <filename>
                about input <num> - About box for input plugin <num>
                config input <num>- Config box for input plugin <num>
                about output      - About box for output plugin
                config output     - Config box for output plugin
                config dsp        - Config box for DSP plugin
        notify <setting>
                Enables fake notification to mIRC when a song completes via
                the use of "on MIDIEND" or "on WAVEEND". You may set up
                a notification if you do not wish to continuously poll the
                DLL to check when a song has completed. Be warned, however,
                that this will interfere with mIRC's handling of waves
                or MIDIs that were started with /splay -- that is, if the
                song being played by the DLL ends before the MIDI or wave
                file does, the MIDI or wave file will be stopped prematurely.
                The notify modes do not affect $inmidi or $inwave, however,
                which will still return $false unless mIRC started playing
                a MIDI or wave.

                The setting choices are:

                none    - No notification. This is the default, and used
                          if you want to poll the DLL for whenever a song
                          ends, rather than avoiding using /timers and
                          interfering with normal MIDI/wave playing.
                wave    - Sets notification mode to "wave". This means
                          that whenever a song finishes playing, this DLL
                          will trigger mIRC's "on WAVEEND" event for your
                          script to handle. Any other waves playing from
                          mIRC will be stopped.
                midi    - The notification mode is set to "midi", which
                          means that when a song finishes playing, mIRC
                          will receive the "on MIDIEND" event, and any
                          MIDI file playing from mIRC will be stopped.
                          Probably a safer choice than the "wave" setting,
                          since the user will probably have more scripts
                          loaded that play wave files, rather than MIDI
                          files.
                mode?   - Does not change the setting, but returns the
                          name of the current notify mode.

                Note: If the queue is being used for playback and
                notification is enabled, "on MIDIEND" or "on WAVEEND"
                will trigger after EACH track, not just when the queue
                ends. By the time the event triggers, the next song will
                have started playing (or not, if the end of the queue
                has been reached and looping is disabled) -- therefore,
                to check if the music has completely stopped, use the
                "status" function of "CurrentMusic".

        Examples:

        //echo The volume is at $calc(100 * $gettok($dll(amp_in.dll,Misc,
                getvolume),2,32)/255) $+ %

        //echo The dialog currently open is $dll(amp_in.dll,Misc,box)

        //echo Notification mode to MIDI: $dll(amp_in.dll,Misc,notify midi)


FlushAllPlugins
        Parameters: none

        Stops playback, unloads all plugins, and unloads the DLL from
        memory. This will happen automatically when mIRC is closed, but
        you can use it if you are uninstalling your script and don't
        want to have to exit mIRC to unload everything.

        //echo Goodbye, WinAmp! $dll(amp_in.dll,FlushAllPlugins,.)
            
DLLInfo
        Parameters: none

        This just gives you my version info.

----
Here's some suggestions of what you can do with this other than making
just a mIRC version of WinAmp:

) Making a mIRC game? Use it to play other file formats as music.
) A ShoutCast script/bot that automatically takes requests from channel or
      private messages.
) mIRC has voice recognition support now; use that to control playback.

----
Known bugs:
        Does not work with the DeFX DSP plugin or innover RealAudio input
        plugin.

        NiceMC input plugin causes mIRC to quit if unloaded. (This is not my
        fault.)

        This isn't really a bug, but yes, I know there's no good way to
        move a file in the playlist. Give me a while.
----
Version info:
1.07    - Fixed a bug (dependency problem) that caused the DLL to not work
             on Windows 95
1.06    - Fixed a bug that caused mIRC to crash when trying to shuffle
             a queue of exactly one item
          Fixed a bug that caused playback to continue from a deleted
             queue item if the item was deleted while nothing was playing.
1.03    - Fixed a thread yielding problem which caused excessive CPU usage
1.00    - Initial release
