Leak_Technologies/VideoTools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e340e56dc8
VideoTools/docs/CLI_Functions.md

6.0 KiB
Raw Blame History

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 <output.mp4> Description: Converts a single video to MP4.

Command: convert-multiple Syntax: video-tools convert-multiple ... <output.mp4> 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 <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.
  1. convert-multiple

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

Usage: video-tools convert-multiple ... <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.
  1. 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