141 lines
3.9 KiB
Markdown
141 lines
3.9 KiB
Markdown
# 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**
|
||
```bash
|
||
video-tools convert-single <input> <output.mp4>
|
||
```
|
||
|
||
**Example**
|
||
```bash
|
||
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 `+faststart` flag 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**
|
||
```bash
|
||
video-tools convert-multiple <input1> <input2> ... <output.mp4>
|
||
```
|
||
|
||
**Example**
|
||
```bash
|
||
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 +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
|