# SEQ BITS | VALUE BIT COUNT
    0          | 6
    1          | 9
    2          | 12
    3          | 20

• If the count of sequential bits is less than 3, skip past the bit whose value of 0 ends the sequential bits. The next value in the sequence follows this skipped bit.
• Otherwise, do not skip the 4th bit. It is part of the next value in the sequence.

    BIT COUNT | VALUE TO ADD
    6         | 1    (0x0001)
    9         | 65   (0x0041)
    12        | 577  (0x0241)
    20        | 4673 (0x1241)

This final numeric value is an offset, in BYTEs, within the destination buffer, subtracted from the buffer's current insertion point.

If the bit count is 20:

• If the numeric value is 1048575 (0x000FFFFF) before adding 4673, the end of the bit stream has been reached.
• Otherwise, increment the count of BYTEs to be decoded by 1, and continue with the next steps.

• If the 12th bit is 1, an error occured.
• Otherwise, continue with the next steps.

• Do not count the bit whose value of 0 ends the sequential bits. Skip past this bit. The next value in the sequence follows this skipped bit.
• The count of sequential bits is also the number of remaining bits in the sequence.

This final count is the number of BYTEs to copy from the above offset to the current insertion point. Copy the BYTEs one at a time, incrementing the insertion point after each BYTE, as the copying may overlap past the original insertion point.

COMPRESSION EXAMPLE

Binary values are typically written in order from most-significant bit to least-significant bit. In this example, they are written from least-significant bit to most-significant bit instead, to display the bits in processing order.

For example, a BYTE value of decimal 64 (hex 0x40) is typically written as 01000000 (MSB to LSB), but is written below as 00000010 (LSB to MSB) instead.

Here is an example of decoding a compressed block of Region Data from the ACSIMAGEINFO structure:

Compressed Data

    00 40 00 04 10 D0 90 80
    42 ED 98 01 B7 FF FF FF
    FF FF FF

Bit Stream

    00000010000000000010000000001000
    00001011000010010000000101000010
    10110111000110011000000011101101
    11111111111111111111111

Bit Stream Breakdown

    000000100 000000000 100000000
    010000000 10110000100 10000000101
    000010101 1011100011001 100000001110110
    111111111111111111111111

    SEQUENCE BITS        | DESCRIPTION
    0                    | single uncompressed BYTE
    00000100             | value = 0x20
                         |
    0                    | single uncompressed BYTE
    00000000             | value = 0x00
                         |
    1                    | compressed BYTE range
    0                    | offset bit count = 6, decoded BYTE count = 2
    000000               | offset = (0+1) BYTE
    0                    | increment decoded count by 0
    -                    | increment decoded count by 0
                         | copy (2+0+0) BYTEs from offset into buffer
                         |
    0                    | single uncompressed BYTE
    10000000             | value = 0x01
                         |
    1                    | compressed BYTE range
    0                    | offset bit count = 6, decoded BYTE count = 2
    110000               | offset = (3+1) BYTEs
    10                   | increment decoded count by 1
    0                    | increment decoded count by 0
                         | copy (2+1+0) BYTEs from offset into buffer
                         |
    1                    | compressed BYTE range
    0                    | offset bit count = 6, decoded BYTE count = 2
    000000               | offset = (0+1) BYTE
    10                   | increment decoded count by 1
    1                    | increment decoded count by 1
                         | copy (2+1+1) BYTEs from offset into buffer
                         |
    0                    | single uncompressed BYTE
    00010101             | value = 0xA8
                         |
    1                    | compressed BYTE range
    0                    | offset bit count = 6, decoded BYTE count = 2
    111000               | offset = (7+1) BYTEs
    110                  | increment decoded count by 3
    01                   | increment decoded count by 2
                         | copy (2+3+2) BYTEs from offset into buffer
                         |
    1                    | compressed BYTE range
    0                    | offset bit count = 6, decoded BYTE count = 2
    000000               | offset = (0+1) BYTE
    1110                 | increment decoded count by 7
    110                  | increment decoded count by 3
                         | copy (2+7+3) BYTEs from offset into buffer
                         |
    1                    | compressed BYTE range
    111                  | offset bit count = 20, decoded BYTE count = 3
    11111111111111111111 | 0x000FFFFF (end of bit stream)

