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

Deck

Deckは順序付きのCanvasスライドの集まりです。各スライドは単独とまったく同じように描画し、同じパイプラインで複数形式への出力を追加します。Canvasのレイヤー用語とシーン内IDも維持します。

作成

Deck(width=None, height=None, slides=None, theme=None)

from quickthumb import Canvas, Deck

deck = Deck()                          # empty, no default size
deck = Deck(1280, 720)                 # default slide size for unsized slides
deck = Deck(slides=[cover, body])      # from pre-built canvases
パラメーター 型 説明
width int \| None スライドの既定幅。heightと一緒に指定するか、両方省きます。
height int \| None スライドの既定高さです。
slides list[Canvas] \| None 順序付きの初期スライド。各要素はCanvasです。
theme dict \| None 全スライドの$theme.*参照で共有するトークングループです。スライド側のテーマが優先されます。to_json()/from_json()で維持します。

Deck.from_aspect_ratio(ratio, base_width)

Canvas.from_aspect_ratioと同様に、縦横比から既定のスライドサイズを決めます。

deck = Deck.from_aspect_ratio("16:9", 1280)   # default 1280×720

スライドを追加する

コンストラクターのDeck(slides=[...])へ初期スライドを渡すか、.slide(canvas, transition=None, *, audio=None, duration=None, notes=None)で1枚ずつ追加します。両方も使えます。Deckを変更してselfを返すので連続呼び出しが可能です。Deckに既定サイズがあれば、サイズ未設定のCanvas()はそれを継承します。明示サイズのCanvasは元の寸法を保ち、異なる場合はmixed-slide-size警告になります。

メソッド 説明
.slide(canvas, transition=None, *, audio=None, duration=None, notes=None) Canvasを1枚追加します。音声と長さは任意のナレーション設定、ノートはHTML発表者モードだけに表示します。 
deck = (
    Deck(1280, 720)
    .slide(
        Canvas().background(color="#101820").text(content="Cover", size=96, color="#FFFFFF"),
        audio="voice.wav",
        duration=2.5,
        notes="Introduce the central thesis.",
    )
    .slide(Canvas().background(color="#1A1A2E").text(content="Body", size=64, color="#FFFFFF"))
)

既定サイズのないDeckへサイズ未設定Canvasを追加するとValidationErrorになります。DeckかCanvasにサイズを与えてください。

Deckはシーケンスでもあり、len(deck)、deck[i]、スライドの反復が使えます。deck.slidesとdeck.notesは対応するスライド・ノート一覧のコピーを返し、返されたリストを変えてもDeckは変わりません。

出力メソッド

.export(path, policy=None, *, format=None, quality=None, animation=None)

render()のように保存し、ExportResultを返します。written_pathsには、ラスターなら番号付きスライドファイル、ほかはPDF、PPTX、HTML、アニメーションの1ファイルを格納します。パスは文字列かpathlib.Pathです。format、quality、animation、policyはrender()と同じです。

result = deck.export("slides.png")
print(result.written_paths)

結果、機能の事前検査、export()と以下のメソッドとの関係は推奨出力APIを参照してください。

.render(path, format=None, quality=None, animation=None, policy=None)

拡張子に応じて描画し、保存したパスのリストを返します。

from quickthumb import GifOptions, VideoOptions

deck.render("deck.pdf")      # one multi-page PDF (a page per slide)
deck.render("deck.pptx")     # one multi-slide PPTX (a slide per slide)
deck.render("deck.gif")      # one animation playing transitions between slides
deck.render(
    "preview.gif",
    animation=GifOptions(fps=8, max_size=(540, 960), colors=128),
)
deck.render("deck.html")     # one self-contained HTML slideshow
deck.render("slides.png")    # slides_01.png, slides_02.png, …
deck.render("slides.jpg", quality=85)
拡張子 動作
.pdf 複数ページのPDF1つ。pdf追加機能が必要です。
.pptx 複数スライドのPPTX1つ。pptx追加機能が必要です。
.gif / .webm / .mov 既定設定でレイヤーと切り替えを再生するアニメーション1つ。WebM/MOVにはffmpegが必要で、MOVはprores_ksを使います。
.mp4 任意のスライド別ナレーションを持つアニメーション。H.264/yuv420p映像とAAC音声です。ffmpegと、ナレーションにはffprobeが必要です。静止スライドには静的CanvasとCut()を使います。
.html / .htm 自己完結した動くHTMLスライドショー1つです。
.png / .jpg / .jpeg / .webp 0埋め番号付きでスライドごとに保存します。
パラメーター 型 既定値 説明
path str — 保存先。ラスターは<stem>_NN<ext>になります。
format str \| None None 大文字小文字を区別しない"PNG"、"JPEG"、"WEBP"の再指定。文書・アニメーション拡張子では拒否します。
quality int \| None None JPEGは1–95、WebPは1–100の圧縮品質。それ以外は拒否します。
animation GifOptions \| VideoOptions \| None None GIFはGifOptions、MP4/WebM/MOVはVideoOptionsです。
policy ExportPolicy \| None None 動画・HTML・PPTXのreduced_motionなどのポリシーです。render()とexport()は書き込み前にunsupported_motionを適用します。

