jE <%SrSSKrSSKrSSKrSSKJr SSKJr SSKJ r SSK J r SSK r SSKJr SSKJrJrJr "S S \\5r\R,"\5rS r\ \\S '"S S\5r"SS\5rS'SjrSr\ \\S'Sr \ \\S'S\ RBS\4Sjr"S\ S\4Sjr#S\ S\S\RS-4Sjr$S\ S\S\S\S\%\&\\R44 S jr'S\ S\S!\(S\%\&\\R44S"jr)"S#S$5r*"S%S&5r+g)(a&Video frame sampling utilities. This module is intentionally free of any docling imports. It provides two frame samplers over a video file, using ffmpeg as the only hard runtime dependency (ffmpeg is already required by the ASR path). - ``FixedIntervalFrameSampler`` extracts one frame every N seconds. - ``SimpleSceneChangeFrameSampler`` probes low-resolution frames and emits a representative frame per detected scene using a mean-absolute-difference heuristic. Both return ``VideoFrame`` objects carrying the frame image and its timestamp. N)Enum)BytesIO)Path)Final)Image) BaseModel ConfigDictFieldc \rSrSrSrSrSrSrg)VideoFrameSamplingModez/Frame sampling strategy for the video pipeline.fixed_interval scene_changeN)__name__ __module__ __qualname____firstlineno____doc__FIXED_INTERVAL SCENE_CHANGE__static_attributes__r_/home/mande/repo/quber/.venv/lib/python3.13/site-packages/docling/utils/video_frame_sampling.pyr r s9%N!Lrr zFFmpeg is required for video processing but was not found on PATH. Install it with your system package manager (e.g., 'brew install ffmpeg' on macOS, 'apt-get install ffmpeg' on Linux, 'winget install ffmpeg' on Windows).MISSING_FFMPEG_MESSAGEc\rSrSr%Sr\"SS9r\"SSSS9r\ \ S '\"SS S 9r \ R\ S '\"S SS 9r \S -\ S'Srg ) VideoFrame0z0A single sampled video frame with its timestamp.Tarbitrary_types_allowed.rzSeconds from video start.)ge description timestampzThe decoded frame image.)r"imageNz+Scene index if produced by a scene sampler.scene_idr)rrrrrr model_configr r#float__annotations__r$rr%intrrrrrr0sT:d;LSQ4OPIuPs0JKE5;;K  GHcDjrrct\rSrSr%Sr\"SS9r\\S'\ "SSS9r \ \S '\ "SSS9r \ \S 'S r \S -\S 'S rg ) VideoScene<z.A contiguous time window treated as one scene.Trr%.r)r! start_timeend_timeNrepresentative_framer)rrrrrr r&r)r(r r-r'r.r/rrrrrr+r+<sF8d;LMca(J(CA&He&.2*t+2rr+returncP[R"S5c[[5eg)Nffmpeg)shutilwhich RuntimeErrorrrrr_require_ffmpegr6Gs" ||H%122&rg~jt?_AUTO_PROMINENCE_FLOORg@_AUTO_PROMINENCE_Kdiffsc[[R"U55n[[R"[R"X- 555S-n[ [ U[ U--5$)uTAdapt the scene-cut threshold to how busy the video is. Uses the median frame difference as the ambient-motion floor and the (robust) median absolute deviation as its spread, so the threshold rises automatically for high-motion footage — ignoring hand-waving and body movement — and drops toward the floor for static screens, catching subtle cuts. Robust statistics are used so the cut spikes themselves do not inflate the estimate (unlike a plain standard deviation). Args: diffs: Frame-to-frame difference signal. Returns: The calibrated prominence threshold for peak detection. g)Ǻ?)r'npmedianabsmaxr7r8)r9r<mads r_auto_prominencer@XsS 299U# $F  "&&01 2V ;C %v0BS0H'H IIr video_pathc  [R"S5cg[R"SSSSSSS[ U5/S S S S 9n[ UR R55$![R[4a gf=f) zFReturn the video duration in seconds using ffprobe, or 0.0 on failure.ffprobez-verrorz -show_entrieszformat=durationz-ofz"default=noprint_wrappers=1:nokey=1T)capture_outputtextcheck) r3r4 subprocessrunstrr'stdoutstripCalledProcessError ValueError)rAouts r_probe_durationrQms ||I&nn!4J   SZZ%%'((  ) ): 6sA A%%BBr#c[R"SSSUSS[U5SSSS S S S / S SS9nURS:wdUR(d@[ R SUURURRSS5SS5 g[R"[UR55RS5$![a n[ R SX5 SnAgSnAff=f)zExtract a single frame at ``timestamp`` as a PIL image via ffmpeg. Returns None if ffmpeg produced no output (e.g. timestamp past end). r2-nostdin-ss.3f-iz -frames:v1-f image2pipe-vcodecpng-TFrFrHrz8Frame extraction at %.3fs produced no output (rc=%s): %sutf-8replace8NRGBz-Failed to decode extracted frame at %.3fs: %s)rIrJrK returncoderL_logdebugstderrdecoderopenrconvert Exception)rAr#procexcs r_extract_framerls >>   o   O        # D& !4;; F  OO KK  w 245 9  zz'$++./77>>  BISs7C C3C..C3startdurationfpsc2[R"SSSUSS[U5SUSSSU3S S S S S /SSS9nURS:wdUR(dA[ R SUURURRSS5SS5 /$/nURnSn[[U55Vs/sHoRXx5(dMUPM n n[U 5HrupU S-[U 5:aXS-O [U5n [R"[XkU 55R!S5n UR%XU- -U 45 Mt U$s snf!["a!n[ R SX5 SnAMSnAff=f)zDecode ``[start, start + duration]`` once at ``fps``, full resolution. Single ffmpeg spawn per call, seeking to ``start`` before decoding (fast input seek) rather than spawning one process per timestamp. r2rSrTrUrVz-t-vffps=rXrYrZr[r\TFr]rz9Range frame probe at %.3fs produced no output (rc=%s): %sr^r_r`NsPNG  raz,Failed to decode frame %d in range probe: %s)rIrJrKrbrLrcrdrerfrangelen startswith enumeraterrgrrhriappend)rArmrnrorjframesbufsigioffsetsidxoffendimgrks r_extract_frames_rangers >>   Sk   O n 3%L      "' D* !4;; G  OO KK  w 245 9   .0F ++C CC/D/Q^^C-Cq/GDg&"%'CL"8gAgc#h **WSS\23;;EBC  uSy(#./' ME   JJEs P  s$>E&E&0E++ F5FFsizec  [R"SSS[U5SSUSUSU3SS S S S / S SS9nURS:wdUR(d@[ R SURURRSS5SS5 /$X"-S-nURn[U5U-n/n[U5H<nXXU-US-U-n URX- [R"SX"4U 545 M> U$)a@Decode the whole video once at ``fps``, returning ``(timestamp, image)`` pairs. Uses a single ffmpeg pass emitting downscaled raw RGB frames, which is far cheaper than spawning one ffmpeg process per timestamp (each spawn re-opens and re-seeks the file). Frames are square ``size`` x ``size`` thumbnails; the timestamp of frame ``i`` is ``i / fps``. Args: video_path: Path to the source video. fps: Sampling rate for the decode pass. size: Width and height, in pixels, of the square thumbnails. Returns: ``(timestamp, image)`` pairs in chronological order. r2rSrVrqrrz,scale=:rXrawvideoz-pix_fmtrgb24r\TFr]rz0Batch frame probe produced no output (rc=%s): %sr^r_r`Nrsra)rIrJrKrbrLrcrdrerfrurtrxr frombytes) rArorrj frame_bytesrzcountryr|chunks r_extract_frames_gridrs$ >>     O 3%wtfAdV ,       D" !4;; > OO KK  w 245 9  +/K ++C H #E.0F 5\ Oq1u &;< qw|U KLM MrcP\rSrSrSrS S\S\S-4SjjrS\S\ \ 4S jr S r g) FixedIntervalFrameSampleriz;Sample one frame every ``interval_seconds`` from time zero.Ninterval_seconds max_framescfUS::a [S5eUbUS::a [S5eXlX lg)Nrzinterval_seconds must be > 0max_frames must be > 0 when set)rOrr)selfrrs r__init__"FixedIntervalFrameSampler.__init__s; q ;< <  !jAo>? ? 0$rrAr0c,[5 [U5n/nSnUS:XdXB:aoURb[U5UR:aU$[ X5nUcU$UR [ XES95 X@R- nUS:XaMhXB:aMoU$)NrD)r#r$)r6rQrrurlrxrr)rrArnrytr$s rsample FixedIntervalFrameSampler.sample's":.#% #o*s6{doo/M  #:1E}  MM*q> ? && &A#o r)rr)g$@N) rrrrrr'r)rrlistrrrrrrrrs@E#'!% % %$J %$z*:rrcj\rSrSrSrSS\S\S-S\S-S\S\S-S \S \S \4S jjrS \S\ \ \\ R44Sjr \ S\ RS\ RS\4Sj5r\ S\ RS\4Sj5rS \S\S\S\S\S-4 SjrS \S\ \4SjrS \S\ \4SjrSrg)SimpleSceneChangeFrameSampleri9uaDetect scenes via local peak detection on the frame-difference signal. No global threshold required. The sampler: 1. Probes the video at ``probe_fps`` (small RGB thumbnails). 2. Computes mean-absolute pixel difference between consecutive frames. 3. Smooths the resulting 1-D signal with a moving average. 4. Detects scene boundaries as local peaks using scipy.signal.find_peaks with a prominence criterion — self-calibrating per video, no manual threshold needed. 5. Selects the sharpest frame in a window around each scene midpoint as the representative keyframe, avoiding motion-blurred frames. N probe_fps prominencecuts_per_minutemin_scene_duration_secondsr probe_size smooth_windowsharpness_candidatesc US::a [S5eUbUS:a [S5eUS:a [S5eUbUS::a [S5eXlX lX0lX@lXPlX`lXplXlg)Nrzprobe_fps must be > 0zprominence must be >= 0z'min_scene_duration_seconds must be >= 0r) rOrrrrrrrr) rrrrrrrrrs rr&SimpleSceneChangeFrameSampler.__init__Gs >45 5  !j1n67 7 % )FG G  !jAo>? ?"$.*D'$$*$8!rrAr0cB[XRUR5$)zIExtract downscaled RGB probe frames at probe_fps in a single decode pass.)rrr)rrAs r _probe_frames+SimpleSceneChangeFrameSampler._probe_framescs#JPPrabcH[R"U[RS9n[R"U[RS9nURUR:wdURS:Xag[ [R "X#- 5R55S- $)zminrrlrrr)rrArmrr%midhalf window_start window_endwindow_durationnrro candidates best_frame best_scorerscores r _best_frame)SimpleSceneChangeFrameSampler._best_frame}s${c! s"S(5*- Dj) j7=  % % c !Q!V 1CKN ShG TX  1u'* o )-   FAsOOC(Ez!" '!3R ! rc URU5n[U5S:a/$UVs/sHo3SPM nn[R"[ [U5S- 5Vs/sH"nUR X%SX%S-S5PM$ sn5n[ SUR5n[R"U[R"U5U- SS9n[ S[URUR-55n URb[ U [SUR- UR-55n [[R"US55n SSKJn U "XU S 9up[$R'S U U [U 55 OJUR(b UR(nO [+U5n[$R'S U5 SSKJn U "XU S 9upU Vs/sHo4UUR:dMUPM nnUS/UVs/sHo4UPM sn-nUS n/n[-U5H<unnUS-[U5:aUUS-OUnUR/[1UUUS95 M> U$s snfs snfs snfs snf)zBDetect scene boundaries using local peak detection on frame diffs.rrrssame)modegN@K) find_peaks)distancerz=Cuts/min mode: interval=%d frames, noise_floor=%.4f, peaks=%dz Prominence mode: prominence=%.4f)rrr)r%r-r.)rrur;arrayrtrr>rconvolveonesr)rrrr' percentile scipy.signalrrcrdrr@rwrxr+)rrAprobesp timestampsr|r9wsmoothedmin_disttarget_interval noise_floorrpeaks_r valid_peaks boundariesr.scenesr~rmstops r detect_scenes+SimpleSceneChangeFrameSampler.detect_scenessg##J/ v;?I$*+FqdF +s6{Q/ /A##FIaL&Q-2BC/   4%% &;;ubggaj1n6Bq#d==NOP    +!#td&:&::dnnLMO  h ;#%#J/JC*-'C O*C:cAg&D MM*cedS T0 k, R (LsI, )I1I64I6I;c>[5 URU5n/nUHynURb[U5UR:a U$UR XR UR UR5nUcMbXTlURU5 M{ U$)z9Sample one sharp representative frame per detected scene.) r6rrrurr-r.r%r/rx)rrArrysceneframes rr$SimpleSceneChangeFrameSampler.samples##J/#%E*s6{doo/M $$,,ennennE -2* e$ r)rrrrrrrr)g?NNrN@rs)rrrrrr'r)rrrtuplerr staticmethodrrrrr+rrrrrrrr9sd #'(,,/!%$%99DL9 9 %* 9 $J 999"98QQeE5;;rs  11"S$""c   333(-e ,P$'E%L&KJBJJJ5J*2$t$$%++:L$N33"3.33:?3 %u{{" #$3l22 2(+2 %u{{" #$2jB}}r