ramforth/video-converter
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity
Files
2846471d503779e662367c33691c92932bb1d7d2
video-converter/DEVELOPMENT_PLAN.md

10 KiB
Raw Blame History

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