video-converter/DEVELOPMENT_PLAN.md

# 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` & `ffprobe`:** The primary tools for video and audio conversion and analysis. These will be bundled with the final application, and are called directly via Python's `subprocess` module.
*   **`yt-dlp`:** A Python library used for downloading videos from various online platforms.
*   **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.

## 3. Core Functionality and Requirements

### 3.1. User Interaction
*   **Input Source Selection:** The script accepts either a local file path or a URL via command-line arguments (`--url` for URL, positional argument for file path). If neither is provided, the user is interactively prompted to enter a file path or URL.
*   **Output Directory Selection:** The script asks the user for a desired output directory via the `-o` argument. If no directory is provided, it defaults to the input file's (or downloaded file's) directory.
*   **Output File Naming:** Converted files are named clearly. If the output directory is the same as the input file's directory, the output filename is prefixed with `recoded_` (e.g., `recoded_original_file.mov`). Otherwise, a clear naming convention is applied (e.g., append `_DR_compatible`). A fail-safe is implemented to generate unique filenames if the target file already exists.
*   **Quality Profile Selection:** Users can select the output video quality profile via the `-q` argument (`low`, `medium`, `high`, `archive`), which maps to specific DNxHD/HR profiles based on resolution.

### 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 (Completed)

1.  **Initial Script Setup:** Created `main.py` with `argparse` for CLI arguments, including input file/URL, output directory, and quality profile selection.
2.  **Directory Creation:** Ensured output directory exists.
3.  **`ffprobe` Integration:** Implemented functions in `utils.py` to call `ffprobe` via `subprocess` and parse its JSON output to get video/audio stream details.
4.  **`ffmpeg` Command Construction:** Developed logic in `converter.py` to build the `ffmpeg` command as a list of strings based on `ffprobe` output, desired Davinci Resolve compatibility, and selected quality profile.
5.  **`ffmpeg` Execution:** Used `subprocess.run()` in `converter.py` to execute the `ffmpeg` command, capturing stdout/stderr for logging.
6.  **Error Handling:** Added robust `try-except` blocks for file operations, `subprocess` calls, and `ffprobe` parsing. Implemented a fail-safe for existing output filenames by generating unique names.
7.  **Basic Testing:** Conducted manual tests with sample video files to ensure conversion to DNxHD/PCM MOV works, including audio, and refined quality profiles.
8.  **Packaging and Bundling:** 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.
## 5. 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, including a fail-safe for existing output filenames, and the default quality profiles have been refined based on user feedback.

## 6. Future Development Priorities

Based on user feedback and project goals, the next development priorities are:

1.  **`yt-dlp` Integration:** (Completed)
    *   **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:** Integrated `yt-dlp` to handle video downloading. The script now accepts a URL via the `--url` argument or interactively, downloads the video to a temporary location (or specified output directory), and then proceeds with the existing conversion process.

2.  **Quality Profile Picker (Command-Line Option):** (Completed)
    *   **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:** Added a new `argparse` argument (`--quality`) that maps to specific `dnxhd` profiles (`low`, `medium`, `high`, `archive`) based on resolution, giving users 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.

## 7. 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.