Miaottie

CN: README_CN.md

A lightweight library to pack and unpack Lottie JSON. It extracts image assets from the Lottie JSON, bundles them into a binary payload, and supports optional compression, lazy asset loading, and running in both browsers and Node.

Features

• Separates and bundles Lottie assets (base64 or remote) into a binary payload
• Optional compression: Zstd or Deflate; uses native CompressionStream/DecompressionStream when available, falls back to pako
• Versioned binary container with a fixed header and metadata for validation and extension
• Lazy asset loading that creates Blob URLs on demand with a unified cleanup function

Install

npm i miaottie
pnpm add miaottie
yarn add miaottie

Quick Start

Pack a Lottie JSON into binary:

import { MiaottiePacker } from 'miaottie'

const packer = new MiaottiePacker({
  // configure if needed
})

const data: Uint8Array = await packer.pack(lottieJson)

Unpack binary back to a Lottie object:

import { MiaottieLoader, useMiaottieV1Unpacker } from 'miaottie'

const unpacker = await useMiaottieV1Unpacker({ lazyAssets: true })
const loader = new MiaottieLoader({ unpackerArr: [unpacker] })

const { lottie, destoryLottie } = await loader.unpack(data)
destoryLottie()

API Overview

• MiaottiePacker

  • Constructor options:
    • AllowDownloadPrefix?: string[] default ['http', 'https']
    • CompressType?: 0 | 1 | 2 equals None | Zstd | Deflate
    • CompressLevel?: number ranges: Zstd -13~22, Deflate 1~10
  • Methods:
    • pack(lottie: any): Promise<Uint8Array>
  • Static: VERSION = 1

• useMiaottieV1Unpacker(options?)

  • options.lazyAssets?: boolean default true
  • Returns { version, handle } for MiaottieLoader

• MiaottieLoader

  • new MiaottieLoader({ unpackerArr: [unpacker] })
  • unpack(data: Uint8Array) returns { lottie, destoryLottie }

File Format (V1)

The .miaottie file contains:

• 4-byte header: 0x38 0x35 0x27 0x21
• 1-byte version
• Payload encoded by msgpack:
  • c: compression type
  • a: asset array with items { i: string, d: Uint8Array }
  • l: msgpack-ed Lottie JSON without assets

Compatibility & Notes

• Environments: modern browsers and Node 18+
• Compression/Decompression: prefers native CompressionStream/DecompressionStream, falls back to pako
• Zstd: implemented via zstd-codec (WASM) for browsers and Node
• Remote assets: during pack, assets are downloaded via fetch if allowed by AllowDownloadPrefix; in Node, ensure global fetch or use a polyfill
• Resource cleanup: call destoryLottie() to release Blob URLs and memory

License

MIT