Decoded Data

    20 00 00 00 01 00 00 00
    00 00 00 00 A8 00 00 00
    00 00 00 00 00 00 00 00
    00 00 00 00 00 00 00 00

    RGNDATAHEADER
        dwSize = 32
        iType = RDH_RECTANGLES
        nCount = 0
        nRgnSize = 168
        rcBound = {0, 0, 0, 0}

ACS Format

The ACS data format contains everything about the Character in a single file. An ACS file is designed for high performance, since all of the relavant data is stored in one place.

An ACS file should be installed on the machine that will be accessing it. On Windows machines, ACS files are installed in the "%WINDIR%\MSAgent\Chars\" folder by default, where "%WINDIR%" is the folder that Windows itself is installed in. ACS files can also be loaded into the MSAgent engine programmably from any path on the machine or local network.

In addition to the Common Data Structures, the ACS format includes the following structures:

ACSLOCATOR

The ACSLOCATOR structure is used to specify the exact location within the data file where a particular block of information can be found.

    DATA TYPE | QUANTITY | DESCRIPTION
    ULONG     | 1        | 0-based BYTE Offset from the Beginning of File
    ULONG     | 1        | Size of Data (in BYTEs)

ACSHEADER

The ACS data format begins with a header structure which identifies the data as being the ACS format. It contains the locations of the rest of the ACS data.

    DATA TYPE  | QUANTITY | DESCRIPTION
    ULONG      | 1        | Signature, Always 0xABCDABC3
    ACSLOCATOR | 1        | Location of ACSCHARACTERINFO Structure
    ACSLOCATOR | 1        | Location of ACSANIMATIONINFO List
    ACSLOCATOR | 1        | Location of ACSIMAGEINFO List
    ACSLOCATOR | 1        | Location of ACSAUDIOINFO List

ACSCHARACTERINFO

The ACSCHARACTERINFO structure describes the dimensions and characteristics of the Character.

    DATA TYPE         | QUANTITY    DESCRIPTION
    USHORT            | 1           Minor Version
    USHORT            | 1           Major Version
    ACSLOCATOR        | 1           Location of LOCALIZEDINFO List
    GUID              | 1           Unique Identifier for the Character
    USHORT            | 1           Character Width (in pixels)
    USHORT            | 1           Character Height (in pixels)
    BYTE              | 1           0-based Index of Transparent Color in Color Table
    ULONG             | 1           Flags
    USHORT            | 1           Animation Set Major Version?
    USHORT            | 1           Animation Set Minor Version?
    VOICEINFO         | 1           Voice Output Info (if enabled)
    BALLOONINFO       | 1           Word Balloon Info (if enabled)
    PALETTECOLOR      | LIST        Color Table
    BOOL              | 1           System Tray Icon is Enabled
    TRAYICON          | 1           System Tray Icon (if enabled)
    STATEINFO         | LIST        Animation States

