VideoTools/docs/CLI_Functions.md

docs/CLI_Functions.md

CLI Function Reference (v0.1.0)

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

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

---

Command Details

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>

Example

video-tools convert-single \
"/run/media/user/Linux/MyData/Videos/Example Collection/Example Movie Part1.avi" \
"Example Movie.mp4"

Output

/home/user/Videos/Example Movie.mp4

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.

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.

---

2. convert-multiple

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

Usage

video-tools convert-multiple <input1> <input2> ... <output.mp4>

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.
• 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 video discs, episodes, or segmented clips.
• When creating a single playback file from multiple source files.

---

Return Codes

Code	Meaning
0	Success
1	Invalid syntax or missing arguments
2	FFmpeg execution error

---

Common Issues

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

---

Planned Additions

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

---

Technical Summary

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.

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.

---

End of File