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

feat: Implement GUI and standalone executable

Browse Source
This commit is contained in:
Ramforth
2025-11-02 12:37:09 +01:00
parent 2846471d50
commit 9b0c557d9c
14 changed files with 605 additions and 492 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
USAGE.md
View File

@@ -1,96 +1,70 @@
# How to Use the Video Converter (Current State)
# How to Use the Video Converter
This document outlines the steps required to set up and run the Video Converter script in its current development state.
This document outlines the steps required to set up and run the Video Converter application.
## 1. Prerequisites
Before running the script, ensure you have the following installed on your **Arch Linux / CachyOS** system:
Before running the application, ensure you have the following installed on your **Arch Linux / CachyOS** system:
* **Python 3:** The script is written in Python 3.
* **`ffmpeg-full`:** A version of `ffmpeg` compiled with DNxHD/HR support.
* Install from AUR: `yay -S ffmpeg-full` (or your preferred AUR helper).
* **Note:** If you use OBS Studio, refer to the [README.md](README.md) for potential dependency workarounds.
* **`yt-dlp`**: A command-line program to download videos from YouTube and other sites.
* Install from the official repositories: `sudo pacman -S yt-dlp`
## 2. Setup
1. **Clone the Repository:**
```bash
git clone https://gitea.ramforth.net/ramforth/video-converter.git
cd video-converter
```
1. **Download the application:**
You can either clone the repository and build the application yourself, or download the latest release from the project's Gitea page.
2. **Create and Activate a Python Virtual Environment:**
It's highly recommended to use a virtual environment to manage Python dependencies.
2. **Building from source (optional):**
If you have cloned the repository, you can build the executable by running the following commands:
```bash
python3 -m venv venv
# Activate the virtual environment
source venv/bin/activate
# Build the executable
pyinstaller --noconfirm video-converter.spec
```
3. **Install Python Dependencies:**
```bash
pip install -r requirements.txt
```
## 3. Running the Application
## 3. Running the Converter
Once the setup is complete, you can run the converter script or the packaged executable.
### Running the Python Script
```bash
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.
* 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 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
After building the executable (see `DEVELOPMENT_PLAN.md` for details on packaging), you can find it in the `dist/` directory.
Once you have the executable, you can run it from your terminal.
1. **Navigate to the `dist` directory:**
```bash
cd /path/to/your/project/video-converter/dist
```
2. **Run the executable:**
2. **Make the executable runnable (if necessary):**
```bash
./video-converter [path_to_your_input_video_file] [-u <video_url>] [-q <quality_profile>] [-o <path_to_output_directory>]
chmod +x video-converter
```
The usage is identical to the Python script, but you execute the binary directly.
**Example:**
3. **Run the executable:**
```bash
./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
./video-converter
```
## 4. What it Does
This will launch the graphical user interface (GUI).
The script converts your input video into a DaVinci Resolve-compatible format using `ffmpeg`:
## 4. Using the GUI
* **Video Codec:** `dnxhd` (DNxHD/HR)
* **1080p (<=1080 height):** `dnxhr_sq` (Standard Quality)
* **1440p (>1080 height):** `dnxhr_hq` (High Quality)
* **Audio Codec:** `pcm_s16le` (Linear PCM)
* **Container:** `.mov` (QuickTime)
The GUI provides the following options:
This ensures optimal compatibility and performance for editing in DaVinci Resolve (Free Linux version).
* **Select video file or enter URL:**
* **Browse:** Click this button to open a file dialog and select a local video file to convert.
* **URL:** Enter the URL of a video to download and convert.
* **Quality:** Select the output video quality profile. The available options are `low`, `medium`, `high`, and `archive`.
* **Cookies from Browser:** If you are downloading a video that requires you to be logged in (e.g., an age-restricted YouTube video), you can select the browser from which to extract the cookies.
* **Output Directory:** Click the "Select Directory" button to choose the directory where the converted file will be saved.
* **Convert:** Click this button to start the conversion process.
* **Cancel:** This button will be enabled during the conversion process and can be used to request cancellation.
* **Status Bar:** The status bar at the bottom of the window will show the current status of the application, including download and conversion progress.
* **Progress Bar:** The progress bar will show the real-time progress of the conversion.
---
*Document generated by Gemini CLI Agent.*
## 5. Logging and Error Reporting
During the conversion, `ffmpeg`'s output is logged to a file named `ffmpeg_output.log` in the same directory as the executable.
If an error occurs during the conversion, a message box will appear with the error message and the last 10 lines of the log file. This can help you diagnose the problem.