# 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