feat(webrtc): process video files by URL with optional max_fps cap

[digaobarbosa]

Description

The objective here is to be able to process a video file that was already uploaded to GCS in asset library without a new download and upload through datachannel approach.

Adds two fields to WebRTCWorkerRequest (POST /initialise_webrtc_worker):

• video_file_url — HTTP(S) URL of a video file (mp4/webm/ogv/...). The server streams it directly with ffmpeg, so no data-channel chunk upload is needed. The URL passes the same SSRF guard used for image URL inputs (_validate_url_destination).
• max_fps — optional cap on the processed frame rate for video files. Frames are decimated with ffmpeg's fps filter (via PyAV's filter graph) inside ThreadedVideoFileTrack. Unset = all frames. The name reuses the established max_fps contract from InferencePipeline/VideoConfiguration.

With webrtc_realtime_processing: false the file is processed as fast as possible (existing ThreadedVideoFileTrack machinery, no pacing).

Implementation notes

• The tail of the chunk-upload handler was extracted into _begin_video_file_processing, shared by the upload path and the new URL branch — no duplicated logic. max_fps also applies to chunk-uploaded files.
• Effective FPS: when max_fps caps a file, _declared_fps (→ VideoFrame.fps / WebRTCVideoMetadata.declared_fps) reports the capped rate, so fps-sensitive workflow blocks (trackers, time-in-zone, velocity) see the real processed rate.
• The fps filter duplicates frames above the native rate, so the cap is only applied when max_fps < detected fps. In realtime mode max_fps is ignored (realtime has its own frame-drop logic) with a warning.
• URL processing is deferred until the peer connection and data channel are ready. A finite file processed at full speed finishes before the channel opens, silently dropping every output — caught in an end-to-end run, not by unit tests.
• Modal: new fields ride the pickled request; billing video_source label video_file_url; request-summary logging. The modal image needs a redeploy before clients send the new fields.

Testing

• Unit tests: request-model validation and fps-filter decimation on a synthetic mp4 (tests/.../webrtc_worker/test_video_file_source.py); full webrtc_worker suite passes (20/20).
• E2E against a locally running server with an aiortc client and a 48s/24fps file over HTTP:
  • max_fps: 5 → exactly 240 outputs, declared_fps=5.0, done in 0.9s
  • no max_fps → all 1152 frames, declared_fps=24.0, done in 3.4s
  • processing_complete delivered in both runs

Reviewer notes

• stream_output: [] is required for data-only sessions (None means "send video back"), same as before — the SDK already does this.
• Docs updated in docs/webrtc-streaming.md (request example + max_fps semantics).