mirror of
https://github.com/streamyfin/streamyfin.git
synced 2026-01-15 23:59:08 +00:00
485dc6eeac
Signed-off-by: Lance Chant <13349722+lancechant@users.noreply.github.com> Co-authored-by: sarendsen <coding-mosses0z@icloud.com> Co-authored-by: Lance Chant <13349722+lancechant@users.noreply.github.com> Co-authored-by: Gauvain <68083474+Gauvino@users.noreply.github.com>
150 lines
4.2 KiB
Markdown
150 lines
4.2 KiB
Markdown
# Downloads Module
|
|
|
|
This module handles all download functionality for the Streamyfin app, including video downloads, subtitles, trickplay images, and cover images.
|
|
|
|
## Architecture
|
|
|
|
The downloads module is structured with a clean separation of concerns:
|
|
|
|
### Core Files
|
|
|
|
- **`database.ts`** - Pure functions for MMKV database operations
|
|
- **`fileOperations.ts`** - Pure functions for file system operations
|
|
- **`utils.ts`** - Pure utility functions (filename generation, URI conversion)
|
|
- **`additionalDownloads.ts`** - Pure functions for downloading additional assets
|
|
- **`notifications.ts`** - Pure functions for notification handling
|
|
- **`types.ts`** - TypeScript type definitions
|
|
|
|
### Hooks
|
|
|
|
- **`useDownloadOperations.ts`** - Hook providing download operations (start, cancel, delete)
|
|
- **`useDownloadEventHandlers.ts`** - Hook setting up native download event listeners
|
|
|
|
### Main Provider
|
|
|
|
- **`DownloadProvider.tsx`** - React context provider that orchestrates all download functionality
|
|
|
|
## Features
|
|
|
|
### Video Downloads
|
|
- Background download support using native module
|
|
- Progress tracking and reporting
|
|
- Pause/resume capability (future enhancement)
|
|
- Download queue management
|
|
|
|
### Additional Assets (Automatic)
|
|
When a video download completes, the following are automatically downloaded:
|
|
|
|
1. **Trickplay Images** - Preview thumbnail sheets for video scrubbing
|
|
2. **Subtitles** - External subtitle files (for non-transcoded content)
|
|
3. **Cover Images** - Primary item images and series images
|
|
4. **Segments** - Intro and credit skip timestamps
|
|
|
|
### File Management
|
|
- Automatic cleanup of all associated files (video, subtitles, trickplay)
|
|
- Size calculation including all assets
|
|
- Batch delete operations
|
|
|
|
## Implementation Details
|
|
|
|
### Pure Functions
|
|
All core logic is implemented as pure functions that:
|
|
- Take explicit parameters
|
|
- Return explicit values
|
|
- Have no side effects
|
|
- Are easily testable
|
|
|
|
### Imperative Design
|
|
The module uses imperative function calls rather than reactive patterns:
|
|
- Direct function invocation
|
|
- Explicit error handling
|
|
- Clear control flow
|
|
- Minimal side effects
|
|
|
|
### Storage
|
|
- **MMKV** - Used for persistent database storage
|
|
- **expo-file-system** - Used for file operations
|
|
- **Native module** - Used for background downloads
|
|
|
|
## Usage
|
|
|
|
```typescript
|
|
import { useDownload } from '@/providers/DownloadProvider';
|
|
|
|
function MyComponent() {
|
|
const {
|
|
startBackgroundDownload,
|
|
cancelDownload,
|
|
deleteFile,
|
|
getDownloadedItems,
|
|
processes,
|
|
} = useDownload();
|
|
|
|
// Start a download
|
|
await startBackgroundDownload(url, item, mediaSource, bitrate);
|
|
|
|
// Cancel a download
|
|
await cancelDownload(itemId);
|
|
|
|
// Delete a download
|
|
await deleteFile(itemId);
|
|
|
|
// Get all downloads
|
|
const items = getDownloadedItems();
|
|
}
|
|
```
|
|
|
|
## Event Flow
|
|
|
|
1. **Start Download**
|
|
- Pre-download cover images
|
|
- Start video download via native module
|
|
- Track progress via event listeners
|
|
|
|
2. **Download Progress**
|
|
- Native module emits progress events
|
|
- React state updated with progress percentage
|
|
- UI reflects current download state
|
|
|
|
3. **Download Complete**
|
|
- Video file saved to disk
|
|
- Additional assets downloaded in parallel:
|
|
- Trickplay images
|
|
- Subtitles (if applicable)
|
|
- Segments data
|
|
- Item saved to database
|
|
- Notification sent
|
|
- Process removed from queue
|
|
|
|
4. **Delete**
|
|
- Item removed from database
|
|
- All associated files deleted:
|
|
- Video file
|
|
- Subtitle files
|
|
- Trickplay directory
|
|
|
|
## File Structure
|
|
|
|
```
|
|
providers/Downloads/
|
|
├── additionalDownloads.ts # Trickplay, subtitles, cover images
|
|
├── database.ts # MMKV operations
|
|
├── fileOperations.ts # File system operations
|
|
├── notifications.ts # Notification helpers
|
|
├── types.ts # TypeScript types
|
|
├── utils.ts # Utility functions
|
|
├── index.ts # Module exports
|
|
├── hooks/
|
|
│ ├── useDownloadEventHandlers.ts
|
|
│ └── useDownloadOperations.ts
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
- Background download scheduling
|
|
- Network condition awareness
|
|
- Download priority management
|
|
- Automatic cleanup of old downloads
|
|
- Series season download management
|