Stats
Actions
Tags
From video
Complete reference for log processing output data formats, feather file discovery, frame statistics analysis, and interpretation guidance. Use when evaluating log processing results, when the user asks about frame timing data, frame drops, or camera acquisition quality.
How this skill is triggered — by the user, by Claude, or both
Slash command
/video:log-processing-resultsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Complete output data format documentation for the camera timestamp extraction pipeline. Covers feather file
Complete output data format documentation for the camera timestamp extraction pipeline. Covers feather file discovery, schema reference, frame statistics analysis, and interpretation guidance for discussing results with users.
Covers:
Does not cover:
/log-input-format)/log-processing)/camera-setup)/camera-interface)/mcp-environment-setup)| Tool | Purpose |
|---|---|
discover_camera_data_tool | Discovers manifests, log archives, video files, and feather files under a root dir |
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
root_directory | str | (required) | Absolute path to root directory to search for manifests |
This tool uses manifest-based routing: it searches for camera_manifest.yaml files, then for each
manifest source locates the corresponding log archive, video file, and processed timestamp feather
output. Each source entry in the response includes a timestamps_file field (path to the feather
file, or null if not yet processed).
| Tool | Purpose |
|---|---|
analyze_camera_frame_statistics_tool | Computes frame timing stats and detects frame drops from feather files |
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
feather_files | list[str] | (required) | Absolute paths to camera_*_timestamps.feather files |
drop_threshold_us | int | 0 | Gap threshold in microseconds; 0 for auto-detection (2x median) |
max_drop_locations | int | 50 | Maximum number of frame drop locations to include per file |
Returns a dictionary with a results list (one entry per file, each containing file, basic_stats,
inter_frame_timing, and frame_drop_analysis keys) and a total_files count. Files that cannot be
read produce an entry with file and error keys instead of statistics.
discover_camera_data_tool — Find all manifests, archives, video files, and feather files under
the root directory. Each source entry includes a timestamps_file path when processing is complete.analyze_camera_frame_statistics_tool — Compute statistics for discovered feather files. Pass the
timestamps_file paths from the discovery response as the feather_files list.The processing pipeline writes all output under a camera_timestamps/ subdirectory within the output
directory provided by the user:
{output_directory}/
└── camera_timestamps/ # Processing output subdirectory
├── camera_processing_tracker.yaml # ProcessingTracker state file (job lifecycle)
├── camera_{source_id}_timestamps.feather # Per-camera output (one per source ID)
├── camera_{source_id}_timestamps.feather
└── ...
Each feather file is a Polars DataFrame serialized as Feather IPC format with a single column:
| Column | Dtype | Description |
|---|---|---|
frame_time_us | UInt64 | Frame acquisition timestamp in microseconds since UTC epoch |
Rows are ordered chronologically. Each row corresponds to one acquired frame.
Files follow the pattern camera_{source_id}_timestamps.feather where source_id is the zero-padded
system ID string from the DataLogger archive (e.g., camera_051_timestamps.feather for system_id=51,
camera_112_timestamps.feather for an MCP session).
The camera_processing_tracker.yaml file tracks job lifecycle per output directory (inside
camera_timestamps/). Each job has:
camera_timestamp_extractionSCHEDULED, RUNNING, SUCCEEDED, or FAILEDFAILED)The analyze_camera_frame_statistics_tool returns a dictionary with three sections.
| Field | Type | Description |
|---|---|---|
total_frames | int | Total number of acquired frames |
first_timestamp_us | int | First frame timestamp (microseconds since UTC epoch) |
last_timestamp_us | int | Last frame timestamp (microseconds since UTC epoch) |
duration_us | int | Total recording duration in microseconds |
duration_seconds | float | Total recording duration in seconds |
estimated_fps | float | Estimated frame rate: (frames - 1) / duration |
| Field | Type | Description |
|---|---|---|
mean_us | float | Mean inter-frame interval in microseconds |
median_us | float | Median inter-frame interval in microseconds |
std_us | float | Standard deviation in microseconds |
min_us | int | Minimum inter-frame interval |
max_us | int | Maximum inter-frame interval |
mean_ms | float | Mean inter-frame interval in milliseconds |
median_ms | float | Median inter-frame interval in milliseconds |
std_ms | float | Standard deviation in milliseconds |
min_ms | float | Minimum inter-frame interval in milliseconds |
max_ms | float | Maximum inter-frame interval in milliseconds |
| Field | Type | Description |
|---|---|---|
threshold_us | float | Gap threshold used for drop detection |
threshold_source | str | "auto_2x_median" or "user_specified" |
total_gaps_detected | int | Number of inter-frame gaps exceeding the threshold |
total_estimated_dropped_frames | int | Estimated total frames lost across all gaps |
drop_rate_percent | float | Percentage of expected frames that were dropped |
longest_gap_us | int | Longest detected gap in microseconds |
longest_gap_ms | float | Longest detected gap in milliseconds |
drop_locations | list | Per-gap details (capped by max_drop_locations) |
drop_locations_truncated | bool | True if more drops exist than max_drop_locations |
Each entry in drop_locations:
| Field | Type | Description |
|---|---|---|
frame_index | int | Index of the frame preceding the gap |
gap_us | int | Gap duration in microseconds |
gap_ms | float | Gap duration in milliseconds |
estimated_frames_lost | int | Estimated number of frames lost in this gap |
Auto-detection algorithm: When drop_threshold_us=0, the threshold is computed as 2x the median
inter-frame interval. Gaps exceeding this threshold are classified as frame drops. The number of lost
frames per gap is estimated by dividing the gap duration by the median interval and rounding.
estimated_fps should be close to the configured camera frame rate. A significant shortfall
(e.g., configured 30fps but estimated 25fps) indicates the camera or encoder cannot keep up.std_us should be small relative to mean_us. A coefficient of variation (std/mean) under 5%
indicates stable timing.min_us and max_us should bracket mean_us tightly. A max_us many times larger than
mean_us signals occasional long gaps even if std_us appears acceptable.| Drop Rate | Severity | Typical Impact |
|---|---|---|
| 0% | None | Perfect acquisition |
| < 0.1% | Minimal | Negligible impact on most analyses |
| 0.1% – 1% | Moderate | May affect high-precision timing analyses |
| 1% – 5% | High | Likely to affect frame-accurate behavioral scoring |
| > 5% | Severe | Recording quality compromised; investigate root cause |
| Pattern | Characteristic | Likely Cause |
|---|---|---|
| Increasing gaps over time | Drops worsen as recording progresses | Thermal throttling (camera or GPU) |
| Random isolated drops | Sporadic single-frame gaps throughout | Interface bandwidth contention (USB/GigE) |
| Periodic drops | Drops at regular intervals | Competing device or process scheduling |
| Burst drops | Clusters of consecutive gaps | Disk write stalls or buffer overflow |
| Single large gap | One very long gap in otherwise stable data | System interruption (sleep, update) |
Encoding cost depends on frame content: high-motion or high-detail frames are expensive to encode, while static or low-contrast frames are cheap. Drops that correlate with scene changes (e.g., animal entering the field of view) indicate the encoder cannot handle peak complexity at the current preset.
estimated_fps << configured frame rate: the camera or encoder cannot sustain the configured rate.
Reduce resolution, frame rate, or switch from CPU to GPU encoding.std_us is high but estimated_fps is close to target: jitter is present but throughput is
maintained. Check cable quality, hub topology (USB), or network configuration (GigE).encoder_speed_preset to handle peak
encoding load, or increase quantization_parameter to reduce per-frame encoding cost.The discover_camera_data_tool returns a flat list of confirmed source entries. Each source entry
includes processing output status via the timestamps_file field:
{
"sources": [
{
"recording_root": "/path/to/session",
"source_id": "51",
"name": "face_camera",
"log_archive": "/path/to/51_log.npz",
"video_file": "/path/to/video.mp4" or null,
"timestamps_file": "/path/to/camera_51_timestamps.feather" or null,
"log_directory": "/path/to/session_data_log"
}
],
"log_directories": ["/path/to/session_data_log"],
"total_sources": 1,
"total_log_directories": 1
}
Processing completeness assessment:
timestamps_file value | Meaning |
|---|---|
| Non-null path | Processing succeeded for this source; feather file available |
null | Not yet processed, processing failed, or output was cleaned |
To determine detailed job status (SCHEDULED, RUNNING, SUCCEEDED, FAILED), check the
camera_processing_tracker.yaml file via get_batch_status_overview_tool.
| Skill | Relationship |
|---|---|
/mcp-environment-setup | Prerequisite: MCP server connectivity for tool access |
/camera-setup | Upstream: MCP discovery tools that locate archives and recordings |
/camera-interface | Context: VideoSystem configuration determines expected frame rates |
/post-recording | Upstream: verifies session outputs before processing |
/log-input-format | Reference: input archive format and source ID semantics |
/log-processing | Upstream: processing workflow that produces this output |
/pipeline | Context: results analysis is phase 6 of the end-to-end pipeline |
Log Processing Output Completeness:
- [ ] Feather files discovered via `discover_camera_data_tool`
- [ ] All expected source IDs have non-null `timestamps_file` entries
- [ ] Processing status verified for all directories
- [ ] Frame statistics analyzed via `analyze_camera_frame_statistics_tool` for each camera
- [ ] Estimated FPS matches expected camera frame rate
- [ ] Frame drop rate is within acceptable range for the experiment
- [ ] No unexplained large gaps in inter-frame timing
npx claudepluginhub sun-lab-nbb/ataraxis --plugin videoAnalyzes JSONL and other log files using rg and jq: structured extraction, cross-log correlation, timeline reconstruction, pattern search.
Provides FFmpeg filters and commands for video QC: detects black/blurry/frozen frames, crop/scene/interlace; computes PSNR/SSIM/VMAF. For automation workflows.
Monitors PostHog log ingestion for volume bursts, severity shifts, service silence, and trace-correlated anomalies. Emits findings only when confidence is high.