ef-timeline-ruler

Time ruler showing time labels and frame markers. Automatically adapts marker density based on zoom level.

Basic Usage

Ruler displays time markers and optional frame markers.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="ruler-demo">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="mt-4">
  <div class="h-[24px] bg-gray-900 rounded-t-lg overflow-hidden relative">
    <ef-timeline-ruler
      duration-ms="10000"
      fps="30"
      content-width="400"
    ></ef-timeline-ruler>
  </div>
  <div class="p-4 bg-gray-800 rounded-b-lg">
    <ef-controls target="ruler-demo" class="flex gap-4 items-center">
      <ef-toggle-play class="px-3 py-1 bg-blue-600 text-white rounded"></ef-toggle-play>
      <ef-time-display class="text-white font-mono"></ef-time-display>
    </ef-controls>
  </div>
</div>

Frame Markers at High Zoom

Frame markers appear when zoomed in enough for precision editing.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="frames-demo">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" sourcein="0s" sourceout="3s" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="mt-4 space-y-4">
  <div>
    <div class="text-white text-sm mb-2">Standard zoom - no frame markers:</div>
    <div class="h-[24px] bg-gray-900 rounded-lg overflow-auto">
      <ef-timeline-ruler
        duration-ms="3000"
        fps="30"
        content-width="120"
      ></ef-timeline-ruler>
    </div>
  </div>
  <div>
    <div class="text-white text-sm mb-2">High zoom - frame markers visible:</div>
    <div class="h-[24px] bg-gray-900 rounded-lg overflow-auto">
      <ef-timeline-ruler
        duration-ms="3000"
        fps="30"
        content-width="600"
      ></ef-timeline-ruler>
    </div>
  </div>
</div>

Used in Timeline

Ruler is automatically included in ef-timeline and ef-filmstrip.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="timeline-ruler">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
  <ef-text class="absolute bottom-4 left-4 text-white text-2xl">
    Timeline with Ruler
  </ef-text>
</ef-timegroup>
<div class="mt-4 h-[300px] bg-gray-900 rounded-lg overflow-hidden">
  <ef-timeline target="timeline-ruler"></ef-timeline>
</div>

Adaptive Time Labels

Time labels automatically adjust spacing based on zoom level. The ruler shows appropriate intervals:

• High zoom — 0.1s, 0.25s, 0.5s intervals
• Medium zoom — 1s, 2s, 5s intervals
• Low zoom — 10s, 30s, 60s intervals

Labels format as "Xs" or "X.Xs" depending on precision needed.

Frame Marker Behavior

Frame markers appear when:

1. Zoom level is high enough (each frame is at least 5px wide by default)
2. FPS is set (defaults to 30fps)

Frame markers are lighter than time markers to distinguish hierarchy.

At very high zoom, you can see individual frame boundaries for frame-accurate editing.

Virtualization

The ruler uses canvas virtualization for performance with long timelines:

• Only renders visible region plus buffer
• Maximum canvas width of 2000px
• Smooth scrolling with 200px buffer on each side

This allows timelines of any length without performance degradation.

Helper Functions

The module exports utility functions for working with frames:

quantizeToFrameTimeMs

Round time to the nearest frame boundary.

import { quantizeToFrameTimeMs } from '@editframe/elements';

const fps = 30;
const rawTime = 1234; // 1.234 seconds
const frameTime = quantizeToFrameTimeMs(rawTime, fps);
// Returns: 1233 (exactly 37 frames at 30fps)

calculateFrameIntervalMs

Get the duration of one frame.

import { calculateFrameIntervalMs } from '@editframe/elements';

const fps = 30;
const frameDuration = calculateFrameIntervalMs(fps);
// Returns: 33.333... (1000ms / 30fps)

calculatePixelsPerFrame

Calculate pixel width of a frame at current zoom.

import { calculatePixelsPerFrame } from '@editframe/elements';

const frameIntervalMs = 33.33; // 30fps
const pixelsPerMs = 0.2; // zoom level
const frameWidth = calculatePixelsPerFrame(frameIntervalMs, pixelsPerMs);
// Returns: 6.666 pixels per frame

shouldShowFrameMarkers

Determine if frame markers should be visible.

import { shouldShowFrameMarkers } from '@editframe/elements';

const pixelsPerFrame = 6.5;
const shouldShow = shouldShowFrameMarkers(pixelsPerFrame);
// Returns: true (frame is wider than 5px minimum)

const pixelsPerFrame = 2;
const shouldShow = shouldShowFrameMarkers(pixelsPerFrame);
// Returns: false (frame too narrow to display markers)

CSS Custom Properties

Ruler appearance uses theme variables:

ef-timeline-ruler {
  --ef-color-text-muted: #9ca3af;
  --ef-color-border-subtle: #6b7280;
}

Usage Context

The ruler is typically used as part of larger timeline components rather than standalone. It automatically reads zoom and scroll state from timeline context.

For custom timeline implementations, provide duration-ms, fps, and content-width explicitly.

Notes

• Ruler is typically used within Timeline or Filmstrip

• Frame markers appear automatically at high zoom levels

• Uses virtualized rendering for performance with long timelines

• Time labels adjust format based on duration and zoom

• Minimum spacing prevents marker overlap

• Canvas-based rendering for smooth performance