--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/third_party/ffmpeg/README.md	Sun Jan 25 10:44:04 2026 -0800
@@ -0,0 +1,75 @@
+# ffmpeg
+
+FFmpeg wrapper for Bazel projects.
+
+## Prerequisites
+
+FFmpeg must be installed on the system:
+
+```bash
+# Ubuntu/Debian
+sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev
+
+# macOS
+brew install ffmpeg
+
+# Arch Linux
+sudo pacman -S ffmpeg
+```
+
+## Libraries
+
+### ffmpeg_cli
+
+Shells out to the `ffmpeg` and `ffprobe` command-line tools. This is the recommended approach for most projects as it's simpler and doesn't require linking against FFmpeg libraries.
+
+```starlark
+deps = ["//third_party/ffmpeg:ffmpeg_cli"]
+```
+
+```c
+#include "third_party/ffmpeg/ffmpeg_cli.h"
+
+// Convert image to WebP
+ImageConvertOpts opts = ffmpeg_image_opts_default();
+opts.quality = 85;
+ffmpeg_image_to_webp("input.jpg", "output.webp", &opts);
+
+// Convert video to HLS
+HlsConvertOpts hls_opts = ffmpeg_hls_opts_default();
+ffmpeg_video_to_hls("input.mp4", "./output", "video", &hls_opts);
+```
+
+### ffmpeg (library)
+
+Links against FFmpeg libraries directly. Use this when you need low-level access to FFmpeg's encoding/decoding APIs.
+
+```starlark
+deps = ["//third_party/ffmpeg:ffmpeg"]
+```
+
+## API
+
+### Image Conversion
+
+```c
+FfmpegResult ffmpeg_image_to_webp(const char* input, const char* output, ImageConvertOpts* opts);
+```
+
+### Video to HLS
+
+```c
+FfmpegResult ffmpeg_video_to_hls(const char* input, const char* output_dir, const char* name, HlsConvertOpts* opts);
+```
+
+### Video Thumbnail
+
+```c
+FfmpegResult ffmpeg_video_thumbnail(const char* input, const char* output, int timestamp_seconds);
+```
+
+### Duration
+
+```c
+FfmpegResult ffmpeg_get_duration(const char* input, double* duration_out);
+```