annotations/README.md

# EventActivityNet Annotations and Timing Metadata

These files cover the canonical 3,263-video Large release. Medium and Small use
the same annotation files, filtered by their video-ID lists. The 5-bin and
9-bin representations share annotations and source timing.

## Files

- `activitynet_captions.json`: ActivityNet Captions timestamped descriptions;
- `activitynet_actions.json`: ActivityNet v1.3 temporal action annotations;
- `eventactivitynet_alignment.json`: EventActivityNet-derived caption/action alignment using temporal IoU with midpoint-distance fallback;
- `annotation_issues.jsonl`: known source annotation quirks preserved without changing canonical values;
- `../metadata/video_metadata.jsonl`: shared source timing and per-representation tensor metadata.

ActivityNet Captions is the source of timestamped descriptions. ActivityNet
v1.3 is the source of temporal action labels and segments. EventActivityNet is
the source of the derived alignment. Captions are timestamped descriptions,
not instruction-tuning records.

## Timing

For source frame count `N`, representation bin count `B` in `{5, 9}`, and
`frames_per_bin=1`:

```text
T_B = ceil((N - 1) / B)
```

Voxel `i` groups adjacent-frame transition indices
`[B*i, min(B*i + B, N - 1))`. Its approximate source-frame interval is
`[B*i, min(B*i + B, N - 1)]`, and its approximate seconds interval is:

```text
[B*i * fps_den / fps_num,
 min(B*i + B, N - 1) * fps_den / fps_num]
```

Construction follows decoded frame order. Per-frame presentation timestamps
are not consumed, so seconds-level mapping is approximate for within-video
variable-frame-rate streams. Do not assume fixed 25 fps or 240 fps.

## Known Source Annotation Quirks

Canonical source annotations are preserved as-is. Some timestamps or action
segments have minor ordering or boundary issues, including small floating-point
overshoots. Use a small numerical tolerance; `annotation_issues.jsonl` records
the observed cases.

## Source Hashes

```json
{
  "activitynet_actions": "4c29d5b1561e1cbff9ac69816c159e60d417a18f16db8acc0fc254c377fa9ae3",
  "alignment": "40a75cfd6a053011766e80e5a6d449b84a3ececf51b1f34cfa33eefba8729d36",
  "captions_train": "704536b2779011c1a729c927ae30e39ea9c90c38557836bbe969499917243d69",
  "captions_val_1": "466aaccb9ebe45c6db4c98488a4ddbeb5b22faffe62e1bbce81222c14fc29e1c",
  "captions_val_2": "08fe56568bc92dd02a6150fe1094457a5f2ac72975b8778a922bc9a65aa7f0e9",
  "class_mapping": "f15c7864abe012bd82b1df2c33beae8254acffc4b86a3dcbf6174c02a61eb400",
  "large_manifest": "02468b7f301a85c5f3776b72b9b1ff83635bc99dd6b2ce42a7c7e5308007c96a",
  "verify_all": "a5d17bcb508789c6e96747d3eac9ecee13b99dd683df995cd81e3179966bd7bc"
}
```