コンテンツにスキップ
quickthumb
すべてのドキュメント

Quickthumb 0.8.0

Quickthumb 0.8.0 は v0.7.0 以降の開発内容をまとめたリリースです。Canvas/Deck 共通の出力契約、より精密なアニメーション、ベクターパス、文字セレクター、合成、対応範囲を限定した Lottie 出力、統一したプレゼンテーション UI を提供します。1.0 より前の、破壊的変更を含むリリースです。保存済み仕様、スクリプト、連携を更新する前に移行の節を読んでください。

v0.7.0 からの移行へ。

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

Python 3.11 以上が必要です。動画出力には FFmpeg を別途インストールしてください。Python の extra を入れても、ネイティブプログラムやライブラリはインストールされません。

共通の文書・出力ワークフロー

Canvas と Deck は、validate()、inspect()、diagnose()、prefetch_assets()、sample()、export() を持つ構造的な Document プロトコルを実装します。新しい文書ラッパーを作る必要はありません。

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))
  • 推奨ファイル API の export(path, ...) は ExportResult を返します。保存パス、機能・代替診断、ピクセル・時間指標、アセット、観測した描画環境を含みます。render() も使えますが、結果レポートは返しません。両方に共通のファイルオプションと機能ポリシーを適用します。バイト列・文字列の to_*() メソッドは固有の契約を保ちます。
  • sample() は基準レンダラーの FrameSequence / CanonicalFrame データを返します。inspect_document() は出力を書かずにレイアウト、モーション、診断、観測アセットをまとめます。
  • 正規 to_json() / from_json() は両文書種別とプラグイン参照に対応します。JSON が記述するのは作成したシーンであり、出力フレーム、コールバック、フォント、アセットアーカイブではありません。レポートモデルには model_dump_json() があります。
  • 構造化エラーは code と、入力パス・レイヤー情報を持つ details を公開します。既存の Quickthumb エラー型に InputError、MissingAssetError、ErrorDetail が加わります。検証・診断レポートは JSON に安全に保存できます。

通常のファイル出力は既存ファイルを上書きできます。Deck のラスター出力は番号付きスライドファイルを書き、結果レポートに記録します。複数ファイルのアトミックなトランザクションではありません。不明な拡張子、互換性のないオプション分類、未対応の形式上書きは拒否します。ラスターの明示的な format は PNG/JPEG/WebP に対応し、指定パスを変更しません。JPEG の quality は 1〜95、通常の WebP は 1〜100 です。ここで PNG に圧縮 quality は指定できません。

出力契約 · 公開 API · JSON・スキーマ

アニメーション・音声・描画

  • 変換のサンプリングはサブピクセルのアフィン幾何を使います。anchor は 0〜1 に正規化した支点で、レイアウトの align とは別です。ScaleXTrack と ScaleYTrack で軸を個別に制御できます。画像の ScaleTrack も他レイヤー同様、外側のオブジェクトを拡縮します。画像のビューポート内の内容には ImageZoomTrack とパン・Ken Burns 制御を使います。静的・アニメーションの変換処理を揃えました。
  • PositionKeyframeSpec に Bézier ハンドルと等速パスサンプリングが加わります。位置は作成した配置からのオフセット、ハンドルは自身のキーフレームからのオフセットであり、キャンバス上の絶対制御点ではありません。絶対的な TimingSpec.start は JSON 保存・復元でも残ります。auto_orient はトラック順に依存せず、作成した回転・回転トラックにパス方向を加えます。ColorTrack は文字・図形の塗りを知覚的に補間します。
  • CubicBezierEasing、キーフレームごとのイージング、hold キーフレーム、閉形式の SpringEasing、seed 付き帯域制限 Wiggle が加わります。spring は正確な端点を持つ、正規化した 1 秒の応答を使います。Wiggle は作成時の開始状態を保ち、終了後は最後の揺らぎを固定します。
  • Canvas.null() / NullLayer と parent でシーン内の変換階層を作れます。対応範囲内の入れ子グループ合成、カウンター、クリップ、マスクを含みます。簡単な自動レイアウトには引き続き .group() を使います。親ローカルの配置でもパーセント座標が親基準にはならず、引き続きキャンバスを基準に解決します。未対応の合成には診断を出します。
  • 単語・行の時間差表示は配置済みのテキストレイアウトを使います。RangeSelector は重み付き選択と範囲のアニメーションに対応します。文字の対象は書記素クラスターではなく Unicode コードポイントです。要求した厳密な断片は、対象が 1 つでも出力前に描画または拒否します。近似的な分割経路はありません。
  • quickthumb.audio.analyze_audio() はキャッシュした AudioAnalysis を返し、ソース時計の立ち上がり時刻と相対 RMS 区間を提供します。立ち上がりを数値のタイミング基準にするか、AnimationSpec.timeline() で analysis.scale_track() を使います。これは過渡変化の検出であり、ビート追跡ではありません。音楽も自動で付けません。
  • 動画のサンプリングはデコードしたタイムスタンプに従います。字幕境界とエンコード出力の時計は、基準シーン時間とは別に検証します。単位は秒です。GIF の量子化やコーデック時間は基準グリッドと異なる場合があり、結果レポートは時間を報告しますが、全コーデックで同じ時計を約束しません。
  • GIF・動画のフレームストリーミング、静的スライド前方部分の再利用、共有フォントフェイス、上限付きの spawn ワーカーで重複作業を減らします。既定は workers=1、対応する並列出力は 1〜8 ワーカーです。空間スーパーサンプリングには render_quality="high" を使います。任意の MotionBlur はファイルオプションと画像シーケンスに時間方向の露光を加えますが、バイト列メソッドでは使えません。空間品質とは別で、合成に明示的な制限があります。to_gif() でも、従来ファイル側の GifOptions だけにあった縦横比を保つ max_size とパレット colors（2〜256）を指定できます。

