English | 简体中文 | Homepage

Introduction

libpag is a real-time rendering library for PAG (Portable Animated Graphics) files that renders both vector-based and raster-based animations across most platforms, such as iOS, Android, macOS, Windows, Linux, and Web.

PAG is an open-source file format for recording animations. PAG files can be created and exported from Adobe After Effects with the PAGExporter plugin and previewed in the PAGViewer app, which you can get from pag.io, and both of them are available on both macOS and Windows.

PAG is now being used by 40+ Tencent apps, such as WeChat, Mobile QQ, Honor of Kings Mobile Game, Tencent Video, QQ Music, and so on, reaching hundreds of millions of users.

Advantages

• Highly efficient file format

Benefiting from the highly efficient binary format design, PAG files can be decoded 10x faster than JSON files but also are about 50% smaller in file size when exporting the same animations. Designers can also ship beautiful animations with bitmaps or audiovisual media integrated into a single file easily without other attachments.

• All AE features supported

While other solutions may only support exporting limited vector-based AE features, PAG supports exporting all AE animations into a single file by combining vector-based exporting with raster-based exporting techniques. Therefore, third-party plugin effects in AE can be exported as well.

• Measurable performance

PAG provides a monitoring panel in PAGViewer that shows normalized performance data for PAG files, which helps designers to examine and optimize performance easily without developers. Along with dozens of automatic optimization techniques from the PAGExporter plugin, animations with cool visual effects and excellent performance now can be created more effectively.

• Runtime editable animations

With the flexible editing APIs from PAG SDK, developers can easily change the layer structure of a single PAG file, mix multiple PAG files into one composition, or replace texts and images with all pre-designed animation effects applied at runtime. It reduces tons of coding work for product features like video templates.

Requirements

• iOS 9.0 or later
• Android 4.4 or later
• macOS 10.13 or later
• Windows 7.0 or later
• Chrome 87.0 or later (Web)
• Safari 11.1 or later (Web)
• GCC 4.9 or later (Linux)

Getting Started

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

iOS Installation

You can use the framework downloaded from the release page, or add libpag to your project by CocoaPods:

Add the pod to your Podfile:

pod 'libpag'

And then run:

pod install

After installing the cocoapod into your project import libpag with

#import <libpag/xxx.h>

Android Installation

You can use the aar downloaded from the release page, or add libpag to your project by Maven:

Edit the build.gradle file in the root of your project, add jcenter() to repositories:

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

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

dependencies {
    implementation 'com.tencent.tav:libpag:3.2.7.34'
}

Add the following rule to your proguard rules to avoid the wrong obfuscation.

  -keep class org.libpag.* {*;}

Finally, run gradle sync and then build the project.

Documentation

• iOS API Reference
• Android API Reference
• Web API Reference

You can find other docs on pag.io

Development

We recommend using CLion IDE on macOS platform for development.

Branch Management

• The main branch is our active developing branch. After full testing, we will periodically pull the pre-release branch based on the main branch.
• The release branch is our stable release branch, which is fully tested and already used in many apps.

Note: This repository only contains the code of PAG 4.0, which is still under active development. So there is no release branch yet at this moment. We are working hard to make a stable release of PAG 4.0 available as soon as possible. For using PAG 3.0 versions, you can download the precompiled libraries from here.

Dependency Management

libpag uses depsync tool to manage third-party dependencies.

For macOS platform：

Just simply run the script in the root of libpag project:

./sync_deps.sh

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

For other platforms：

First, make sure you have installed the latest version of node.js (You may need to restart your computer after this step). And then run the following command to install depsync tool:

npm install -g depsync

And then run depsync in the root directory of libpag project.

depsync

Git account and password may be required during synchronizing. Please make sure you have enabled the git-credential-store so that CMakeList.txt can trigger synchronizing automatically next time.

Build

After the synchronization, open the project with CLion, then you are good to go!

Note: If anything goes wrong during cmake building, please update the cmake tool to the latest version and try again.

License

libpag is licensed under the Apache Version 2.0 License

Contribution

If you have any ideas or suggestions to improve libpag, welcome to submit an issue / pull request. Before making a pull request or issue, please make sure to read Contributing Guide.