Principle:CARLA simulator Carla Recording Introspection
| Knowledge Sources | |
|---|---|
| Domains | Simulation, Recording |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Recording introspection enables querying the metadata and contents of a recorded simulation file without replaying it, providing fast access to actor inventories, event timelines, and recording statistics.
Description
After a recording session has been finalized, the resulting binary log file contains a wealth of structured data about the simulation that was captured. Recording introspection refers to the ability to parse and query this data without performing a full replay. This is analogous to reading the table of contents and index of a book rather than reading it cover to cover.
Introspection provides information such as:
- Actor inventory: A complete list of all actors that appeared during the recording, including their type (vehicle, walker, traffic light), unique ID, and the frames at which they were spawned and destroyed.
- Event timeline: A chronological list of significant events such as actor spawns, actor destructions, and traffic light state changes.
- Recording statistics: Total duration, total number of frames, frame rate, and map name.
- Per-frame summaries: When verbose mode is enabled, detailed per-frame data including actor positions and states.
This information enables users to make informed decisions about which portions of a recording to replay, which actors to follow, and what time windows contain events of interest -- all without the computational cost of a full replay.
Usage
Use recording introspection when you need to:
- Preview a recording to understand its contents before committing to a full replay.
- Locate specific events such as when a particular vehicle was spawned or destroyed.
- Verify recording completeness by checking frame counts and duration against expected values.
- Select replay parameters by identifying the time ranges and actor IDs of interest.
- Catalog recordings in an automated pipeline by extracting metadata from multiple recording files.
Theoretical Basis
Recording introspection is an application of metadata indexing in temporal data stores. The CARLA recording format organizes data into typed event records (spawn, destroy, transform, state) with frame-level timestamps. The introspection API performs a sequential scan of these records, building an in-memory summary without instantiating any simulation actors or performing physics calculations.
This approach follows the read-only query paradigm: the recording file is treated as an immutable data source, and introspection operations extract information without modifying the file or the simulation state. The cost of introspection is proportional to the size of the recording file (linear scan) but is significantly cheaper than replay because it avoids actor instantiation, rendering, and physics simulation.
The two verbosity levels (summary vs. full) implement a progressive disclosure model. The summary mode extracts only event-level data (spawns, destroys, and frame boundaries), while the full mode additionally parses per-frame transform and state data. This allows users to quickly scan a recording's high-level structure and then drill into frame-level details only when needed.