The Flags value is comprised of the following bits:

    BITS  | DESCRIPTION
    0-3   | unknown
    4     | Voice Output
          |     0 = disabled
          |     1 = enabled
    5-7   | unknown
    8, 9  | Word Balloon disabled/enabled (respectively)
          |     (I don't know why Microsoft separates these bits)
    10-15 | unknown
    16-18 | Word Balloon Styles
          |     Can contain any combination of the following:
          |         0x01 = size to text enabled
          |         0x02 = auto hide disabled
          |         0x04 = auto pace disabled
    19    | unknown
    20    | Standard Animation Set
          |     0 = not supported
          |     1 = supported
    21-31 | unknown 

The Animation Set Major Version has been observed as always being 2, and the Minor Version as begin 0.

ACSOVERLAYINFO (List Count: BYTE)

The ACSOVERLAYINFO structure describes information about a particular mouth overlay for an animation frame. Mouth overlays are displayed only during the Character's spoken TTS output.

    DATA TYPE | QUANTITY | DESCRIPTION
    BYTE      | 1        | Overlay Type
    BOOL      | 1        | Replace the Top Image of the Frame
    USHORT    | 1        | 0-based Index of Image in ACSIMAGEINFO List from the ACSHEADER structure
    BYTE      | 1        | unknown
    BOOL      | 1        | Region Data is Present
    SHORT     | 1        | X-offset from top of Frame (in pixels)
    SHORT     | 1        | Y-offset from top of Frame (in pixels)
    USHORT    | 1        | Width (in pixels)
    USHORT    | 1        | Height (in pixels)
    DATABLOCK | 1        | Region Data (if present)

The Overlay Type can be one of the following:

    0x00 = mouth closed
    0x01 = mouth wide open 1
    0x02 = mouth wide open 2
    0x03 = mouth wide open 3
    0x04 = mouth wide open 4
    0x05 = mouth medium
    0x06 = mouth narrow

The Unknown value has been observed as usually being 0.

The Region data is a RGNDATA structure.

A frame can be composited using multiple images. If the "Replace Top Image" flag is enabled, the top-most image defined for the frame is substituted with the overlay image. Otherwise, the overlay image is placed over the frame's top-most image instead.

Note: The Width and Height are expressed as values that have been divided by 2. I do not know why Microsoft is doing that.

ACSFRAMEIMAGE (List Count: USHORT)

The ACSFRAMEIMAGE structure describes a particular image used for an animation frame. A frame can be composited using multiple images, and a single image can be shared by multiple frames.

    DATA TYPE | QUANTITY | DESCRIPTION
    ULONG     | 1        | 0-based Index of Image in ACSIMAGEINFO List from the ACSHEADER structure
    SHORT     | 1        | X-offset from Top of Frame (in pixels)
    SHORT     | 1        | Y-offset from Top of Frame (in pixels)

ACSFRAMEINFO (List Count: USHORT)

The ACSFRAMEINFO structure describes a particular frame in an animation sequence.

    DATA TYPE      | QUANTITY | DESCRIPTION
    ACSFRAMEIMAGE  | LIST     | Images used to Composite the Frame
    USHORT         | 1        | 0-based Index in ACSAUDIOINFO List from the ACSHEADER structure
    USHORT         | 1        | Frame Duration (in 1/100 seconds)
    SHORT          | 1        | 0-based Index of Frame to Exit to in Animation
    BRANCHINFO     | LIST     | Frame Branches
    ACSOVERLAYINFO | LIST     | Mouth Overlays

The Frame Images are composited in reverse order from last to first.

Refer to the "Designing Characters for Microsoft Agent" documentation provided by Microsoft for more information regarding how Exit Frames work.

Note: the Exit Frame index may be -2. I am not sure the significance of this value yet, but it seems to only appear in the last frame(s) of an animation

ACSANIMATIONINFO (List Count: ULONG)

The ACSANIMATIONINFO structure describes information about a particular animation.

    DATA TYPE  | QUANTITY | DESCRIPTION
    STRING     | 1        | Animation Name
    ACSLOCATOR | 1        | Location of Animation Information

    DATA TYPE         QUANTITY    DESCRIPTION
    STRING            1           Animation Name (in uppercase)
    BYTE              1           Transition Type
    STRING            1           Return Animation (in uppercase)
    ACSFRAMEINFO      LIST        Animation Frames

The Transition Type can be one of the following values:

    0x00 = use return animation
    0x01 = use exit branches
    0x02 = no transition

Refer to the "Designing Characters for Microsoft Agent" documentation provided by Microsoft for more information regarding how Animation Transitions work.

ACSIMAGEINFO (List Count: ULONG)

The ACSIMAGEINFO structure describes information about a particular frame image.

    DATA TYPE  | QUANTITY | DESCRIPTION
    ACSLOCATOR | 1        | Location of Image Information
    ULONG      | 1        | Checksum?

    DATA TYPE   | QUANTITY | DESCRIPTION
    BYTE        | 1        | unknown
    USHORT      | 1        | Width (in pixels)
    USHORT      | 1        | Height (in pixels)
    BOOL        | 1        | Image Data is Compressed
    DATABLOCK   | 1        | Image Data
    COMPRESSED  | 1        | Region Data

The Unknown value has been observed as begin either 0 or 1.

The Image Data is the raw bitmap bits. Refer to the Win32 API documentation for the BITMAPINFOHEADER structure for details about how the bits are formatted. The Image Data has 1 Plane and a Bit Count of 8, and does not use any pixel compression.

If the Image Data is compressed, the number of BYTEs needed for allocating a suitable buffer prior to decompressing the data can be calculated by rounding the Image Width up to a ULONG boundary and then multiplying it by the Image Height. For example:

    ((Width + 3) & 0xFC) * Height)

