Build a High‑Performance H5 PAG Player: SDK, Image Editing, Batch Synthesis

Background

The "Use Basketball to Know Me" community activity introduced a core feature where users upload a photo to generate a personalized basketball star card. Initially the composition was done on the server using PAG, but to give users more freedom the workflow was moved to the H5 side, requiring image drag, pinch‑zoom, and rotation before final synthesis.

What is PAG?

PAG (Portable Animated Graphics) is Tencent’s open‑source animation workflow solution. It exports After Effects (AE) animations to a binary .pag format with high compression and fast decoding, supports Android, iOS, Web and other platforms, guarantees cross‑platform rendering consistency, GPU acceleration, and runtime layer editing (e.g., replace images or text).

Core Interaction Chain

To meet the product goal, the development was broken down into six priority tasks:

PAG player basics : play/pause, layer replacement, text modification, export of the current frame.

Image transformation : single‑finger drag, dual‑finger pinch‑zoom and rotation for the user portrait.

Real‑time sync : reflect every adjustment instantly on the PAG preview.

Batch synthesis : reuse the core pipeline to generate multiple cards in one go.

Performance optimization : improve instance release and layer rendering efficiency.

Fallback & degradation : static layers or server‑side synthesis when the SDK cannot run.

Basic PAG Player Implementation

1. Load PAG SDK

The SDK consists of libpag.min.js and its accompanying libpag.wasm. Both files must reside in the same directory (or the path can be overridden). The loading code creates a script tag, appends it to document.head, and resolves when window.libpag becomes available.

const loadLibPag = useCallback(async () => {
  // Return if already loaded
  if (window.libpag) return window.libpag;
  try {
    const script = document.createElement('script');
    script.src = 'https://h5static.xx/10122053/libpag.min.js';
    document.head.appendChild(script);
    return new Promise((resolve, reject) => {
      script.onload = async () => {
        await new Promise(r => setTimeout(r, 500)); // ensure init
        if (window.libpag) resolve(window.libpag);
        else reject(new Error('window.libpag is not available'));
      };
      script.onerror = () => reject(new Error('Failed to load libPag script'));
    });
  } catch (error) {
    throw new Error(`Failed to load libPag: ${error}`);
  }
}, []);

2. Initialize the Player

After the SDK is ready, the player sets up a canvas element, loads the .pag template, creates a PAGView, and wraps control methods (play, pause, destroy). The player starts in a paused state because the use‑case only needs a static preview.

const initPlayer = useCallback(async () => {
  try {
    setIsLoading(true);
    const canvas = canvasRef.current;
    canvas.width = width;
    canvas.height = height;
    const libpag = await loadLibPag();
    const PAG = await libpag.PAGInit({ useScale: false });
    const response = await fetch(src);
    const buffer = await response.arrayBuffer();
    const pagFile = await PAG.PAGFile.load(buffer);
    const pagView = await PAG.PAGView.init(pagFile, canvas);
    const player = {
      _pagView: pagView,
      _pagFile: pagFile,
      _PAG: PAG,
      _isPlaying: false,
      async play() { await this._pagView.play(); this._isPlaying = true; },
      pause() { this._pagView.pause(); this._isPlaying = false; },
      destroy() { this._pagView.destroy(); }
    };
    // store player reference …
  } catch (error) {
    console.error('PAG Player initialization failed:', error);
  }
}, [src, width, height]);

After initialization the canvas correctly displays the star‑card animation (paused).

Replace Layers and Text

Image layer replacement : pagFile.replaceImage(index, image) – the image can be a CDN URL, a HTMLImageElement, or a Canvas element.

Text replacement : pagFile.setTextData(index, textData) – updates the content and font of a text layer.

Apply changes : after each replacement call pagView.flush() to force a render refresh.

Image Transformation Feature Development

The component enables users to drag, scale, and rotate the portrait with the following goals:

Single‑finger drag for translation.

Two‑finger pinch for uniform scaling (min 0.1×, max 5×).

Two‑finger rotation (optional).

High‑DPI rendering to avoid blur.

State feedback (offset, scale, rotation) for reset or export.

