v0.1.2 - Documentation standardization, version sync, config update
This commit is contained in:
parent
b8c07a4247
commit
e340e56dc8
28
Makefile
28
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
|
||||
# ------------------------
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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**
|
||||
|
|
@ -58,5 +110,4 @@ This project adheres to [Semantic Versioning](https://semver.org/).
|
|||
|
||||
---
|
||||
|
||||
|
||||
End of File
|
||||
|
|
|
|||
|
|
@ -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**
|
||||
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.
|
||||
- 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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
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
|
||||
|
|
|
|||
208
docs/README.md
208
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
|
||||
```
|
||||
|
||||
2. Make the script executable:
|
||||
```bash
|
||||
chmod +x video-tools.sh
|
||||
```
|
||||
|
||||
3. (Optional) Add it to PATH:
|
||||
```bash
|
||||
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
|
||||
|
|
|
|||
102
docs/Upscale.md
102
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user