# abstractmachine/head-irad-playable-cinema architecture

> Architecture diagram of the GitHub repository abstractmachine/head-irad-playable-cinema, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abstractmachine/head-irad-playable-cinema
- Repository: https://github.com/abstractmachine/head-irad-playable-cinema

## Overview

Playable Cinema is a research project for connecting gameplay with historical film; its software includes Crossing Tool for training and playback, plus a separate Nickelodeon playback application. The map highlights media identity and annotation, frame matching and search, visual analysis, and engraving, alongside playback. The sampled references show several data and service dependencies, but not the full CLI or visualization wiring; those links are omitted where evidence is unavailable.

Main entry points: [`code/crossing-tool/services/frame_match.py`](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/frame_match.py) (Frame Matching), [`code/crossing-tool/data/metadata.py`](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/metadata.py) (Media Metadata), [`code/playable-nickelodeon/app.py`](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/app.py) (Nickelodeon App), [`code/crossing-tool/data/annotate.py`](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/annotate.py) (Shot Annotation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_crossing["Crossing Tool"]
  node_crossing_cli["Crossing CLI<br/>[cli.py]"]
  node_visualizer_launcher["Visualizer Launcher<br/>[launcher.py]"]
  node_sync_visualizer["Sync Visualizer<br/>[sync_visualizer.py]"]
  node_mcp_server["MCP Server<br/>[mcp_server.py]"]
end

subgraph group_media["Media and Annotation"]
  node_metadata["Media Metadata<br/>[metadata.py]"]
  node_media_identity["Media Identity<br/>[media_id.py]"]
  node_shotlists["Shotlists<br/>[shotlist.py]"]
  node_annotation["Shot Annotation<br/>[annotate.py]"]
  node_resource_locations["Resource Locations"]
  node_resource_storage[("Resource Registry")]
end

subgraph group_analysis["Analysis and Generation"]
  node_frame_match["Frame Matching<br/>[frame_match.py]"]
  node_frame_retrieval["Frame Retrieval<br/>[frame_retrieval.py]"]
  node_shot_search["Shot Search<br/>[search.py]"]
  node_scene_detection["Scene Detection<br/>[scene_detection.py]"]
  node_generators["Visual Generators"]
  node_engraving_pipeline["Engraving Pipeline"]
end

subgraph group_playback["Playback"]
  node_nickelodeon_app["Nickelodeon App<br/>[app.py]"]
  node_cinematheque["Film Catalog<br/>[cinematheque.py]"]
  node_player["Media Player<br/>[player.py]"]
  node_switcher["Playback Switcher<br/>[switcher.py]"]
  node_control_server["Control Server<br/>[server.py]"]
end

node_researcher(("Researcher"))

node_researcher -.->|"uses"| node_crossing_cli
node_metadata -->|"computes IDs"| node_media_identity
node_metadata -->|"uses registry"| node_resource_storage
node_metadata -->|"resolves paths"| node_resource_locations
node_annotation -->|"uses registry"| node_resource_storage
node_annotation -->|"resolves paths"| node_resource_locations
node_annotation -->|"updates"| node_shotlists
node_frame_match -->|"reads and updates"| node_annotation
node_frame_match -->|"reads"| node_metadata
node_frame_match -->|"reads"| node_shotlists
node_frame_match -->|"resolves paths"| node_resource_locations
node_frame_match -->|"uses registry"| node_resource_storage
node_frame_retrieval -->|"calls"| node_frame_match
node_frame_retrieval -->|"calls"| node_shot_search
node_frame_retrieval -->|"uses mosaic"| node_generators
node_sync_visualizer -->|"uses"| node_frame_match
node_sync_visualizer -->|"reads"| node_metadata
node_sync_visualizer -->|"uses"| node_media_identity
node_nickelodeon_app -->|"uses"| node_cinematheque
node_nickelodeon_app -->|"uses"| node_switcher
node_nickelodeon_app -->|"uses"| node_player
node_nickelodeon_app -->|"uses"| node_control_server
node_player -->|"reads catalog"| node_cinematheque
node_player -->|"uses"| node_switcher
node_switcher -->|"reads catalog"| node_cinematheque
node_control_server -->|"gets films"| node_cinematheque

click node_crossing_cli "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/cli.py"
click node_visualizer_launcher "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/visualizers/launcher.py"
click node_sync_visualizer "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/visualizers/sync_visualizer.py"
click node_metadata "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/metadata.py"
click node_media_identity "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/media_id.py"
click node_shotlists "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/shotlist.py"
click node_annotation "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/annotate.py"
click node_resource_locations "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/resource_locations.py"
click node_resource_storage "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/resource_storage.py"
click node_frame_match "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/frame_match.py"
click node_frame_retrieval "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/frame_retrieval.py"
click node_shot_search "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/search.py"
click node_scene_detection "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/scene_detection.py"
click node_generators "https://github.com/abstractmachine/head-irad-playable-cinema/tree/main/code/crossing-tool/generators"
click node_engraving_pipeline "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/engraving_local_pipeline.py"
click node_mcp_server "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/mcp_server/mcp_server.py"
click node_nickelodeon_app "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/app.py"
click node_cinematheque "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/cinematheque.py"
click node_player "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/player.py"
click node_switcher "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/switcher.py"
click node_control_server "https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/server.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_crossing_cli,node_visualizer_launcher,node_sync_visualizer,node_mcp_server toneBlue
class node_metadata,node_media_identity,node_shotlists,node_annotation,node_resource_locations,node_resource_storage toneAmber
class node_frame_match,node_frame_retrieval,node_shot_search,node_scene_detection,node_generators,node_engraving_pipeline toneMint
class node_nickelodeon_app,node_cinematheque,node_player,node_switcher,node_control_server toneRose
class node_researcher toneIndigo
```

## Components

### Crossing Tool

- [Crossing CLI](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/cli.py): `code/crossing-tool/cli.py`
- [Visualizer Launcher](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/visualizers/launcher.py): `code/crossing-tool/visualizers/launcher.py`
- [Sync Visualizer](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/visualizers/sync_visualizer.py): `code/crossing-tool/visualizers/sync_visualizer.py`
- [MCP Server](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/mcp_server/mcp_server.py): `code/crossing-tool/mcp_server/mcp_server.py`

### Media and Annotation

- [Media Metadata](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/metadata.py): `code/crossing-tool/data/metadata.py`
- [Media Identity](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/media_id.py): `code/crossing-tool/data/media_id.py`
- [Shotlists](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/shotlist.py): `code/crossing-tool/data/shotlist.py`
- [Shot Annotation](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/annotate.py): `code/crossing-tool/data/annotate.py`
- [Resource Locations](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/resource_locations.py): `code/crossing-tool/data/resource_locations.py`
- [Resource Registry](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/data/resource_storage.py): `code/crossing-tool/data/resource_storage.py`

### Analysis and Generation

- [Frame Matching](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/frame_match.py): `code/crossing-tool/services/frame_match.py`
- [Frame Retrieval](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/frame_retrieval.py): `code/crossing-tool/services/frame_retrieval.py`
- [Shot Search](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/search.py): `code/crossing-tool/services/search.py`
- [Scene Detection](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/scene_detection.py): `code/crossing-tool/services/scene_detection.py`
- [Visual Generators](https://github.com/abstractmachine/head-irad-playable-cinema/tree/main/code/crossing-tool/generators): `code/crossing-tool/generators`
- [Engraving Pipeline](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/crossing-tool/services/engraving_local_pipeline.py): `code/crossing-tool/services/engraving_local_pipeline.py`

### Playback

- [Nickelodeon App](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/app.py): `code/playable-nickelodeon/app.py`
- [Film Catalog](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/cinematheque.py): `code/playable-nickelodeon/cinematheque.py`
- [Media Player](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/player.py): `code/playable-nickelodeon/player.py`
- [Playback Switcher](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/switcher.py): `code/playable-nickelodeon/switcher.py`
- [Control Server](https://github.com/abstractmachine/head-irad-playable-cinema/blob/main/code/playable-nickelodeon/server.py): `code/playable-nickelodeon/server.py`

### Other components

- **Researcher**

## Connections

- Researcher → Crossing CLI: uses
- Media Metadata → Media Identity: computes IDs (evidence: `code/crossing-tool/data/metadata.py`)
- Media Metadata → Resource Registry: uses registry (evidence: `code/crossing-tool/data/metadata.py`)
- Media Metadata → Resource Locations: resolves paths (evidence: `code/crossing-tool/data/metadata.py`)
- Shot Annotation → Resource Registry: uses registry (evidence: `code/crossing-tool/data/annotate.py`)
- Shot Annotation → Resource Locations: resolves paths (evidence: `code/crossing-tool/data/annotate.py`)
- Shot Annotation → Shotlists: updates (evidence: `code/crossing-tool/data/annotate.py`)
- Frame Matching → Shot Annotation: reads and updates (evidence: `code/crossing-tool/services/frame_match.py`)
- Frame Matching → Media Metadata: reads (evidence: `code/crossing-tool/services/frame_match.py`)
- Frame Matching → Shotlists: reads (evidence: `code/crossing-tool/services/frame_match.py`)
- Frame Matching → Resource Locations: resolves paths (evidence: `code/crossing-tool/services/frame_match.py`)
- Frame Matching → Resource Registry: uses registry (evidence: `code/crossing-tool/services/frame_match.py`)
- Frame Retrieval → Frame Matching: calls (evidence: `code/crossing-tool/services/frame_retrieval.py`)
- Frame Retrieval → Shot Search: calls (evidence: `code/crossing-tool/services/frame_retrieval.py`)
- Frame Retrieval → Visual Generators: uses mosaic (evidence: `code/crossing-tool/services/frame_retrieval.py`)
- Sync Visualizer → Frame Matching: uses (evidence: `code/crossing-tool/visualizers/sync_visualizer.py`)
- Sync Visualizer → Media Metadata: reads (evidence: `code/crossing-tool/visualizers/sync_visualizer.py`)
- Sync Visualizer → Media Identity: uses (evidence: `code/crossing-tool/visualizers/sync_visualizer.py`)
- Nickelodeon App → Film Catalog: uses (evidence: `code/playable-nickelodeon/app.py`)
- Nickelodeon App → Playback Switcher: uses (evidence: `code/playable-nickelodeon/app.py`)
- Nickelodeon App → Media Player: uses (evidence: `code/playable-nickelodeon/app.py`)
- Nickelodeon App → Control Server: uses (evidence: `code/playable-nickelodeon/app.py`)
- Media Player → Film Catalog: reads catalog (evidence: `code/playable-nickelodeon/player.py`)
- Media Player → Playback Switcher: uses (evidence: `code/playable-nickelodeon/player.py`)
- Playback Switcher → Film Catalog: reads catalog (evidence: `code/playable-nickelodeon/switcher.py`)
- Control Server → Film Catalog: gets films (evidence: `code/playable-nickelodeon/server.py`)
