libpag Documentation

The official rendering library for PAG (Portable Animated Graphics) files that renders After Effects animations natively across multiple platforms.

5,803 stars HTML HTML 3 files · ~3,970 tokens #after-effects#animation#keyframes#libpag#pag
RAW Doc

Technical Documentation: Tencent/libpag

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md)






English | 简体中文 | Homepage

Introduction

libpag is a real-time rendering library for PAG (Portable Animated Graphics) files, capable of
rendering both vector-based and raster-based animations across various platforms, including iOS,
Android, OpenHarmony, macOS, Windows, Linux, and the Web.

PAG is an open-source file format designed for recording animations. You can create and export PAG
files from Adobe After Effects using the PAGExporter plugin and preview them in the PAGViewer app,
both available on macOS and Windows.

PAG is widely used in major Tencent apps like WeChat, Mobile QQ, Honor of Kings, Tencent Video, and
QQ Music, as well as in thousands of third-party apps, reaching hundreds of millions of users.

Advantages

  • Highly efficient file format

Benefiting from its highly efficient binary format, PAG files decode 10 times faster than JSON files
and are about 50% smaller in file size for the same animations. Designers can also easily include
beautiful animations with bitmaps or audiovisual media in a single file without needing additional
attachments.

  • All AE features supported

While other solutions may only support exporting limited vector-based AE features, PAG combines
vector-based and raster-based exporting techniques to support all AE animations in a single file.
This means third-party plugin effects in AE can also be exported.

  • Measurable performance

PAG provides a monitoring panel in PAGViewer that displays normalized performance data for PAG files,
making it easy for designers to review and optimize performance without needing developers. With
numerous automatic optimization techniques from the PAGExporter plugin, you can create animations
with impressive visual effects and excellent performance more efficiently.

PAGViewer includes a monitoring panel

  • Runtime editable animations

With the flexible editing APIs from the PAG SDK, developers can easily modify the layer structure of
a single PAG file, combine multiple PAG files into one composition, or replace text and images with
all pre-designed animation effects applied at runtime. This significantly reduces the coding work
required for features like video templates.

System Requirements

  • iOS 15.0+
  • Android 5.0+
  • HarmonyOS Next 5.0.0(12)+
  • macOS 12.0+
  • Windows 7.0+
  • Chrome 69.0+ (Web)
  • Safari 15.0+ (Web)

Getting Started

We currently only publish precompiled libraries for iOS, Android, macOS, Web, and OpenHarmony. You
can build libraries of other platforms from the source code. The latest releases can be downloaded
from here.

iOS Integration

You can download the framework from the release page or add libpag to your project using CocoaPods.
To add the pod to your Podfile, include:

text
pod 'libpag'

And then run:

text
pod install

After installing the CocoaPod, import libpag into your project with:

text
#import <libpag/xxx.h>

Android Integration

You can download the AAR from the release page or add libpag to your project using Maven:

Edit the build.gradle file in the root of your project and add mavenCentral() to the repositories section:

text
buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.2.1'
    }
}

Add libpag to app/build.gradle (4.0.5.10 should be replaced with the latest release version):

text
dependencies {
    implementation 'com.tencent.tav:libpag:4.0.5.10'
}

Add the following rule to your proguard rules to prevent incorrect obfuscation:

text
-keep class org.libpag.** {*;}
  -keep class androidx.exifinterface.** {*;}

Finally, run gradle sync and build your project.

OpenHarmony Integration

You can download the HAR file from the release page,
or add libpag to your project using OHPM:

text
ohpm install @tencent/libpag

Alternatively, you can add it to your project manually. Add the following lines to oh-package.json5
in your app module.

text
"dependencies": {
"@tencent/libpag": "^1.0.1",
}

Then run:

text
ohpm install

Web Integration

Copy the following code into an HTML file and open it in your browser:

html
<canvas class="canvas" id="pag"></canvas>
<script src="https://unpkg.com/libpag@latest/lib/libpag.min.js"></script>
<script>
  window.libpag.PAGInit().then((PAG) => {
    const url = 'https://pag.io/file/like.pag';
    fetch(url)
      .then((response) => response.blob())
      .then(async (blob) => {
        const file = new window.File([blob], url.replace(/(.*\/)*([^.]+)/i, '$2'));
        // Do Something.
      });
  });
