💎 CrystalMedia
A hyper-interactive terminal downloader for YouTube MP4/MP3 with a live Rich UI.
⚡ Jump To
- 🚀 30-Second Quick Start
- 🧪 Interactive README + Full Visual Walkthrough
- 🎮 Interactive Walkthrough
- ⌨️ Controls Cheatsheet
- 🧠 Download Modes
- 🖥️ Live UI Preview
- 📁 Output Structure
- 🛠 Requirements
- ❗ MIT License + Legal Warning
🚀 30-Second Quick Start
# From PyPI (recommended)
pip install crystalmedia
crystalmedia
# From source
git clone https://github.com/Thegamerprogrammer/CrystalMedia.git
cd CrystalMedia
pip install .
crystalmedia
On first launch, CrystalMedia runs a dependency preflight/status check and self-healing diagnostics. Runtime auto-install of dependencies is disabled for packaging safety; install/update dependencies through pip.
It now also initializes output configuration once (crystalmedia_config.json) and defaults downloads/logs to CrystalMedia_output/ unless you choose a custom path.
🧪 Interactive README + Full Visual Walkthrough
Before install, you can explore a modern clickable mini site + complete visual docs:
- Interactive README (glass UI):
docs/interactive-readme.html - Pre-install demo:
docs/interactive-demo.html - PyPI page: https://pypi.org/project/crystalmedia/
On Windows, open
docs\interactive-readme.htmldirectly in your browser.
Full Screenshot Gallery (Setup + Functions + Troubleshooting)
Setup
Core UI
YouTube Functions
Spotify Functions
When You Get Stuck
🎮 Interactive Walkthrough
When the app starts, the flow is designed to feel game-like and guided:
- Splash appears (
CrystalMedialogo + version) - Main menu opens (YouTube Video / YouTube Music / Spotify / Exit)
- You choose (all animated with the starfield):
- Single item or playlist
- URL
- MP4 quality or MP3 bitrate
- JavaScript runtime preference (Auto / Deno-first / Node-first)
- Live UI kicks in:
- Header panel with current context
Progresspanel (single progress bar)Download Logpanel (bounded recent yt-dlp events)
- On completion, timeout prompt waits for input (or auto-returns)
⌨️ Controls Cheatsheet
| Action | Key |
|---|---|
| Move up/down in menu | ↑ / ↓ |
| Select menu item | Enter |
| Skip wait timer / continue now | Any key or Enter |
| Interrupt current flow | Ctrl + C |
🧠 Download Modes
🎬 YouTube Video (MP4)
- Quality presets: low → best available
- Single or playlist
- Remux/postprocess handling with ffmpeg
🎵 YouTube Music (MP3)
- Bitrate presets: 96 → 320 kbps
- Single or playlist
- Audio extraction postprocessing
🎧 Spotify (Exportify-first Playlist Mode)
- Single track: reads Spotify metadata and downloads via
yt-dlpsearch (with automatic browser-cookie fallback for age-restricted YouTube matches). - Playlist/album: Exportify CSV is the primary path.
- Open your playlist URL in CrystalMedia.
- CrystalMedia opens
vendor/exportify/index.htmlhelper + Exportify in browser. - Export the same playlist and save CSV in
./csv(next toCrystalMedia.py). - Filename matching is used as a hint; CrystalMedia will still try the newest CSV if names do not match.
- CrystalMedia reads that CSV and downloads each song via
yt-dlpsearch.
If no CSV is found, CrystalMedia attempts direct Spotify page scraping fallback.
🍪 Age-restricted YouTube matches (Spotify fallback)
- CrystalMedia now auto-tries
yt-dlp --cookies-from-browserprofiles when YouTube returns age/sign-in restrictions. - For best results, sign in to YouTube in your normal (non-incognito) browser profile first.
- If browser-cookie extraction still fails, export a Netscape cookies file and pass it manually in yt-dlp workflows.
🖥️ Live UI Preview
CrystalMedia uses a fixed Rich layout to keep output readable:
- Animated splash header: CrystalMedia logo + live starfield + current download context
- Progress panel: one progress bar (download/processing/merging)
- Download Log panel: compact rolling logs with truncation + color tags
This minimizes noisy terminal spam and keeps the interface focused.
📁 Output Structure
CrystalMedia_output/ # default root (configurable once at startup)
├── downloads/
│ ├── YT VIDEO/
│ │ ├── Single/
│ │ └── Playlist/
│ ├── YT MUSIC/
│ │ ├── Single/
│ │ └── Playlist/
│ └── SPOTIFY/
│ ├── Single/
│ └── Playlist/
└── logs/
├── log.txt
├── crash.txt
└── deps.txt
crystalmedia_config.json # persists custom output_root
🛠 Requirements
- Python 3.8+
- Internet connection
- FFmpeg (install via your OS package manager, or use Docker below)
🐳 Docker (no host Python/FFmpeg install required)
If you prefer not to install Python/FFmpeg directly on your machine, run CrystalMedia in Docker:
docker build -t crystalmedia .
Linux/macOS:
docker run --rm -it \
-v "$(pwd)/CrystalMedia:/app/CrystalMedia" \
-v "$(pwd)/csv:/app/csv" \
crystalmedia
Windows PowerShell:
docker run --rm -it `
-v "${PWD}/CrystalMedia:/app/CrystalMedia" `
-v "${PWD}/csv:/app/csv" `
crystalmedia
This keeps your host clean while still running the full TUI flow.
❗ MIT License + Legal Warning
CrystalMedia is released under the MIT License (see LICENSE).
Important warning
- The MIT License allows broad use/modification/distribution of this software.
- It does not grant rights to download copyrighted media without permission.
- You are solely responsible for how you use this tool and for compliance with local laws/platform terms.
Use responsibly and only with content you are authorized to download.
-
No Affiliation CrystalMedia is an independent, unofficial, community-developed project with no affiliation, endorsement, or partnership with YouTube, Google LLC, Spotify AB, or any related entities. Dependency Notices
-
This project uses third-party libraries including yt-dlp and relies on user-provided data/credentials. The authors do not control, modify, or distribute these dependencies in any infringing manner. Takedown Compliance
-
Indemnification
-
By using CrystalMedia, you agree to indemnify, defend, and hold harmless the authors, contributors, maintainers, and distributors of this software from and against any and all claims, damages, losses, liabilities, costs, or expenses (including reasonable attorneys' fees) arising from or related to your use, misuse, distribution, or operation of the software.
-
This includes, but is not limited to, claims involving copyright infringement, violations of platform terms of service, or violations of local, national, or international laws. The responsibility for ensuring that the use of CrystalMedia complies with applicable laws and platform policies rests solely with the user.
-
By using CrystalMedia, you agree to indemnify and hold harmless the authors, contributors, and any associated parties from any claims, damages, losses, liabilities, costs, or expenses (including attorneys' fees) arising from your use or misuse of the software.
CrystalMedia does not circumvent digital rights management (DRM).
It relies on publicly available interfaces and third-party libraries.
🧯 Troubleshooting
- If terminal rendering looks off after a resize, return to the main menu and start the download again.
- Check
CrystalMedia/logs/crash.txtfor error traces andCrystalMedia/logs/deps.txtfor dependency snapshots after startup. - On unrecoverable errors, CrystalMedia shows a fatal error panel, writes details to
CrystalMedia/logs/crash.txt, and exits cleanly.
PRs are welcome for UI polish, reliability improvements, and Spotify-mode recovery when upstream ecosystem changes stabilize.
🧾 Exportify CSV (Playlist) Quick Notes
- CSV files must be in
./csv(relative to where you runCrystalMedia.py). - Leave filename blank in prompt to auto-detect latest CSV in
./csvthat matches playlist name. - Playlist title is auto-derived from the Spotify playlist link and used for fuzzy CSV matching.
Update Changelog(github, pypi)
- v3.1.9-v4.0.0(UI Changes)
- v4.0.0-v4.0.1(update readme.md)
- v4.0.1-v4.0.2(update readme.md)
Metadata
Release files for crystalmedia 4.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| crystalmedia-4.0.2.tar.gz | 61.2 kB | Without provenance | Details for crystalmedia-4.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| crystalmedia-4.0.2-py3-none-any.whl | Python 3 | none | any | Details for crystalmedia-4.0.2-py3-none-any.whl |
Total release size: 102.2 kB
Release files / crystalmedia-4.0.2.tar.gz
| Download URL | crystalmedia-4.0.2.tar.gz |
|---|---|
| Size | 61.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
64e50df79a19714fcda24a60c99a59a6c2e667eb6f7723d6ca88f83fe44d9173
|
|
BLAKE2b-256 checksum How to use checksums |
c87ddd06c161d2f21f0c15faacdc1a8fd826be95bb346c573dfc042f4b4e414b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0
|
Release files / crystalmedia-4.0.2-py3-none-any.whl
| Download URL | crystalmedia-4.0.2-py3-none-any.whl |
|---|---|
| Size | 41.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e52dfffb7149b9b770bbb8ad6c445224f24af933a8f62d90c2503eeaa3fbfb14
|
|
BLAKE2b-256 checksum How to use checksums |
4d155b1422e4e4a29f8c251cd979a3e12826f1d846fed9f5a0f19a65a77e2645
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0
|
Security for crystalmedia 4.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.