{anyOverridden ? ( ) : null}

} > {narrow ? ( <> Undo Redo ) : null} Multi-select Automation Keyboard shortcuts

{SHORTCUTS.map((shortcut) => (

{shortcut.action} {shortcut.keys.map((key) => ( {key} ))}

))}

{zoomInBar ? null : ( <> Zoom

{ZOOM_PRESETS.map((ratio) => ( maxRatio} key={ratio} value={String(ratio)} > {ratio === 1 ? "Fit" : `${ratio * 100} %`} ))} )}

{/* As wide as the lanes, so the stuck headers stay put however far it scrolls. */}

{/* One sticky block, so what is stuck stays stacked whatever each row measures. */}

Loop } > } > {snap ? gridLabel(gridSeconds, tempo) : "Snap off"} } > {songBars .filter((item) => item.partial) .map((item) => (

))} {labels.map((item) => ( {item.number} ))} Markers } > {locators.map((locator) => ( ))} Signature

} > {signatures.map((change) => ( ))}

{tracks.map((track) => (

} mix={mixOf(track)} name={track.name} onDuplicate={duplicateTrack} onInsert={addTrack} onMix={changeTrackMix} onMixCommit={settleClipEdit} onRemove={removeTrack} onRename={renameTrack} onSelect={pickTrack} onToggleFold={toggleFold} selected={selectedTracks.includes(track.id)} trackId={track.id} > {automationOf(track).chooser}

} onResize={resizeTrack} selected={selectedTracks.includes(track.id)} trackId={track.id} > }> {copying .filter((original) => original.track === track.id) .map((original) => ( ))} {clips .filter((clip) => clip.track === track.id) .map((clip) => ( original.id === clip.id )} describe={describe} key={clip.id} lift={ lifting && lifting.id !== clip.id && selectedIds.includes(clip.id) && selectedIds.includes(lifting.id) ? lifting.offset : 0 } multi={multi} onAction={handleClipAction} onChange={changeClip} onCommit={commitClip} onFadeShape={setFadeShape} onLift={lift} onRemove={removeClip} onRename={renameClip} onSelect={pickClip} selected={selectedIds.includes(clip.id)} swatch={mixOf(track).color} trackName={track.name} /> ))} {timeSelection?.tracks.includes(track.id) ? ( ))}

} > {/* The surface carries on to the bottom of the view, so the arrangement does not stop at the last track. */} }>

