AMIP Documentation

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.

Format Variables

Variables are prefixed with % char. You can use them in Presets, Callbacks and even files.

All the variables are case-sensitive. Also, if you want some text to follow your variable, like %brkbps, you should use a special separator char ~: %br~kbps.

Tags

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:

Tag Value
%1 Artist
%2 Title
%3 Track Number
%4 Album
%5 Year
%6 Comment
%7 Genre

File Info

In addition to the above tags, AMIP provides a lot of other information about song file, format specification, playlist and player state.

Variable Value
%name Song title and artist in ARTIST - TITLE format. ARTIST and TITLE are taken from any of the available tag types. If the file contains no supported tags, file name is used for %name (without extension). If playing unsupported file type or stream, title is taken from player (becomes %s).
%s Song title as returned by player, usually it's ARTIST - TITLE, but you can usually change it in your player preferences.
%fl File size in MB, like 3.56
%rawlenFile size in bytes, as returned by ftell
%fn Full file name with extension and path, like c:\song.mp3
%nm Name with extension (without path) (song.mp3)
%no File name only, without extension (song)
%ext File extension (mp3/wma/wav/vqf/etc)
%fdir Directory name (for C:\Music\Metallica\Best Of\Nothing-Else Matters.mp3 it will be set to "Best of")
%fupdir Up-directory name (for C:\Music\Metallica\Best Of\Nothing-Else Matters.mp3 it will be set to "Metallica")
%fpath File directory path, like C:\Music\Metallica\Best Of

Song Format

Variable Value
%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
%modeAdvanced version of %typ: Joint Stereo/Stereo/Mono/Dual Channel
%min Minutes component of song length (mm)
%sec Seconds component of song length (ss)
Use above together like %min:%sec
%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

Flags

Flags are either set to 1 or empty (return nothing), they should be used in the conditional statements.

Variable Value
%playing player is playing
%streamset 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
%mp4 MP4 format

Player/AMIP Info

Variable Value
%playerOne of Winamp/QCD/foobar2000/iTunes
%ver Player version (2.72)
%pv AMIP version (2.50)
%phwnd Player window HWND
%statNumeric player status (playing - 1, paused - 3, stopped - 0)
%tstatText 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
%ystamp current year
%monstamp current month
%prc current percentage of song being played
%repeat (on/off) repeat state
%shuffle (on/off) shuffle state
%ll Playlist length
%pos Current position in the playlist
%sl Song length in seconds
%sle Seconds left to play
%indexedNumber 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
iTunes specific:
%itrtSong rating (0-100)
%itpcSong playcount

Tag Versions

Variable Value
%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

EncSpot

If EncSpot is disabled in the Performance options most of these variables will be unavailable.

Variable Value
%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
%EMP Emphasis
%COM (yes/no) if file is complete (not broken)
%ERR number of sync errors
%CPR (yes/no) Copyrighted
%ORG (yes/no) Original
%CRC (yes/no) CRC
Lame header:
%MET Lame VBR method
%REV Lame tag revision
%LABR Lame ABR bitrate
%LQUA Lame quality (0..100)
%LAM (yes/no) lame header existance

mIRC Control Codes

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.

Code Description
&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)
&i Inverse color
&b Bold attribute

Some of the variables listed here may not work in your AMIP version. This documentation may contain variables and functions that appeared only in the recent builds. So, before reporting a bug please try the latest beta build first.


Functions

Formatting

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)).

You can use any character inside function except parentheses. Parentheses should be escaped with '\' character: $lc(/me is playing %name \(%7\)). If function has nested functions, you don't need to escape the parentheses of the inner function desciption: $ue($lc(%name) \(%7\)).

$lc(string)
Lower cases the string

$uc(string)
Upper cases the string

$cf(string)
Capitalizes First Letter Of Each Word In String

$u2s(string)
Converts %20 and underscores to spaces

$ue(string)
URL encodes the argument. Necessary to pass AMIP variables to the scripts via POST and GET

$next(string)
Provides information about the next song in the playlist (valid only if shuffle is disabled). Example: $next(next song: %name [%pos])

$pad(expr,n)
Pads the result of expr with n digits, for instance, $pad(%min,0) where %min is 01 gives 1

$trunc(text,len)
Truncates string by lenght and appends "…"

$trunc2(text,len,str)
Truncates and appends str if text is longer than len

$chr(dec)
Inserts ASCII character with specified decimal code

$enc(text,enc)
Encodes text to specified encoding. (encoding can be WIN, KOI, OEM, FIDO)

$strip(pattern,subject)
Removes all matches to pattern from subject

$strrep(search,replace,subject)
Returns a string with all occurrences of search in subject replaced with the given replace value

$regrep(pattern,replacement,subject)
Searches subject for matches to pattern and replaces them with replacement

$regmatch(subject,pattern,group)
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'.


Conditions

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 $function.

The most basic form is:
%?VARIABLE<TRUE|FALSE>

You should read it as: if %VARIABLE is not empty, then use TRUE, otherwise use FALSE, where TRUE and FALSE can be any parts of templates, can contain text, variables and functions.

Sample: %?4<"%4"|>
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:
%?VARIABLE='pattern'<TRUE|FALSE>

Basically, it's the same, but the condition is true if variable matches the pattern and is false otherwise.

Sample: %?id3v1='yes'<File has ID3v1 tag|No tag present>
Pattern must be enclosed in single quotes!

The limitation of the above syntax is that you can't use <, >, | chars in TRUE and FALSE parts.




You can also use the so called functional syntax of the above with some variations:

$if(a,b,c)
If a is not an empty string, b will be used, otherwise c: $if(%1,%1 - %2,%name).

$if2(a,b)
Same as $if(a,b,).

$if3(a,b)
Same as $if(a,a,b).

$mat(subj,patt)
Returns 1 if subject matches regexp pattern, otherwise returns empty string. Main purpose is to be used in conditional functions.
Sample: $if($mat(%id3v1,yes),File has ID3v1 tag,No tag present).

$iflen(str,len,shortstr)
If str is longer than len, use shortstr, otherwise use str.

You must escape parentheses and commas (if any) in function arguments with backslashes.


Commands

You can use action commands in Presets & Callbacks.

/cmsg
(mIRC specific) If format string starts with this command all output will be directed only to the list of channels specified in options.

/cme
(mIRC specific) Same as /cmsg, but as /me command.

/exec:(application) arguments
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.

/template:(input_file) output_file
Takes the input_file, replaces all the variables and functions and writes the result to output_file.

/fileonce:(filename) command
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 \n in command to write multiple lines into file.

/file:(filename) command
Writes log to file (appends to the file!).

For Russian users:

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.

Examples:

/fileonce:(c:\song_KOI.txt|KOI) np: %name
/fileonce:(c:\song_OEM.txt|OEM) np: %name
/template:(c:\song_win.txt|FIDO) c:\song_fido.txt

/msn(manual)title::artist::album
Use in callbacks to change text in MSN Messenger depending on the player state, replace title, artist and album with AMIP variables.

/msn(alt)format
Sends song info formatted according to format to the MSN Messenger.

/msn(clear)
Clears status in the MSN Messenger. For example, put in Pause callback to clear status when player is paused.

/skype format
Sends song info formatted according to format to Skype. Read tutorial for details.

/yahoo format
Sends song info formatted according to format to Yahoo! Messenger.

/gtalk format
Sends song info formatted according to format to Google Talk.

/aimstatus format
Sets AIM status message to text using format.

/aimprofile format
Sets AIM profile text to format.

/aimreplace format
Replaces %song in AIM profile with the specified text.

/aimrestoreprofile
Restores AIM profile to its original state.

/socket(host,port,timeout)message
Sends message to AMIP Remote client with the specified host, port and timeout. This allows to announce to multiple clients with different hosts/ports from one preset.

/flash(LAMP)
Flashes keyboard LAMP, LAMP can be NUM, SCROLL or CAPS.

/flash(LAMP,delay_ms,flash_ms,count)
For example, /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.

You can put multiple commands in one preset (command per line). It's also possible to comment out commands and other preset string using # character. AMIP will skip all the lines starting with the sharp char.


API Commands

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.

For example 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.

All the commands listed below are in the universal format, which is client independent, they must be prefixed with client specific calls in order to use with your client application.


Player Control

control >
Plays next entry.

control <
Plays previous.

control play
Starts playback.

control stop
Stops playback.

control pause
Pauses playback.

control vol x
Sets volume to x (0-255).

control rew
Rewind 5 sec.

control ff
Fast forward 5 sec.

control vup
Volume up.

control vdwn
Volume down.

control repeat
Toggles repeat.

control shuffle
Toggles shuffle.

setrepeat on/off
Sets repeat to on or off.

setshuffle on/off
Sets shuffle to on or off.

control exit
Shuts down the player. Supports Winamp, ITunes, QCD/QMP, Fooobar.

control minimize/restore
Minimize/restore player window.

jumptotime SS
Jumps to SS seconds from the start of the currently playing song.

setplpos index
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 autoplay is 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
Same as rfind, but doesn't support regular expressions.

play index
Plays song from the playlist with the specified index (1-based!).

getlistlength "" handler
Prints entire playlist length.

getlist idx_from idx_to
Prints a part of playlist from idx_from to idx_to.

reindex
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.

reindexq
Quietly re-indexes playlist in async mode (in background thread) without progress dialog. API call returns instantly.

reindexa
Same as reindexq, but progress dialog will be displayed.

clear
Clears local playlist (search results), and cached player playlist.

clearcache
Clears cached song information. Use if you want AMIP to re-read tag information from updated file without restart.

autoplay on/off
Toggles autoplay after find and rfind commands. If set to on, then AMIP will start playing the list of found songs automatically.

handler in the above functions allows you to specify the alias which will be used for client output. By default cmdstr config setting is used as output command (set to '/echo -s '). If you want to use this default alias, replace handler with "", otherwise specify your own alias (it should be a single command without spaces, like /myoutput).


Plugin Control

announce
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
Same as announce, but use preset N (1..5).

announcesong N
Announces song with playlist index N by invoking current preset.

announcesong N X
Announces song N by invoking preset X (1..5).

search
Shows AMIP search dialog.

options
Shows AMIP options screen. If AMIP Configurator is installed, it will be executed automatically instead of native options dialog which is obsolete.

control on
Enables AMIP.

control off
Disables AMIP.

getstrip
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 .

preset N
Changes active preset to N (1..5).

set "" str
Sets output preset to str value.

help
Displays the help.

manual page.htm
Displays page.htm from the AMIP chm help.

format handler format_string
Calls handler using format_string with variables (commands are not handled).

setdde server_name
Changes DDE Server name AMIP communicates with, DDE stack is automatically reinitialized.

setpirch on/off
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.

setmapping on/off
Changes the way how AMIP communicates with mIRC from DDE to FileMapping and back.

Some of the above commands (working with AMIP configuration) are obsolete, consider using the new API to work with configuration described in developers documentation. Also check the note about handler in Playlist Search section.

Last modified: 2008/07/04 14:45 by serge