モーションと時間 · 音声 API と例 · 動くローワーサード

パス・マスク・プラグイン

  • Canvas.path() / PathLayer は固定ビューポート内に SVG パスデータを作ります。多角形パス、適応的な 2 次・3 次曲線と楕円弧、対応範囲内のグラデーション、実線・破線、端点・接合を扱います。動く形状はデバイス解像度で再描画します。DashOffsetTrack、TrimStartTrack、TrimEndTrack、TrimOffsetTrack は基準パス長のサンプリングを使います。
  • PathMorphTrack は対応付けたパス輪郭を補間します。既存のスライド間 transitions.Morph とは別 API であり、全ベクター出力が morph トラックを扱えるわけではありません。
  • TrackMatte は、ソースの表示、反転、再利用を明示したアルファ・輝度ソースに対応します。所有レイヤー内のパスマスクと MaskPositionTrack、MaskSizeTrack、MaskFeatherTrack が加わります。入れ子・動的グループ、字幕、背景など未対応の組み合わせは、黙って近似せず拒否します。ネイティブ HTML のハードマスクはラスターより対応範囲が狭くなります。
  • バージョン付き PluginDefinition / PluginRegistry は、パラメーター、アセット、同期ラスターコールバックを宣言します。Canvas.plugin() と JSON 読み込みは明示的なレジストリを受け付けます。プラグインは信頼できる Python でありサンドボックスではなく、JSON がコールバックをインストールすることはありません。ラスター描画は必須で、時間依存プラグインと workers > 1 のプラグイン描画は未対応です。任意の SVG フックは SVG だけに適用し、ネイティブ出力にはローカルのピクセル比較による採用判定が必要です。

Path API · マスクとマット · プラグイン契約

出力形式と制限

出力 0.8.0 の変更
PNG/JPEG/WebP 共通のファイルポリシー、結果レポート、明示的な品質検証。引き続きラスター出力です。
画像シーケンス export_image_sequence() が PNG、JPEG、WebP のフレームとマニフェストを新しいディレクトリへ書きます。空でも既存ディレクトリは上書きしません。親は存在する必要があります。非公開ステージングと排他的なアトミック rename で公開しますが、クラッシュ後の永続性を保証するアセットアーカイブではありません。音声は含みません。
GIF/MP4 共通のアニメーション時計と出力設定。Deck MP4 は既定で動きを再生し、スライドごとのナレーションと音楽のスケジュールを保ちます。MP4 は不透明、GIF にはパレット・透明度の制限があります。
WebM/MOV transparent=True で VP9 alpha WebM と ProRes 4444 MOV に対応します。アルファ対応は、コーデックの色変換やプレーヤーをまたぐ RGB/RGBA の完全な可逆性を保証しません。MOV には FFmpeg の prores_ks が必要です。
SVG 対応範囲内のネイティブパス・塗りと、採用判定を通ったプラグイン経路。レポートは実際のネイティブ・ラスターレイヤーを区別します。静的忠実度は CairoSVG で観測します。Deck の to_svg() はありません。
HTML 対話性を維持します。ネイティブパスの stroke 位相・trim とハードマスクの対応は限定的です。パスモーションは 120 Hz グリッドと作成した節点を使います。未対応のアニメーションには、Deck の各スライドの経路も含め、静的・代替表現を明示します。
PDF 対応するパスは編集可能な曲線となり、未対応の塗りは明示的なラスター代替になります。任意の PDFium 比較は実際に実行した経路を報告します。Deck PDF の忠実度観測は拒否します。
PPTX 実際の編集可能・ラスター経路を報告します。対応は機能ごとに異なります。Linux テスト群はネイティブ PowerPoint の再生・忠実度を保証していません。
Lottie .lot export()/render() と LottieOptions による Canvas 専用出力。Deck・バイト列 API はありません。対応範囲内の図形・パスの単色塗り（アルファ含む）、3 次曲線、ネイティブ stroke trim、サンプルした保持姿勢、Null/Shape の親階層、不透明な文字塗りを持つ自己完結した静的 ASCII 文字輪郭に対応します。一般的なラスター代替、音声、画像、グラデーション、任意の文字整形、track matte、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 専用で、互換性のない引数はエラーです。マニフェストは全形式で RGBA が一致すると主張せず、エンコード、フレーム名・数・時間、寸法、アルファ、mode、quality/lossless/matte を正確に記録します。

