How junkfood02/seal works
1. What this repo is
- Seal is an Android downloader app built as a single-activity, Compose-first application.
- Its core job is to turn a URL into a queued download job, run that job in the background through yt-dlp-based tooling, and persist the result/history locally.
2. App entry and process boundaries
- MainActivity is the main UI host.
- QuickDownloadActivity provides a shortcut entry point for incoming share/open-with flows.
- DownloadService is the main background execution boundary for downloads.
- NotificationActionReceiver handles notification actions tied to active downloads.
- CrashReportActivity is a separate recovery/reporting path for failures.
3. UI architecture
- The UI lives under ui/ and is organized as Composable pages, not fragments.
- ui/page/AppEntry.kt and NavigationDrawer.kt form the shell/navigation layer.
- Major screens are grouped by function: download flow, download-v2 flow, video list/history, task list/logs, settings, and about/update pages.
- Reusable UI pieces live in ui/component/, while cross-cutting helpers live in ui/common/.
4. Two download UX flows
- There is a newer, more structured flow under ui/page/downloadv2/ with explicit configuration steps like URL input, format selection, and playlist selection.
- The older flow under ui/page/download/ still exists, including the home page view model and dialogs for settings/permissions/playlist selection.
- This suggests the app supports both an established UI path and a newer download configuration flow side by side.
5. Download engine and task model
- The execution layer is split into Downloader.kt/DownloadService.kt and the newer download/DownloaderV2.kt, Task.kt, and TaskFactory.kt.
- The task layer is the abstraction that turns user choices into executable work items.
- The actual download work is delegated to external tooling, primarily yt-dlp and optionally aria2c as an external downloader.
6. Data flow for a download
- User enters a URL in the UI.
- The UI/view model resolves options such as format, playlist handling, subtitles, cookies, and destination directory.
- A task is created and handed to the service/downloader layer.
- The service runs the job, emits progress/notifications, and records relevant metadata locally.
- Completion and errors are reflected back into UI pages like queue/history and logs.
7. Persistence layer
- Local storage is handled by Room via database/AppDatabase.kt and VideoInfoDao.kt.
- Versioned schema snapshots in app/schemas/... indicate the database is part of the app’s stable state and is migrated over time.
- Stored objects include downloaded video info, cookie profiles, command templates, and option shortcuts.
- Backup/import support exists under database/backup/, which means user configuration is treated as first-class local data.
8. Settings and configuration domains
- Settings are split into functional sections: appearance, general, format, directory, network, interaction, command templates, and troubleshooting.
- Preferences are managed through dedicated pages/dialogs rather than a single monolithic settings screen.
- Network settings include cookie management and a WebView-based page, indicating the app supports authenticated sites and session-based access.
9. Command templating and advanced behavior
- database/objects/CommandTemplate.kt and the settings pages under ui/page/settings/command/ show that users can define reusable yt-dlp command templates.
- This is a distinct customization boundary: the UI collects template metadata, the database stores it, and the downloader layer executes the resulting command shape.
10. Updates and maintenance flows
- AppUpdater, YtdlpUpdater, and their dialogs/pages handle app and embedded yt-dlp update behavior.
- This means the app is not just a downloader UI; it also manages the lifecycle of the underlying downloader binary/components.
- The presence of update pages in settings and release metadata in fastlane/ reinforces that update distribution is part of the product architecture.
11. Notifications and foreground execution
- Download progress and actions are surfaced through Android notifications, with a permission dialog in the UI and action handling in the receiver.
- This is important because long-running downloads need to survive backgrounding and remain user-controllable.
12. Theming, localization, and presentation
- The UI uses Material Design 3 with dynamic color support.
- The color/ module contains Monet/material color utilities, which acts as a shared theming subsystem.
- The app is heavily localized: res/values-* contains many language packs, and translations/ stores translation contributor docs.
13. Supporting infrastructure
- buildSrc/ and the Gradle Kotlin DSL structure centralize versioning/build logic.
- GitHub Actions workflows handle Android CI, issue automation, stale issue cleanup, and sponsorship automation.
- fastlane/metadata/ provides store listing assets, descriptions, changelogs, and screenshots, which are part of the release/distribution pipeline.
14. Architecture boundaries to draw
- One boundary is UI vs. execution: Compose screens and view models prepare requests, while service/downloader code performs work.
- Another is execution vs. persistence: task results, history, templates, and profiles are stored in Room, backed up, and reused by later sessions.
- A third is app vs. external tools: the app orchestrates yt-dlp/aria2c, but the actual media extraction/download mechanics live outside the Android process.
Main entry points: SettingsPage.kt Settings page · AppEntry.kt App shell · DownloadService.kt Download service · AppDatabase.kt App database
Components 34
Entry & host
Android entry points, activity boundaries, and background execution.
- Main activity · Primary single-activity UI entry point.
app/src/main/java/com/junkfood/seal/MainActivity.kt - Quick entry · Shortcut activity for share/open-with download entry.
app/src/main/java/com/junkfood/seal/QuickDownloadActivity.kt - Download service · Background execution boundary for long-running downloads.
app/src/main/java/com/junkfood/seal/DownloadService.kt - Action receiver · Handles notification actions for active downloads.
app/src/main/java/com/junkfood/seal/NotificationActionReceiver.kt - Crash report · Separate path for crash reporting and recovery.
app/src/main/java/com/junkfood/seal/CrashReportActivity.kt
Compose UI
Screen navigation, reusable components, and feature pages.
- App shell · Top-level app entry, routing, and navigation structure.
app/src/main/java/com/junkfood/seal/ui/page/AppEntry.kt - Drawer nav · Navigation drawer and app-wide screen switching.
app/src/main/java/com/junkfood/seal/ui/page/NavigationDrawer.kt - Download page · Older download flow and related dialogs/view model.
app/src/main/java/com/junkfood/seal/ui/page/download/DownloadPage.kt - Download v2 · Structured newer download flow with configuration steps.
app/src/main/java/com/junkfood/seal/ui/page/downloadv2/DownloadPageV2.kt - Video list · History and downloaded video browsing.
app/src/main/java/com/junkfood/seal/ui/page/videolist/VideoListPage.kt - Task pages · Task list and task log views for queued work.
app/src/main/java/com/junkfood/seal/ui/page/command/TaskListPage.kt - Settings page · Settings hub for all preference sections.
app/src/main/java/com/junkfood/seal/ui/page/settings/SettingsPage.kt - UI components · Reusable controls, dialogs, cards, and list items.
app/src/main/java/com/junkfood/seal/ui/component/CommonComponents.kt
Download pipeline
Task creation, downloader orchestration, and external download tooling.
- Task model · Represents executable download work and task composition.
app/src/main/java/com/junkfood/seal/download/Task.kt - Task factory · Builds tasks from UI choices and stored options.
app/src/main/java/com/junkfood/seal/download/TaskFactory.kt - Downloader v2 · Newer download orchestration layer.
app/src/main/java/com/junkfood/seal/download/DownloaderV2.kt - Downloader · Legacy download execution path used by the service.
app/src/main/java/com/junkfood/seal/Downloader.kt
Local data
Room persistence, backup/import, and stored app state.
- App database · Room database holding app state and download history.
app/src/main/java/com/junkfood/seal/database/AppDatabase.kt - Video DAO · Primary data access interface for stored video info.
app/src/main/java/com/junkfood/seal/database/VideoInfoDao.kt - Backup · Backup and restore support for local app data.
app/src/main/java/com/junkfood/seal/database/backup/Backup.kt - Stored objects · Persisted command templates, cookie profiles, shortcuts, and video info.
app/src/main/java/com/junkfood/seal/database/objects/CommandTemplate.kt
Settings & config
Preferences and configuration pages for downloader behavior.
- Network prefs · Cookie and network-related preferences, including WebView access.
app/src/main/java/com/junkfood/seal/ui/page/settings/network/NetworkPreferences.kt - Format prefs · Download format and subtitle configuration.
app/src/main/java/com/junkfood/seal/ui/page/settings/format/DownloadFormatPreferences.kt - Directory prefs · Destination path and download directory controls.
app/src/main/java/com/junkfood/seal/ui/page/settings/directory/DownloadDirectoryPreferences.kt - General prefs · Core downloader behavior and advanced toggles.
app/src/main/java/com/junkfood/seal/ui/page/settings/general/GeneralDownloadPreferences.kt - Command templates · Reusable yt-dlp command template management.
app/src/main/java/com/junkfood/seal/ui/page/settings/command/TemplateListPage.kt - Appearance · Theme and language preferences.
app/src/main/java/com/junkfood/seal/ui/page/settings/appearance/AppearancePreferences.kt - Interaction prefs · Interface and interaction customization.
app/src/main/java/com/junkfood/seal/ui/page/settings/interaction/InteractionPreferencePage.kt - Troubleshooting · Diagnostics and support-oriented settings.
app/src/main/java/com/junkfood/seal/ui/page/settings/troubleshooting/TroubleshootingPage.kt
Updates & maintenance
App and yt-dlp update flows plus recovery/reporting.
- App updater · Application update checks and release handling.
app/src/main/java/com/junkfood/seal/ui/page/AppUpdater.kt - yt-dlp updater · Embedded yt-dlp update management.
app/src/main/java/com/junkfood/seal/ui/page/YtdlpUpdater.kt - Update dialogs · Update and welcome dialogs shown around setup and maintenance.
app/src/main/java/com/junkfood/seal/ui/page/UpdateDialog.kt
Shared UI system
Theme, color, and shared cross-cutting UI utilities.
- Theme · Material 3 theme and color configuration.
app/src/main/java/com/junkfood/seal/ui/theme/Theme.kt - Color system · Dynamic color and Monet-related color utilities.
color/src/main/java/com/kyant/monet/Monet.kt
Connections 39
- Main activity → App shell: hosts · Main activity mounts the Compose app shell.
- Quick entry → Download v2: launches · Shortcut entry routes into download setup.
- App shell → Drawer nav: navigates · Shell owns app-wide navigation chrome.
- App shell → Download page: shows · Routes to the legacy download flow.
- App shell → Download v2: shows · Routes to the structured download flow.
- App shell → Video list: shows · Shell navigates to history and library pages.
- App shell → Task pages: shows · Shell navigates to task and log pages.
- App shell → Settings page: shows · Shell navigates to settings sections.
- Download page → Task factory: builds · Legacy UI prepares work items from user choices.
- Download v2 → Task factory: builds · New flow turns configuration into tasks.
- Task factory → Task model: creates · Factory produces executable task objects.
- Task model → Downloader v2: runs via · Structured tasks are executed by the newer downloader layer.
- Task model → Downloader: runs via · Older tasks can still flow through the legacy engine.
- Downloader v2 → Download service: delegates to · Downloader execution is handed to the background service boundary.
- Downloader → Download service: delegates to · Legacy engine is also serviced by the background executor.
- Download service → Action receiver: notifies · Service exposes notification actions for active jobs.
- Download service → App database: persists · Service writes job and history state locally.
- App database → Video DAO: accesses · Database is queried through the DAO layer.
- App database → Stored objects: stores · Database contains templates, profiles, and download metadata.
- Backup → App database: backs up · Backup layer exports and restores database-backed state.
- Video list → Video DAO: reads · History and video list pages read stored downloads.
- Task pages → Download service: observes · Task pages reflect service-managed background work.
- Settings page → Network prefs: contains · Settings hub exposes network preferences.
- Settings page → Format prefs: contains · Settings hub exposes format preferences.
- Settings page → Directory prefs: contains · Settings hub exposes directory preferences.
- Settings page → General prefs: contains · Settings hub exposes general preferences.
- Settings page → Command templates: contains · Settings hub exposes command template management.
- Settings page → Appearance: contains · Settings hub exposes appearance controls.
- Settings page → Interaction prefs: contains · Settings hub exposes interaction controls.
- Settings page → Troubleshooting: contains · Settings hub exposes troubleshooting controls.
- Command templates → Stored objects: edits · Template settings mutate stored command templates.
- Network prefs → Stored objects: edits · Network settings manage cookie profiles.
- Appearance → Theme: configures · Appearance settings affect shared app theming.
- Theme → Color system: uses · Theme composition relies on Monet color utilities.
- App updater → Update dialogs: presents · Update flow is surfaced through dialogs and pages.
- yt-dlp updater → Update dialogs: presents · yt-dlp maintenance also uses the update dialog layer.
- App updater → Main activity: affects · App updates coordinate with the main application lifecycle.
- yt-dlp updater → Downloader v2: updates · Embedded downloader binary supports the download engine.
- Crash report → App shell: recovers to · Crash reporting is a separate recovery route into the app shell.