TWIPLA Recordings Player

React library that allows playing TWIPLA recordings.

Installation

npm install @twipla/recordings-player

Usage

TwiplaPlayer supports two data modes, chosen by which props you pass — the rest of the API (customization, injection, theming, the imperative ref) is identical in both.

Self-fetching mode

The lightest integration: the player fetches recordings/events itself using the TWIPLA API. Required props:

• websiteId - the id of the website where the recordings were created
• sessionId - the id of the session for which the recording events need to be played
• token - bearer token used for interacting with the TWIPLA API (note: pass only the token, without Bearer)
• apiDomain (optional) - overrides the default TWIPLA API gateway

import { TwiplaPlayer } from '@twipla/recordings-player';
import '@twipla/recordings-player/dist/esm/index.css';

const ReactComponent = () => {
  return <TwiplaPlayer
    websiteId={WEBSITE_ID}
    sessionId={SESSION_ID}
    token={AUTHENTICATION_TOKEN}
  />
};

Controlled mode

For consumers that already fetch/own the recordings and events (e.g. because they merge in proprietary data, apply their own privacy filtering, or share the parsed events with sibling components), pass recordings and events directly — the player skips fetching entirely:

<TwiplaPlayer
  recordings={recordings}       // Array<Recording>
  events={events}               // Record<string, Array<ParsedRecordingEvent>>
/>

recordings/events and sessionId/websiteId/token/apiDomain are mutually exclusive — TypeScript enforces one mode or the other via a discriminated union.

Customization

• loaderNode - displayed while the API calls are in progress (self-fetching mode only)
• errorNode - (args: { message, status? }) => ReactElement, displayed on a fetch error or when there are too few events to play
• playButton, skipInactiveSwitch, toggleFullScreenButton, speedItem - replace the default button/switch renderers with your own components
• speedValues - the list of selectable playback speeds (default [1, 2, 4, 8])
• controls - fully replace the default controls bar with a custom one; see CustomControls's prop shape (isPlaying, isFinished, togglePlay, currentTime, totalTime, setSpeed, toggleSkipInactive, toggleFullScreen, ...)
• renderSegmentTooltip - (ctx: SegmentTooltipRenderContext) => ReactNode, replaces the default progress-bar hover tooltip content (segment time or event details)

<TwiplaPlayer
      loaderNode={<Loader />}
      errorNode={({ message, status }) => <ErrorNode message={message} status={status} />}
      playButton={({ isPlaying }) => <div>{isPlaying ? 'Playing' : 'Paused'}</div>}
      skipInactiveSwitch={({ isSkipping }) => <div>{isSkipping ? 'Skipping' : 'Not skipping'}</div>}
      toggleFullScreenButton={({ isFullscreen }) => <div>{isFullscreen ? 'Minimize' : 'Maximize'}</div>}
/>

Behavior props

• autoPlay (default true), autoPlayStart - start playback automatically, optionally seeked to a given delay
• allowReplay - show a replay affordance instead of looping/resetting when playback finishes
• skipInactive, onToggleSkipInactive - control/observe the "skip inactive periods" toggle
• onFullScreen - override the built-in fullscreen behavior
• onCurrentEventChange - called with the index of the most recently played progress-bar event
• onEventsParsed - called with the fully processed ProgressBarEventType[] once the timeline is built

Event pipeline injection

The library owns the generic timeline/event-processing algorithms; taxonomy and presentation that are specific to a consumer (e.g. a proprietary alarming-event/e-commerce taxonomy) are injected:

• computeCustomEventDetails - recognizes EventType.Custom events the library doesn't know about; return undefined for events you don't own so the library falls back to its generic handling
• compactionConfig - range-based rules for hiding events while a custom start/end range is active (e.g. hide individual clicks during a "rage click" range)
• mergeConfig - rules for collapsing consecutive similar events (e.g. merge rapid scroll events)
• classifyMetaEvents (default true) - classify navigation events into entry-page/refresh/navigate
• hideEventInProgressBar - predicate to drop specific events from the progress bar (they still play)
• getEventText, getEventTooltip - localize/format an event's label and tooltip text
• getEventIcon - (args: { eventDetails, color? }) => { icon, backgroundColor? }, used by the progress-bar tooltip

Imperative API

TwiplaPlayer forwards a ref exposing { playFromEvent, playFromTimeOffset }, useful for seeking from an external UI (e.g. an events list rendered outside the player):

const playerRef = useRef<TwiplaPlayerHandle>(null);
<TwiplaPlayer ref={playerRef} ... />
// later:
playerRef.current?.playFromEvent(event);
playerRef.current?.playFromTimeOffset(12_000);

Theming

The controls bar and progress-bar fill/playhead colors are CSS custom properties, overridable on the player element or any ancestor:

• --ssr-color-primary (default #4A90E2) - progress-bar fill and playhead knob color
• --ssr-controls-bg (default rgba(0, 0, 0, 1)) - controls/timeline bar background

.my-player-wrapper {
  --ssr-color-primary: var(--brand-color);
  --ssr-controls-bg: rgba(0, 0, 0, 0.5);
}

Exported types & helpers

Besides TwiplaPlayer, the package exports:

• Types: TwiplaPlayerProps, TwiplaPlayerHandle, Recording, ParsedRecordingEvent, ProgressBarEventType, EventDetail, ComputeCustomEventDetails, CompactionRule, MergeCondition, MergeConditionsMap, GetEventIcon, RenderSegmentTooltip, SegmentTooltipRenderContext, EventPipelineProps, PlayerBehaviorProps, CustomizationProps
• EventTypeEnum - the library's own progress-bar event-name enum (meta/click/scroll/ABE names, ...)
• EventType, IncrementalSource, MouseInteractions - self-contained copies of the rrweb event-taxonomy enums (mirroring @visa/rrweb's values), so consumers building computeCustomEventDetails don't need the private @visa/rrweb package installed
• Reusable pipeline algorithms: compactRecordingEvents, mergeEvents, processMetaEvents, mapEventForProgressBar, computeEventDetails, computeStandardEventDetails, isEventNeeded

© TWIPLA, 2026