video-converter/USAGE.md

How to Use the Video Converter (Current State)

This document outlines the steps required to set up and run the Video Converter script in its current development state.

1. Prerequisites

Before running the script, 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 for potential dependency workarounds.

2. Setup

1. Clone the Repository:

   git clone https://gitea.ramforth.net/ramforth/video-converter.git
   cd video-converter
   

2. Create and Activate a Python Virtual Environment: It's highly recommended to use a virtual environment to manage Python dependencies.

   python3 -m venv venv
   source venv/bin/activate
   

3. Install Python Dependencies:

   pip install -r requirements.txt
   

3. Running the Converter

Once the setup is complete, you can run the converter script or the packaged executable.

Running the Python Script

python -m src.main [path_to_your_input_video_file] [-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.

Example (Interactive Input):

python -m src.main
# Script will then prompt: Please enter the path to the input video file: 

Running the Packaged Executable

After building the executable (see DEVELOPMENT_PLAN.md for details on packaging), you can find it in the dist/ directory.

1. Navigate to the dist directory:

   cd /path/to/your/project/video-converter/dist
   

2. Run the executable:

   ./video-converter [path_to_your_input_video_file] [-o <path_to_output_directory>]
   

   The usage is identical to the Python script, but you execute the binary directly.

   Example:

   ./video-converter /home/user/Videos/my_original_video.mp4 -o /home/user/ConvertedVideos
   

4. What it Does

The script converts your input video into a DaVinci Resolve-compatible format using ffmpeg:

• 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)

This ensures optimal compatibility and performance for editing in DaVinci Resolve (Free Linux version).

---

Document generated by Gemini CLI Agent.