ExportPolicy で未対応モーションの扱いを明示します。ネイティブ経路レポートは実際の経路の観測であり、全ビューアーでの編集性を保証しません。任意の静的 SVG/PDF の fidelity 限界は報告専用です。超過しても自動拒否やレンダラー切り替えは行いません。Chrome 比較はテストツールで、本番用の新しい描画バックエンドではありません。形式別の制限を参照してください。

アセット・フォント・CLI・プレゼンテーション

  • 共通のリモート解決に prefetch_assets() とマニフェストが加わり、キャッシュ状態、ソース・内容の識別、stale の理由を報告します。オフラインのキャッシュ描画は明示的で、古いデータは報告しますが自動拒否しません。文書は最初のリモート解決を保持し、新しい文書は現在のポリシーで解決し直します。レポートはバイトを転送せず、キャッシュの寿命も管理しません。出力完了まで、ローカルファイルと参照キャッシュを利用可能にしてください。制御には QUICKTHUMB_ASSET_CACHE_DIR、QUICKTHUMB_ASSET_MAX_AGE、QUICKTHUMB_ASSET_OFFLINE を使います。
  • 描画環境は実際のフォントバイト、フェイス・可変軸・文字整形の識別、レンダラーのバージョンを記録します。リモートフォントは内容アドレス付きコピーを使います。既定の QUICKTHUMB_DEFAULT_FONT 選択も weight、bold、italic を反映するようになったため、既存の文字の折り返し、整列、見えるピクセルが変わる場合があります。
  • quickthumb doctor は検出した要件と書き込み準備を確認し、quickthumb inspect は共通の Canvas/Deck エンベロープを提供します。schema、lint、render、エラー出力は厳密な文書契約に従います。CLI のラスター品質も JPEG 1〜95 / WebP 1〜100 を区別します。
  • quickthumb serve はスライド中心のプレゼンテーションを既定に保ちます。Presentation と Inspect motion は、暖かな白とティールの UI、実際のスライドサムネイル、元の縦横比を共有します。モーションパネルは時間・proxy 設定で出力レンダラーのラスターフレームを探すもので、再生・音声・編集の機能ではありません。--timeline でこの検査モードを開きます。発表者画面も同じテーマになり、現在・次のスライド、ノート、経過時間、移動を表示します。キーボード・キュー進行、聴衆との同期、ソース再読み込みも残ります。
  • インストール案内は、基本出力と cli、svg、pdf、pptx、lottie、rembg extra を区別します。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 からの移行

削除した API に互換用の別名はありません。

以前 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 スライドも含む文書境界に kind: "canvas" / "deck" を加え、レイヤーの type を残し、無効なフィールド・ID を修正します。インストール版でスキーマを再生成してください。厳密な解析は非有限値、JSON 後の余分な内容、不正なスカラーフィールドも拒否します。
画像の ScaleTrack をビューポートのズームとして使用 ビューポートのズームには ImageZoomTrack を使います。ScaleTrack は画像の外側の形状を変換します。アンカー、auto-orient と回転オフセットを見直してください。
timeline/compiler/renderer ヘルパーを quickthumb からインポート 公開された制作型と文書の sample() / inspect_motion() を使います。低レベル実装ヘルパーはルートの公開 API でも、サポート対象のライフサイクルでもありません。
既定のフォントスタイルが 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 を使ってください。reduced-motion は別のポリシーです。

未リリースの途中のチェックアウトに合わせた連携では、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() の振り分け手段ではなくなりました。

検証と残る制限

リリース前の統合 main は Linux CI で 4,632 テスト成功、3 スキップ、カバレッジ 92.23%、品質・型・ビルド・セキュリティ検査を通過しました。バージョン PR と公開 wheel はリリースパイプラインで別に検査します。文書化した範囲内の Lottie、HTML、ベクター、時間、アルファ経路には参照プレーヤーやピクセルの証拠がありますが、全組み合わせやネイティブアプリケーションを保証しません。

未完了の Linux 既定フォントの基準画像更新は、このリリースで新たに検証したわけではありません。形式固有の実装・ネイティブアプリケーションの制限は、上記の各出力に記載しています。

全変更の比較: https://github.com/sjquant/quickthumb/compare/v0.7.0...v0.8.0