> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# Animation helpers

> Powerful animation utilities for creating smooth transitions and motion in Helios

Helios provides a comprehensive set of animation helpers to create smooth, natural motion in your video compositions. These utilities handle interpolation, spring physics, and easing functions.

## interpolate()

Maps an input value from one range to another with support for easing and extrapolation.

```typescript theme={null}
import { interpolate } from '@helios-project/core';

const opacity = interpolate(frame, [0, 30], [0, 1]);
const scale = interpolate(frame, [0, 60, 120], [1, 1.5, 1]);
```

### Parameters

<ParamField path="input" type="number" required>
  The value to interpolate
</ParamField>

<ParamField path="inputRange" type="number[]" required>
  Array of input values (must be strictly monotonically increasing). Minimum 2 elements.
</ParamField>

<ParamField path="outputRange" type="number[]" required>
  Array of output values (must match length of inputRange)
</ParamField>

<ParamField path="options" type="InterpolateOptions">
  Configuration for extrapolation and easing

  <Expandable title="properties">
    <ParamField path="extrapolateLeft" type="'extend' | 'clamp' | 'identity'" default="'extend'">
      Behavior when input is less than the minimum inputRange value:

      * `extend`: Continue the trend linearly
      * `clamp`: Return the first outputRange value
      * `identity`: Return the input value unchanged
    </ParamField>

    <ParamField path="extrapolateRight" type="'extend' | 'clamp' | 'identity'" default="'extend'">
      Behavior when input is greater than the maximum inputRange value
    </ParamField>

    <ParamField path="easing" type="(t: number) => number">
      Easing function to apply to the interpolation. Use functions from the `Easing` object.
    </ParamField>
  </Expandable>
</ParamField>

### Returns

`number` - The interpolated value

### Examples

#### Basic interpolation

```typescript theme={null}
import { interpolate } from '@helios-project/core';
import { useVideoFrame } from './hooks/useVideoFrame';

function AnimatedBox({ helios }) {
  const frame = useVideoFrame(helios);
  
  // Fade in over first 30 frames
  const opacity = interpolate(frame, [0, 30], [0, 1]);
  
  // Move from left to right
  const x = interpolate(frame, [0, 120], [0, 800]);
  
  return (
    <div style={{ opacity, transform: `translateX(${x}px)` }}>
      Content
    </div>
  );
}
```

#### Multi-point interpolation

```typescript theme={null}
// Create a bounce effect with multiple keyframes
const y = interpolate(
  frame,
  [0, 30, 60, 90, 120],
  [0, -100, -50, -75, 0]
);
```

#### With extrapolation

```typescript theme={null}
const x = interpolate(
  frame,
  [0, 60],
  [0, 200],
  { extrapolateRight: 'clamp' } // Stop at 200 after frame 60
);
```

#### With easing

```typescript theme={null}
import { interpolate, Easing } from '@helios-project/core';

const scale = interpolate(
  frame,
  [0, 60],
  [1, 2],
  { easing: Easing.cubic.out }
);
```

## spring()

Calculates spring physics values for natural, bouncy motion using a damped harmonic oscillator simulation.

```typescript theme={null}
import { spring } from '@helios-project/core';

const scale = spring({
  frame,
  fps: 30,
  from: 0,
  to: 1,
  config: { stiffness: 100, damping: 10 }
});
```

### Parameters

<ParamField path="options" type="SpringOptions" required>
  Spring configuration object

  <Expandable title="properties">
    <ParamField path="frame" type="number" required>
      Current frame number
    </ParamField>

    <ParamField path="fps" type="number" required>
      Frames per second of the composition
    </ParamField>

    <ParamField path="from" type="number" default="0">
      Starting value of the spring animation
    </ParamField>

    <ParamField path="to" type="number" default="1">
      Target value the spring animates toward
    </ParamField>

    <ParamField path="config" type="SpringConfig">
      Spring physics parameters

      <Expandable title="properties">
        <ParamField path="mass" type="number" default="1">
          Mass of the spring. Higher values create slower, heavier motion.
        </ParamField>

        <ParamField path="stiffness" type="number" default="100">
          Spring stiffness. Higher values create faster, tighter springs.
        </ParamField>

        <ParamField path="damping" type="number" default="10">
          Damping force. Higher values reduce oscillation and settling time.
        </ParamField>

        <ParamField path="overshootClamping" type="boolean" default="false">
          If true, prevents the spring from overshooting the target value
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="durationInFrames" type="number">
      Optional duration hint (currently ignored as physics simulations are time-based)
    </ParamField>
  </Expandable>
</ParamField>

### Returns

`number` - The calculated spring value at the current frame

### Examples

#### Basic spring animation

```typescript theme={null}
import { spring } from '@helios-project/core';

function SpringBox({ helios }) {
  const frame = useVideoFrame(helios);
  
  const scale = spring({
    frame,
    fps: 30,
    from: 0,
    to: 1
  });
  
  return (
    <div style={{ transform: `scale(${scale})` }}>
      Bouncy!
    </div>
  );
}
```

