Class KeyboardStepSource

Keyboard-based position source for stepping through a timeline.

Supports:

Left/Right arrows: step by stepSize (default 1s)
Shift+Left/Right: large step by largeStepSize (default 10s)
Home/End: jump to start/end
Up/Down: configurable (timeline switch, chapter navigation, or disabled)

Example

const source = new KeyboardStepSource({
  duration: 60,
  verticalMode: 'chapter-navigation',
  markers: [0, 10, 20, 30, 40, 50],
});

await source.init();

source.onPosition((position) => {
  console.log(`Position: ${position}s`);
});

source.onMarkerJump((index, position) => {
  console.log(`Jumped to marker ${index} at ${position}s`);
});

await source.activate();

Hierarchy (View Summary)

BasePositionSource
- KeyboardStepSource

Implements

ISeekable

Index

Constructors

constructor

new KeyboardStepSource(config: KeyboardStepSourceConfig): KeyboardStepSource
Create a new keyboard-based position source.
Parameters
- config: KeyboardStepSourceConfig
  Configuration options
Returns KeyboardStepSource
Overrides BasePositionSource.constructor
- Defined in timelineproviders/position-sources/keyboard-step-source.ts:148

Accessors

loop

get loop(): boolean
Whether to loop when reaching the end boundary.

When true, the source resets to position 0 and continues. When false, the source emits 'end' boundary and deactivates.

For sources where looping is not applicable (e.g., mouse position), this property has no effect.

Returns boolean
Inherited from BasePositionSource.loop
- Defined in timelineproviders/position-sources/base-position-source.ts:81
set loop(value: boolean): void
Whether to loop when reaching the end boundary.

When true, the source resets to position 0 and continues. When false, the source emits 'end' boundary and deactivates.

For sources where looping is not applicable (e.g., mouse position), this property has no effect.
Parameters
- value: boolean
Returns void
Inherited from BasePositionSource.loop
- Defined in timelineproviders/position-sources/base-position-source.ts:85

state

get state(): TSourceState
Current state of the position source

Returns TSourceState
Inherited from BasePositionSource.state
- Defined in timelineproviders/position-sources/base-position-source.ts:77

Methods

activate

activate(): Promise<void>
Activate the position source to begin emitting position updates.

Transitions state from inactive or suspended to active.

Returns Promise<void>
Throws
If activation fails (e.g., autoplay blocked, permission denied)
Inherited from BasePositionSource.activate
- Defined in timelineproviders/position-sources/base-position-source.ts:110

deactivate

deactivate(): void
Deactivate the position source and reset to initial state.

Transitions state to inactive. Position is reset (typically to 0).

Returns void
Inherited from BasePositionSource.deactivate
- Defined in timelineproviders/position-sources/base-position-source.ts:136

destroy

destroy(): void
Destroy the position source and release all resources.

After calling destroy, the source cannot be reused. Removes event listeners, closes connections, clears timers.

Returns void
Inherited from BasePositionSource.destroy
- Defined in timelineproviders/position-sources/base-position-source.ts:97

`Protected`doDestroy

doDestroy(): void
Perform source-specific cleanup.

Called by destroy(). Override to release resources, unbind listeners, etc.

Returns void
Overrides BasePositionSource.doDestroy
- Defined in timelineproviders/position-sources/keyboard-step-source.ts:180

`Protected`doInit

doInit(): Promise<void>
Perform source-specific initialization.

Called by init(). Override to load resources, bind listeners, etc.

Returns Promise<void>
Overrides BasePositionSource.doInit
- Defined in timelineproviders/position-sources/keyboard-step-source.ts:163

`Protected`emitBoundary

emitBoundary(boundary: TBoundary): void
Emit a boundary event to all registered callbacks.
Parameters
- boundary: TBoundary
  The boundary type ('start' or 'end')
Returns void
Inherited from BasePositionSource.emitBoundary
- Defined in timelineproviders/position-sources/base-position-source.ts:203

getDuration

getDuration(): number
Get the total duration.

Returns number
Duration in seconds (or source-specific units), or Infinity for unbounded sources
Inherited from BasePositionSource.getDuration
- Defined in timelineproviders/position-sources/base-position-source.ts:158

getPosition

getPosition(): number
Get the current position.

Returns number
Current position in seconds (or source-specific units)
Inherited from BasePositionSource.getPosition
- Defined in timelineproviders/position-sources/base-position-source.ts:154

init

init(): Promise<void>
Initialize the position source.

Performs any async setup required before the source can be activated. For example: loading media, binding event listeners, establishing connections.

Returns Promise<void>
Throws
If initialization fails (e.g., media load error, connection refused)
Inherited from BasePositionSource.init
- Defined in timelineproviders/position-sources/base-position-source.ts:93

