GifHorse — 对话搜索与 GIF 制作工具

通过搜索视频中的对话并添加带时间戳的字幕，从您的视频库中快速生成反应类 GIF。

GifHorse 的功能

1. 视频转录 —— 通过下载在线字幕、使用本地 .srt 文件或 Whisper AI 自动提取带时间戳的对话文本
2. 对话搜索 —— 瞬间在全部视频库中定位指定台词或引述
3. 片段预览 —— 在生成 GIF 前，精确查看将被截取的画面内容
4. GIF 生成 —— 输出带精准同步字幕的 GIF，支持可选水印

安装配置

首次安装

1. 安装 gifhorse（点击上方安装按钮）
2. 安装 FFmpeg-full（用于字幕渲染，点击上方安装按钮）
3. 对您的视频库执行转录（自动下载字幕）：

cd ~/gifhorse && source venv/bin/activate
gifhorse transcribe ~/Movies

所有 gifhorse 命令必须在虚拟环境中运行。您可通过以下命令激活环境：

cd ~/gifhorse && source venv/bin/activate

或使用快捷激活脚本：

source ~/gifhorse/activate.sh

可用命令

视频转录

从视频中提取对话文本（每段视频仅需执行一次）：

# 默认模式：从在线服务自动下载字幕（速度快，推荐）
gifhorse transcribe /path/to/videos

# 仅使用本地 .srt 文件（不下载、不调用 Whisper）
gifhorse transcribe /path/to/videos --use-subtitles

# 使用 Whisper AI（速度较慢，但适用于任意视频）
gifhorse transcribe /path/to/video.mp4 --use-whisper

# 强制重新转录数据库中已存在的视频
gifhorse transcribe /path/to/videos --force

仅下载字幕文件

下载 .srt 字幕文件，但不存入数据库：

gifhorse fetch-subtitles /path/to/videos
gifhorse fetch-subtitles /path/to/videos --skip-existing

对话搜索

在全部视频库中查找台词：

# 基础搜索
gifhorse search "令人难忘的台词"

# 搜索时包含上下文（前后各 N 行对话）
gifhorse search "令人难忘的台词" --context 2

# 显示全部匹配结果（不限数量）
gifhorse search "令人难忘的台词" --all

# 自定义结果数量（默认为 100 条）
gifhorse search "令人难忘的台词" --limit 50

生成前预览

精确查看将被截取的内容：

gifhorse preview "令人难忘的台词" 1
gifhorse preview "台词" 1 --include-before 1 --include-after 1

生成 GIF

生成带字幕的 GIF：

# 基础模式（文件名自动基于台词生成，保存至 exports/ 目录）
gifhorse create "令人难忘的台词" 1

# 指定输出路径
gifhorse create "令人难忘的台词" 1 -o reaction.gif

# 高质量输出（适用于社交媒体）
gifhorse create "台词" 1 --width 720 --fps 24 --quality high

# 包含完整对话上下文
gifhorse create "台词" 1 --include-before 2 --include-after 1

# 替换字幕中的特定词语（可重复使用；段落编号来自 preview 输出）
gifhorse create "人类的时代" 1 --include-after 1 
  -s 1 "men" "standardized software" 
  -s 2 "orc" "custom applications"

# 干净替换（无删除线效果）
gifhorse create "台词" 1 -r 1 "旧词" "新词"

# 生成后通过 iMessage 发送
gifhorse create "台词" 1 --send
gifhorse create "台词" 1 --send-to "+15551234567"

数据库管理

# 按路径通配符移除视频（支持 SQL LIKE 语法）
gifhorse remove "%Adventure Time%"
gifhorse remove "%S01%" --yes

# 检查目录下字幕状态
gifhorse subtitle-status ~/Videos
gifhorse subtitle-status ~/Videos --missing-only

状态检查

# 查看转录统计信息
gifhorse stats

# 列出所有已完成转录的视频
gifhorse list

配置管理

# 设置 iMessage 发送手机号
gifhorse config --set-phone "+15551234567"

# 查看当前配置
gifhorse config --show

时间控制选项

精细控制截取范围：

• --include-before N —— 包含匹配台词前 N 段对话
• --include-after N —— 包含匹配台词后 N 段对话
• --padding-before SECS —— 在对话开始前增加缓冲秒数（默认：1.0）
• --padding-after SECS —— 在对话结束后增加缓冲秒数（默认：1.0）
• --start-offset SECS —— 手动调整起始时间（可为负值）
• --end-offset SECS —— 手动调整结束时间（可为负值）

