Playwrightの画面録画がカクカクする原因と対処──headlessのソフトウェアレンダリングを疑う

Playwrightでブラウザゲームやアニメーションの多い画面を録画するとカクカクの紙芝居になる——その主因になりやすいのが、headlessモード（画面を表示せずにブラウザを動かすモード）ではGPUが使われず、CPUによるソフトウェア描画（WebGLはSwiftShaderが代行）になることです。対処の本命は「headless=Falseで実GPUを使って録画する」こと。あわせてrecord_video_sizeとviewport（ブラウザの表示領域サイズ）を最終解像度で一致させると、引き伸ばしによる画質劣化も防げます。この記事では原因と設定手順、録画中の注意点までを解説します。

• headlessモードはCPUによるソフトウェア描画（WebGLはSwiftShader）になりやすく、動きの多い画面の録画は紙芝居化しやすい
• 対処の本命はheadless=False＋実GPU。ただし改善幅は環境に依存する
• record_video_sizeとviewportは最終的に使う解像度で一致させる。小さく録って引き伸ばすと画質が劣化する

なぜheadlessの録画はカクカクになるのか

Chromiumは、ヘッドレス環境やGPUが使えない環境では、GPU支援のないソフトウェア描画（CPU処理）に切り替わります。特にWebGLはSwiftShaderというソフトウェアレンダラーが代行します（Chromium公式ドキュメント）。本来GPUが並列処理でこなす毎フレームの描画をCPUが肩代わりするため、CanvasゲームやCSSアニメーションのように「毎フレーム画面全体が動く」ページでは描画が追いつかず、フレームが飛びます。録画はその飛んだ状態をそのまま記録するので、再生すると紙芝居のようなカクつきになります。

headlessモードでGPUハードウェアを使えるようにする取り組みはChromium側でもissueとして追跡されてきましたが、環境によって効く・効かないの差が大きいのが実情です。

対処A: headless=Falseで実GPUを使って録画する

headedモード（実際にウィンドウを表示するモード）で起動すると、通常のChromeと同じく実GPUで描画されるため、フレーム落ちが減ります。録画品質を優先するなら、まずこれを試すのが早道です。

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)  # 実GPUで描画する
    context = browser.new_context(
        viewport={"width": 1920, "height": 1080},
        record_video_dir="videos/",
        record_video_size={"width": 1920, "height": 1080},
    )
    page = context.new_page()
    # ...操作...
    context.close()  # 録画はコンテキストを閉じた時点で保存される

対処B: headlessのまま運用したい場合

CIサーバーなど画面のない環境では、そのままではheadedで起動できません（Linuxならxvfbなどの仮想ディスプレイを使えばheaded起動自体は可能ですが、仮想ディスプレイ上では実GPUが効くわけではなく、録画品質の根本解決にはなりにくいです）。その場合は「動きの少ない画面に録画を限定する」「テスト証跡と割り切ってカクつきを許容する」という選択になります。headlessでのGPU利用は前述の通り環境依存が強く、確実な解決策と言える段階ではありません。映像としての録画品質が目的なら、画面のあるマシンでheadedで撮る方が確実です。

record_video_sizeとviewportは最終解像度で一致させる

Playwright公式ドキュメントによると、record_video_sizeを指定しない場合、録画サイズは「viewportを800x800に収まるよう縮小したサイズ」になります。つまり何も指定しないと小さめの解像度で録画され、それを動画編集で引き伸ばすと画質が劣化します。

最終的に使う解像度（例として1920x1080で出力したい場合）が決まっているなら、上のコード例のようにviewportとrecord_video_sizeの両方をその解像度に揃えます。小さく録って後から拡大するより、最初からネイティブ解像度で録る方が仕上がりはきれいです。

録画中のウィンドウに人間が触らない

headedモードでは実際のウィンドウが画面に出ます。録画中にうっかりそのウィンドウをクリックしたりスクロールしたりすると、人間の操作がPlaywrightの自動操作に混ざり、そのまま録画に残ります。録画が走っている間はウィンドウに触らない、可能なら別の仮想デスクトップに置いておくのが安全です。

筆者の現場から

自作のブラウザゲーム（制作の経緯はClaude Codeで初心者がゲームを作った記録にまとめています）のプレイ映像を収録したとき、まさにこの問題を踏みました。headlessで録画したプレイ映像が紙芝居になっていて、結局全部録り直しに。その後、headless=Falseに切り替え、あわせてviewportと録画サイズをネイティブ解像度で一致させる設定にしてからは、録画は安定しています。

原因はSwiftShaderだけとは限らない

• カクつきの原因はSwiftShaderだけとは限りません。マシンの負荷、ページ側の実装、録画解像度の高さなど複数の要因が絡みます。本記事は「まず疑う場所」としてheadlessの描画方式を挙げていますが、環境ごとの切り分けは必要です。
• headed＋実GPUでも、描画負荷の高いシーンではフレーム落ちは起こりえます。滑らかになる保証はありません。
• SwiftShaderの扱いはChromium側で変更が進んでおり（WebGLフォールバックを廃止する方針が公表されています）、バージョンによって挙動が変わる可能性があります。
• Playwrightのrecord_videoはもともとテストの証跡を残す用途が主眼で、映像作品レベルの収録に最適化された機能ではありません。結果はOSやGPUなど環境に依存します。

PlaywrightとChromiumの公式ドキュメント

• Videos | Playwright
• Videos | Playwright Python
• Chromium Docs - Using Chromium with SwiftShader
• Support GPU hardware in headless mode (Chromium Issue Tracker)