202 lines
5.9 KiB
Markdown
202 lines
5.9 KiB
Markdown
# GroovyBox Track Repository Refactor Summary
|
|
|
|
## Overview
|
|
Successfully refactored the `lib/data/track_repository.dart` to support more settings including in-place indexing and folder watching functionality.
|
|
|
|
## Key Changes Made
|
|
|
|
### 1. Database Schema Updates (`lib/data/db.dart`)
|
|
- Added `WatchFolders` table for managing watch folders
|
|
- Added `AppSettings` table for storing app preferences
|
|
- Updated database schema version to 6
|
|
- Added proper migrations for new tables
|
|
|
|
### 2. Settings Provider (`lib/providers/settings_provider.dart`)
|
|
- Created comprehensive settings management with Riverpod
|
|
- Added `ImportMode` enum (Copy vs In-place)
|
|
- Added auto-scan and watch-for-changes settings
|
|
- Added supported audio formats configuration
|
|
- Persistent storage using SharedPreferences
|
|
|
|
### 3. Watch Folder Provider (`lib/providers/watch_folder_provider.dart`)
|
|
- Created service for managing watch folders
|
|
- Added database operations for CRUD operations
|
|
- Simplified implementation avoiding complex watcher issues
|
|
- Added folder scanning functionality
|
|
- Added missing track cleanup
|
|
|
|
### 4. Track Repository Refactor (`lib/data/track_repository.dart`)
|
|
- **Major Changes:**
|
|
- Split `importFiles` into mode-specific methods
|
|
- `_importFilesWithCopy`: Original behavior (copies files to internal storage)
|
|
- `_importFilesInPlace`: New behavior (indexes files in original location)
|
|
- Added `scanDirectory` method for folder scanning
|
|
- Added `scanWatchFolders` method for bulk scanning
|
|
- Added file event handlers (`addFileFromWatch`, `removeFileFromWatch`, `updateFileFromWatch`)
|
|
- Added `cleanupMissingTracks` for maintaining database integrity
|
|
- Updated `deleteTrack` to handle in-place vs copied files correctly
|
|
|
|
### 5. Settings UI (`lib/ui/screens/settings_screen.dart`)
|
|
- Created comprehensive settings interface
|
|
- Import mode selection (Copy vs In-place)
|
|
- Auto-scan and watch-for-changes toggles
|
|
- Watch folders management section
|
|
- Supported formats display
|
|
- Integration with new providers
|
|
|
|
### 6. Dependencies (`pubspec.yaml`)
|
|
- Added `watcher: ^1.2.0` for file system monitoring
|
|
- Added `shared_preferences: ^2.3.5` for settings persistence
|
|
|
|
## New Functionality
|
|
|
|
### Import Modes
|
|
1. **Copy Mode (Default):**
|
|
- Original behavior maintained
|
|
- Files copied to internal music directory
|
|
- Safe file management
|
|
- Suitable for mobile devices
|
|
|
|
2. **In-place Mode:**
|
|
- Files indexed in original location
|
|
- No additional storage usage
|
|
- Preserves original file organization
|
|
- Suitable for desktop/storage-rich environments
|
|
|
|
### Watch Folder Features
|
|
- Add/remove watch folders
|
|
- Toggle active/inactive status
|
|
- Bulk scanning of all active folders
|
|
- Automatic cleanup of missing tracks
|
|
- Support for recursive scanning
|
|
|
|
### Settings Management
|
|
- Persistent storage of user preferences
|
|
- Auto-scan scheduling
|
|
- File change monitoring toggle
|
|
- Configurable audio formats
|
|
|
|
## Usage Examples
|
|
|
|
### Switch to In-place Indexing
|
|
```dart
|
|
// Update settings to use in-place indexing
|
|
ref.read(settingsProvider.notifier).setImportMode(ImportMode.inplace);
|
|
```
|
|
|
|
### Add Watch Folder
|
|
```dart
|
|
// Add a folder to watch list
|
|
final watchService = ref.read(watchFolderServiceProvider);
|
|
await watchService.addWatchFolder('/path/to/music', name: 'My Music');
|
|
```
|
|
|
|
### Scan Watch Folders
|
|
```dart
|
|
// Scan all active watch folders
|
|
final trackRepo = ref.read(trackRepositoryProvider);
|
|
await trackRepo.scanWatchFolders();
|
|
```
|
|
|
|
### Cleanup Missing Tracks
|
|
```dart
|
|
// Remove tracks that no longer exist
|
|
final trackRepo = ref.read(trackRepositoryProvider);
|
|
await trackRepo.cleanupMissingTracks();
|
|
```
|
|
|
|
## Benefits
|
|
|
|
### User Experience
|
|
- Flexible import options for different use cases
|
|
- Automatic library maintenance
|
|
- Real-time folder monitoring capabilities
|
|
- Preserved file organization when desired
|
|
|
|
### Performance
|
|
- Efficient database operations
|
|
- Selective file scanning
|
|
- Proper resource cleanup
|
|
- Minimal storage impact for in-place mode
|
|
|
|
### Maintainability
|
|
- Clear separation of concerns
|
|
- Modular provider architecture
|
|
- Comprehensive error handling
|
|
- Extensible design for future features
|
|
|
|
## Future Enhancements
|
|
|
|
### Potential Additions
|
|
1. Real-time file watching implementation
|
|
2. Advanced file format detection
|
|
3. Folder exclusion/inclusion patterns
|
|
4. Metadata caching for performance
|
|
5. Batch operations optimization
|
|
6. Conflict resolution for duplicate files
|
|
|
|
### UI Improvements
|
|
1. Watch folder management interface
|
|
2. Import progress indicators
|
|
3. Folder scanning status
|
|
4. Settings organization and search
|
|
5. Conflict resolution dialogs
|
|
|
|
## Migration Guide
|
|
|
|
### For Existing Users
|
|
- Current behavior preserved (copy mode by default)
|
|
- Manual switch to in-place mode available
|
|
- Existing copied files unaffected
|
|
- Gradual migration possible
|
|
|
|
### Recommended Workflow
|
|
1. Start with copy mode for testing
|
|
2. Add watch folders in in-place mode
|
|
3. Enable auto-scan when comfortable
|
|
4. Use cleanup to maintain library
|
|
|
|
## Technical Notes
|
|
|
|
### Database Considerations
|
|
- Unique path constraint ensures no duplicates
|
|
- Cascade deletion maintains referential integrity
|
|
- Proper indexing on path for performance
|
|
- Migration handles existing installations
|
|
|
|
### File System Safety
|
|
- Existence checks before operations
|
|
- Graceful error handling
|
|
- Safe disposal of file watchers
|
|
- Album art always stored internally
|
|
|
|
### Memory Management
|
|
- Lazy loading of watch folders
|
|
- Efficient streaming for large libraries
|
|
- Proper cleanup of resources
|
|
- Minimal memory footprint
|
|
|
|
## Testing Recommendations
|
|
|
|
### Unit Tests
|
|
- Test import mode switching
|
|
- Test watch folder operations
|
|
- Test file event handling
|
|
- Test cleanup functionality
|
|
- Test settings persistence
|
|
|
|
### Integration Tests
|
|
- Test full import workflows
|
|
- Test settings changes
|
|
- Test database migrations
|
|
- Test file system scenarios
|
|
|
|
### Edge Cases
|
|
- Large file collections
|
|
- Network storage scenarios
|
|
- Permission denials
|
|
- File system errors
|
|
- Corrupted metadata
|
|
|
|
This refactor provides a solid foundation for enhanced music library management while maintaining backward compatibility and enabling powerful new features.
|