注意

.pdf、.pptx、アニメーションにqualityを指定するとRenderingErrorになります。空のDeckの描画も同じです。

GifOptionsとVideoOptionsはquickthumbから取得できます。GifOptionsはGIFのfps、hold、ループ回数、マット、比率を保つmax_size、パレットcolorsを、VideoOptionsはMP4/WebM/MOVのfps、hold、マット、サウンドトラック、音声ループを制御します。音楽はAudioTrack(path="music.mp3", loop=True)として渡します。

VideoOptions(transparent=True)はVP9 WebMとProRes 4444 MOVでアルファを保ちます。厳密なブール型で既定はFalseです。他の出力はすべて拒否します。両方のholdは厳密な有限の非負数（既定3秒）で、既定値なら保存時に省略します。workersは厳密な整数1–8（既定1）、render_quality="standard"または"high"を指定できます。spawnと対応入力は並列描画を参照してください。別のアニメーション形式の専用オプションは拒否します。

.to_html()

自己完結したスライドショー文書を返します。通常の観客画面はクリック、Space、矢印キーで操作できます。quickthumb serveで?presenterを付けて開くと、現在・次のスライド、発表者ノート、一時停止・再開・リセットのタイマー、同期した観客操作が加わります。

html = deck.to_html()
deck.render("slides.html")

開発中はquickthumb serve slides.pyを使えます。Pythonソースはモジュール変数deck、slides、canvasでDeckを公開します。

.to_pdf() / .to_pptx()

Canvasごとに1ページ・1スライドの文書バイト列を返します。

with open("deck.pdf", "wb") as f:
    f.write(deck.to_pdf())   # requires quickthumb[pdf]
pptx_bytes = deck.to_pptx()  # requires quickthumb[pptx]

.to_gif(...) / .to_webm(...) / .to_mov(...)

各スライドのレイヤーを動かし、最後の状態を保持するアニメーションを返します。トランジションはそのスライドへ入る変化です。時間の仕組みはGIFと動画を参照してください。.to_webm()と.to_mov()にはPATH上かQUICKTHUMB_FFMPEGで指定したffmpegが必要です。

gif_bytes = deck.to_gif(fps=20, hold=3.0, loop=0, matte="#000000")
webm_bytes = deck.to_webm(fps=30, hold=3.0)
overlay_bytes = deck.to_webm(fps=30, hold=3.0, transparent=True)

全アニメーションバイトメソッドはキーワード専用のworkers=1とrender_quality="standard"を受け付けます。"high"はスーパーサンプリングです。.to_gif()は比率を保つmax_size=None、パレットのcolors=None（指定時2–256）も受け付けます。既存の位置引数は変わりません。

これらは.to_mp4()でも使えます。静止ナレーションには静的CanvasとCut()を使います。ファイルオプションとバイトメソッドはどちらもholdを使います。ナレーションも明示的な長さもないスライドがある場合、動画には正の既定保持時間が必要です。Deck GIFと無音の画像シーケンスでは0も有効です。Deck GIFはスライドごとのナレーションと明示長を無視します。

.to_webm()と.to_mov()のキーワード専用transparentは出力マットだけを省き、作成した背景は残ります。コーデック、アルファのデコード、切り替えは透過WebMを参照してください。