The Region Data is a RGNDATA structure.

ACSAUDIOINFO (List Count: ULONG)

The ACSAUDIOINFO structure describes information about a particular block of waveform audio.

    DATA TYPE  | QUANTITY | DESCRIPTION
    ACSLOCATOR | 1        | Audio Data
    ULONG      | 1        | Checksum?

Refer to the RIFF Audio section for details about the format used for audio data.

ACF Format

The ACF data format contains just the Character's core information. The animation data is stored in separate ACA files, one for each animation. ACF/ACA files are designed to be download from a remote location, such as an HTTP server, and thus are relatively small to reduce network traffic. Because the animations are stored separately, they must be downloaded before they can be played. On the other hand, the benefit is that they can be downloaded individually on an as-needed basis without having to download all of the Character's data beforehand, unlike with ACS files which have to be loaded in full.

In addition to the Common Data Structures, the ACF format includes the following structures:

ACFHEADER

The ACF data format begins with a header structure which identifies the data as being the ACF format.

    DATA TYPE  | QUANTITY | DESCRIPTION
    ULONG      | 1        | Signature, Always 0xABCDABC4
    COMPRESSED | 1        | Character Data

The Character Data is an ACFCHARACTERINFO structure.

ACFANIMATIONINFO (List Count: USHORT)

The ACFANIMATIONINFO structure specifies the name of the ACA file for a particular animation.

    DATA TYPE | QUANTITY | DESCRIPTION
    STRING    | 1        | Animation Name
    STRING    | 1        | ACA Filename
    STRING    | 1        | Return Animation (in uppercase)
    ULONG     | 1        | ACA Checksum

The ACA filename has no folder path included in it. ACA files must be stored in the same folder as the ACF file.

The Checksum value matches the checksum in the ACAHEADER structure of the ACA file.

• At the time of this writing, the algorithm used for calculating the Checksum has not been determined yet.

ACFCHARACTERINFO

The ACFCHARACTERINFO structure describes the dimensions and characteristics of the Character.

    DATA TYPE        | QUANTITY | DESCRIPTION
    USHORT           | 1        | Minor Version
    USHORT           | 1        | Major Version
    ACFANIMATIONINFO | LIST     | Animations
    GUID             | 1        | Unique Identifier for the Character
    LOCALIZEDINFO    | LIST     | Character Localized Info
    USHORT           | 1        | Character Width (in pixels)
    USHORT           | 1        | Character Height (in pixels)
    BYTE             | 1        | 0-based Index of Transparent Color in Color Table
    ULONG            | 1        | Flags
    USHORT           | 1        | Animation Set Major Version?
    USHORT           | 1        | Animation Set Minor Version?
    VOICEINFO        | 1        | Voice Output Info (if enabled)
    BALLOONINFO      | 1        | Word Balloon Info (if enabled)
    PALETTECOLOR     | LIST     | Color Table
    BOOL             | 1        | System Tray Icon is Enabled
    TRAYICON         | 1        | System Tray Icon (if enabled)
    STATEINFO        | LIST     | Animation States

