Leak_Technologies/VideoTools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: Leak_Technologies:master
Branches Tags
Leak_Technologies:master
Leak_Technologies:v0.1.2
Leak_Technologies:v0.1.1
Leak_Technologies:v0.1.0
..
compare: Leak_Technologies:v0.1.1
Branches Tags
Leak_Technologies:master
Leak_Technologies:v0.1.2
Leak_Technologies:v0.1.1
Leak_Technologies:v0.1.0

No commits in common. "master" and "v0.1.1" have entirely different histories.
master ... v0.1.1

7 changed files with 331 additions and 480 deletions
Show Stats Expand all files Collapse all files

28
Makefile
View File

@ -1,3 +1,4 @@
# root/Makefile
# Cross-platform installer for VideoTools (Linux / Windows via Git Bash or WSL) # Cross-platform installer for VideoTools (Linux / Windows via Git Bash or WSL)
PREFIX ?= /usr/local PREFIX ?= /usr/local
@ -51,12 +52,6 @@ verify:
else \ else \
echo "✔ FFmpeg found."; \ echo "✔ FFmpeg found."; \
fi fi
@if ! command -v ffprobe >/dev/null 2>&1; then \
echo "✖ FFprobe not found. Please install FFprobe before continuing."; \
exit 1; \
else \
echo "✔ FFprobe found."; \
fi
@echo "✔ Environment OK." @echo "✔ Environment OK."
@echo "" @echo ""
@ -66,27 +61,16 @@ verify:
docs: docs:
@echo "Available documentation files:" @echo "Available documentation files:"
@ls -1 "$(DOCS)" | sed 's/^/ - /' @ls -1 "$(DOCS)"
# ------------------------ # ------------------------
# Help # Help
# ------------------------ # ------------------------
help: help:
@echo "VideoTools Makefile — available targets:" @echo "Available targets:"
@echo ""
@echo " make install Install the toolkit system-wide" @echo " make install Install the toolkit system-wide"
@echo " make uninstall Remove all installed files" @echo " make uninstall Remove the toolkit"
@echo " make verify Check FFmpeg, FFprobe, and environment" @echo " make verify Check if FFmpeg and environment are ready"
@echo " make docs List available documentation" @echo " make docs List documentation files"
@echo " make help Show this message" @echo " make help Show this message"
@echo ""
@echo "Installation directories:"
@echo " Script: $(INSTALL_DIR)"
@echo " Docs : $(DOC_DIR)"
@echo ""
@echo "Note: Windows users can run 'make' via Git Bash or WSL."
# ------------------------
# End of File
# ------------------------

21
config/config.json
View File

@ -1,5 +1,5 @@
{ {
"version": "0.1.1", "version": "0.1.0",
"output_dir": "~/Videos", "output_dir": "~/Videos",
"video_codec": "libx264", "video_codec": "libx264",
"audio_codec": "aac", "audio_codec": "aac",
@ -9,22 +9,5 @@
"default_filter": "lanczos", "default_filter": "lanczos",
"enable_faststart": true, "enable_faststart": true,
"auto_timestamp_fix": true, "auto_timestamp_fix": true,
"allow_overwrite": false, "allow_overwrite": false
"logging": {
"enabled": true,
"directory": "~/.local/share/video-tools/logs",
"timestamp_format": "%Y-%m-%d_%H-%M-%S"
},
"profiles": {
"hi-rate": {
"crf": 14,
"preset": "veryslow",
"audio_bitrate": "320k"
},
"portable": {
"crf": 24,
"preset": "faster",
"audio_bitrate": "128k"
}
}
} }

55
docs/CHANGELOG.md
View File

