Context
OneCMS requires video trimming functionality across multiple content workflows.
Historically, video trimming was attempted as a player-specific implementation and proved difficult to maintain and evolve. New trimming requirements are expected to appear in multiple areas of the CMS, increasing the risk of duplicated logic, inconsistent behavior, and tight coupling to specific player implementations.
At the same time, OneCMS already supports multiple player technologies and has an active player SDK ecosystem where similar functionality may eventually be adopted.
A decision was required regarding:
- ownership of trim state
- ownership of trim behavior
- player integration boundaries
- module structure
- future SDK compatibility
- separation of capability and presentation concerns
The architecture needed to support current OneCMS requirements without prematurely moving functionality into the player SDK.
Decision
Video trimming shall be implemented as two distinct layers:
1. Video Trim Manager
A platform-agnostic capability layer located under:
src/lib/internals/video-trim-manager
The Video Trim Manager shall own:
- trim state
- trim validation
- range selection behavior
- playback synchronization
- trim history
- event emission
- player contracts
The Video Trim Manager shall not depend on:
- React
- OneCMS modules
- Bitmovin
- Video.js
- Shaka
- backend workflows
- transcoding services
The manager shall interact with players exclusively through a normalized player contract.
2. Video Trim Module
A OneCMS-specific presentation layer located under:
src/modules/video-trim
The Video Trim Module shall own:
- UI rendering
- layout
- timeline rendering
- controls
- user interaction
- workflow orchestration
- backend integration
The module shall consume the Video Trim Manager and must not become the source of truth for trim state.
Ownership Model
The Video Trim Manager is the single source of truth for trimming behavior.
React hooks act as integration boundaries between React and the manager.
The Video Trim Module acts solely as a consumer of manager state and behavior.
Player Integration
Player implementations shall be adapted into a normalized contract before interacting with the Video Trim Manager.
The manager shall never directly reference a specific player implementation.
Folder Structure
The implementation shall follow existing OneCMS architectural conventions.
Hooks shall live under:
src/hooks/video-trim
Types required by the Video Trim Manager shall remain within the manager itself.
The capability layer shall remain self-contained and portable.
No module-local hooks, types, or services directories shall be introduced.
Dependency Management
Barrel exports shall not be used for this feature.
Direct imports shall be preferred to reduce dependency ambiguity and minimize circular dependency risk.
Consequences
Enables
- Reusable trim behavior across multiple CMS workflows
- Clear separation between capability and presentation
- Consistent trim behavior regardless of player implementation
- Future extraction into player SDKs if desired
- Independent evolution of UI and trim logic
- Simplified testing of trimming behavior
Restricts
- React components cannot own trim state
- Player-specific APIs cannot be consumed directly by trim logic
- Business workflows cannot be embedded into the manager
- Timeline rendering cannot become a dependency of trim behavior
Accepted Trade-Offs
- Additional abstraction through a player contract
- Additional manager layer between UI and player implementation
- Some implementation complexity in exchange for architectural separation
- Initial duplication between OneCMS and SDK efforts until patterns stabilize
Notes
The initial implementation intentionally excludes:
- thumbnail generation
- sprite generation
- timeline zooming
- chapter integration
- marker overlays
- transcoding workflows
These concerns may be added in future iterations but are not part of the Video Trim Manager responsibility.
The Video Trim Manager is conceptually a time-range selection engine rather than a player feature.
The architecture is designed to allow future SDK adoption without requiring SDK ownership today.
Architecture Overview
Related Documents:
- Video Trim System Specification v1.1