Cascade

Unified, high-performance personal cloud storage and media streaming suite.

Platforms • Features • Architecture • Installation • Building • Security & Privacy • Contributing • License

---

Overview

Cascade is a modern, cross-platform personal cloud drive and high-performance media streaming suite engineered for speed, fluid navigation, and instant 4K HDR playback. Connecting to your personal cloud via open MTProto/TDLib protocol, Cascade transforms your cloud account into an unlimited, structured file drive, multimedia library, and secure digital vault across desktop and mobile devices.

Files are cataloged locally in high-performance SQLite storage and transferred using uniform ~1.9 GiB chunking, engineered to fit comfortably beneath single-document upload ceilings while minimizing message overhead and maximizing transfer throughput.

---

📱 Platform Support & Availability

Cascade is designed natively for each operating system:

Platform	Status	Distribution	Minimum Version	Architecture
macOS	Public Beta (Available Now)	DMG (Direct) / Sparkle OTA	macOS 15.0+	Universal (arm64 + x86_64)
iOS / iPadOS	Coming Soon	Direct Sideloading (.ipa / AltStore / TrollStore)	iOS 17.0+	arm64
Android	Coming Soon	Direct Download (.apk)	Android 7.0+ (API 24+)	arm64-v8a, armeabi-v7a, x86_64
Windows	Planned	Native Installer / MSIX	Windows 10 / 11	x64, ARM64
Linux	Planned	AppImage / Flatpak	Modern Distributions	x86_64, aarch64

---

Features

• 🎬 Native MPV Media Engine
  Built-in custom libmpv media pipeline for hardware-accelerated playback of 4K HDR (AV1, HEVC, H.264), lossless audio (FLAC, ALAC, Opus), and advanced subtitle rendering (ASS/SSA, SRT, VTT).

• ⚡️ Instant Byte-Range Cloud Streaming
  Stream high-bitrate videos and audio files directly from your cloud storage without waiting for full downloads. Cascade's internal loopback HTTP range server (VaultStreamServer) serves virtual byte ranges directly to the media engine for zero-wait seeking and scrubbing.

• 📦 Uniform ~1.9 GiB Chunking
  Large files are partitioned into uniform ~1.9 GiB chunks, maximizing single-document upload ceilings while minimizing message count. Small and medium files under 1.9 GiB upload as single, intact documents. Upload and download resumption is handled reliably at internal part granularity via TDLib.

• 🔍 Across-App Global Search
  Search instantly across all folders, subfolders, media categories, books, and documents. Includes scope toggling (Everywhere vs. Current Folder), breadcrumb path tags, and "Show in Enclosing Folder".

• 🛡️ Biometric Private Vault
  A dedicated locked partition protected by biometric authentication (Touch ID, Face ID, Fingerprint) or master PIN. Hidden from the main library and search until explicitly unlocked. PIN verification is backed by PBKDF2-HMAC-SHA256 (600,000 iterations) with exponential attempt backoff.

• 📚 Integrated Readers & Collections
  Built-in EPUB and PDF reader with reading progress tracking, alongside smart categories for Photos, Videos, Audio, Documents, and Books.

• 📝 Integrated Notes
  Fast, lightweight note-taking space with Markdown preview, auto-detected links, and tag filtering.

• 💾 Adaptive Offline Cache & Pinning
  Mark files or entire folders with "Keep Downloaded" for offline access. The engine includes an adaptive LRU cache that respects system disk pressure.

• 🔄 Over-the-Air (OTA) Updates
  Built-in seamless automatic updates. On macOS, updates are powered by Sparkle 2 with Ed25519 cryptographic signature verification, available directly from the app menu or Settings.

• 🎨 Adaptive Platform-Native Design
  Engineered natively for each platform—featuring liquid glass materials and vibrancy on macOS and iOS, Material You on Android, and Fluent styling on Windows. Automatically adapts to standard translucent system materials on any display or hardware profile.

---

Architecture

