TranscodePy

TranscodePy is a Python-based media transcoding tool that recursively scans directories for media files, displays metadata, and optionally transcodes files exceeding a configurable size threshold. It leverages FFmpeg for transcoding operations and follows clean architecture principles.

Features

• Recursive Directory Scanning: Finds media files in specified directories.
• Metadata Extraction: Retrieves file size, format, and other details.
• Configurable Transcoding: Converts media files to H.264/AAC in MKV format.
• Dry-Run Mode: Simulates the transcoding process without making changes.
• Clean Code Architecture: Designed for maintainability and extensibility.

Requirements

• Python 3.8+
• FFmpeg installed and available in your PATH

Installation

1. Clone the repository:

   git clone https://github.com/stephenjacobsio/transcode-py.git  \
   cd transcode-py

2. Install dependencies:

   pip install -r requirements.txt

Usage

Run the tool using the CLI:

python src/main.py <path> [options]

Arguments

Argument	Description
<path>	Path to the file or directory to scan/transcode.

Options

Option	Description
-t, --threads	Number of CPU threads for FFmpeg (default: 2).
-y, --overwrite	Overwrite output files if they already exist.
--dry-run	Simulate transcoding without making changes.
--size-threshold	Minimum file size (in GB) to consider for transcoding.

Example

To scan a directory and transcode files larger than 6GB:

python src/main.py /path/to/media --threads 4 --size-threshold 6.0

To perform a dry run:

python src/main.py /path/to/media --dry-run

Testing

Run unit tests with:

python -m unittest discover -s tests

Project Structure

transcode-py/
├── src/
│   ├── cli.py                # Command-line interface
│   ├── config/
│   │   ├── __init__.py       # Config initialization
│   │   └── settings.py       # Configurations and constants
│   ├── core/
│   │   ├── __init__.py       # Core package initialization
│   │   ├── media_file.py     # MediaFile dataclass
│   │   ├── media_scanner.py  # Media scanning logic
│   │   └── transcoder.py     # Transcoding logic
│   ├── interfaces/
│   │   ├── __init__.py       # Interfaces initialization
│   │   ├── i_media_scanner.py # Media scanner interface
│   │   └── i_transcoder.py   # Transcoder interface
│   └── main.py               # Main entry point
├── tests/
│   ├── test_cli.py           # CLI unit tests
│   ├── test_media_file.py    # MediaFile unit tests
│   ├── test_media_scanner.py # MediaScanner unit tests
│   └── test_transcoder.py    # Transcoder unit tests
├── requirements.txt          # Python dependencies
└── README.md                 # Project documentation

Contributing

Contributions are welcome! Please fork the repository, make changes, and submit a pull request.

License

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

Acknowledgments

• FFmpeg for the powerful transcoding capabilities.
• Python community for the amazing libraries and support.

---

_{Built with ❤️ by Stephen Jacobs}