opensportslib 0.3.1.dev24__tar.gz → 0.3.1.dev26__tar.gz

{opensportslib-0.3.1.dev24/opensportslib.egg-info → opensportslib-0.3.1.dev26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.1.dev24
+Version: 0.3.1.dev26
 Summary: OpenSportsLib is the professional library, designed for advanced video understanding in sports. It provides state-of-the-art tools for action recognition, spotting, retrieval, and captioning, making it ideal for researchers, analysts, and developers working with sports video data.
 Author: Jeet Vora
 Requires-Python: >=3.12
@@ -324,3 +324,9 @@ video understanding. Core contributors affiliated with KAUST include:
 - [Jeet Vora](https://jeetv.github.io/) — Remote Research Engineer
 - [Dr. Merey Ramazanova](https://meryusha.github.io/) — Post-Doc
 - [Dr. Silvio Giancola](https://www.silviogiancola.com/) — Research Scientist
+
+For synchronized native-FPS GAR action clips and optional exact frame reproduction, see the
+[spotting-to-classification converter](docs/tools/spotting-to-classification.md).
+
+For full-rate tracking clips with the same classification sample IDs, see the
+[tracking conversion script](docs/tools/spotting-tracking-to-classification.md).

{opensportslib-0.3.1.dev24 → opensportslib-0.3.1.dev26}/README.md

@@ -285,3 +285,9 @@ video understanding. Core contributors affiliated with KAUST include:
 - [Jeet Vora](https://jeetv.github.io/) — Remote Research Engineer
 - [Dr. Merey Ramazanova](https://meryusha.github.io/) — Post-Doc
 - [Dr. Silvio Giancola](https://www.silviogiancola.com/) — Research Scientist
+
+For synchronized native-FPS GAR action clips and optional exact frame reproduction, see the
+[spotting-to-classification converter](docs/tools/spotting-to-classification.md).
+
+For full-rate tracking clips with the same classification sample IDs, see the
+[tracking conversion script](docs/tools/spotting-tracking-to-classification.md).

{opensportslib-0.3.1.dev24 → opensportslib-0.3.1.dev26/opensportslib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.1.dev24
+Version: 0.3.1.dev26
 Summary: OpenSportsLib is the professional library, designed for advanced video understanding in sports. It provides state-of-the-art tools for action recognition, spotting, retrieval, and captioning, making it ideal for researchers, analysts, and developers working with sports video data.
 Author: Jeet Vora
 Requires-Python: >=3.12
@@ -324,3 +324,9 @@ video understanding. Core contributors affiliated with KAUST include:
 - [Jeet Vora](https://jeetv.github.io/) — Remote Research Engineer
 - [Dr. Merey Ramazanova](https://meryusha.github.io/) — Post-Doc
 - [Dr. Silvio Giancola](https://www.silviogiancola.com/) — Research Scientist
+
+For synchronized native-FPS GAR action clips and optional exact frame reproduction, see the
+[spotting-to-classification converter](docs/tools/spotting-to-classification.md).
+
+For full-rate tracking clips with the same classification sample IDs, see the
+[tracking conversion script](docs/tools/spotting-tracking-to-classification.md).

{opensportslib-0.3.1.dev24 → opensportslib-0.3.1.dev26}/opensportslib.egg-info/SOURCES.txt

@@ -215,6 +215,7 @@ tests/unit/tools/test_hf_transfer.py
 tests/unit/tools/test_release_manifest.py
 tests/unit/tools/test_report_summary.py
 tests/unit/tools/test_setup.py
+tests/unit/tools/test_spotting_classification.py
 tools/convert/build_sn_vqa_2026_vqa.py
 tools/convert/build_sngar_spotting.py
 tools/convert/build_soccernet_gar.py
@@ -226,6 +227,8 @@ tools/convert/osl_json_to_parquet_webdataset.py
 tools/convert/parquet_webdataset_to_osl_json.py
 tools/convert/sngar_dataset_card.py
 tools/convert/sngar_events.py
+tools/convert/spotting_to_classification.py
+tools/convert/spotting_tracking_to_classification.py
 tools/convert/verify_sngar_spotting.py
 tools/download/download_hf_repo.py
 tools/download/download_osl_hf.py
@@ -235,4 +238,6 @@ tools/train/train_config.py
 tools/training/classification.py
 tools/training/localization.py
 tools/training/vqa.py
-tools/upload/upload_model_hf.py
+tools/upload/upload_model_hf.py
+tools/upload/upload_sngar_tracking_full.py
+tools/upload/upload_sngar_videos.py

{opensportslib-0.3.1.dev24 → opensportslib-0.3.1.dev26}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opensportslib"
-version = "0.3.1.dev24"
+version = "0.3.1.dev26"
 description = "OpenSportsLib is the professional library, designed for advanced video understanding in sports. It provides state-of-the-art tools for action recognition, spotting, retrieval, and captioning, making it ideal for researchers, analysts, and developers working with sports video data."
 readme = "README.md"
 requires-python = ">=3.12"

opensportslib-0.3.1.dev26/scripts/release_versions.py

@@ -0,0 +1,181 @@
+"""Keep the library version and the server's library pin in sync."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+
+STABLE_VERSION = re.compile(r"^(?P<version>\d+\.\d+\.\d+)$")
+DEV_VERSION = re.compile(r"^(?P<base>\d+\.\d+\.\d+)\.dev(?P<number>\d+)$")
+PROJECT_VERSION = re.compile(
+    r'(?ms)(^\[project\]\s*.*?^version\s*=\s*")[^"]+("\s*$)'
+)
+SERVER_PIN = re.compile(r'("opensportslib==)([^"]+)(")')
+
+
+def next_dev_version(current: str) -> str:
+    """Return the next development release for an existing dev version."""
+    match = DEV_VERSION.fullmatch(current)
+    if not match:
+        raise ValueError(f"expected X.Y.Z.devN, got {current!r}")
+    return f"{match.group('base')}.dev{int(match.group('number')) + 1}"
+
+
+def stable_version(tag: str) -> str:
+    """Return a stable version from a vX.Y.Z release tag."""
+    if not tag.startswith("v"):
+        raise ValueError(f"release tag must start with 'v', got {tag!r}")
+    version = tag[1:]
+    if not STABLE_VERSION.fullmatch(version):
+        raise ValueError(f"release tag must have the form vX.Y.Z, got {tag!r}")
+    return version
+
+
+def development_version(tag: str) -> str:
+    """Return the initial development version for a stable release tag."""
+    return f"{stable_version(tag)}.dev0"
+
+
+def next_patch_development_version(tag: str) -> str:
+    """Return the next patch's initial development version for a release tag."""
+    major, minor, patch = (int(part) for part in stable_version(tag).split("."))
+    return f"{major}.{minor}.{patch + 1}.dev0"
+
+
+def version_base(version: str) -> str:
+    """Return X.Y.Z from either a stable or development package version."""
+    dev_match = DEV_VERSION.fullmatch(version)
+    if dev_match:
+        return dev_match.group("base")
+    if STABLE_VERSION.fullmatch(version):
+        return version
+    raise ValueError(f"unsupported release version {version!r}")
+
+
+def read_project_version(pyproject: Path) -> str:
+    text = pyproject.read_text()
+    match = PROJECT_VERSION.search(text)
+    if not match:
+        raise ValueError(f"project.version not found in {pyproject}")
+    return text[match.start(0) + len(match.group(1)) : match.end(0) - len(match.group(2))]
+
+
+def read_server_pin(pyproject: Path) -> str:
+    """Return the OpenSportsLib dependency pin from the server metadata."""
+    text = pyproject.read_text()
+    matches = SERVER_PIN.findall(text)
+    if len(matches) != 1:
+        raise ValueError(f"expected one opensportslib dependency pin in {pyproject}")
+    return matches[0][1]
+
+
+def assert_synchronized(root_pyproject: Path, server_pyproject: Path) -> str:
+    """Ensure the package version and server dependency pin are identical."""
+    version = read_project_version(root_pyproject)
+    pin = read_server_pin(server_pyproject)
+    if version != pin:
+        raise ValueError(
+            f"version metadata is not synchronized: {root_pyproject} has {version!r}, "
+            f"but {server_pyproject} pins {pin!r}"
+        )
+    return version
+
+
+def validate_release(tag: str, root_pyproject: Path, server_pyproject: Path) -> str:
+    """Validate that metadata is the prepared prerelease for *tag*."""
+    expected = development_version(tag)
+    current = assert_synchronized(root_pyproject, server_pyproject)
+    if not DEV_VERSION.fullmatch(current) or version_base(current) != stable_version(tag):
+        raise ValueError(
+            f"release tag {tag!r} requires prepared version {expected[:-1]}N, got {current!r}"
+        )
+    return current
+
+
+def prepare_development(tag: str, root_pyproject: Path, server_pyproject: Path) -> str:
+    """Start the requested release line at X.Y.Z.dev0."""
+    target = development_version(tag)
+    current = assert_synchronized(root_pyproject, server_pyproject)
+    if tuple(map(int, stable_version(tag).split("."))) <= tuple(map(int, version_base(current).split("."))):
+        raise ValueError(f"target release {tag!r} must be newer than current version {current!r}")
+    synchronize(target, root_pyproject, server_pyproject)
+    return target
+
+
+def advance_development(tag: str, root_pyproject: Path, server_pyproject: Path) -> str:
+    """Advance a released development line to its next patch development base."""
+    validate_release(tag, root_pyproject, server_pyproject)
+    target = next_patch_development_version(tag)
+    synchronize(target, root_pyproject, server_pyproject)
+    return target
+
+
+def synchronize(version: str, root_pyproject: Path, server_pyproject: Path) -> None:
+    """Write one OpenSportsLib version to both release metadata files."""
+    if not (STABLE_VERSION.fullmatch(version) or DEV_VERSION.fullmatch(version)):
+        raise ValueError(f"unsupported release version {version!r}")
+
+    root_text = root_pyproject.read_text()
+    server_text = server_pyproject.read_text()
+    if len(PROJECT_VERSION.findall(root_text)) != 1:
+        raise ValueError(f"expected one project.version in {root_pyproject}")
+    if len(SERVER_PIN.findall(server_text)) != 1:
+        raise ValueError(f"expected one opensportslib dependency pin in {server_pyproject}")
+
+    root_updated = PROJECT_VERSION.sub(rf"\g<1>{version}\g<2>", root_text)
+    server_updated = SERVER_PIN.sub(rf"\g<1>{version}\g<3>", server_text)
+    root_pyproject.write_text(root_updated)
+    server_pyproject.write_text(server_updated)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "command",
+        choices=(
+            "bump-dev",
+            "set-stable",
+            "prepare-dev",
+            "validate-release",
+            "advance-dev",
+            "assert-synchronized",
+        ),
+    )
+    parser.add_argument("value", nargs="?", help="vX.Y.Z tag for set-stable")
+    parser.add_argument("--root", type=Path, default=Path("pyproject.toml"))
+    parser.add_argument("--server", type=Path, default=Path("server/pyproject.toml"))
+    args = parser.parse_args()
+
+    if args.command == "bump-dev":
+        if args.value is not None:
+            parser.error("bump-dev does not accept a value")
+        version = next_dev_version(assert_synchronized(args.root, args.server))
+        synchronize(version, args.root, args.server)
+    elif args.command == "set-stable":
+        if args.value is None:
+            parser.error("set-stable requires a vX.Y.Z tag")
+        version = stable_version(args.value)
+        synchronize(version, args.root, args.server)
+    elif args.command == "prepare-dev":
+        if args.value is None:
+            parser.error("prepare-dev requires a vX.Y.Z tag")
+        version = prepare_development(args.value, args.root, args.server)
+    elif args.command == "validate-release":
+        if args.value is None:
+            parser.error("validate-release requires a vX.Y.Z tag")
+        version = validate_release(args.value, args.root, args.server)
+    elif args.command == "advance-dev":
+        if args.value is None:
+            parser.error("advance-dev requires a vX.Y.Z tag")
+        version = advance_development(args.value, args.root, args.server)
+    else:
+        if args.value is not None:
+            parser.error("assert-synchronized does not accept a value")
+        version = assert_synchronized(args.root, args.server)
+    print(version)
+
+
+if __name__ == "__main__":
+    main()

opensportslib-0.3.1.dev26/tests/unit/contracts/test_release_versions.py

@@ -0,0 +1,118 @@
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+
+SCRIPT = Path(__file__).parents[3] / "scripts" / "release_versions.py"
+SPEC = importlib.util.spec_from_file_location("release_versions", SCRIPT)
+release_versions = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(release_versions)
+
+
+def test_next_dev_version_increments_counter():
+    assert release_versions.next_dev_version("0.3.1.dev5") == "0.3.1.dev6"
+
+
+@pytest.mark.parametrize("version", ["0.3.1", "0.3.1rc1", "invalid"])
+def test_next_dev_version_rejects_non_dev_versions(version):
+    with pytest.raises(ValueError, match="expected X.Y.Z.devN"):
+        release_versions.next_dev_version(version)
+
+
+def test_stable_version_requires_stable_v_tag():
+    assert release_versions.stable_version("v0.3.1") == "0.3.1"
+    with pytest.raises(ValueError, match="vX.Y.Z"):
+        release_versions.stable_version("v0.3.1.dev1")
+
+
+def test_development_version_helpers():
+    assert release_versions.development_version("v0.4.0") == "0.4.0.dev0"
+    assert release_versions.next_patch_development_version("v0.3.1") == "0.3.2.dev0"
+    assert release_versions.version_base("0.3.1.dev5") == "0.3.1"
+    assert release_versions.version_base("0.3.1") == "0.3.1"
+    with pytest.raises(ValueError, match="unsupported release version"):
+        release_versions.version_base("invalid")
+
+
+def test_synchronize_updates_root_and_server_pin_only(tmp_path):
+    root = tmp_path / "pyproject.toml"
+    server = tmp_path / "server.toml"
+    root.write_text('[project]\nname = "opensportslib"\nversion = "0.3.1.dev5"\n')
+    server.write_text(
+        '[project]\nname = "opensportslib-server"\nversion = "0.1.0"\n'
+        'dependencies = [\n  "opensportslib==0.3.1.dev5",\n  "fastapi",\n]\n'
+    )
+
+    release_versions.synchronize("0.3.1.dev6", root, server)
+
+    assert 'version = "0.3.1.dev6"' in root.read_text()
+    assert 'version = "0.1.0"' in server.read_text()
+    assert '"opensportslib==0.3.1.dev6"' in server.read_text()
+
+
+def test_synchronize_fails_before_writing_when_server_pin_is_missing(tmp_path):
+    root = tmp_path / "pyproject.toml"
+    server = tmp_path / "server.toml"
+    original = '[project]\nversion = "0.3.1.dev5"\n'
+    root.write_text(original)
+    server.write_text('[project]\nversion = "0.1.0"\n')
+
+    with pytest.raises(ValueError, match="dependency pin"):
+        release_versions.synchronize("0.3.1.dev6", root, server)
+
+    assert root.read_text() == original
+
+
+def test_assert_synchronized_rejects_mismatched_metadata(tmp_path):
+    root = tmp_path / "pyproject.toml"
+    server = tmp_path / "server.toml"
+    root.write_text('[project]\nversion = "0.3.1.dev5"\n')
+    server.write_text('dependencies = ["opensportslib==0.3.1.dev4"]\n')
+
+    with pytest.raises(ValueError, match="not synchronized"):
+        release_versions.assert_synchronized(root, server)
+
+
+def test_validate_release_requires_matching_prepared_dev_line(tmp_path):
+    root = tmp_path / "pyproject.toml"
+    server = tmp_path / "server.toml"
+    root.write_text('[project]\nversion = "0.3.1.dev5"\n')
+    server.write_text('dependencies = ["opensportslib==0.3.1.dev5"]\n')
+
+    assert release_versions.validate_release("v0.3.1", root, server) == "0.3.1.dev5"
+    with pytest.raises(ValueError, match="requires prepared version"):
+        release_versions.validate_release("v0.3.2", root, server)
+
+
+def test_prepare_development_starts_newer_feature_line(tmp_path):
+    root = tmp_path / "pyproject.toml"
+    server = tmp_path / "server.toml"
+    root.write_text('[project]\nversion = "0.3.2.dev8"\n')
+    server.write_text('dependencies = ["opensportslib==0.3.2.dev8"]\n')
+
+    assert release_versions.prepare_development("v0.4.0", root, server) == "0.4.0.dev0"
+    assert release_versions.assert_synchronized(root, server) == "0.4.0.dev0"
+    with pytest.raises(ValueError, match="must be newer"):
+        release_versions.prepare_development("v0.4.0", root, server)
+
+
+def test_advance_development_moves_to_next_patch_only_from_matching_line(tmp_path):
+    root = tmp_path / "pyproject.toml"
+    server = tmp_path / "server.toml"
+    root.write_text('[project]\nversion = "0.3.1.dev6"\n')
+    server.write_text('dependencies = ["opensportslib==0.3.1.dev6"]\n')
+
+    assert release_versions.advance_development("v0.3.1", root, server) == "0.3.2.dev0"
+    assert release_versions.assert_synchronized(root, server) == "0.3.2.dev0"
+
+
+def test_advance_development_refuses_a_different_release_line(tmp_path):
+    root = tmp_path / "pyproject.toml"
+    server = tmp_path / "server.toml"
+    root.write_text('[project]\nversion = "0.4.0.dev0"\n')
+    server.write_text('dependencies = ["opensportslib==0.4.0.dev0"]\n')
+
+    with pytest.raises(ValueError, match="requires prepared version"):
+        release_versions.advance_development("v0.3.1", root, server)

{opensportslib-0.3.1.dev24 → opensportslib-0.3.1.dev26}/tests/unit/tools/test_hf_transfer.py

@@ -1942,3 +1942,181 @@ def test_upload_dataset_inputs_from_json_to_hf_can_be_cancelled_before_upload(mo
         )
 
     assert calls["create_commit"] == 0
+
+
+@pytest.fixture
+def tracking_full_upload(tmp_path, monkeypatch):
+    import importlib.util
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+
+    script = Path(__file__).resolve().parents[3] / "tools/upload/upload_sngar_tracking_full.py"
+    spec = importlib.util.spec_from_file_location("tracking_full_upload", script)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    monkeypatch.setattr(module, "COUNTS", {"train": 1, "valid": 1, "test": 1})
+    root = tmp_path / "tracking"
+    reports = tmp_path / "reports"
+    reports.mkdir()
+    (reports / "build.json").write_text(json.dumps({"status": "passed", "completed": 3, "identity": "build"}))
+    for split in module.COUNTS:
+        (root / split).mkdir(parents=True)
+        pq.write_table(pa.table({"frameNum": range(144), "tracking_valid": [True] * 144}), root / split / "clip.parquet")
+        sample = {"id": split + "_000000", "inputs": [{"type": "tracking_parquet", "path": f"{split}/clip.parquet"}],
+                  "metadata": {"conversion": {"identity": "build", "frame_interval": 1,
+                      "window_slots": 144, "output_rows": 144, "gap_policy": "pad"}}}
+        (root / f"annotations_{split}.json").write_text(json.dumps({"task": "action_classification", "data": [sample]}))
+    calls = []
+    monkeypatch.setattr(module, "dataset_repo_exists_on_hf", lambda repo: calls.append(("exists", repo)) or True)
+    monkeypatch.setattr(module, "create_dataset_branch_on_hf", lambda *args, **kw: calls.append(("branch", args)))
+    monkeypatch.setattr(module, "upload_dataset_as_parquet_to_hf", lambda *args, **kw: calls.append(("upload", args, kw)) or {})
+    return module, root, calls
+
+
+def test_tracking_full_check_is_offline(tracking_full_upload):
+    module, root, calls = tracking_full_upload
+    assert module.main(["--data-root", str(root), "--check-only"]) == 0
+    assert calls == []
+
+
+@pytest.mark.parametrize("failure", ["unfinished", "missing", "downsampled", "wrong_rows"])
+def test_tracking_full_invalid_build_never_contacts_hub(tracking_full_upload, failure):
+    module, root, calls = tracking_full_upload
+    if failure == "unfinished":
+        (root.parent / "reports/build.json").write_text('{"status": "running"}')
+    elif failure == "missing":
+        (root / "test/clip.parquet").unlink()
+    else:
+        path = root / "annotations_test.json"
+        data = json.loads(path.read_text())
+        conversion = data["data"][0]["metadata"]["conversion"]
+        conversion["frame_interval" if failure == "downsampled" else "output_rows"] = 9
+        path.write_text(json.dumps(data))
+    assert module.main(["--data-root", str(root)]) == 1
+    assert calls == []
+
+
+def test_tracking_full_routes_to_internal_sharded_uploader(tracking_full_upload):
+    module, root, calls = tracking_full_upload
+    assert module.main(["--data-root", str(root), "--shard-size", "500MB", "--splits", "valid", "test"]) == 0
+    assert calls[1] == ("branch", ("OpenSportsLab/SoccerNet-GAR", "tracking-full"))
+    uploads = calls[2:]
+    assert [call[2]["split"] for call in uploads] == ["valid", "test"]
+    for _, args, kwargs in uploads:
+        assert args[0] == "OpenSportsLab/SoccerNet-GAR"
+        assert Path(args[1]) == root / f"annotations_{kwargs['split']}.json"
+        assert kwargs["revision"] == "tracking-full"
+        assert kwargs["shard_mode"] == "size"
+        assert kwargs["shard_size"] == module.parse_shard_size("500MB")
+
+
+def test_tracking_full_stops_on_upload_failure(tracking_full_upload, monkeypatch):
+    module, root, calls = tracking_full_upload
+    attempted = []
+    def fail(*args, **kwargs):
+        attempted.append(kwargs["split"])
+        raise RuntimeError("Upload interrupted")
+    monkeypatch.setattr(module, "upload_dataset_as_parquet_to_hf", fail)
+    assert module.main(["--data-root", str(root)]) == 1
+    assert attempted == ["train"]
+
+
+@pytest.fixture
+def videos_upload(tracking_full_upload, monkeypatch):
+    import importlib.util
+    from fractions import Fraction
+    import av
+    import numpy as np
+
+    _, root, _ = tracking_full_upload
+    script = Path(__file__).resolve().parents[3] / "tools/upload/upload_sngar_videos.py"
+    spec = importlib.util.spec_from_file_location("videos_upload", script)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    monkeypatch.setattr(module, "COUNTS", {"train": 1, "valid": 1, "test": 1})
+    rate = Fraction(30000, 1001)
+    for split in module.COUNTS:
+        path = root / split / "clip.mp4"
+        with av.open(str(path), "w") as output:
+            stream = output.add_stream("libx264", rate=rate)
+            stream.width, stream.height, stream.pix_fmt = 16, 16, "yuv420p"
+            for i in range(144):
+                frame = av.VideoFrame.from_ndarray(np.zeros((16, 16, 3), dtype=np.uint8), format="rgb24")
+                frame.pts, frame.time_base = i, 1 / rate
+                for packet in stream.encode(frame):
+                    output.mux(packet)
+            for packet in stream.encode():
+                output.mux(packet)
+        manifest = root / f"annotations_{split}.json"
+        data = json.loads(manifest.read_text())
+        sample = data["data"][0]
+        sample["inputs"] = [{"type": "video", "path": f"{split}/clip.mp4", "fps": float(rate)}]
+        sample["metadata"]["conversion"] = {
+            "identity": "build", "validation": "temporal", "alignment": {"passed": True},
+            "sampled_frame_indices": list(range(90, 234, 9)),
+            "clip": {"start_frame": 90, "end_frame_exclusive": 234, "frame_count": 144,
+                     "native_rate": str(rate), "width": 16, "height": 16,
+                     "duration_seconds": float(144 / rate)},
+        }
+        manifest.write_text(json.dumps(data))
+    calls = []
+    monkeypatch.setattr(module, "dataset_repo_exists_on_hf", lambda repo: calls.append(("exists", repo)) or True)
+    monkeypatch.setattr(module, "create_dataset_branch_on_hf", lambda *args, **kw: calls.append(("branch", args)))
+    monkeypatch.setattr(module, "upload_dataset_as_parquet_to_hf", lambda *args, **kw: calls.append(("upload", args, kw)) or {})
+    return module, root, calls
+
+
+def test_videos_upload_offline_fractional_fps(videos_upload):
+    module, root, calls = videos_upload
+    assert module.main(["--data-root", str(root), "--check-only"]) == 0
+    assert calls == []
+
+
+@pytest.mark.parametrize("failure", ["unfinished", "missing", "corrupt", "alignment", "frame_count", "native_rate", "duration_seconds"])
+def test_videos_invalid_build_never_contacts_hub(videos_upload, failure, capsys):
+    module, root, calls = videos_upload
+    if failure == "unfinished":
+        (root.parent / "reports/build.json").write_text('{"status": "running"}')
+    elif failure == "missing":
+        (root / "test/clip.mp4").unlink()
+    elif failure == "corrupt":
+        (root / "test/clip.mp4").write_bytes(b"invalid mp4")
+    else:
+        manifest = root / "annotations_test.json"
+        data = json.loads(manifest.read_text())
+        conversion = data["data"][0]["metadata"]["conversion"]
+        if failure == "alignment":
+            conversion["alignment"]["passed"] = False
+        else:
+            conversion["clip"][failure] = 16
+        manifest.write_text(json.dumps(data))
+    assert module.main(["--data-root", str(root)]) == 1
+    assert calls == []
+    assert "Error:" in capsys.readouterr().err
+
+
+def test_videos_routes_to_internal_uploader(videos_upload):
+    module, root, calls = videos_upload
+    assert module.main(["--data-root", str(root), "--splits", "test", "--shard-size", "500MB"]) == 0
+    assert calls[1] == ("branch", ("OpenSportsLab/SoccerNet-GAR", "videos"))
+    assert len(calls) == 3
+    _, args, kwargs = calls[2]
+    assert args == ("OpenSportsLab/SoccerNet-GAR", str(root / "annotations_test.json"))
+    assert kwargs["revision"] == "videos"
+    assert kwargs["split"] == "test"
+    assert kwargs["shard_mode"] == "size"
+    assert kwargs["shard_size"] == module.parse_shard_size("500MB")
+
+
+def test_videos_accepts_legacy_timestamp_quantization(videos_upload):
+    module, root, calls = videos_upload
+    from fractions import Fraction
+    # Legacy provenance stores nominal FPS, slightly different from measured
+    # output FPS when the source timestamps include a one-tick correction.
+    path = root / "annotations_test.json"
+    data = json.loads(path.read_text())
+    clip = data["data"][0]["metadata"]["conversion"]["clip"]
+    clip["native_rate"] = str(Fraction(12960000, 432433))
+    path.write_text(json.dumps(data))
+    assert module.main(["--data-root", str(root), "--check-only"]) == 0
+    assert calls == []