English | Bahasa Indonesia

✨ About

Lumenfetch is a lightweight Python CLI that downloads YouTube videos as MP4 or extracts their audio as MP3. Just paste a link and it auto-detects the title, duration, and estimated file size, then offers the relevant quality options. Powered by yt-dlp under the hood, plus curl_cffi to pass YouTube's bot checks.

"One command, straight to MP4/MP3."

🎯 Features

📦 Requirements

• Python 3.9 or newer
• Internet connection
• Libraries: yt-dlp, rich, curl_cffi, auto-installed with lumenfetch, no manual install needed

ffmpeg does not need manual install - Lumenfetch uses your system ffmpeg if present, otherwise it automatically downloads its own bundled copy (via static-ffmpeg) on first use, just like ffmpeg-static in Node.js projects.

Never used a terminal? Start here

No Python yet?

1. Open python.org/downloads and download the latest version
2. Windows only: on the first installer screen, tick "Add Python to PATH" before clicking Install. If you skip this, the python command won't be recognized later
3. After installing, open a terminal (see above) and check with:

python --version
# or
python3 --version

If a version number shows up (e.g. Python 3.12.1), you're ready.

🚀 Installation

Option A: Install from PyPI (easiest)

pip install lumenfetch

If pip is not recognized, try:

python -m pip install lumenfetch

If you get an externally-managed-environment error (usually on Linux):

pip install lumenfetch --break-system-packages

Once installed, the lumenfetch command works from any terminal, continue to Usage.

Option B: Install from source (for development / reading the code)

1. Get the code

git clone https://github.com/nekonaru/lumenfetch.git
cd lumenfetch

cd Downloads/lumenfetch-main

2. Install in "editable" mode

pip install -e .

Same as Option A, append --break-system-packages if you hit the externally-managed-environment error.

This also registers the lumenfetch command, but it uses the code straight from this folder, handy if you want to modify the code and see results without reinstalling.

🖥️ Usage

Run:

lumenfetch

If you installed from source without pip install -e ., run via python main.py from inside the project folder instead, but the editable install above is recommended.

Paste a YouTube URL when asked:

Masukkan URL YouTube (q: keluar, history, settings, help): https://youtube.com/watch?v=...

If there is a valid link in your clipboard, Lumenfetch offers it first - just answer y to use it.

Pick an output type:

Pilih tipe output:
  [1] Video (MP4)
  [2] Audio (MP3)

Pick a quality (size & ETA estimates included):

Pilih Quality:
  [1] Best   (default)  (~147.8 MB, ~31 detik)
  [2] 1080p              (~147.8 MB, ~31 detik)
  [3] 720p               (~81.1 MB, ~17 detik)
  [4] 480p               (~42.9 MB, ~9 detik)

Confirm the filename, then the download runs with a real-time progress bar (speed, size, ETA). Press Ctrl+C anytime to cancel safely.

Done! 🎉

✅ Selesai!
   File  : C:\Users\user\Downloads\YouTube_Lofi-Hip-Hop-Radio_2026.mp4
   Ukuran: 81.1 MB
   Waktu : 17 detik

↻ Resume Otomatis

If a download stops halfway (connection drops, terminal closed), the partial .part file stays on disk.

Just run the same URL again and yt-dlp resumes from where it stopped instead of starting over. Connection errors are also retried automatically with exponential backoff (2s, 4s, 8s... max 30s).

⚙️ Preferensi Tersimpan

Your download folder, max retry, auto-paste, naming template, and cookies choice are saved automatically in your user config dir and reused as defaults next session:

Detailed logs live in lumenfetch.log in the same folder (run with -v/--verbose for debug level).

🌍 Display Language

The CLI (menus, prompts, messages, and --help text) is available in English (default) and Bahasa Indonesia.

lumenfetch --ui-lang id              # Bahasa Indonesia, remembered for next sessions
lumenfetch --ui-lang en              # back to English
LUMENFETCH_LANG=id lumenfetch        # via environment variable (Windows: set LUMENFETCH_LANG=id)

Priority order: --ui-lang → LUMENFETCH_LANG env → ui_lang in user config → default en.

📜 Playlist

A playlist URL downloads only the first video by default (with a warning), so one URL never silently floods your folder. To grab the whole list as indexed files:

lumenfetch "https://youtube.com/playlist?list=PLxxxxxx" --playlist all -y

📦 Batch Download

