Tencent /libpag
The official rendering library for PAG (Portable Animated Graphics) files that renders After Effects animations natively across multiple platforms.
★ 5,822⑂ 533👁 47⑃ 1,525● 734▤ 73
+1
日增长
5,822
stars
533
forks
47
watchers
1,525
prs
734
issues
73
releases
README
English | 简体中文 | 官网
介绍
libpag 是 PAG (Portable Animated Graphics) 动效文件的渲染 SDK,目前已覆盖几乎所有的主流平台,包括:iOS, Android, OpenHarmony, macOS,
Windows, Linux, 以及 Web 端。
PAG 方案是一套完善的动效工作流。提供从 AE(Adobe After Effects)导出插件,到桌面预览工具 PAGViewer,再到各端的跨平台渲染 SDK。
目标是降低或消除动效研发相关的成本,打通设计师创作到素材交付上线的极简流程,不断输出运行时可编辑的高质量动效内容。
PAG 方案目前已经接入了腾讯系几乎所有主流应用以及外部几千个业务,包括微信,手机QQ,王者荣耀,腾讯视频,QQ音乐等头部产品,
稳定性经过了海量用户的持续验证,可以广泛应用于UI动画、贴纸动画、视频编辑、模板设计等场景。典型应用场景可以参考官网案例。
详细介绍可以参考相关报道:
- 王者QQ微信都在用的动画神器要开源了:把交付时间缩短90%
- 腾讯推出移动端动画组件PAG,释放设计生产力
PAG 优势
- 高效的文件格式
采用可扩展的二进制文件格式,可单文件集成图片音频等资源,实现快速交付。导出相同的 AE 动效内容,在文件解码速度和压缩率上均大幅领先于同类型方案。
- 全 AE 特性支持
在纯矢量导出方式上支持更多 AE 特性的同时,还引入了BMP预合成结合矢量的混合导出能力,实现支持所有 AE 特性的同时又能保持动效运行时的可编辑性。
- 性能监测可视化
通过导出插件内置的自动优化策略,以及预览工具集成的性能监测面板,能够直观地看到每个素材的性能状态,以帮助设计师制作效果和性能俱佳的动画特效。
- 运行时可编辑
运行时,可在保留动效效果前提下,动态修改替换文本或替换占位图内容,甚至对任意子图层进行增删改及移动,轻松实现照片和视频模板等素材的批量化生产。
系统要求
- iOS 15.0 版本及以上
- Android 5.0 版本及以上
- HarmonyOS Next 5.0.0(12) 版本及以上
- macOS 12.0 版本及以上
- Windows 7.0 版本及以上
- Chrome 69.0 版本及以上
- Safari 15.0 版本及以上
快速接入
由于大部分平台没有统一的上层业务框架,目前我们暂时只为 iOS, Android,macOs, Web 和鸿蒙平台定期发布预编译的二进制库,
其他平台的库需要通过源码根据自己的实际需求调整参数进行编译。移动端最新的release库可以在 这里
下载。 详细的 SDK接入文档可以参考 SDK 接入 。Web 平台的接入文档可以参考 Web SDK
接入
iOS 端接入
可以从 release 页面下载预编译的二进制库,或者通过CocoaPods接入
在Podfile中添加libpag依赖:
pod 'libpag'
然后运行:
pod install
然后在项目中引入libpag的头文件
import
Android 端接入
可以从 release 页面下载预编译的 aar 库文件,或者通过 Maven 将 libpag 添加到你的项目中:
编辑工程根目录下的 build.gradle 文件, 在repositories下面添加 mavenCentral() :
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.android.tools.build:gradle:3.2.1'
}
}
在 app/build.gradle中添加libpag依赖 (4.0.5.10 应替换为最新发布版本):
dependencies {
implementation 'com.tencent.tav:libpag:4.0.5.10'
}
在混淆列表里面,添加libpag的keep规则
-keep class org.libpag. {;}
-keep class androidx.exifinterface. {;}
配置完以后,sync一下,再编译即可。
OpenHarmony 端接入
可以从 release 页面下载预编译的 har,或者通过 OHPM 将 libpag 添加到您的项目中:
ohpm install @tencent/libpag
或者可以手动将其添加到您的项目中。
将以下几行添加到应用模块上的 oh-package.json5
"dependencies": {
"@tencent/libpag": "^1.0.1",
}
Then run
ohpm install
Web 端接入
直接拷贝如下代码,然后在浏览器中运行即可:
html
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.
});
});
Web 端更多接入方式请参考:Web端接入指南
范例工程
我们准备了如下各端的 Demo 工程,检出对应平台的 Demo 工程可以快速开始学习如何使用 libpag 的 API:
- https://github.com/libpag/pag-ios
- https://github.com/libpag/pag-android
- https://github.com/libpag/pag-web
API 手册:
- iOS API 参考
- Android API 参考
- Web API 参考
更多的其他文档可以访问官网 pag.io 获得。
开发指南
如果您希望参与到 libpag 项目的源码开发中,请务必严格按照以下步骤先配置完开发环境再进行开发和调试。
我们推荐使用 CLion 并在 macOS 平台上进行开发。
分支介绍
main 分支是我们主要的开发分支,日常会有频繁的修改合入。main 分支稳定后会不定期创建发布分支 release/{version}。release/ 下
的分支是我们推荐的在生产环境中使用的稳定版本。稳定版本一旦拉取出分支后,将不再合入新功能,只做缺陷问题的修复。
注:这个仓库只包含从 PAG 4.0 版Top issues
#23224.3.57版本概率出现释放卡死导致进程无响应14 comments · 2024-05-24#2274PAGImageView播放崩溃12 comments · 2024-04-29#2712Android 连续播放报错- ImageDecoderTask::onMakeResource() Failed to decode the image!11 comments · 2025-03-05#2374EXC_BAD_ACCESS libpag pag::PAGVideoDecoder::SetMaxHardwareDecoderCount(int) + 244876 (使用的是Firebase上报的crash)11 comments · 2024-07-16#2705libpag鸿蒙端调用PAGView的getProgress导致应用ANR crash10 comments · 2025-03-03#3780[iOS][4.5.98] HardwareDecoder 析构时 EXC_BAD_ACCESS,调用来自 VideoReader::destroyVideoDecoder9 comments · 2026-10-22#3621iOS 4.5.75崩溃9 comments · 2026-07-23#2668线上崩溃,影响较大8 comments · 2025-01-18
Discussions
#3772鸿蒙视频导出2 comments · 2026-10-20#3749pag 4.5.98 版本异常1 comments · 2026-09-24#3724Android端libpag库harfbuzz版本特殊字符替换ANR1 comments · 2026-09-10#3723鸿蒙使用libpag 最新版本"@tencent/libpag": "4.5.94", 崩溃闪退1 comments · 2026-09-09#3720🙏🏻关于接口上报(https://otheve.beacon.qq.com/analytics/v2_upload)的合规问题建议优化1 comments · 2026-09-08#3714您好,目前看到pag格式在官方顯示是開源的,請問後續會有開源轉收費的可能性嗎?1 comments · 2026-09-02#3705什么时候出AI版啊1 comments · 2026-08-27#3704Android端特定PAG文件在4.5.x版本播放抖动1 comments · 2026-08-26
Latest release
v4.5.102 v4.5.102 2026-11-08主要修改内容: (1)修复鸿蒙平台 PAGView 事件分发器在 release 后写入已释放内存导致的卡死 (3761) (2)更新 tgfx,合入 TaskPool 唤醒问题修复(鸿蒙) (3)修复 Android 与鸿蒙平台 PAGImageView 设置 ScaleMode 为 None 后未恢复合成原始尺寸的问题 (3757) (4)限制 ticker 驱动的异步刷新频率,并对解码失败的渲染增加冷却,避免循环播放时发热 (3793) (5)解码失败时保留最后一帧已解码画面,不再显示透明帧 (3753) (6)修复纹理替换图在图层缩小至低于 mipmap 阈值时渲染空白的问题 (3756) (7)修复 HarfBuzz 构建下 RTL 及双向混排文本导致的 ANR 与字形映射错误 (3752) (8)修复 pag 文件中引用环导致的栈溢出与死循环 (3747) (9)更新 tgfx,修复视频边缘闪烁与 render target 创建时的空指针解引用 Main modifications: (1) Fix OHOS main thread freezes caused by the PAGView event dispatcher writing to freed memory on release (3761) (2) Update tgfx to