onActivated

onActivated(callback: () => void): void
Register a callback for when the source becomes active.

Called once each time the source transitions to the active state. This is equivalent to "first frame" semantics - for RAF sources it's the first tick, for video sources it's when playback actually starts.
Parameters
- callback: () => void
  Function called when source becomes active
Returns void
Inherited from BasePositionSource.onActivated
- Defined in timelineproviders/position-sources/base-position-source.ts:174

onBoundaryReached

onBoundaryReached(callback: (boundary: TBoundary) => void): void
Register a callback for boundary events.

Called when position reaches a boundary (start or end). For looping sources, 'end' is emitted before reset.
Parameters
- callback: (boundary: TBoundary) => void
  Function receiving the boundary type
Returns void
Inherited from BasePositionSource.onBoundaryReached
- Defined in timelineproviders/position-sources/base-position-source.ts:170

onMarkerJump

onMarkerJump(callback: (markerIndex: number, position: number) => void): void
Register callback for marker jumps (chapter-navigation mode).
Parameters
- callback: (markerIndex: number, position: number) => void
  Called with marker index and position when jumping
Returns void
- Defined in timelineproviders/position-sources/keyboard-step-source.ts:230

onPosition

onPosition(callback: (position: number) => void): void
Register a callback for position updates.

Called whenever the position changes while the source is active. Frequency depends on the source type (e.g., RAF tick, video timeupdate).
Parameters
- callback: (position: number) => void
  Function receiving the current position
Returns void
Inherited from BasePositionSource.onPosition
- Defined in timelineproviders/position-sources/base-position-source.ts:166

onTimelineChangeRequest

onTimelineChangeRequest(callback: (direction: "prev" | "next") => void): void
Register callback for timeline change requests (timeline-switch mode).
Parameters
- callback: (direction: "prev" | "next") => void
  Called with 'prev' or 'next' when Up/Down is pressed
Returns void
- Defined in timelineproviders/position-sources/keyboard-step-source.ts:219

seek

seek(position: number): Promise<number>
Seek to a specific position.

Position is clamped to the valid range [0, duration].
Parameters
- position: number
  Target position in seconds
Returns Promise<number>
Actual position after seek (may be clamped)
Implementation of ISeekable.seek
- Defined in timelineproviders/position-sources/keyboard-step-source.ts:204

`Protected`setPosition

setPosition(position: number): void
Set the current position and emit to callbacks.

Only emits if the source is active.
Parameters
- position: number
  New position value
Returns void
Inherited from BasePositionSource.setPosition
- Defined in timelineproviders/position-sources/base-position-source.ts:189

`Protected`startTicking

startTicking(): void
Start emitting position updates.

Called when transitioning to active state. Override to start timers, begin listening to events, etc.

Returns void
Overrides BasePositionSource.startTicking
- Defined in timelineproviders/position-sources/keyboard-step-source.ts:184

`Protected`stopTicking

stopTicking(): void
Stop emitting position updates.

Called when transitioning from active to suspended or inactive. Override to stop timers, pause listening, etc.

Returns void
Overrides BasePositionSource.stopTicking
- Defined in timelineproviders/position-sources/keyboard-step-source.ts:188

suspend

suspend(): void
Suspend the position source, preserving current position.

Transitions state from active to suspended. Position updates stop but position is preserved for later resumption.

Returns void
Inherited from BasePositionSource.suspend
- Defined in timelineproviders/position-sources/base-position-source.ts:125

Class KeyboardStepSource

Example

Hierarchy (View Summary)

Implements

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns KeyboardStepSource

Accessors

loop

Returns boolean

Parameters

Returns void

state

Returns TSourceState

Methods

activate

Returns Promise<void>

Throws

deactivate

Returns void

destroy

Returns void

ProtecteddoDestroy

Returns void

ProtecteddoInit

Returns Promise<void>

ProtectedemitBoundary

Parameters

Returns void

getDuration

Returns number

getPosition

Returns number

init

Returns Promise<void>

Throws

onActivated

Parameters

Returns void

onBoundaryReached

Parameters

Returns void

onMarkerJump

Parameters

Returns void

onPosition

Parameters

Returns void

onTimelineChangeRequest

Parameters

Returns void

seek

Parameters

Returns Promise<number>

ProtectedsetPosition

Parameters

Returns void

ProtectedstartTicking

Returns void

ProtectedstopTicking

Returns void

suspend

Returns void

Settings

On This Page

`Protected`doDestroy

`Protected`doInit

`Protected`emitBoundary

`Protected`setPosition

`Protected`startTicking

`Protected`stopTicking