Document audited AVSpeech missing-media boundary

README.md

@@ -10,22 +10,140 @@ configs:
 
 # AVSpeech Video + Audio
 
-A restructured subset of the [AVSpeech](https://looking-to-listen.github.io/avspeech/) dataset with separated media streams and derived identifiers.
+This repository is a media-bearing reconstruction of the public AVSpeech
+annotations. Each row represents an already-trimmed segment and keeps the
+original source-video timing and target-face-center metadata.
+
+## Dataset structure
+
+- `clip_id`: identifier derived as
+  `{youtube_id}_{start_sec:.3f}_{end_sec:.3f}`.
+- `avspeech_metadata`: JSON containing `youtube_id`, `start_sec`, `end_sec`,
+  `x_center`, and `y_center` from the AVSpeech annotation.
+- `video`: video-only stream, or null when the source segment could not be
+  materialized.
+- `audio`: audio-only stream, or null when the source segment could not be
+  materialized.
+
+The `video` field is already trimmed. `start_sec` and `end_sec` refer to the
+original YouTube-video timeline and must not be used to seek again within this
+clip. AVSpeech defines `(x_center, y_center)` as the normalized center of the
+speaker's face in the frame at the beginning of the segment, with `(0, 0)` at
+the top left.
+
+## Audited snapshot and known publication gap
+
+The following figures describe revision
+`efdceb2a0b9d81a6aec76f10668cca49e8209e37`:
+
+| Split | Rows | Rows with both media | Rows without both media | Parquet files | Encoded size |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| train | 2,621,845 | 1,589,842 | 1,032,003 | 5,142 | 1,404,473,032,806 bytes |
+| test | 183,273 | 98,605 | 84,668 | 359 | 88,861,772,006 bytes |
+| total | 2,805,118 | 1,688,447 | 1,116,671 | 5,501 | 1,493,334,804,812 bytes |
+
+The train states were verified by an exhaustive read-only scan of all 5,142
+train Parquet files and 2,621,845 rows. Of the 1,032,003 train rows without both
+media streams, 1,032,000 have both media null, 3 are video-only, and 0 are
+audio-only. The test split was not audited at that row-state granularity, so
+the table reports only its aggregate count without both streams.
+
+The completed exporter expected 1,589,942 paired train occurrences, while this
+snapshot contains 1,589,842, an aggregate gap of 100. Surviving non-media
+evidence supports high-confidence assignment of 49 of those occurrence slots:
+
+- 46 both-null occurrences have a paired sibling at the pinned revision.
+- 3 video-only occurrences retain a published `video.path` while `audio.path`
+  is null, showing that the exporter reached archive-member processing.
+
+The remaining 51 occurrence slots cannot be assigned to exact rows or
+`clip_id` values without the original expected-pair manifest or historical
+ID-to-archive map. Their ambiguity remains within a pool of 4,103
+metadata-resolved both-null occurrences across 403 YouTube IDs. “Unresolved”
+does not mean that these rows were verified unavailable.
+
+The audit selected only `clip_id`, `avspeech_metadata`, `video.path`, and
+`audio.path`. It did not select or materialize embedded media bytes, and its
+range guards recorded zero intersections with media-byte column chunks. No
+media recovery, YouTube retrieval, torrent-media transfer, row repair, or
+Hugging Face mutation was attempted as part of that audit.
+
+## Bounded loading
+
+Do not use `snapshot_download` for routine training: the repository is about
+1.49 TB. Stream rows, keep media decoding disabled at the dataset layer, skip
+any row without both media streams, and materialize only one bounded work unit
+at a time. Preserve the official split and stable row provenance, and report
+pre-filter and retained denominators plus exclusions by reason.
+
+```python
+from datasets import Audio, Video, load_dataset
+
+revision = "efdceb2a0b9d81a6aec76f10668cca49e8209e37"
+rows = load_dataset(
+    "ProgramComputer/avspeech-visual-audio",
+    split="train",
+    revision=revision,
+    streaming=True,
+)
+rows = rows.cast_column("video", Video(decode=False))
+rows = rows.cast_column("audio", Audio(decode=False))
+
+for row in rows:
+    if row["video"] is None or row["audio"] is None:
+        continue
+    # Materialize/process this row in bounded temporary storage.
+```
+
+The official AVSpeech page states that its supplied train and test annotations
+use disjoint speakers. This reconstruction preserves those source split labels.
+It does not add person identities, and a YouTube video ID must not be described
+as a speaker identity.
+
+## Intended use and limitations
+
+This dataset is intended for research on audio-visual speech and related
+representation-learning tasks. It is derived from public Internet video and is
+not demographically balanced. Availability, codecs, media quality, language,
+pose, lighting, and annotation accuracy vary. Missing rows are not necessarily
+random, so filtering to paired media may introduce additional selection bias.
+The unresolved 51-slot publication gap is aggregate provenance information,
+not a verified unavailable-row list, and must not be converted into invented
+row-level labels.
+
+The face-center coordinate is a point hint at the beginning of the segment,
+not a bounding box, persistent track, verified identity label, or consent
+signal. Downstream systems must validate the associated detected face and must
+not use this dataset for identification, surveillance, or consequential
+decisions.
+
+## License and provenance review
+
+The official AVSpeech download page provides train/test annotation CSVs and
+states that “this data” is available under CC BY 4.0. This repository also
+redistributes media derived from YouTube videos. The maintainer has not yet
+documented a legal review establishing that the same license statement covers
+redistribution of every embedded media stream or that all upstream platform
+and uploader terms are satisfied. Therefore this card deliberately does not
+assert a Hugging Face `license` tag for the media-bearing reconstruction.
+
+Before continued public redistribution, document the source acquisition
+process, takedown procedure, upstream terms, and the basis for redistributing
+the embedded audio/video. This note is a publication safeguard, not legal
+advice.
 
-- `clip_id`: unique identifier per clip, derived as `{youtube_id}_{start:.3f}_{end:.3f}` from the original AVSpeech CSV columns.
-- `avspeech_metadata`: JSON string with the original AVSpeech row fields (`youtube_id`, `start_sec`, `end_sec`, `x_center`, `y_center`).
-- `video`: video-only stream (no audio), stream-copied without re-encoding.
-- `audio`: audio-only stream, stream-copied without re-encoding.
-  
 ## Citation
 
-If you use this dataset, please cite the original AVSpeech paper:
+If you use the data, cite the original AVSpeech work:
 
 ```bibtex
-@inproceedings{ephrat2018looking,
-  title={Looking to listen at the cocktail party: A speaker-independent audio-visual model for speech separation},
-  author={Ephrat, Ariel and Mosseri, Inbar and Lang, Oran and Dekel, Tali and Wilson, Kevin and Hassidim, Avinatan and Freeman, William T and Rubinstein, Michael},
-  booktitle={ACM SIGGRAPH 2018},
+@article{ephrat2018looking,
+  title={Looking to Listen at the Cocktail Party: A Speaker-Independent Audio-Visual Model for Speech Separation},
+  author={Ephrat, Ariel and Mosseri, Inbar and Lang, Oran and Dekel, Tali and Wilson, Kevin and Hassidim, Avinatan and Freeman, William T. and Rubinstein, Michael},
+  journal={ACM Transactions on Graphics},
   year={2018}
 }
 ```
+
+Official AVSpeech project and download page:
+<https://looking-to-listen.github.io/avspeech/download.html>.