====== AMIP Documentation ======
You can customize the the song information provided by AMIP and perform different actions using variables and functions listed below. [[manual:installing#configuring_amip|Open AMIP Options]] and feel free to modify the presets. If you need the full power of AMIP, consider using [[manual:installing#installing_amip_configurator|AMIP Configurator]].

====== Format Variables ======
Variables are prefixed with **%** char. You can use them in **Presets**, **Callbacks** and even **files**. 
<note important>
All the variables are **case-sensitive**. Also, if you want some text to follow your variable, like **%br**kbps, you should use a **special separator char** **~**: **%br**''~''kbps.
</note>

===== 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  |
~~UP~~

===== 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''|
|%rawlen|File 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''|
~~UP~~


===== 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|
|%mode|Advanced 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|
~~UP~~

===== Flags =====
<note classic>
Flags are **either set to 1 or empty** (return nothing), they should be used in the [[manual:amip#conditions|conditional statements]].
</note>
^ Variable ^ Value ^
|%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  |
|%mp4| MP4 format |
~~UP~~


===== Player/AMIP Info =====
^ Variable ^ Value ^
|%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 |
|%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 |
|%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|
|**iTunes specific:**||
|%itrt|Song rating (0-100)|
|%itpc|Song playcount|
~~UP~~

===== 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 |
~~UP~~

===== EncSpot =====
<note important>
If **EncSpot** is disabled in the **Performance** options most of these variables will be **unavailable**.
</note>

^ 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 |
~~UP~~

===== 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  |

<note important>
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 [[amipdev:downloads|latest beta build]] first.
</note>
\\
~~UP~~

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

<note classic>
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\))''.
</note>

**''$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'.
~~UP~~
\\


===== 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!**

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

\\
\\
\\
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''.

<note important>
You must **escape parentheses and commas** (if any) in function arguments with backslashes.
</note>
~~UP~~
\\



===== Commands =====
You can use action commands in [[manual:configurator#presets|Presets]] & [[manual:configurator#callbacksweb|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!).

<note classic>
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''
</note>

**''/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 [[tutorials:skype|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.

<note tip>
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.
</note>

\\
~~UP~~

====== 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:
<code java>
Client c = Client.getInstance();
c.init();
c.execute("control pause");
</code>

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.

<note important>
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.
</note>
~~UP~~
\\



===== 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.
~~UP~~
\\

===== Playlist Search =====
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.

<note classic>
**''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'').
</note>
~~UP~~
\\




===== 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 [[tutorials:mirc_hotkey|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.

<note classic>
Some of the above commands (working with AMIP configuration) are **obsolete**, consider using the new API to work with configuration described in [[amipdev:doc|developers documentation]]. Also check the note about **''handler''** in [[manual:amip##playlist_search|Playlist Search]] section.
</note> 
~~UP~~