#### Configuring spring physics

```typescript theme={null}
// Tight, fast spring
const tightSpring = spring({
  frame,
  fps: 30,
  config: { stiffness: 200, damping: 15 }
});

// Loose, wobbly spring
const wobblySpring = spring({
  frame,
  fps: 30,
  config: { stiffness: 50, damping: 5 }
});

// Heavy, slow spring
const heavySpring = spring({
  frame,
  fps: 30,
  config: { mass: 5, stiffness: 100, damping: 20 }
});
```

#### Preventing overshoot

```typescript theme={null}
const scale = spring({
  frame,
  fps: 30,
  from: 0,
  to: 1,
  config: { overshootClamping: true } // Never goes above 1
});
```

## calculateSpringDuration()

Estimates how many frames a spring animation needs to settle within a threshold.

```typescript theme={null}
import { calculateSpringDuration } from '@helios-project/core';

const duration = calculateSpringDuration(
  { fps: 30, config: { stiffness: 100, damping: 10 } },
  0.001 // threshold
);
```

### Parameters

<ParamField path="options" type="Omit<SpringOptions, 'frame'>" required>
  Spring configuration (same as `spring()` but without `frame`)
</ParamField>

<ParamField path="threshold" type="number" default="0.001">
  Distance from target value to consider the spring "settled"
</ParamField>

### Returns

`number` - Estimated duration in frames

## Easing functions

Helios includes a comprehensive library of easing functions for use with `interpolate()` and other animations.

```typescript theme={null}
import { Easing } from '@helios-project/core';
```

### Available easing functions

#### Basic

* `Easing.linear` - No easing, linear interpolation
* `Easing.step(steps)` - Step function with specified number of steps
* `Easing.bezier(x1, y1, x2, y2)` - Custom cubic bezier curve

#### Polynomial

All polynomial easings have `.in`, `.out`, and `.inOut` variants:

* `Easing.quad` - Quadratic (t²)
* `Easing.cubic` - Cubic (t³)
* `Easing.quart` - Quartic (t⁴)
* `Easing.quint` - Quintic (t⁵)

#### Transcendental

* `Easing.sine` - Sinusoidal easing
* `Easing.expo` - Exponential easing
* `Easing.circ` - Circular easing

#### Physical

* `Easing.back` - Overshoots then returns
* `Easing.elastic` - Elastic bounce effect
* `Easing.bounce` - Bouncing ball effect

### Examples

```typescript theme={null}
import { interpolate, Easing } from '@helios-project/core';

// Ease in (slow start)
const x1 = interpolate(frame, [0, 60], [0, 100], {
  easing: Easing.cubic.in
});

// Ease out (slow end)
const x2 = interpolate(frame, [0, 60], [0, 100], {
  easing: Easing.cubic.out
});

// Ease in-out (slow start and end)
const x3 = interpolate(frame, [0, 60], [0, 100], {
  easing: Easing.cubic.inOut
});

// Elastic bounce
const scale = interpolate(frame, [0, 60], [0, 1], {
  easing: Easing.elastic.out
});

// Custom bezier
const custom = interpolate(frame, [0, 60], [0, 1], {
  easing: Easing.bezier(0.68, -0.55, 0.265, 1.55)
});

// Step animation (5 steps)
const stepped = interpolate(frame, [0, 60], [0, 100], {
  easing: Easing.step(5)
});
```

## Common patterns

### Typewriter effect

```typescript theme={null}
import { interpolate } from '@helios-project/core';

function Typewriter({ text, frame, start, end }) {
  const visibleCount = Math.floor(
    interpolate(frame, [start, end], [0, text.length])
  );
  
  return <div>{text.slice(0, visibleCount)}</div>;
}
```

### Stagger animations

```typescript theme={null}
function StaggeredList({ items, frame }) {
  return items.map((item, i) => {
    const delay = i * 10; // 10 frames between each
    const opacity = interpolate(
      frame,
      [delay, delay + 20],
      [0, 1],
      { extrapolateRight: 'clamp' }
    );
    
    return (
      <div key={i} style={{ opacity }}>
        {item}
      </div>
    );
  });
}
```

### Combining helpers

```typescript theme={null}
function AnimatedElement({ frame }) {
  // Use interpolate for position
  const x = interpolate(frame, [0, 60], [0, 200]);
  
  // Use spring for scale
  const scale = spring({ frame, fps: 30, from: 0, to: 1 });
  
  // Use easing for rotation
  const rotation = interpolate(
    frame,
    [0, 120],
    [0, 360],
    { easing: Easing.cubic.inOut }
  );
  
  return (
    <div style={{
      transform: `translateX(${x}px) scale(${scale}) rotate(${rotation}deg)`
    }}>
      Content
    </div>
  );
}
```