video-to-gif

视频转 GIF 工坊

将视频片段转换为高品质、经过优化的 GIF，适用于社交媒体、文档、教程和演示文稿。支持精确控制时间、添加文字叠加、应用特效，以及智能优化文件大小。

核心功能

• 片段选择：从视频中提取特定时间范围
• 速度控制：慢动作、加速或倒放
• 裁剪：调整大小并裁剪为任意尺寸
• 文字叠加：添加字幕、标题或水印
• 特效：滤镜、淡入淡出、颜色调整
• 优化：针对目标文件大小进行智能压缩
• 批量处理：一次转换多个片段

快速开始

from scripts.gif_workshop import GifWorkshop

# Basic conversion
workshop = GifWorkshop("video.mp4")
workshop.to_gif("output.gif")

# With options
workshop = GifWorkshop("video.mp4")
workshop.clip(start=5, end=10)          # 5-10 seconds
workshop.resize(width=480)               # Resize to 480px wide
workshop.set_fps(15)                     # 15 frames per second
workshop.optimize(max_size_kb=500)       # Max 500KB
workshop.to_gif("output.gif")

核心工作流

1. 加载视频

from scripts.gif_workshop import GifWorkshop

# From file
workshop = GifWorkshop("video.mp4")

# With initial settings
workshop = GifWorkshop("video.mp4", fps=15, width=480)

2. 选择片段范围

# By time (seconds)
workshop.clip(start=5, end=15)  # 5s to 15s

# By time string
workshop.clip(start="00:01:30", end="00:01:45")  # 1:30 to 1:45

# From start or to end
workshop.clip(start=10)  # From 10s to end
workshop.clip(end=5)     # First 5 seconds

# Multiple clips
workshop.clip_multi([
    (0, 3),
    (10, 15),
    (20, 25)
])  # Concatenates clips

3. 调整速度

# Speed up
workshop.speed(2.0)  # 2x faster

# Slow motion
workshop.speed(0.5)  # Half speed

# Reverse
workshop.reverse()

# Boomerang effect (forward then reverse)
workshop.boomerang()

4. 调整大小并裁剪

# Resize by width (maintain aspect)
workshop.resize(width=480)

# Resize by height
workshop.resize(height=360)

# Exact dimensions
workshop.resize(width=480, height=360)

# Crop to region
workshop.crop(x=100, y=50, width=400, height=300)

# Crop to aspect ratio
workshop.crop_to_aspect(16, 9)  # 16:9
workshop.crop_to_aspect(1, 1)   # Square

5. 添加文字

# Simple text overlay
workshop.add_text(
    "Hello World!",
    position='bottom',
    fontsize=24,
    color='white'
)

# Text with timing
workshop.add_text(
    "Watch this!",
    position='top',
    start_time=0,
    end_time=3  # Show for first 3 seconds
)

# Multiple text overlays
workshop.add_text("Step 1", position='top-left', start_time=0, end_time=2)
workshop.add_text("Step 2", position='top-left', start_time=2, end_time=4)

# Caption bar
workshop.add_caption_bar(
    "This is a caption",
    position='bottom',
    background='black',
    padding=10
)

6. 应用特效

# Color filters
workshop.filter('grayscale')
workshop.filter('sepia')

# Adjustments
workshop.adjust(brightness=0.1, contrast=0.2)

# Fade in/out
workshop.fade_in(duration=0.5)
workshop.fade_out(duration=0.5)

# Blur
workshop.blur(intensity=2)

7. 优化文件大小

# Target file size
workshop.optimize(max_size_kb=500)

# Quality settings
workshop.optimize(
    quality='medium',  # 'low', 'medium', 'high'
    colors=128         # Color palette size (2-256)
)

# Manual FPS control
workshop.set_fps(10)  # Lower FPS = smaller file

# Lossy compression
workshop.optimize(lossy=80)  # 0-100, higher = more compression

8. 导出

# Basic export
workshop.to_gif("output.gif")

# With options
workshop.to_gif(
    "output.gif",
    optimize=True,
    colors=256,
    loop=0  # 0 = infinite loop, 1+ = loop count
)

