[ar-api] Add native video upload and ingestion status to CLI (VID-53)

[digaobarbosa]

Motivation

Action Recognition projects take whole videos as Sources, but the CLI only offered legacy video inference jobs. Users could not upload an original video or follow its processing from the terminal.

roboflow video upload now sends the original MP4/MOV bytes unchanged and reports the canonical video ID. That ID can differ from the first one when the same content already exists. roboflow video upload-status reads or waits for processing with that ID. Legacy video infer and video status keep their own behavior.

Failures follow the CLI exit-code contract: a rejected API key exits 2, an unknown project or video exits 3, and other failures exit 1. A missing file or a bad wait bound is rejected before any bytes are sent.

Stack and dependency

The SDK dependency (PR #534) is merged, so this PR targets main. Segment annotation is stacked on top in PR #544 (VID-59), which contains this branch. Merge this one first.

Changes since reopening

This PR was closed by mistake and revived on 2026-10-09 with main merged in and a simplification pass:

• Typer validates --poll-interval (min=0.1) and --poll-timeout (min=0), replacing a handler-side check. Bad bounds are usage errors (exit 2) and still fail before any bytes are stored.
• --metadata parsing has one error path.
• JSON usage errors keep the option name, e.g. Invalid value for '--poll-interval': …. Click's str() dropped it for every min= option in the CLI.
• Removed CLI tests that only re-checked --help or shared resolver behaviour. Added a direct test for the get_project status code that the exit-code mapping relies on.

Verification

1. Full unit suite at head 834f4bd: 1,224 tests pass, one skipped, also with Rich color forced as in CI. ruff check, ruff format --check and mypy roboflow pass.
2. Staging E2E at dc3f815: 11/11 passed against api.roboflow.one / model-evaluation-workspace with the installed CLI, in 31 s. The only later commit changes one test assertion. The run's project was moved to Trash: a later project get exits 3 and trash list shows it.
3. CI: the Python/Windows build matrix runs now that the base is main.

Staging E2E results: upload and upload-status (head dc3f815, 2026-10-09)

Commands ran as roboflow --json -k $KEY -w model-evaluation-workspace … (shown without the key and workspace). $P is a private Action Recognition project the run created and then moved to Trash. Uploads are byte-unique stream copies of real 24 fps clips (time base 1/12288), so no shared Source is touched. The cases are scripted in run_native_video_e2e.sh from the e2e-test skill.

#	Case	Command	Exit	Result
U1	upload --no-wait	roboflow --json video upload -f $SCRATCH/unique-copy.mp4 -p $P --no-wait	0	PASS
U2	upload-status single read	roboflow --json video upload-status <id> -p $P	0	PASS
U3	upload-status --wait	roboflow --json video upload-status <id> -p $P --wait --poll-timeout 120	0	PASS
U4	re-upload is deduplicated onto Source A	roboflow --json video upload -f $SCRATCH/unique-copy.mp4 -p $P	0	PASS
U5	upload-status unknown id	roboflow --json video upload-status doesnotexist123 -p $P	3	PASS
U6	unsupported container	roboflow --json video upload -f $SCRATCH/clip.avi -p $P	1	PASS
U7	missing file	roboflow --json video upload -f $SCRATCH/absent.mp4 -p $P	1	PASS
U8	unknown project	roboflow --json video upload -f $SCRATCH/unique-copy.mp4 -p no-such-project-xyz	3	PASS
U9	bad api key	roboflow --json -k bogus video upload-status <id> -p $P	2	PASS
U10	upload --poll-interval 0 is a usage error	roboflow --json video upload -f $SCRATCH/unique-copy.mp4 -p $P --poll-interval 0	2	PASS
U11	upload-status --poll-timeout -1 is a usage error	roboflow --json video upload-status <id> -p $P --wait --poll-timeout -1	2	PASS

Notes

1. An unknown project shows the server's generic --help hint instead of the CLI's project hint. The shared output_error lets a server hint win for every command, so it is out of scope here.
2. If the SDK's status read fails after the bytes are stored, the CLI cannot show the reserved video ID. Fixing that needs the SDK ([ar-api] Annotate Action Recognition video segments from Python  #534) to expose the ID on its error. The hint now says that re-uploading the same file reuses the stored Source.
3. A re-upload of known bytes links the existing Source, and segments live on that Source. Annotating it in one project therefore changes every project that holds it. This matters for the follow-up annotate command.

🤖 Generated with Claude Code

[digaobarbosa]

Staging verification

Run against https://api.roboflow.one / https://app.roboflow.one (hosts asserted before SDK import), isolated config dir, credentials loaded from a private file. Exercised through the real installed CLI (uv editable env, console script on PATH), not the test runner. Verified head 8ac66a1010327234db824400de65ae2cb8d6a1e6.

Disposable fixtures only, in model-evaluation-workspace. Project vid53-cli-native-video.

Fixtures

Two clips cut from my own footage, re-encoded so the content is unique to this card and no shared/deduplicated Source is touched. Both have integer nominal FPS, so this run does not cross the VID-49 fractional-FPS boundary (see limitations).

Fixture	fps	duration	time_base	frames	dims
vid53-walk.mp4	25	5.200000	1/12800	130	1920x1080
vid53-gesture.mov	30	4.566667	1/15360	137	1620x1080

Upload, status, canonical identity

$ roboflow --json video upload -p <ws>/vid53-cli-native-video -f vid53-walk.mp4 \
    -b vid53-clips -t "vid53,walk" --metadata '{"fixture":"vid53-walk"}' -s train
{ "videoId": "4xC6CzNqDf8AaFN8LTuA", "status": "uploaded",
  "resolvedBatch": { "id": "RAJN8IqDv26dGias8V7a", "name": "vid53-clips" } }        exit 0

$ roboflow --json video upload ... -f vid53-gesture.mov -s valid --no-wait
{ "videoId": "p5JU7eBVRAaULrV6qqSg", "status": "pending" }                          exit 0

$ roboflow video upload-status p5JU7eBVRAaULrV6qqSg -p <ws>/vid53-cli-native-video
Video ID: p5JU7eBVRAaULrV6qqSg
Status:   uploaded
Batch:    vid53-clips (RAJN8IqDv26dGias8V7a)                                        exit 0

$ roboflow --json video upload-status p5JU7eBVRAaULrV6qqSg -p ... --wait --poll-timeout 120
{ "videoId": "p5JU7eBVRAaULrV6qqSg", "status": "uploaded", "resolvedBatch": {...} }  exit 0

Owned-file dedup — re-uploading the same owned file returns the same canonical ID with resolvedBatch: null, so the reported ID stays the one to annotate:

$ roboflow --json video upload ... -f vid53-walk.mp4 -b vid53-clips
{ "videoId": "4xC6CzNqDf8AaFN8LTuA", "status": "uploaded",
  "resolvedBatch": null, "duplicate": true }                                        exit 0

Signed bytes preservation — SHA256 of the stored object fetched from the Source's signed URL, vs the local file:

4xC6CzNqDf8AaFN8LTuA  stored == local  True   (acb77ee53161720d…)
p5JU7eBVRAaULrV6qqSg  stored == local  True   (e226346d83b479ad…)

Annotation submit and readback

$ roboflow --json video annotate -p ... -i 4xC6CzNqDf8AaFN8LTuA -a walk-segments.json
{ "success": true, "inDataset": true, "createdClasses": ["walking","standing"] }     exit 0

$ roboflow --json video annotate -p ... -i p5JU7eBVRAaULrV6qqSg -a gesture-segments.json \
    -s test --no-add-to-dataset
{ "success": true, "inDataset": false, "createdClasses": ["hand_gesture"] }          exit 0

Readback of the MOV Source. Its real presentation timestamps are not frame_index * ticks_per_frame (index 5 is 3067, not 2560), and they came back untouched — the strongest available evidence that nothing is recomputed or re-encoded:

split: "test"
segments: [ { "id": "coco-1", "label": "hand_gesture",
              "startFrameIndex": 5, "endFrameIndex": 64,
              "startPts": 3067, "endPts": 33275,
              "startTimestampUs": 199674, "endTimestampUs": 2166341 } ]

3067 / 15360 = 0.199674 s — consistent with the declared rational time base.

Defaults, options, conflicts

Case	Result
Identical re-submit, no --overwrite	success: true, createdClasses: [], exit 0
Different segments, no --overwrite	"This video already has annotations. Send overwrite=true…", exit 1, hint names --overwrite
Same different document with --overwrite	success: true, exit 0
--no-add-to-dataset	inDataset: false
-s test	Source readback split: "test"

Dataset and export persistence

Project after both annotations: images: 1, splits: {train: 1, valid: 0, test: 0}. Only the clip added with the default membership counts; the --no-add-to-dataset MOV and the never-annotated clip do not. Generated version 1 → images: 1, splits: {train: 1}, then exported video-coco:

export/train/vid53-walk-mp4.4xC6CzNqDf8AaFN8LTuA/vid53-walk-mp4.mp4
export/train/vid53-walk-mp4.4xC6CzNqDf8AaFN8LTuA/_annotations.coco.json

• Exported video SHA256 acb77ee53161720d… — identical to the uploaded file.
• videos[0]: fps 25, duration 5.2, time_base {numerator: 1, denominator: 12800}, segment_count 2.
• segments: coco-1 frames 10–49 / pts 5120–25088, and coco-2 frames 70–109 / pts 35840–55808 — the post---overwrite values, confirming the overwrite persisted all the way into the generated artifact.
• The --no-add-to-dataset MOV is absent from the export, as intended.

Error paths through real dispatch

Command	Message	Exit
annotate malformed JSON	Invalid JSON in …	1
annotate non-object JSON	… must contain a JSON object.	1
annotate missing file	Cannot read annotation file: …	1
annotate zero segments	The roboflow-video-coco document has no segments (server)	1
annotate unknown video ID	Video not found	3
upload-status unknown video ID	Video … not found	3
upload unknown project	… does not exist or cannot be loaded …	3
upload .avi	Native video upload accepts .mp4 and .mov files	1
upload missing path	Video file not found: …	1
upload bad --metadata	Invalid metadata JSON: …	1

The three malformed-input cases never reached the API (asserted in the unit tests too).

Cleanup

$ roboflow --json project delete <ws>/vid53-cli-native-video --yes
{ "deleted": true, "projectId": "HK88oq2fLYG64gqJoYHf", "trash": true }

$ roboflow --json project get <ws>/vid53-cli-native-video
{"error": {"message": "… `GET /…/vid53-cli-native-video` does not exist …"}}   exit 3

$ roboflow --json trash list
{ "type": "project", "id": "HK88oq2fLYG64gqJoYHf", "name": "vid53-cli-native-video",
  "deletedAt": "2026-10-05T14:45:11.933Z", "scheduledCleanupAt": "2026-11-04T14:45:11.905Z" }

Only the owned project was removed, through public Trash. Trash ID matches the delete response. No shared or deduplicated Source, GCS object or Firestore record was touched.

CI

The matrix workflow does not run on this PR. .github/workflows/test.yml is gated to pull_request: branches: [main], and this PR targets bc/VID-36. It will fire once #534 merges and this is retargeted to main. I am not claiming matrix CI green.

Checks that did run on the exact head, all terminal and passing: pre-commit.ci - pr, Socket Security: Project Report, Socket Security: Pull Request Alerts.

To cover the gap, the CI matrix was reproduced locally on the exact head — full suite on each interpreter the workflow uses:

Python	Result
3.10.18	1154 tests, OK (1 skipped)
3.11.13	1154 tests, OK (1 skipped)
3.12.11	1154 tests, OK (1 skipped)
3.13.6	1154 tests, OK (1 skipped)

ruff check clean, mypy roboflow clean. This is local evidence, not CI, and it does not cover windows-latest.

Limitations

• Fractional FPS untested. Both fixtures are integer FPS (25, 30) on purpose, because VID-49 is not deployed. No header or PTS was altered to dodge the rounding, and no backend metadata was changed — the fractional path is simply out of scope for this card.
• Staging only. Tests and CI do not prove deployed behaviour, and nothing here establishes production.
• Class counts read back 0 for all three created classes. That is the known VID-30/31 counter work, not caused by this change.
• Annotation depends on the segment route being deployed to the target environment; it was reachable on staging during this run.
• windows-latest, training, inference and ZIP ingestion were not exercised.

[digaobarbosa]

Superseded by #544, which contained all of this branch and is merged to main.