{currentTrack?.title} ({duration}s) - {isPlaying ? "▶" : "⏸"}
); } ``` ### Architecture ```mermaid graph TB A(React Components) -->|useAudioStore selector| B(AudioStore Zustand) B -->|State Updates| A B -->|Actions| C($audio Singleton) C -->|HTMLAudioElement| D(Browser Audio API) B -->|Persist| E(localStorage) E -->|Restore| B ``` ## Types ### Track Common audio track object. See [HTML Audio](/docs/lib/html-audio#track) for full definition. ### AudioStore State The store exposes state organized by concern: | Category | Property | Type | Description | | ----------------- | -------------------- | -------------------------------- | ------------------------------- | | **Playback** | `isPlaying` | `boolean` | Currently playing | | | `isLoading` | `boolean` | Loading track | | | `isBuffering` | `boolean` | Buffering audio | | | `isError` | `boolean` | Error state | | | `errorMessage` | `string \| null` | Error details | | **Current Track** | `currentTrack` | `Track \| null` | Active track object | | | `currentTime` | `number` | Playback position (seconds) | | | `duration` | `number` | Track length | | | `progress` | `number` | Normalized progress 0–1 | | | `bufferedTime` | `number` | Buffered amount | | **Queue** | `queue` | `Track[]` | Array of tracks | | | `currentQueueIndex` | `number` | Active track index | | **Controls** | `volume` | `number` | Volume 0–1 | | | `isMuted` | `boolean` | Mute state | | | `repeatMode` | `"none" \| "one" \| "all"` | Repeat mode | | | `shuffleEnabled` | `boolean` | Shuffle state | | | `insertMode` | `"first" \| "last" \| "after"` | Insertion position for queue | ### Types | Type | Values | Description | | ------------ | -------------------------------- | ------------------------------------------ | | `RepeatMode` | `"none" \| "one" \| "all"` | Repeat playback mode | | `InsertMode` | `"first" \| "last" \| "after"` | Where new tracks are added to the queue | #### RepeatMode Flow ```mermaid stateDiagram-v2 [*] --> none none --> one: changeRepeatMode() one --> all: changeRepeatMode() all --> none: changeRepeatMode() note right of none No repeat Play queue once end note note right of one Repeat current track indefinitely end note note right of all Repeat entire queue Loop forever end note ``` ## Utility Functions ### calculateNextIndex(queue, currentIndex, shuffleEnabled, repeatMode) Calculate the next track index based on playback mode. ```tsx const nextIndex = calculateNextIndex( queue, currentQueueIndex, shuffleEnabled, repeatMode ); // Returns: number (track index or -1 if none) ``` ### calculatePreviousIndex(queue, currentIndex, shuffleEnabled, repeatMode) Calculate the previous track index based on playback mode. ```tsx const prevIndex = calculatePreviousIndex( queue, currentQueueIndex, shuffleEnabled, repeatMode ); // Returns: number (track index or -1 if none) ``` ### canUseDOM() Check if code runs in a DOM environment (not SSR). ```tsx if (canUseDOM()) { // Browser-only code } ```canUseDOM(){" "}
internally to handle server-side rendering. When accessing the store in SSR
contexts, ensure you check for DOM availability before calling store methods
that interact with browser APIs.
Track: {currentTrack?.title ?? "None"}
Time: {formatDuration(currentTime)} / {formatDuration(duration)}
Status: {isPlaying ? "▶" : "⏸"}
play, next,{" "}
setCurrentTrack) wait for audio loading
- addToQueue supports "first", "last", and "after" insert modes
- Queue shuffling randomizes order but preserves track identity
- setQueueAndPlay and similar actions trigger audio loading via the
[HTML Audio](/docs/lib/html-audio)
- Persistence is automatic; no manual save required
- Direct store access via getState() is useful for non-React code
or imperative operations
$htmlAudio singleton must
be initialized on the client. Call $htmlAudio.init() from a client
component or inside useEffect() so the underlying{" "}
HTMLAudioElement is created only in the browser environment.
play() call
returns a promise which may be rejected by browser autoplay policies if there
was no user gesture. Wrap calls to play() in a try/catch and
provide a fallback UI so your app handles playback interruptions gracefully.
isLive is
true) seeking is disabled and long timeouts are used. Live streams are best
handled with a separate code-path because the playback semantics differ from
on-demand audio files.
isLive() method checks
if a duration is NaN, Infinity, or{" "}
-Infinity. A duration of 0 is not considered a live
stream (it just means the duration hasn't loaded yet).
tracks on AudioPlayer for self-contained widgets. Use AudioProvider at the root when multiple components share the same playback session.
trackId or track, not both. trackId requires an AudioProvider in the tree.
AudioPlayerPlay registers a global keydown listener for Space when the document body is focused.
@dnd-kit,
which includes keyboard-friendly drag-and-drop behavior. See the{" "}
dnd-kit documentation
for details.
- **Drag Handle:** SortableDragHandle uses the project Button{" "}
primitive and ships pre-wired accessibility attributes.
- **Item IDs:** Each item must have a unique id property. The
`id` type must match between the item object and the SortableItem{" "}
component.
- **Usage in Audio Components:** This component is used by{" "}
AudioTrackList for queue reordering.