From 2846471d503779e662367c33691c92932bb1d7d2 Mon Sep 17 00:00:00 2001 From: Ramforth Date: Sat, 1 Nov 2025 16:15:40 +0100 Subject: [PATCH] Docs: Update all documentation to reflect current project state and future priorities --- DEVELOPMENT_PLAN.md | 103 +++++++++++--------------------------------- USAGE.md | 21 ++++++--- 2 files changed, 39 insertions(+), 85 deletions(-) diff --git a/DEVELOPMENT_PLAN.md b/DEVELOPMENT_PLAN.md index 1ffbebd..57d724f 100644 --- a/DEVELOPMENT_PLAN.md +++ b/DEVELOPMENT_PLAN.md @@ -5,19 +5,19 @@ Create a standalone executable application (using Python) to convert video files ## 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. +* **`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. -* **`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`). +* **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. @@ -70,94 +70,39 @@ Based on the "DaVinci Resolve 18 Supported Codec List.pdf" and web search result * 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 +## 4. Development Steps (Completed) -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. -8. **Packaging and Bundling:** (Completed) 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. -## 9. Current Status +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, and the default quality profiles have been refined based on user feedback. +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. -## 10. Future Development Priorities +## 6. Future Development Priorities Based on user feedback and project goals, the next development priorities are: -1. **`yt-dlp` Integration:** +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:** Integrate `yt-dlp` (a Python library) to handle video downloading. The script would prompt for a URL, download the video, and then proceed with the existing conversion process. + * **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):** - * **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:** Add a new `argparse` argument (e.g., `--quality [low|medium|high|archive]`) that maps to specific `dnxhd` profiles. This will give users more control over the size/quality trade-off. +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. -## 11. Other Future Considerations +## 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. - -## 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. - - diff --git a/USAGE.md b/USAGE.md index b2e222e..1066170 100644 --- a/USAGE.md +++ b/USAGE.md @@ -38,17 +38,25 @@ Once the setup is complete, you can run the converter script or the packaged exe ### Running the Python Script ```bash -python -m src.main [path_to_your_input_video_file] [-o ] +python main.py [path_to_your_input_video_file] [-u ] [-q ] [-o ] ``` * Replace `[path_to_your_input_video_file]` with the absolute or relative path to the video file you want to convert. This argument is now optional. -* Replace `` with the desired directory for the converted file. If omitted, the converted file will be saved in the same directory as the input file. +* Use `-u ` to provide a URL for a video to download and convert. If both a file path and a URL are provided, the URL will be prioritized. +* Use `-q ` to select the output video quality. Available choices are `low`, `medium` (default), `high`, and `archive`. This controls the DNxHD/HR profile used for conversion, impacting file size and visual fidelity. +* Replace `` with the desired directory for the converted file. If omitted, the converted file will be saved in the same directory as the input file (or the downloaded file). **Example (Interactive Input):** ```bash -python -m src.main -# Script will then prompt: Please enter the path to the input video file: +python main.py +# Script will then prompt: Please enter the path to the input video file or a URL: +``` + +**Example (Downloading and Converting from URL):** + +```bash +python main.py -u "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q high -o /home/user/ConvertedVideos ``` ### Running the Packaged Executable @@ -61,14 +69,15 @@ After building the executable (see `DEVELOPMENT_PLAN.md` for details on packagin ``` 2. **Run the executable:** ```bash - ./video-converter [path_to_your_input_video_file] [-o ] + ./video-converter [path_to_your_input_video_file] [-u ] [-q ] [-o ] ``` The usage is identical to the Python script, but you execute the binary directly. **Example:** ```bash - ./video-converter /home/user/Videos/my_original_video.mp4 -o /home/user/ConvertedVideos + ./video-converter /home/user/Videos/my_original_video.mp4 -q low -o /home/user/ConvertedVideos + ./video-converter -u "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q archive ``` ## 4. What it Does