From f598ed66ede36d839631ef73062fad4e54a29b73 Mon Sep 17 00:00:00 2001
From: Sandor Semsey <sandor@es-progress.hu>
Date: Wed, 3 Dec 2025 02:45:08 +0100
Subject: [PATCH] lib: add ffmpeg audio/video library

---
 docs/lib/ffmpeg.md | 38 ++++++++++++++++++++++++++++++++++++++
 docs/nav.md        |  1 +
 lib/_loader.sh     |  1 +
 lib/ffmpeg.sh      | 39 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 79 insertions(+)
 create mode 100644 docs/lib/ffmpeg.md
 create mode 100644 lib/ffmpeg.sh

diff --git a/docs/lib/ffmpeg.md b/docs/lib/ffmpeg.md
new file mode 100644
index 0000000..16a546b
--- /dev/null
+++ b/docs/lib/ffmpeg.md
@@ -0,0 +1,38 @@
+# ffmpeg
+
+Wrapper for the `ffmpeg` tool.
+
+---
+
+## fffmpeg-cut
+
+Cut a shot from a video file. The wrapper passes any ffmpeg timing/options you provide.
+
+**Usage**
+
+```
+fffmpeg-cut INPUT_FILE OUTPUT_FILE TIMING_POSITIONS
+
+Params:
+INPUT_FILE         Path to input video file
+OUTPUT_FILE        Path to output video file
+TIMING_POSITIONS   Time positions to specify the start and end of cutted segment
+                   Example to extract 10s from 1min: -ss 60 -t 10
+                                                 or: -ss 00:01:00 -t 00:00:10
+```
+
+---
+
+## fffmpeg-join
+
+Join multiple video files using `ffmpeg` concat demuxer.
+
+**Usage**
+
+```
+fffmpeg-join OUTPUT_FILE INPUT_FILE...
+
+Params:
+OUTPUT_FILE        Path to resulting joined file
+INPUT_FILE         One or more input files to concatenate
+```
diff --git a/docs/nav.md b/docs/nav.md
index 3a3aaf8..60c3117 100644
--- a/docs/nav.md
+++ b/docs/nav.md
@@ -8,6 +8,7 @@
         - [Database](lib/db.md)
         - [Dev Tools](lib/dev.md)
         - [Error Handling](lib/error.md)
+        - [FFmpeg](lib/ffmpeg.md)
         - [Files](lib/files.md)
         - [Git](lib/git.md)
         - [GitHub CLI](lib/github.md)
diff --git a/lib/_loader.sh b/lib/_loader.sh
index 87b4cee..f89e7ab 100644
--- a/lib/_loader.sh
+++ b/lib/_loader.sh
@@ -14,6 +14,7 @@ base_dir=$(cd "$(dirname "${path_self}")" >/dev/null 2>&1 && pwd)
 . "${base_dir}/db.sh"
 . "${base_dir}/dev.sh"
 . "${base_dir}/error.sh"
+. "${base_dir}/ffmpeg.sh"
 . "${base_dir}/files.sh"
 . "${base_dir}/git.sh"
 . "${base_dir}/github.sh"
diff --git a/lib/ffmpeg.sh b/lib/ffmpeg.sh
new file mode 100644
index 0000000..ff0724b
--- /dev/null
+++ b/lib/ffmpeg.sh
@@ -0,0 +1,39 @@
+# shellcheck shell=bash
+##########################
+## Audio/Video Library  ##
+##                      ##
+## Wrapper for 'ffmpeg' ##
+##########################
+
+## Cut a video file
+##
+## @param    $1  Input file
+## @param    $2  Output file
+## @param    $@  Positions
+##               -ss START_TIME [-t DURATION]
+#############################################
+fffmpeg-cut() {
+    local input_file="${1:?Input file missing}"
+    local output_file="${2:?Output file missing}"
+    shift 2
+    ffmpeg -i "${input_file}" "${@}" -preset veryfast "${output_file}"
+}
+
+## Join multiple video files
+##
+## @param    $1  Output file
+## @param    $@  Input files
+############################
+fffmpeg-join() {
+    local output_file="${1:?Output file missing}"
+    local temp_file input_file
+    temp_file=$(mktemp)
+    shift
+
+    for input_file in "${@}"; do
+        input_file=$(realpath "${input_file}")
+        echo "file '${input_file}'" >> "${temp_file}"
+    done
+
+    ffmpeg -f concat -safe 0 -i "${temp_file}" -c copy "${output_file}"
+}