bevy-capture

bevy-capture — Bevy 0.19 のカメラ録画

このスキルを使う場面

• 決定論的なゲームプレイ、シネマティクス、またはレンダリングテストの証拠を記録する場合。
• ヘッドレスな Camera2d／Camera3d を MP4、GIF、または連番 PNG にキャプチャする場合。
• プロセス内の OpenH264、ffmpeg、可逆フレーム出力から選ぶ場合。
• エンコーダーモジュールが見つからない、出力が空、または録画がフラッシュされないといった問題を診断する場合。

bevy_capture = "0.6" は Bevy 0.19 をネイティブに対象としています。0.4.x の Bevy パッチや、古い CameraTargetHeadless API を引き継がないでください。

標準的なパターン

[dependencies]
bevy = "0.19"
bevy_capture = { version = "0.6", features = ["mp4_openh264"] }

use bevy::{
    app::{RunMode, ScheduleRunnerPlugin},
    camera::RenderTarget,
    prelude::*,
    render::RenderPlugin,
    winit::WinitPlugin,
};
use bevy_capture::{
    encoder::mp4_openh264::Mp4Openh264Encoder,
    Capture, CaptureBundle, CapturePlugin, RenderTargetHeadless,
};
use std::fs::{self, File};

const WIDTH: u16 = 1280;
const HEIGHT: u16 = 720;

fn main() -> AppExit {
    App::new()
        .add_plugins((
            DefaultPlugins.build().disable::<WinitPlugin>().set(RenderPlugin {
                synchronous_pipeline_compilation: true,
                ..default()
            }),
            ScheduleRunnerPlugin {
                run_mode: RunMode::Loop { wait: None },
            },
            CapturePlugin,
        ))
        .add_systems(Startup, setup)
        .add_systems(Update, record)
        .run()
}

fn setup(mut commands: Commands, mut images: ResMut<Assets<Image>>) {
    commands.spawn((
        Camera2d,
        RenderTarget::target_headless(WIDTH.into(), HEIGHT.into(), &mut images),
        CaptureBundle::default(),
    ));
}

fn record(
    mut captures: Query<&mut Capture>,
    mut waited_for_pipeline: Local<bool>,
    mut frame: Local<u32>,
) {
    // Allow the render pipeline one frame to become ready.
    if !*waited_for_pipeline {
        *waited_for_pipeline = true;
        return;
    }

    let Ok(mut capture) = captures.single_mut() else { return };
    if !capture.is_capturing() && *frame == 0 {
        fs::create_dir_all("captures").expect("create captures directory");
        let encoder = Mp4Openh264Encoder::new(
            File::create("captures/run.mp4").expect("create output"),
            WIDTH,
            HEIGHT,
        )
        .expect("initialize OpenH264");
        capture.start(encoder);
    }

    *frame += 1;
    if *frame == 300 {
        capture.stop(); // drops the encoder and finalizes the MP4
    }
}

エンコーダーの選択

エンコーダー	フィーチャー	外部プログラム	最適な用途
Mp4Openh264Encoder	mp4_openh264	いいえ	プロセス内の H.264
Mp4FfmpegCliEncoder	mp4_ffmpeg_cli	ffmpeg	短い／オフラインのクリップ
Mp4FfmpegCliPipeEncoder	mp4_ffmpeg_cli_pipe	ffmpeg	長時間のストリーミングキャプチャ
GifEncoder	gif	いいえ	小さなプレビュー
FramesEncoder	なし	いいえ	可逆の PNG シーケンス

本番用のコーデックや配布モデルを選ぶ前に、エンコーダーの詳細を参照してください。

注意点

• RenderTargetHeadless は RenderTarget に実装されています。RenderTarget::target_headless(...) を呼び出してください。Camera の古いヘルパーは現在は使われていません。
• Camera2d／Camera3d、ヘッドレスの RenderTarget、CaptureBundle を同じエンティティにアタッチしてください。
• 開始前に少なくとも 1 フレーム待機してください。同期的なパイプラインコンパイルにより、決定論的なバッチキャプチャの品質は向上しますが、起動時間が長くなる場合があります。
• エンコーダーモジュールはフィーチャーによって有効化されます。インポートするフィーチャーだけを有効にしてください。
• Capture::stop() を呼び出すか Capture をドロップすると、エンコーダーがファイナライズされます。プロセスを突然終了すると、無効な MP4 や GIF が残ることがあります。
• ffmpeg エンコーダーには PATH 上の ffmpeg が必要です。コンストラクターは Result を返します。
• エンコーダーの寸法をヘッドレスタ―ゲットに合わせてください。OpenH264 が受け取る値は u16 です。
• ブラウザーの WASM には通常のファイルシステムや子プロセスがありません。これらのエンコーダーが動作すると想定するのではなく、明示的な JS ダウンロード／ストリーミング経路を設計してください。

関連項目

• bevy-cameras — カメラとレンダーターゲット。
• bevy-cargo-features — フィーチャーの選択。
• bevy-wasm-webgpu — ブラウザーの制約。
• エンコーダーの比較。
• 0.19 との互換性。