Intro

1. "How do I install this?"
2. "I want AMIP to announce automatically when song changes in Winamp"
3. "I want to announce manually, only when I press hotkey in mIRC or type some command, how can I accomplish this?"
4. "I want to announce automatically, but only to the particular channels"
5. "Automatic announcement to all the channels"
6. Does AMIP support Trillian, ICQ, my_another_very_cool_client?
7. Integrating with mail clients and with anything else which can read from files
8. "I can't see AMIP output in mIRC, please help!"
9. Conditional statements
10. Searching for the song really quickly
11. Displaying song info in the active window title (experimental)
12. Conclusion
13. Uninstalling

0. Intro

Thank you for using AMIP! I hope you'll enjoy it! To make your life easier I wrote this quick start. It is based on the questions I frequently receive by e-mail or from AMIP forums.

These common questions (and of course my answers) will help you to set up plug-in very quickly. You will also know about some advanced AMIP features. So, let's start.

If you want to get access to all the AMIP options, please use AMIP Configurator, it is available from http://amip.tools-for.net/config/ , built-in options dialog allows to configure basic options only.

1. Installation "How do I install this?"

I assume that you've already installed it =), the main problem users usually get is installing AMIP Winamp 2 version on Winamp 3 and vice versa. There are 2 AMIP versions, each should be installed on the appropriate Winamp version. Please note, that AMIP Winamp 2 version will also probably work on Apollo. Actually, the installer is smart enough not to allow you to install on the improper Winamp version.

2. "I want AMIP to announce automatically when song changes in Winamp"

Probably it is not very wise way of configuration, because it can spam channels, but it is the default one and the most simple, so it is good to start with. See chapter 3 below for manual announcing.

To open options you can just type /dde mplug options in the IRC client. The other way is to browse Winamp preferences and find them there (Options | Preferences | Plug-ins | General Purpose, Advanced mIRC Integration Plug-in, for Winamp 2.x and Preferences | AMIP Wrapper for Winamp 3.x).

From AMIP version 2.30 I've changed the default output string format to:

//describe $active np: %name [%min:%sec~m/%br~Kbps/%sr~KHz]

This is more polite version, because it announces song info only to the active channel and doesn't advertise AMIP's homepage (Now you have to tell all your friends about AMIP manually :)).

Let's see what each part of this string does.

//describe - It is mIRC command, the same as /me but allows to specify the channel or nick

$active - mIRC variable which stands for the active channel you are currently chatting in. It can also be the query nick name.

All the rest part of this string is what you will get as your action text in the IRC client. This text contains variables which start with % sign, all the variables are described in this manual, for example:

%name is a song artist and title separated by " - ", if there is no tag, file name will be used as a value. It is quite universal and will work for most of files, you'll always see something as a value of this variable.

%min:%sec~m - for example the output of this will be 06:31m, please note that it is necessary to separate variable name from the rest of the text by ~ character. If you need to print ~ character in the IRC client, you need to use ~~ sequence in the preset.

%br is a bitrate, %sr is a sample rate. There are more than 100 another variables available for using in the presets.

Please note that the above string will work fine in mIRC 6, however if you will use /me instead of /describe $active it will not work. The problem is that mIRC 6 interprets the string passed by AMIP like if it was typed in the Status window, but mIRC 5.x automatically passes it to the active window.

Feel free to change the above string to anything you like. Read the appropriate sections of this manual to know how to use colors and other text attributes.

3. "I want to announce manually, only when I press hotkey in mIRC or type some command, how can I accomplish this?"

Well, this question is the most common one, so read very carefully =)

The first thing you probably want to do is to stop automatic announcing. There are several ways. You can just disable IRC integration or remove all the text from the preset. In the second case please be sure to choose some other preset than the first one, because the first one will be restored to the default value.

OK, now AMIP doesn't announce automatically and we need to make mIRC to announce when we press hotkey (or type some command). Fortunately AMIP is flexible enough to pass its variables to mIRC upon request. For the detailed information you can refer to the mIRC Scripting section, here I will describe the basics.

The easiest way is to use $dde variable with format option. Open mIRC aliases editor and type in the following:

F12 /me $dde(mPlug,format,"np:_%name_[%min:%sec~m/%br~Kbps/%sr~KHz]")

Now every time you hit F12, you'll get just the same as described in the previous chapter.

F12 is the hotkey, you can use some command instead of this, for example /mp3, /me is a mIRC command to say what you are doing. $dde has 3 arguments: mPlug is the AMIP dde server name, format is AMIP internal command, it tells AMIP that it should interpret the third parameter as a usual preset. The third parameter is the text with variables you want to be printed in mIRC. There is one important limitation, you can't use spaces in this parameter, all spaces must be replaced with the underscores. You can use all the other AMIP variables in it like in the usual preset.

In the mIRC scripting section you will find the complete script sample using this approach. It sets mIRC variables to AMIP variables using $dde and then build output line using only scripting language. This one is for advanced users who are keen at mIRC scripting. You can get full control over the AMIP options, get all the variables, control Winamp from your script, etc.

4. "I want to announce automatically, but only to the particular channels"

It is very simple. Open AMIP Options, you will see the channels list on the right, add channels to it using "+" button. Be sure to enter channel names with # character, like "#mycoolchannel".

Now, in the active preset change the command to /cme to announce in the form of action or to /msg to announce as a usual typed text. For example, the default string from chapter one in this case will look like:

/cme np: %name [%min:%sec~m/%br~Kbps/%sr~KHz]

