# 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 Description: Converts a single video to MP4. Command: convert-multiple Syntax: video-tools convert-multiple ... Description: Combines multiple video files into one MP4. 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. 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 [--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 ... [--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 [--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