The Flags are comprised of the following bits:

    BITS  | DESCRIPTION
    0-3   | unknown
    4     | Voice Output
          |    0 = disabled
          |    1 = enabled
    5-7   | unknown
    8, 9  | Word Balloon disabled/enabled (respectively)
          |    (I don't know why Microsoft separates these bits)
    10-15 | unknown
    16-18 | Word Balloon Styles
          |    Can contain any combination of the following:
          |        0x01 = size to text enabled
          |        0x02 = auto hide disabled
          |        0x04 = auto pace disabled
    19    | unknown
    20    | Standard Animation Set
          |    0 = not supported
          |    1 = supported
    21-31 | unknown 

ACA Format

The ACA data format contains information about a specific animation for a Character that is described in a separate ACF file.

In addition to the Common Data Structures, the ACA format includes the following structures:

ACAHEADER

The ACA data format begins with a header structure which identifies the data as being the ACA format.

    DATA TYPE | QUANTITY | DESCRIPTION
    USHORT    | 1        | Minor Version
    USHORT    | 1        | Major Version
    ULONG     | 1        | Checksum
    BOOL      | 1        | Animation Data is Compressed
    BYTE      | variable | Animation Data

The Checksum value matches the checksum in the ACFANIMATIONINFO structure of the ACF file.

• At the time of this writing, the algorithm used for calculating the Checksum has not been determined yet.

The Animation Data is an ACAANIMATIONINFO structure. If it is compressed, it is inside of a COMPRESSED structure. Otherwise, it is just the ACAANIMATIONINFO structure by itself.

ACAIMAGEINFO (List Count: USHORT)

The ACAIMAGEINFO structure describes information about a particular frame image.

    DATA TYPE | QUANTITY | DESCRIPTION
    ULONG     | 1        | Size of Image Data (in BYTEs)
    BYTE      | 1        | unknown
    BYTE      | variable | Image Data
    DATABLOCK | 1        | Region Data

The Unknown value has been observed as always being 0.

The Image Data is the raw bitmap bits. Refer to the Win32 API documentation for the BITMAPINFOHEADER structure for details about how the bits are formatted. The Image Data has 1 Plane and a Bit Count of 8, and does not use any pixel compression.

The Region Data is a RGNDATA structure.

ACAAUDIOINFO (List Count: USHORT)

The ACAAUDIOINFO structure describes information about a particular block of waveform audio.

    DATA TYPE | QUANTITY | DESCRIPTION
    DATABLOCK | 1        | Audio Data

Refer to the RIFF Audio section for details about the format used for audio data.

ACAOVERLAYINFO (List Count: BYTE)

The ACAOVERLAYINFO structure describes information about a particular mouth overlay for an animation frame. Mouth overlays are displayed only during the Character's spoken TTS output.

    DATA TYPE | QUANTITY | DESCRIPTION
    BYTE      | 1        | Overlay Type
    BYTE      | variable | Base Image Info (present only if Overlay Type is 0x00)
    ULONG     | 1        | Size of Image Data (in BYTEs)
    BYTE      | 1        | unknown
    BOOL      | 1        | Region Data is Present
    SHORT     | 1        | X-offset from top of Frame (in pixels)
    SHORT     | 1        | Y-offset from top of Frame (in pixels)
    USHORT    | 1        | Width (in pixels)
    USHORT    | 1        | Height (in pixels)
    BYTE      | variable | Image Data
    DATABLOCK | 1        | Region Data (if present)

The Overlay Type can be one of the following:

    0x00 = mouth closed
    0x01 = mouth wide open 1
    0x02 = mouth wide open 2
    0x03 = mouth wide open 3
    0x04 = mouth wide open 4
    0x05 = mouth medium
    0x06 = mouth narrow

If the Overlay Type is 0x00, the Base Image Info is present, as is defined as the following

    DATA TYPE | QUANTITY | DESCRIPTION
    BOOL      | 1        | Replace the Top Image of the Frame
    BYTE      | variable | Base Image Data

If the "Replace Top Image" is 0x00, the Base Image Data is not present. Otherwise, it is defined as the following:

    DATA TYPE | QUANTITY | DESCRIPTION
    DATABLOCK | 1        | Base Image Data
    DATABLOCK | 1        | Base Region Data

Unlike frames in ACS files, frames in ACA files do not contain a list of multiple images. If multiple images are specified when the frame is defined by the character author, they are composited into a single image when the ACA file is compiled. If the "Replace Top Image" flag is 0x00, the overlay image is placed on top of the frame image specified by the ACAFRAMEINFO structure. If the "Replace Top Image" flag is not 0x00, the Base Image for the overlay is the complete frame image without the top image present. The Overlay is placed on top of this Base Image rather than the frame image specified by the ACAFRAMEINFO structure.

The Unknown value has been observed as always being 0.

The Image Data is the raw bitmap bits. Refer to the Win32 API documentation for the BITMAPINFOHEADER structure for details about how the bits are formatted. The Image Data has 1 Plane and a Bit Count of 8, and does not use any pixel compression.

Note: The Width and Height are expressed as values that have been divided by 2. I do not know why Microsoft is doing that.

ACAFRAMEINFO (List Count: USHORT)

The ACAFRAMEINFO structure describes a particular frame in an animation sequence.

    DATA TYPE      | QUANTITY | DESCRIPTION
    USHORT         | 1        | 0-based Index of Image in ACAIMAGEINFO List from the ACAANIMATIONINFO structure
    USHORT         | 1        | 0-based Index of Audio in ACAAUDIOINFO List from the ACAANIMATIONINFO structure
    USHORT         | 1        | Frame Duration (in 1/100 seconds)
    ULONG          | 1        | unknown
    SHORT          | 1        | 0-based Index of Frame to Exit to in Animation
    BRANCHINFO     | LIST     | Frame Branches
    ACAOVERLAYINFO | LIST     | Mouth Overlays

The Unknown value has been observed as always being 0.

ACAANIMATIONINFO

The ACAANIMATIONINFO structure describes the characteristics of the Animation.

    DATA TYPE    | QUANTITY | DESCRIPTION
    ACAAUDIOINFO | List     | Frame Sounds
    ACAIMAGEINFO | List     | Frame Images
    BYTE         | 1        | Transition Type
    ACAFRAMEINFO | LIST     | Animation Frames

The Transition Type can be one of the following values:

    0x00 = use return animation
    0x01 = use exit branches
    0x02 = no transition

Specification Change History

November 6, 2022 - Version 1.6 released publicly

• Updating Copyright.
• Updated links to MSDN documentation.
• Updated Data Types section to add BOOL.
• Fixed a typo in GUID definition.
• Updated Common Data Structures section to add COMPRESSED structure.
• Added some clarifications in the Compression Algorithm section.
• Miscellaneous formatting changes.

February 25, 2021 - Version 1.5 released publicly

• Updating Copyright.

December 14, 2020 - Version 1.4 released publicly

May 10, 2017 - Version 1.4 (not released yet)

• Added links to MSDN documentation for Win32 API structures.
• ACFCHARACTERINFO structure:
      Added fields for VOICEINFO, BALLOONINFO, and TRAYICON.
• ACAANIMATIONINFO structure:
      The Quantity of Animation Frames has been corrected to be LIST instead of 1.
• ACAOVERLAYINFO structure:
      Correcting the offset of the Overlay Type field.

June 10, 2009 - Version 1.3 released publicly

November 15, 2006 - Version 1.3 (not released yet)

• Specification re-written in HTML format.
• Updated Data Types section to include a note about the endian format used.
• ACS Format
  
  • Added additional structures to describe Image and Audio data.
  • Added new section to describe the Compression Algorithm.
  • Header structure:
        The unknown fields have been identified as ACSLOCATORs to ACSIMAGEINFO and ACSAUDIOINFO Lists.
  • ExtraCharacterInfo structure:
        Renamed to LOCALIZEDINFO.
  • ExitBranchInfo structure:
        Renamed to BRANCHINFO. This is no longer specific to an exit branch.
  • OverlayInfo structure:
        The index field has been corrected to be an index into the ACSIMAGEINFO List from the ACSHEADER structure.
  • FrameInfo structure:
        The unknown fields have been identified as an ACSFRAMEIMAGE List, and an index into the ACSAUDIOINFO List from the ACSHEADER structure.
• ACF and ACA Formats
  
  • Added to the specification.

June 18, 2004 - Version 1.2 (not released yet)

• Added quantity column to structure definitions.
• AnimationInfo structure:
      The unknown fields have been identified as an ACSLOCATOR to extended animation info.

March 14, 2004 - Version 1.1 released publicly

• VoiceInfo structure:
      The unknown field has been identified as a Flag indicating whether the remaining Voice data is present.
• CharacterInfo structure:
      The unknown fields surrounding the Color Table flag have been identified as being the actual number of colors in the color table.
• Footer structure:
      Renamed structure to ExtraCharacterInfo and added ExtraCharacterInfoList structure.

March 31, 2003 - Version 1.0 released publicly