mirror of
https://github.com/nimbold/Firelink.git
synced 2026-07-27 12:29:29 +00:00
docs: simplify and restructure README to GitHub standards
This commit is contained in:
nimbold
@@ -1,97 +1,100 @@
|
||||
# Firelink
|
||||
<div align="center">
|
||||
<h1>Firelink</h1>
|
||||
<p><strong>A clean, native SwiftUI download manager for Apple Silicon macOS</strong></p>
|
||||
|
||||
Firelink is a clean SwiftUI download manager for Apple Silicon Macs. The goal is to bring the practical parts of IDM/FDM-style download management to macOS with a native interface, segmented downloads, queue control, automatic file organization, and credential-aware transfers.
|
||||
[](https://swift.org)
|
||||
[](https://apple.com)
|
||||
[](https://aria2.github.io/)
|
||||
[](LICENSE)
|
||||
</div>
|
||||
|
||||
This project is early, but it already has a working native prototype, an `aria2c`-backed download engine, a queue-focused UI, batch link intake, and app-wide settings.
|
||||
---
|
||||
|
||||
## Features
|
||||
**Firelink** brings the efficiency of multi-segmented download managers (like IDM or FDM) to macOS with a modern, native SwiftUI interface. Designed specifically for Apple Silicon, it delivers high-speed concurrent transfers, drag-and-drop queue control, automated file organization, and Keychain-secured authentication—all in a lightweight native package.
|
||||
|
||||
- Native SwiftUI macOS interface.
|
||||
- Segmented downloads with a per-file connection count that also controls the split count.
|
||||
- Multiple files downloading at the same time.
|
||||
- Queue-based downloads with drag-and-drop priority ordering.
|
||||
- Batch Add Downloads window for pasting one or many links at once.
|
||||
- Automatic link parsing from newlines, whitespace, and common separators.
|
||||
- Metadata preview for new downloads, including file size when the server reports it.
|
||||
- Total required disk space and available disk space summary before adding downloads.
|
||||
- Per-batch save location override, while keeping automatic file-type folders by default.
|
||||
- Native macOS Settings window, available from App menu > Settings and the main toolbar.
|
||||
- Configurable default per-server connection count.
|
||||
- Configurable parallel file download limit in Settings.
|
||||
- Per-batch connection controls in the Add Downloads window.
|
||||
- Sidebar filters for all downloads, queued, active, completed, failed, and file categories.
|
||||
- Sortable, resizable download table columns with a right-click column chooser.
|
||||
- Default table columns for file name, size, progress/status, ETA, last try date, and date added.
|
||||
- Download row context menu with properties, show in Finder, resume, stop, queue, and delete actions.
|
||||
- Download properties window for editing URL, file name, save location, connection count, and login behavior.
|
||||
- Delete confirmation with optional move-to-Trash for downloaded or partial files.
|
||||
- Automatic cleanup of unfinished `.aria2` cache files when removing incomplete downloads.
|
||||
- Automatic save folders under `~/Downloads`:
|
||||
- `Musics`
|
||||
- `Movies`
|
||||
- `Compressed`
|
||||
- `Pictures`
|
||||
- `Documents`
|
||||
- `Other`
|
||||
- Custom download locations per file category.
|
||||
- Broad file extension detection for audio, video, archive, image, and document formats.
|
||||
- HTTP, HTTPS, FTP, and SFTP URL support through `aria2c`.
|
||||
- Site login rules with URL pattern matching and Keychain-stored passwords.
|
||||
- Optional prevention of system sleep while files are downloading, while still allowing display sleep.
|
||||
- Pause, resume, cancel, delete, progress, speed, ETA, and connection count display.
|
||||
- Release `.app` bundle script for local macOS builds.
|
||||
---
|
||||
|
||||
## Engine
|
||||
## ✨ Key Features
|
||||
|
||||
This first version uses `aria2c` as the download engine. It is a better fit than plain `curl` for the requested IDM/FDM-style behavior because it has segmented downloads, resumable transfers, concurrent downloads, HTTP/FTP/SFTP support, and username/password options built in.
|
||||
- ⚡ **High-Speed Downloads:** Multi-segmented download engine powered by `aria2c` for concurrent connections and optimal bandwidth utilization. Supports HTTP, HTTPS, FTP, and SFTP.
|
||||
- 🎨 **Native macOS & SwiftUI:** Responsive interface designed natively for Apple Silicon, featuring resizable tables, customizable columns, sidebar filters, and a native Settings panel.
|
||||
- 🗂️ **Smart Queue & Categories:** Drag-and-drop priority ordering, batch link ingestion with smart parsing, and automatic file organization (`Musics`, `Movies`, `Compressed`, `Pictures`, `Documents`, `Other`) based on extension detection.
|
||||
- 🔒 **Keychain Security:** Local macOS Keychain integration for secure site credential storage and matching during transfers.
|
||||
- ⚙️ **Power & System Integrity:** Optional system sleep prevention during active downloads, disk-space safety checks, and automated cleanup of partial `.aria2` metadata cache files.
|
||||
|
||||
Firelink uses one per-file connection value for both `aria2c` split count and same-server connection count. That keeps the download behavior close to the familiar IDM-style model: choosing 8 connections splits the file into 8 parallel segments.
|
||||
<details>
|
||||
<summary>🔍 View Full Feature Index (30+ features)</summary>
|
||||
|
||||
## Requirements
|
||||
### All native SwiftUI macOS features:
|
||||
|
||||
Install the engine:
|
||||
- **Core Download Engine:**
|
||||
- Segmented downloads with per-file connection/split counts.
|
||||
- Multi-threaded, parallel downloading with configurable limits.
|
||||
- Support for HTTP, HTTPS, FTP, and SFTP transfers via `aria2c`.
|
||||
- **Advanced Queue Control:**
|
||||
- Drag-and-drop download reordering to manage priorities.
|
||||
- Comprehensive download table with resizable, custom columns (Name, Size, Status, ETA, Dates).
|
||||
- Individual download controls: pause, resume, stop, and queue actions.
|
||||
- **Smart Link Ingestion:**
|
||||
- Batch Add window for pasting multiple links at once.
|
||||
- Automated link parsing (whitespaces, newlines, standard separators).
|
||||
- Disk space availability checks and total size calculation prior to adding.
|
||||
- **File Organization:**
|
||||
- Automatic categorization of files (Music, Movies, Compressed, Documents, Images) into structured subfolders under `~/Downloads`.
|
||||
- Smart fallback to customizable download folders per category.
|
||||
- Automatic cleanup of unfinished `.aria2` metadata/cache files on removal.
|
||||
- **Security & System:**
|
||||
- Local macOS Keychain integration for site logins.
|
||||
- Prevents system sleep while active transfers are in progress, preserving display sleep.
|
||||
- Release `.app` bundle build scripts ready for distribution.
|
||||
|
||||
```sh
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Engine Architecture
|
||||
|
||||
Firelink leverages `aria2c` under the hood as its core download engine. Unlike standard `curl`, `aria2c` allows:
|
||||
- **Segmented Downloads:** Splits files into multiple streams for maximum transfer speeds.
|
||||
- **Unified Connection Control:** A single slider regulates both the server connection count and segment split count, matching the intuitive behavior of classic managers like IDM/FDM.
|
||||
- **Built-in Resumability:** Seamlessly resumes interrupted or paused downloads without data corruption.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Requirements & Setup
|
||||
|
||||
### 1. Install Dependencies
|
||||
Ensure you have **Homebrew** and the **Swift toolchain** installed:
|
||||
```bash
|
||||
brew install aria2
|
||||
```
|
||||
- **OS Support:** macOS 14.0 or newer (built natively for Apple Silicon)
|
||||
- **Toolchain:** Xcode 15+ / Swift 6.0 toolchain
|
||||
|
||||
- macOS 14 or newer.
|
||||
- Apple Silicon Mac.
|
||||
- Swift 6 toolchain.
|
||||
- `aria2c` installed with Homebrew, or bundled into the app resources later.
|
||||
|
||||
## Run
|
||||
|
||||
```sh
|
||||
### 2. Build & Run
|
||||
Run the application directly via the terminal:
|
||||
```bash
|
||||
swift run Firelink
|
||||
```
|
||||
|
||||
Build a release `.app` bundle:
|
||||
|
||||
```sh
|
||||
make app
|
||||
open build/Firelink.app
|
||||
Or build a production `.app` bundle:
|
||||
```bash
|
||||
make app && open build/Firelink.app
|
||||
```
|
||||
|
||||
Because the current machine only has Command Line Tools selected, this repository is set up as a Swift Package with a bundling script rather than a generated Xcode project. Opening the package in Xcode will still give you a native macOS app workflow.
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
## 🗺️ Roadmap
|
||||
|
||||
- Persist download history, queue order, column choices, and active download state across launches.
|
||||
- Bundle or manage `aria2c` automatically so users do not need a separate Homebrew install.
|
||||
- Add first-class pause/resume semantics with clearer partial-file and cache handling.
|
||||
- Add per-download and global speed limits, plus scheduler rules for start/stop windows.
|
||||
- Add retry policies, mirror fallback, and richer failure recovery for unstable servers.
|
||||
- Add browser integration or a companion extension for capturing download links from Safari/Chrome/Firefox.
|
||||
- Add cookie/header support for authenticated downloads that require browser sessions.
|
||||
- Improve site-login editing, credential migration, and matching diagnostics.
|
||||
- Add duplicate detection for URLs, file names, and already-downloaded files.
|
||||
- Add checksum/hash verification and optional post-download integrity checks.
|
||||
- Add download history search, saved filters, and better category management.
|
||||
- Add signed/notarized release builds, auto-update support, and downloadable GitHub releases.
|
||||
- Add localization-ready strings and accessibility review for keyboard and VoiceOver workflows.
|
||||
- Add unit and integration tests for file classification, URL parsing, queue behavior, settings persistence, `aria2c` progress parsing, and metadata fetching.
|
||||
- [ ] **Data Persistence:** Store history, column layout preferences, and active queues across restarts.
|
||||
- [ ] **Zero-Config Setup:** Automatically bundle and configure `aria2c` inside the `.app` bundle.
|
||||
- [ ] **Bandwidth Limits:** Add global and per-download speed caps and calendar schedules.
|
||||
- [ ] **Browser Extensions:** Capture links directly from Safari, Chrome, and Firefox.
|
||||
- [ ] **Advanced Transfer Features:** Checksum validation, cookie/header ingestion, and smart mirror failovers.
|
||||
- [ ] **Distribution:** Notarized release builds, automated Sparkle updates, and Homebrew formulae.
|
||||
|
||||
## License
|
||||
---
|
||||
|
||||
Firelink is released under the MIT License. See [LICENSE](LICENSE).
|
||||
## 📄 License
|
||||
|
||||
Firelink is released under the MIT License. See [LICENSE](LICENSE) for details.
|
||||
|
||||
Reference in New Issue
Block a user