Now AMIP will announce only to the specified list of channels, in despite of the channel you are currently chatting in (the active one).

5. "Automatic announcement to all the channels"

Be extremely careful! You can flood a lot of channels and you can get banned very quickly!
Now, if you realise what you are doing, here are the sample strings for you (first for action, second for the simple message):

/ame np: %name [%min:%sec~m/%br~Kbps/%sr~KHz]

/amsg np: %name [%min:%sec~m/%br~Kbps/%sr~KHz]

6. Does AMIP support Trillian, ICQ, my_another_very_cool_client?

The answer is yes! Every application in which you can paste from clipboard is automatically supported by AMIP.

All that you need is to specify preset #5 in AMIP Options, let's set it to "np: %name [%min:%sec~m/%br~Kbps/%sr~KHz]". It is not necessary to make this preset active.

Now press Ctrl+Alt+Z and the song info formatted according to the preset #5 will be pasted in the window just after the cursor.

By default AMIP uses Ctrl+V sequence for pasting, however if your applications doesn't accept Ctrl+V, but supports Shift+Insert, you need to press Ctrl+Alt+Z twice quickly. AMIP will switch keystroke for this particular application to Shift+Insert and will remember the name of this application. You will see window flashing when the keystroke is switched. To switch the keystroke back, just hit Ctrl+Alt+Z twice again. After some seconds the original content of the clipboard is automatically restored.

Probably you want to change Ctrl+Alt+Z shortcut to something else. Currently it is not possible directly from the options, however you can change it in the plugin.ini located in the Winamp plugins directory.
Make sure that Winamp is closed, open plugin.ini with your favorite text editor, find the line PasteHotkey=... and change the keystroke. Here is the brief description of special keys and modifiers which can be used:

control
shift
alt
win

backspace
tab
return
pause
escape
space
pageup
pagedown
end
home
left
up
right
down
printscreen
insert
delete

and the usual letters, digits and Fxx keys from F1 to F11. Note that F12 is reserved in latest Windows versions, however F12 can be used in combination with some modifier, like control f12.

For example you want to use Win+S as a paste shortcut, make the following change:

PasteHotkey=win s

7. Integrating with mail clients and with anything else which can read from files

Open AMIP Options, you will see MAIL integration controls group.

Specify the file you want AMIP to write to, for example e:\song.txt. Configure presets for each player state and that is all.

Now in your mail client find an option which allows to include text file as a part of your signature. Specify the there the same file.

Please note that you can write to multiple lines in the file by using \n as a line separator in the file presets.

8. "I can't see AMIP output in mIRC, please help!"

The main problem is that DDE Server name in mIRC Options doesn't match DDE Server name in the AMIP Options, make them equal, restart both mIRC and AMIP and all should work (In mIRC this setting is located under File | Options | General | Servers | DDE Server, also check that it is enabled).

Actually DDE communication is not the best way to pass info to mIRC, and AMIP supports the better way, which is faster and doesn't require any configuration of mIRC. To enable this way of communication, find and check the "direct send" checkbox in the AMIP options. This will help if DDE doesn't work on your system for some reason.

Please note that if you are using some other client from the supported clients list, such as Klient, Bersirc or PIRCH, you have to use DDE. For Klient and PIRCH there are special checkboxes in AMIP Options. For Bersirc you will need special DDE Wrapper which can be obtained from the AMIP's site. Be sure to read readme.txt from the wrapper archive.

Another problem is the preset. If you see the usual AMIP message in the status when you start Winamp but cannot see the song info, please check the preset.

9. Conditional statements

In the presets you can use so called conditional statements which allow you to choose which variable will be printed depending on the value of another variable.

For example:

%?7<%7|->

The above code will print song genre if it is specified, otherwise it will print -.

The format is %?variable_to_check<print_if_not_empty|print_if_empty>

One condition can be used inside another, AMIP supports unlimited nesting.

It is also possible to compare the variable with some value and then print one or another text depending on the comparation result:

%?LEN='^0$'<--:--:--|%LEN>

The string in single quotes is a perl compatible regular expression.

10. Searching for the song really quickly

You have thousands of mp3s in your playlist and want to listen to song which suites your current mood, or which suits the current moment, or you want to show some one in IRC that you have this song. AMIP again can help you.

You probably know that there is Jump to File dialog in Winamp (Called by J if Winamp window is active). But it has a lot of limitations. It is not convenient to activate Winamp every time you want to switch the song, Winamp 3 doesn't support this at all, also this Windows doesn't support searching non-english titles, etc.

AMIP provides the complete replacement for this dialog. Just hit Ctrl+J from any application and the windows popups. Enter the part of song title or artist name and choose the song you like. You can use up/down arrows and pgup/pgdown to navigate through the results. Focus will always remain in the edit control, so that you can do the search using only keyboard. Hit the Enter key to play selected song, window disappears and focus is automatically returned to the window you were working in.

You can use perl compatible regular expressions when performing search.

Wow! Now you can choose any song from thousands just within 2 seconds!

Ctrl+J shortcut can be changed in the plugin.ini as described in chapter 6, parameter name is RegexHotkey.

11. Displaying song info in the active window title (experimental)

Make sure that your player is not running, open plugin.ini, change CFG_DRAWONCAPTION value from 0 to 1.

Optional: change the format of the displayed text by modifying CFG_CAPTIONFORMAT variable.

12. Conclusion

I hope now you are able to use AMIP and have fun with it, for more advanced options, please read the rest sections of this manual.

13. Uninstalling

Go to Add/Remove programs, find AMIP in the list and remove it.