跳转至
quickthumb
全部文档

Quickthumb 0.8.0

Quickthumb 0.8.0 汇聚了自 v0.7.0 以来的全部研发成果:统一的 Canvas/Deck 输出契约、更高精度的动效控制、矢量路径、文本范围选择器、图层高级合成、受限的 Lottie 导出以及一体化演示文稿 UI。这是一次破坏性(breaking)变更的 pre-1.0 版本。在升级现有的规范文件、脚本或集成项目之前,请务必仔细阅读迁移指南。

跳转至从 v0.7.0 迁移说明。

python -m pip install --upgrade "quickthumb[cli]==0.8.0"

要求 Python 3.11 及以上版本。视频导出需要外部安装 FFmpeg;安装 Python 可选依赖不会自动安装原生操作系统程序或系统库。

一体化文档与输出工作流

Canvas 与 Deck 现已全面实现统一的结构化 Document 协议,提供 validate()、inspect()、diagnose()、prefetch_assets()、sample() 与 export() 方法,无需包装额外的文档壳对象。

from quickthumb import Canvas, Deck, VideoOptions

canvas = Canvas(320, 180).background(color="#102030").shape(
    "rectangle", position=(24, 24), width=96, height=64, color="#42CEB7",
)
receipt = canvas.export("card.png")
print(receipt.written_paths, receipt.pixel_metrics.width)
frames = canvas.sample(time=[0.0])
print(frames.frames[0].sha256)
Deck(slides=[canvas]).export("slides.mp4", animation=VideoOptions(hold=1.0))
  • export(path, ...) 为推荐使用的文件输出 API,并返回 ExportResult:包含写入的文件路径列表、功能支持/降级诊断、像素与时序度量指标、资源清单以及实测渲染环境。原有的 render() 依然保留,但不返回执行凭据。两者均严格执行统一的文件选项与功能策略。二进制字节/字符串的 to_*() 方法保留各自的接口契约。
  • sample() 返回来自规范渲染器的 FrameSequence / CanonicalFrame 数据。inspect_document() 在不写入任何导出文件的前提下,整合布局、动效、诊断与观测到的资源。
  • 规范的 to_json() / from_json() 现已完整覆盖两种文档类型以及插件引用。JSON 专门描述创作时的设计场景,而非导出的帧图像、回调函数、字体文件或资源归档。报告模型均提供 model_dump_json()。
  • 结构化错误通过 code 和包含输入路径与图层上下文的 details 进行抛出。InputError、MissingAssetError 与 ErrorDetail 加入到现有的 Quickthumb 异常体系中。校验与诊断报告均具备 JSON 序列化安全性。

普通文件写入可能会覆盖已有文件。Deck 光栅导出生成带有数字编号的幻灯片文件,并在结果凭据中列出;这并非原子化的多文件事务。遇到未知扩展名、不兼容选项系列或不受支持的格式覆盖时将直接报错拒绝。显式光栅 format 覆盖支持 PNG/JPEG/WebP,且无需重命名传入的文件路径。JPEG 质量参数范围为 1–95,常规 WebP 质量范围为 1–100;此处 PNG 不接收压缩 quality。

输出契约 · 公开 API · JSON/Schema

