Tencent VAP - Flutter

A Flutter plugin that integrates Tencent's Video Animation Player (VAP) technology for high-performance video animations with dynamic content replacement. Supports multiple simultaneous animations through individual VAPView widgets.

Features

• High-Performance Playback: Hardware-accelerated video animation rendering
• Flexible Controls: Loop options, scale types, audio control, lifecycle management
• Dynamic Content: Text and image injection (Base64, files, assets, URLs)
• Event System: Complete lifecycle and error handling callbacks
• Multiple Instances: Run concurrent animations with independent widgets

Platform Setup

Android (android/app/build.gradle):

android {
        compileSdkVersion 34
        defaultConfig {
                minSdkVersion 21
        }
}

iOS (ios/Podfile):

platform :ios, '11.0'

Quick Start

// Basic VAP animation
VapView(
    scaleType: ScaleType.fitCenter,
    repeat: -1,
    onViewCreated: (controller) {
        controller.setAnimListener(
            onVideoStart: () => print('Started'),
            onVideoComplete: () => print('Completed'),
            onFailed: (code, type, msg) => print('Error: $code'),
        );
        controller.playAsset('animations/sample.mp4');
    },
)

// With dynamic content
VapView(
    vapTagContents: {
        'username': TextContent('John Doe'),
        'avatar': ImageURLContent('https://example.com/avatar.jpg'),
        'badge': ImageAssetContent('assets/images/badge.png'),
    },
    onViewCreated: (controller) => controller.playAsset('animations/profile.mp4'),
)

API Reference

VapView Properties

• scaleType: How video scales (fitCenter, centerCrop, fitXY)
• repeat: Loop count (0=once, -1=infinite, 1=2times, 2=3times and so on)
• mute: Audio enabled/disabled
• vapTagContents: Initial dynamic content
• onViewCreated: Controller callback

VapController Methods

// Playback
await controller.playFile('/path/to/file.mp4');
await controller.playAsset('assets/anim.mp4');
await controller.stop();
await controller.setLoop(-1);

// Content Management
await controller.setVapTagContent('tag', TextContent('text'));
await controller.setVapTagContents({'tag1': content1, 'tag2': content2});
VAPContent? content = await controller.getVapTagContent('tag');
await controller.clearVapTagContents();

// Events
controller.setAnimListener(
    onVideoStart: () {},
    onVideoComplete: () {},
    onFailed: (code, type, msg) {},
);

VAPContent Types

• TextContent('text') - Dynamic text
• ImageBase64Content('base64...') - Base64 images
• ImageFileContent('/path/file.jpg') - Local files
• ImageAssetContent('assets/img.png') - Flutter assets
• ImageURLContent('https://url.jpg') - Remote images

Error Handling

Common error codes:

• -1: File not found
• -2: Playback error
• -1001: Invalid video data
• -1002: Decoder malfunction
• -1006: File too large

controller.setAnimListener(
    onFailed: (code, type, message) {
        switch (code) {
            case -1: /* Handle file not found */; break;
            case -1001: /* Handle corrupted data */; break;
            default: print('Error $code: $message');
        }
    },
);

Best Practices

• Memory Management: Always dispose controllers in dispose()
• Batch Updates: Use setVapTagContents() for multiple content updates
• Error Handling: Wrap playback calls in try-catch blocks
• Performance: Use appropriate scale types and avoid unnecessary infinite loops

Troubleshooting

1. Animation not playing: Check VAP file exists, verify asset registration
2. Memory issues: Dispose controllers, limit concurrent animations
3. Content not updating: Verify tag names, set content before playback
4. iOS build issues: Ensure iOS 11.0+, run pod install

Contributing

We welcome contributions to improve this plugin! Please feel free to:

• Report bugs and issues
• Suggest new features
• Submit pull requests
• Improve documentation

Credits

This Flutter plugin is built upon the excellent work of Tencent's VAP project:

• Original VAP Project: https://github.com/Tencent/vap
• License: MIT License
• Tencent VAP Team: For creating the foundational VAP technology

We extend our gratitude to the Tencent team for developing and open-sourcing the VAP framework, which makes high-performance video animations accessible to developers worldwide.

Instruction to create the Animation Video

License

This project is licensed under the MIT License - see the LICENSE file for details.

The original Tencent VAP project is also licensed under the MIT License.