164 lines
13 KiB
Markdown
164 lines
13 KiB
Markdown
# Video Converter Script Development Plan
|
|
|
|
## 1. Project Goal
|
|
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-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
|
|
|
|
### 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. 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.
|
|
|
|
### 3.3. Davinci Resolve Compatibility - Codec and Format Selection
|
|
|
|
Based on the "DaVinci Resolve 18 Supported Codec List.pdf" and web search results, the following are recommended for optimal compatibility and editing performance in Davinci Resolve, especially for intermediate files:
|
|
|
|
#### Video Codecs (for Intermediate Editing)
|
|
* **DNxHR / DNxHD:**
|
|
* **Container:** QuickTime (`.mov`)
|
|
* **Description:** Excellent intraframe codecs for Windows and Linux. DNxHR is for resolutions above 1080p, while DNxHD is for up to 1080p. They offer good performance and preserve quality.
|
|
* **Profiles:** HQ (High Quality) or HQX (Higher Quality, larger file size) are preferred.
|
|
* **FFmpeg Example:** `-c:v dnxhr -profile:v HQ` (or `HQX`)
|
|
* **Apple ProRes:**
|
|
* **Container:** QuickTime (`.mov`)
|
|
* **Description:** High-quality, widely used, especially on macOS. FFmpeg can encode/decode on other OS. Davinci Resolve supports ProRes with alpha channels.
|
|
* **FFmpeg Example:** `-c:v prores_ks -profile:v 3` (for ProRes HQ, profile numbers vary)
|
|
* **GoPro CineForm:**
|
|
* **Container:** QuickTime (`.mov`)
|
|
* **Description:** Another high-quality intermediate codec supported by Davinci Resolve.
|
|
|
|
#### Audio Codecs
|
|
* **PCM (Pulse Code Modulation):**
|
|
* **Description:** Crucial for Linux users, as Davinci Resolve on Linux often has compatibility issues with AAC audio. PCM is uncompressed and widely compatible.
|
|
* **FFmpeg Example:** `-c:a pcm_s16le` (16-bit signed little-endian PCM)
|
|
* **FLAC:**
|
|
* **Description:** A lossless audio codec, suitable as an alternative to PCM or for extracting audio separately if needed.
|
|
* **FFmpeg Example:** `-c:a flac`
|
|
|
|
#### Container Format
|
|
* **QuickTime (`.mov`):** Generally recommended for intermediate files due to better stability and metadata handling with Davinci Resolve.
|
|
|
|
#### Quality and Settings
|
|
* **Aspect Ratio:** The script should preserve the original aspect ratio of the input video. `ffmpeg` handles this by default unless specific scaling filters are applied.
|
|
* **Resolution:** Maintain original resolution or convert to a Davinci Resolve-friendly resolution if necessary (e.g., for DNxHD/HR profiles).
|
|
* **Bit Depth:** Aim for 10-bit color depth (e.g., `yuv422p10le` pixel format) if the source video supports it and Davinci Resolve Studio is used, to prevent banding and ensure higher quality.
|
|
* **Bitrate:** For intermediate files, high bitrates are expected and desired to preserve quality.
|
|
|
|
### 3.4. Conversion Logic (using `ffmpeg`)
|
|
1. **Analyze Input:** Use `ffprobe` to get detailed information about the input video (video codec, audio codec, resolution, aspect ratio, frame rate, bit depth).
|
|
2. **Determine Output Parameters:** Based on the input analysis and user preferences (if any are added later), select the most appropriate Davinci Resolve compatible video and audio codecs, profiles, and pixel formats.
|
|
3. **Construct `ffmpeg` Command:** Build the `ffmpeg` command dynamically.
|
|
* **Example for DNxHR/DNxHD with PCM audio:**
|
|
```bash
|
|
ffmpeg -i "input.mp4" -c:v dnxhr -profile:v HQ -c:a pcm_s16le "output_DR_compatible.mov"
|
|
```
|
|
* **Considerations:**
|
|
* Handling different input audio codecs (e.g., converting AAC to PCM).
|
|
* Mapping all video and audio streams (`-map 0`).
|
|
* Potentially adding `-vf scale=w:h:force_original_aspect_ratio=decrease,pad=w:h:(ow-iw)/2:(oh-ih)/2` for specific aspect ratio handling if cropping/padding is desired, but generally, preserving original is default.
|
|
|
|
## 4. Development Steps
|
|
|
|
1. **Initial Script Setup:** Create `main.py` with basic `argparse` for input/output paths.
|
|
2. **Directory Creation:** Ensure output directory exists.
|
|
3. **`ffprobe` Integration:** Implement a function to call `ffprobe` and parse its JSON output to get video/audio stream details.
|
|
4. **`ffmpeg` Command Construction:** Develop logic to build the `ffmpeg` command based on `ffprobe` output and desired Davinci Resolve compatibility.
|
|
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:** (Completed) Used PyInstaller to create a standalone executable, bundling `ffmpeg` and `ffprobe` binaries. This involved switching from `ffmpeg-python` to direct `subprocess` calls to resolve bundling issues. The executable is now functional.
|
|
## 9. Current Status
|
|
|
|
The core functionality of the Video Converter is complete. The script successfully converts video files to DaVinci Resolve compatible formats (DNxHD/HR video, PCM audio in .mov container) and is packaged as a standalone executable for Linux. Error handling has been strengthened, and the default quality profiles have been refined based on user feedback.
|
|
|
|
## 10. Future Development Priorities
|
|
|
|
Based on user feedback and project goals, the next development priorities are:
|
|
|
|
1. **`yt-dlp` Integration:**
|
|
* **Goal:** Allow users to directly download videos from supported online platforms (e.g., YouTube) and then convert them to DaVinci Resolve compatible formats in a single workflow.
|
|
* **Details:** Integrate `yt-dlp` (a Python library) to handle video downloading. The script would prompt for a URL, download the video, and then proceed with the existing conversion process.
|
|
|
|
2. **Quality Profile Picker (Command-Line Option):**
|
|
* **Goal:** Provide users with command-line options to select different quality/file size profiles for the output video (e.g., `--dnxhr_lb`, `--dnxhr_sq`, `--dnxhr_hq`, `--dnxhr_hqx`).
|
|
* **Details:** Add a new `argparse` argument (e.g., `--quality [low|medium|high|archive]`) that maps to specific `dnxhd` profiles. This will give users more control over the size/quality trade-off.
|
|
|
|
3. **Graphical User Interface (GUI):**
|
|
* **Goal:** Develop a user-friendly graphical interface for the application.
|
|
* **Details:** This would involve choosing a Python GUI framework (e.g., `tkinter`, `PyQt`, `Kivy`) and designing an interface that allows users to select input/output files, choose quality profiles, view conversion progress, and manage other settings visually. This would significantly enhance the user experience for non-CLI users.
|
|
|
|
## 11. Other Future Considerations
|
|
|
|
* **Batch Processing:** Allow conversion of multiple files at once.
|
|
* **Refine Error Handling/Logging:** Add more detailed logging to a file for easier debugging.
|
|
* **Configuration File:** Enable users to save preferred codec/profile settings.
|
|
* **Progress Bar:** Implement a progress indicator for long conversions.
|
|
|
|
## 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.
|
|
|
|
|