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)
PREFIX ?= /usr/local
@ -51,12 +52,6 @@ verify:
else \
echo "✔ FFmpeg found."; \
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 ""
@ -66,27 +61,16 @@ verify:
docs:
@echo "Available documentation files:"
@ls -1 "$(DOCS)" | sed 's/^/ - /'
@ls -1 "$(DOCS)"
# ------------------------
# Help
# ------------------------
help:
@echo "VideoTools Makefile — available targets:"
@echo ""
@echo "Available targets:"
@echo " make install Install the toolkit system-wide"
@echo " make uninstall Remove all installed files"
@echo " make verify Check FFmpeg, FFprobe, and environment"
@echo " make docs List available documentation"
@echo " make uninstall Remove the toolkit"
@echo " make verify Check if FFmpeg and environment are ready"
@echo " make docs List documentation files"
@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",
"video_codec": "libx264",
"audio_codec": "aac",
@ -9,22 +9,5 @@
"default_filter": "lanczos",
"enable_faststart": true,
"auto_timestamp_fix": true,
"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"
}
}
"allow_overwrite": false
}

53
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
### Added
- Initial release of **Video Tools CLI**
@ -110,4 +58,5 @@ This project adheres to [Semantic Versioning](https://semver.org/).
---
End of File

216
docs/CLI_Functions.md
View File

@ -1,165 +1,143 @@
# 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.
------------------------------------------------------------
Quick Reference
------------------------------------------------------------
---
Command: convert-single
Syntax: video-tools convert-single <input> <output.mp4>
Description: Converts a single video to MP4.
## Quick Reference
Command: convert-multiple
Syntax: video-tools convert-multiple <input1> <input2> ... <output.mp4>
Description: Combines multiple video files into one MP4.
| Command | Syntax | Description |
|----------|---------|-------------|
| `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
Syntax: video-tools videoinfo <file>
Description: Displays concise technical details for a video.
All outputs are saved in your default `~/Videos` folder, unless overridden in `config/config.json`.
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.
Usage:
video-tools convert-single <input> <output.mp4> [--hi-rate | --portable]
**Usage**
```bash
video-tools convert-single <input> <output.mp4>
```
Examples:
video-tools convert-single "example.avi" "example.mp4"
video-tools convert-single "movie.avi" "movie_high.mp4" --hi-rate
video-tools convert-single "clip.avi" "clip_mobile.mp4" --portable
**Example**
```bash
video-tools convert-single \
"/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
"Example Movie.mp4"
```
Profiles:
Default - CRF 18, preset slow, audio 192k (balanced quality/speed)
--hi-rate - CRF 14, preset veryslow, audio 320k (maximum quality)
--portable - CRF 24, preset faster, audio 128k (mobile optimized)
**Output**
```
/home/user/Videos/Example Movie.mp4
```
Behavior:
**Behavior**
- Converts older formats (AVI, MPG, MOV, MKV, etc.) into MP4.
- Uses H.264 (libx264) for video and AAC for audio.
- Rebuilds timestamps with -fflags +genpts to prevent sync issues.
- Adds -movflags +faststart to improve playback and streaming.
- Displays detailed FFmpeg progress and conversion summary.
- Creates timestamped logs in ~/.local/share/video-tools/logs/.
- Uses H.264 (`libx264`) for video and AAC for audio.
- Rebuilds timestamps with `-fflags +genpts` to prevent sync issues.
- Adds `-movflags +faststart` to improve playback and streaming performance.
- Displays detailed FFmpeg progress and conversion status.
When to Use:
- To modernize legacy or incompatible video files.
- When playback fails on mobile or modern systems.
- To reduce file size while preserving visible quality.
**When to Use**
- To modernize older video files.
- When a video fails to play properly on mobile or modern devices.
- 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.
Usage:
video-tools convert-multiple <input1> <input2> ... <output.mp4> [--hi-rate | --portable]
**Usage**
```bash
video-tools convert-multiple <input1> <input2> ... <output.mp4>
```
Example:
**Example**
```bash
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 Part2.avi" \
"/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part3.avi" \
"Example Movie Combined.mp4"
```
Behavior:
- Merges all listed videos sequentially into a single MP4.
- Re-encodes each input using the same profile (default, hi-rate, or portable).
- 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/.
**Output**
```
/home/user/Videos/Example Movie Combined.mp4
```
When to Use:
- To combine multi-part discs, episodes, or clips.
- When producing a single continuous playback file.
**Behavior**
- Merges all listed videos sequentially.
- 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.
------------------------------------------------------------
3. videoinfo
------------------------------------------------------------
**When to Use**
- 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:
video-tools videoinfo <file> [--verbose]
## Return Codes
Examples:
video-tools videoinfo "movie.mp4"
video-tools videoinfo "movie.mp4" --verbose
| Code | Meaning |
|------|----------|
| 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.
---
------------------------------------------------------------
Return Codes
------------------------------------------------------------
## Common Issues
0 - Success
1 - Invalid syntax or missing arguments
2 - FFmpeg or ffprobe execution error
| Symptom | Cause | Fix |
|----------|--------|----|
| 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
Cause: Input path invalid
Fix: Ensure full path is correct and quoted properly.
## Planned Additions
Symptom: Merge causes sync or timing drift
Cause: Source files differ in resolution or frame rate
Fix: Convert each to MP4 first, then merge.
| Command | Description |
|----------|-------------|
| `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/.
---
------------------------------------------------------------
Planned Additions
------------------------------------------------------------
## Technical Summary
convert-batch - Convert every video in a folder automatically.
upscale-video - Upscale videos to 720p, 1080p, or 4K using lanczos or ML-based filters.
compress-video - Recompress MP4s with HEVC (H.265) or AV1 for reduced size.
video-compare - Compare bitrate, resolution, and encoding stats between two files.
auto-fix - Automatically repair timestamps or rotation metadata before encoding.
### Conversion Logic
- Uses FFmpeg with explicit input and output flags:
```
ffmpeg -fflags +genpts -i "input" -c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k -movflags +faststart "output"
```
- `-fflags +genpts` regenerates presentation timestamps (avoids "Non-monotonic DTS" errors).
- Re-encoding ensures compatibility and stable playback.
------------------------------------------------------------
Technical Summary
------------------------------------------------------------
### File Safety
- 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

157
docs/Conversion_Settings.md
View File

@ -1,134 +1,101 @@
# 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:
```
Format: MP4
Container: MPEG-4 Part 14
Video Codec: H.264 (libx264)
Audio Codec: AAC
```
Why MP4:
**Why MP4?**
- Universally supported across modern devices.
- Balances quality, compression, and compatibility.
- 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
Purpose: H.264 video encoding (modern, efficient, hardware-accelerated)
## Default Parameters
Parameter: -crf 18
Purpose: Constant Rate Factor for near-lossless quality (lower = higher quality)
| Parameter | Value | Purpose |
|------------|--------|----------|
| `-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
Purpose: High-quality audio encoding compatible with most players
## Quality vs. File Size
Parameter: -b:a 192k
Purpose: Balances clarity and file size
The **CRF scale** (used by FFmpeg) defines the balance between quality and compression:
Parameter: -movflags +faststart
Purpose: Optimizes MP4 for streaming and faster playback start
| CRF | Description | Typical Use |
|------|-------------|--------------|
| 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
Purpose: Rebuilds timestamps to prevent sync issues with older containers
**Default CRF: 18**
Provides visually lossless results while reducing most AVI/MPG files to **40–60% smaller sizes**.
------------------------------------------------------------
Profile Presets
------------------------------------------------------------
---
Default Profile:
CRF 18
Preset slow
Audio 192k
Balanced for visual clarity and efficient storage.
## Why Use Preset “slow”
Hi-Rate Profile (--hi-rate):
CRF 14
Preset veryslow
Audio 320k
Maximum quality, slower encoding, ideal for archiving or high-bitrate content.
The preset defines the trade-off between encoding speed and compression efficiency.
Range: `ultrafast` → `veryslow`.
Portable Profile (--portable):
CRF 24
Preset faster
Audio 128k
Optimized for mobile devices and reduced file sizes.
- `slow` offers excellent compression without excessive CPU time.
- Typical speed: ~2–3× real-time on a midrange CPU.
- Output files are usually **10–20% smaller** than with `medium` preset at the same quality.
Each profile automatically adjusts encoding parameters to ensure consistent results without user intervention.
---
------------------------------------------------------------
Quality vs. File Size
------------------------------------------------------------
## Audio Strategy
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)
CRF 18–20: High quality (default visual transparency)
CRF 21–24: Medium (smaller file size, minimal loss)
CRF 25+: Low quality (fast encoding, visible artifacts)
Future options may include:
- `-c:a copy` for untouched audio streams.
- `-b:a 320k` for high-fidelity preservation.
Default CRF: 18
Produces files roughly 40–60 percent smaller than original sources with minimal visible loss.
---
------------------------------------------------------------
Preset Choice
------------------------------------------------------------
## Color Space & Scaling
Presets define encoding speed versus compression efficiency.
Range: ultrafast → veryslow
No scaling is applied by default — the video retains its original resolution and color profile.
The preset "slow" was chosen because:
- Offers a strong balance between speed and compression.
- Output files are typically 10–20 percent smaller than those encoded at "medium".
- Encoding speed is roughly two to three times real-time on a midrange CPU.
Planned future command: `upscale-video`, supporting:
- FFmpeg’s `scale` and `zscale` filters.
- `lanczos` resampling for sharp, clean upscales.
- Optional ML upscaling (Real-ESRGAN, waifu2x).
------------------------------------------------------------
Audio Strategy
------------------------------------------------------------
---
AAC at 192k is used for:
- Transparent stereo audio for most content.
- Low CPU usage during encoding.
- Roughly two megabytes per minute of stereo content.
## Future Additions
Future audio options include:
- -c:a copy to preserve original streams when re-encoding is unnecessary.
- -b:a 320k for studio-grade sound reproduction.
- FLAC or PCM support for lossless audio workflows.
| Planned Setting | Description |
|------------------|-------------|
| `upscale-mode` | Default scaling filter for upscaling tasks |
| `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

208
docs/README.md
View File

@ -1,153 +1,153 @@
# 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.
Developed by Leak Technologies for efficient local video processing.
Fully compatible with Linux and Windows (via Git Bash or WSL).
A simple command-line utility for video conversion and merging using FFmpeg.
Designed for personal use and sharing with friends.
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.
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.
This tool provides two main commands:
All converted videos are saved to ~/Videos by default.
Logs are stored in ~/.local/share/video-tools/logs with ISO timestamps.
| Command | Description |
|----------|-------------|
| `convert-single` | Converts a single video file to MP4 using modern compression. |
| `convert-multiple` | Combines multiple video files into one high-quality MP4. |
------------------------------------------------------------
Requirements
------------------------------------------------------------
All output files are saved in your `~/Videos` directory by default.
Linux:
Install FFmpeg using your package manager:
sudo pacman -S ffmpeg (Arch, Garuda, EndeavourOS)
sudo apt install ffmpeg (Debian, Ubuntu, Mint)
---
Windows:
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.
## Requirements
------------------------------------------------------------
Installation
------------------------------------------------------------
### Linux
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:
```bash
git clone https://git.leaktechnologies.dev/Leak_Technologies/VideoTools.git
cd VideoTools
```
2. Make the script executable:
```bash
chmod +x video-tools.sh
```
3. (Optional) Add it to your system PATH:
3. (Optional) Add it to PATH:
```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"
```
------------------------------------------------------------
Default Settings
------------------------------------------------------------
---
Output directory: ~/Videos
Video codec: libx264
Audio codec: aac
Quality (CRF): 18
Preset: slow
Audio bitrate: 192k
## Default Settings
These defaults balance visual quality and compression efficiency.
They are ideal for general use, personal archiving, and local playback.
| Setting | Value | Description |
|----------|--------|-------------|
| 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:
video-tools convert-single "/path/to/input.avi" "output.mp4"
## Example Conversions
Merge multiple videos:
video-tools convert-multiple "/path/to/part1.avi" "/path/to/part2.avi" "combined.mp4"
### Convert a single AVI file
Check video info:
video-tools videoinfo "combined.mp4"
```bash
video-tools convert-single \
"/run/media/stu/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
"Example Movie.mp4"
```
Verbose mode:
video-tools videoinfo "combined.mp4" --verbose
**Output**
```
/home/stu/Videos/Example Movie.mp4
```
------------------------------------------------------------
Conversion Profiles
------------------------------------------------------------
---
Default:
CRF 18, preset slow, 192k audio (balanced quality and speed)
### Combine multiple AVI parts into one MP4
--hi-rate:
CRF 14, preset veryslow, 320k audio (maximum quality)
```bash
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:
CRF 24, preset faster, 128k audio (mobile optimized)
**Output**
```
/home/stu/Videos/Example Movie Combined.mp4
```
Profiles can be added after any convert command.
---
Example:
video-tools convert-single "movie.avi" "movie_high.mp4" --hi-rate
## Troubleshooting
------------------------------------------------------------
Troubleshooting
------------------------------------------------------------
| Issue | Cause | Solution |
|--------|--------|----------|
| `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
Cause: FFmpeg not installed
Fix: Install it using your system package manager
## Roadmap
Problem: permission denied
Cause: Missing executable permission
Fix: chmod +x video-tools.sh
| Feature | Status |
|----------|--------|
| `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
---
------------------------------------------------------------
Roadmap
------------------------------------------------------------
## Documentation Index
convert-single Complete
convert-multiple Complete
videoinfo Complete
upscale-video Planned
batch conversion Planned
auto format detect Planned
video-compare Planned
config overrides Planned
| File | Description |
|------|--------------|
| [`docs/CLI_Functions.md`](./CLI_Functions.md) | Command usage reference |
| [`docs/Conversion_Settings.md`](./Conversion_Settings.md) | Technical breakdown of FFmpeg defaults |
| [`docs/Upscale.md`](./Upscale.md) | Planned module for loss-minimized video upscaling |
------------------------------------------------------------
Documentation Index
------------------------------------------------------------
---
docs/CLI_Functions.md Command reference and usage examples
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
## License
------------------------------------------------------------
License
------------------------------------------------------------
Free for personal use.
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

102
docs/Upscale.md
View File

@ -1,83 +1,73 @@
# 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.
It will begin with traditional FFmpeg filters and later introduce machine learning based upscalers.
The `upscale-video` command will provide loss-minimized video upscaling.
------------------------------------------------------------
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)
- 1080p (Full HD)
- 2160p (4K UHD)
- 2160p (4K)
The first release will use FFmpeg’s built-in scaling filters including lanczos, bicubic, and spline36.
Future updates will explore GPU and ML-based upscaling options such as Real-ESRGAN and waifu2x.
It will begin with FFmpeg’s native scaling filters and may later support machine learning-based methods.
------------------------------------------------------------
Planned Syntax
------------------------------------------------------------
---
## Planned Syntax
```bash
video-tools upscale-video <input> <output.mp4> --scale 1920x1080
```
Optional parameters:
--scale <WxH> Specify custom resolution
--filter <name> Choose scaling filter (lanczos, bicubic, spline36, bilinear)
--hevc Encode output with H.265 for reduced file size
--keep-audio Copy the original audio stream without re-encoding
```
--scale <WxH> Set explicit resolution
--filter <name> Choose scaling filter (lanczos, bicubic, spline36)
--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:
Input: 960x540 → Output: 1280x720
Input: 1280x720 → Output: 1920x1080
Input: 1440x1080 → Output: 1920x1080
If no explicit resolution is provided, the tool will upscale intelligently to the nearest standard resolution above the source.
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:
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
## Technical Notes
Explanation:
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.
### FFmpeg Filter Example
------------------------------------------------------------
Planned Features
------------------------------------------------------------
```bash
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
zscale and bicubic scaling Planned
ML-based upscaling (Real-ESRGAN) Research stage
Auto-resolution detection Planned
GPU acceleration support Planned
Configurable quality presets Planned
HEVC and AV1 encoder options Planned
Batch folder upscaling mode Planned
**Explanation:**
- `scale=1920:1080:flags=lanczos` → performs high-quality resampling.
- `lanczos` produces sharp, low-artifact results.
- Future versions may introduce `zscale` or machine-learning upscalers.
------------------------------------------------------------
Example Future Commands
------------------------------------------------------------
---
Upscale to 1080p using default settings:
video-tools upscale-video "movie.mp4" "movie_1080p.mp4"
## Planned Features
Upscale to 4K using HEVC and Lanczos filter:
video-tools upscale-video "movie.mp4" "movie_4k.mp4" --scale 3840x2160 --hevc --filter lanczos
| Feature | Status |
|----------|--------|
| 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