持续维护最后验证：2026-09-20

`~/.local/bin` 媒体工具箱

一组基于 fzf + ffmpeg 的命令行媒体处理脚本，编码参数数据库移植自 FFmpegFreeUI (3FUI) v6。

设计目标

所有媒体脚本使用 Bash，并优先采用 set -euo pipefail。
共享逻辑集中在 fzf-fftools-lib，避免重复实现选择器、编码器、日志和预览。
文件名统一按 Shell-safe 方式传递，支持空格与中文路径。
输出避免意外覆盖，任务与错误日志写入 XDG state 目录。
fzf 是交互入口；非交互参数优先提供给脚本自动化使用。

依赖

必备：bash ffmpeg ffprobe fzf fd

按需：whisper-cli、ollama、chafa、yt-dlp、libplacebo/zscale。

运行 fzf-fftools 主菜单中的环境诊断可检查依赖和编码器。

核心组件

组件	作用
`fzf-fftools`	总入口与环境诊断
`fzf-fftools-lib`	文件选择、编码器、滤镜、日志、队列、预览等共享库
`fzf-preview-video`	fzf 视频/图片/音频预览与缓存
`fzf-ffmpeg-batch`	批量编码与可恢复队列
`fzf-ffmpeg-preset`	内置与用户压制预设

工具分类

转码 / 编码

fzf-convert-media、fzf-ffmpeg-batch、fzf-ffmpeg-builder、fzf-ffmpeg-color、fzf-ffmpeg-preset、fzf-speed-video、fzf-target-size、fzf-trim-video

字幕

fzf-generate-subs、fzf-translate-subs、fzf-burn-subs、fzf-shift-subs、fzf-convert-subs

音频 / 图片

fzf-audio-tools、fzf-image-batch、fzf-add-watermark、fzf-mute-video、fzf-video-to-gif

合并 / 混流 / 抽流

fzf-merge-av、fzf-concat-video、fzf-mux-media、fzf-extract-streams、fzf-swap-audio

质量 / 分析

fzf-quality-eval、fzf-validate-media、fzf-media-report、fzf-screenshot-video

其他

fzf-download、fzf-pkg、battery-monitor、backlight、set-wallpapers、omarchy-show-done

Fish 集成

所有用户可直接调用的 fzf-* 工具都有对应的 Fish completion，文件位于 ~/.config/fish/completions/。

已清理已经合并/删除的旧 completion：fzf-compress-video、fzf-extract-audio。

fzf-fftools-lib、fzf-preview、fzf-preview-video 是内部库/预览回调，不提供普通命令补全。

状态与日志

运行日志：~/.local/state/fzf-fftools/logs/
任务日志：~/.local/state/fzf-fftools/tasks.log
编码队列：~/.local/state/fzf-fftools/queue.tsv
预览缓存：~/.cache/fzf-media-preview
字体缓存：~/.cache/fzf-fftools/fonts.tsv

用户预设

用户预设位于 ~/.config/fzf-fftools/presets/*.preset，格式示例：

desc=我的压制方案
args=-c:v libx265 -preset slow -crf 24 -pix_fmt yuv420p10le -c:a aac -b:a 192k
passes=1
ext=mp4
decode=

环境变量

变量	说明
`FZF_SUBTITLE_FONT_SIZE` / `FZF_SUBTITLE_FONT_NAME` / `FZF_SUBTITLE_FONTS_DIR`	字幕默认样式
`FZF_TRANSLATE_MODEL` / `FZF_TRANSLATE_BATCH`	Ollama 翻译模型与批量大小
`FZF_VMAF_THREADS` / `FZF_VMAF_MODEL` / `FZF_VMAF_POOL`	VMAF 线程、模型和 pooling