You can customize the the song information provided by AMIP and perform different actions using variables and functions listed below. Open AMIP Options and feel free to modify the presets. If you need the full power of AMIP, consider using AMIP Configurator.
Variables are prefixed with % char. You can use them in Presets, Callbacks and even files.
AMIP has built-in Tag parser supporting a lot of different formats of files and tags. The main song information is presented by the following tags:
In addition to the above tags, AMIP provides a lot of other information about song file, format specification, playlist and player state.
|%name|| Song title and artist in
|%s|| Song title as returned by player, usually it's
|%fl||File size in MB, like
|%rawlen||File size in bytes, as returned by ftell|
|%fn||Full file name with extension and path, like
|%nm||Name with extension (without path) (
|%no||File name only, without extension (
|%ext||File extension (mp3/wma/wav/vqf/etc)|
|%fdir||Directory name (for
|%fupdir||Up-directory name (for
|%fpath||File directory path, like
|%sr||Sampling frequency (KHz) (44)|
|%br||Bit-rate (Kbps) (128)|
|%typ||Song mode e.g. Stereo or Mono|
|%channels||1 for Mono, 2 for Stereo|
|%mode||Advanced version of
|%min||Minutes component of song length (mm)|
|%sec||Seconds component of song length (ss)|
|Use above together like
|%lver||Layer Version. e.g. Layer 3|
|%mver||Mpeg Version. e.g. MPEG Version 1|
|%head||32bit Mpeg header represented as a bitset. See www.mp3-tech.org for description|
|%at||Number of bytes from the file beginning where first mpeg header was found|
|%playing||player is playing|
|%stream||set to 1 when playing live stream (when song length is 0), otherwise is empty|
|%mp3||file is the mp3|
|%id3||ID3 tag present|
|%mac||Monkey audio file (.mac or .ape)|
|%ape||APEv1 or APEv2 tag presence|
|%flactag||FLAC tag presence|
|%flac||FLAC file (.fla or .flac)|
|%mpc||MusePack file format|
|%player||One of Winamp/QCD/foobar2000/iTunes|
|%ver||Player version (2.72)|
|%pv||AMIP version (2.50)|
|%phwnd||Player window HWND|
|%stat||Numeric player status (playing - 1, paused - 3, stopped - 0)|
|%tstat||Text player status|
|%mil||Minutes left (mm)|
|%sel||Seconds left (ss)|
|%page||URL of page where you can get latest Plug-In version|
|%vol||Player volume (0..255) now should work with any player|
|%ps||current song position (seconds)|
|%pm||current song position (minutes)|
|%psec||current song position in seconds|
|%hstamp||current time hours|
|%mstamp||current time minutes|
|%sstamp||current time seconds|
|%dstamp||current day of month|
|%prc||current percentage of song being played|
|%repeat||(on/off) repeat state|
|%shuffle||(on/off) shuffle state|
|%pos||Current position in the playlist|
|%sl||Song length in seconds|
|%sle||Seconds left to play|
|%indexed||Number of songs in AMIP internal playlist, mainly for API so that you can check how many songs are really indexed and reindex if this number doesn't match the lenght of the playlist|
|%itrt||Song rating (0-100)|
|%id3v1||(yes/no) ID3v1 tag|
|%id3v2||(yes/no) ID3v2 tag|
|%Lyrics||(yes/no) Lyrics tag|
|%Lyrics3v2||(yes/no) Lyrics3v2 tag|
|%MusicMatch||(yes/no) MusicMatch tag|
|%apev1||(yes/no) APE v1.0 tag|
|%apev2||(yes/no) APE v2.0 tag|
|%FLAC||(yes/no) FLAC tag|
|%mp4tag||(yes/no) MP4 tag|
|%ABR||Average bitrate of mp3 file (this also works for other file types)|
|%VBR||(yes/no) shows if file has VBR|
|%ENC||encoder used to make mp3 file|
|%LEN||(e.g. 00:03:19) song length|
|%FRQ||(e.g. 44100) Samlping frequency (hz)|
|%MOD||(e.g. joint stereo) Mode|
|%FRM||number of frames|
|%FSZ||(e.g. 4,157,036) file size in bytes|
|%TYP||(e.g. mpeg 1 layer III) - mpeg and layer version|
|%QUO||(good/ok/bad) a rough determination of the quality of the file. Determined solely by the encoder used, the bitrate, and the stereo mode|
|%COM||(yes/no) if file is complete (not broken)|
|%ERR||number of sync errors|
|%MET||Lame VBR method|
|%REV||Lame tag revision|
|%LABR||Lame ABR bitrate|
|%LQUA||Lame quality (0..100)|
|%LAM||(yes/no) lame header existance|
Using these special variables you can control the appearance of output to mIRC. More information about applying these codes you can find in mIRC Help File.
|&cXX,YY||X - foreground color, Y - background color. All text after this variable will be colored according to X and Y values (00 - 15). To discard color settings use another color or &p variable. Press Ctrl+K in mIRC for the color table. To avoid problems, be sure to use 2-digit codes, like &c01,05|
|&p||All control settings are discarded after this variable|
|&u||Underline the text between &u and the next &u (or the end of line if trailing &u is omitted)|
Functions should be written in
$name(param) form. For example
/me is listening to $lc(%name) will print song title in lower case.
One function can be inserted in another:
/me now playing $u2s($cf(%name)).
$lc(/me is playing %name \(%7\)). If function has nested functions, you don't need to escape the parentheses of the inner function desciption:
Lower cases the string
Upper cases the string
Capitalizes First Letter Of Each Word In String
Converts %20 and underscores to spaces
URL encodes the argument. Necessary to pass AMIP variables to the scripts via POST and GET
Provides information about the next song in the playlist (valid only if shuffle is disabled). Example:
$next(next song: %name [%pos])
Pads the result of expr with n digits, for instance, $pad(%min,0) where %min is 01 gives 1
Truncates string by lenght and appends "…"
Truncates and appends str if text is longer than len
Inserts ASCII character with specified decimal code
Encodes text to specified encoding. (encoding can be WIN, KOI, OEM, FIDO)
Removes all matches to pattern from subject
Returns a string with all occurrences of search in subject replaced with the given replace value
Searches subject for matches to pattern and replaces them with replacement
Matches subject against regexp pattern and returns the contents of parentheses group, use group = 0 for entire match. Sample:
$regmatch(text::other,\(.*?\)::.*,1) will return 'text'.
Conditional constructions allow you to choose what to put into preset text depending on some condition. Condition itself can be a flag, a variable or result of other function.
At the moment there are 2 different syntax constructions for conditions. One of them is specially designed for this, second form looks like a
The most basic form is:
You should read it as: if
%VARIABLE is not empty, then use
TRUE, otherwise use
FALSE can be any parts of templates, can contain text, variables and functions.
The above will print album name only in case if it's not empty.
More advanced form of the above uses regular expression pattern matching:
Basically, it's the same, but the condition is true if variable matches the pattern and is false otherwise.
%?id3v1='yes'<File has ID3v1 tag|No tag present>
Pattern must be enclosed in single quotes!
You can also use the so called functional syntax of the above with some variations:
If a is not an empty string, b will be used, otherwise c:
$if(%1,%1 - %2,%name).
Returns 1 if subject matches regexp pattern, otherwise returns empty string. Main purpose is to be used in conditional functions.
$if($mat(%id3v1,yes),File has ID3v1 tag,No tag present).
str is longer than
shortstr, otherwise use
(mIRC specific) If format string starts with this command all output will be directed only to the list of channels specified in options.
(mIRC specific) Same as
/cmsg, but as
Executes the application with specified command line
arguments. For example you can execute the FTP client to upload file, prepared by
/template command. Note: working directory is set to the directory of the application executable.
input_file, replaces all the variables and functions and writes the result to
Writes current song to file instead of mIRC. Useful to integrate AMIP with program without DDE, for example e-mail client, e.g in AMIP:
/fileonce:(e:\current.log)%name and in The Bat!:
Winamp is playing: %INCLUDE="e:\current.log" as a part of e-mail template. Use
command to write multiple lines into file.
Writes log to file (appends to the file!).
There is optional parameter - encoding, you can use it to write the file in the specified encoding (KOI, OEM, FIDO, WIN). This parameter must be placed after the file name using | as a separator. It is supported for file, fileonce and template commands.
/fileonce:(c:\song_KOI.txt|KOI) np: %name
/fileonce:(c:\song_OEM.txt|OEM) np: %name
Use in callbacks to change text in MSN Messenger depending on the player state, replace
album with AMIP variables.
Sends song info formatted according to
format to the MSN Messenger.
Clears status in the MSN Messenger. For example, put in Pause callback to clear status when player is paused.
Sends song info formatted according to
format to Skype. Read tutorial for details.
Sends song info formatted according to
format to Yahoo! Messenger.
Sends song info formatted according to
format to Google Talk.
Sets AIM status message to text using
Sets AIM profile text to
Replaces %song in AIM profile with the specified text.
Restores AIM profile to its original state.
Sends message to AMIP Remote client with the specified
timeout. This allows to announce to multiple clients with different hosts/ports from one preset.
LAMP can be NUM, SCROLL or CAPS.
/flash(NUM,0,200,5) will start flashing NUMLOCK with the initial delay 0, in each state (ON/OFF) lamp will be 200ms and will flash 5 times.
#character. AMIP will skip all the lines starting with the
These commands are universal and can be used from any client and via AMIP SDK. You can control player, AMIP, request song information, change AMIP configuration and so on.
The main difference is how commands are executed from client. It depends on the communication API being used and on the integration specifics.
control pause command triggers playback pause state.
Using mIRC DDE API:
/dde mplug control pause
/dde is mIRC built-in command,
mplug is AMIP DDE server name,
control pause is the command itself.
From mIRC Socket API (when ac.dll is installed), it can be invoked like:
/dll ac mexec control pause
/dll is mIRC command to invoke functions in libraries,
ac is the name of AMIP socket library (ac.dll),
mexec is ac library execution command,
control pause is again the API command.
Using AMIP Java SDK the code would look like:
Client c = Client.getInstance(); c.init(); c.execute("control pause");
If you are not sure how to use the below commands from your client, please consult the documentation which should be bundled with the integration you are using.
Plays next entry.
control vol x
Sets volume to x (0-255).
Rewind 5 sec.
Fast forward 5 sec.
Sets repeat to
Sets shuffle to
Shuts down the player. Supports Winamp, ITunes, QCD/QMP, Fooobar.
Minimize/restore player window.
Jumps to SS seconds from the start of the currently playing song.
Sets playlist position, index is 1-based.
The following API commands were designed to be used from the client command line (like mIRC command line). You can use them to search songs and play search results directly from your client.
rfind handler pattern
This command will find all songs from current playlist matching
pattern. Player starts to play matched songs (if
on, see below). Pattern may be a part of song title and is treated as regular expression. If AMIP has no cached playlist, it will be indexed automatically (see
index command below).
find handler keyword
rfind, but doesn't support regular expressions.
Plays song from the playlist with the specified
getlistlength "" handler
Prints entire playlist length.
getlist idx_from idx_to
Prints a part of playlist from
Re-indexes player playlist. If there are changes that AMIP can't detect automatically, invoke this command to synchronize AMIP playlist data with the actual player playlist. It may take some time to complete with large playlists (thousands of entries), therefore progress dialog is displayed. API command call returns only when indexing is finished and may timeout if it takes too long.
Quietly re-indexes playlist in async mode (in background thread) without progress dialog. API call returns instantly.
reindexq, but progress dialog will be displayed.
Clears local playlist (search results), and cached player playlist.
Clears cached song information. Use if you want AMIP to re-read tag information from updated file without restart.
Toggles autoplay after find and rfind commands. If set to on, then AMIP will start playing the list of found songs automatically.
handlerin the above functions allows you to specify the alias which will be used for client output. By default
cmdstrconfig setting is used as output command (set to
'/echo -s'). If you want to use this default alias, replace
"", otherwise specify your own alias (it should be a single command without spaces, like
Announces current song to the client using current preset. Works even when automatic announcing mode is off. This is the command you should use in mIRC and other clients to trigger song information display. For instance, in mIRC you can use it like
/dde mplug announce or
/dll ac mexec announce (if ac.dll is present). This can be aliased, for detailed mIRC instructions see this tutorial.
announce preset N
announce, but use preset
Announces song with playlist index
N by invoking current preset.
announcesong N X
N by invoking preset
Shows AMIP search dialog.
Shows AMIP options screen. If AMIP Configurator is installed, it will be executed automatically instead of native options dialog which is obsolete.
Displays current output preset value without the control codes.
cfg_enabled "" handler
Prints 1 if AMIP is enabled, 0 - otherwise.
cfg_convert "" handler
Prints 1 if convert check-box is enabled, 0 - otherwise.
cfg_strip "" handler
Prints 1 if strip check-box is enabled, 0 - otherwise.
getplain "" handler
Displays current output preset value.
getcodes "" handler
Displays current output string value translating &xx variables to control codes .
Changes active preset to
set "" str
Sets output preset to
Displays the help.
page.htm from the AMIP chm help.
format handler format_string
Calls handler using
format_string with variables (commands are not handled).
Changes DDE Server name AMIP communicates with, DDE stack is automatically reinitialized.
Allows to switch from mIRC to PIRCH mode and back. Note: you will need to call
setdde with appropriate server name to finish the process of IRC client switching.
Changes the way how AMIP communicates with mIRC from DDE to FileMapping and back.
handlerin Playlist Search section.