截屏录屏助手 (screen-studio)

一屏五用：截图（静态）+ 录屏（动态）+ 录音（麦克风）+ 合成（音视频）+ 标注（圈画/水印），一个技能全搞定。

何时使用

• 需要保存屏幕画面做证据、文档、演示、报错现场
• 需要把一段操作过程录成视频/GIF（教程、演示、复盘、bug 复现）
• 需要录屏 + 讲解配音（record-av 一路同时录屏幕和麦克风并自动合成）
• 需要在截图上圈画重点、箭头、文字、高亮（annotate 程序化 / annotate-gui 手绘）
• 需要录屏时叠加水印（--stamp 实时标注在画面左上角）
• 需要把截图发给视觉模型（输出 base64）
• 需要周期连拍留证（burst，配合定时任务用）
• 需要知道当前屏幕/显示器分辨率、麦克风设备信息

依赖

# 基础（截图 + GIF 录屏 + 程序化标注，够用大多数场景）
pip install mss pillow

# 完整（+ MP4 录屏）
pip install mss pillow numpy opencv-python-headless

# 录音 + 合成（+ 麦克风录音、音视频合并）
pip install sounddevice soundfile imageio-ffmpeg

# 交互式手绘标注：需要系统 Python 自带 tkinter（Windows 常规 python.org 安装已带）

> 依赖均延迟导入：不录 MP4 就不需要 OpenCV；不录音就不需要 sounddevice；
> imageio-ffmpeg 内置一个 ffmpeg 二进制，合成无需另装系统 ffmpeg。
> GUI 标注因需要 tkinter，建议用系统 Python（带 tkinter）运行 scripts/annotate_gui.py。

快速开始（CLI）

# 1) 查显示器 / 麦克风设备
python scripts/cli.py info
python scripts/cli.py devices

# 2) 全屏截图
python scripts/cli.py shot -o shot.png

# 3) 区域截图
python scripts/cli.py shot -o region.png -r '{"left":100,"top":100,"width":800,"height":600}'

# 4) 截图输出 base64（发给视觉 API）
python scripts/cli.py base64 -f JPEG -q 85

# 5) 连拍留证（3 张，间隔 1s）
python scripts/cli.py burst -n 3 -i 1.0 --out-dir shots -o cap

# 6) 录屏 10 秒 MP4
python scripts/cli.py record -o demo.mp4 -t 10 --fps 15

# 7) 录 GIF 5 秒（轻量，无需 OpenCV）
python scripts/cli.py record -o demo.gif -t 5 --fps 8

# 8) 手动停止录屏（不指定 -t，按 Ctrl+C 结束）
python scripts/cli.py record -o demo.mp4 --fps 20

# 9) 麦克风录音 5 秒
python scripts/cli.py record-wav -o voice.wav -t 5

# 10) 屏幕 + 麦克风同时录 8 秒并自动合成
python scripts/cli.py record-av -o final.mp4 -t 8 --fps 15

# 11) 单独合成（已有 mp4 + wav）
python scripts/cli.py mux -v demo.mp4 -a voice.wav -o final.mp4

# 12) 录屏时叠加文字水印（红色，左上角）
python scripts/cli.py record -o demo.mp4 -t 8 --stamp "内部演示" --stamp-color red

# 13) 对已有图片做程序化标注（JSON 描述标注元素）
python scripts/cli.py annotate -i shot.png -o out.png -e '[
  {"type":"rect","box":[10,10,300,200],"color":"red","width":5},
  {"type":"arrow","points":[10,400,500,400],"color":"blue","width":5},
  {"type":"highlight","box":[10,240,500,280],"color":"yellow","alpha":0.4},
  {"type":"text","xy":[20,20],"text":"注意这里","color":"red","size":28,"bg":"white"}
]'

# 14) 打开窗口手绘标注（快捷键 1=红 2=蓝 3=黄；p画笔 l直线 a箭头 r矩形 e椭圆 h高亮 t文字）
python scripts/annotate_gui.py -i shot.png -o out.png

作为 Python 模块使用

from scripts.capture import ScreenCapture, ScreenRecorder, AudioRecorder, mux_audio_video
from scripts.annotate import annotate_image, rect, arrow, text, highlight, pen

