Implementation:Farama Foundation Gymnasium Save Video

Knowledge Sources	Gymnasium Gymnasium Utils
Domains	Reinforcement_Learning, Visualization
Last Updated	2026-02-15 03:00 GMT

Overview

Concrete tool for saving pre-collected render frames as video files provided by the Gymnasium library.

Description

The save_video function creates MP4 video files from lists of rendered frames using MoviePy's ImageSequenceClip. It supports episode-triggered and step-triggered saving, configurable video length, and custom filename prefixes.

Usage

Call save_video with collected frames from env.render() (in rgb_array_list mode) after episode completion. Pass fps from env.metadata["render_fps"] for correct playback speed.

Code Reference

Source Location

• Repository: Gymnasium
• File: gymnasium/utils/save_video.py
• Lines: L36-117

Signature

def save_video(
    frames: list,
    video_folder: str,
    episode_trigger: Callable[[int], bool] = None,
    step_trigger: Callable[[int], bool] = None,
    video_length: int | None = None,
    name_prefix: str = "rl-video",
    episode_index: int = 0,
    step_starting_index: int = 0,
    save_logger: str | None = None,
    **kwargs,
):
    """Save videos from rendering frames.

    Args:
        frames: List of render frames (RGB arrays).
        video_folder: Directory to save videos.
        episode_trigger: Function(episode_id) -> bool for recording.
        step_trigger: Function(step_id) -> bool for recording.
        video_length: Max frames per video clip.
        name_prefix: Video filename prefix.
        episode_index: Current episode index.
        step_starting_index: Step index of the first frame.
        save_logger: Logger mode ("bar" for progress bar).
        **kwargs: Passed to MoviePy ImageSequenceClip.
    """

Import

from gymnasium.utils.save_video import save_video

I/O Contract

Inputs

Name	Type	Required	Description
frames	list	Yes	List of RGB array frames
video_folder	str	Yes	Output directory
fps	int	Yes (via kwargs)	Frames per second for the video
episode_index	int	No	Current episode number (default 0)

Outputs

Name	Type	Description
video file	.mp4	Saved to video_folder with name_prefix

Usage Examples

Save Episode Video

import gymnasium as gym
from gymnasium.utils.save_video import save_video

env = gym.make("FrozenLake-v1", render_mode="rgb_array_list")
obs, info = env.reset()

terminated, truncated = False, False
while not (terminated or truncated):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)

# Get all accumulated frames
frames = env.render()

# Save as video
save_video(
    frames=frames,
    video_folder="./videos",
    fps=env.metadata["render_fps"],
    episode_index=0,
)
env.close()

Related Pages

Implements Principle

• Principle:Farama_Foundation_Gymnasium_Video_Frame_Saving

Requires Environment

• Environment:Farama_Foundation_Gymnasium_Video_Recording_Dependencies