feat: Implement GUI and standalone executable
This commit is contained in:
Ramforth
@@ -1,108 +1,36 @@
|
||||
# Video Converter Script Development Plan
|
||||
## Development Plan: Video Converter
|
||||
|
||||
## 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.
|
||||
This document outlines the development plan for the Video Converter project, aiming to create a standalone Python tool for converting video files into DaVinci Resolve compatible formats.
|
||||
|
||||
## 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.
|
||||
### Overall Goal
|
||||
Develop a user-friendly, standalone Python tool to convert video files into formats compatible with Davinci Resolve (Free edition on Linux) to improve editing workflows for content creators.
|
||||
|
||||
**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.
|
||||
### Completed Features
|
||||
|
||||
## 3. Core Functionality and Requirements
|
||||
* **Core Conversion Logic:** Implemented video conversion using `ffmpeg` with `dnxhd` codec and `pcm_s16le` audio, outputting to `.mov` container.
|
||||
* **Quality Profile Picker:** Added `--quality` argument (low, medium, high, archive) to control `dnxhd` profiles.
|
||||
* **Filename Fail-safe:** Implemented logic to append `_1`, `_2`, etc., to output filenames if a file with the same name already exists.
|
||||
* **`yt-dlp` Integration:** Added `--url` argument to download videos from YouTube (and other supported sites) using `yt-dlp` before conversion.
|
||||
* **PyInstaller Bundling:** Successfully bundled the application into a standalone executable for Linux.
|
||||
* **Robust Download Path Handling:** Ensured `yt-dlp` downloads directly to the user-specified output directory (or current working directory if not specified), resolving `os.path.exists()` issues within the PyInstaller environment.
|
||||
* **Basic Error Handling & Logging:** Suppressed verbose `yt-dlp` output and redirected `ffmpeg` output to `ffmpeg_output.log` for detailed error inspection.
|
||||
|
||||
### 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.
|
||||
### Current Priorities (Next Steps)
|
||||
|
||||
### 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.
|
||||
1. **Implement GUI:** Develop a graphical user interface for easier interaction, including file selection, quality profile choice, and URL input. (High Priority)
|
||||
2. **Implement Browser Cookies for YouTube Authorization:** Revisit and implement `--cookies-from-browser` functionality for `yt-dlp` to handle age-restricted or private YouTube videos. (Deferred, now higher priority)
|
||||
3. **Refine Error Handling/Logging:** Implement more user-friendly error messages, potentially displaying the last few lines of the log file directly in the console upon failure, and providing clear instructions to check the full log.
|
||||
|
||||
### 3.3. Davinci Resolve Compatibility - Codec and Format Selection
|
||||
### Future Considerations
|
||||
|
||||
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:
|
||||
* **Batch Processing:** Allow conversion of multiple files or URLs in a single run.
|
||||
* **Configuration File:** Implement a configuration file (e.g., YAML, JSON) for persistent settings.
|
||||
* **Progress Bar:** Integrate a progress bar for both download and conversion processes.
|
||||
* **Cross-Platform Compatibility:** Explore bundling for Windows and macOS. (Lowest priority)
|
||||
* **Advanced `ffmpeg` Options:** Expose more `ffmpeg` options (e.g., bitrate, resolution scaling) for advanced users.
|
||||
* **Metadata Preservation:** Option to preserve or transfer metadata from the original file.
|
||||
|
||||
#### 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.
|
||||
### Known Issues / Limitations
|
||||
|
||||
#### 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.
|
||||
* DaVinci Resolve Free on Linux has limitations with certain audio codecs (e.g., AAC) and 4K output/encoding (requires Studio version).
|
||||
* `ffmpeg-full` AUR package is required for `dnxhd` support on Arch-based systems.
|
||||
Reference in New Issue
Block a user