diff --git a/Makefile b/Makefile
index cebec4f..f8132ec 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,3 @@
-# root/Makefile
# Cross-platform installer for VideoTools (Linux / Windows via Git Bash or WSL)
PREFIX ?= /usr/local
@@ -52,6 +51,12 @@ 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 ""
@@ -61,16 +66,27 @@ verify:
docs:
@echo "Available documentation files:"
- @ls -1 "$(DOCS)"
+ @ls -1 "$(DOCS)" | sed 's/^/ - /'
# ------------------------
# Help
# ------------------------
help:
- @echo "Available targets:"
+ @echo "VideoTools Makefile — available targets:"
+ @echo ""
@echo " make install Install the toolkit system-wide"
- @echo " make uninstall Remove the toolkit"
- @echo " make verify Check if FFmpeg and environment are ready"
- @echo " make docs List documentation files"
+ @echo " make uninstall Remove all installed files"
+ @echo " make verify Check FFmpeg, FFprobe, and environment"
+ @echo " make docs List available documentation"
@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
+# ------------------------
diff --git a/config/config.json b/config/config.json
index ecb9ae6..136db5a 100644
--- a/config/config.json
+++ b/config/config.json
@@ -1,5 +1,5 @@
{
- "version": "0.1.0",
+ "version": "0.1.1",
"output_dir": "~/Videos",
"video_codec": "libx264",
"audio_codec": "aac",
@@ -9,5 +9,22 @@
"default_filter": "lanczos",
"enable_faststart": 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"
+ }
+ }
}
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index c93cd9d..3d88df0 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -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
### Added
- Initial release of **Video Tools CLI**
@@ -24,7 +76,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
- Color-coded CLI feedback for INFO, WARN, ERROR, OK
- Graceful error handling with safe exits and cleanup
- Compatible with:
- - Linux (bash/zsh/fish shells)
+ - Linux (bash / zsh / fish shells)
- Windows (via Git Bash or WSL)
### Documentation
@@ -35,16 +87,16 @@ This project adheres to [Semantic Versioning](https://semver.org/).
### Build System
- `Makefile` with:
- - `install` / `uninstall` / `verify` / `docs` / `help` targets
- - Version-aware output and FFmpeg dependency check
- - Installs both binary and documentation to system paths
+ - `install` / `uninstall` / `verify` / `docs` / `help` targets
+ - Version-aware output and FFmpeg dependency check
+ - Installs both binary and documentation to system paths
---
## Planned for [0.2.0]
### Added
- `upscale-video` command:
- - FFmpeg `lanczos` scaling for 720p / 1080p / 4K
+ - FFmpeg `lanczos` scaling for 720p / 1080p / 4K
- Optional H.265 (HEVC) encoding for smaller files
- `convert-batch` for folder-wide conversions
- JSON-driven override for per-run configuration (custom CRF, bitrate, etc.)
@@ -58,5 +110,4 @@ This project adheres to [Semantic Versioning](https://semver.org/).
---
-
End of File
diff --git a/docs/CLI_Functions.md b/docs/CLI_Functions.md
index 02268a0..852ee0f 100644
--- a/docs/CLI_Functions.md
+++ b/docs/CLI_Functions.md
@@ -1,143 +1,165 @@
# 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.
----
+------------------------------------------------------------
+Quick Reference
+------------------------------------------------------------
-## Quick Reference
+Command: convert-single
+Syntax: video-tools convert-single
+Description: Converts a single video to MP4.
-| Command | Syntax | Description |
-|----------|---------|-------------|
-| `convert-single` | `video-tools convert-single ` | Converts a single video to MP4. |
-| `convert-multiple` | `video-tools convert-multiple ... ` | Combines multiple video files into one MP4. |
+Command: convert-multiple
+Syntax: video-tools convert-multiple ...
+Description: 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
+Description: Displays concise technical details for a video.
----
+Command: videoinfo --verbose
+Syntax: video-tools videoinfo --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.
-**Usage**
-```bash
-video-tools convert-single
-```
+Usage:
+video-tools convert-single [--hi-rate | --portable]
-**Example**
-```bash
-video-tools convert-single \
-"/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
-"Example Movie.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
-**Output**
-```
-/home/user/Videos/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)
-**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 performance.
-- Displays detailed FFmpeg progress and conversion status.
+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/.
-**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.
+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.
----
+------------------------------------------------------------
+2. convert-multiple
+------------------------------------------------------------
-### 2. convert-multiple
-
-**Purpose**
+Purpose:
Combine several clips or discs into one MP4 output file.
-**Usage**
-```bash
-video-tools convert-multiple ...
-```
+Usage:
+video-tools convert-multiple ... [--hi-rate | --portable]
-**Example**
-```bash
+Example:
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"
-```
-**Output**
-```
-/home/user/Videos/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/.
-**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.
+When to Use:
+- To combine multi-part discs, episodes, or clips.
+- When producing a single continuous playback file.
-**When to Use**
-- To combine multi-part video discs, episodes, or segmented clips.
-- When creating a single playback file from multiple source files.
+------------------------------------------------------------
+3. videoinfo
+------------------------------------------------------------
----
+Purpose:
+Display detailed technical information about a video file.
-## Return Codes
+Usage:
+video-tools videoinfo [--verbose]
-| Code | Meaning |
-|------|----------|
-| 0 | Success |
-| 1 | Invalid syntax or missing arguments |
-| 2 | FFmpeg execution error |
+Examples:
+video-tools videoinfo "movie.mp4"
+video-tools videoinfo "movie.mp4" --verbose
----
+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 |
-|----------|--------|----|
-| 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 |
+0 - Success
+1 - Invalid syntax or missing arguments
+2 - FFmpeg or ffprobe execution error
----
+------------------------------------------------------------
+Common Issues
+------------------------------------------------------------
-## Planned Additions
+Symptom: Conversion fails immediately
+Cause: Input path invalid
+Fix: Ensure full path is correct and quoted properly.
-| 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: Merge causes sync or timing drift
+Cause: Source files differ in resolution or frame rate
+Fix: Convert each to MP4 first, then merge.
----
+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
-- 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.
+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.
-### 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.
+------------------------------------------------------------
+Technical Summary
+------------------------------------------------------------
----
+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
diff --git a/docs/Conversion_Settings.md b/docs/Conversion_Settings.md
index 4a390c4..32266c2 100644
--- a/docs/Conversion_Settings.md
+++ b/docs/Conversion_Settings.md
@@ -1,101 +1,134 @@
# 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:
-```
-Format: MP4
-Container: MPEG-4 Part 14
-Video Codec: H.264 (libx264)
+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
+------------------------------------------------------------
-## Default Parameters
+Parameter: -c:v libx264
+Purpose: H.264 video encoding (modern, efficient, hardware-accelerated)
-| 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: -crf 18
+Purpose: Constant Rate Factor for near-lossless quality (lower = higher quality)
----
+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 |
-|------|-------------|--------------|
-| 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: -movflags +faststart
+Purpose: Optimizes MP4 for streaming and faster playback start
-**Default CRF: 18**
-Provides visually lossless results while reducing most AVI/MPG files to **40–60% smaller sizes**.
+Parameter: -fflags +genpts
+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.
-Range: `ultrafast` → `veryslow`.
+Hi-Rate Profile (--hi-rate):
+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.
-- 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.
+Portable Profile (--portable):
+CRF 24
+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:
-- Broad device compatibility (phones, TVs, web players).
-- Transparent stereo sound for most content.
-- Efficient storage (~2 MB/min of stereo audio).
+The CRF (Constant Rate Factor) scale controls perceived quality versus compression level.
-Future options may include:
-- `-c:a copy` for untouched audio streams.
-- `-b:a 320k` for high-fidelity preservation.
+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)
----
+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:
-- FFmpeg’s `scale` and `zscale` filters.
-- `lanczos` resampling for sharp, clean upscales.
-- Optional ML upscaling (Real-ESRGAN, waifu2x).
+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.
----
+------------------------------------------------------------
+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 |
-|------------------|-------------|
-| `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 |
+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.
----
+------------------------------------------------------------
+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
diff --git a/docs/README.md b/docs/README.md
index d719425..7f83389 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,153 +1,153 @@
# 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.
-Designed for personal use and sharing with friends.
-Works on both Linux and Windows (via Git Bash or WSL).
+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).
----
+------------------------------------------------------------
+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 |
-|----------|-------------|
-| `convert-single` | Converts a single video file to MP4 using modern compression. |
-| `convert-multiple` | Combines multiple video files into one high-quality MP4. |
+All converted videos are saved to ~/Videos by default.
+Logs are stored in ~/.local/share/video-tools/logs with ISO timestamps.
-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:
-```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
+------------------------------------------------------------
+Installation
+------------------------------------------------------------
1. Clone or copy the repository:
- ```bash
- git clone https://git.leaktechnologies.dev/Leak_Technologies/VideoTools.git
- cd VideoTools
- ```
+git clone https://git.leaktechnologies.dev/Leak_Technologies/VideoTools.git
+cd VideoTools
2. Make the script executable:
- ```bash
- chmod +x video-tools.sh
- ```
+chmod +x video-tools.sh
-3. (Optional) Add it to PATH:
- ```bash
- sudo ln -s ~/VideoTools/video-tools.sh /usr/local/bin/video-tools
- ```
+3. (Optional) Add it to your system PATH:
+sudo ln -s ~/VideoTools/video-tools.sh /usr/local/bin/video-tools
-You can now run it globally:
-```bash
+You can now use it globally:
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 |
-|----------|--------|-------------|
-| 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 balance visual quality and compression efficiency.
+They are ideal for general use, personal archiving, and local playback.
-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).
+For full parameter details, see docs/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
-video-tools convert-single \
-"/run/media/stu/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
-"Example Movie.mp4"
-```
+Check video info:
+video-tools videoinfo "combined.mp4"
-**Output**
-```
-/home/stu/Videos/Example Movie.mp4
-```
+Verbose mode:
+video-tools videoinfo "combined.mp4" --verbose
----
+------------------------------------------------------------
+Conversion Profiles
+------------------------------------------------------------
-### Combine multiple AVI parts into one MP4
+Default:
+CRF 18, preset slow, 192k audio (balanced quality and speed)
-```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"
-```
+--hi-rate:
+CRF 14, preset veryslow, 320k audio (maximum quality)
-**Output**
-```
-/home/stu/Videos/Example Movie Combined.mp4
-```
+--portable:
+CRF 24, preset faster, 128k audio (mobile optimized)
----
+Profiles can be added after any convert command.
-## Troubleshooting
+Example:
+video-tools convert-single "movie.avi" "movie_high.mp4" --hi-rate
-| 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 |
+------------------------------------------------------------
+Troubleshooting
+------------------------------------------------------------
----
+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 |
-|----------|--------|
-| `convert-single` | ✅ Done |
-| `convert-multiple` | ✅ Done |
-| `upscale-video` | 🔜 Planned |
-| `batch conversion` | 🔜 Planned |
-| `automatic format detection` | 🔜 Planned |
+Problem: permission denied
+Cause: Missing executable permission
+Fix: chmod +x video-tools.sh
----
+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 |
-|------|--------------|
-| [`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 |
+convert-single Complete
+convert-multiple Complete
+videoinfo Complete
+upscale-video Planned
+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
diff --git a/docs/Upscale.md b/docs/Upscale.md
index b5dce4c..5835163 100644
--- a/docs/Upscale.md
+++ b/docs/Upscale.md
@@ -1,73 +1,83 @@
# 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
-
-This module will allow upscaling of existing videos to higher resolutions such as:
+The goal of this module is to let users upscale existing videos to standardized modern resolutions such as:
- 720p (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 --scale 1920x1080
-```
Optional parameters:
-```
---scale Set explicit resolution
---filter Choose scaling filter (lanczos, bicubic, spline36)
---hevc Encode using H.265 for smaller output
---keep-audio Copy original audio stream without re-encoding
-```
+--scale Specify custom resolution
+--filter 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
----
+------------------------------------------------------------
+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:**
-- Input: 960×540 → Output: 1280×720
-- Input: 1280×720 → Output: 1920×1080
+The tool will retain the same aspect ratio and avoid unnecessary stretching or cropping.
----
+------------------------------------------------------------
+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 \
--c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k output_1080p.mp4
-```
+------------------------------------------------------------
+Planned Features
+------------------------------------------------------------
-**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.
+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
----
+------------------------------------------------------------
+Example Future Commands
+------------------------------------------------------------
-## Planned Features
+Upscale to 1080p using default settings:
+video-tools upscale-video "movie.mp4" "movie_1080p.mp4"
-| Feature | Status |
-|----------|--------|
-| FFmpeg scaler (`lanczos`) | 🔜 Planned |
-| ML-based upscaling (Real-ESRGAN / waifu2x) | 🚧 Research |
-| Auto-resolution detection | 🔜 Planned |
-| GPU acceleration support | 🔜 Planned |
-| Configurable presets | 🔜 Planned |
+Upscale to 4K using HEVC and Lanczos filter:
+video-tools upscale-video "movie.mp4" "movie_4k.mp4" --scale 3840x2160 --hevc --filter lanczos
----
+Copy original audio without re-encoding:
+video-tools upscale-video "documentary.mp4" "documentary_upscaled.mp4" --keep-audio
+------------------------------------------------------------
End of File