ramforth/video-converter
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Complete initial project setup and core functionality

Browse Source
This commit is contained in:
Ramforth
2025-11-01 11:22:59 +01:00
parent f06797d437
commit 0fbc261e1b
15 changed files with 418 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
DEVELOPMENT_PLAN.md
View File

@@ -1,12 +1,15 @@
# Video Converter Script Development Plan
## 1. Project Goal
Create a Python script to convert video files into formats highly compatible with Davinci Resolve, ensuring optimal aspect ratio, video quality, and audio fidelity. The script should be user-friendly, prompting for input and output locations, and leveraging `ffmpeg` for robust conversion.
Create a standalone executable application (using Python) to convert video files into formats highly compatible with Davinci Resolve, ensuring optimal aspect ratio, video quality, and audio fidelity. The application should be user-friendly, accepting input file paths via CLI arguments, prompting for output locations (if not specified), and leveraging `ffmpeg` for robust conversion. The goal is a single executable that requires no external dependencies (like Python or `ffmpeg` installations) from the end-user.
## 2. Key Tools and Technologies
* **Python:** For scripting the user interface, logic, and orchestrating `ffmpeg` commands.
* **`ffmpeg`:** The primary tool for video and audio conversion. It will be called via Python's `subprocess` module.
* **`ffprobe` (part of `ffmpeg` suite):** For analyzing input video file properties (codecs, resolution, aspect ratio, audio streams).
* **`ffmpeg-python` library:** A robust Python binding for FFmpeg to simplify command construction and execution.
* **`ffmpeg` & `ffprobe`:** The primary tools for video and audio conversion and analysis. These will be bundled with the final application.
* **PyInstaller (or similar):** For packaging the Python script and bundled `ffmpeg`/`ffprobe` into a standalone executable.
**Inspiration Repositories:** We will review `xavier150/convert-video-for-Resolve` and `tkmxqrdxddd/davinci-video-converter` for insights into Davinci Resolve specific conversion strategies and `ffmpeg` command construction.
* **`yt-dlp` (Optional, for future expansion):** While the current scope is local files, `yt-dlp` could be integrated later for direct downloading and converting from online sources.
## 3. Core Functionality and Requirements
@@ -14,7 +17,7 @@ Create a Python script to convert video files into formats highly compatible wit
### 3.1. User Interaction
* **Input File Selection:** The script will prompt the user to provide the absolute path to the input video file.
* **Output Directory Selection:** The script will ask the user for a desired output directory. If no directory is provided, it will default to the script's current working directory.
* **Output File Naming:** Converted files will be named clearly, possibly by appending `_DR_compatible` or similar to the original filename, while retaining the new extension.
* **Output File Naming:** Converted files will be named clearly. If the output directory is the same as the input file's directory, the output filename will be prefixed with `recoded_` (e.g., `recoded_original_file.mov`). Otherwise, a clear naming convention will be applied (e.g., append `_DR_compatible`).
### 3.2. Shell Environment (Re-evaluation)
* The initial request mentioned confirming the shell type. However, `ffmpeg` commands executed via Python's `subprocess` module are generally shell-agnostic. The Python script itself will handle the execution. Therefore, explicit shell detection is likely unnecessary unless specific shell-dependent environment variables or configurations for `ffmpeg` or `yt-dlp` (if integrated later) become an issue. This point will be kept in mind for troubleshooting.
@@ -76,12 +79,60 @@ Based on the "DaVinci Resolve 18 Supported Codec List.pdf" and web search result
5. **`ffmpeg` Execution:** Use `subprocess.run()` to execute the `ffmpeg` command, capturing stdout/stderr for logging.
6. **Error Handling:** Add `try-except` blocks for file operations, `subprocess` calls, and `ffprobe` parsing.
7. **Basic Testing:** Test with a few sample video files (e.g., H.264/AAC MP4) to ensure conversion to DNxHR/PCM MOV works.
8. **Packaging and Bundling:** Use PyInstaller (or similar) to create standalone executables for target operating systems. This step will involve bundling the Python script, its dependencies, and the `ffmpeg`/`ffprobe` binaries. Note that packaging will be OS-specific (e.g., a Linux executable must be built on Linux).
9. **Error Handling for Bundled Tools:** Implement checks to ensure bundled `ffmpeg`/`ffprobe` are accessible and provide clear error messages if not.
## 6. Directory and File Structure
To ensure a modular, maintainable, and scalable project, the following directory and file structure is proposed:
```
/home/joe/Cloud9/Documents/Obisdian/projects/Video Converter/
├── .sources_library/
│ ├── davinci_resolve_18_supported_codec_list.pdf
│ ├── davinci_resolve_20_2_2_info.md
│ ├── davinci_resolve_20_2_new_features.pdf
│ └── yt-dlp_readme.md
├── src/
│ ├── __init__.py # Makes 'src' a Python package
│ ├── main.py # Main CLI entry point, argument parsing
│ ├── converter.py # Core video conversion logic, ffmpeg calls
│ ├── utils.py # Helper functions (ffprobe parsing, path handling, logging)
│ └── config.py # Configuration settings (codec profiles, defaults)
├── tests/
│ ├── __init__.py
│ ├── test_converter.py # Unit tests for converter.py
│ └── test_utils.py # Unit tests for utils.py
├── .gitignore
├── DEVELOPMENT_PLAN.md
├── README.md
├── requirements.txt # Python dependencies (e.g., ffmpeg-python)
└── build/ # Output directory for packaged executables (PyInstaller)
```
**Explanation of Structure:**
* **`.sources_library/`**: Contains all reference documents and downloaded resources.
* **`src/`**: This directory will contain all the Python source code for the application.
* `__init__.py`: Marks `src` as a Python package.
* `main.py`: The primary entry point for the CLI. It will handle argument parsing (`argparse`) and orchestrate calls to `converter.py` and `utils.py`.
* `converter.py`: This module will encapsulate the core logic for video conversion. It will contain functions that take input file paths, desired output settings, and construct/execute `ffmpeg` commands using `ffmpeg-python`.
* `utils.py`: This module will house helper functions, such as:
* Parsing `ffprobe` output.
* Handling file path manipulations (e.g., adding `recoded_` prefix, resolving output paths).
* Basic file existence checks.
* Logging setup.
* `config.py`: For storing configurable parameters like default codec profiles, output formats, or any other settings that might be user-adjustable or need to be easily changed.
* **`tests/`**: This directory will contain unit tests for the `src` modules.
* `__init__.py`: Marks `tests` as a Python package.
* `test_converter.py`: Tests for the conversion logic in `converter.py`.
* `test_utils.py`: Tests for utility functions in `utils.py`.
* **`.gitignore`**: Standard Git ignore file.
* **`DEVELOPMENT_PLAN.md`**: This detailed plan document.
* **`README.md`**: Project overview.
* **`requirements.txt`**: Will list all Python dependencies (e.g., `ffmpeg-python`). This is crucial for managing the project's environment.
* **`build/`**: This directory will be created later by PyInstaller to store the packaged executables.
This structure promotes modularity, making the codebase easier to understand, test, and maintain. It separates concerns (CLI handling, core logic, utilities, configuration) into distinct modules.
## 5. Future Considerations / Enhancements
* **GUI:** Develop a simple graphical user interface for easier interaction.
* **Batch Processing:** Allow conversion of multiple files at once.
* **Configuration File:** Enable users to save preferred codec/profile settings.
* **Progress Bar:** Implement a progress indicator for long conversions.
* **`yt-dlp` Integration:** Add an option to download videos directly from URLs before converting.
* **Detailed Logging:** Enhance logging for debugging and user feedback.
* **Pre-defined Profiles:** Offer specific profiles for different Davinci Resolve versions or common use cases (e.g., "YouTube Upload," "Archival Quality").