Vid Downloader CLI — A Cross-Platform Video Downloader

Overview

Vid Downloader CLI (VDL) is a cross-platform command-line application designed to simplify downloading videos and audio directly from the terminal.

Built with Python and powered by yt-dlp, the application supports interactive and non-interactive workflows, batch downloads, video quality selection, MP3 extraction, partial downloads, and safe resume functionality.

VDL supports Windows, macOS, and Linux, providing a flexible solution for managing media downloads through a simple and configurable command-line interface.

The Idea

Downloading videos through command-line tools often requires remembering complex commands, configuring output directories, and handling interrupted downloads manually.

I wanted to create a tool that simplifies these tasks while preserving the flexibility of terminal-based workflows.

Vid Downloader CLI was developed as a convenient interface around yt-dlp, allowing users to download media through interactive prompts or direct commands.

The application also supports persistent configuration, making repetitive downloading tasks easier to manage.

Key Features

1. Interactive Command-Line Interface

VDL provides an interactive mode that guides users through the downloading process.

Users can start the application using:

vdl

The interactive workflow supports:

On first launch, users can select a default download directory, which is preserved across application reinstallations.

2. Direct Video Downloads

VDL supports downloading individual videos without interactive prompts.

For example, downloading a video from YouTube:

vdl download "https://www.youtube.com/watch?v=jfKfPfyJRdk"

This command allows users to download a video directly from the terminal.

The non-interactive workflow is particularly useful for scripting, automation, and repeated download operations.

3. Batch Video Downloads

VDL supports downloading multiple videos using a configuration file named download.conf.

Users can define multiple YouTube URLs along with their preferred download settings.

Example configuration:

URLS=[
    "https://www.youtube.com/watch?v=jfKfPfyJRdk",
    "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
]

DOWNLOAD_DIR=
QUALITY=720

After creating the configuration file, users can execute:

vdl download

The application processes the configured URLs using the specified download preferences.

Users can also provide a custom configuration file:

vdl download --config ~/Downloads/download.conf

4. Video Quality Selection

VDL allows users to specify their preferred video quality.

For example, downloading a YouTube video at 720p:

vdl download "https://www.youtube.com/watch?v=jfKfPfyJRdk" --quality 720

If no quality is specified, the application uses the best available quality.

This feature provides flexibility when balancing video resolution, file size, and download requirements.

5. MP3 Audio Extraction

VDL supports downloading audio-only content and converting it into MP3 format.

Example:

vdl download "https://www.youtube.com/watch?v=jfKfPfyJRdk" --audio

The application produces MP3 audio at 192 kbps.

This feature is useful when users only need the audio portion of a supported video.

6. Partial Video Downloads

VDL allows users to download specific sections of a video by defining start and end timestamps.

For example, downloading a YouTube video segment between 00:10 and 00:30:

vdl download "https://www.youtube.com/watch?v=jfKfPfyJRdk" --start 00:10 --end 00:30

This functionality helps users retrieve selected portions of longer videos without downloading the entire content when the source and download engine support the operation.

7. Custom Download Directories

VDL allows users to specify where downloaded media files should be saved.

For example:

vdl download "https://www.youtube.com/watch?v=jfKfPfyJRdk" --folder ~/Downloads/Videos

Users can also configure a default download directory to avoid repeatedly specifying the same location.

8. Safe Resume and File Handling

Interrupted downloads can occur due to network instability or unexpected process termination.

VDL supports resumable downloads through .part files when supported by the source and underlying download engine.

The application also handles duplicate filenames automatically.

For example:

video.mp4
video (1).mp4
video (2).mp4

Additionally, cross-process locking helps coordinate concurrent download operations without creating extra lock files inside the output directory.

9. Persistent Configuration

VDL provides configuration management for reusable download preferences.

Users can initialize or reconfigure the application using:

vdl init

To display the selected configuration file:

vdl config-path

The configuration system supports:

10. Cross-Platform Support

VDL is designed to work across Windows, macOS, and Linux.

The application uses uv for Python application installation and environment management.

Installation:

git clone https://github.com/firhanhardiansyah/vid-downloader-cli.git
cd vid-downloader-cli
uv tool install .

After installation, users can launch the application using:

vdl

Alternatively:

vid-downloader

Technical Architecture

Vid Downloader CLI is built as a Python command-line application that integrates yt-dlp as its underlying media-downloading engine.

Command-Line Interface

The application provides two primary execution modes:

Both workflows provide access to the application's download capabilities.

Download Engine

The application uses yt-dlp to handle supported video and audio downloads.

VDL extends this functionality through:

Configuration Management

Configuration files store reusable download preferences and collections of URLs.

This reduces repeated command entry and enables consistent download behavior.

File Management and Process Coordination

VDL includes mechanisms for handling incomplete downloads, duplicate filenames, and concurrent processes.

These features improve the reliability of download operations and help protect existing output files.

Dependency Management

The project uses uv for application installation and Python dependency management.

GNU Make shortcuts are also available for common development operations, including installation, reinstallation, testing, and dependency synchronization.

Engineering Challenges

Designing Flexible CLI Workflows

One challenge was supporting both beginner-friendly interactive workflows and direct commands suitable for experienced terminal users.

VDL addresses this by providing separate execution modes within one application.

Handling Interrupted Downloads

Network interruptions can leave downloads incomplete.

The application supports .part files and resumable download behavior to reduce unnecessary repeated transfers when supported.

Preventing Filename Conflicts

Downloading multiple files with identical names can create filename collisions.

VDL automatically generates alternative filenames to preserve existing files.

Managing Concurrent Processes

Running multiple download processes can introduce conflicts when accessing shared resources.

Cross-process locking helps coordinate operations without placing additional lock files in download directories.

Supporting Different Operating Systems

Windows, macOS, and Linux have different filesystem conventions and shell environments.

VDL maintains a consistent command interface and installation process across these platforms.

What I Learned

Building Vid Downloader CLI provided practical experience in developing command-line applications with Python.

The project involved command design, configuration management, media download orchestration, filesystem operations, and process coordination.

It reinforced the importance of designing software that balances simplicity and flexibility.

The project also highlighted the value of defensive file handling and recovery mechanisms when building tools that interact with network resources and local files.

Future Improvements

Potential improvements include:

Conclusion

Vid Downloader CLI demonstrates how Python can be used to build practical, cross-platform developer tools.

By combining yt-dlp with interactive workflows, batch downloads, quality selection, partial downloads, and safe file handling, the application simplifies media downloading directly from the terminal.

The project reflects a focus on workflow automation, reliable command-line utilities, and cross-platform software engineering.