graph TD
    A["Local Files / Dropped Assets"] --> B["ChunkPlanner (Uniform ~1.9 GiB)"]
    B --> C["UploadEngine / TDLib Client"]
    C --> D["Cloud Storage Channel"]

    D -.->|Byte-Range Streaming| E["VaultStreamServer (HTTP Loopback)"]
    E --> F["MPV Media Engine (Video / Audio)"]
    
    B --> G["Local SQLite Catalog (GRDB)"]
    G --> H["Cascade Native Interface (macOS / iOS / Android / Desktop)"]

Loading

• Chunk Management: ChunkPlanner determines document boundaries with a uniform 1,900 MiB safe ceiling.
• Transfer Engines: UploadEngine and DownloadEngine manage concurrent transfers, TDLib-backed resumes, and automatic network retry.
• Local Catalog: Stored in a local SQLite database via GRDB, providing instant search, tagging, folder hierarchy navigation, and offline metadata access.
• Streaming Pipeline: VaultStreamServer serves virtual HTTP byte ranges straight into libmpv, enabling instant scrubbing through multi-gigabyte media without downloading the whole file.

---

Installation

macOS (Beta Available Now)

Download the latest release disk image from the Releases page:

1. Download Cascade-1.2.0.dmg.
2. Open the disk image and drag Cascade to your Applications folder.
3. Launch Cascade and connect your account via phone number.

Note for macOS Gatekeeper: Because this is a pre-release developer beta, macOS may block the app on first launch with an unidentified developer notice. On macOS 15 (Sequoia) and later, you can open it via:

• System Settings: Go to System Settings > Privacy & Security, scroll down to the Security section, and click Open Anyway.
• Terminal: Alternatively, remove the quarantine attribute by running:

  xattr -cr /Applications/Cascade.app

iOS & Android (Coming Soon)

• iOS / iPadOS: Pre-built .ipa packages will be distributed for direct sideloading (via AltStore, SideStore, TrollStore, or manual developer signing). Cascade for iOS is distributed independently outside the Apple App Store.
• Android: Pre-built standalone .apk packages will be available directly on the Releases page.

Windows & Linux (Planned)

Native desktop clients for Windows and Linux are planned on the project roadmap and will begin development following the mobile rollouts.

---

Building from Source

macOS

Prerequisites:

• macOS 15.0 or later
• Xcode 16.0 or later with Command Line Tools
• create-dmg (optional, for packaging installer disk images)

# Clone the repository
git clone https://github.com/entanglon/cascade.git
cd cascade

# Build the Debug scheme
xcodebuild -project Cascade.xcodeproj -scheme Cascade -destination 'platform=macOS' build

# Build the Release DMG package
bash scripts/make_dmg.sh 1.2.0

---

Security & Privacy

1. Hardware-Backed Credential Storage: Account credentials and vault authentication tokens are stored securely in platform-native credential storage (Keychain on macOS/iOS, Keystore on Android, Credential Locker on Windows, Secret Service on Linux).
2. Biometric Protection: Vault unlock uses hardware biometric sensors (Touch ID, Face ID, BiometricPrompt) backed by the device's Secure Enclave / TEE, with exponential backoff on repeated PIN failures.
3. Hardened Runtime: Built with macOS Hardened Runtime enabled for code-signing tamper resistance.

---

Contributing

Contributions are welcome! Please read our Contributing Guidelines for instructions on setting up the development environment, running tests, and opening Pull Requests.

---

License & Legal

Cascade is licensed under the GNU General Public License v3.0 (GPLv3) with additional terms pursuant to Section 7:

• Trademark & Brand Reservation: All rights to the trade name "Cascade", "Entanglon", official application icons, and brand graphics are strictly reserved by Entanglon and excluded from the open-source license grant. Modified or forked versions must adopt their own distinct name, icon, and branding.
• Third-Party Acknowledgements: Cascade integrates open-source components under their respective licenses:
  • TDLib: Boost Software License 1.0 © Telegram FZ-LLC
  • libmpv: LGPLv2.1+ / GPLv2+ © mpv development team
  • GRDB.swift: MIT License © Gwendal Roué
  • Sparkle: MIT License © Andy Matuschak & Sparkle contributors