Put one URL per line in a text file (# = comment), then:

lumenfetch --batch daftar.txt --jobs 2

🍪 Cookies (Optional)

Age-restricted or private videos need a login. If you hit such errors, enable one of these:

A. Browser cookies:

1. Open Lumenfetch, type settings
2. Pick [5] Pakai cookies dari browser/file
3. Pick the browser where you're logged into YouTube (Chrome/Firefox/Edge/Brave/Opera/Vivaldi/Safari)

Important: the chosen browser must be fully closed while downloading (its cookie file is locked while open - the error looks like Could not copy ... cookie database). Check Task Manager and kill all its processes (Edge/Chrome often keep running in the background).

B. Cookie file (most reliable, recommended if cookie errors persist):

1. Install the "Get cookies.txt LOCALLY" extension (Chrome/Edge/Firefox)
2. Open youtube.com (make sure you're logged in), click the extension → Export → save e.g. D:\cookies.txt
3. In Lumenfetch: settings → [5] → [1] Nonaktifkan → enter the cookie file path
4. Or via CLI: lumenfetch <URL> --cookies-file D:\cookies.txt

🤖 Non-Interactive Mode (Scripting/Automation)

Besides the Q&A mode, Lumenfetch also runs via command line arguments, handy for scheduling (cron/Task Scheduler) or calling from other scripts.

lumenfetch "https://youtube.com/watch?v=..." -t video -f mp4 -q 720p -y

Available arguments:

More examples:

# Audio only, best bitrate
lumenfetch "https://youtube.com/watch?v=..." -t audio -q 320kbps -y

# Whole playlist as MP4
lumenfetch "https://youtube.com/playlist?list=PLxxx" --playlist all -y

# With subtitles embedded
lumenfetch "https://youtube.com/watch?v=..." -t video --subs --embed-subs -y

# Batch of URLs, 2 at a time
lumenfetch --batch daftar.txt --jobs 2

# See all options
lumenfetch --help

📂 Output Structure

Filenames follow the template in settings (default: %(platform)s_%(title)s_%(year)s):

YouTube_Lofi-Hip-Hop-Radio_2026.mp4
YouTube_Lofi-Hip-Hop-Radio_2026.mp3

🗺️ Default Folder per OS

Change it anytime via the settings command ([1]), absolute paths and ~ are both accepted.

⚠️ Troubleshooting

📝 Important Notes

• Only YouTube links are accepted (youtube.com, youtu.be, music.youtube.com) - other platforms are rejected with a clear message, not a crash
• A Sign in to confirm you're not a bot message means YouTube is challenging automated requests: install/update curl_cffi + yt-dlp, then enable cookies
• This tool is for downloading videos you have the right to save (your own uploads, Creative Commons, offline watching). Respect creators' copyright

🛠️ Built With

🗂️ Project Structure

lumenfetch/
├── main.py                    # Entry point, CLI args, batch, main loop
├── core/
│   ├── constants.py           # Single source of truth (version, formats, limits)
│   ├── errors.py              # Central error taxonomy (classification + friendly messages)
│   ├── i18n.py                # UI strings (English default, Indonesian via --ui-lang)
│   ├── cli.py                 # Argument parsing + non-interactive choice building
│   ├── doctor.py              # Setup diagnosis (ffmpeg, deps, cookies, network)
│   ├── ffmpeg.py              # System ffmpeg first, bundled fallback
│   ├── log.py                 # Central file logging
│   ├── downloader.py          # MP4 download / MP3 extract + resume + retry backoff
│   ├── detector.py            # YouTube video info detection
│   ├── options.py             # Interactive menus & prompts (rich)
│   ├── update_checker.py      # Auto-check for newer yt-dlp on PyPI
│   └── utils.py               # Filename sanitizing, size formatting, user config
├── tests/
│   ├── conftest.py            # Global fixtures (no-sleep) + SAMPLE_VIDEO_FORMATS
│   ├── test_utils.py
│   ├── test_detector.py
│   ├── test_downloader.py
│   ├── test_options.py
│   ├── test_main.py
│   └── test_features.py       # Features (CLI, backoff, batch, ffmpeg, cookies, log)
├── .github/
│   └── workflows/
│       └── tests.yml          # CI: automatic test & lint
├── requirements.txt           # Dependency list (for manual reference)
├── pyproject.toml             # Package metadata + entry point + ruff config
├── CONTRIBUTING.md            # Contribution guide
├── LICENSE
├── README.md                  # Main docs (English)
└── README.id.md               # Docs (Bahasa Indonesia)

Module separation principles:

• constants.py, shared values (version, formats, limits) so modules never drift
• errors.py, central error classification used by detector & downloader together
• detector.py, purely detects YouTube video info, never downloads anything
• downloader.py, purely MP4/MP3 processing & progress, never shows menus
• options.py, all user interaction & menus, no download logic
• utils.py, pure helpers (sanitizing, formatting, config read/write), knows nothing about CLI or network
• main.py, ties everything together via CLI + main loop

🧪 Testing

Unit tests per module (filename sanitizing, naming templates, duplicate resolving, size/duration formatting, config, YouTube URL validation, yt-dlp opts, CLI, etc.).

pip install -e .[dev]
pytest tests/ -v
ruff check .

CI (.github/workflows/tests.yml) runs these automatically on every push & pull request to main.

🤝 Contributing

Want to help develop Lumenfetch? Read CONTRIBUTING.md for the project structure and contribution flow.

❓ FAQ

👤 Author

Nicolas Dwi Dharma
github.com/nekonaru

📄 License

Distributed under the MIT License. See LICENSE for more information.