</script>

More information：Web SDK Guide

Example

Explore these projects to learn how to use the libpag APIs:

Documentation

You can find additional documentation on pag.io

Development

We recommend using the CLion IDE on macOS for development.

Branch Management

  • The main branch is our active development branch, containing the latest features and bug fixes.
  • The release/ branches are our stable milestone branches, fully tested. We periodically create a
    release/{version} branch from the main branch. After a release/{version} branch is created,
    only high-priority fixes are checked into it.

Note: This repository only contains the latest code since PAG 4.0. For legacy PAG 3.0 versions,
you can download the precompiled libraries from here.

Build Prerequisites

  • Xcode 13.0+
  • GCC 9.0+
  • Visual Studio 2019+
  • NodeJS 14.14.0+
  • Ninja 1.9.0+
  • CMake 3.13.0+
  • QT 6.2.0+
  • NDK 28+ (28.0.13004108 recommended)
  • Emscripten 3.1.58+

Dependency Management

libpag uses the depsync tool to manage third-party dependencies.

For macOS platform：

Run the script located in the root directory of the project:

text
./sync_deps.sh

This script will automatically install the necessary tools and sync all third-party repositories.

For other platforms：

First, ensure you have the latest version of Node.js installed (you may need to restart your
computer afterward). Then, run the following command to install the depsync tool:

text
npm install depsync

Then, run depsync in the root directory of the project.

text
depsync

You might need to enter your Git account and password during synchronization. Ensure you have
enabled the git-credential-store so that CMakeList.txt can automatically trigger synchronization
next time.

Build

After synchronization, you can open the project with CLion and build the PAG library.

For macOS:

No additional CLion configuration is needed.

For Windows:

Follow these steps to configure CLion correctly:

  • Ensure you have installed the [Desktop development with C++] and [Universal Windows Platform development] components for VS2019.
  • Open the File->Settings panel, go to Build, Execution, Deployment->Toolchains, and set the toolchain to Visual Studio with amd64 (Recommended) or x86 architecture.

Note: If you encounter issues during the CMake build, update to the latest version of the CMake
command-line tool and try again.

Support Us

If you find libpag helpful, please give us a Star. We truly appreciate your support :)

License

libpag is licensed under the Apache Version 2.0 License

The copyright notice pertaining to the Tencent code in this repo was previously in the name of "THL
A29 Limited". That entity has now been de-registered. You should treat all previously distributed
copies of the code as if the copyright notice was in the name of "Tencent".

Privacy Policy

Please refer to the PAG SDK Personal Information Processing Rules when using the libpag SDK.

Data Collection

  • Binaries built from this repository collect no data. They contain no network requests or usage reporting, and the bundled privacy manifest (PrivacyInfo.xcprivacy) declares no data collection.
  • Official prebuilt releases distributed through pag.io and CocoaPods contain an additional anonymous usage statistics module on iOS and Android, which reports the following data to the Tencent Beacon analytics service (otheve.beacon.qq.com), at most once per SDK version per month: host app name and bundle identifier, operating system version and device model, GPU version and vendor, and the libpag SDK version. No user IDs, advertising identifiers, or other personal data are collected, and the data is used solely for SDK usage statistics. The privacy manifest bundled in the official releases declares this data collection accordingly.

Contribution

If you have any ideas or suggestions to improve libpag, feel free to submit an
issue or a pull request.
Before doing so, please read our Contributing Guide.

Web Doc Compatibility (`web/doc/compatibility.md`)

兼容性情况

Chrome Safari Chrome for Android Safari on iOS
Chrome >= 69 Safari >= 11.3 Android >= 7.0 iOS >= 11.3

libpag Web端是基于 WebAssembly + WebGL实现，并通过适配 Web 平台能力来支持 libpag 全能力，以上的兼容表仅代表可以运行的兼容性。

libpag 的渲染性能受以下条件影响：

  • PAG 动效文件的复杂度
  • libpag 调用方式
  • Web 浏览器环境

本文主要讲解 libpag Web端在各个浏览器中的性能，以及一些兼容兜底方案。