动效、音频与渲染引擎升级

  • 变换采样全面采用亚像素级仿射几何。anchor 为归一化的 0–1 几何变换枢轴点,独立于布局排版的 align;ScaleXTrack 与 ScaleYTrack 引入独立坐标轴缩放。图像图层的 ScaleTrack 现已与其他图层完全一致,直接缩放其外部几何对象。ImageZoomTrack 以及图像平移/Ken Burns 镜头控制则专门用于操作图像视口内部的画面内容。静态与动态几何变换处理逻辑完全对齐。
  • PositionKeyframeSpec 增加了贝塞尔切线控制手柄与恒速路径采样支持。位置数值代表相对于创作初始布局的偏移量;切线手柄相对于自身关键帧进行偏移,而非声明绝对的画布控制点。绝对时间 TimingSpec.start 数值现已完整支持 JSON 往返序列化。auto_orient 会将路径切线朝向动态叠加至创作时的旋转角度或旋转轨道之上,且独立于轨道声明顺序。ColorTrack 采用感知均匀的文本/形状着色插值算法。
  • CubicBezierEasing、单关键帧独立缓动、保持关键帧(hold keyframes)、封闭解形式的 SpringEasing 以及带随机种子和带宽限制的 Wiggle 大幅拓展了动效创作空间。弹簧缓动采用具有精确终点的归一化 1 秒动态响应。Wiggle 会精确保留创作的起始姿态并在运动结束后冻结其最终扰动值。
  • Canvas.null() / NullLayer 与 parent 属性支持场景局部的几何变换层级联动,包括受限的嵌套编组复合、计数器、裁剪与遮罩。.group() 依然作为便捷的自动布局入口。父级局部定位不会将百分比坐标转换为父级的百分比,它们依然相对于画布根尺寸进行解析。不受支持的复合层级将给出明确诊断。
  • 文本字/行的交错动画直接基于实际排版布局展开。RangeSelector 支持带权重的范围选取与动态边界;字符目标为 Unicode 代码点(code points),而非字形簇(grapheme clusters)。请求的精确切片片段在输出前要么成功渲染,要么明确报错拒绝(包含单一目标的情况),不存在模糊的近似切分路径。
  • quickthumb.audio.analyze_audio() 返回缓存的 AudioAnalysis 源时钟起音(onset)时间点与相对 RMS 窗口。可将起音点用作数值时序锚点,或在 AnimationSpec.timeline() 中使用 analysis.scale_track()。此功能为瞬态突变检测,并非节拍跟随跟踪(beat tracking),且不会自动为你附加配乐音轨。
  • 视频采样忠实遵循解码后的真实时间戳;字幕时间边界与编码输出时钟均与规范场景时间分开独立测试。时间单位统一为秒。GIF 量化与编解码器时序可能与规范网格存在微小出入;凭据报告实际时序,并不承诺在所有编解码器中时钟分秒不差。
  • GIF/视频流式逐帧输出、静态幻灯片前缀复用、共享字体实例以及受限的多进程工作线程有效减少了重复开销。默认为 workers=1;受支持的多进程输出接受 1–8 个工作线程。空间超采样请使用 render_quality="high"。可选的 MotionBlur 为文件选项与图像序列引入时间曝光动态模糊,不适用于字节导出方法。它与空间分辨率质量相互独立,具有明确的图层合成限制。to_gif() 同样暴露了等比缩放的 max_size 与调色板 colors(2–256),此前该功能仅在文件层面的 GifOptions 中提供。

动效与时序 · 音频 API 与示例 · 动态人名条示例

路径、遮罩与插件生态

  • Canvas.path() / PathLayer 支持在固定视口内创作 SVG 路径数据:多边形路径、自适应二次/三次贝塞尔曲线与椭圆弧线、受限的渐变填充、实线/虚线描边、端点与拐角连接样式。动画几何图形在设备物理分辨率下重新栅格化绘制。DashOffsetTrack、TrimStartTrack、TrimEndTrack 与 TrimOffsetTrack 采用规范路径长度采样。
  • PathMorphTrack 对匹配的路径轮廓进行平滑插值。该 API 独立于既有的跨幻灯片 transitions.Morph;它并不意味着所有矢量导出器都能直接消化变形轨道。
  • TrackMatte 支持 Alpha/亮度(luma)遮罩源,具备显式的源图层可见性、反转及复用规则。宿主专属局部路径遮罩以及 MaskPositionTrack、MaskSizeTrack 和 MaskFeatherTrack 进一步拓展了遮罩能力。嵌套/动态编组、字幕、背景等不受支持的组合将被直接拒绝,而非静默粗略近似。原生 HTML 硬遮罩的支持范围窄于光栅格式。
  • 带有版本控制的 PluginDefinition / PluginRegistry 注册机制可声明参数、静态资源及同步光栅渲染回调。Canvas.plugin() 与 JSON 加载支持接收显式注册表。插件属于受信任的 Python 代码,并非沙箱环境;JSON 反序列化不会自动安装任何执行回调。光栅渲染为必选项;暂不支持带时间轴的插件及在 workers > 1 下运行插件。可选的 SVG 钩子仅影响 SVG 导出,且要求通过本地像素验收准入方可作为原生内容输出。

