# google/mediapy architecture

> Architecture diagram of the GitHub repository google/mediapy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/mediapy
- Repository: https://github.com/google/mediapy

## Overview

mediapy is a Python library for reading, writing, transforming, and displaying images and videos in IPython/Jupyter notebooks. The main user workflow is to provide arrays or media paths, optionally transform media, then save it or render it in notebook output. Video file I/O relies on external ffmpeg. The implementation is concentrated in one large module; the graph separates its principal API responsibilities. Relationships follow the README examples and the sampled module excerpt; unsampled internals are not assumed to call one another.

Main entry points: [`mediapy/__init__.py`](https://github.com/google/mediapy/blob/main/mediapy/__init__.py) (Read videos)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_image["Image workflows"]
  node_image_read["Read images<br/>[__init__.py]"]
  node_image_write["Write images<br/>[__init__.py]"]
  node_image_transform["Image transforms<br/>[__init__.py]"]
  node_image_compress["Image compression<br/>[__init__.py]"]
end

subgraph group_video["Video workflows"]
  node_video_read["Read videos<br/>[__init__.py]"]
  node_video_reader["VideoReader<br/>[__init__.py]"]
  node_video_write["Write videos<br/>[__init__.py]"]
  node_video_writer["VideoWriter<br/>[__init__.py]"]
  node_video_transform["Video transforms<br/>[__init__.py]"]
end

subgraph group_shared["Shared media tools"]
  node_generators["Media generators<br/>[__init__.py]"]
  node_format_convert["Format conversion<br/>[__init__.py]"]
end

subgraph group_notebook["Notebook display"]
  node_image_display["Show images<br/>[__init__.py]"]
  node_image_compare["Compare images<br/>[__init__.py]"]
  node_video_display["Show videos<br/>[__init__.py]"]
  node_multi_display["Multi-video display<br/>[__init__.py]"]
end

node_user(("Python user"))
node_ffmpeg["ffmpeg"]
node_notebook_runtime(("IPython/Jupyter"))
node_media_source(("Media paths or URLs"))

node_user -->|"requests read"| node_image_read
node_media_source -->|"supplies path"| node_image_read
node_image_read -->|"resize example"| node_image_transform
node_image_transform -->|"displays result"| node_image_display
node_user -->|"requests write"| node_image_write
node_user -->|"requests display"| node_image_display
node_user -->|"requests comparison"| node_image_compare
node_user -->|"requests read"| node_video_read
node_media_source -->|"supplies path"| node_video_read
node_video_read -->|"resize example"| node_video_transform
node_video_transform -->|"displays result"| node_video_display
node_user -->|"requests write"| node_video_write
node_user -->|"requests playback"| node_video_display
node_user -->|"opens reader"| node_video_reader
node_user -->|"opens writer"| node_video_writer
node_video_reader -->|"streams frames"| node_video_writer
node_video_read -->|"decodes video"| node_ffmpeg
node_video_write -->|"encodes video"| node_ffmpeg
node_user -->|"requests display"| node_multi_display
node_user -->|"creates media"| node_generators
node_user -->|"converts formats"| node_format_convert
node_image_display -->|"renders output"| node_notebook_runtime
node_image_compare -->|"renders comparison"| node_notebook_runtime
node_video_display -->|"renders playback"| node_notebook_runtime
node_multi_display -->|"renders output"| node_notebook_runtime
node_image_compress -->|"compresses for display"| node_image_display

click node_image_read "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_image_write "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_image_transform "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_image_compress "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_image_display "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_image_compare "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_video_read "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_video_reader "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_video_write "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_video_writer "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_video_transform "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_video_display "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_multi_display "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_generators "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"
click node_format_convert "https://github.com/google/mediapy/blob/main/mediapy/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_image_read,node_image_write,node_image_transform,node_image_compress,node_user toneBlue
class node_video_read,node_video_reader,node_video_write,node_video_writer,node_video_transform toneAmber
class node_generators,node_format_convert toneMint
class node_image_display,node_image_compare,node_video_display,node_multi_display toneRose
class node_ffmpeg,node_notebook_runtime,node_media_source toneIndigo
```

## Components

### Image workflows

- [Read images](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [Write images](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [Image transforms](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [Image compression](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`

### Video workflows

- [Read videos](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [VideoReader](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [Write videos](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [VideoWriter](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [Video transforms](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`

### Shared media tools

- [Media generators](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [Format conversion](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`

### Notebook display

- [Show images](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [Compare images](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [Show videos](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`
- [Multi-video display](https://github.com/google/mediapy/blob/main/mediapy/__init__.py): `mediapy/__init__.py`

### Other components

- **Python user**
- **ffmpeg**
- **IPython/Jupyter**
- **Media paths or URLs**

## Connections

- Python user → Read images: requests read (evidence: `README.md`)
- Media paths or URLs → Read images: supplies path (evidence: `README.md`)
- Read images → Image transforms: resize example (evidence: `mediapy_examples.py`)
- Image transforms → Show images: displays result (evidence: `mediapy_examples.py`)
- Python user → Write images: requests write (evidence: `README.md`)
- Python user → Show images: requests display (evidence: `README.md`)
- Python user → Compare images: requests comparison
- Python user → Read videos: requests read (evidence: `README.md`)
- Media paths or URLs → Read videos: supplies path (evidence: `README.md`)
- Read videos → Video transforms: resize example (evidence: `mediapy_examples.py`)
- Video transforms → Show videos: displays result (evidence: `mediapy_examples.py`)
- Python user → Write videos: requests write (evidence: `README.md`)
- Python user → Show videos: requests playback (evidence: `README.md`)
- Python user → VideoReader: opens reader (evidence: `README.md`)
- Python user → VideoWriter: opens writer (evidence: `README.md`)
- VideoReader → VideoWriter: streams frames (evidence: `README.md`)
- Read videos → ffmpeg: decodes video (evidence: `README.md`)
- Write videos → ffmpeg: encodes video (evidence: `README.md`)
- Python user → Multi-video display: requests display
- Python user → Media generators: creates media (evidence: `README.md`)
- Python user → Format conversion: converts formats
- Show images → IPython/Jupyter: renders output (evidence: `README.md`)
- Compare images → IPython/Jupyter: renders comparison (evidence: `mediapy/__init__.py`)
- Show videos → IPython/Jupyter: renders playback (evidence: `README.md`)
- Multi-video display → IPython/Jupyter: renders output
- Image compression → Show images: compresses for display (evidence: `mediapy/__init__.py`)