# ---- 截图 ----
with ScreenCapture() as sc:
    print(sc.primary_size)                 # (1920, 1080)
    sc.to_file("full.png")                 # 全屏 -> 文件
    sc.to_file("region.png", region={"left":0,"top":0,"width":800,"height":600})
    sc.burst(prefix="cap", count=5, interval=1.0)   # 连拍 5 张
    b64 = sc.to_base64(fmt="JPEG", quality=85)      # -> base64，喂给视觉模型

# ---- 录屏 ----
with ScreenRecorder(fps=15) as rec:
    rec.record("demo.mp4", duration=10)    # MP4 录 10 秒
    # rec.record("demo.gif", duration=5)   # GIF 录 5 秒

# ---- 录音 + 合成 ----
AudioRecorder().record_wav("voice.wav", duration=5)
mux_audio_video("demo.mp4", "voice.wav", "final.mp4")

# ---- 截图标注 ----
from PIL import Image
img = Image.open("shot.png")
out = annotate_image(img, [
    rect(box=[10, 10, 300, 200], color="red", width=5),
    arrow(p0=[10, 400], p1=[500, 400], color="blue", width=5),
    highlight(box=[10, 240, 500, 280], color="yellow", alpha=0.4),
    text(xy=[20, 20], text="重点", color="red", size=28, bg="white"),
    pen(points=[[500,300],[560,320],[620,300]], color="blue", width=5),
])
out.save("marked.png")

核心规则（吸收自截图技能方法论）

1. 按产物选路径，不按习惯：网页要整页/元素截图时，优先浏览器原生截图（Playwright），而不是对着浏览器窗口截桌面；桌面 App 才用本工具。
2. 截图前先稳定目标：动态页面等数据/字体/过渡完成再截，别截到半成品状态。
3. 冻结视口与缩放保证可复现：做前后对比时，视口、缩放、主题必须一致，否则 diff 无意义。
4. 截最小的有用范围：能截区域/窗口就别截全屏；全屏噪声大、难比对。
5. 截图前去除噪声：光标、提示条、时间戳、随机内容、隐私/密钥/token 都要藏掉或打码，除非"噪声本身就是 bug"。
6. 选对输出格式：截图/UI/代码/终端默认 PNG；JPEG 只给照片类内容，别拿它压缩截图（会糊字）。
7. 录屏默认 MP4，短演示用 GIF：MP4 画质好体积小；GIF 无需 OpenCV、即开即用，适合 5-10 秒小动图。
8. 带配音录屏用 record-av：一条命令同时录屏幕和麦克风并自动合成，适合教程讲解、演示旁白。
9. 标注颜色优先红/蓝/黄：这三个颜色在明暗背景上都醒目，适合圈重点、画箭头、打高亮。
10. 手绘标注用 annotate-gui：临时圈画重点比程序化 JSON 快；保存时仍输出原分辨率 PNG。

常见陷阱

• 该截网页元素/整页，却对着浏览器窗口截桌面 → 模糊、带浏览器边框。
• 数据/字体/布局还没加载完就截 → 半成品。
• 不同缩放/主题下做对比 → diff 全是假阳性。
• 用 JPEG 存截图 → 文字、代码、边缘发糊。
• 录 MP4 时输出扩展名与编码不匹配（.avi 配 mp4v）→ 打不开。
• 录屏区域宽高为奇数 → 某些 MP4 编码器拒绝，本工具已自动取偶。
• GIF 录全屏 → 又慢又大，配 -r 截小区域或改用 MP4。
• 录音没声音 → 检查 devices 里麦克风是否默认输入、系统是否已授权。
• 分享的截图里还露着 token、账号、地址栏 URL。
• 标注文字出方块乱码 → 系统缺中文字体；Windows 下已内置微软雅黑/黑体候选，macOS/Linux 请确保有 PingFang/DejaVuSans。
• GUI 标注窗口打不开 → 该环境 Python 没有 tkinter；请换用系统 Python（python.org 安装通常自带 tkinter）运行 scripts/annotate_gui.py。
• 录屏加水印掉帧 → 每帧 PIL 转码有开销，建议降低 fps（8–15）或改用后期合成。

参数速查

完整 API 参数说明见 reference.md。

后续可扩展

• 系统音轨（非麦克风）录制（WASAPI loopback）
• 定时截图自动化（配合 automation 做周期性画面留证）
• 截图 OCR（接 tesseract / 视觉模型）
• 录屏后期标注（在已录好的视频上逐帧叠加箭头/文字）
• GUI 标注支持马赛克/模糊打码