feat: add multi-track timeline foundation

[YLaxmikanth]

Description

This PR introduces a Phase 1 MVP implementation of Reframe’s multi-track non-linear timeline architecture.

The objective of this phase is to establish a scalable and extensible foundation for layered video editing workflows while preserving compatibility with the existing single-track editor pipeline.

This implementation focuses on:

• reusable multi-track timeline state management
• layered preview rendering
• Picture-in-Picture (PiP) compositing support
• dynamic FFmpeg overlay graph generation
• timeline utility abstractions
• extensible architecture for future non-linear editing features

The scope intentionally avoids a risky full-editor rewrite in a single PR and instead introduces a clean incremental foundation.

---

Related Issue

Closes #1204

---

Type of Contribution

• Bug fix
• New feature
• Documentation update
• Refactor
• GSSoC contribution

---

Participant Info

• GitHub username: YLaxmikanth
• Contribution level (Beginner/Intermediate/Advanced): Advanced

---

Checklist

• I have read the contribution guidelines
• My changes follow the project structure
• I have tested my changes in Chrome, Firefox, and Safari
• bun run lint passes (no ESLint errors)
• bunx tsc --noEmit passes (no TypeScript errors)
• New interactive elements have aria-label / accessible names
• No console.log statements left in
• This PR is related to a valid issue
• Screen recording attached above (required for UI/feature/design changes)

---

Architecture Summary

Background

The previous editing workflow was primarily built around a single-video editing model:

• one uploaded source
• one render layer
• one export pipeline

While suitable for simple trimming/cropping workflows, this structure limited support for:

• multi-layer compositing
• Picture-in-Picture layouts
• layered rendering
• timeline-based editing
• future transition and animation systems

---

Phase 1 MVP Goals

This PR establishes the core primitives required for future non-linear editing support while keeping the implementation:

• mergeable
• incremental
• browser-performance conscious
• FFmpeg.wasm compatible

This phase intentionally excludes:

• transitions
• keyframes
• audio mixing
• waveform editing
• timeline zooming
• animation curves
• advanced drag timelines

---

Core Features

Multi-Track Timeline Data Model

Introduced reusable timeline primitives in:

• src/lib/types.ts

New structures include:

• TimelineTrack
• TimelineTrackType
• TrackTransform
• TrackPosition

Tracks now support:

• z-index layering
• visibility toggling
• opacity
• positioning
• scaling
• rotation
• duration metadata

---

Timeline Utility Layer

Added:

• src/lib/timeline.ts

Implements:

• immutable track creation
• track updates
• ordering helpers
• selection helpers
• validation helpers
• constrained Phase 1 track limits

This creates a stable foundation for future timeline editing workflows.

---

Dynamic FFmpeg Overlay Graph Generation

Added:

• src/lib/overlayGraph.ts

Introduced:

• buildOverlayFilterGraph()

The system dynamically generates FFmpeg filter_complex overlay graphs for:

• layered compositing
• scaling
• Picture-in-Picture rendering
• overlay positioning
• track ordering

Example generated graph:

[0:v]scale=1080:1920[bg];
[1:v]scale=480:432[pip];
[bg][pip]overlay=20:20[outv]

This architecture establishes the foundation for future:

• transitions
• compositing pipelines
• animated transforms
• advanced layering systems

---

Layered Preview Rendering

Updated:

• src/components/VideoPreview.tsx

The preview renderer now supports:

• multiple simultaneous video layers
• z-index ordering
• opacity rendering
• scaling transforms
• PiP positioning

while preserving:

• responsive behavior
• existing editor compatibility
• browser rendering performance

---

Extended Editor State Management

Updated:

• src/hooks/useVideoEditor.ts

Added:

• multi-track timeline state
• track CRUD operations
• synchronization helpers
• backward-compatible single-track bridging

Existing workflows remain functional without regressions.

---

Test Coverage

Added:

• src/lib/tests/timeline.test.ts
• src/lib/tests/overlayGraph.test.ts

Coverage includes:

• overlay graph generation
• immutable state updates
• track ordering
• scaling calculations
• PiP positioning
• validation constraints
• lifecycle helpers

---

Validation

Build

• npm run build ✅

Lint

• npm run lint ✅

Tests

• npm run test ✅
• 115 tests passing

TypeScript

• bunx tsc --noEmit ✅

---

Files Added

New Files

• src/lib/timeline.ts
• src/lib/overlayGraph.ts
• src/lib/tests/timeline.test.ts
• src/lib/tests/overlayGraph.test.ts
• PHASE_1_MVP.md

Updated Files

• src/lib/types.ts
• src/hooks/useVideoEditor.ts
• src/components/VideoPreview.tsx
• vitest.config.ts

---

Performance Considerations

FFmpeg.wasm operates entirely inside the browser and is constrained by available memory and CPU resources.

To ensure Phase 1 remains stable:

• simultaneous tracks are intentionally limited
• overlay graph complexity is constrained
• unnecessary rerenders are minimized
• immutable lightweight state patterns are used

This keeps the implementation practical for browser-based processing.

---

Future Roadmap

This architecture now enables future incremental work for:

• draggable timeline editor
• transitions
• animated transforms
• keyframes
• audio layering
• waveform rendering
• grouped tracks
• advanced compositing
• timeline zooming
• collaborative editing

without requiring another foundational rewrite.

---

Expected Outcome

Reframe now has a scalable foundational architecture for:

• multi-track editing
• layered compositing
• Picture-in-Picture workflows
• dynamic FFmpeg overlay generation

while remaining:

• incremental
• browser-conscious
• backward-compatible
• maintainable

[vercel]

@YLaxmikanth is attempting to deploy a commit to the magic-peach1's projects Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

✅ PR Format Check Passed — @YLaxmikanth

Basic format checks passed. A maintainer will review your code changes.

This does not mean the PR is approved — it just means the format is correct.

[github-actions]

👋 Thanks for your PR, @YLaxmikanth!

Welcome to Reframe — a browser-based video editor built for everyone 🎬

🟠 GSSoC'26 PR detected — thanks for contributing under GirlScript Summer of Code 2026!

What happens next

1. 🤖 Automated checks — build & TypeScript typecheck will run automatically
2. ✅ Vercel preview — a preview deployment will be created (requires maintainer authorization for fork PRs)
3. 👀 Code review — a maintainer will review your changes
4. 🚀 Merge — once approved, your PR will be merged!

Quick checklist

• PR title follows Conventional Commits (e.g. feat: add dark mode)
• Linked the issue this PR closes (e.g. Closes #123)
• Tested the changes locally (bun run dev)
• Build passes (bun run build)

Useful links

• 📖 CONTRIBUTING.md
• 🐛 Open Issues
• ⭐ Star the repo to support the project!

Happy coding! 🎉

[YLaxmikanth]

Implemented the requested Phase 1 multi-track timeline foundation architecture for #1204.

Included

• Multi-track timeline state model
• Layered preview rendering
• Dynamic FFmpeg overlay graph generation
• Basic PiP compositing support
• Timeline utility abstractions
• Overlay graph + timeline unit tests
• Backward-compatible single-track support

Validation

• npm run build ✅
• npm run lint ✅
• bunx tsc --noEmit ✅
• npm run test ✅ (115 passing tests)

Also cleaned up:

• generated build artifact issues affecting CI
• strict TypeScript safety issues
• noisy test console output

The implementation intentionally limits Phase 1 to lightweight foundational primitives and avoids a risky full-editor rewrite in a single PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
reframe	Ready	Preview, Comment	May 26, 2026 10:06am

[magic-peach]

@YLaxmikanth please add a screen recording so that i can approve the changes