VidEnc/README.md

VidEnc: Video Encoding with OMDB Metadata

VidEnc streamlines complex video transcoding workflows into a single CLI command by generating a portable FFmpeg-based shell script that:

• Converts video streams to AV1 for maximum compression efficiency
• Encodes audio tracks to Opus for reduced file size without sacrificing quality
• Adjusts anamorphic sources to a correct 1:1 sample aspect ratio automatically
• Retrieves and embeds movie title and release date from OMDB using your IMDb ID
• Strips all other metadata to produce a clean, optimized output

Designed for media archivists, home theater enthusiasts, and content creators, VidEnc offers customizable presets (CRF, film grain strength, speed), original media type tagging, optional subtitle handling, and shell completion support for a seamless CLI experience.

---

🚀 Features

• Encode video streams to AV1 and audio streams to Opus
• Convert anamorphic video to 1:1 pixel aspect ratio
• Fetch and inject movie title and release date from OMDB
• Strip all other metadata to produce a clean output
• Configurable presets, CRF, film grain, media type, and subtitle handling
• Automatic generation of a reusable encode.sh script
• Shell completion support

🔧 Prerequisites

• Python >= 3.12
• FFmpeg (including ffprobe) installed and available in your PATH
• OMDB API key: Sign up at https://www.omdbapi.com/ and set API_KEY as an environment variable or in a .env file

⚙️ Installation

1. Clone the repository (or navigate to your project folder):

   git clone https://github.com/Kessinen/VidEnc.git
   cd VidEnc
   

2. Install Python dependencies using uv:

   uv install
   

3. Create a .env file with your OMDB API key:

   echo "API_KEY=your_omdb_api_key" > .env
   

📝 Usage

Generate the encoding script

# via uv:
uv run src/app.py path/to/video.mp4 --imdb tt1234567

# or directly:
python src/app.py path/to/video.mp4 -i tt1234567

This will probe the input, fetch metadata, and write an executable encode.sh next to your video.

Execute the encoding script

bash encode.sh

⚙️ CLI Options

Option	Description	Default
-ns, --nosubtitles	Disable subtitle processing	false
-p, --preset INT	Encoding preset (1–10 scale; higher = faster, lower quality)	2
-c, --crf INT	Constant Rate Factor for video quality	30
-o, --original-media-type	Source media type (DVD, BluRay, TVRip, WebRip, Other)	DVD
-fg, --film-grain INT	Film grain strength	20
--install-completion	Install shell completion for your current shell	—
--show-completion	Display shell completion script for customization	—

# Install bash completion (example):
python src/app.py --install-completion

🔍 How It Works

1. Probe the input file with ffprobe to collect stream data.
2. Parse video, audio, and subtitle streams into a structured model.
3. Fetch title and release date from OMDB using the provided IMDb ID.
4. Configure each video stream with presets, CRF, film grain, and media type.
5. Generate a single FFmpeg command to re-encode streams, convert SAR, embed metadata, and strip all other metadata.
6. Write the command into encode.sh, prompting before overwrite if it exists.

💡 Contributing

Contributions, issues, and feature requests are welcome! Feel free to open a PR or issue in the GitHub repository.

📄 License

This project is licensed under the MIT License. See LICENSE for details.