Player Component

The <Player> is the main playback container for Elucim animations. It wraps a <Scene>, adds a playback timeline, controls bar, and keyboard shortcuts. Every standalone animation needs a Player.

Props

Prop	Type	Default	Description
width	number	1920	Scene width in pixels
height	number	1080	Scene height in pixels
fps	number	60	Frames per second
durationInFrames	number	required	Total frames in the animation
background	string	'#000'	Background color
controls	boolean	true	Show the controls bar (play/pause, scrubber, frame counter)
loop	boolean	true	Loop playback when it reaches the end
autoPlay	boolean	false	Start playing automatically on mount
className	string	—	CSS class for the root element
style	React.CSSProperties	—	Inline styles for the root element
children	React.ReactNode	—	Elucim primitives, animations, and math components

Basic Usage

import { Player, FadeIn, Circle, Text } from '@elucim/core';

<Player width={800} height={600} fps={30} durationInFrames={90}>
  <FadeIn duration={20}>
    <Circle cx={400} cy={300} r={80} stroke="#6c5ce7" strokeWidth={3} />
  </FadeIn>
  <FadeIn duration={20}>
    <Text x={400} y={305} fill="#fff" fontSize={24} textAnchor="middle">
      Hello World
    </Text>
  </FadeIn>
</Player>

Keyboard Controls

When the Player is focused, the following keyboard shortcuts are available:

Key	Action
Space	Play / Pause
←	Seek backward 1 frame
→	Seek forward 1 frame
Shift + ←	Seek backward 10 frames
Shift + →	Seek forward 10 frames
Home	Jump to the first frame
End	Jump to the last frame

Sizing Behavior

The Player renders an SVG with a viewBox of 0 0 {width} {height}, so it scales responsively to fit its container while preserving the aspect ratio. The width and height props define the coordinate system, not the CSS size.

{/* 16:9 coordinate space, but fills its parent container */}
<Player width={1920} height={1080} fps={60} durationInFrames={300}>
  {/* coordinates go from 0,0 to 1920,1080 */}
</Player>

CSS Customization

The Player’s root element can be styled with className and style. The controls bar inherits from the Player’s container, so you can scope custom styles to your class:

<Player
  className="my-player"
  style={{ maxWidth: 800, margin: '0 auto' }}
  width={1920}
  height={1080}
  fps={60}
  durationInFrames={180}
>
  {/* ... */}
</Player>

Tip

For embedding in a blog or docs site, set controls={true} and loop={true} so readers can replay the animation. For a cinematic feel, use autoPlay={true} and controls={false}.

Theme-Aware Defaults

The Player automatically adapts to light and dark themes using the CSS light-dark() function. Out of the box, the controls bar picks appropriate colors for both themes — no custom CSS required.

Default	Light	Dark
Controls background	#f5f5f5	#1a1a2e
Controls text	#333	#e0e0e0
Scrubber accent	#6c5ce7	#4ecdc4

These defaults work because the Player sets color-scheme: light dark on its container, allowing the browser to resolve light-dark() values based on the active theme.

To override, pass controlsBackground, controlsColor, or controlsAccent (or use your own CSS).

Inside a Presentation

When a Player is rendered inside a <Slide>, it automatically detects the Presentation context and adjusts its behavior:

• Background becomes transparent (inherits the slide/presentation background)
• Width and height expand to fill the slide
• Set controls={false} to hide the controls bar — the Presentation provides its own HUD and navigation

<Slide title="My Slide">
  <Player width={1920} height={1080} fps={30} durationInFrames={90}
          autoPlay loop controls={false}>
    {/* slide content */}
  </Player>
</Slide>