HumanSignal · niklub · Aug 21, 2025 · May 26, 2025 · May 27, 2025 · May 27, 2025
diff --git a/web/libs/core/src/hooks/useRefCallback.ts b/web/libs/core/src/hooks/useRefCallback.ts
@@ -0,0 +1,10 @@
+import { useValueRef } from "@humansignal/core/hooks/useValueRef";
+import { useCallback } from "react";
+
+export function useRefCallback<T extends (...args: any[]) => any>(callback: T) {
+  const ref = useValueRef<T>(callback);
+
+  return useCallback((...args: Parameters<T>): ReturnType<T> => {
+    return ref.current(...args);
+  }, []);
+}
diff --git a/web/libs/core/src/hooks/useValueRef.ts b/web/libs/core/src/hooks/useValueRef.ts
@@ -0,0 +1,7 @@
+import { useRef } from "react";
+
+export function useValueRef<T>(value: T) {
+  const ref = useRef<T>(value);
+  ref.current = value;
+  return ref;
+}
diff --git a/web/libs/core/src/lib/utils/feature-flags/flags.ts b/web/libs/core/src/lib/utils/feature-flags/flags.ts
@@ -73,6 +73,11 @@ export const FF_ADJUSTABLE_SPANS = "fflag_feat_front_leap_1973_adjustable_spans_
  */
 export const FF_THEME_TOGGLE = "fflag_feat_front_optic_1217_theme_toggle_short";
 
+/**
+ * Fixes synced audio/video buffering
+ */
+export const FF_SYNCED_BUFFERING = "fflag_fix_front_fit_31_synced_media_buffering";
+
 /**
  * Enables the summary view for annotations
  */

