# 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