A beautiful Flutter application that creates an interactive cassette tape animation with 3D USDZ model integration, image galleries, and smooth transitions.
- 3D Cassette Model: Interactive USDZ model with rotation and scaling animations
- Image Gallery: Grid-based cassette image selection with smooth transitions
- Memories Timeline: Monthly photo collections with random image generation
- TV Animation: Dynamic TV screen with rotating images
- Smooth Transitions: Fluid animations between different states
- Clean Architecture: Well-organized code with service-based architecture
lib/
├── main.dart # App entry point
├── services/ # Business logic services
│ ├── usdz_method_channel.dart # USDZ communication service
│ └── cassette_animation_service.dart # Animation management
├── views/ # Main UI screens
│ └── cassette_view.dart # Main cassette viewer
└── widgets/ # Reusable UI components
├── cassette_image_grid.dart # Image grid component
└── memories_list_view.dart # Memories timeline component
ios/Runner/
├── AppDelegate.swift # iOS app delegate with plugin registration
└── USDZView.swift # USDZ 3D model view implementation
assets/
├── cassette.png # Cassette tape images
├── TV.png # TV frame image
├── TV_Cutout.png # TV cutout overlay
└── model.usdz # 3D cassette model
- Flutter SDK (3.8.1 or higher)
- iOS development environment (Xcode)
- macOS for iOS development
-
Clone the repository
git clone <repository-url> cd cassette_animation
-
Install dependencies
flutter pub get
-
Run the app
flutter run
The USDZMethodChannel class handles all communication between Flutter and the native iOS USDZ view:
// Initialize the service
final usdzChannel = USDZMethodChannel();
usdzChannel.initialize();
// Set rotation
await usdzChannel.setRotation(x: -90.0, y: 0.0, z: 0.0);
// Set scale
await usdzChannel.setScale(scale: 0.8);
// Relative rotation
await usdzChannel.rotateBy(x: 15.0, y: 0.0, z: 0.0);Available Methods:
setRotation(x, y, z)- Set absolute rotation in degreessetScale(scale)- Set model scale (0.1 to 2.0)rotateBy(x, y, z)- Rotate by relative amountszoomIn()/zoomOut()- Camera zoom controlsgetRotationValues()- Get current rotation stategetScaleValue()- Get current scale value
The CassetteAnimationService manages the smooth cassette rotation animation:
// Initialize with TickerProvider
final animationService = CassetteAnimationService(
vsync: this,
usdzChannel: usdzChannel,
);
// Start animation
animationService.startAnimation();
// Stop animation
animationService.stopAnimation();
// Check animation state
bool isAnimating = animationService.isAnimating;Animation Sequence:
- Start:
(0°, 0°, -90°)- Initial position - Step 1:
(-30°, 0°, -60°)- First rotation - Step 2:
(-60°, 0°, -30°)- Second rotation - Step 3:
(-65°, 0°, -15°)- Third rotation - End:
(-90°, 0°, 0°)- Final position
CassetteImageGrid(
imageList: imageList,
onImageTap: (index) => handleImageTap(index),
imageKeys: imageKeys,
)MemoriesListView(
scrollController: scrollController,
randomPhotoCounts: photoCounts,
randomImageIndices: imageIndices,
randomImageUrls: imageUrls,
)- TV Frame: Top section with TV cutout and overlay images
- Image Grid: 3x3 grid of cassette images (Tab 1)
- Memories Timeline: Monthly photo collections (Tab 2)
- 3D Model: USDZ cassette model with animations
- Image Overlay: Selected image follows animation
- Image Selection: User taps on cassette image
- Position Animation: Model moves to image position
- Rotation Animation: Smooth 4-step rotation sequence
- TV Transition: TV screen shows rotating images
- Tab Switch: Automatically switches to memories tab
- Scroll Animation: Smooth scroll to bottom of memories
The iOS USDZView class handles 3D model rendering:
// Model loading with automatic scaling
guard let modelScene = try? SCNScene(named: "Assets.scnassets/model.usdz") else {
print("❌ Could not load model.usdz")
return
}
// Automatic model normalization
let (minVec, maxVec) = modelNode.boundingBox
let maxDimension = max(size.x, max(size.y, size.z))
let scaleFactor = targetSize / maxDimension
modelNode.scale = SCNVector3(scaleFactor, scaleFactor, scaleFactor)setRotation- Set absolute rotation (degrees to radians conversion)setScale- Set model scalerotateX/Y/Z- Relative rotation actionszoomIn/Out- Camera zoom controls
This project includes a comprehensive test suite with 52 tests covering all major functionality:
test/
├── widget_test.dart # Main widget tests (13 tests)
├── integration_test.dart # Integration tests (14 tests)
├── test_cassette_viewer.dart # Test-specific widget for timer cleanup
├── services/ # Service unit tests
│ ├── usdz_method_channel_test.dart # USDZ service tests (12 tests)
│ └── cassette_animation_service_test.dart # Animation service tests (13 tests)
├── test_helpers.dart # Common test utilities and mocks
├── test_config.dart # Test configuration and setup
└── run_tests.sh # Test runner script
- ✅ Service Tests (25 tests): Complete coverage of
USDZMethodChannelandCassetteAnimationService - ✅ Widget Tests (13 tests): All UI components tested for proper behavior
- ✅ Integration Tests (14 tests): Full app functionality and user interactions
# Run all tests
flutter test
# Run specific test files
flutter test test/widget_test.dart
flutter test test/services/
flutter test test/integration_test.dart
# Run with coverage
flutter test --coverage
# Use the test runner script
chmod +x run_tests.sh
./run_tests.shFor detailed information about the test suite, see TEST_DOCUMENTATION.md which includes:
- Test Architecture: How tests are organized and structured
- Writing Tests: Guidelines for creating new tests
- Mocking: How to use mocks and test utilities
- Best Practices: Testing patterns and recommendations
- Debugging: Tips for troubleshooting test failures
- CI/CD Integration: Setting up automated testing
- Timer Management: Proper cleanup of
Future.delayedtimers in tests - Platform Channel Mocking: Safe testing of iOS method channels
- Animation Testing: Comprehensive animation state and sequence testing
- Widget Testing: UI component behavior and interaction testing
- Integration Testing: Full app workflow and user journey testing
dependencies:
flutter:
sdk: flutter
cupertino_icons: ^1.0.8
flutter_inappwebview: ^6.1.5
media_kit_video: ^1.3.0
media_kit: ^1.2.0
media_kit_libs_video: ^1.0.6
media_kit_libs_android_video: ^1.3.7
- 0ms: Stop current animation, hide TV images
- 500ms: Move model to left position (-20px)
- 1300ms: Start rotation animation, move to center (118px)
- 1900ms: Adjust vertical position (+17px)
- 2200ms: Hide top TV overlay
- 2500ms: Enable cassette down animation
- 2600ms: Show TV images, switch to memories tab, scroll to bottom
- Duration: 800ms total
- Segments: 4 smooth transitions
- Easing:
Curves.easeInOut - Scale Change: Model scales to 84% during step 3
- New Animation: Extend
CassetteAnimationService - New UI Component: Create in
widgets/directory - New Service: Add to
services/directory - New Method: Add to
USDZMethodChannel
- Services: Business logic and external communication
- Views: Main UI screens and state management
- Widgets: Reusable UI components
- Models: Data structures and constants
-
USDZ Model Not Loading
- Check if
model.usdzexists inios/Runner/Assets.xcassets/ - Verify iOS bundle includes the file
- Check if
-
Method Channel Errors
- Ensure
USDZViewis properly registered inAppDelegate.swift - Check method names match between Flutter and iOS
- Ensure
-
Animation Not Smooth
- Verify
TickerProvideris properly implemented - Check animation duration and curve settings
- Verify
- Use
print()statements in method channel handlers - Check iOS console for USDZ loading errors
- Verify animation controller state in Flutter
This project is licensed under the MIT License - see the LICENSE file for details.
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
For support and questions:
- Create an issue in the repository
- Check the troubleshooting section
- Review the code documentation
Built with ❤️ using Flutter and SceneKit
