Performance

Start with a bounded amount of work, then increase detail on the devices you support. Playback FPS, character density, and cursor responsiveness are separate controls; a 60 fps setting cannot add motion frames to a 24 fps source.

A starting point for video

import { asciifyVideo } from 'asciify-engine';

const stop = await asciifyVideo('/hero.mp4', canvas, {
  fitTo: hero, objectFit: 'cover',
  fontSize: 7, fps: 24, maxRenderDimension: 720,
  options: {
    colorMode: 'fullcolor', normalize: false,
    animationStyle: 'none', hoverStrength: 0,
  },
});
// Call stop() when the view unmounts.

Tune the expensive work

Option	Type	Default	Description
`Processing size`	maxRenderDimension	720–960	Lower this before sacrificing the source playback cadence. Stay within the source dimensions.
`Character density`	fontSize	7–8	Smaller characters increase cell count. Compare actual legibility at desktop and mobile sizes.
`Frame rate`	fps	24–30	Match the source and check sustained rendering, not only the first frame.
`Color`	colorMode	Choose for the media	Use fullcolor when color matters. Grayscale and accent are also available.
`Added effects`	hover / motion / dither	One deliberate treatment	Keep npm hover and animation off when the optional studio surface provides them.

Media delivery

Use an optimized MP4 or WebM and a small poster. Remove unused audio. For MP4, put metadata at the start of the file (fast-start). Use content-hashed filenames before enabling long-term immutable caching. A small source video usually supplies enough detail for ASCII; a 4K download rarely improves a coarse character grid.

Motion and cleanup

Avoid resizing or remounting on every pointer event. Pause media when hidden or offscreen, offer a real Play/Pause control, and render a still for reduced motion. The complete hero example includes those behaviors; the framework helper handles source changes and late cleanup.

If the artwork looks like an outline

Check the source lighting before increasing density. Thin highlights around a dark subject produce an outline in ASCII. Use footage with broad midtones and visible surfaces. Full color preserves existing colors; it cannot recover detail from black pixels. Compare normalization carefully because it can change the contrast between video frames.

Measure the result

Check a complete loop, rapid cursor changes, mobile sizing, and navigation cleanup. Profile main-thread work and memory on the target device. Report device, viewport, source resolution, settings, and sustained FPS when making a performance claim.