注册软件解码器 ffavc 需要加载多一个 wasm 文件，会增加内存和 CPU 占用。

桌面端

Chrome (Win/Mac)

性能表现良好

Safari (Mac)

性能表现良好

Firefox (Win/Mac)

除带 BMP 序列帧的 PAG 动效文件外，性能表现良好。

因为 Firefox 的 Video 标签无法解析 PAG 动效文件中 BMP 序列帧转化而成的视频，所以需要注册软件解码器 ffavc 来解析。示例Demo

移动端

Safari (iOS)

除带 BMP 序列帧的 PAG 动效文件外，性能表现良好。

libpag 解析带 BMP 序列帧的 PAG 动效文件调用了 Video 标签的 blobURL 属性解码视频，而在 iOS Safari 浏览器上当 blobURL 为 src 的 Video 时，会存在“播放到视频末尾掉帧”、“修改currentTime后currentTime属性不变化，而video画面渲染成功”等BUG。

而且当 iOS 设备处于省电模式或者在微信浏览器中，存在“用户与页面交互之后才可以使用 Video 标签进行视频播放”的规则限制，所以，使用播放动效的场景需要经过用户交互之后播放。

以上两个环境兼容性的影响，可以使用注册软件解码器 ffavc 解析视频来规避，也是当前推荐的方案。示例Demo

Chrome (Android)

除带 BMP 序列帧的 PAG 动效文件外，性能表现良好。

部分 Android 设备和在微信浏览器中，存在“用户与页面交互之后才可以使用 Video 标签进行视频播放”的规则限制，所以，使用播放动效的场景需要经过用户交互之后播放。

这里也使用注册软件解码器 ffavc 解析视频来规避，但是 ffavc 软解码在 Android 设备中的性能表现较差，所以我们并不推荐使用这个方案，后续我们会努力寻求更优秀的方案来覆盖这个场景。暂时需要接入方从业务场景中引导用户产生交互来规避“用户与页面交互之后才可以使用 Video 标签进行视频播放”的规则限制。

Android 原生浏览器

因为各个厂商都有自己的自带浏览器，而自带浏览器的环境除了会收到厂商浏览器实现差异影响还会受到GPU芯片差异影响。所以，我们暂时没有计划对这部分机器进行兼容，我们首要的精力会放在主流的浏览器中。

Web Doc Develop Install (`web/doc/develop-install.md`)

开发安装

目录结构

bash
├─ lib                        
│   ├─ libpag.cjs.js        ## CommonJs
│   ├─ libpag.cjs.js.map
│   ├─ libpag.esm.js        ## ESModule
│   ├─ libpag.esm.js.map
│   ├─ libpag.min.js        ## umd-min
│   ├─ libpag.min.js.map
│   ├─ libpag.umd.js        ## umd
│   ├─ libpag.umd.js.map
│   └─ libpag.wasm          ## WebAssembly
│
├─ types
│   ├─ core
│   ├─ h264
│   ├─ utils
│   └─ pag.d.ts
│
├─ CHANGELOG.md
├─ package.json
└─ README.md

产物说明

lib

  • lib 文件夹中打包了 esm、 cjs 和 umd 三种导出方式版本的 Js 文件， min 文件为 umd 版本的压缩文件
  • libpag.esm.js 采用 ES Modules 标准 构建，可以使用 import 或者使用 <script type="module"> 加载
  • libpag.cjs.js 采用 CommonJs Modules 标准 构建，可以使用 require 加载
  • libpag.umd.js 和 libpag.min.js 采用 UMD 模块标准 构建，可以直接在 Browser 环境中使用 <script> 加载
  • libpag.wasm WebAssembly 二进制文件

types

  • 包含类型声明文件 \*.d.ts

安装

默认组件包的 main 入口指向 lib/libpag.cjs.js，esm 入口指向 libpag.esm.js

默认加载 Js 文件同目录下的 libpag.wasm 文件，可以用 PAGInit 的参数中的 locateFile 方法重新指定 wasm 文件的地址

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#after-effects Browse after-effects catalog → #animation Browse animation catalog → #keyframes Browse keyframes catalog → #libpag Browse libpag catalog → #pag Browse pag catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →