video-to-gif

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Video to GIF Workshop

视频转GIF工具集（GifWorkshop）

Transform video clips into high-quality, optimized GIFs perfect for social media, documentation, tutorials, and presentations. Features precise timing control, text overlays, effects, and intelligent file size optimization.

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

Core Capabilities

核心功能

Clip Selection: Extract specific time ranges from videos
Speed Control: Slow motion, speed up, or reverse
Cropping: Resize and crop to any dimensions
Text Overlays: Add captions, titles, or watermarks
Effects: Filters, fades, color adjustments
Optimization: Smart compression for target file size
Batch Processing: Convert multiple clips at once

片段选择：从视频中提取特定时间范围的内容
速度调节：慢动作、加速或倒放
裁剪功能：调整尺寸和裁剪至任意规格
文本叠加：添加字幕、标题或水印
特效处理：滤镜、淡入淡出、色彩调整
优化功能：针对目标文件大小的智能压缩
批量处理：一次性转换多个片段

Quick Start

快速开始

python

from scripts.gif_workshop import GifWorkshop

python

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")

undefined

workshop = GifWorkshop("video.mp4") workshop.clip(start=5, end=10) # 5-10秒 workshop.resize(width=480) # 调整宽度至480像素 workshop.set_fps(15) # 每秒15帧 workshop.optimize(max_size_kb=500) # 最大500KB workshop.to_gif("output.gif")

undefined

Core Workflow

核心工作流程

1. Load Video

1. 加载视频

python

from scripts.gif_workshop import GifWorkshop

python

from scripts.gif_workshop import GifWorkshop

From file

从文件加载

workshop = GifWorkshop("video.mp4")

With initial settings

带初始设置加载

workshop = GifWorkshop("video.mp4", fps=15, width=480)

undefined

workshop = GifWorkshop("video.mp4", fps=15, width=480)

undefined

2. Select Clip Range

2. 选择片段范围

python

undefined

python

undefined

By time (seconds)

按时间（秒）选择

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

workshop.clip(start=5, end=15) # 5秒到15秒

By time string

按时间字符串选择

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

workshop.clip(start="00:01:30", end="00:01:45") # 1分30秒到1分45秒

From start or to end

从指定时间到结尾

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

workshop.clip(start=10) # 从10秒到结尾 workshop.clip(end=5) # 前5秒内容

Multiple clips

选择多个片段

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

undefined

workshop.clip_multi([ (0, 3), (10, 15), (20, 25) ]) # 拼接多个片段

undefined

3. Adjust Speed

3. 调整速度

python

undefined

python

undefined

Speed up

加速

workshop.speed(2.0) # 2x faster

workshop.speed(2.0) # 2倍速

Slow motion

慢动作

workshop.speed(0.5) # Half speed

workshop.speed(0.5) # 0.5倍速

Reverse

倒放

workshop.reverse()

Boomerang effect (forward then reverse)

回旋镖效果（正向播放后倒放）

workshop.boomerang()

undefined

workshop.boomerang()

undefined

4. Resize and Crop

4. 调整尺寸与裁剪

python

undefined

python

undefined

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

undefined

workshop.crop_to_aspect(16, 9) # 16:9 workshop.crop_to_aspect(1, 1) # 正方形

undefined

5. Add Text

5. 添加文本

python

undefined

python

undefined

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 )

workshop.add_text( "看这里！", position='top', start_time=0, end_time=3 # 前3秒显示 )

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)

workshop.add_text("步骤1", position='top-left', start_time=0, end_time=2) workshop.add_text("步骤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 )

undefined

workshop.add_caption_bar( "这是一段字幕", position='bottom', background='black', padding=10 )

undefined

6. Apply Effects

6. 应用特效

python

undefined

python

undefined

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)

undefined

workshop.blur(intensity=2)

undefined

7. Optimize for Size

7. 尺寸优化

python

undefined

python

undefined

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) )

workshop.optimize( quality='medium', # 'low', 'medium', 'high' colors=128 # 调色板大小（2-256） )

Manual FPS control

手动控制帧率

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

workshop.set_fps(10) # 帧率越低，文件越小

Lossy compression

有损压缩

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

undefined

workshop.optimize(lossy=80) # 0-100，数值越高压缩率越高

undefined

8. Export

8. 导出

python

undefined

python

undefined

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 )

workshop.to_gif( "output.gif", optimize=True, colors=256, loop=0 # 0 = 无限循环，1+ = 循环次数 )

Export as video (for comparison)

导出为视频（用于对比）

workshop.to_video("output.mp4")

Export frames

导出帧

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

undefined

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

undefined

Presets

预设配置

python

undefined

python

undefined

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

workshop.preset('twitter') # 宽度512像素，最大5MB workshop.preset('discord') # 256像素，最大8MB workshop.preset('slack') # 480像素，最大5MB workshop.preset('reddit') # 720像素，经过优化

Quality presets

质量预设

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

workshop.preset('high') # 高质量，文件较大 workshop.preset('medium') # 平衡质量与大小 workshop.preset('low') # 文件小，质量较低

Special presets

特殊预设

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

undefined

workshop.preset('thumbnail') # 小型预览GIF workshop.preset('reaction') # 反应式GIF（体积小，加载快）

undefined

Text Position Options

文本位置选项

Position	Description
`'top'`	Top center
`'bottom'`	Bottom center
`'center'`	Center of frame
`'top-left'`	Top left corner
`'top-right'`	Top right corner
`'bottom-left'`	Bottom left corner
`'bottom-right'`	Bottom right corner

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

Advanced Features

高级功能

Frame Extraction

帧提取

python

undefined

python

undefined

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")

frame = workshop.get_frame_at(5.5) # 5.5秒处的帧 frame.save("frame.png")

Extract all frames

导出所有帧

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

undefined

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

undefined

Video Information

视频信息

python

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']}")

python

info = workshop.get_info()
print(f"时长: {info['duration']} 秒")
print(f"尺寸: {info['width']}x{info['height']}")
print(f"帧率: {info['fps']}")
print(f"总帧数: {info['frame_count']}")

Custom Filters

自定义滤镜

python

undefined

python

undefined

Apply custom function to each frame

为每帧应用自定义函数

def custom_filter(frame): # frame is a PIL Image return frame.rotate(5)

workshop.apply_filter(custom_filter)

undefined

def custom_filter(frame): # frame 是 PIL 图像对象 return frame.rotate(5)

workshop.apply_filter(custom_filter)

undefined

Concatenate Videos

视频拼接

python

undefined

python

undefined

Join multiple clips

拼接多个视频片段

workshop.concat([ "intro.mp4", "main.mp4", "outro.mp4" ])

undefined

workshop.concat([ "intro.mp4", "main.mp4", "outro.mp4" ])

undefined

CLI Usage

CLI 用法

bash

undefined

bash

undefined

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

undefined

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

undefined

Optimization Tips

优化技巧

File Size Reduction

减小文件大小

Reduce dimensions: Smaller = much smaller file
Lower FPS: 10-15 FPS is usually sufficient
Limit colors: 64-128 colors often looks fine
Shorter duration: Each second adds significant size
Use lossy compression: Small quality loss, big size reduction

缩小尺寸：画面越小，文件体积越小
降低帧率：10-15帧/秒通常足够
限制色彩数：64-128色通常视觉效果良好
缩短时长：每一秒都会显著增加文件大小
使用有损压缩：微小的质量损失，大幅减小体积

Quality Improvement

提升画质

Start with high-quality source: Better input = better output
Use 256 colors: Maximum palette
Higher FPS: 24-30 FPS for smooth motion
Avoid heavy compression: Keep lossy above 90

使用高质量源视频：输入质量越高，输出效果越好
使用256色：最大调色板数量
提高帧率：24-30帧/秒实现流畅运动
避免过度压缩：有损压缩值保持在90以上

Size vs Quality Presets

大小与质量预设对比

Preset	Width	FPS	Colors	Use Case
`reaction`	256px	10	64	Quick reactions
`low`	320px	12	128	Basic sharing
`medium`	480px	15	256	General use
`high`	640px	20	256	High quality
`max`	Original	24	256	Best quality

预设	宽度	帧率	色彩数	使用场景
`reaction`	256px	10	64	快速反应式GIF
`low`	320px	12	128	基础分享
`medium`	480px	15	256	通用场景
`high`	640px	20	256	高质量需求
`max`	原尺寸	24	256	最佳画质

Error Handling

错误处理

python

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")

python

from scripts.gif_workshop import GifWorkshop, GifError

try:
    workshop = GifWorkshop("video.mp4")
    workshop.clip(start=0, end=100)  # 可能超出视频时长
    workshop.to_gif("output.gif")
except GifError as e:
    print(f"错误: {e}")
except FileNotFoundError:
    print("未找到视频文件")

Supported Formats

支持的格式

Input (Video)

输入（视频）

MP4, MOV, AVI, MKV, WebM, FLV, WMV

MP4, MOV, AVI, MKV, WebM, FLV, WMV

Output

输出

GIF (animated)
MP4 (for comparison)
PNG/JPEG (frames)

GIF（动图）
MP4（用于对比）
PNG/JPEG（单帧）

Dependencies

依赖项

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

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

Limitations

限制

Maximum practical GIF size: ~20-30MB
Very long GIFs become unwieldy
Complex scenes may have color banding
No audio support in GIF format

实际可用的最大GIF大小：约20-30MB
过长的GIF会难以处理
复杂场景可能出现色带问题
GIF格式不支持音频