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

v0.1.2 - Documentation standardization, version sync, config update

Browse Source
This commit is contained in:
Stu Leak 2025-11-05 15:39:15 -05:00
parent b8c07a4247
commit e340e56dc8
7 changed files with 480 additions and 331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
Makefile
View File

@ -1,4 +1,3 @@
# 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
@ -52,6 +51,12 @@ 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 ""
@ -61,16 +66,27 @@ verify:
docs: docs:
@echo "Available documentation files:" @echo "Available documentation files:"
@ls -1 "$(DOCS)" @ls -1 "$(DOCS)" | sed 's/^/ - /'
# ------------------------ # ------------------------
# Help # Help
# ------------------------ # ------------------------
help: help:
@echo "Available targets:" @echo "VideoTools Makefile — available targets:"
@echo ""
@echo " make install Install the toolkit system-wide" @echo " make install Install the toolkit system-wide"
@echo " make uninstall Remove the toolkit" @echo " make uninstall Remove all installed files"
@echo " make verify Check if FFmpeg and environment are ready" @echo " make verify Check FFmpeg, FFprobe, and environment"
@echo " make docs List documentation files" @echo " make docs List available documentation"
@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.0", "version": "0.1.1",
"output_dir": "~/Videos", "output_dir": "~/Videos",
"video_codec": "libx264", "video_codec": "libx264",
"audio_codec": "aac", "audio_codec": "aac",
@ -9,5 +9,22 @@
"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"
}
}
} }

53
docs/CHANGELOG.md
View File