路径 API · 遮罩与轨道蒙版 · 插件契约规范

输出格式与其支持边界

输出格式 0.8.0 中的变更说明
PNG/JPEG/WebP 统一的文件策略、执行凭据、显式质量校验;依然为静态光栅输出。
图像序列 export_image_sequence() 将 PNG、JPEG 或 WebP 帧图像及清单文件输出到全新目录。已有目录(即便为空)绝不会被覆盖。其父级目录必须已存在。发布流程采用私有暂存与互斥原子化重命名;并非具备断电容灾恢复能力的持久归档。不包含音频。
GIF/MP4 统一的动画时钟与输出控制。Deck MP4 默认播放动效并保留每页旁白与配乐编排。MP4 始终为不透明;GIF 具有调色板与透明度限制。
WebM/MOV transparent=True 支持 VP9 Alpha WebM 与 ProRes 4444 MOV。Alpha 支持并不承诺在跨编解码器色彩转换或各类播放器中做到无损 RGB/RGBA 绝对一致。MOV 需要系统提供 FFmpeg 的 prores_ks 编码器。
SVG 受限的原生路径/着色与准入的插件路由;执行凭据清晰区分真实的原生与光栅图层。静态保真度观测使用 CairoSVG。Deck 没有 to_svg() 方法。
HTML 演示文稿保持交互式特性;受支持的原生路径描边相位/修剪与硬遮罩映射范围受限。路径运动映射采用 120 Hz 采样网格配合创作节点。不受支持的动效具有显式的静态/降级报告,包含每页 Deck 路由。
PDF 受限路径成为可编辑曲线,不受支持的着色方案具有显式的光栅降级回退。可选的 PDFium 比对会报告实际执行的路由。Deck PDF 的保真度观测请求会被拒绝。
PPTX 执行凭据报告实际的可编辑/光栅路由;各项支持按具体特性细分。原生的 PowerPoint 实际播放与呈现保真度尚未经由 Linux 自动化测试套件完成正式认证。
Lottie .lot 仅限 Canvas,通过 export()/render() 与 LottieOptions 导出;不支持 Deck 或字节 API。支持形状/路径上的受限纯色着色(包含 Alpha)、三次贝塞尔几何、原生描边修剪、采样的定型姿态、Null/Shape 父级层级,以及包含不透明文本着色的自包含静态 ASCII 文本轮廓。不支持通用光栅降级、音频、图片、渐变、任意复杂脚本文字塑形、轨道遮罩或 PathMorphTrack 消费者。不受支持的特性即便在其他策略要求光栅化时也会直接报错退出。
from quickthumb import ImageSequenceOptions, LottieOptions

canvas.export_image_sequence(
    "frames", format="webp", lossless=True,
    options=ImageSequenceOptions(fps=30.0, hold=1.0),
)
canvas.export("card.lot", animation=LottieOptions(fps=30.0, hold=1.0))

图像序列的编码参数与时序参数各自独立:PNG 保留规范的 8 位直通 RGBA;JPEG 在默认白色底衬上压平为 RGB;WebP 可配置为有损或无损。图像序列的 JPEG/WebP quality 参数范围为 1–95,区别于常规 WebP 的 1–100。lossless 仅适用于 WebP;传入不兼容参数会直接报错。清单文件精确记录编码格式、帧文件名/总数/时序、尺寸、Alpha、色彩模式、quality/lossless/matte,绝不妄言绝对通用的 RGBA 完全等同。

