FFmpeg CLI Tool

A comprehensive, production-ready Command Line Interface for FFmpeg operations built with Python. This tool provides a modern, user-friendly interface for video and audio processing tasks.

Features

Video Operations

• Format Conversion: Convert between MP4, MKV, AVI, WebM, MOV, and more
• Resolution Change: Resize videos to 4K, 1080p, 720p, or custom resolutions
• Compression: Reduce file size using CRF quality settings
• Trimming: Cut videos by specifying start time and duration
• GIF Creation: Convert videos to animated GIFs with customizable FPS
• And More: Crop, rotate, speed adjustment, frame extraction

Audio Operations

• Format Conversion: Convert between MP3, WAV, FLAC, AAC, M4A, OGG
• Audio Extraction: Extract audio from video files
• Volume Adjustment: Increase or decrease audio volume
• Normalization: Normalize audio levels using EBU R128 standard
• Audio Removal: Create videos without audio tracks
• Bitrate Control: Adjust audio quality and file size

User Experience Features

• Real-time Progress Tracking: Visual progress bars with ETA
• Smart Input Validation: Intelligent file path and parameter validation
• Automatic Defaults: Smart default values for output paths
• Graceful Cancellation: Ctrl+C support with cleanup
• Cross-Platform: Works on Windows, Linux, and macOS
• Session Logging: All operations logged to session.log

Requirements

• Python 3.8 or higher
• FFmpeg installed and accessible in system PATH

Installation

1. Install FFmpeg

Windows:

1. Download FFmpeg from ffmpeg.org/download.html
2. Extract the archive
3. Add the bin folder to your system PATH
4. Restart your terminal

macOS:

brew install ffmpeg

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install ffmpeg

Linux (Fedora):

sudo dnf install ffmpeg

2. Install Python Dependencies

cd ffmpeg_cli_tool
pip install -r requirements.txt

Usage

Run the application:

python main.py

Navigation

• Use numeric keys to select menu options
• Press B to go back to the previous menu
• Press 0 to exit the application
• Press Ctrl+C to cancel any ongoing operation
• Press Enter to accept default values

Example Workflow

1. Start the application
2. Select "Video Operations" from the main menu
3. Choose "Convert Format"
4. Enter the path to your video file
5. Select the desired output format
6. Confirm the operation
7. Watch the real-time progress
8. Find your converted file in the output directory

Project Structure

ffmpeg_cli_tool/
├── main.py                 # Application entry point
├── requirements.txt        # Python dependencies
├── README.md              # This file
├── core/                  # Core functionality
│   ├── __init__.py
│   ├── config.py          # Configuration singleton
│   ├── command_builder.py # FFmpeg command builder (Builder pattern)
│   ├── validator.py       # Input validation
│   ├── ffmpeg_engine.py   # FFmpeg execution engine
│   └── ui_manager.py      # User interface manager
├── modules/               # Operation modules
│   ├── __init__.py
│   ├── factory.py         # Module factory (Factory pattern)
│   ├── video.py           # Video operations
│   └── audio.py           # Audio operations
└── utils/                 # Utility functions

Architecture

Design Patterns

1. Singleton Pattern: Used in Config class for centralized configuration
2. Builder Pattern: FFmpegCommandBuilder for constructing complex FFmpeg commands
3. Factory Pattern: ModuleFactory for dynamic module loading

Key Components

• Config: Centralized configuration management
• Validator: Comprehensive input validation (paths, formats, parameters)
• CommandBuilder: Fluent interface for building FFmpeg commands
• FFmpegEngine: Subprocess management with progress tracking
• UIManager: Rich-based UI components (menus, prompts, panels)

Advanced Features

Command Builder

The FFmpegCommandBuilder class provides a fluent interface for constructing FFmpeg commands:

command = (builder
    .set_input(input_file)
    .set_output(output_file)
    .set_video_codec("libx264")
    .set_crf(23)
    .add_filter("scale=1920x1080")
    .build())

Progress Tracking

The tool parses FFmpeg's output in real-time to display:

• Percentage completed
• Time elapsed
• Estimated time remaining
• Processing speed

Error Handling

All operations include:

• Try-catch blocks around subprocess calls
• User-friendly error messages
• Automatic cleanup of partial files on failure
• Session logging for debugging

Configuration

The Config singleton stores default settings:

• Default output directory
• Preferred video codec (default: libx264)
• Preferred audio codec (default: aac)
• Default CRF value (default: 23)
• Logging preferences

Extending the Tool

Adding New Operations

1. Add a method to the appropriate module (e.g., video.py)
2. Update the get_operations() method to include the new operation
3. Follow the existing pattern for input validation and command building

Adding New Categories

1. Create a new module file (e.g., subtitle.py)
2. Implement the required methods
3. Update ModuleFactory to include the new category
4. Add the category to get_available_categories()

Logging

All operations are logged to session.log in the current directory:

• Timestamp of each operation
• Full FFmpeg command executed
• Error messages if operations fail

Troubleshooting

FFmpeg Not Found

Ensure FFmpeg is installed and added to your system PATH. Run ffmpeg -version in your terminal to verify.

Permission Errors

Ensure you have write permissions in the output directory.

File Not Found

Use absolute paths or ensure your current working directory is correct.

Operation Cancelled

If you cancel with Ctrl+C, any partial output files are automatically cleaned up.

License

This project is provided as-is for educational and personal use.

Contributing

To contribute:

1. Follow PEP 8 style guidelines
2. Add type hints to all functions
3. Include docstrings for classes and methods
4. Test on multiple platforms
5. Update documentation

Support

For issues or questions:

1. Check the session.log file for detailed error messages
2. Verify FFmpeg installation
3. Ensure file paths are correct and accessible
4. Review FFmpeg documentation for specific codec/filter questions