VideoTools/docs/CLI_Functions.md

# docs/CLI_Functions.md
CLI Function Reference (v0.1.2)

This document describes the available commands in video-tools.sh.
Each command can be run from any terminal once the tool is installed.

------------------------------------------------------------
Quick Reference
------------------------------------------------------------

Command: convert-single
Syntax: video-tools convert-single <input> <output.mp4>
Description: Converts a single video to MP4.

Command: convert-multiple
Syntax: video-tools convert-multiple <input1> <input2> ... <output.mp4>
Description: Combines multiple video files into one MP4.

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.

All outputs are saved in your default ~/Videos folder, unless overridden in config/config.json.

------------------------------------------------------------
1. convert-single
------------------------------------------------------------

Purpose:
Convert a single input video file into an MP4 using modern compression and audio standards.

Usage:
video-tools convert-single <input> <output.mp4> [--hi-rate | --portable]

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

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.
- Displays detailed FFmpeg progress and conversion summary.
- Creates timestamped logs in ~/.local/share/video-tools/logs/.

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

Purpose:
Combine several clips or discs into one MP4 output file.

Usage:
video-tools convert-multiple <input1> <input2> ... <output.mp4> [--hi-rate | --portable]

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" \
"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/.

When to Use:
- To combine multi-part discs, episodes, or clips.
- When producing a single continuous playback file.

------------------------------------------------------------
3. videoinfo
------------------------------------------------------------

Purpose:
Display detailed technical information about a video file.

Usage:
video-tools videoinfo <file> [--verbose]

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.

------------------------------------------------------------
Return Codes
------------------------------------------------------------

0 - Success
1 - Invalid syntax or missing arguments
2 - FFmpeg or ffprobe execution error

------------------------------------------------------------
Common Issues
------------------------------------------------------------

Symptom: Conversion fails immediately
Cause: Input path invalid
Fix: Ensure full path is correct and quoted properly.

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/.

------------------------------------------------------------
Planned Additions
------------------------------------------------------------

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.

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