Siphonix — Universal Terminal Media Downloader

  ███████╗██╗██████╗ ██╗  ██╗ ██████╗ ███╗   ██╗██╗██╗  ██╗
  ██╔════╝██║██╔══██╗██║  ██║██╔═══██╗████╗  ██║██║╚██╗██╔╝
  ███████╗██║██████╔╝███████║██║   ██║██╔██╗ ██║██║ ╚███╔╝ 
  ╚════██║██║██╔═══╝ ██╔══██║██║   ██║██║╚██╗██║██║ ██╔██╗ 
  ███████║██║██║     ██║  ██║╚██████╔╝██║ ╚████║██║██╔╝ ██╗
  ╚══════╝╚═╝╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝╚═╝  ╚═╝
  Siphonix v0.1.0 — Universal Terminal Media Extraction Engine

Downloading online media should be effortless, fast, and completely reliable. Yet the modern media extraction ecosystem is riddled with compromises: ad-infested web converters, bloated Electron wrappers, or raw command-line tools that dump non-standard video streams incompatible with native hardware players.

The Compatibility Bottleneck: Why Downloads Fail to Play

Modern streaming platforms optimize for their own bandwidth consumption rather than user hardware compatibility. Default downloads often fetch Google’s VP9 or AV01 video containers paired with Opus audio streams. On Apple platforms — macOS QuickTime Player, iPadOS, iOS Photos, and Final Cut Pro — or default Windows Media Player, these files refuse to play without third-party tools like VLC.

Siphonix resolves this fundamentally at the multiplexing stage. Every MP4 video stream extracted by Siphonix is passed through an automated FFmpeg transcode filter that enforces H.264 (avc1) video encoding paired with 320 kbps AAC (mp4a) audio. This guarantees that files play natively with hardware-accelerated decoding across Apple Silicon, Windows, and Linux with zero lag or missing tracks.

Core System Capabilities

• —<strong>Universal Native Playback:</strong> Automatic multiplexing into high-bitrate H.264 and 320 kbps AAC ensures universal compatibility with QuickTime, mobile camera rolls, and desktop editing suites.
• —<strong>Studio-Quality Audio Extraction:</strong> Direct stream-ripping into pristine 320 kbps MP3 or lossless 24-bit FLAC from the highest available source audio streams (ba/b), complete with embedded ID3 metadata tags and album cover art.
• —<strong>Dual Interaction Modes:</strong> Operates as a distraction-free 4-step interactive terminal wizard (navigated with number keys 1–7 via inquire) or as a scriptable headless CLI driven by clap.
• —<strong>Real-Time Streaming Diagnostics:</strong> Asynchronous regex parsers stream live progress bars (indicatif) displaying download percentages, network throughput (MiB/s), and ETA countdowns.
• —<strong>Download Provenance via SQLite:</strong> Embedded SQLite database using Write-Ahead Logging (WAL) tracks all downloads, original source URLs, local paths, and file integrity hashes (siphonix --history).
• —<strong>Zero-Orphan Process Isolation:</strong> Subprocesses (yt-dlp, FFmpeg) are encapsulated with kill_on_drop(true). On SIGINT (Ctrl+C), active child processes are immediately reaped and partial .part/.ytdl staging files are cleaned up from disk.

Execution Pipeline & Subprocess Architecture

[CLI Arguments / Interactive TUI Wizard]
                 │
                 ▼
[URL Extraction & Metadata Probe (yt-dlp JSON)]
                 │
                 ▼
[Format Resolver & Codec Matrix Selection]
       ├─ Video: MP4 (H.264 avc1 + 320k AAC mp4a) / MKV
       └─ Audio: MP3 (320 kbps CBR) / FLAC (Lossless Studio)
                 │
                 ▼
[Asynchronous Download Worker (Tokio Subprocess)]
       ├─ Real-Time Stream Parser (indicatif TUI)
       └─ Process Supervisor (kill_on_drop & SIGINT Handler)
                 │
                 ▼
[FFmpeg Multiplexing, Codec Conversion & Metadata Tagging]
                 │
                 ▼
[SQLite WAL Audit Ledger + Desktop Revealer (opener)]

Direct CLI Commands & Scripting

Beyond the interactive wizard, Siphonix provides a full suite of direct flags for power users, terminal keybindings, and automated cron pipelines:

# Download MP4 Video in 1080p Full HD (Universal QuickTime Playback)
siphonix "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -m video -f MP4 -q 1080p

# Download MP4 Video in 4K (2160p Ultra HD)
siphonix "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -m video -f MP4 -q 2160p

# Download Studio-Grade 320 kbps MP3 with Embedded Cover Art
siphonix "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -m audio -f MP3 -q 320k

# Download Lossless 24-Bit FLAC Audio
siphonix "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -m audio -f FLAC

# Inspect Download History and Verified Provenance
siphonix --history

# Verify Underlying Engine Diagnostics (yt-dlp and FFmpeg)
siphonix --diagnostics

Engineering Reflections & Repository

Building Siphonix in Rust underscored the power of fearless concurrency and memory safety in systems tooling. By offloading resource-heavy extraction to managed subprocesses while maintaining strict ownership of process lifecycles and signal interrupts, Siphonix delivers a resilient, high-speed terminal experience that never panics or leaves orphaned background workers.

The open-source repository, full documentation, and cross-platform installation scripts are published on GitHub: github.com/cp099/Siphonix.