🎬 vyank - YouTube Downloader

vyank is a small Tkinter desktop tool for downloading YouTube videos, audio, playlists, and channel videos. It uses pytubefix for YouTube access and ffmpeg for merging separate high-resolution video and audio streams into a final MP4 file.

The project is packaged as a Python application and is prepared for PyPI distribution. Publishing is not required for local use.

✅ Features

• Simple Tkinter GUI with tabs for different download workflows
• Download a single YouTube video
• Download comma-separated video URLs from the General tab
• Download audio-only streams
• Download playlists
• Download channel videos
• Automatically sanitizes video titles for safe filenames
• Downloads to the user Downloads folder by default
• Uses FFmpeg to merge adaptive video-only and audio-only streams
• Packaged with a vyank console entry point for PyPI installation

⚠️ Important Notes

YouTube Terms

Only download content that you own, are allowed to download, or are permitted to use under the content owner's terms. YouTube access behavior may change over time, so updating pytubefix may occasionally be required.

FFmpeg Requirement

vyank needs FFmpeg for video downloads that require separate video and audio streams to be merged.

The application calls ffmpeg from your system PATH. You do not need a hardcoded FFmpeg path in the source code.

Check whether FFmpeg is available:

ffmpeg -version

Install FFmpeg if needed:

Debian/Ubuntu:

sudo apt install ffmpeg

Arch Linux:

sudo pacman -S ffmpeg

Fedora:

sudo dnf install ffmpeg

macOS with Homebrew:

brew install ffmpeg

Windows:

1. Download FFmpeg from https://ffmpeg.org/download.html
2. Add the FFmpeg bin folder to your system PATH
3. Open a new terminal and run ffmpeg -version

💾 Installation

After publishing to PyPI, install with:

pip install vyank

For local development from this repository:

cd /path/to/vyank
python -m venv .venv
source .venv/bin/activate
pip install -e .

On Windows PowerShell:

cd C:\path\to\vyank
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

🚀 Usage

Launch the GUI after installation:

vyank

Run directly from the repository without installing:

python -m vyank.main

If you use the included virtual environment during development:

.venv/bin/python -m vyank.main

🖥️ GUI Workflow

General Tab

Use the General tab for one or more normal YouTube video URLs.

1. Paste a YouTube URL into the input field.
2. For multiple videos, separate URLs with commas.
3. Choose the output directory.
4. Select the download mode:
   • Video downloads the highest available MP4 video stream and merges audio with FFmpeg.
   • Audio downloads audio only.
   • Video and Audio is shown in the GUI as a shared mode option, but current download handling is focused on video or audio modes.
5. Click Download.

Playlist Tab

Use the Playlist tab for a YouTube playlist URL.

1. Paste the playlist URL.
2. Choose the output directory.
3. Select video or audio mode.
4. Click Download.

Channel Tab

Use the Channel tab for a YouTube channel URL.

1. Paste the channel URL.
2. Choose the output directory.
3. Click Download.

📁 Default Download Folder

By default, downloads go to:

Linux/macOS:

~/Downloads

Windows:

%USERPROFILE%\Downloads

You can override this from the GUI by choosing another output directory.

📦 Project Structure

vyank/
├── CHANGELOG.md
├── LICENSE
├── MANIFEST.in
├── README.md
├── pyproject.toml
└── vyank/
    ├── main.py
    ├── application/
    │   ├── config.py
    │   └── core.py
    ├── basic_functions/
    │   ├── os_funs.py
    │   └── text.py
    └── gui/
        ├── gui.py
        └── tab_base.py

🔧 Development Setup

Clone the repository:

git clone https://github.com/benevantmathew/vyank.git
cd vyank

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate

Install the package in editable mode:

pip install -e .

Install build tools when preparing a release:

pip install build twine

Run a quick import/compile check:

python -m compileall -q vyank
python -c "import vyank.main; print('vyank import ok')"

🧪 Build and PyPI Readiness

Build source and wheel distributions locally:

python -m build

Check the generated distributions:

twine check dist/*

Install the locally built wheel for testing:

pip install --force-reinstall dist/vyank-0.1.0-py3-none-any.whl

Run the installed command:

vyank

Do not publish until you are ready. When ready, publish with:

twine upload dist/*

📌 Package Metadata

• Package name: vyank
• Current version: 0.1.0
• Python requirement: >=3.10
• License: MIT
• Author: Benevant Mathew
• Repository: https://github.com/benevantmathew/vyank
• Main GUI entry point: vyank.main:main
• Console script: vyank

🧩 Runtime Dependencies

Python packages:

• pytubefix

System packages:

• ffmpeg
• tkinter / Tk support for your Python installation

On some Linux distributions, Tkinter is packaged separately. If the GUI fails with a Tkinter import error, install the Tk package for your Python version.

Debian/Ubuntu example:

sudo apt install python3-tk

📝 Changelog

See CHANGELOG.md for release notes.

📄 License

This project is licensed under the MIT License. See LICENSE for details.