ANI (file format)

This article is about the file format. For other uses, see Ani (disambiguation).

ANI
The wait cursor in Windows 8.x, Windows 10, and Windows 11
Filename extension	.ani
Internet media type	application/x-navi-animation
Magic number	ACON (4 bytes, ASCII)
Developed by	Microsoft
Type of format	animated raster image format for mouse cursors
Container for	CUR frames

The ANI file format is a graphics file format used for animated mouse cursors on the Microsoft Windows operating system.

The format is based on the Microsoft Resource Interchange File Format, which is used as a container for storing the individual frames (which are standard Windows cursors) of the animation.

History

The concept of an animated mouse pointer originated on OS/2 Presentation Manager, whose animated pointers were produced by an early Microsoft animation tool later ported to Windows NT. The RIFF/ACON container was not part of the original 1991 RIFF specification; the ACON form type was registered by Microsoft in April 1993. Early third-party documentation described the AF_ICON flag in the anih header as selecting between two frame formats: with the flag set, each frame is a complete icon or cursor resource; without it, frames would be raw device-independent bitmaps described by the cx, cy, cBitCount and cPlanes header fields. This raw-bitmap mode did not appear in Microsoft's own published specification, however, and no version of Windows accepts a frame with the flag unset; in every animated cursor shipped with Windows the flag is set and those four header fields are zero.

The Animated Cursor Editor for Windows NT (ANIEDIT) provides a reference implementation of the ANI format. Its source code was distributed as a sample in the Windows SDK — as source only, with compiled binaries provided instead in the Windows 95 and Windows NT Resource Kits — and is preserved in the MSDN October 2001 Library.

The 16-bit Windows 3.x line had no animated cursor support of any kind. Windows NT 3.5 was the first version to load and display animated cursors, and shipped a set of ANI files — such as the animated hourglass — as part of its default cursor scheme; these early frames were 16-color (4 bpp) 32×32 images, some using a reversing "ping-pong" playback sequence. Windows 95 brought animated cursor support to the consumer line, adding a monochrome (1 bpp) fallback image to the first frame for display adapters running in 16 colors. On Windows 9x, animating a cursor required a protected-mode disk driver together with a suitable display driver; on systems lacking them the pointer was shown in color but did not animate.

Windows Vista introduced 32-bit color cursors with its Aero theme, and its animated cursors were the first to store several sizes within each frame so that a larger pointer could be drawn at higher display scaling — the built-in aero_busy.ani, for example, carries 32×32, 48×48 and 64×64 variants in every frame, for 100%, 150% and 200% scaling respectively.

File structure

An ANI file is a RIFF container with the chunk identifier ACON. It contains a mandatory animation header chunk (anih), a mandatory list of frame chunks (fram), and optional chunks for per-step timing (rate), frame sequencing (seq), and metadata (INFO).

#define AF_ICON     0x1

typedef struct {
    DWORD cbSizeof;           // 36
    DWORD cFrames;            // unique frame count
    DWORD cSteps;             // animation step count
    DWORD cx, cy;             // unused (legacy)
    DWORD cBitCount, cPlanes; // unused (legacy)
    DWORD jifRate;            // default rate in jiffies (1/60 s)
    DWORD fl;                 // AF_ICON (required); see Sequence and playback
} ANIHEADER;

RIFF('ACON'
    [LIST('INFO'
        [INAM(<ZSTR>)]        // title (optional)
        [IART(<ZSTR>)]        // author (optional)
    )]
    [DISP(<DWORD> <data>)]    // display preview (optional, defined in spec; unused in practice)
    'anih'(<ANIHEADER>)
    ['rate'(<DWORD[cSteps]>)]  // per-step rates in jiffies; see Timing
    ['seq '(<DWORD[cSteps]>)]  // per-step frame indices (0-based); see Sequence and playback
    LIST('fram'               // cFrames icon chunks
        'icon'(<icon_data_1>)
        'icon'(<icon_data_2>)
        ...
    )
)

The cbSizeof field must be exactly 36; any other value causes the file to fail to load. The anih chunk must appear before rate, seq , and the fram list; this is the only strict ordering constraint defined in the specification. The INFO list may contain standard RIFF metadata sub-chunks, including INAM (title) and IART (author). All are null-terminated strings encoded in ASCII or the system ANSI code page; the original RIFF specification defines ISO 8859/1 as the default. Windows ignores all INFO sub-chunks when loading a cursor; the metadata is only read by third-party editors.

