| name | post-recording |
| description | Guides post-recording verification and handoff: log archive assembly, video file validation, output completeness checks, and readiness assessment for downstream log processing. Use after stopping a video session to verify outputs before processing frame timestamps. |
| user-invocable | false |
Post-recording
Guides the steps between stopping a recording session and starting log processing. Covers archive
assembly, video validation, output completeness checks, and handoff conditions.
Scope
Covers:
- Log archive assembly from raw
.npy files to .npz archives
- Video file validation (existence, size, metadata inspection)
- Output directory completeness verification
- Video quality assessment guidance
- Correlating video frame counts with log archive message counts
- Handoff conditions to
/log-processing
- Troubleshooting assembly failures, missing archives, and corrupt video
Does not cover:
- Camera discovery or interactive session management (see
/camera-setup)
- Writing VideoSystem integration code (see
/camera-interface)
- Log processing workflow or batch operations (see
/log-processing)
- Input archive format details or source ID semantics (see
/log-input-format)
- Output feather files or frame statistics analysis (see
/log-processing-results)
- MCP server connectivity (see
/video-mcp-environment-setup)
Handoff rules: If the user asks about archive internal format or source IDs, invoke /log-input-format.
If ready for processing, invoke /log-processing. If asking about frame statistics after processing, invoke
/log-processing-results.
Available tools
Session stop tool
| Tool | Purpose |
|---|
stop_video_session_tool | Stops the active session; returns video path, log directory; auto-assembles |
The enhanced stop_video_session_tool returns a dictionary:
{
"status": "stopped",
"video_file": "/path/to/112.mp4" or null,
"log_directory": "/path/to/mcp_video_session_data_log",
"archives_assembled": true or false,
"source_ids": ["112"]
}
When archives_assembled is true, the raw .npy log files have been consolidated into .npz archives
and the source .npy files have been removed. When false, auto-assembly failed, and you should use the
manual assembly tool.
Archive assembly tool
| Tool | Purpose |
|---|
assemble_log_archives_tool | Manually assembles .npy files into .npz archives in a directory |
Parameters:
| Parameter | Type | Default | Description |
|---|
log_directory | str | (required) | Absolute path to DataLogger output directory containing .npy |
remove_sources | bool | true | Whether to remove .npy files after successful assembly |
verify_integrity | bool | false | Whether to verify archive integrity against source files first |
Video validation tool
| Tool | Purpose |
|---|
validate_video_file_tool | Inspects a video file for codec, resolution, frame count, etc. |
Parameters:
| Parameter | Type | Default | Description |
|---|
video_file | str | (required) | Absolute path to the video file to check |
Return structure:
{
"file": "/path/to/112.mp4",
"valid": true,
"codec": "h264",
"codec_long_name": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
"width": 600,
"height": 400,
"frame_count": 9000,
"duration_seconds": 300.0,
"bit_rate_bps": 5000000,
"file_size_bytes": 187500000,
"pixel_format": "yuv420p",
"frame_rate": "30/1"
}
Archive verification tool
| Tool | Purpose |
|---|
discover_camera_data_tool | Verifies archives, video files, and manifests exist via manifest-based discovery |
Parameters:
| Parameter | Type | Default | Description |
|---|
root_directory | str | (required) | Absolute path to root directory to search for manifests |
Note: This tool requires camera_manifest.yaml files to exist in DataLogger output directories.
These manifests are written automatically by VideoSystem.__init__(). For each confirmed manifest
source, the tool locates the corresponding log archive, video file, and processed timestamp feather
output, returning a flat sources list. The return also includes a flat log_directories list (which
feeds batch /log-processing) plus total_sources and total_log_directories aggregate counts.
Caution: video_file/timestamps_file are resolved by a name-then-ID substring heuristic with
path-proximity tie-breaking, not exact paths. A None video_file means "not matched", not necessarily
"not on disk" — confirm with validate_video_file_tool using the path returned by the stop tool. Beware false
matches when a camera name or the zero-padded ID appears in an unrelated .mp4 stem under the root.
Post-recording workflow
You MUST follow these steps after every recording session.
-
Stop the session — Call stop_video_session_tool. Record the returned video_file path and log_directory
path from the response.
-
Verify video file — Call validate_video_file_tool with the video_file path. Confirm:
- The file exists and has non-zero
file_size_bytes
frame_count is greater than 0 (note: frame_count may be null when ffprobe cannot report
nb_frames for the container, so treat a null value as "unknown" rather than zero frames)codec, width, height, and frame_rate match expected session parameters- A
null video_file means the session had no output directory / no saver configured
(output_directory was None at construction); a non-null path that fails
validate_video_file_tool with "File not found" is the signal that start_frame_saving_tool was
never called and no .mp4 was written
-
Verify archive assembly — If archives_assembled is true in the stop response, call
discover_camera_data_tool with the recording root to confirm archives exist for all expected
source IDs. The discovery tool uses manifest-based routing, so it requires a camera_manifest.yaml in
the log directory (written automatically by VideoSystem.__init__()). Each source in the flat sources
list includes a log_archive path. If archives_assembled is false, call
assemble_log_archives_tool with the log_directory path, then verify with the discovery tool.
-
Confirm archive presence for cross-referencing — discover_camera_data_tool confirms that each
source's log_archive exists but does not compute an archive message count. The genuine frame-count
vs. message-count cross-check (video frame_count from validate_video_file_tool against the archive
message count) can only be performed after /log-processing, where the message count becomes available.
They should be approximately equal (within 1-2 frames due to pipeline buffering); large discrepancies
indicate data loss.
-
Assess readiness — Run through the handoff checklist below. When all conditions are met, invoke
/log-processing to begin timestamp extraction.
Manual archive assembly
Use assemble_log_archives_tool when:
- The
stop_video_session_tool response shows archives_assembled: false
- Processing log directories from code-based sessions that called
logger.stop() without assembly
- Recovering from partial session failures
- Assembling archives from sessions run via the
axvs run CLI that were interrupted before assembly
After calling the tool, verify the result with discover_camera_data_tool to confirm all expected
source IDs have corresponding .npz archives.
Note: discover_camera_data_tool requires a camera_manifest.yaml in the log directory.
For MCP and code-based sessions using the current library version, this manifest is written automatically.
For legacy sessions without manifests, use write_camera_manifest_tool (see /camera-setup) to
retroactively register camera sources before running discovery.
Video quality assessment
Video property checks
| Property | Good | Concerning | Action |
|---|
| Frame count | Within 1% of fps * duration | > 1% deficit | Check frame drops via /log-processing-results |
| File size | Proportional to duration | Zero or very small | Re-record; check encoder configuration |
| Codec | Matches configured encoder | Unexpected codec | Verify encoder parameters in session start |
| Resolution | Matches camera configuration | Different from expected | Check width/height parameters |
| FPS | Matches configured frame rate | Significantly lower | Check encoder throughput and speed preset |
Correlating video metadata with log data
- Video
frame_count should approximate the number of frame messages in the log archive minus the onset
message (i.e., archive_frame_messages - 1).
- Video
duration_seconds should match (last_timestamp - first_timestamp) from processed timestamps.
- These cross-checks can only be validated after log processing completes via
/log-processing-results,
because the archive message count is not available until then. At this stage, discover_camera_data_tool
can only confirm that each source's log_archive path exists, not its message count.
- Processed output (feather files and tracker) is written to a
camera_timestamps/ subdirectory under the
output directory, not directly into the log directory.
Handoff to log processing
All the following conditions must be true before invoking /log-processing:
Post-Recording Readiness:
- [ ] Video session stopped (no active session)
- [ ] Video file exists and has non-zero size (or output_directory was None)
- [ ] Archives assembled (.npz files present in DataLogger output directory)
- [ ] No raw .npy files remain in the log directory
- [ ] All expected source IDs have corresponding archives
- [ ] Archive naming matches {source_id}_log.npz pattern
Video files are named {system_id:03d}.mp4 (zero-padded to 3 digits, e.g. 001.mp4, 042.mp4), whereas log
archives use the bare integer {source_id}_log.npz (1_log.npz, 42_log.npz). The same source ID drives both;
only the video name is padded.
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|
| No video file in output directory | Saving was never started | Verify start_frame_saving_tool was called |
| Video file is 0 bytes | FFMPEG encoding failed silently | Check FFMPEG installation; re-record |
No .npz archives after stopping | Auto-assembly failed or nothing logged | Call assemble_log_archives_tool manually |
| Assembly produces empty archives | No frame messages were logged | Verify start_frame_saving_tool was called |
Raw .npy files remain after assembly | Assembly ran with remove_sources=false | Re-run with remove_sources=true |
| Frame count mismatch (video vs archive) | Buffer flush timing or interruption | 1-2 frames normal; large gaps indicate loss |
validate_video_file_tool returns error | File corrupt or ffprobe unavailable | Check FFMPEG installation; re-record if needed |
| MCP tools unavailable | Server not running | Invoke /video-mcp-environment-setup |
A frame deficit concentrated at the end of a recording is a distinct case: stop() waits up to
10 minutes for the saver queue to drain, then forcibly terminates the consumer and discards the
unencoded tail with no error surfaced by the stop tool. It means the encoder could not keep up at
shutdown — use a faster encoder_speed_preset or hardware encoding next time.
Related skills
| Skill | Relationship |
|---|
/camera-setup | Upstream: MCP session management that produces recordings |
/camera-interface | Upstream: VideoSystem code that produces recordings |
/log-input-format | Reference: archive format and source ID semantics |
/log-processing | Downstream: processes archives into frame timestamps |
/log-processing-results | Downstream: analyzes processed frame statistics |
/pipeline | Context: end-to-end orchestration including this phase |
/video-mcp-environment-setup | Prerequisite: MCP server connectivity for tool access |
Verification checklist
Post-Recording Verification:
- [ ] Video session stopped via stop_video_session_tool
- [ ] Video file validated via validate_video_file_tool (codec, resolution, frame count, FPS)
- [ ] Log archives assembled (.npz files present in DataLogger output directory)
- [ ] All expected source IDs have corresponding archives
- [ ] No raw .npy files remain in log directory
- [ ] Archive presence confirmed for all source IDs (frame-count vs message-count cross-check deferred
to /log-processing-results)
- [ ] Handoff conditions met for /log-processing
