ramforth/video-converter
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Docs: Update all documentation to reflect current project state and future priorities

Browse Source
This commit is contained in:
Ramforth
2025-11-01 16:15:40 +01:00
parent be101e0869
commit 2846471d50
2 changed files with 39 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
DEVELOPMENT_PLAN.md
View File

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

21
USAGE.md
View File

@@ -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 <path_to_output_directory>]
python main.py [path_to_your_input_video_file] [-u <video_url>] [-q <quality_profile>] [-o <path_to_output_directory>]
```
* 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 `<path_to_output_directory>` 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 <video_url>` 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 <quality_profile>` 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 `<path_to_output_directory>` 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 <path_to_output_directory>]
./video-converter [path_to_your_input_video_file] [-u <video_url>] [-q <quality_profile>] [-o <path_to_output_directory>]
```
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