ExportPolicy 明确了对不受支持动效的处理行为。原生路由报告是对实际所选路由的客观记录,并非在所有查看器中绝对具备可编辑性的承诺。可选的静态 SVG/PDF fidelity 指标阈值仅用于生成报告:超出指标阈值不会自动拒绝文件写入或切换渲染器。Chrome 浏览器比对套件定位为开发测试工具,并非新的生产环境渲染后端。详情请参见针对各格式的具体限制。

资源、字体、CLI 与演示文稿体系

  • 统一的远程资源解析增加了 prefetch_assets() 以及记录缓存状态、源/内容标识及过期原因的清单文件。离线缓存渲染逻辑明确;陈旧过期的数据将如实报告,绝不擅自自动拒绝。文档会保留其首次远程解析结果;新文档实例则在当前缓存策略下重新解析。报告本身不转移实际字节,也不掌管缓存文件的生命周期。请在整个导出期间保持本地文件与引用的缓存文件可用。缓存控制环境变量包括 QUICKTHUMB_ASSET_CACHE_DIR、QUICKTHUMB_ASSET_MAX_AGE 以及 QUICKTHUMB_ASSET_OFFLINE。
  • 渲染环境记录真实的字体字节数据、字形/可变轴/塑形引擎标识以及渲染器版本。远程字体使用内容寻址副本。默认的 QUICKTHUMB_DEFAULT_FONT 选择现已完整遵循 weight、bold 与 italic 属性,因此原有文本的折行、对齐与渲染像素可能会发生相应微调。
  • quickthumb doctor 全面检查环境依赖与磁盘写入就绪状态;quickthumb inspect 提供通用的 Canvas/Deck 检查信封。Schema 校验、代码检查、渲染与错误输出全面遵循更严谨的文档契约。CLI 光栅压缩质量遵循 JPEG 1–95 / WebP 1–100 的明确区分。
  • quickthumb serve 默认保持以幻灯片为核心的演示体验。演示界面与 Inspect motion(动效检查面板) 共享暖白/青色 UI 主题、真实的幻灯片缩略图以及原始的幻灯片宽高比。动效检查面板通过时序/代理控制擦碰浏览导出渲染器的光栅帧序列;它并非视频播放器、音频混音台或交互编辑器。命令行追加 --timeline 可直接打开该检查模式。演讲者视图与全局主题深度融合,提供当前/下一张幻灯片、演讲者备注、已用时长以及导航控制。支持键盘/提示点推进、观众端实时同步与源码热重载。
  • 安装与文档明确区分了核心基础输出与 cli、svg、pdf、pptx、lottie 及 rembg 可选依赖。CairoSVG 需要系统安装原生 Cairo;文本轮廓化需要 [lottie]/fontTools 以及受支持的字体(非零字间距需要 RAQM 排版引擎)。背景去除功能在初次运行时会自动下载模型。
  • 安全与依赖维护包括打补丁修复的 rembg/ONNX Runtime、Pillow、certifi、filelock/virtualenv 与 ty 0.0.84,以及最新固定的 CI Actions、watchfiles、Typer、inline-snapshot 和 diff-cover。现有的自动化安全扫描门禁全数保持生效。

安装指南 · CLI 与 serve 命令 · 示例代码库

从 v0.7.0 迁移指南

对于已被移除的旧入口点,本版本不提供任何兼容性别名。

