156 lines
4.9 KiB
Markdown
156 lines
4.9 KiB
Markdown
# 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`):
|
|
```gradle
|
|
android {
|
|
compileSdkVersion 34
|
|
defaultConfig {
|
|
minSdkVersion 21
|
|
}
|
|
}
|
|
```
|
|
|
|
**iOS** (`ios/Podfile`):
|
|
```ruby
|
|
platform :ios, '11.0'
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```dart
|
|
// 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
|
|
```dart
|
|
// 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
|
|
|
|
```dart
|
|
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](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](https://github.com/Tencent/vap/blob/master/tool/README_en.md)
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
The original Tencent VAP project is also licensed under the MIT License.
|
|
|