Keyboard shortcuts hooks provide a flexible system for mapping keyboard input to playlist actions. Use useKeyboardShortcuts for custom shortcuts and usePlaybackShortcuts for common playback controls.
useKeyboardShortcuts
Generic keyboard shortcut system with modifier key support.
Import
import { useKeyboardShortcuts, getShortcutLabel } from '@waveform-playlist/browser';
import type { KeyboardShortcut } from '@waveform-playlist/browser';
Basic Usage
import { useKeyboardShortcuts } from '@waveform-playlist/browser';
import { useClipSplitting } from '@waveform-playlist/browser';
function MyPlaylist() {
const { splitClipAtPlayhead } = useClipSplitting({ /* ... */ });
useKeyboardShortcuts({
shortcuts: [
{
key: 's',
action: splitClipAtPlayhead,
description: 'Split clip at playhead',
preventDefault: true,
},
{
key: 'S',
shiftKey: true,
action: () => console.log('Split at selection'),
description: 'Split at selection boundaries',
},
],
});
return <div>Press 's' to split clip</div>;
}
Modifier Keys
useKeyboardShortcuts({
shortcuts: [
{
key: 'z',
ctrlKey: true, // Ctrl+Z (Windows/Linux)
metaKey: true, // Cmd+Z (Mac)
action: undo,
description: 'Undo',
},
{
key: 'z',
ctrlKey: true,
shiftKey: true,
action: redo,
description: 'Redo',
},
{
key: 'Delete',
action: deleteSelected,
description: 'Delete selected',
},
],
});
Conditional Shortcuts
const [enabled, setEnabled] = useState(true);
useKeyboardShortcuts({
shortcuts: [...],
enabled, // Disable shortcuts when enabled=false
});
Get Shortcut Labels
import { getShortcutLabel } from '@waveform-playlist/browser';
const shortcut = { key: 's', shiftKey: true };
const label = getShortcutLabel(shortcut); // "Shift+S"
const macShortcut = { key: 'z', metaKey: true };
const macLabel = getShortcutLabel(macShortcut); // "Cmd+Z" on Mac, "Ctrl+Z" on Windows
Parameters
options
UseKeyboardShortcutsOptions
required
Shortcut configuration.
UseKeyboardShortcutsOptions
shortcuts
KeyboardShortcut[]
required
Array of keyboard shortcut definitions.
Whether shortcuts are currently enabled. Set to false to temporarily disable.
KeyboardShortcut
The key to listen for. Can be a letter ('s'), special key ('Space', 'Escape', 'Delete'), or number ('0').See MDN KeyboardEvent.key for all values. Whether Ctrl key must be pressed. Use with metaKey for cross-platform support.
Whether Shift key must be pressed.
Whether Meta/Cmd key must be pressed (Mac Command key).
Whether Alt/Option key must be pressed.
Function to call when shortcut is triggered.
Human-readable description of the shortcut’s action.
Whether to call event.preventDefault(). Set to false to allow default browser behavior.
// Shortcuts DON'T trigger when typing in these elements:
// - <input>
// - <textarea>
// - contentEditable elements
usePlaybackShortcuts
Pre-configured playback shortcuts with customization support.
Import
import { usePlaybackShortcuts } from '@waveform-playlist/browser';
import type { UsePlaybackShortcutsOptions } from '@waveform-playlist/browser';
Basic Usage
import { usePlaybackShortcuts } from '@waveform-playlist/browser';
function MyPlaylist() {
// Enable default playback shortcuts
usePlaybackShortcuts();
return <WaveformPlaylistProvider>...</WaveformPlaylistProvider>;
}
Default Shortcuts
The hook provides these shortcuts by default:
- Space - Toggle play/pause
- Escape - Stop playback
- 0 - Rewind to start (seek to time 0)
Add Custom Shortcuts
const { splitClipAtPlayhead } = useClipSplitting({ /* ... */ });
usePlaybackShortcuts({
additionalShortcuts: [
{
key: 's',
action: splitClipAtPlayhead,
description: 'Split clip',
preventDefault: true,
},
{
key: 'i',
action: () => setSelectionStart(currentTime),
description: 'Set in point',
},
{
key: 'o',
action: () => setSelectionEnd(currentTime),
description: 'Set out point',
},
],
});
Override All Shortcuts
usePlaybackShortcuts({
shortcuts: [
{ key: 'p', action: play, description: 'Play' },
{ key: 'Home', action: rewindToStart, description: 'Go to start' },
// Only these shortcuts will be active
],
});
Disable Shortcuts
const [enabled, setEnabled] = useState(true);
usePlaybackShortcuts({ enabled });
Parameters
options
UsePlaybackShortcutsOptions
Playback shortcuts configuration.
UsePlaybackShortcutsOptions
Additional shortcuts to include alongside the default playback shortcuts.
Override default shortcuts. If provided, only these shortcuts will be used.
Return Value
Rewind to the beginning (time = 0). If playing, stops and restarts playback from the beginning.
Toggle between play and pause.
Stop playback and return to start position.
The list of active keyboard shortcuts (for displaying help UI).
Usage Patterns
function ShortcutHelp() {
const { shortcuts } = usePlaybackShortcuts({
additionalShortcuts: [
{ key: 's', action: split, description: 'Split clip' },
],
});
return (
<div>
<h2>Keyboard Shortcuts</h2>
<ul>
{shortcuts.map((shortcut, i) => (
<li key={i}>
<kbd>{getShortcutLabel(shortcut)}</kbd>
{shortcut.description && ` - ${shortcut.description}`}
</li>
))}
</ul>
</div>
);
}
// Works on both Mac and Windows
const isMac = navigator.platform.includes('Mac');
useKeyboardShortcuts({
shortcuts: [
{
key: 'z',
ctrlKey: !isMac, // Ctrl on Windows
metaKey: isMac, // Cmd on Mac
action: undo,
description: 'Undo',
},
],
});
Conditional Shortcuts Based on State
const { selectedTrackId } = usePlaylistState();
useKeyboardShortcuts({
shortcuts: [
{
key: 'Delete',
action: () => {
if (selectedTrackId) {
deleteTrack(selectedTrackId);
}
},
description: 'Delete selected track',
},
],
});
Event Handling
The hook listens for keydown events on window:
window.addEventListener('keydown', handleKeyDown);
- Key matches (
event.key === shortcut.key)
- All required modifiers match (Ctrl, Shift, Meta, Alt)
- Focus is NOT in an input field