变更前(v0.7.0) 0.8.0
deck.to_animated_mp4(slide_duration=2.0) 使用 deck.to_mp4(hold=2.0);文件导出使用 deck.export("out.mp4", animation=VideoOptions(hold=2.0))。
用于静态带旁白 PNG 幻灯片的 deck.to_mp4(...) / deck.render_mp4(...) 常规 MP4 现在会正常播放动效。如需静止硬切转场,请构建静态 Canvas 并显式设置 transitions.Cut();旁白/时长配置依然保留在 .slide() 上。原有的仅静止画面方法已被彻底移除,不再静默保留。
deck.to_gif(slide_duration=2.0) / deck.to_webm(slide_duration=2.0) 两个方法均改为使用 hold=2.0。已持久化保存的动画选项 JSON 也需同步更新。
直接遍历 canvas.diagnose() / deck.diagnose() 改为遍历 .diagnose().findings;DiagnosticReport 全面替代原有的旧版结果数据结构。
deck.model_dump(mode="json") 获取场景数据请使用 json.loads(deck.to_json())。结果与诊断报告模型依然保留完整的 Pydantic 序列化能力。
缺少文档 kind、或包含未知字段/重复图层 ID 的手写 JSON 在文档边界(包括 slides 内部)补齐 kind: "canvas" / "deck",保留图层 type,并修复无效字段/ID。使用当前版本重新生成 Schema。严格解析还会直接拒绝非有限浮点数、尾随杂质 JSON 以及格式不合规的标量字段。
将图像图层的 ScaleTrack 视作视口缩放(zoom) 视口缩放请使用 ImageZoomTrack;ScaleTrack 现在直接缩放外层图像几何体。请仔细检查锚点以及自动朝向配合旋转的偏移量。
直接从 quickthumb 顶层导入时间轴/编译器/渲染器底层辅助工具 请改用文档公开声明的创作类型以及文档级别的 sample() / inspect_motion() 操作。底层内部实现工具不再作为顶层公开导出提供,也不属于受支持的公共生命周期范畴。
假定默认字体样式总是能自动命中常规(regular)字形 请显式明确选择所需字体及其样式,并在修复样式查找逻辑后重新审视文本排版布局。

在常规 MP4 路径中创建带有旁白的静态硬切幻灯片示例:

from quickthumb import Deck, VideoOptions, transitions

deck = Deck(320, 180, transition=transitions.Cut())
deck.slide(canvas, audio="narration.wav", duration=2.0)
deck.export("narrated.mp4", animation=VideoOptions(fps=30.0, hold=1.0))
mp4_bytes = deck.to_mp4(fps=30.0, hold=1.0)

duration 会覆盖旁白音频的实际长度;未显式指定时,旁白音频时长直接提供静态幻灯片在进入默认 hold 保持前的持续时间。这并不会强行冻结任意带有动画的 Canvas。设置 None 转场会沿用现有的默认淡入淡出;如需硬切转场请显式传入 Cut。减弱动效属于完全独立的导出策略。

对于基于未发布的中间开发代码构建的集成项目,还需将 export_png_sequence / PngSequence* 替换为 export_image_sequence / ImageSequence*,将动画选项中的 quality 替换为 render_quality,并将 to_narrated_mp4 / render_narrated_mp4 替换为常规 MP4 导出路径。这些中间状态的旁白/序列名称从未进入过 v0.7.0 的公开 API 规范中。猴子补丁(monkeypatch)篡改的 render() 钩子不再作为 export() 的底层调度机制。

验证与现有边界说明

发布前的集成主分支在 Linux CI 上以 4,632 项测试全部通过、3 项跳过、覆盖率 92.23% 的成绩,全票通过各项质量检查、类型检查、构建检查与安全扫描。版本发布 PR 以及正式发布的 Wheel 包由发布流水线独立把关。针对文档记载的受限 Lottie、HTML、矢量、时序与 Alpha 通道路由均拥有基准播放器与像素级测试依据;这并不意味着对所有可能的组合或第三方原生桌面应用程序均作全面认证。

未结项的 Linux 默认字体黄金基线刷新工作在本次发版中并未重新验证。针对具体格式的具体实现限制与第三方原生应用支持边界已在上方各个输出章节中详细列明。

完整变更对比:https://github.com/sjquant/quickthumb/compare/v0.7.0...v0.8.0