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

2025-11-05 15:39:15 -05:00
7 changed files with 480 additions and 331 deletions
--- a/28
+++ b/28
@ -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
+# ------------------------
--- 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"
+    }
+  }
 }
--- 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
--- 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 <input> <output.mp4>
+Description: Converts a single video to 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: convert-multiple
+Syntax: video-tools convert-multiple <input1> <input2> ... <output.mp4>
+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 <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.

-**Usage**
-```bash
-video-tools convert-single <input> <output.mp4>
-```
+Usage:
+video-tools convert-single <input> <output.mp4> [--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 <input1> <input2> ... <output.mp4>
-```
+Usage:
+video-tools convert-multiple <input1> <input2> ... <output.mp4> [--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 <file> [--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
--- 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
--- 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
--- 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 <input> <output.mp4> --scale 1920x1080
-```

 Optional parameters:
-```
--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
-```
+--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

---
+------------------------------------------------------------
+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