Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: added most commong use case examples to readme #12

Merged
merged 2 commits into from
Feb 4, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,13 @@ files quickly and efficiently.

Because it uses ffmpeg under the hood, it supports any media file processing that ffmpeg can handle.

1. [Installation](#installation)
2. [Usage](#usage)
- [Practical examples](#more-practical-examples)
3. [Requirements](#requirements)
4. [All available options](#available-options)
5. [License](#license)

### Installation

#### [Homebrew](https://brew.sh) (macOS / Linux)
Expand Down Expand Up @@ -75,6 +82,83 @@ changing the file extension to `.mp4` while processing 4 files in parallel.
For more info on the `-o` syntax, run `ffzap --help`. For more ffmpeg options,
visit [ffmpeg's documentation](https://ffmpeg.org/ffmpeg.html).

#### More practical examples:

<details>
<summary>Re-encode multiple videos to H265 and the audio to opus</summary>

```bash
ffzap --input-file files.txt -f "-c:v libx265 -preset medium -crf 23 -c:a libopus -b:a 128k" -o "Output/{{name}}.mp4" -t 2
```

Keypoints:
- use `--input-file` to pass a list of file names to process
- re-encode the video to H265 using `-c:v libx265`
- `-preset medium` to balance out speed and file size
- `-crf 23` to achieve good quality with reasonable file size
- re-encode the audio to opus using `-c:a libopus`
- `-b:a 128k` sets the audio bitrate to 128k for a good trade-off between file size and audio quality
- `-t 2` runs two ffmpeg processes simultaneously to re-encode two files at once
- adjust this number according to your system specs. Most system should be able to handle two instances comfortably

</details>

---

<details>
<summary>Convert PNG images to JPG</summary>

```bash
ffzap --input-file files.txt -f "-c:v mjpeg -q:v 2" -o "Output/{{name}}.jpg" -t 6
```

Keypoints:
- use `--input-file` to pass a list of file names to process
- convert the image to JPG using `-c:v mjpeg`
- `-q:v 2` to set very high quality
- `-t 6` runs six processes in parallel, converting six files at once
- adjust this number according to your system specs. Six shouldn't be too taxing on a modern CPU

</details>

---

<details>
<summary>Add a watermark to multiple videos</summary>

```bash
ffzap --input-file files.txt -f "-i watermark.png -filter_complex [1]format=rgba,lut=a=val*0.3[watermark];[0][watermark]overlay=(main_w-overlay_w)/2:(main_h-overlay_h)/2 -c:a copy" -o "{{name}}_watermark.mp4" -t 2
```
(Note that this command may not work in Windows Powershell as it requires a different escaping format)

Keypoints:
- use `--input-file` to pass a list of file names to process (these are the files the watermark gets added to)
- select to watermark file with `-i watermark.png` **inside** `-f`
- `-filter_complex` applies the watermark with 70% opacity to the center of each video
- `-c:a copy` copies the audio
- `-t 2` processes two files in parallel
- adjust this number according to your system specs. Two should be good on most modern systems

</details>

---

<details>
<summary>Resize multiple videos</summary>

```bash
ffzap --input-file files.txt -f "-vf scale=1280:720 -c:a copy" -o "{{name}}_resized.mp4" -t 2
```

Keypoints:
- use `--input-file` to pass a list of file names to process
- `-vf scale=1280:720` sets the video resolution to HD
- `-c:a copy` copies the audio
- `-t 2` processes two files in parallel
- adjust this number according to your system specs. Two should be good on most modern systems

</details>

### Requirements

- a working installation of [ffmpeg](https://ffmpeg.org/download.html)
Expand Down