@ -7,6 +7,58 @@ 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**
@ -58,5 +110,4 @@ This project adheres to [Semantic Versioning](https://semver.org/).
--- ---
End of File End of File

216
docs/CLI_Functions.md
View File

@ -1,143 +1,165 @@
# docs/CLI_Functions.md # docs/CLI_Functions.md
# CLI Function Reference (v0.1.0) CLI Function Reference (v0.1.2)
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
------------------------------------------------------------
## Quick Reference Command: convert-single
Syntax: video-tools convert-single <input> <output.mp4>
Description: Converts a single video to MP4.
| Command | Syntax | Description | Command: convert-multiple
|----------|---------|-------------| Syntax: video-tools convert-multiple <input1> <input2> ... <output.mp4>
| `convert-single` | `video-tools convert-single <input> <output.mp4>` | Converts a single video to MP4. | Description: Combines multiple video files into one MP4.
| `convert-multiple` | `video-tools convert-multiple <input1> <input2> ... <output.mp4>` | Combines multiple video files into one MP4. |
All outputs are saved in your default `~/Videos` folder, unless overridden in `config/config.json`. Command: videoinfo
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.
## Command Details All outputs are saved in your default ~/Videos folder, unless overridden in config/config.json.
### 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:
```bash video-tools convert-single <input> <output.mp4> [--hi-rate | --portable]
video-tools convert-single <input> <output.mp4>
```
**Example** Examples:
```bash video-tools convert-single "example.avi" "example.mp4"
video-tools convert-single \ video-tools convert-single "movie.avi" "movie_high.mp4" --hi-rate
"/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \ video-tools convert-single "clip.avi" "clip_mobile.mp4" --portable
"Example Movie.mp4"
```
**Output** Profiles:
``` Default - CRF 18, preset slow, audio 192k (balanced quality/speed)
/home/user/Videos/Example Movie.mp4 --hi-rate - CRF 14, preset veryslow, audio 320k (maximum quality)
``` --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 performance. - Adds -movflags +faststart to improve playback and streaming.
- Displays detailed FFmpeg progress and conversion status. - Displays detailed FFmpeg progress and conversion summary.
- Creates timestamped logs in ~/.local/share/video-tools/logs/.
**When to Use** When to Use:
- To modernize older video files. - To modernize legacy or incompatible video files.
- When a video fails to play properly on mobile or modern devices. - When playback fails on mobile or modern systems.
- To reduce file size while retaining visual quality. - To reduce file size while preserving visible quality.
--- ------------------------------------------------------------
2. convert-multiple
------------------------------------------------------------
### 2. convert-multiple Purpose:
**Purpose**
Combine several clips or discs into one MP4 output file. Combine several clips or discs into one MP4 output file.
**Usage** Usage:
```bash video-tools convert-multiple <input1> <input2> ... <output.mp4> [--hi-rate | --portable]
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"
```
**Output** Behavior:
``` - Merges all listed videos sequentially into a single MP4.
/home/user/Videos/Example Movie Combined.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/.
**Behavior** When to Use:
- Merges all listed videos sequentially. - To combine multi-part discs, episodes, or clips.
- Re-encodes each input using the same H.264/AAC settings. - When producing a single continuous playback file.
- 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** ------------------------------------------------------------
- To combine multi-part video discs, episodes, or segmented clips. 3. videoinfo
- When creating a single playback file from multiple source files. ------------------------------------------------------------
--- Purpose:
Display detailed technical information about a video file.
## Return Codes Usage:
video-tools videoinfo <file> [--verbose]
| Code | Meaning | Examples:
|------|----------| video-tools videoinfo "movie.mp4"
| 0 | Success | video-tools videoinfo "movie.mp4" --verbose
| 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
------------------------------------------------------------
| Symptom | Cause | Fix | 0 - Success
|----------|--------|----| 1 - Invalid syntax or missing arguments
| Conversion fails immediately | Input path invalid | Ensure file path is correct and quoted | 2 - FFmpeg or ffprobe execution error
| 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
------------------------------------------------------------
## Planned Additions Symptom: Conversion fails immediately
Cause: Input path invalid
Fix: Ensure full path is correct and quoted properly.
| Command | Description | Symptom: Merge causes sync or timing drift
|----------|-------------| Cause: Source files differ in resolution or frame rate
| `convert-batch` | Convert every video in a folder automatically | Fix: Convert each to MP4 first, then merge.
| `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
------------------------------------------------------------
### Conversion Logic convert-batch - Convert every video in a folder automatically.
- Uses FFmpeg with explicit input and output flags: 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.
ffmpeg -fflags +genpts -i "input" -c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k -movflags +faststart "output" video-compare - Compare bitrate, resolution, and encoding stats between two files.
``` 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 ------------------------------------------------------------
- Original files are untouched. Technical Summary
- 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,101 +1,134 @@
# docs/Conversion_Settings.md # docs/Conversion_Settings.md
# Conversion Settings (v0.1.0) Conversion Settings (v0.1.2)
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
------------------------------------------------------------
## Default Parameters Parameter: -c:v libx264
Purpose: H.264 video encoding (modern, efficient, hardware-accelerated)
| Parameter | Value | Purpose | Parameter: -crf 18
|------------|--------|----------| 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
## Quality vs. File Size Parameter: -c:a aac
Purpose: High-quality audio encoding compatible with most players
The **CRF scale** (used by FFmpeg) defines the balance between quality and compression: Parameter: -b:a 192k
Purpose: Balances clarity and file size
| CRF | Description | Typical Use | Parameter: -movflags +faststart
|------|-------------|--------------| 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 |
**Default CRF: 18** Parameter: -fflags +genpts
Provides visually lossless results while reducing most AVI/MPG files to **40–60% smaller sizes**. Purpose: Rebuilds timestamps to prevent sync issues with older containers
--- ------------------------------------------------------------
Profile Presets
------------------------------------------------------------
## Why Use Preset “slow” Default Profile:
CRF 18
Preset slow
Audio 192k
Balanced for visual clarity and efficient storage.
The preset defines the trade-off between encoding speed and compression efficiency. Hi-Rate Profile (--hi-rate):
Range: `ultrafast` → `veryslow`. CRF 14
Preset veryslow
Audio 320k
Maximum quality, slower encoding, ideal for archiving or high-bitrate content.
- `slow` offers excellent compression without excessive CPU time. Portable Profile (--portable):
- Typical speed: ~2–3× real-time on a midrange CPU. CRF 24
- Output files are usually **10–20% smaller** than with `medium` preset at the same quality. Preset faster
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
------------------------------------------------------------
**AAC at 192k** is chosen for: The CRF (Constant Rate Factor) scale controls perceived quality versus compression level.
- Broad device compatibility (phones, TVs, web players).
- Transparent stereo sound for most content.
- Efficient storage (~2 MB/min of stereo audio).
Future options may include: CRF 14–16: Near-lossless (archival or studio preservation)
- `-c:a copy` for untouched audio streams. CRF 18–20: High quality (default visual transparency)
- `-b:a 320k` for high-fidelity preservation. CRF 21–24: Medium (smaller file size, minimal loss)
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
------------------------------------------------------------
No scaling is applied by default — the video retains its original resolution and color profile. Presets define encoding speed versus compression efficiency.
Range: ultrafast → veryslow
Planned future command: `upscale-video`, supporting: The preset "slow" was chosen because:
- FFmpeg’s `scale` and `zscale` filters. - Offers a strong balance between speed and compression.
- `lanczos` resampling for sharp, clean upscales. - Output files are typically 10–20 percent smaller than those encoded at "medium".
- Optional ML upscaling (Real-ESRGAN, waifu2x). - Encoding speed is roughly two to three times real-time on a midrange CPU.
--- ------------------------------------------------------------
Audio Strategy
------------------------------------------------------------
## Future Additions 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.
| Planned Setting | Description | Future audio options include:
|------------------|-------------| - -c:a copy to preserve original streams when re-encoding is unnecessary.
| `upscale-mode` | Default scaling filter for upscaling tasks | - -b:a 320k for studio-grade sound reproduction.
| `hevc-mode` | Switch to H.265 (libx265) for smaller files | - FLAC or PCM support for lossless audio workflows.
| `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

208
docs/README.md
View File

@ -1,153 +1,153 @@
# docs/README.md # docs/README.md
# Video Tools CLI (v0.1.0) Video Tools CLI (v0.1.2)
A simple command-line utility for video conversion and merging using FFmpeg. A lightweight command-line utility for video conversion, merging, and media inspection using FFmpeg.
Designed for personal use and sharing with friends. Developed by Leak Technologies for efficient local video processing.
Works on both Linux and Windows (via Git Bash or WSL). Fully compatible with Linux and Windows (via Git Bash or WSL).
--- ------------------------------------------------------------
Overview
------------------------------------------------------------
## Overview The tool provides several core commands:
This tool provides two main commands: 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.
| Command | Description | All converted videos are saved to ~/Videos by default.
|----------|-------------| 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)
## Requirements 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.
### Linux ------------------------------------------------------------
Install FFmpeg with your package manager: Installation
```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:
```bash
git clone https://git.leaktechnologies.dev/Leak_Technologies/VideoTools.git git clone https://git.leaktechnologies.dev/Leak_Technologies/VideoTools.git
cd VideoTools cd VideoTools
```
2. Make the script executable: 2. Make the script executable:
```bash
chmod +x video-tools.sh chmod +x video-tools.sh
```
3. (Optional) Add it to PATH: 3. (Optional) Add it to your system PATH:
```bash
sudo ln -s ~/VideoTools/video-tools.sh /usr/local/bin/video-tools sudo ln -s ~/VideoTools/video-tools.sh /usr/local/bin/video-tools
```
You can now run it globally: You can now use it globally:
```bash
video-tools convert-single "input.avi" "output.mp4" video-tools convert-single "input.avi" "output.mp4"
```
--- ------------------------------------------------------------
Default Settings
------------------------------------------------------------
## Default Settings Output directory: ~/Videos
Video codec: libx264
Audio codec: aac
Quality (CRF): 18
Preset: slow
Audio bitrate: 192k
| Setting | Value | Description | These defaults balance visual quality and compression efficiency.
|----------|--------|-------------| 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 |
These defaults prioritize quality while still reducing file sizes compared to older formats such as AVI or MPG. For full parameter details, see docs/Conversion_Settings.md.
For more details, see [`docs/Conversion_Settings.md`](./Conversion_Settings.md).
--- ------------------------------------------------------------
Example Usage
------------------------------------------------------------
## Example Conversions Convert a single file:
video-tools convert-single "/path/to/input.avi" "output.mp4"
### Convert a single AVI file Merge multiple videos:
video-tools convert-multiple "/path/to/part1.avi" "/path/to/part2.avi" "combined.mp4"
```bash Check video info:
video-tools convert-single \ video-tools videoinfo "combined.mp4"
"/run/media/stu/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
"Example Movie.mp4"
```
**Output** Verbose mode:
``` video-tools videoinfo "combined.mp4" --verbose
/home/stu/Videos/Example Movie.mp4
```
--- ------------------------------------------------------------
Conversion Profiles
------------------------------------------------------------
### Combine multiple AVI parts into one MP4 Default:
CRF 18, preset slow, 192k audio (balanced quality and speed)
```bash --hi-rate:
video-tools convert-multiple \ CRF 14, preset veryslow, 320k audio (maximum quality)
"/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"
```
**Output** --portable:
``` CRF 24, preset faster, 128k audio (mobile optimized)
/home/stu/Videos/Example Movie Combined.mp4
```
--- Profiles can be added after any convert command.
## Troubleshooting Example:
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
## Roadmap Problem: ffmpeg not found
Cause: FFmpeg not installed
Fix: Install it using your system package manager
| Feature | Status | Problem: permission denied
|----------|--------| Cause: Missing executable permission
| `convert-single` | ✅ Done | Fix: chmod +x video-tools.sh
| `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
------------------------------------------------------------
| File | Description | convert-single Complete
|------|--------------| convert-multiple Complete
| [`docs/CLI_Functions.md`](./CLI_Functions.md) | Command usage reference | videoinfo Complete
| [`docs/Conversion_Settings.md`](./Conversion_Settings.md) | Technical breakdown of FFmpeg defaults | upscale-video Planned
| [`docs/Upscale.md`](./Upscale.md) | Planned module for loss-minimized video upscaling | batch conversion Planned
auto format detect Planned
video-compare Planned
config overrides Planned
--- ------------------------------------------------------------
Documentation Index
------------------------------------------------------------
## License 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
Free for personal use. ------------------------------------------------------------
You may modify or share this tool with anyone. License
------------------------------------------------------------
--- 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,73 +1,83 @@
# docs/Upscale.md # docs/Upscale.md
# Upscale Module (Planned) — v0.1.0 Upscale Module (Planned) - v0.1.2
The `upscale-video` command will provide loss-minimized video upscaling. 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.
--- ------------------------------------------------------------
Overview
------------------------------------------------------------
## Overview The goal of this module is to let users upscale existing videos to standardized modern resolutions such as:
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) - 2160p (4K UHD)
It will begin with FFmpeg’s native scaling filters and may later support machine learning-based methods. 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.
--- ------------------------------------------------------------
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
--scale <WxH> Set explicit resolution --filter <name> Choose scaling filter (lanczos, bicubic, spline36, bilinear)
--filter <name> Choose scaling filter (lanczos, bicubic, spline36) --hevc Encode output with H.265 for reduced file size
--hevc Encode using H.265 for smaller output --keep-audio Copy the original audio stream without re-encoding
--keep-audio Copy original audio stream without re-encoding
```
--- ------------------------------------------------------------
Default Behavior
------------------------------------------------------------
## Default Behavior When no scale or filter is provided, the tool will automatically upscale to the next common resolution above the source.
If no explicit resolution is provided, the tool will upscale intelligently to the nearest standard resolution above the source. Examples:
Input: 960x540 → Output: 1280x720
Input: 1280x720 → Output: 1920x1080
Input: 1440x1080 → Output: 1920x1080
**Examples:** The tool will retain the same aspect ratio and avoid unnecessary stretching or cropping.
- Input: 960×540 → Output: 1280×720
- Input: 1280×720 → Output: 1920×1080
--- ------------------------------------------------------------
Technical Notes
------------------------------------------------------------
## 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
### FFmpeg Filter Example 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.
```bash ------------------------------------------------------------
ffmpeg -i input.mp4 -vf scale=1920:1080:flags=lanczos \ Planned Features
-c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k output_1080p.mp4 ------------------------------------------------------------
```
**Explanation:** FFmpeg scaler (lanczos) Planned
- `scale=1920:1080:flags=lanczos` → performs high-quality resampling. zscale and bicubic scaling Planned
- `lanczos` produces sharp, low-artifact results. ML-based upscaling (Real-ESRGAN) Research stage
- Future versions may introduce `zscale` or machine-learning upscalers. Auto-resolution detection Planned
GPU acceleration support Planned
Configurable quality presets Planned
HEVC and AV1 encoder options Planned
Batch folder upscaling mode Planned
--- ------------------------------------------------------------
Example Future Commands
------------------------------------------------------------
## Planned Features Upscale to 1080p using default settings:
video-tools upscale-video "movie.mp4" "movie_1080p.mp4"
| Feature | Status | Upscale to 4K using HEVC and Lanczos filter:
|----------|--------| 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