From bff6ea683a6a984d5c9d0fc98e78db8384116dd8 Mon Sep 17 00:00:00 2001 From: Ramforth Date: Fri, 31 Oct 2025 23:11:45 +0100 Subject: [PATCH] Initial commit: Add DEVELOPMENT_PLAN.md --- DEVELOPMENT_PLAN.md | 87 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 DEVELOPMENT_PLAN.md diff --git a/DEVELOPMENT_PLAN.md b/DEVELOPMENT_PLAN.md new file mode 100644 index 0000000..7250148 --- /dev/null +++ b/DEVELOPMENT_PLAN.md @@ -0,0 +1,87 @@ +# 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. + +## 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). +* **`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, possibly by appending `_DR_compatible` or similar to the original filename, while retaining the new extension. + +### 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. + +## 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").