.to_mov()は.to_webm()と同じパラメーターと時間で、ProRes 4444映像とAAC音声に固定されます。奇数や1ピクセルの寸法も保ちます。RGBAソースは8ビットです。16ビットのアルファ符号化はデコード後の8ビット値に1段階の差を生むことがあり、色は損失のある4:4:4 YUVです。変換の限界と要件はProRes MOVを参照してください。render()とexport()は不透明・透明の両方でVideoOptionsと.movを受け付けます。

.export_image_sequence(output_directory, *, format="png", quality=None, matte=None, lossless=None, options=None, policy=None)

既存の親の下の新しいディレクトリへ、アニメーションを独立したPNG（既定）、JPEG、WebPとmanifest.jsonで保存します。ImageSequenceOptions(fps=30, hold=3, workers=1, render_quality="standard")で時間と合成を、メソッドのキーワードで画像符号化を選びます。JPEGは不透明マット（既定白）のRGBでquality=1..95です。WebPはアルファとlossless=Trueをサポートし、損失WebPでは品質を指定できます。PNGと無損失WebPはレンダラーのRGBA8を正確に保ちます。不透明WebPがRGBで開かれる場合もあり、マニフェストのモードは論理的なRGBAデコードを表します。実際のフレーム数、時間、符号化、保存先を報告します。検証、形式別情報、上書きしないアトミックな公開は画像シーケンスを参照してください。

.to_mp4(...)

.to_webm()と同じアニメーションをH.264 MP4で返します。予定されたスライド別ナレーションと任意のミックス音楽を含みます。MP4/WebM/MOVはDeckあたりナレーション付きスライド最大64枚です。無音スライドはこのFFmpeg入力数の運用制限に含めません。

ファイル出力にはdeck.export("deck.mp4", animation=VideoOptions(soundtrack=AudioTrack(path="music.mp3", loop=True)))を使います。各スライドのaudioナレーションと音楽を描画中にミックスします。オプションなしのdeck.export("deck.mp4")も、既定のVideoOptions()で同じタイムラインを使います。

.diagnose()

各スライドのCanvas.diagnose()をまとめ、Deck全体の検査を加えます。findingsにDeckDiagnosticを格納するDiagnosticReportを返します。

for finding in deck.diagnose().findings:
    print(finding.slide_index, finding.code, finding.message)
フィールド 型 説明
code str スライドのコード（off-canvas、tiny-textなど）かmixed-slide-sizeです。
severity str "warning"か"error"です。
message str 人が読む説明です。
slide_index int \| None 該当スライド。Deck全体ならNoneです。
layer_index int \| None 該当する場合のスライド内レイヤーです。
layer_id str \| None グループの子を含む、発生元レイヤーの安定したIDです。
layer_name str \| None 存在する場合の発生元レイヤー名です。
bbox dict \| None キャンバス座標で測定した境界です。
related_layers list[str] 指摘に関係するレイヤーIDです。
measured dict 規則ごとの測定値です。
suggestion str \| None 利用できる場合の修正ヒントです。

サイズが揃っていないとmixed-slide-size警告になります。PDFはページごとのサイズですが、PPTXは最初のスライドのサイズを全体へ使うため、後ろの大きなスライドがPowerPointで切れます。.pptxではサイズを揃えてください。

.prefetch_assets()（任意）

Canvas.prefetch_assets()と同様、全スライドのリモートアセットを事前取得し、Deck全体のasset_manifestを返します。描画と出力自体が取得するので、長い処理の前に通信失敗や期限切れを確認したい場合だけ呼んでください。

JSON

.to_json() / Deck.from_json(json_str)

各Canvasのシリアライズを再利用し、正規JSONを往復します。形式は{"kind": "deck", "width": ..., "height": ..., "theme": {...}, "slides": [<canvas spec>, ...]}で、各スライドも"kind": "canvas"を持ちます。既定サイズのwidth/heightとthemeは設定時だけ出力します。Deckに既定サイズがあればJSONのスライドは寸法を省略でき、正規保存では継承した値を具体化します。スライド別のtransition、audio、duration、notesもCanvasのフィールドとともに維持します。最上位のthemeは全スライドで共有し、Canvas.from_jsonと同じように$theme.*を参照できます。

spec = deck.to_json()
restored = Deck.from_json(spec)

補足

Canvas.to_json()と同様、.custom(fn)を含むスライドはコールバックを登録しなければ保存できません。from_json()はdictではなくJSON文字列を受け付けます。