Frames

The AF_ICON flag in anih is required and marks each frame in the fram list as a complete CUR-format resource. Because the frame format is identical to a standalone CUR file, a frame may contain images at multiple sizes within a single chunk — this capability is part of the original 1993 specification. Within each icon chunk, the dwImageOffset field of each directory entry is relative to the start of the chunk content and must fit within 16 bits.

cFrames must be at least 1; a value of 1 is treated as a static cursor. Both cFrames and cSteps are effectively 16-bit on modern Windows: non-zero upper bits cause the file to fail to load. Without a seq chunk, cSteps must not exceed cFrames; with one, every frame index in the table must be less than cFrames.

Because frames use the ICO/CUR image format, they may also contain PNG-compressed images since Windows Vista (see PNG format). PNG compression can reduce file size by around 40× compared to uncompressed BMP for typical semi-transparent cursors; existing Windows cursor tools only emit uncompressed BMP frames.

Timing

Frame rates are measured in jiffies, with one jiffy equal to 1/60 of a second, or approximately 16.7 ms. The anih header specifies a default rate (jifRate) applied to all steps. The optional rate chunk overrides this with a per-entry rate table, allowing individual frames to be held for different durations. The table must contain exactly cSteps entries.

Sequence and playback

The optional seq chunk contains a table of cSteps frame indices, mapping each animation step to a frame index and allowing frames to be played in any order and reused across multiple steps. For example, an animation with three unique images and the step sequence 0–1–2–1–0 only needs to store three frames while playing five steps, saving storage space. The fl field also carries a 0x2 bit, not part of Microsoft's own published specification but described in early third-party documentation as a sequence flag — conventionally referred to as AF_SEQUENCE — set when a seq chunk is present. It is informational only: Windows parses the seq chunk unconditionally whenever it appears, regardless of whether the bit is set.

When an ANI file is used as a Windows cursor, the sequence loops continuously; the fl field defines no play-once or other playback-control bits. An application can also draw a chosen animation step directly with the Win32 DrawIconEx function, whose istepIfAniCur parameter selects the frame index to render when the handle refers to an animated cursor.

Animated cursor resources

ANI files stored in Portable Executable binaries use the resource type RT_ANICURSOR (21) for animated cursors and RT_ANIICON (22) for animated icons. Unlike static icons and cursors, an animated cursor is embedded as a single unmodified RIFF/ACON blob rather than split into a group resource and individual frame resources. The Win32 LoadImage, LoadCursor, and CreateIconFromResource functions detect the RIFF/ACON signature automatically and route it to the ANI loader. In a resource-definition script, an animated cursor or icon is declared with the ordinary CURSOR or ICON statement pointing at the .ani file; the resource compiler recognises the animated format and emits an RT_ANICURSOR or RT_ANIICON resource rather than the static RT_CURSOR/RT_ICON group-and-image pair.

Security

Because Windows renders animated cursors automatically from files that may come from untrusted sources, the ANI parser has been the target of several remote-code-execution vulnerabilities. On January 11, 2005, Microsoft's security bulletin MS05-002 fixed three such flaws: insufficient validation of cursor, animated-cursor, and icon files could allow remote code execution (CVE-2004-1049) or crash the kernel (CVE-2004-1305) from a malformed file, and a specific stack-based buffer overflow in the animation-header length field of an ANI file could allow code execution (CVE-2005-0416); affected systems ranged from Windows NT through Windows Server 2003. In late March 2007, a further animated-cursor parsing flaw (CVE-2007-0038) — discovered by Alexander Sotirov of Determina Security Research — was disclosed and was already being exploited in the wild. It was a recurrence of the MS05-002 class of bug: the validation added in 2005 checked the length of only the first animation header, so a file carrying a second, malformed anih header bypassed the check and overflowed a fixed-size buffer. Microsoft released bulletin MS07-017 the following week, covering Windows 2000, Windows XP, Windows Server 2003, and Windows Vista. Later that year, a buffer overflow in the ANI handling of the third-party image viewer IrfanView 3.99 — showing the risk was not limited to Microsoft's own code — was assigned CVE-2007-1867.

See also

• Pointer (user interface)
• ICO (file format)
• List of icon software