How tfourj/palladium works
1. Product shape
Palladium is a native iOS/iPadOS app, not a server-backed service. The architecture centers on an app target (Palladium) plus a separate ShareExtension target, with the main executable responsible for all download, processing, storage, and UI orchestration on-device.
2. Primary user entry points
The main app UI is SwiftUI-based and organized around a tabbed shell (Download, Console, Packages, Settings). ContentView and its feature-specific extensions act as the coordination layer between user actions and the underlying services.
3. Download pipeline
The core flow is: user submits a media URL → app prepares download options/cookies/packages → Swift layer launches a Python workflow → Python yt-dlp logic extracts and downloads media → ffmpeg is used for post-processing when needed → the finished file is stored locally and surfaced back to the UI. This is the main architecture boundary in the repo.
4. Python execution boundary
The repo embeds Python tooling inside the app rather than calling out to a backend. PythonFlowRunner and PythonScripts in Swift bridge into the bundled Python code under Services/Python/palladium_ytdlp, including yt_dlp_flow.py and supporting modules. That Python package is the implementation layer for extraction, package handling, file handling, and WebKit/JS integration.
5. Media extraction and processing
yt-dlp is the extraction engine, while ffmpeg handles conversion, muxing, and related media processing. The FFmpeg/SwiftFFmpegBridge.swift and Python-side ffmpeg_bridge.py indicate a two-sided integration around the same native capability, with the app mediating between Swift UI and media-processing primitives.
6. State and domain models
The app’s user-configurable state is represented in Models/: download options, appearance mode, imported cookie files, and link history. These models form the persistent configuration boundary for the UI and the download engine, especially around remembering prior links, user preferences, and authentication-related cookie imports.
7. Settings and preferences subsystem
The Views/Tabs/Settings subtree shows the app’s configuration surface is split into focused panels: after-download behavior, cookies, download arguments/options, notifications, packages, storage, and interface preferences. This suggests a fairly explicit settings-to-runtime mapping, where user choices directly influence the Python download flow and post-processing behavior.
8. Console and observability
Services/Logging/ConsoleLogStore.swift plus ConsoleTabView imply the app captures and presents runtime logs inside the app rather than relying on external logging. The console is likely the main debugging surface for download failures, package issues, and Python/ffmpeg output.
9. Shortcuts and automation
There are two automation hooks: AppIntents/ShortcutDownloadIntents.swift for system Shortcuts integration, and Services/Shortcuts/ShortcutDownloadRequestStore.swift for persisting requests. This creates an alternate entry path into the same download pipeline without going through the main UI.
10. Share extension boundary
The ShareExtension target is a separate iOS extension with its own storyboard and entitlements. Its job is to accept shared content from other apps and hand off a URL or related download request into the main app’s workflow, acting as an acquisition front door.
11. Cookies and authenticated access
Cookie import support is a first-class subsystem, which matters because media sites often require authenticated or session-aware requests. The cookies settings and ImportedCookieFile model indicate the app can ingest browser/exported cookies and pass them into the Python/yt-dlp layer.
12. Packaging and runtime setup
The presence of scripts/install_python_runtime.sh, privacy-manifests/python, and the Package.resolved in the Xcode workspace indicates this is a self-contained mobile build that bundles runtime dependencies and declares privacy metadata for embedded Python-related components. The build pipeline is iOS-centric, with build_ipa.sh and GitHub Actions used to produce distributable IPAs.
13. What to draw as the main architecture
A useful diagram would show three major zones: the SwiftUI app shell and settings UI; the service layer that manages logging, shortcuts, storage, and Python invocation; and the embedded Python/media-processing runtime built around yt-dlp and ffmpeg. The share extension and App Intents should be shown as alternate ingress paths into the same central download workflow.
Main entry points: ContentView+DownloadFlow.swift Download flow · ContentView.swift Content view · DownloadOptions.swift App models · PythonFlowRunner.swift Python runner
Components 25
iOS App
Main SwiftUI app target and feature surfaces.
- Palladium app · Main iOS/iPadOS executable entry point.
Palladium/PalladiumApp.swift - Content view · Coordinates tabs and feature-specific app flows.
Palladium/Views/ContentView.swift - Download tab · User entry for starting downloads.
Palladium/Views/Tabs/DownloadTabView.swift - Console tab · In-app runtime log and troubleshooting surface.
Palladium/Views/Tabs/ConsoleTabView.swift - Packages tab · Package visibility and setup controls.
Palladium/Views/Tabs/PackagesTabView.swift - Settings tab · Container for app preferences panels.
Palladium/Views/Tabs/SettingsTabView.swift - App models · Persistent app state for options, appearance, cookies, and history.
Palladium/Models/DownloadOptions.swift - Download flow · Coordinates URL intake, options, Python invocation, and completion handling.
Palladium/Views/ContentView+DownloadFlow.swift - Preferences · Maps UI preferences to runtime behavior.
Palladium/Views/ContentView+Preferences.swift - History · Tracks previously handled links.
Palladium/Views/ContentView+History.swift - Cookies · Imports and applies cookie files for authenticated downloads.
Palladium/Views/ContentView+Cookies.swift - Post-download · Handles after-download actions and file handoff.
Palladium/Views/ContentView+PostDownload.swift - Storage · Controls local file locations and retention behavior.
Palladium/Views/ContentView+Storage.swift - Notifications · Notification preferences and delivery hooks.
Palladium/Views/ContentView+Notifications.swift - Shortcuts · System Shortcuts entry into the download pipeline.
Palladium/AppIntents/ShortcutDownloadIntents.swift - Request store · Persists shortcut-triggered download requests.
Palladium/Services/Shortcuts/ShortcutDownloadRequestStore.swift - Log store · Captures app and runtime output for the console tab.
Palladium/Services/Logging/ConsoleLogStore.swift
Embedded Runtime
On-device Python and media-processing boundary.
- Python runner · Swift boundary for invoking bundled Python workflows.
Palladium/Services/Python/PythonFlowRunner.swift - Python scripts · Declares bundled Python entry scripts and resources.
Palladium/Services/Python/PythonScripts.swift - yt-dlp flow · Top-level Python workflow for extraction and download.
Palladium/Services/Python/yt_dlp_flow.py - palladium_ytdlp · Bundled Python package implementing extraction, file, package, and JS helpers.
Palladium/Services/Python/palladium_ytdlp/__init__.py - FFmpeg bridge · Swift side integration with native ffmpeg capabilities.
Palladium/Services/FFmpeg/SwiftFFmpegBridge.swift
Extension & Build
Ingress extension and build/distribution tooling.
- Share extension · Separate target that accepts shared content and hands off requests.
ShareExtension/ShareViewController.swift - IPA build · Automates archive and distributable IPA creation.
build_ipa.sh - Python runtime setup · Installs or prepares the embedded Python runtime.
scripts/install_python_runtime.sh
Connections 26
- Palladium app → Content view: launches · App entry presents the main SwiftUI shell.
- Content view → Download tab: shows · Download entry point is one of the primary tabs.
- Content view → Console tab: shows · Console surface is embedded in the shell.
- Content view → Packages tab: shows · Packages management is available from the shell.
- Content view → Settings tab: shows · Settings panels are grouped under a tab.
- Content view → Download flow: orchestrates · Feature extensions coordinate the end-to-end download flow.
- Download flow → App models: reads/writes · Download options, history, cookies, and storage state feed the flow.
- Download flow → Python runner: invokes · Swift bridge launches bundled Python processing.
- Download flow → FFmpeg bridge: uses · Media post-processing may require ffmpeg integration.
- Download flow → Post-download: hands off · Completed files are routed to post-download handling.
- Preferences → App models: updates · User preferences are persisted in app state models.
- History → App models: updates · Visited links are stored in history state.
- Cookies → App models: updates · Imported cookie files are tracked as state.
- Storage → App models: updates · Storage choices map into persisted configuration.
- Notifications → App models: updates · Notification settings are persisted.
- Shortcuts → Request store: persists · Shortcut requests are stored for later processing.
- Shortcuts → Download flow: triggers · Automation enters the same download pipeline as the UI.
- Console tab → Log store: reads · Console UI presents captured runtime logs.
- Python runner → Python scripts: loads · Runner selects bundled script entry points.
- Python runner → yt-dlp flow: executes · Runner enters the main Python download workflow.
- yt-dlp flow → palladium_ytdlp: depends on · The flow relies on the bundled Python package implementation.
- palladium_ytdlp → FFmpeg bridge: integrates · Python side includes media-processing bridge support.
- Share extension → Download flow: hands off to · Shared content becomes a download request for the main app.
- Share extension → App models: uses · Extension may pass along or derive request state.
- Python runtime setup → Python runner: prepares · Runtime setup supports the embedded Python bridge.
- IPA build → Python runtime setup: packages · Build tooling assembles the runtime into the distributable app.