Skip to main content

💎 CrystalMedia

A hyper-interactive terminal downloader for YouTube MP4/MP3 with a live Rich UI.

License: MIT Python


⚡ Jump To


🚀 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:

On Windows, open docs\interactive-readme.html directly in your browser.

Setup

Setup Python Setup PyPI Install Setup Source Install

Core UI

Splash Main Menu Success

YouTube Functions

YouTube Flow YouTube MP4 Quality YouTube MP3 Bitrate

Spotify Functions

Spotify Exportify Spotify Single Spotify Playlist CSV

When You Get Stuck

Stuck Help Age Restricted Troubleshooting Missing Dependencies Troubleshooting Output and Logs

🎮 Interactive Walkthrough

When the app starts, the flow is designed to feel game-like and guided:

  1. Splash appears (CrystalMedia logo + version)
  2. Main menu opens (YouTube Video / YouTube Music / Spotify / Exit)
  3. 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)
  4. Live UI kicks in:
    • Header panel with current context
    • Progress panel (single progress bar)
    • Download Log panel (bounded recent yt-dlp events)
  5. 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-dlp search (with automatic browser-cookie fallback for age-restricted YouTube matches).
  • Playlist/album: Exportify CSV is the primary path.
    1. Open your playlist URL in CrystalMedia.
    2. CrystalMedia opens vendor/exportify/index.html helper + Exportify in browser.
    3. Export the same playlist and save CSV in ./csv (next to CrystalMedia.py).
    4. Filename matching is used as a hint; CrystalMedia will still try the newest CSV if names do not match.
    5. CrystalMedia reads that CSV and downloads each song via yt-dlp search.

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-browser profiles 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.


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.txt for error traces and CrystalMedia/logs/deps.txt for 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 run CrystalMedia.py).
  • Leave filename blank in prompt to auto-detect latest CSV in ./csv that 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)

Source distribution for crystalmedia 4.0.2
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)

Table of built distributions (wheels) for crystalmedia 4.0.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page