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`)

Analyze Input: Use ffprobe to get detailed information about the input video (video codec, audio codec, resolution, aspect ratio, frame rate, bit depth).
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.
Construct ffmpeg Command: Build the ffmpeg command dynamically.
- Example for DNxHR/DNxHD with PCM audio:
```
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

Initial Script Setup: Create main.py with basic argparse for input/output paths.
Directory Creation: Ensure output directory exists.
ffprobe Integration: Implement a function to call ffprobe and parse its JSON output to get video/audio stream details.
ffmpeg Command Construction: Develop logic to build the ffmpeg command based on ffprobe output and desired Davinci Resolve compatibility.
ffmpeg Execution: Use subprocess.run() to execute the ffmpeg command, capturing stdout/stderr for logging.
Error Handling: Add try-except blocks for file operations, subprocess calls, and ffprobe parsing.
Basic Testing: Test with a few sample video files (e.g., H.264/AAC MP4) to ensure conversion to DNxHR/PCM MOV works.
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).
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.

11 KiB Raw Blame History