{marquee.rect ? // In the page's body: a dialog is transformed, which would make a fixed rectangle its own. createPortal( ); } ``` The base for an arrangement view, a clip editor or a piano roll. The registry component wraps the `Timeline` primitive from `@audio-ui/react`. The timeline has no notion of tempo: its units are whatever you count in (seconds, beats, pulses or steps). Musical time comes from the `musical-time` lib. ## Overview - **Units and zoom:** `duration` is the length in your units, and `zoom` is the number of pixels per unit. Without `zoom`, the timeline fits its width. With it, every lane is as long as the timeline and the viewport scrolls. - **Zooming:** Cmd/Ctrl + scroll, or a trackpad pinch, zooms around the pointer. Every zoom change keeps its anchor point in place, or the middle of the view when there is none. - **Grid:** with a `snapStep`, the ruler snaps to the grid. Hold Cmd/Ctrl to place the playhead off the grid, and Shift to scrub four times finer. - **Playback:** pass a live `source` and every playhead follows it in the DOM, without a React render per frame. - **Ranges:** a `TimelineRange` is a stretch of the timeline, such as a loop, a selection or a clip. Drag it to move it, drag a handle to resize it, or, with `drawable`, drag across an empty lane to draw a new one. Ranges snap to the grid. - **Navigator:** `TimelineNavigator` shows the whole timeline as one bar, with the visible part inside it. Drag the window to scroll, drag an edge to zoom, and double-click to show everything. With `scrollbar="hidden"` on the viewport, it replaces the scrollbar. - **Accessibility:** the ruler, each range and range handle, and the navigator's window and edges hold a native ``, so every pointer action has a keyboard equivalent. The ruler's input spans the timeline: it takes focus, carries `aria-label` and announces the position (or the text from `getAriaValueText`, such as "Bar 3, beat 2"). The arrow keys move by `step`, Page Up / Page Down and Shift by `largeStep`, and Home / End go to the ends. ## Installation **CLI** ```bash npx shadcn@latest add @audio-ui/timeline npm install @audio-ui/core ``` **Manual** **1. Install the following dependencies:** ```bash npm install @audio-ui/react ``` **2. Copy and paste the following code into your project.** ```tsx title="components/audio-ui/timeline.tsx" "use client"; import { FADE_SHAPES, type FadeShape, fadeGain, Timeline as TimelinePrimitive, } from "@audio-ui/react"; import { type CSSProperties, type FocusEvent, type KeyboardEvent, type MouseEvent, type ReactNode, useCallback, useRef, useState, } from "react"; import { IconPlaceholder } from "@/components/icon-placeholder"; import { cn } from "@/lib/utils"; import { Button } from "@/components/ui/button"; import { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuItem, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuTrigger, } from "@/components/ui/context-menu"; import { DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, } from "@/components/ui/dropdown-menu"; import { Fader } from "@/components/audio-ui/fader"; import { Knob } from "@/components/audio-ui/knob"; import type { Mix } from "@/lib/arrangement"; function Timeline({ className, ...props }: TimelinePrimitive.Root.Props) { return ( ); } type TimelineViewportProps = TimelinePrimitive.Viewport.Props & { /** `hidden` drops the native scrollbar, for a `TimelineNavigator` to scroll with instead. */ scrollbar?: "hidden" | "native"; }; function TimelineViewport({ className, scrollbar = "native", ...props }: TimelineViewportProps) { return ( ); } function TimelineRuler({ className, ...props }: TimelinePrimitive.Ruler.Props) { return ( ); } type TimelineLaneProps = Omit & { /** Distance between grid lines, in the timeline's units. Leave it out for no lines. */ gridStep?: number; style?: CSSProperties; }; /** A line every `gridStep` units, sized from the lane's own unit so it follows the zoom. */ function gridLines(gridStep: number | undefined): CSSProperties | undefined { if (!(gridStep && gridStep > 0)) { return; } return { backgroundImage: "repeating-linear-gradient(to right, var(--timeline-grid-color) 0 1px, transparent 1px 100%)", backgroundSize: `calc(var(--timeline-unit) * ${gridStep}) 100%`, }; } function TimelineLane({ className, gridStep, style, ...props }: TimelineLaneProps) { return ( ); } function TimelineTrack({ className, ...props }: TimelinePrimitive.Track.Props) { return ( ); } function TimelineTrackHeader({ className, ...props }: TimelinePrimitive.TrackHeader.Props) { return ( ); } function TimelineTrackResizeHandle({ className, ...props }: TimelinePrimitive.TrackResizeHandle.Props) { return ( ); } function TimelineMark({ className, ...props }: TimelinePrimitive.Mark.Props) { return ( ); } function TimelinePlayhead({ className, ...props }: TimelinePrimitive.Playhead.Props) { return ( ); } function TimelineRange({ className, ...props }: TimelinePrimitive.Range.Props) { return ( ); } function TimelineRangeHandle({ className, ...props }: TimelinePrimitive.RangeHandle.Props) { return ( ); } /** Where a fade being dragged stops: the other fade's start, as a dashed line. */ const FADE_LIMIT = "pointer-events-none absolute inset-y-0 z-30 hidden border-foreground/60 border-l border-dashed"; function TimelineClip({ children, className, ...props }: TimelinePrimitive.Clip.Props) { return ( {children} ); } /** The clip's title bar: drag it to move the clip. Put the clip's name in it. */ function TimelineClipHeader({ className, ...props }: TimelinePrimitive.ClipHeader.Props) { return ( ); } function TimelineClipHandle({ className, ...props }: TimelinePrimitive.ClipHandle.Props) { return ( ); } /** Shades what a fade attenuates, over the clip's content. */ function TimelineClipFade({ className, ...props }: TimelinePrimitive.ClipFade.Props) { return ( ); } const FADE_SHAPE_LABELS: Record = { fast: "Fast", linear: "Linear", slow: "Slow", smooth: "Smooth", }; const CURVE_STEPS = 12; /** A fade-in's curve as an SVG path, silent at the bottom left to full at the top right. */ function curvePath(shape: FadeShape): string { return Array.from({ length: CURVE_STEPS + 1 }, (_, step) => { const progress = step / CURVE_STEPS; const x = 2 + progress * 20; const y = 14 - fadeGain(shape, progress) * 12; return `${step === 0 ? "M" : "L"}${x.toFixed(1)} ${y.toFixed(1)}`; }).join(" "); } type TimelineClipFadeHandleProps = TimelinePrimitive.ClipFadeHandle.Props & { /** The fade's curve. With `onShapeChange`, a right-click on the handle lists the curves. */ shape?: FadeShape; onShapeChange?: (shape: FadeShape) => void; }; function TimelineClipFadeHandle({ className, onShapeChange, shape = "linear", ...props }: TimelineClipFadeHandleProps) { const handleShape = useCallback( (value: string) => onShapeChange?.(value as FadeShape), [onShapeChange] ); const handle = ( ); if (!onShapeChange) { return handle; } return ( {FADE_SHAPES.map((item) => ( {FADE_SHAPE_LABELS[item]} ))} ); } /** The whole timeline as one bar: drag the window to scroll, an edge to zoom, double-click to show everything. */ function TimelineNavigator({ className, ...props }: TimelinePrimitive.Navigator.Props) { return ( ); } const selectText = (element: HTMLInputElement | null) => element?.select(); /** A track is never shorter than its full header needs: to go smaller, fold it. */ export const MIN_TRACK_HEIGHT = 79; /** Below this a track is a strip: the full header (name, solo, mute, gain, pan) needs this much room, so a shorter track keeps the name, solo and mute and drops the rest. */ export const COMPACT_TRACK_HEIGHT = 79; export const MAX_TRACK_HEIGHT = 320; export const TRACK_HEIGHT_STEP = 8; /** The colors a track can take: the theme's chart tokens, written out for the stylesheet to find. */ export const TRACK_COLORS = [ { dot: "bg-chart-1", clip: "[--primary:var(--chart-1)]", edge: "border-s-chart-1", name: "Color 1", }, { dot: "bg-chart-2", clip: "[--primary:var(--chart-2)]", edge: "border-s-chart-2", name: "Color 2", }, { dot: "bg-chart-3", clip: "[--primary:var(--chart-3)]", edge: "border-s-chart-3", name: "Color 3", }, { dot: "bg-chart-4", clip: "[--primary:var(--chart-4)]", edge: "border-s-chart-4", name: "Color 4", }, { dot: "bg-chart-5", clip: "[--primary:var(--chart-5)]", edge: "border-s-chart-5", name: "Color 5", }, ] as const; const formatPan = (pan: number) => { const amount = Math.round(Math.abs(pan) * 100); if (amount === 0) { return "C"; } return `${pan < 0 ? "L" : "R"}${amount}`; }; /** A track's context menu: an entry for each action it is given, then the colors. */ function TimelineTrackMenu({ folded, onColor, onDuplicate, onFold, onInsert, onRemove, onRename, }: { folded?: boolean; onColor: (event: MouseEvent) => void; onDuplicate?: () => void; onFold?: () => void; onInsert?: () => void; onRemove?: () => void; onRename?: () => void; }) { return ( {onRename ? ( Rename ) : null} {onDuplicate ? ( Duplicate ) : null} {onFold ? ( {folded ? "Unfold" : "Fold"} ) : null} {onRemove ? ( <> Delete ) : null} {onInsert ? ( <> Insert track ) : null} {TRACK_COLORS.map((swatch, index) => ( ))} ); } /** * What a track's header holds: its name, which selects the track (its content * is where the cursor goes), solo, mute and gain. The lower edge resizes it. */ function TimelineTrackControls({ children, compact, folded, mix, name, onMix, onMixCommit, onDuplicate, onInsert, onRemove, onRename, onSelect, onToggleFold, meter, selected, trackId, }: { /** More rows under the mix, such as the automation's parameter chooser. A short track leaves them out. */ children?: ReactNode; /** A level meter drawn down the header's right edge, such as a vertical `Meter` sized to fill it. */ meter?: ReactNode; /** Whether the track is short: one row, with no gain. */ compact: boolean; /** Whether the track is folded to a strip: the caret opens it. */ folded?: boolean; /** Gives the header a caret that folds the track. */ onToggleFold?: (trackId: string) => void; mix: Mix; name: string; onMix: (trackId: string, patch: Partial) => void; /** Called when a drag of the gain or the pan ends, to close it as one undo step. */ onMixCommit?: (trackId: string) => void; /** Gives the menu a "Duplicate" entry. */ onDuplicate?: (trackId: string) => void; /** Gives the menu an "Insert track" entry: a new track after this one. */ onInsert?: (trackId: string) => void; /** Lets the name be edited in place: a double-click, or "Rename" in the menu. */ onRename?: (trackId: string, name: string) => void; /** Gives the menu a "Delete track" entry. Leave it out for tracks that cannot be removed. */ onRemove?: (trackId: string) => void; /** `additive` when Shift, Cmd or Ctrl is held: add the track to the tracks picked. */ onSelect: (trackId: string, additive: boolean) => void; selected: boolean; trackId: string; }) { const handleMute = useCallback( () => onMix(trackId, { muted: !mix.muted }), [mix.muted, onMix, trackId] ); const handleSolo = useCallback( () => onMix(trackId, { soloed: !mix.soloed }), [mix.soloed, onMix, trackId] ); const handleGain = useCallback( (value: number | readonly number[]) => onMix(trackId, { gain: Array.isArray(value) ? value[0] : Number(value) }), [onMix, trackId] ); const handlePan = useCallback( (value: number | readonly number[]) => onMix(trackId, { pan: Array.isArray(value) ? value[0] : Number(value) }), [onMix, trackId] ); const handleMixCommit = useCallback( () => onMixCommit?.(trackId), [onMixCommit, trackId] ); const handleColor = useCallback( (event: MouseEvent) => onMix(trackId, { color: Number(event.currentTarget.dataset.color) }), [onMix, trackId] ); const handleRemove = useCallback( () => onRemove?.(trackId), [onRemove, trackId] ); const [renaming, setRenaming] = useState(false); const startRenaming = useCallback(() => setRenaming(true), []); // The menu hands focus back as it closes, which would end the edit: open the field after it. const renameWhenClosed = useRef(false); const handleMenuClosed = useCallback((open: boolean) => { if (!open && renameWhenClosed.current) { renameWhenClosed.current = false; setRenaming(true); } }, []); const handleRenameItem = useCallback(() => { renameWhenClosed.current = true; }, []); const handleNameKeyDown = useCallback( (event: KeyboardEvent) => { event.stopPropagation(); if (event.key === "Enter") { onRename?.(trackId, event.currentTarget.value); setRenaming(false); } else if (event.key === "Escape") { setRenaming(false); } }, [onRename, trackId] ); const handleNameBlur = useCallback( (event: FocusEvent) => { onRename?.(trackId, event.currentTarget.value); setRenaming(false); }, [onRename, trackId] ); const handleDuplicate = useCallback( () => onDuplicate?.(trackId), [onDuplicate, trackId] ); const handleInsert = useCallback( () => onInsert?.(trackId), [onInsert, trackId] ); const handleFold = useCallback( () => onToggleFold?.(trackId), [onToggleFold, trackId] ); const handleClick = useCallback( (event: MouseEvent) => onSelect(trackId, event.shiftKey || event.metaKey || event.ctrlKey), [onSelect, trackId] ); // The whole header picks the track, but not through a control that has its own job. const handleHeaderClick = useCallback( (event: MouseEvent) => { const target = event.target as Element; if ( !target.closest( "button, input, [data-slot^=fader], [data-slot=knob], [data-slot=timeline-track-resize-handle]" ) ) { handleClick(event); } }, [handleClick] ); return ( } >

{onToggleFold ? ( ) : null} {renaming ? ( ) : ( )}

{compact ? null : (

)} {compact ? null :

{children}

} {meter ? (

{meter}

) : null} ); } /** The menu items of the grid, for a context menu or a dropdown menu. */ type GridMenuKit = { RadioGroup: typeof ContextMenuRadioGroup; RadioItem: typeof ContextMenuRadioItem; CheckboxItem: typeof ContextMenuCheckboxItem; Separator: typeof ContextMenuSeparator; }; const CONTEXT_GRID_KIT: GridMenuKit = { RadioGroup: ContextMenuRadioGroup, RadioItem: ContextMenuRadioItem, CheckboxItem: ContextMenuCheckboxItem, Separator: ContextMenuSeparator, }; const DROPDOWN_GRID_KIT: GridMenuKit = { RadioGroup: DropdownMenuRadioGroup, RadioItem: DropdownMenuRadioItem, CheckboxItem: DropdownMenuCheckboxItem, Separator: DropdownMenuSeparator, }; /** The grid's divisions and its two flags, as the menu a right-click on a lane or a dropdown opens. */ function TimelineGridMenuItems({ division, divisions, onDivisionChange, onSnapChange, onTripletChange, snap, triplet, variant = "context", }: { division: string; divisions: { label: string; value: string }[]; onDivisionChange: (value: string) => void; onSnapChange: (checked: boolean) => void; onTripletChange: (checked: boolean) => void; snap: boolean; triplet: boolean; variant?: "context" | "dropdown"; }) { const { RadioGroup, RadioItem, CheckboxItem, Separator } = variant === "dropdown" ? DROPDOWN_GRID_KIT : CONTEXT_GRID_KIT; return ( <> {divisions.map((item) => ( {item.label.replace("Grid: ", "")} ))} Triplet grid Snap to grid ); } export { Timeline, TimelineClip, TimelineClipFade, TimelineClipFadeHandle, TimelineClipHandle, TimelineClipHeader, TimelineGridMenuItems, TimelineLane, TimelineMark, TimelineNavigator, TimelinePlayhead, TimelineRange, TimelineRangeHandle, TimelineRuler, TimelineTrack, TimelineTrackControls, TimelineTrackHeader, TimelineTrackResizeHandle, TimelineViewport, }; ``` **3. Update the import paths to match your project setup.** ## Anatomy Import the primitive and assemble its parts. ```tsx import { Timeline } from "@audio-ui/react"; ``` ## Usage ```tsx import { Timeline, TimelineLane, TimelineMark, TimelinePlayhead, TimelineRuler, TimelineViewport, } from "@/components/audio-ui/timeline"; import { DEFAULT_TEMPO, describeBarsBeats, gridInterval, } from "@audio-ui/core/time"; ``` ```tsx const snapStep = gridInterval("adaptive", zoom, DEFAULT_TEMPO); transport.seek(seconds)} onZoomChange={setZoom} snapStep={snapStep} source={transport.position} zoom={zoom} > describeBarsBeats(seconds, DEFAULT_TEMPO)} > 1 2 ``` ## Ranges ```tsx const [loop, setLoop] = useState([8, 16]); ``` The range's own input moves it with Left and Right, by the timeline's `step`, and with Up and Down by its own length; Cmd/Ctrl + Left and Right shorten or lengthen it by a step, Cmd/Ctrl + Up and Down double or halve it; each handle's input moves its edge, which stops `minLength` short of the other one (the grid step by default). `onValueChange` receives `[start, end]` and `eventDetails` with the `edge` that moved (`"start"`, `"end"` or `"both"`) and the `reason` (`"drag"`, `"draw"`, `"keyboard"` or `"input-change"`). Leave the handles out for a range that only moves, or pass `movable={false}` for one that only resizes. ## Tracks A track is a row: a header beside a lane. `Timeline.Track` holds the row, `Timeline.TrackHeader` is the strip that names it and stays at the left edge while the lane scrolls, and `Timeline.TrackResizeHandle` sets its height. You hold the height: leave it out and the row shares the room it is given; set it and the row keeps it. ```tsx const [height, setHeight] = useState(); setHeight(next)} selected={selected} > Drums {/* clips */} ; ``` You put the header's controls in it, such as solo, mute and gain. The track does not know about them. The block reorders tracks by their grip, the bar at the track's left edge: press it and drag. A copy of the track's header follows the pointer, the dragged track stays in place faded, and a line marks the place it would land in. Near the top or bottom of a view that scrolls, the view scrolls on its own while the track is held. The arrow keys move a focused grip one place up or down, and every move is one undo step with its clips. The move is `moveTrack(id, index)` in `useArrangement`; it uses a pointer drag rather than the browser's drag and drop, so it does not depend on how the browser handles a drag. ## Clips A clip is a stretch of a source (a recording, a pattern) laid on a track. It is a range that knows about its source: trimming its start moves where in the source it begins, so its content stays where it is, and it cannot show more than the source holds. ```tsx const [clip, setClip] = useState({ start: 8, // where it sits on the timeline length: 16, // how long it plays offset: 4, // where in the source it begins fadeIn: 0, fadeInShape: "linear", // or "fast", "slow", "smooth" fadeOut: 0, }); removeClip()} onValueChange={setClip} sourceLength={48} value={clip} > Groove ``` All of it is in the timeline's units, the source's too. Dragging the clip's header, its title bar, moves it on the grid, and over other lanes: `eventDetails.lane` is the `Timeline.Lane` under the pointer, so put your own attribute on each lane (`data-track` above) and read it in `onValueCommitted`, which also fires for a drop on another lane that left the position as it was. The clip follows the pointer vertically through `--clip-drag-y`. A press on the clip's body selects it and puts the cursor there, and a drag scrubs, so the body never moves the clip by accident. Its content is yours: it sets `--clip-offset` and `--clip-source-length` so a `Waveform` can show the stretch that is played. Holding Alt when a drag begins marks it as a copy (`eventDetails.copy`): the clip you were dragging is the copy, so leave the original where it was and add the dragged one. A fade's shape is stepped by double-clicking its handle, or Enter on its input (`reason` is `"double-click"` or `"keyboard"`), and `ClipFade` draws the real ramp. The registry's `TimelineClipFadeHandle` also takes `onShapeChange`: a right-click on the handle lists the four curves, each drawn, and the arrangement's `setFadeShape(id, edge, shape)` sets one as a single undo step. Laying a clip where others already are is `coverClips(clips, placed, { duration }, split)`: the clips under it are covered rather than stacked (removed, trimmed or cut in two around it), and `split` makes the second piece of a cut clip from the first, so what your app keeps about a clip travels with each piece. Covering only shortens a clip, so the timeline's `duration` is the one limit it reads: the length of a source, which limits how far one clip stretches, never applies to the clips under it. Cutting, copying and the like are plain functions on the clip, for the model behind your clips: `splitClip(clip, at)` returns the two pieces (or `null` when `at` leaves one too short), and `moveClip`, `trimClipStart`, `trimClipEnd`, `setClipFadeIn`, `setClipFadeOut`, `setClipFadeShape` and `duplicateClip` return the clip as it would end up, within the limits you give them. ### Many clips Dragging one clip among 1 000 takes about a millisecond of script, and the playhead moves outside React, so it costs no render. The real cost is rendering every clip again whenever one moves, which happens when the clip component is not memoized. Put one clip in a `React.memo` component with stable props (the clip's own `value`, callbacks that take its id), so React skips every clip a drag did not touch. ### Selecting several clips The primitive keeps no selection: `selected` and `onSelectedChange` are yours, so a selection is any set of ids you keep. `onSelectedChange` fires when a press selects a clip, and again on a press with Shift, Cmd or Ctrl held (read `eventDetails.event`), which is how you add to a selection or take from it. A touch screen has no modifier keys: give the clip `additive` (from a "select several" mode of your own) and every press is reported, so a press adds a clip to the selection or takes it from it. To move a group, read `eventDetails.delta` on a move, how far the dragged clip is from where the drag began, and move each other selected clip by the same amount from where it was when the drag began; `moveClip` keeps each on the timeline. For the group to follow the clip up and down too, `onDragOffsetChange` reports how far it is dragged vertically, in px, and 0 when the drag ends: shift the other selected clips by that much. A drop on another lane then moves each by as many lanes as the dragged one did. The registry's arrangement block does all of this, with Cmd/Ctrl + A to select every clip and Shift + drag across bare lane to select the clips a rectangle touches (it measures each clip's `getBoundingClientRect()`, so it needs nothing from the primitive). ### The cursor A `Timeline.Lane` with `seekable` puts the position where a press lands on its bare area, as the ruler does, and a drag scrubs it. Presses on the clips in it go to the clips. The cursor can then go anywhere along a track, and your track header selects the whole track. A split is then `splitClip(clip, position)` on the selected clip, or on each clip of the selected track that the cursor is over. ## Navigator ```tsx … ``` Place it anywhere inside the timeline, outside the viewport. Dragging an edge zooms while holding the other edge in place, through `onZoomChange` with `reason: "drag"`; a double-click fits the whole timeline with `reason: "double-click"`. ## Musical time `@audio-ui/core/time` turns a tempo into what a timeline needs, in seconds: - `gridInterval(division, zoom, tempo)` is the grid's step: a fixed division (`"1-bar"`, `"1/8"`, …), or `"adaptive"` for the finest division still 24px apart at this zoom. Pass `{ triplet: true }` for three in the space of two. Give the same number to `snapStep` and to the lanes' `gridStep`, so gestures land on the lines you see. - `barLabelInterval(zoom, tempo)` is how far apart the ruler's bar numbers go: whole bars, spread out until they no longer collide. - `barsBeatsAt(seconds, tempo)` and `describeBarsBeats` read a position as bars, beats and sixteenths. - `gridLabel(seconds, tempo)` names an interval the way a grid readout does (`"1 bar"`, `"1/16"`, `"1/8T"`), so the adaptive grid reads out the division it uses, and a menu and a readout always name a grid the same way. - `metronomeRhythmSeconds(rhythm, tempo)` is the interval of a click rhythm (`"1/8"`, `"1/8t"`, …), or `null` for `"auto"`, which follows the beat. ## An arrangement The arrangement block, the preview above, is a timeline with tracks of clips, locators, time signatures, automation and MIDI clips. Its parts, its state, its keys and its undo are on the [Arrangement editor](/docs/components/base/arrangement-editor) page. ## Placing your own parts Every lane sets a `--timeline-unit` CSS variable, the width of one unit. Parts are placed with it, so anything you draw follows the zoom the same way: ```tsx

``` ## API reference ### Root Groups the parts of a timeline and owns what they share: its length, its zoom, its grid and the playback position. Units are yours: seconds, beats, pulses or steps. `zoom` is how many px one unit takes; leave it unset and the timeline fits the width it is given. The position comes from `position`, or from a live `source` that the playhead follows straight in the DOM without re-rendering React. With a `snapStep`, every gesture lands on the grid unless Cmd/Ctrl is held, and `snapPoints` (the edges of other clips, the locators) pull a dragged clip or range onto them from a few px away. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `defaultPosition` | `number` | `0` | Uncontrolled starting position. | | `defaultZoom` | `number` | | Uncontrolled starting zoom, in px per unit. Unset, the timeline fits its width until zoomed. | | `disabled` | `boolean` | | | | `duration` | `number` | `1` | Length of the timeline, in your units. | | `largeStep` | `number` | | Step for Page Up/Page Down and Shift + arrow keys. Defaults to ten `step`s. | | `maxZoom` | `number` | `Infinity` | | | `minZoom` | `number` | `0` | | | `onPositionChange` | `(value: number, eventDetails: PositionChangeEventDetails) => void` | | Fires while the position is moved: press, drag, keyboard and input changes. | | `onPositionCommitted` | `(value: number, eventDetails: PositionCommitEventDetails) => void` | | Fires when a gesture that moved the position ends. | | `onZoomChange` | `(zoom: number, eventDetails: ZoomChangeEventDetails) => void` | | Fires when the zoom changes, already clamped. `eventDetails.cancel()` keeps the zoom where it was. | | `position` | `number` | | Playback position, from 0 to `duration`. | | `snapOffset` | `number` | `0` | Where the grid's lines start, in your units. | | `snapPoints` | `readonly number[]` | | Places that pull a dragged clip or range onto them from a few px away, ahead of the grid: the edges of other clips, the locators. Cmd/Ctrl lets go of them too. | | `snapStep` | `number` | `0` | Distance between grid lines, in your units. 0 is no grid. | | `source` | `Source` | | A live position followed outside React; takes precedence over `position`. | | `step` | `number` | | Step for the arrow keys. Defaults to `snapStep`, or a hundredth of `duration`. | | `zoom` | `number` | | Zoom, in px per unit. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-fitted` | Whether no zoom is set, so the timeline fits the width it is given. | | `data-scrubbing` | Whether a pointer is moving the position. | ### Navigator The whole timeline as one bar, with the stretch the viewport shows drawn inside it as `Timeline.NavigatorWindow`: drag the window to scroll, drag one of its `Timeline.NavigatorHandle`s to zoom, double-click to show everything. Place it anywhere inside `Timeline.Root`, outside the viewport. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `getAriaValueText` | `DescribePosition` | | Returns how a position is announced by the window and its handles. Defaults to the number. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-fitted` | Whether no zoom is set, so the timeline fits the width it is given. | | `data-scrubbing` | Whether a pointer is moving the position. | ### NavigatorWindow The stretch of the timeline the viewport shows. Dragging it scrolls; its native `` scrolls from the keyboard and carries its accessible name. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `edge` | `"end" \| "start"` | | The edge of the window this handle moves. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-fitted` | Whether no zoom is set, so the timeline fits the width it is given. | | `data-scrubbing` | Whether a pointer is moving the position. | ### Viewport The scrolling window onto the timeline. Cmd/Ctrl + wheel (and pinch on a trackpad) zooms around the pointer; a bare wheel scrolls as usual. Every zoom change keeps its anchor point in place, or the middle of the view when there is none. It reports its scroll offset and width for `Timeline.Navigator`. Renders a `

` element. **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-fitted` | Whether no zoom is set, so the timeline fits the width it is given. | | `data-scrubbing` | Whether a pointer is moving the position. | ### Lane A strip along the timeline that its parts are placed on: a track, the ruler's strip, a row of markers. Zoomed, it is as long as the timeline; fitted, it takes the width it is given and the timeline is spread across it. Its `--timeline-unit` CSS variable is the width of one unit. With `seekable`, a press on its bare area moves the position, as on the ruler, so the cursor can be put anywhere along a track; with `onSelectionChange` too, a drag from there selects a stretch of time instead of scrubbing. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `seekable` | `boolean` | `false` | Whether a press on the lane's bare area moves the position, and a drag scrubs it, on the grid unless Cmd/Ctrl is held. | | `onSelectionChange` | `(range: readonly [number, number], eventDetails) => void` | | With `seekable`, fires while a drag from the lane's bare area selects a stretch of time, as `[start, end]` in timeline units on the grid unless Cmd/Ctrl is held: from where the press put the position to the pointer. The drag then no longer scrubs. `eventDetails.cancel()` keeps the selection as it was. | | `onSelectionCommitted` | `(range: readonly [number, number], eventDetails) => void` | | Fires when a selection that changed ends. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-fitted` | Whether no zoom is set, so the timeline fits the width it is given. | | `data-scrubbing` | Whether a pointer is moving the position. | ### Track One track of the arrangement: a row holding a header beside a lane. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `height` | `number` | | The height in px, or leave it out for the row to share what room there is. | | `minHeight / maxHeight` | `number` | `32 / 480` | Bounds the height is clamped to. | | `step / largeStep` | `number` | `8 / 32` | How far the arrows, and Page Up and Page Down, move the height. | | `selected` | `boolean` | `false` | Whether the track is the one picked: only styling, `data-selected`. | | `onHeightChange` | `(height \| undefined, eventDetails) => void` | | A new height is asked for, by a drag or a key; a double-click on the handle gives the height up, which is `undefined`. `eventDetails.cancel()` refuses it. | | `onHeightCommitted` | `(height \| undefined, eventDetails) => void` | | A resize ended having changed the height. | **Data attributes** | Attribute | Description | | --- | --- | | `data-selected` | Present when the track is selected. | | `data-resizing` | Whether a pointer is resizing the track. | ### TrackHeader The strip beside a track's lane that names it and holds what sets it. It stays at the left edge while the lane scrolls under it, at the stacking level of the `--timeline-track-header-z` CSS variable (20): raise it while the header is hovered or focused if it shows something that reaches into the next row, such as a value readout. It carries the track's `data-selected` and `data-resizing`. Renders a `

` element. ### TrackResizeHandle Sets the track's height: by dragging, or from the keyboard through the native `` it holds, which carries the accessible name. The arrows move by a step (Down is taller), Page Up and Page Down by a large one, Home and End to the minimum and the maximum. Place it along the track's lower edge. A double-click clears the height, so the track shares the room again. Renders a `

` element. ### Ruler The lane that moves the position: a press jumps to the pointer and a drag scrubs, both on the grid unless Cmd/Ctrl is held; with Shift held the drag scrubs four times finer. With `onSelectionChange`, a drag that starts with Shift held selects a stretch instead, to loop. It holds the native `` that takes focus, handles the keyboard and carries the accessible name (`aria-label` / `aria-labelledby`). Place `Timeline.Mark`s in it for its labels. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `getAriaValueText` | `DescribePosition` | | Returns how the position is announced, e.g. `"bar 3, beat 2"`. Defaults to the number. | | `onSelectionChange` | `(range: readonly [number, number], eventDetails) => void` | | Fires while a stretch is selected by dragging with Shift held, as `[start, end]` in timeline units on the grid unless Cmd/Ctrl is held: feed it to a `Timeline.Range` as a loop. A plain press and drag still move the position. `eventDetails.cancel()` keeps the selection as it was. | | `onSelectionCommitted` | `(range: readonly [number, number], eventDetails) => void` | | Fires when a selection that changed ends. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-fitted` | Whether no zoom is set, so the timeline fits the width it is given. | | `data-scrubbing` | Whether a pointer is moving the position. | ### Range A stretch of the timeline, such as a loop, a selection or a clip, laid on the lane it sits in from `value[0]` to `value[1]`. Dragging its body moves it, on the grid unless Cmd/Ctrl is held; add a `Timeline.RangeHandle` per edge to resize it. With `drawable`, dragging across empty lane draws a new range. Its own native `` moves it from the keyboard and carries its accessible name (`aria-label` / `aria-labelledby`): Left and Right by a step, Up and Down by its own length, and with Cmd/Ctrl, Left and Right shorten or lengthen it by a step while Up and Down double or halve it. A drag lands an edge on a `snapPoints` place within a few px. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `defaultValue` | `Value` | | Uncontrolled starting range. Defaults to the whole timeline. | | `disabled` | `boolean` | | | | `drawable` | `boolean` | `false` | Whether dragging across empty lane draws a new range. | | `getAriaValueText` | `DescribePosition` | | Returns how a position is announced, for the range and its handles. Defaults to the number. | | `minLength` | `number` | | The shortest the range can be, in the timeline's units. Defaults to the grid step. | | `movable` | `boolean` | `true` | Whether dragging the body, or its keys, moves the range. | | `onValueChange` | `(value: Value, eventDetails: ChangeEventDetails) => void` | | Fires while the range is moved, resized or drawn. | | `onValueCommitted` | `(value: Value, eventDetails: CommitEventDetails) => void` | | Fires when a gesture that changed the range ends. | | `value` | `Value` | | The range, as `[start, end]` in the timeline's units. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-dragging` | Whether a pointer is moving, resizing or drawing the range. | ### RangeHandle Resizes one edge of the range: by dragging, on the grid unless Cmd/Ctrl is held, or from the keyboard through the native `` it holds, which carries the accessible name. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `edge` | `"end" \| "start"` | | The edge of the range this handle resizes. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-dragging` | Whether a pointer is moving, resizing or drawing the range. | ### Clip A stretch of a source laid on a lane. Dragging its `Timeline.ClipHeader` moves it, on the grid unless Cmd/Ctrl is held, and over other lanes too; pressing its body selects it and puts the cursor there. Add a `Timeline.ClipHandle` per edge to trim it and a `Timeline.ClipFadeHandle` per fade. It sets `--clip-offset`, `--clip-source-length`, `--clip-fade-in` and `--clip-fade-out` for its content, and `--clip-fade-in-max` and `--clip-fade-out-max`, how long each fade can grow, to draw the limit of a fade being dragged (`data-fading`). Its own native `` moves it from the keyboard and carries its accessible name (`aria-label` / `aria-labelledby`); Delete and Backspace on it call `onRemove`. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `value` | `Value` | | The clip: `{ start, length, offset, fadeIn, fadeOut }`, all in the timeline's units. | | `defaultValue` | `Value` | | Uncontrolled starting clip. Defaults to the whole timeline. | | `sourceLength` | `number` | | How long the source is, in the timeline's units: trimming stops where it runs out. Defaults to no limit. | | `selected` | `boolean` | | Whether the clip is selected. | | `defaultSelected` | `boolean` | `false` | Whether the clip starts selected, when `selected` is not set. | | `additive` | `boolean` | `false` | Whether every press is reported, as one with Shift, Cmd or Ctrl held is: for building a selection where there are no modifier keys, such as a touch screen. | | `onSelectedChange` | `(selected: boolean, eventDetails) => void` | | Fires when a press on the clip selects it, and again on a press with Shift, Cmd or Ctrl held (or any, when `additive`), which `eventDetails.event` carries. | | `onValueChange` | `(value: Value, eventDetails: ChangeEventDetails) => void` | | Fires while the clip is moved, trimmed or faded. | | `onValueCommitted` | `(value: Value, eventDetails: CommitEventDetails) => void` | | Fires when a gesture that changed the clip ends, or one that dropped it on another lane. | | `onRemove` | `(eventDetails) => void` | | Fires when Delete or Backspace is pressed on the clip: removing it is up to you. | | `minLength` | `number` | | The shortest the clip can be trimmed to, in the timeline's units. Defaults to the grid step. | | `movable` | `boolean` | `true` | Whether dragging the header, or the keys, moves the clip. | | `getAriaValueText` | `DescribePosition` | | Returns how a position is announced. Defaults to the number. | | `disabled` | `boolean` | | | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-dragging` | Whether a pointer is moving, trimming or fading the clip. | | `data-fading` | `"in"` or `"out"`: the fade a pointer is dragging. | | `data-selected` | Present when the clip is selected. | ### ClipHeader The clip's title bar: dragging it moves the clip, on the grid unless Cmd/Ctrl is held, and over other lanes too. The rest of the clip is its body, where a press puts the cursor. Place it along the clip's top and put the clip's name in it. Renders a `

` element. **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-dragging` | Whether a pointer is moving, trimming or fading the clip. | | `data-selected` | Present when the clip is selected. | ### ClipHandle Trims one edge of the clip: by dragging, on the grid unless Cmd/Ctrl is held, or from the keyboard through the native `` it holds, which carries the accessible name. Trimming the start moves where in the source the clip begins and leaves its content where it is; trimming the end stops where the source or the timeline does. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `edge` | `"end" \| "start"` | | The edge of the clip this handle trims. | ### ClipFadeHandle Sets how long one of the clip's fades lasts: by dragging, or from the keyboard through the native `` it holds, which carries the accessible name. Double-clicking it, or pressing Enter on its input, steps the fade through its shapes, and Delete or Backspace takes the fade away. It sits where its fade ends, at the clip's top edge. The two fades cannot overlap. Renders a `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `edge` | `"in" \| "out"` | | The fade of the clip this handle sets: the one at its start or at its end. Double-click it, or press Enter on its input, to step the fade through its shapes. | ### ClipFade Draws a fade over the clip's content, as a DAW does: the ramp as a line from the clip's edge, as long as the fade, with what it attenuates lightly shaded. It is hidden while its fade is empty and ignores the pointer. Its color is the `color` it is given. Renders an `

` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `value` | `number` | | Where the mark sits, in the timeline's units. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-fitted` | Whether no zoom is set, so the timeline fits the width it is given. | | `data-scrubbing` | Whether a pointer is moving the position. | ### Registry component #### Timeline | Prop | Type | Default | Description | | --- | --- | --- | --- | | `duration` | `number` | `1` | Length of the timeline, in your units. | | `zoom` | `number` | | Zoom, in px per unit. | | `defaultZoom` | `number` | | Uncontrolled starting zoom, in px per unit. Unset, the timeline fits its width until zoomed. | | `minZoom / maxZoom` | `number` | `0 / Infinity` | Bounds the zoom is clamped to. | | `onZoomChange` | `(zoom, eventDetails) => void` | | Fires when the zoom changes, already clamped. `eventDetails.cancel()` keeps the zoom where it was. | | `position` | `number` | | Playback position, from 0 to `duration`. | | `defaultPosition` | `number` | `0` | Uncontrolled starting position. | | `source` | `{ getSnapshot, subscribe }` | | A live position followed outside React; takes precedence over `position`. | | `onPositionChange` | `(value, eventDetails) => void` | | Fires while the position is moved: press, drag, keyboard and input changes. | | `onPositionCommitted` | `(value, eventDetails) => void` | | Fires when a gesture that moved the position ends. | | `snapStep` | `number` | `0` | Distance between grid lines, in your units. 0 is no grid. | | `snapOffset` | `number` | `0` | Where the grid's lines start, in your units. | | `step / largeStep` | `number` | `snapStep / ten steps` | Keyboard steps. | | `disabled` | `boolean` | `false` | Disables seeking and zooming. | #### Parts **Components** | Name | Description | | --- | --- | | `TimelineViewport` | The scrolling window. Zooms around the pointer with Cmd/Ctrl + scroll. `scrollbar="hidden"` drops the native scrollbar. | | `TimelineRuler` | The lane that seeks. Holds the input; takes `aria-label` and `getAriaValueText`. | | `TimelineLane` | A strip the timeline's parts are placed on. `gridStep` draws a line every that many units. | | `TimelineTrack` | A row: a header beside a lane. `height`, `selected`, `onHeightChange`. | | `TimelineTrackHeader` | The strip that names a track, kept at the left edge. | | `TimelineTrackResizeHandle` | Sets the track's height, by dragging or with the keys. | | `TimelineMark` | Something placed at `value`: a bar number, a cue. | | `TimelinePlayhead` | Follows the position on the lane it sits in. | | `TimelineRange` | A stretch of the timeline: `value`, `defaultValue`, `minLength`, `movable`, `drawable`, `onValueChange`, `onValueCommitted`. | | `TimelineRangeHandle` | Resizes one `edge` of the range. | | `TimelineClip` | A stretch of a source: `value`, `sourceLength`, `selected`, `onValueChange`, `onValueCommitted`, `onRemove`. Dragged over other lanes too. | | `TimelineClipHeader` | The clip's title bar: drag it to move the clip. | | `TimelineClipHandle` | Trims one `edge` of the clip. | | `TimelineClipFade` | Draws a fade, as a line with its shading. Takes `edge`. | | `TimelineClipFadeHandle` | Sets a fade, at the clip's top corner: a square that shows when the clip is hovered or selected. Takes `edge`. | | `TimelineNavigator` | The whole timeline as one bar, scrolling and zooming the viewport. | `@audio-ui/react/timeline` exposes the same parts as `Timeline.Root`, `Timeline.Viewport`, `Timeline.Ruler`, `Timeline.Lane`, `Timeline.Mark`, `Timeline.Playhead`, `Timeline.Range`, `Timeline.RangeHandle`, `Timeline.Clip`, `Timeline.ClipHeader`, `Timeline.ClipHandle`, `Timeline.ClipFade`, `Timeline.ClipFadeHandle`, and `Timeline.Navigator` with its `Timeline.NavigatorWindow` and `Timeline.NavigatorHandle`. Every part accepts a `render` prop and `className` / `style` as functions of state, and exposes `data-disabled`, `data-fitted` and `data-scrubbing`.