@ -7,58 +7,6 @@ This project adheres to [Semantic Versioning](https://semver.org/).
--- ---
## [0.1.2] - 2025-11-06
### Added
- Relative path headers (`# docs/...`) restored to the top of all documentation files for readability and navigation.
- Updated documentation to reflect:
- `videoinfo` and `--verbose` functionality.
- Logging directory structure with ISO timestamps and `latest.log` symlink.
- Cross-platform (Linux/Windows) compatibility details.
- Added clarification on the `--hi-rate` and `--portable` profiles in `docs/CLI_Functions.md`.
- Added reference to computed bitrate fallback in the upcoming version roadmap.
### Changed
- Documentation standardized for plain-text (Gitea-safe) format.
- Minor corrections to examples and paths in `README.md` and `CLI_Functions.md`.
- Clarified usage of `convert-multiple` and quoting rules for paths with spaces.
- Improved layout consistency across all docs for version parity.
### Planned for 0.1.3
- Computed fallback bitrate in `videoinfo` for older containers (AVI, WMV, MPG).
- Colorized technical output for clarity.
- Header profile label display (Default / High Rate / Portable).
- Automatic configuration detection improvements.
---
## [0.1.1] - 2025-11-05
### Added
- `--hi-rate` and `--portable` profile options:
- High-rate: CRF 14, preset `veryslow`, 320 kbps audio
- Portable: CRF 24, preset `faster`, 128 kbps audio
- `videoinfo` command:
- Displays concise technical details (duration, codecs, resolution, FPS, bitrate, etc.)
- `--verbose` flag outputs full `ffprobe` metadata for debugging
- Automatic log directory:
- `~/.local/share/video-tools/logs/` with ISO-timestamped filenames
- Symlink `latest.log` points to the newest log
- Conversion summary now includes bitrate, FPS, elapsed time, and mux overhead
- Cross-platform compatibility confirmed for Linux and Windows (Git Bash / WSL)
### Changed
- Improved `convert-multiple` handling of spaced file paths
- Cleaner and color-coded CLI output
- Updated internal default values for logging and error messages
- Improved argument parsing for optional profile flags
### Fixed
- Resolved “unbound variable output_name” in `convert_multiple`
- Fixed missing log directory permissions
- Corrected path handling issues on Windows systems
- Ensured temporary concat lists are removed after conversion
---
## [0.1.0] - 2025-11-04 ## [0.1.0] - 2025-11-04
### Added ### Added
- Initial release of **Video Tools CLI** - Initial release of **Video Tools CLI**
@ -76,7 +24,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
- Color-coded CLI feedback for INFO, WARN, ERROR, OK - Color-coded CLI feedback for INFO, WARN, ERROR, OK
- Graceful error handling with safe exits and cleanup - Graceful error handling with safe exits and cleanup
- Compatible with: - Compatible with:
- Linux (bash / zsh / fish shells) - Linux (bash/zsh/fish shells)
- Windows (via Git Bash or WSL) - Windows (via Git Bash or WSL)
### Documentation ### Documentation
@ -110,4 +58,5 @@ This project adheres to [Semantic Versioning](https://semver.org/).
--- ---
End of File End of File

216
docs/CLI_Functions.md
View File

@ -1,165 +1,143 @@
# docs/CLI_Functions.md # docs/CLI_Functions.md
CLI Function Reference (v0.1.2) # CLI Function Reference (v0.1.0)
This document describes the available commands in video-tools.sh. This document describes the available commands in `video-tools.sh`.
Each command can be run from any terminal once the tool is installed. Each command can be run from any terminal once the tool is installed.
------------------------------------------------------------ ---
Quick Reference
------------------------------------------------------------
Command: convert-single ## Quick Reference
Syntax: video-tools convert-single <input> <output.mp4>
Description: Converts a single video to MP4.
Command: convert-multiple | Command | Syntax | Description |
Syntax: video-tools convert-multiple <input1> <input2> ... <output.mp4> |----------|---------|-------------|
Description: Combines multiple video files into one MP4. | `convert-single` | `video-tools convert-single <input> <output.mp4>` | Converts a single video to MP4. |
| `convert-multiple` | `video-tools convert-multiple <input1> <input2> ... <output.mp4>` | Combines multiple video files into one MP4. |
Command: videoinfo All outputs are saved in your default `~/Videos` folder, unless overridden in `config/config.json`.
Syntax: video-tools videoinfo <file>
Description: Displays concise technical details for a video.
Command: videoinfo --verbose ---
Syntax: video-tools videoinfo <file> --verbose
Description: Displays full raw ffprobe metadata for advanced debugging.
All outputs are saved in your default ~/Videos folder, unless overridden in config/config.json. ## Command Details
------------------------------------------------------------ ### 1. convert-single
1. convert-single
------------------------------------------------------------
Purpose: **Purpose**
Convert a single input video file into an MP4 using modern compression and audio standards. Convert a single input video file into an MP4 using modern compression and audio standards.
Usage: **Usage**
video-tools convert-single <input> <output.mp4> [--hi-rate | --portable] ```bash
video-tools convert-single <input> <output.mp4>
```
Examples: **Example**
video-tools convert-single "example.avi" "example.mp4" ```bash
video-tools convert-single "movie.avi" "movie_high.mp4" --hi-rate video-tools convert-single \
video-tools convert-single "clip.avi" "clip_mobile.mp4" --portable "/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
"Example Movie.mp4"
```
Profiles: **Output**
Default - CRF 18, preset slow, audio 192k (balanced quality/speed) ```
--hi-rate - CRF 14, preset veryslow, audio 320k (maximum quality) /home/user/Videos/Example Movie.mp4
--portable - CRF 24, preset faster, audio 128k (mobile optimized) ```
Behavior: **Behavior**
- Converts older formats (AVI, MPG, MOV, MKV, etc.) into MP4. - Converts older formats (AVI, MPG, MOV, MKV, etc.) into MP4.
- Uses H.264 (libx264) for video and AAC for audio. - Uses H.264 (`libx264`) for video and AAC for audio.
- Rebuilds timestamps with -fflags +genpts to prevent sync issues. - Rebuilds timestamps with `-fflags +genpts` to prevent sync issues.
- Adds -movflags +faststart to improve playback and streaming. - Adds `-movflags +faststart` to improve playback and streaming performance.
- Displays detailed FFmpeg progress and conversion summary. - Displays detailed FFmpeg progress and conversion status.
- Creates timestamped logs in ~/.local/share/video-tools/logs/.
When to Use: **When to Use**
- To modernize legacy or incompatible video files. - To modernize older video files.
- When playback fails on mobile or modern systems. - When a video fails to play properly on mobile or modern devices.
- To reduce file size while preserving visible quality. - To reduce file size while retaining visual quality.
------------------------------------------------------------ ---
2. convert-multiple
------------------------------------------------------------
Purpose: ### 2. convert-multiple
**Purpose**
Combine several clips or discs into one MP4 output file. Combine several clips or discs into one MP4 output file.
Usage: **Usage**
video-tools convert-multiple <input1> <input2> ... <output.mp4> [--hi-rate | --portable] ```bash
video-tools convert-multiple <input1> <input2> ... <output.mp4>
```
Example: **Example**
```bash
video-tools convert-multiple \ video-tools convert-multiple \
"/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \ "/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
"/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part2.avi" \ "/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part2.avi" \
"/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part3.avi" \
"Example Movie Combined.mp4" "Example Movie Combined.mp4"
```
Behavior: **Output**
- Merges all listed videos sequentially into a single MP4. ```
- Re-encodes each input using the same profile (default, hi-rate, or portable). /home/user/Videos/Example Movie Combined.mp4
- Creates and deletes a temporary concat list automatically. ```
- Displays each added file and progress in the terminal.
- Ensures the output is playable immediately after completion.
- Logs conversion details in ~/.local/share/video-tools/logs/.
When to Use: **Behavior**
- To combine multi-part discs, episodes, or clips. - Merges all listed videos sequentially.
- When producing a single continuous playback file. - Re-encodes each input using the same H.264/AAC settings.
- Creates and deletes a temporary file list automatically.
- Displays each added file and overall progress in the terminal.
- Ensures the output file is playable immediately after completion.
------------------------------------------------------------ **When to Use**
3. videoinfo - To combine multi-part video discs, episodes, or segmented clips.
------------------------------------------------------------ - When creating a single playback file from multiple source files.
Purpose: ---
Display detailed technical information about a video file.
Usage: ## Return Codes
video-tools videoinfo <file> [--verbose]
Examples: | Code | Meaning |
video-tools videoinfo "movie.mp4" |------|----------|
video-tools videoinfo "movie.mp4" --verbose | 0 | Success |
| 1 | Invalid syntax or missing arguments |
| 2 | FFmpeg execution error |
Behavior: ---
- Without flags: Displays key metadata (duration, codecs, resolution, FPS, bitrate).
- With --verbose: Prints full raw ffprobe data for technical inspection.
- Outputs consistent formatting across platforms (no bc dependency).
- Provides fallback for older files missing embedded bitrate metadata.
- Useful for comparing encoding quality or diagnosing container issues.
------------------------------------------------------------ ## Common Issues
Return Codes
------------------------------------------------------------
0 - Success | Symptom | Cause | Fix |
1 - Invalid syntax or missing arguments |----------|--------|----|
2 - FFmpeg or ffprobe execution error | Conversion fails immediately | Input path invalid | Ensure file path is correct and quoted |
| Merge creates sync issues | Source files differ in resolution or frame rate | Convert each to MP4 first, then merge |
| Output not found | FFmpeg failed silently | Check terminal logs for permission or codec errors |
------------------------------------------------------------ ---
Common Issues
------------------------------------------------------------
Symptom: Conversion fails immediately ## Planned Additions
Cause: Input path invalid
Fix: Ensure full path is correct and quoted properly.
Symptom: Merge causes sync or timing drift | Command | Description |
Cause: Source files differ in resolution or frame rate |----------|-------------|
Fix: Convert each to MP4 first, then merge. | `convert-batch` | Convert every video in a folder automatically |
| `upscale-video` | Upscale videos to 1080p or 4K using `lanczos` or ML filters |
| `compress-video` | Recompress MP4s using HEVC or AV1 for smaller storage |
| `video-info` | Quick summary of resolution, codec, and bitrate |
Symptom: Output not found ---
Cause: FFmpeg encountered an error
Fix: Review the relevant log in ~/.local/share/video-tools/logs/.
------------------------------------------------------------ ## Technical Summary
Planned Additions
------------------------------------------------------------
convert-batch - Convert every video in a folder automatically. ### Conversion Logic
upscale-video - Upscale videos to 720p, 1080p, or 4K using lanczos or ML-based filters. - Uses FFmpeg with explicit input and output flags:
compress-video - Recompress MP4s with HEVC (H.265) or AV1 for reduced size. ```
video-compare - Compare bitrate, resolution, and encoding stats between two files. ffmpeg -fflags +genpts -i "input" -c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k -movflags +faststart "output"
auto-fix - Automatically repair timestamps or rotation metadata before encoding. ```
- `-fflags +genpts` regenerates presentation timestamps (avoids "Non-monotonic DTS" errors).
- Re-encoding ensures compatibility and stable playback.
------------------------------------------------------------ ### File Safety
Technical Summary - Original files are untouched.
------------------------------------------------------------ - All intermediate list files are removed automatically.
- FFmpeg handles SIGINT (Ctrl+C) gracefully—partially written files are still playable.
Conversion Logic: ---
ffmpeg -fflags +genpts -i "input" \
-c:v libx264 -crf 18 -preset slow \
-c:a aac -b:a 192k -movflags +faststart "output"
Notes:
- -fflags +genpts regenerates presentation timestamps (avoids "Non-monotonic DTS" errors).
- Modern codecs ensure full compatibility and efficient compression.
- Re-encoding avoids playback issues caused by legacy container formats.
File Safety:
- Original files remain untouched.
- All intermediate concat lists are deleted automatically.
- FFmpeg handles SIGINT (Ctrl+C) safely — partial outputs remain playable.
------------------------------------------------------------
End of File End of File

157
docs/Conversion_Settings.md
View File

@ -1,134 +1,101 @@
# docs/Conversion_Settings.md # docs/Conversion_Settings.md
Conversion Settings (v0.1.2) # Conversion Settings (v0.1.0)
This file documents the default FFmpeg parameters used in video-tools.sh and explains why they are chosen. This file documents the default FFmpeg parameters used in `video-tools.sh` and explains why they are chosen.
------------------------------------------------------------ ---
Output Format
------------------------------------------------------------ ## Output Format
All conversions produce: All conversions produce:
```
Format: MP4 Format: MP4
Container: MPEG-4 Part 14 Container: MPEG-4 Part 14
Video Codec: H.264 (libx264) Video Codec: H.264 (libx264)
Audio Codec: AAC Audio Codec: AAC
```
Why MP4: **Why MP4?**
- Universally supported across modern devices. - Universally supported across modern devices.
- Balances quality, compression, and compatibility. - Balances quality, compression, and compatibility.
- H.264 encoding provides excellent visual quality at modest bitrates. - H.264 encoding provides excellent visual quality at modest bitrates.
- AAC audio ensures consistent playback on all major systems including Windows, macOS, Android, and iOS.
------------------------------------------------------------ ---
Default Parameters
------------------------------------------------------------
Parameter: -c:v libx264 ## Default Parameters
Purpose: H.264 video encoding (modern, efficient, hardware-accelerated)
Parameter: -crf 18 | Parameter | Value | Purpose |
Purpose: Constant Rate Factor for near-lossless quality (lower = higher quality) |------------|--------|----------|
| `-c:v libx264` | H.264 video encoding | Modern, efficient codec with wide hardware support |
| `-crf 18` | Constant Rate Factor | Maintains near-lossless visual quality (lower = better) |
| `-preset slow` | Encoding preset | Improves compression efficiency at moderate CPU cost |
| `-c:a aac` | Audio codec | Standard high-quality stereo audio |
| `-b:a 192k` | Audio bitrate | Balances fidelity and file size |
| `-movflags +faststart` | MP4 optimization | Enables faster playback start in players or web streams |
| `-fflags +genpts` | Timestamp repair | Regenerates timestamps on older AVI/MPEG inputs |
Parameter: -preset slow ---
Purpose: Improves compression efficiency at moderate CPU cost
Parameter: -c:a aac ## Quality vs. File Size
Purpose: High-quality audio encoding compatible with most players
Parameter: -b:a 192k The **CRF scale** (used by FFmpeg) defines the balance between quality and compression:
Purpose: Balances clarity and file size
Parameter: -movflags +faststart | CRF | Description | Typical Use |
Purpose: Optimizes MP4 for streaming and faster playback start |------|-------------|--------------|
| 14–16 | Near lossless | Archival or professional mastering |
| 18–20 | High quality | Everyday use, visually lossless |
| 21–24 | Medium quality | Smaller file sizes with light compression |
| 25+ | Low quality | Fast compression, noticeable loss |
Parameter: -fflags +genpts **Default CRF: 18**
Purpose: Rebuilds timestamps to prevent sync issues with older containers Provides visually lossless results while reducing most AVI/MPG files to **40–60% smaller sizes**.
------------------------------------------------------------ ---
Profile Presets
------------------------------------------------------------
Default Profile: ## Why Use Preset “slow”
CRF 18
Preset slow
Audio 192k
Balanced for visual clarity and efficient storage.
Hi-Rate Profile (--hi-rate): The preset defines the trade-off between encoding speed and compression efficiency.
CRF 14 Range: `ultrafast` → `veryslow`.
Preset veryslow
Audio 320k
Maximum quality, slower encoding, ideal for archiving or high-bitrate content.
Portable Profile (--portable): - `slow` offers excellent compression without excessive CPU time.
CRF 24 - Typical speed: ~2–3× real-time on a midrange CPU.
Preset faster - Output files are usually **10–20% smaller** than with `medium` preset at the same quality.
Audio 128k
Optimized for mobile devices and reduced file sizes.
Each profile automatically adjusts encoding parameters to ensure consistent results without user intervention. ---
------------------------------------------------------------ ## Audio Strategy
Quality vs. File Size
------------------------------------------------------------
The CRF (Constant Rate Factor) scale controls perceived quality versus compression level. **AAC at 192k** is chosen for:
- Broad device compatibility (phones, TVs, web players).
- Transparent stereo sound for most content.
- Efficient storage (~2 MB/min of stereo audio).
CRF 14–16: Near-lossless (archival or studio preservation) Future options may include:
CRF 18–20: High quality (default visual transparency) - `-c:a copy` for untouched audio streams.
CRF 21–24: Medium (smaller file size, minimal loss) - `-b:a 320k` for high-fidelity preservation.
CRF 25+: Low quality (fast encoding, visible artifacts)
Default CRF: 18 ---
Produces files roughly 40–60 percent smaller than original sources with minimal visible loss.
------------------------------------------------------------ ## Color Space & Scaling
Preset Choice
------------------------------------------------------------
Presets define encoding speed versus compression efficiency. No scaling is applied by default — the video retains its original resolution and color profile.
Range: ultrafast → veryslow
The preset "slow" was chosen because: Planned future command: `upscale-video`, supporting:
- Offers a strong balance between speed and compression. - FFmpeg’s `scale` and `zscale` filters.
- Output files are typically 10–20 percent smaller than those encoded at "medium". - `lanczos` resampling for sharp, clean upscales.
- Encoding speed is roughly two to three times real-time on a midrange CPU. - Optional ML upscaling (Real-ESRGAN, waifu2x).
------------------------------------------------------------ ---
Audio Strategy
------------------------------------------------------------
AAC at 192k is used for: ## Future Additions
- Transparent stereo audio for most content.
- Low CPU usage during encoding.
- Roughly two megabytes per minute of stereo content.
Future audio options include: | Planned Setting | Description |
- -c:a copy to preserve original streams when re-encoding is unnecessary. |------------------|-------------|
- -b:a 320k for studio-grade sound reproduction. | `upscale-mode` | Default scaling filter for upscaling tasks |
- FLAC or PCM support for lossless audio workflows. | `hevc-mode` | Switch to H.265 (libx265) for smaller files |
| `audio-pass` | Option to skip audio re-encoding |
| `config.json` | User-editable file to override default values |
------------------------------------------------------------ ---
Color and Resolution
------------------------------------------------------------
No scaling or color adjustments occur unless explicitly requested.
Source resolution, frame rate, and color space (usually bt709) are preserved.
Future command "upscale-video" will support:
- FFmpeg scale and zscale filters.
- Lanczos resampling for high-quality upscales.
- Optional machine-learning upscalers such as Real-ESRGAN or waifu2x.
------------------------------------------------------------
Future Additions
------------------------------------------------------------
upscale-mode Choose default scaling filter for upscaling tasks
hevc-mode Switch to H.265 (libx265) for smaller, more efficient files
audio-pass Skip audio re-encoding when not needed
config.json User-editable configuration to override all defaults
auto-bitrate Compute estimated average bitrate for legacy containers
------------------------------------------------------------
End of File End of File

216
docs/README.md
View File

@ -1,153 +1,153 @@
# docs/README.md # docs/README.md
Video Tools CLI (v0.1.2) # Video Tools CLI (v0.1.0)
A lightweight command-line utility for video conversion, merging, and media inspection using FFmpeg. A simple command-line utility for video conversion and merging using FFmpeg.
Developed by Leak Technologies for efficient local video processing. Designed for personal use and sharing with friends.
Fully compatible with Linux and Windows (via Git Bash or WSL). Works on both Linux and Windows (via Git Bash or WSL).
------------------------------------------------------------ ---
Overview
------------------------------------------------------------
The tool provides several core commands: ## Overview
convert-single Converts a single video to MP4 using high-quality compression. This tool provides two main commands:
convert-multiple Combines multiple video clips or discs into one MP4 file.
videoinfo Displays technical details such as bitrate, resolution, codecs, and duration.
videoinfo --verbose Shows full ffprobe metadata for advanced analysis.
All converted videos are saved to ~/Videos by default. | Command | Description |
Logs are stored in ~/.local/share/video-tools/logs with ISO timestamps. |----------|-------------|
| `convert-single` | Converts a single video file to MP4 using modern compression. |
| `convert-multiple` | Combines multiple video files into one high-quality MP4. |
------------------------------------------------------------ All output files are saved in your `~/Videos` directory by default.
Requirements
------------------------------------------------------------
Linux: ---
Install FFmpeg using your package manager:
sudo pacman -S ffmpeg (Arch, Garuda, EndeavourOS)
sudo apt install ffmpeg (Debian, Ubuntu, Mint)
Windows: ## Requirements
1. Download FFmpeg from https://ffmpeg.org/download.html
2. Add FFmpeg to your PATH environment variable.
3. Use Git Bash or WSL to execute video-tools.sh.
------------------------------------------------------------ ### Linux
Installation Install FFmpeg with your package manager:
------------------------------------------------------------ ```bash
sudo pacman -S ffmpeg # For Arch or Garuda
sudo apt install ffmpeg # For Debian or Ubuntu
```
### Windows
1. Install FFmpeg from https://ffmpeg.org/download.html
2. Use **Git Bash** or **WSL** to run the script.
---
## Installation
1. Clone or copy the repository: 1. Clone or copy the repository:
git clone https://git.leaktechnologies.dev/Leak_Technologies/VideoTools.git ```bash
cd VideoTools git clone https://git.leaktechnologies.dev/Leak_Technologies/VideoTools.git
cd VideoTools
```
2. Make the script executable: 2. Make the script executable:
chmod +x video-tools.sh ```bash
chmod +x video-tools.sh
```
3. (Optional) Add it to your system PATH: 3. (Optional) Add it to PATH:
sudo ln -s ~/VideoTools/video-tools.sh /usr/local/bin/video-tools ```bash
sudo ln -s ~/VideoTools/video-tools.sh /usr/local/bin/video-tools
```
You can now use it globally: You can now run it globally:
```bash
video-tools convert-single "input.avi" "output.mp4" video-tools convert-single "input.avi" "output.mp4"
```
------------------------------------------------------------ ---
Default Settings
------------------------------------------------------------
Output directory: ~/Videos ## Default Settings
Video codec: libx264
Audio codec: aac
Quality (CRF): 18
Preset: slow
Audio bitrate: 192k
These defaults balance visual quality and compression efficiency. | Setting | Value | Description |
They are ideal for general use, personal archiving, and local playback. |----------|--------|-------------|
| Output directory | `~/Videos` | All results are stored here |
| Video codec | `libx264` | High-quality H.264 encoding |
| Audio codec | `aac` | High-quality AAC stereo audio |
| Quality (CRF) | 18 | Visually lossless quality |
| Preset | `slow` | Balances speed and compression |
| Audio bitrate | 192k | High-quality stereo output |
For full parameter details, see docs/Conversion_Settings.md. These defaults prioritize quality while still reducing file sizes compared to older formats such as AVI or MPG.
For more details, see [`docs/Conversion_Settings.md`](./Conversion_Settings.md).
------------------------------------------------------------ ---
Example Usage
------------------------------------------------------------
Convert a single file: ## Example Conversions
video-tools convert-single "/path/to/input.avi" "output.mp4"
Merge multiple videos: ### Convert a single AVI file
video-tools convert-multiple "/path/to/part1.avi" "/path/to/part2.avi" "combined.mp4"
Check video info: ```bash
video-tools videoinfo "combined.mp4" video-tools convert-single \
"/run/media/stu/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
"Example Movie.mp4"
```
Verbose mode: **Output**
video-tools videoinfo "combined.mp4" --verbose ```
/home/stu/Videos/Example Movie.mp4
```
------------------------------------------------------------ ---
Conversion Profiles
------------------------------------------------------------
Default: ### Combine multiple AVI parts into one MP4
CRF 18, preset slow, 192k audio (balanced quality and speed)
--hi-rate: ```bash
CRF 14, preset veryslow, 320k audio (maximum quality) video-tools convert-multiple \
"/run/media/stu/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
"/run/media/stu/Linux/MyData/Videos/Example Collection/Example Movie Part2.avi" \
"/run/media/stu/Linux/MyData/Videos/Example Collection/Example Movie Part3.avi" \
"Example Movie Combined.mp4"
```
--portable: **Output**
CRF 24, preset faster, 128k audio (mobile optimized) ```
/home/stu/Videos/Example Movie Combined.mp4
```
Profiles can be added after any convert command. ---
Example: ## Troubleshooting
video-tools convert-single "movie.avi" "movie_high.mp4" --hi-rate
------------------------------------------------------------ | Issue | Cause | Solution |
Troubleshooting |--------|--------|----------|
------------------------------------------------------------ | `command not found` | Script not in PATH | Use full path or add symlink to `/usr/local/bin` |
| `ffmpeg not found` | FFmpeg not installed | Install FFmpeg using your package manager |
| `Permission denied` | Script not executable | Run `chmod +x video-tools.sh` |
| Merge fails | Input files have mismatched codecs | Convert each input to MP4 first, then merge |
Problem: command not found ---
Cause: Script not linked globally
Fix: Run ./video-tools.sh or create a symlink in /usr/local/bin
Problem: ffmpeg not found ## Roadmap
Cause: FFmpeg not installed
Fix: Install it using your system package manager
Problem: permission denied | Feature | Status |
Cause: Missing executable permission |----------|--------|
Fix: chmod +x video-tools.sh | `convert-single` | ✅ Done |
| `convert-multiple` | ✅ Done |
| `upscale-video` | 🔜 Planned |
| `batch conversion` | 🔜 Planned |
| `automatic format detection` | 🔜 Planned |
Problem: merge fails ---
Cause: Inputs use different codecs or frame rates
Fix: Convert each input to MP4 first, then merge
------------------------------------------------------------ ## Documentation Index
Roadmap
------------------------------------------------------------
convert-single Complete | File | Description |
convert-multiple Complete |------|--------------|
videoinfo Complete | [`docs/CLI_Functions.md`](./CLI_Functions.md) | Command usage reference |
upscale-video Planned | [`docs/Conversion_Settings.md`](./Conversion_Settings.md) | Technical breakdown of FFmpeg defaults |
batch conversion Planned | [`docs/Upscale.md`](./Upscale.md) | Planned module for loss-minimized video upscaling |
auto format detect Planned
video-compare Planned
config overrides Planned
------------------------------------------------------------ ---
Documentation Index
------------------------------------------------------------
docs/CLI_Functions.md Command reference and usage examples ## License
docs/Conversion_Settings.md Technical breakdown of encoding defaults
docs/CHANGELOG.md Version history and planned updates
docs/Upscale.md Future plans for scaling and ML-based enhancement
------------------------------------------------------------ Free for personal use.
License You may modify or share this tool with anyone.
------------------------------------------------------------
Free for personal and educational use. ---
Redistribution permitted with attribution to Leak Technologies.
------------------------------------------------------------
End of File End of File

102
docs/Upscale.md
View File

@ -1,83 +1,73 @@
# docs/Upscale.md # docs/Upscale.md
Upscale Module (Planned) - v0.1.2 # Upscale Module (Planned) — v0.1.0
The upscale-video command will provide high-quality resolution upscaling with minimal visual loss. The `upscale-video` command will provide loss-minimized video upscaling.
It will begin with traditional FFmpeg filters and later introduce machine learning based upscalers.
------------------------------------------------------------ ---
Overview
------------------------------------------------------------
The goal of this module is to let users upscale existing videos to standardized modern resolutions such as: ## Overview
This module will allow upscaling of existing videos to higher resolutions such as:
- 720p (HD) - 720p (HD)
- 1080p (Full HD) - 1080p (Full HD)
- 2160p (4K UHD) - 2160p (4K)
The first release will use FFmpeg’s built-in scaling filters including lanczos, bicubic, and spline36. It will begin with FFmpeg’s native scaling filters and may later support machine learning-based methods.
Future updates will explore GPU and ML-based upscaling options such as Real-ESRGAN and waifu2x.
------------------------------------------------------------ ---
Planned Syntax
------------------------------------------------------------
## Planned Syntax
```bash
video-tools upscale-video <input> <output.mp4> --scale 1920x1080 video-tools upscale-video <input> <output.mp4> --scale 1920x1080
```
Optional parameters: Optional parameters:
--scale <WxH> Specify custom resolution ```
--filter <name> Choose scaling filter (lanczos, bicubic, spline36, bilinear) --scale <WxH> Set explicit resolution
--hevc Encode output with H.265 for reduced file size --filter <name> Choose scaling filter (lanczos, bicubic, spline36)
--keep-audio Copy the original audio stream without re-encoding --hevc Encode using H.265 for smaller output
--keep-audio Copy original audio stream without re-encoding
```
------------------------------------------------------------ ---
Default Behavior
------------------------------------------------------------
When no scale or filter is provided, the tool will automatically upscale to the next common resolution above the source. ## Default Behavior
Examples: If no explicit resolution is provided, the tool will upscale intelligently to the nearest standard resolution above the source.
Input: 960x540 → Output: 1280x720
Input: 1280x720 → Output: 1920x1080
Input: 1440x1080 → Output: 1920x1080
The tool will retain the same aspect ratio and avoid unnecessary stretching or cropping. **Examples:**
- Input: 960×540 → Output: 1280×720
- Input: 1280×720 → Output: 1920×1080
------------------------------------------------------------ ---
Technical Notes
------------------------------------------------------------
Example FFmpeg usage: ## Technical Notes
ffmpeg -i input.mp4 -vf scale=1920:1080:flags=lanczos -c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k output_1080p.mp4
Explanation: ### FFmpeg Filter Example
scale=1920:1080:flags=lanczos performs resampling using the Lanczos algorithm for sharp, high-quality results.
Lanczos minimizes aliasing and ringing while retaining edge detail.
Future implementations may use zscale for improved color management or GPU-accelerated scaling with CUDA or Vulkan.
------------------------------------------------------------ ```bash
Planned Features ffmpeg -i input.mp4 -vf scale=1920:1080:flags=lanczos \
------------------------------------------------------------ -c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k output_1080p.mp4
```
FFmpeg scaler (lanczos) Planned **Explanation:**
zscale and bicubic scaling Planned - `scale=1920:1080:flags=lanczos` → performs high-quality resampling.
ML-based upscaling (Real-ESRGAN) Research stage - `lanczos` produces sharp, low-artifact results.
Auto-resolution detection Planned - Future versions may introduce `zscale` or machine-learning upscalers.
GPU acceleration support Planned
Configurable quality presets Planned
HEVC and AV1 encoder options Planned
Batch folder upscaling mode Planned
------------------------------------------------------------ ---
Example Future Commands
------------------------------------------------------------
Upscale to 1080p using default settings: ## Planned Features
video-tools upscale-video "movie.mp4" "movie_1080p.mp4"
Upscale to 4K using HEVC and Lanczos filter: | Feature | Status |
video-tools upscale-video "movie.mp4" "movie_4k.mp4" --scale 3840x2160 --hevc --filter lanczos |----------|--------|
| FFmpeg scaler (`lanczos`) | 🔜 Planned |
| ML-based upscaling (Real-ESRGAN / waifu2x) | 🚧 Research |
| Auto-resolution detection | 🔜 Planned |
| GPU acceleration support | 🔜 Planned |
| Configurable presets | 🔜 Planned |
Copy original audio without re-encoding: ---
video-tools upscale-video "documentary.mp4" "documentary_upscaled.mp4" --keep-audio
------------------------------------------------------------
End of File End of File