OpenCut Video Editor Timeline Component Structure: Current State and Planned Architecture

The OpenCut video editor timeline component does not exist in the current codebase yet, as the application is being rewritten from the ground up, but the planned structure will likely follow the existing UI primitive patterns in apps/web/src/components/ui/ and utilize a dedicated apps/web/src/components/editor/timeline/ directory.

The OpenCut repository represents a complete rewrite of the video editor, with the current main branch containing only foundational UI primitives rather than full editor features. While the timeline functionality remains on the implementation roadmap according to the project README, analyzing the existing component architecture reveals clear conventions that will govern how the video editor timeline component structure is organized when development reaches that milestone.

Current State of the Timeline Component

The OpenCut source tree currently does not contain a concrete timeline UI component. A comprehensive search across the repository for "timeline" only returns matches in non-code files like .github/SECURITY.md, confirming the absence of this feature in the present codebase.

According to the Status section of the README.md, the project is actively being rewritten with planned features including an Editor API and first-class third-party plugin support. The UI library currently provides only generic primitives—such as sidebar.tsx, tooltip.tsx, button.tsx, and slider.tsx—located in apps/web/src/components/ui/. These components are built on top of @base-ui/react and serve as the low-level building blocks for future editor-specific interfaces.

Expected Video Editor Timeline Component Structure

Based on the established patterns in the existing UI architecture, the timeline implementation will likely adhere to a hierarchical component structure organized under a dedicated editor directory.

Directory Layout and File Organization

When the timeline component arrives, expect the following directory structure to emerge alongside the existing UI primitives:

apps/web/
└─ src/
   ├─ components/
   │  ├─ ui/                # Low-level building blocks (existing)

   │  └─ editor/            # Editor-specific UI (future)

   │     └─ timeline/
   │        ├─ Timeline.tsx          # Root component rendering track rows

   │        ├─ Track.tsx             # Individual video/audio track

   │        ├─ Clip.tsx              # Draggable clip blocks

   │        ├─ Playhead.tsx          # Moving playback cursor

   │        ├─ TimelineControls.tsx  # Zoom, snap, and add-track buttons

   │        └─ TimelineProvider.tsx  # Context provider for timeline state

   └─ lib/
      └─ utils.ts           # Tailwind class merging utilities

Component Hierarchy and Data Flow

The video editor timeline component structure will implement a nested composition pattern where Timeline renders multiple Track components, each hosting Clip components representing media segments.

Following the pattern established by SidebarProvider in apps/web/src/components/ui/sidebar.tsx, the timeline will likely utilize a TimelineProvider context to supply project timeline data to nested tracks and clips. This approach enables centralized state management for clip positions, zoom levels, and current selection without excessive prop drilling.

State management will likely leverage React state or a global store such as Zustand or Recoil to handle complex interactions like drag-and-drop positioning, playhead scrubbing, and multi-track synchronization.

Technical Implementation Conventions

Components in the timeline directory will import UI primitives from @base-ui/react, mirroring the existing sidebar implementation. Each file will utilize the cn helper function imported from #/lib/utils.ts for Tailwind CSS class composition and conditional styling.

Keyboard shortcuts will follow the pattern seen in SidebarProvider, potentially supporting combinations like Ctrl+←/→ to nudge the playhead or Delete to remove selected clips. The architecture will likely leverage mergeProps and the useRender helper from the existing utility patterns to ensure consistent behavior across interactive elements.

Key Files to Monitor for Timeline Development

When implementation begins, watch for these specific files in the repository:

Expected File	Purpose	Import Path
Timeline.tsx	Main canvas rendering tracks and playhead	#components/editor/timeline/Timeline.tsx
Track.tsx	Row component for video/audio/subtitle layers	#components/editor/timeline/Track.tsx
Clip.tsx	Draggable and resizable media block	#components/editor/timeline/Clip.tsx
Playhead.tsx	Vertical playback position indicator	#components/editor/timeline/Playhead.tsx
TimelineProvider.tsx	Context wrapper exposing timeline state	#components/editor/timeline/TimelineProvider.tsx

How to Verify Timeline Implementation Progress

To determine when the video editor timeline component structure becomes available in the codebase:

1. Search for component files using terms like Timeline.tsx or Track.tsx in the repository root.
2. Monitor the apps/web/src/components/editor/ directory, as this is the anticipated location for all editor-specific UI components.
3. Check for new imports from @base-ui/react or react-resizable-panels (used elsewhere for draggable interfaces) in recent commits.
4. Review the apps/web/src/routes/ directory for timeline-specific route definitions that would indicate functional UI integration.

Until these files appear, contributors can prepare by studying the patterns in apps/web/src/components/ui/sidebar.tsx and utilizing the cn utility from apps/web/src/lib/utils.ts to ensure compatibility with the existing design system.

Summary

• The OpenCut video editor timeline component does not currently exist in the main branch, as the project is undergoing a complete ground-up rewrite.
• Current UI primitives in apps/web/src/components/ui/ provide the foundation, utilizing @base-ui/react and Tailwind CSS with the cn helper from apps/web/src/lib/utils.ts.
• The anticipated timeline structure will reside in apps/web/src/components/editor/timeline/ with a component hierarchy of Timeline > Track > Clip.
• Implementation will likely feature a TimelineProvider context for state management and follow keyboard shortcut patterns established in the sidebar component.
• Contributors should monitor the components/editor/ directory for the appearance of Timeline.tsx, Track.tsx, and Clip.tsx files to track development progress.

Frequently Asked Questions

Is the timeline component available in OpenCut yet?

No, the timeline component is not available in the current OpenCut codebase. The repository contains only foundational UI primitives like buttons, sliders, and sidebars under apps/web/src/components/ui/, while the timeline remains on the implementation roadmap according to the project README.

Where will the OpenCut video editor timeline component be located when implemented?

When implemented, the timeline component will likely reside in apps/web/src/components/editor/timeline/, following the convention where apps/web/src/components/ui/ contains generic primitives and apps/web/src/components/editor/ houses higher-level editor-specific compositions.

What UI library does OpenCut use for its component architecture?

OpenCut builds its UI components on top of @base-ui/react, a low-level headless component library. This is evident in existing files like sidebar.tsx and tooltip.tsx, which import primitives from this library and utilize the cn helper function from apps/web/src/lib/utils.ts for Tailwind class merging.

How can I contribute to the timeline implementation in OpenCut?

To contribute, create the apps/web/src/components/editor/timeline/ directory and implement components following the existing patterns: import primitives from @base-ui/react, use the cn utility for styling, implement a context provider for state management similar to SidebarProvider, and ensure keyboard accessibility matches the shortcuts defined in the sidebar component.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}