Dictee Display Live

A lightweight TypeScript/React library for rendering live, word-by-word dictation animations (inspired by TikTok-style lyric reveals). It ships both an imperative API (displayLive) and a React wrapper (<DisplayLive />) so you can embed the animation in any DOM node or React tree.

Features

• Text playback controller with play/pause/stop/rewind controls
• Style presets (highlight, gradient, typewriter, etc.) plus custom colors
• React hook + component wrapper for idiomatic integration
• Rolldown build that outputs ESM/CJS/IIFE bundles and bundled types
• Storybook playground (Vite-powered) showcasing responsive layouts and styles

Getting Started

# install dependencies (bun, npm, or pnpm)
bun install

# build the library bundles (dist/index.*)
bun run build:lib

# run storybook on http://localhost:6006
bun run storybook

Storybook Playground

The legacy index.html harness has been retired in favor of the Display/DisplayLive/InteractivePlayground story. Fire up Storybook to explore the full-featured demo (style selector, solo toggle, card theme switcher, speed controls, and progress HUD) without leaving the docs environment.

React Usage

import 'animated-text-presentation/word-style.css';
import { DisplayLive } from 'animated-text-presentation';
import type { TextData, StyleConfig } from 'animated-text-presentation';

const data: TextData = /* your sentence + timings */;
const styleConfig: StyleConfig = {
    type: 'highlight',
    solo: false,
    colors: ['#f97316', '#fde047']
};

export function Example() {
    return (
        <DisplayLive
            textData={data}
            styleConfig={styleConfig}
            style={{ width: '400px', minHeight: '120px' }}
        />
    );
}

Next.js tip: if you're using the App Router, import animated-text-presentation/word-style.css in app/layout.tsx (or _app.tsx for the pages router) so the animation classes are available globally.

Imperative Usage

import 'animated-text-presentation/word-style.css';
import { displayLive } from 'animated-text-presentation';

const controller = displayLive(textData, 'destination-element-id', styleConfig);
controller.play();

Customizing Text Size & Typography

All presets now read their font-family, font-size, and font-weight from styleConfig.style. Each type ships with sensible defaults, but you can override any of them on a per-instance basis:

const styleConfig: StyleConfig = {
    type: 'tiktok-gradient',
    solo: false,
    colors: ['#7928ca', '#ff0080', '#ffdd00'],
    style: {
        fontFamily: "'Space Grotesk', sans-serif",
        fontSize: 'clamp(36px, 5vw, 64px)',
        fontWeight: '600'
    }
};

Providing only one property (e.g., fontSize) leaves the other defaults intact, so you can tweak text sizing without restyling the rest of the preset.

Scripts

• bun run build – builds the distributable bundles plus shared CSS.
• bun run build:bundle – Rolldown build (ESM/CJS/IIFE + types).
• bun run storybook / bun run build-storybook – develop or build docs.

Development Notes

• Source lives under src/. React helpers are in src/react/.
• Rolldown entry point is src/index.ts.
• Storybook stories live in src/stories/; config is under .storybook/.

License

MIT © 2025