Real‑Time Interaction and Preview Synchronization

The architecture follows a three‑layer model:

Interaction layer : captures raw touch/mouse events and converts them into semantic intents (translate, scale, rotate, reset).

Transformation layer : computes geometric transforms, applies constraints, and updates the internal state.

Render layer : draws the transformed image onto a canvas, then feeds the canvas directly to PAG via replaceImageFast, avoiding format conversion.

To keep the preview responsive, updates are merged using requestAnimationFrame. If no new interaction occurs for >100 ms, an immediate flushPagView() is triggered; otherwise a short delayed flush (16 ms ~ updateThrottle/2) batches multiple changes.

const timeSinceLastFlush = Date.now() - batchUpdate.lastFlushTime;
if (timeSinceLastFlush > 100) {
  await flushPagView(); // immediate refresh
} else {
  setTimeout(async () => {
    if (batchUpdate.pendingUpdates > 0) await flushPagView();
  }, Math.max(16, updateThrottle / 2));
}

Snapshot Export (PagPlayer Capture)

Exporting the final image is done by synchronizing size and flushing the view, then converting the canvas to a JPEG data URL (quality 0.9) and uploading to CDN.

canvas.toDataURL('image/jpeg', 0.9); // Base64 JPEG ready for upload

Earlier attempts using pagView.makeSnapshot() returned a transparent frame because the rendering state was out of sync. Adding updateSize() + flush() before the snapshot resolves the issue.

Batch Synthesis

For generating multiple cards (different levels) the pipeline is extended with a batch composer that:

Creates an off‑screen container to avoid layout interference.

Pre‑loads resources and caches buffers.

Runs a coroutine pool to process templates concurrently while respecting GPU limits.

Implements a shared cursor and atomic task acquisition to guarantee each template is processed once.

Provides retry logic (up to 3 attempts) and per‑template fallback to static layers.

In practice, synthesizing eight cards takes 3–10 seconds, which is imperceptible to users.

Performance Optimization & Degradation Compatibility

Key optimizations include:

Reusing the same canvas element for image replacement ( replaceImageFast) to avoid costly format conversion.

Smart flush strategy that merges rapid updates and only forces GPU work when necessary.

Explicit destruction of previous PAGPlayer instances when the source changes to free WebGL resources.

High‑DPI handling: detect device pixel ratio and scale the canvas accordingly.

WebGL & WebAssembly capability checks; if unavailable, the app falls back to server‑side synthesis with static layers.

export function isWebGLAvailable(): boolean {
  if (typeof window === 'undefined') return false;
  try {
    const canvas = document.createElement('canvas');
    const gl = canvas.getContext('webgl') || canvas.getContext('experimental-webgl');
    return !!gl;
  } catch (e) { return false; }
}

export function isWasmAvailable(): boolean {
  try {
    const hasBasic = typeof (globalThis as any).WebAssembly === 'object' &&
      typeof (WebAssembly as any).instantiate === 'function';
    if (!hasBasic) return false;
    const bytes = new Uint8Array([0x00,0x61,0x73,0x6d,0x01,0x00,0x00,0x00]);
    const mod = new WebAssembly.Module(bytes);
    const inst = new WebAssembly.Instance(mod);
    return inst instanceof WebAssembly.Instance;
  } catch (e) { return false; }
}

export function isPagRuntimeAvailable(): boolean {
  return isWebGLAvailable() && isWasmAvailable();
}

If the checks fail, the system switches to a server‑side composition path, ensuring the star‑card feature remains functional on low‑end devices.

Conclusion & Takeaways

The implementation solves the original pain point of fixed server composition by giving users full control over portrait positioning on the front end while preserving cross‑platform visual consistency through PAG. The project also yields reusable components ( PagPlayer, CanvasImageEditor, EditablePagPlayer, PAGBatchComposer) and a set of performance‑tuning patterns (RAF‑based batching, resource pooling, fallback strategies) that can be applied to future image‑editing or animation‑synthesis features.

Future work may explore moving heavy PAG parsing into Web Workers for even smoother batch processing and extending the editor with cropping, filters, or sticker overlays.