3.9 KiB
3.9 KiB
CLI Function Reference
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.
Command Details
1. convert-single
Purpose
Convert a single input video file into an MP4 with 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.
- Ensures output uses the H.264 codec (libx264) and AAC audio.
- Rebuilds timestamps to avoid sync issues.
- Adds
+faststartflag for quicker playback when streamed or loaded in players.
When to use
- When you want to upgrade old videos to a more efficient format.
- When a single video won’t play on mobile or modern devices.
- To reduce file size without losing 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>
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
- Reads all listed files in order and merges them seamlessly.
- Each input is re-encoded using the same H.264/AAC settings.
- Temporary file list is automatically created and deleted.
- Logs detailed FFmpeg progress to the terminal.
When to use
- When combining multi-part video discs, episodes, or scene splits.
- When creating a single playable MP4 from segmented source material.
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 +genptsregenerates 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