Video Music Remover

A powerful Python tool to remove background music from videos while preserving speech and other sounds using advanced machine learning models.

Overview

Video Music Remover is a command-line tool that uses the powerful demucs machine learning model to separate and remove music from videos while preserving speech, sound effects, and other audio elements. This is particularly useful for Muslim people and anyone who needs to remove music from videos.

The tool automatically processes all audio tracks in the input file, making it ideal for videos with multiple language tracks or commentary audio tracks.

Note: An internet connection is required the first time you use a model, as it needs to be downloaded. Once downloaded, the tool can be used completely offline.

Features

• Batch Processing: Process multiple videos in a directory with a single command
• Multiple ML Models: Choose from different machine learning models based on your needs
• Preserves Video Quality: Maintains the original video quality while only modifying the audio
• Multiple Audio Tracks Support: Automatically processes all audio tracks in the input video
• Simple CLI Interface: Easy-to-use command-line interface
• Logging Support: Optional logging for tracking processing progress
• Original File Management: Option to delete original files after processing

Supported Formats

Video Formats

• MP4 (.mp4)
• Matroska (.mkv)
• WebM (.webm)

Machine Learning Models

• demucs/htdemucs (default): First version of Hybrid Transformer Demucs
• demucs/htdemucs_ft: Fine-tuned version of htdemucs (4x slower but potentially better quality)
• demucs/mdx: Trained only on MusDB HQ, winning model on track A at the MDX challenge
• demucs/mdx_extra: Trained with extra training data, ranked 2nd on track B of the MDX challenge

System Requirements

• Python 3.10 or higher
• FFmpeg (required for audio/video processing)
• Sufficient disk space for temporary files during processing

Installation

Using pip

pip install video-music-remover

Using UV (recommended)

uv tool install video-music-remover

Usage

Basic Usage

To remove music from a single video:

video-music-remover remove-music input_video.mp4 output_directory/

To process all supported videos in a directory:

video-music-remover remove-music input_directory/ output_directory/

Advanced Options

Specify a different machine learning model:

video-music-remover remove-music input_video.mp4 output_directory/ --model ht_demucs_ft

Enable logging to a file:

video-music-remover remove-music input_video.mp4 output_directory/ --log processing.log

Delete original files after successful processing:

video-music-remover remove-music input_video.mp4 output_directory/ --delete-original

Health Check

Verify that all dependencies are correctly installed:

video-music-remover health-check

For detailed debugging information:

video-music-remover health-check --debug

Version Information

Display the installed version:

video-music-remover version

How It Works

The program processes videos through the following steps:

1. Audio Extraction: Extracts all audio tracks from the input video
   • if input is file, the new video file in the output directory will be replaced if it exists
   • if input is a directory, only supported files that don't exist in the output directory will be processed
2. Music Separation: Uses the selected demucs model to separate vocals from music in all extracted audio tracks.
   • Note: The first time a model is used, it will be downloaded automatically. Subsequent uses will be offline from the local cache.
3. Audio Processing: Preserves the vocal tracks and removes the music tracks
4. Video Reconstruction: Creates a new video with the original video track and the processed audio tracks while preserving other streams and metadata
5. Original File Handling: Optionally deletes original files when using --delete-original

The resulting video will have the same visual quality but with background music removed while preserving speech and other sounds.

Development Setup

Package Manager

This project uses UV as its package manager for development.

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/asaah18/video-music-remover.git
   cd video-music-remover

2. Create a virtual environment and install dependencies:

   uv venv
   uv sync

License

This project is licensed under the MIT License - see the LICENSE file for details.