streamyfin/providers/Downloads/MIGRATION.md

Download Provider Migration Guide

Overview

The DownloadProvider has been completely rewritten to use the new native BackgroundDownloader module instead of the third-party @kesha-antonov/react-native-background-downloader library.

What Changed

New Implementation

• Native Module: Uses our custom BackgroundDownloader Expo module built with NSURLSession
• Simplified: Focuses only on downloading video files
• Background Support: True iOS background downloads with system integration
• Event-Driven: Uses native event emitters for progress, completion, and errors

Removed Features (For Now)

The following features from the old implementation have been temporarily removed to simplify the initial version:

• ✗ Trickplay image downloads
• ✗ Subtitle downloads
• ✗ Series primary image caching
• ✗ Intro/credit segment fetching
• ✗ Download queue management with concurrent limits
• ✗ Pause/Resume functionality
• ✗ Speed calculation and ETA
• ✗ Cache directory management

Maintained Features

• ✓ Download video files with progress tracking
• ✓ Database persistence (same structure)
• ✓ Movies and Episodes support
• ✓ Download notifications
• ✓ File deletion and management
• ✓ Downloaded items listing
• ✓ Same context API

API Compatibility

The public API remains mostly the same to avoid breaking existing code:

Working Methods

const {
  // Core functionality
  startBackgroundDownload,
  cancelDownload,
  
  // Database operations
  getDownloadedItems,
  getDownloadsDatabase,
  getDownloadedItemById,
  getDownloadedItemSize,
  
  // File management
  deleteFile,
  deleteItems,
  deleteAllFiles,
  
  // State
  processes,
  APP_CACHE_DOWNLOAD_DIRECTORY,
  appSizeUsage,
} = useDownload();

Deprecated (No-op) Methods

These methods exist but do nothing in the new version:

• startDownload() - Use startBackgroundDownload() instead
• pauseDownload() - Not supported yet
• resumeDownload() - Not supported yet
• deleteFileByType() - Not needed (only video files)
• cleanCacheDirectory() - Not needed
• updateDownloadedItem() - Not needed
• dumpDownloadDiagnostics() - Not needed

Migration Steps

For Developers

1. No code changes needed if you're using startBackgroundDownload() and basic file management
2. Remove calls to deprecated methods (they won't break but do nothing)
3. Test downloads to ensure they work in your workflows

For Users

• No action required - the new system uses the same database format
• Existing downloads will still be accessible
• New downloads will use the improved background system

Future Enhancements

Planned features to add back:

1. Pause/Resume: Using NSURLSession's built-in pause/resume
2. Queue Management: Better control over concurrent downloads
3. Trickplay: Re-add trickplay image downloading
4. Subtitles: Download and link subtitle files
5. Progress Persistence: Resume downloads after app restart
6. Cellular Control: Respect cellular data settings
7. Speed/ETA: Better download metrics

Database Structure

The database structure remains unchanged:

interface DownloadsDatabase {
  movies: Record<string, DownloadedItem>;
  series: Record<string, DownloadedSeries>;
  other: Record<string, DownloadedItem>;
}

interface DownloadedItem {
  item: BaseItemDto;
  mediaSource: MediaSourceInfo;
  videoFilePath: string;
  videoFileSize: number;
  videoFileName?: string;
  trickPlayData?: TrickPlayData;
  introSegments?: MediaTimeSegment[];
  creditSegments?: MediaTimeSegment[];
  userData: UserData;
}

Known Differences

1. Progress Updates: More frequent and accurate with native module
2. Background Handling: Better iOS background download support
3. Error Messages: Different error format from native module
4. File Paths: Uses Paths.document instead of cache directory
5. No Queue: Downloads start immediately (no queuing system yet)

Troubleshooting

Downloads not starting

• Check that the iOS app has been rebuilt with the new native module
• Verify network permissions
• Check console logs for errors

Progress not updating

• Ensure event listeners are properly registered
• Check that the task ID mapping is correct
• Verify the download is still active

Files not found

• Old downloads might be in a different location
• Re-download content if files are missing
• Check file permissions

Old Implementation

The old implementation has been preserved at:

• providers/DownloadProvider.deprecated.tsx

You can reference it if needed, but it should not be used in production.

Testing

After migration, test these scenarios:

• Download a movie
• Download an episode
• Download multiple items
• Cancel a download
• Delete a downloaded item
• View downloaded items list
• Background app during download
• Force quit and restart app
• Verify notifications appear
• Check file sizes are correct

Questions?

If you encounter issues with the migration, please:

1. Check the console logs
2. Verify the native module is installed
3. Review the old implementation for reference
4. Open an issue with details