重要提示： 若需截取对话之后的反应镜头，请使用 --padding-after 而非 --include-after。--include-after 将捕获至下一段对话开始前的所有画面（可能长达 30 秒以上！）。

质量控制选项

• --quality low|medium|high —— 调整调色板质量（影响文件大小）
• --fps N —— 帧率（默认：15，推荐 24 实现更流畅动画）
• --width N —— 输出宽度（像素，默认：480，推荐 720 实现高清效果）

字幕控制选项

• -s, --sub NUM OLD NEW —— 替换指定段落中的词语（可重复使用）。被替换词以红色删除线显示，新词以红色显示。段落编号由 preview 命令展示。
• -r, --replace NUM OLD NEW —— 干净替换词语（无删除线效果）。可重复使用。
• --no-subtitles —— 生成不含字幕叠加层的 GIF

输出说明

• 默认输出文件名根据台词自动生成（例如：i_dont_think_so.gif），保存至 exports/ 目录
• 使用 -o PATH 可覆盖默认路径；若文件名冲突，则自动追加 _2、_3 等后缀

iMessage 支持

• --send —— 将生成的 GIF 通过 iMessage 发送给配置的手机号（仅 macOS 支持）
• --send-to NUMBER —— 发送给指定手机号（覆盖配置中设置的号码）

注意： 所有生成的 GIF 均自动在右下角嵌入细微的 “gifhorse” 水印。

常用工作流示例

快速制作反应 GIF

gifhorse search "完美"
gifhorse create "完美" 1 --padding-after 2.0

完整对话片段

gifhorse search "关键词组"
gifhorse preview "关键词组" 1 --include-before 2 --include-after 1
gifhorse create "关键词组" 1 --include-before 2 --include-after 1

带词语替换的梗图（Meme）

gifhorse preview "人类的时代" 1 --include-after 1
gifhorse create "人类的时代" 1 --include-after 1 
  -s 1 "men" "standardized software" 
  -s 2 "orc" "custom applications"

适配 Twitter/X 的高质量 GIF

gifhorse create "台词" 1 --width 720 --fps 24 --quality high -o tweet.gif

含对话后反应镜头的场景

gifhorse create "令人难忘的台词" 1 --padding-after 3.0

生成并经 iMessage 发送

gifhorse config --set-phone "+15551234567"
gifhorse create "台词" 1 --send

技巧与建议

1. 务必先预览 —— 使用 preview 命令确认时间点无误后再生成 GIF
2. 默认自动下载字幕 —— 直接运行 gifhorse transcribe 即可自动获取字幕
3. 关注文件体积 —— 高质量 + 长时长 = 大文件（20 秒 GIF 可达 20 MB 以上）
4. 区分 padding 与 include —— 制作反应类 GIF 时，请使用 --padding-after 而非 --include-after
5. 带上下文搜索 —— 添加 --context 2 可同时查看匹配台词前后的对话内容
6. 强制重转录 —— 若获得更准确的字幕文件，可用 --force 更新已有转录结果
7. 检查字幕覆盖率 —— 使用 subtitle-status 快速识别哪些视频尚未拥有字幕

文件体积参考指南

• 低质量、10 秒、360p： ~1–2 MB
• 中等质量、10 秒、480p： ~3–5 MB
• 高质量、20 秒、720p： ~20+ MB

常见问题排查

“command not found: gifhorse”

请先激活虚拟环境：

cd ~/gifhorse && source venv/bin/activate

字幕渲染失败

请确保已安装 FFmpeg-full：

brew install ffmpeg-full

视频文件未找到

数据库中存储的是绝对路径。若您在完成转录后移动了视频文件，请在新位置重新执行转录。

网络共享支持

GifHorse 支持挂载在网络上的视频文件：

# 挂载网络共享（macOS）
open "smb://server-ip/share-name"

# 对网络共享中的视频执行转录
gifhorse transcribe "/Volumes/server-ip/Movies"

适用场景

当用户希望执行以下操作时，请调用 gifhorse：

• 在其视频库中搜索台词或引述
• 从电影或电视剧中制作反应类 GIF
• 制作带词语替换的梗图（Meme GIF）
• 为视频片段添加字幕
• 对视频进行转录，以便支持全文本搜索
• 在生成 GIF 前预览最终效果
• 通过 iMessage 发送 GIF
• 从数据库中移除视频条目
• 检查其视频收藏集的字幕覆盖状态

进一步了解

• GitHub 仓库： https://github.com/Coyote-git/gifhorse
• 使用指南： https://github.com/Coyote-git/gifhorse/blob/main/USAGE_GUIDE.md
• 路线图： https://github.com/Coyote-git/gifhorse/blob/main/ROADMAP.md

许可证

MIT