# Export as video (for comparison)
workshop.to_video("output.mp4")

# Export frames
workshop.export_frames("frames/", format='png')

预设

# Social media presets
workshop.preset('twitter')     # 512px wide, 5MB max
workshop.preset('discord')     # 256px, 8MB max
workshop.preset('slack')       # 480px, 5MB max
workshop.preset('reddit')      # 720px, optimized

# Quality presets
workshop.preset('high')        # High quality, larger file
workshop.preset('medium')      # Balanced
workshop.preset('low')         # Small file, lower quality

# Special presets
workshop.preset('thumbnail')   # Small preview GIF
workshop.preset('reaction')    # Reaction GIF (small, fast)

文字位置选项

位置	描述
'top'	顶部居中
'bottom'	底部居中
'center'	画面中央
'top-left'	左上角
'top-right'	右上角
'bottom-left'	左下角
'bottom-right'	右下角

高级功能

提取帧

# Get best frame (thumbnail)
best_frame = workshop.get_best_frame()
best_frame.save("thumbnail.png")

# Extract frame at time
frame = workshop.get_frame_at(5.5)  # Frame at 5.5 seconds
frame.save("frame.png")

# Extract all frames
workshop.export_frames("frames/", format='png')

视频信息

info = workshop.get_info()
print(f"Duration: {info['duration']} seconds")
print(f"Size: {info['width']}x{info['height']}")
print(f"FPS: {info['fps']}")
print(f"Frames: {info['frame_count']}")

自定义滤镜

# Apply custom function to each frame
def custom_filter(frame):
    # frame is a PIL Image
    return frame.rotate(5)

workshop.apply_filter(custom_filter)

拼接视频

# Join multiple clips
workshop.concat([
    "intro.mp4",
    "main.mp4",
    "outro.mp4"
])

CLI 用法

# Basic conversion
python gif_workshop.py video.mp4 -o output.gif

# With clip selection
python gif_workshop.py video.mp4 -o output.gif --start 5 --end 15

# With options
python gif_workshop.py video.mp4 -o output.gif \
    --width 480 \
    --fps 15 \
    --speed 1.5 \
    --max-size 500

# With text
python gif_workshop.py video.mp4 -o output.gif \
    --text "Hello World" \
    --text-position bottom

# Apply preset
python gif_workshop.py video.mp4 -o output.gif --preset twitter

优化技巧

减小文件大小

1. 降低尺寸：尺寸越小，文件也会小得多
2. 降低 FPS：通常 10-15 FPS 就足够
3. 限制颜色数量：64-128 种颜色通常效果不错
4. 缩短时长：每增加一秒，文件大小都会显著增加
5. 使用有损压缩：质量略有损失，但文件大小会大幅减少

提升质量

1. 从高品质源文件开始：输入质量越好，输出质量越好
2. 使用 256 种颜色：使用最大调色板
3. 提高 FPS：使用 24-30 FPS，让动作更流畅
4. 避免过度压缩：将有损压缩值保持在 90 以上

文件大小与质量预设

预设	宽度	FPS	颜色	使用场景
reaction	256px	10	64	快速反应
low	320px	12	128	基本分享
medium	480px	15	256	通用场景
high	640px	20	256	高品质
max	原始	24	256	最佳品质

错误处理

from scripts.gif_workshop import GifWorkshop, GifError

try:
    workshop = GifWorkshop("video.mp4")
    workshop.clip(start=0, end=100)  # May exceed video length
    workshop.to_gif("output.gif")
except GifError as e:
    print(f"Error: {e}")
except FileNotFoundError:
    print("Video file not found")

支持的格式

输入（视频）

• MP4、MOV、AVI、MKV、WebM、FLV、WMV

输出

• GIF（动画）
• MP4（用于比较）
• PNG/JPEG（帧）

依赖项

moviepy>=1.0.3
Pillow>=10.0.0
imageio>=2.31.0
numpy>=1.24.0

限制

• GIF 的最大实用文件大小：约 20-30MB
• 时长过长的 GIF 会变得难以使用
• 复杂场景可能出现色带
• GIF 格式不支持音频