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

Initial commit: Add DEVELOPMENT_PLAN.md

Browse Source
This commit is contained in:
Ramforth
2025-10-31 23:11:45 +01:00
commit bff6ea683a
1 changed files with 87 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
DEVELOPMENT_PLAN.md Normal file
View File

@@ -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").