144 lines
4.1 KiB
Markdown
144 lines
4.1 KiB
Markdown
# 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**
|
|
```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.
|
|
- 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**
|
|
```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**
|
|
- 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
|