diff --git a/web/libs/core/src/lib/utils/schema/tags.json b/web/libs/core/src/lib/utils/schema/tags.json
@@ -738,7 +738,7 @@
   },
   "Video": {
     "name": "Video",
-    "description": "Video tag plays a simple video file. Use for video annotation tasks such as classification and transcription.\n\nUse with the following data types: video\n\n### Video format\n\nLabel Studio relies on your web browser to play videos and evaluate the total frame number. So, it's essential that your videos use a format and codecs that are universally supported. To ensure maximum compatibility, we recommend using an MP4 container with video encoded using the H.264 (AVC) codec and audio encoded with AAC. This combination is widely supported across all modern browsers and minimizes issues like incorrect total duration detection or problems with playback. In addition, it's important to convert your videos to a constant frame rate (CFR), ideally around 30 fps, to avoid discrepancies in frame counts and issues with duplicated or missing frames. All audio and video streams from your file must have the same durations; otherwise, you will have extra total frames.\n\nConverting your videos to this recommended format will help ensure that they play smoothly in Label Studio and that the frame rate and duration are correctly recognized for accurate annotations. To convert any video to this format, you can use FFmpeg. For example, the following commands convert an input video to MP4 with H.264 video, AAC audio, and a constant frame rate of 30 fps:\n\n```bash\n# Extract the exact video stream duration in seconds\nDUR=$(ffprobe -v error -select_streams v:0 -show_entries stream=duration -of default=nokey=1:noprint_wrappers=1 input.mp4)\n# Re-encode media file to recommended format\nffmpeg -i input_video.mp4 -c:v libx264 -profile:v high -level 4.0 -pix_fmt yuv420p -r 30 -c:a aac -b:a 128k -to $DUR output_video.mp4\n```\n\nIn this command:\n- `-i input_video.mp4` specifies your source video.\n- `-c:v libx264` uses the H.264 codec for video encoding.\n- `-profile:v high -level 4.0` sets compatibility parameters for a broad range of devices.\n- `-pix_fmt yuv420p` ensures the pixel format is compatible with most browsers.\n- `-r 30` forces a constant frame rate of 30 fps. You can also omit the -r option, ffmpeg will save your current frame rate. This is fine if you are 100% certain that your video has a constant frame rate.\n- `-c:a aac -b:a 128k` encodes the audio in AAC at 128 kbps.\n- `-to` stops writing output as soon as the container clock hits your video’s end timestamp, so any extra audio tail is automatically dropped.\n- `output_video.mp4` is the converted video file ready for use in Label Studio.\n\nUsing this FFmpeg command to re-encode your videos will help eliminate playback issues and ensure that Label Studio detects the total video duration  accurately, providing a smooth annotation experience.\n\nIt is a good idea to check all parameters of your video using this command:\n```bash\nffprobe -v error -show_format -show_streams -print_format json input.mp4\n```",
+    "description": "Video tag plays a simple video file. Use for video annotation tasks such as classification and transcription.\n\nUse with the following data types: video\n\n### Video format\n\nLabel Studio relies on your web browser to play videos and evaluate the total frame number. So, it's essential that your videos use a format and codecs that are universally supported. To ensure maximum compatibility, we recommend using an MP4 container with video encoded using the H.264 (AVC) codec and audio encoded with AAC. This combination is widely supported across all modern browsers and minimizes issues like incorrect total duration detection or problems with playback. In addition, it's important to convert your videos to a constant frame rate (CFR), ideally around 30 fps, to avoid discrepancies in frame counts and issues with duplicated or missing frames. All audio and video streams from your file must have the same durations; otherwise, you will have extra total frames.\n\nConverting your videos to this recommended format will help ensure that they play smoothly in Label Studio and that the frame rate and duration are correctly recognized for accurate annotations. To convert any video to this format, you can use FFmpeg. For example, the following commands convert an input video to MP4 with H.264 video, AAC audio, and a constant frame rate of 30 fps:\n\n```bash\n# Extract the exact video stream duration in seconds\nDUR=$(ffprobe -v error -select_streams v:0 -show_entries stream=duration -of default=nokey=1:noprint_wrappers=1 input.mp4)\n# Re-encode media file to recommended format\nffmpeg -i input_video.mp4 -c:v libx264 -profile:v high -level 4.0 -pix_fmt yuv420p -r 30 -c:a aac -b:a 128k -to $DUR output_video.mp4\n```\n\nIn this command:\n- `-i input_video.mp4` specifies your source video.\n- `-c:v libx264` uses the H.264 codec for video encoding.\n- `-profile:v high -level 4.0` sets compatibility parameters for a broad range of devices.\n- `-pix_fmt yuv420p` ensures the pixel format is compatible with most browsers.\n- `-r 30` forces a constant frame rate of 30 fps. You can also omit the -r option, ffmpeg will save your current frame rate. This is fine if you are 100% certain that your video has a constant frame rate.\n- `-c:a aac -b:a 128k` encodes the audio in AAC at 128 kbps.\n- `-to` stops writing output as soon as the container clock hits your video's end timestamp, so any extra audio tail is automatically dropped.\n- `output_video.mp4` is the converted video file ready for use in Label Studio.\n\nUsing this FFmpeg command to re-encode your videos will help eliminate playback issues and ensure that Label Studio detects the total video duration accurately, providing a smooth annotation experience.\n\nIt is a good idea to check all parameters of your video using this command:\n```bash\nffprobe -v error -show_format -show_streams -print_format json input.mp4\n```",
     "attrs": {
       "name": {
         "name": "name",

@@ -1,7 +1,30 @@
 .timeline-controls {
+  position: relative;
   background: var(--color-neutral-background-bold);
   padding: 4px;
 
+  &__buffering {
+    left: 0;
+    right: 0;
+    top: 0;
+    height: 4px;
+    position: absolute;
+    background-color: var(--color-primary-content);
+    overflow: hidden;
+
+    &::after {
+      content: "";
+      position: absolute;
+      top: 0;
+      left: -100%;
+      width: 25%;
+      height: 100%;
+      will-change: left;
+      background-color: var(--color-primary-content-subtle);
+      animation: buffering-media 800ms ease-out infinite;
+    }
+  }
+
   &__counter {
     height: 36px;
     min-width: 115px;
@@ -86,7 +109,7 @@
         }
       }
 
-      & + & {
+      &+& {
         border-left: 1px solid var(--color-neutral-border);
       }
     }
@@ -111,3 +134,13 @@
     background: var(--color-neutral-surface);
   }
 }
+
+@keyframes buffering-media {
+  0% {
+    left: -100%;
+  }
+
+  100% {
+    left: 100%;
+  }
+}
@@ -50,6 +50,7 @@ export const Controls: FC<TimelineControlsProps> = memo(
     position,
     frameRate = 1024,
     playing,
+    buffering = false,
     collapsed,
     duration,
     extraControls,
@@ -174,6 +175,7 @@ export const Controls: FC<TimelineControlsProps> = memo(
 
     return (
       <Block name="timeline-controls" tag={Space} spread style={{ gridAutoColumns: "auto" }}>
+        {buffering && <Elem name="buffering" aria-label="Buffering Media Source" />}
         {mediaType === "audio" ? (
           renderControls()
         ) : (

@@ -3,15 +3,13 @@
   background-color: var(--color-neutral-background);
 
   &__topbar {
+    padding-bottom: var(--spacing-tight);
     min-height: 48px;
-    padding: 6px;
     display: grid;
     grid-row-gap: 8px;
     align-items: center;
     grid-auto-rows: min-content;
     grid-template-rows: 1fr;
-    border-top: 1px solid var(--color-neutral-border);
-    border-bottom: 1px solid var(--color-neutral-border);
   }
 }
 

@@ -21,6 +21,7 @@ const TimelineComponent: FC<TimelineProps> = ({
   altHopSize = 1,
   hopSize = altHopSize,
   playing = false,
+  buffering = false,
   fullscreen = false,
   disableView = false,
   defaultStepSize = 10,
@@ -129,6 +130,7 @@ const TimelineComponent: FC<TimelineProps> = ({
         position={currentPosition}
         frameRate={framerate}
         playing={playing}
+        buffering={buffering}
         volume={props.volume}
         controls={props.controls}
         altHopSize={altHopSize}

@@ -16,6 +16,7 @@ export interface TimelineProps<D extends ViewTypes = "frames"> {
   mode: D;
   framerate: number;
   playing: boolean;
+  buffering?: boolean;
   zoom?: number;
   volume?: number;
   speed?: number;
@@ -184,6 +185,7 @@ export interface TimelineControlsProps {
   playing: boolean;
   collapsed: boolean;
   fullscreen: boolean;
+  buffering?: boolean;
   volume?: number;
   speed?: number;
   zoom?: number;

@@ -39,7 +39,7 @@
     padding: 2px 7px;
     text-align: center;
     background-color: var(--color-neutral-background);
-    background-image: repeating-linear-gradient(90deg, var(--grape_500) 0, var(--grape_400) 120px, var(--grape_500) 240px);
+    background-image: repeating-linear-gradient(90deg, var(--color-primary-content) 0, var(--color-primary-content-subtle) 120px, var(--color-primary-content) 240px);
     animation: buffering 1.2s linear infinite;
   }
 }
@@ -72,4 +72,4 @@
   100% {
     background-position: 240px 0;
   }
-}
+}