Update README
This commit is contained in:
Esa Kataja
@@ -1,33 +1,98 @@
|
|||||||
# Video Encoding App
|
# VidEnc: Video Encoding with OMDB Metadata
|
||||||
|
|
||||||
## Overview
|
VidEnc streamlines complex video transcoding workflows into a single CLI command by generating a portable FFmpeg-based shell script that:
|
||||||
This app takes a video file and an IMDb ID as input, generates a shell script to encode the video streams to AV1 and audio streams to Opus format, converts anamorphic video to SAR 1:1, and adds metadata from OMDB while stripping all other metadata.
|
- 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
|
||||||
|
|
||||||
## Input Requirements
|
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.
|
||||||
1. **Video File**: A valid video file in a supported format.
|
|
||||||
2. **IMDb ID**: A valid IMDb ID to fetch metadata from OMDB.
|
|
||||||
|
|
||||||
## Optional CLI Arguments
|
---
|
||||||
1. **`-ns`/`--nosubtitles`**: Disables subtitle processing.
|
|
||||||
2. **`-p`/`--preset`**: Sets the encoding preset for the video. Default is `2`.
|
|
||||||
3. **`-c`/`--crf`**: Sets the CRF value for the video. Default is `30`.
|
|
||||||
4. **`-o`/`--original-media-type`**: Sets the ORIGINAL_MEDIA_TYPE metadata. Default is `DVD`.
|
|
||||||
|
|
||||||
## Output Details
|
## 🚀 Features
|
||||||
The app generates a shell script that performs the following tasks:
|
|
||||||
1. Encodes the video to AV1 format.
|
|
||||||
2. Encodes the audio to Opus format.
|
|
||||||
3. Converts anamorphic video to SAR 1:1.
|
|
||||||
4. Adds metadata from OMDB using the provided IMDb ID.
|
|
||||||
5. Strips all other metadata from the video.
|
|
||||||
|
|
||||||
## Metadata Handling
|
- Encode video streams to AV1 and audio streams to Opus
|
||||||
- **Added Metadata**: Metadata fetched from OMDB using the IMDb ID.
|
- Convert anamorphic video to 1:1 pixel aspect ratio
|
||||||
- **Stripped Metadata**: All other metadata is removed from the video.
|
- 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
|
||||||
|
|
||||||
## Anamorphic Video Conversion
|
## 🔧 Prerequisites
|
||||||
Anamorphic videos are converted to SAR (Sample Aspect Ratio) 1:1 to ensure proper display on all devices.
|
|
||||||
|
- **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):
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/Kessinen/VidEnc.git
|
||||||
|
cd VidEnc
|
||||||
|
```
|
||||||
|
2. Install Python dependencies using **uv**:
|
||||||
|
```bash
|
||||||
|
uv install
|
||||||
|
```
|
||||||
|
3. Create a `.env` file with your OMDB API key:
|
||||||
|
```bash
|
||||||
|
echo "API_KEY=your_omdb_api_key" > .env
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📝 Usage
|
||||||
|
|
||||||
|
### Generate the encoding script
|
||||||
|
|
||||||
## Example Usage
|
|
||||||
```bash
|
```bash
|
||||||
./encode_video.sh input_video.mp4 -i tt1234567
|
# 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
|
||||||
|
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 | — |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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](https://github.com/Kessinen/VidEnc).
|
||||||
|
|
||||||
|
## 📄 License
|
||||||
|
|
||||||
|
This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
|
||||||
Reference in New Issue
Block a user