feat(components): add playback speed control to audio player (#3)

* feat(components): add playback speed control to audio player

* fix(components): preserve playback speed when switching tracks

Author: jefferypippitt

apps/www/content/docs/components/audio-player.mdx

@@ -53,6 +53,8 @@ import {
   AudioPlayerDuration,
   AudioPlayerProgress,
   AudioPlayerProvider,
+  AudioPlayerSpeed,
+  AudioPlayerSpeedButtonGroup,
   AudioPlayerTime,
   useAudioPlayer,
   useAudioPlayerTime,
@@ -178,6 +180,43 @@ Displays the total duration of the current track or "--:--" when unavailable.
 | className | `string`          | Optional CSS classes            |
 | ...props  | `HTMLSpanElement` | All standard span element props |
 
+### AudioPlayerSpeed
+
+A dropdown menu button (with settings icon) for controlling playback speed. Displays "Normal" for 1x speed and shows other speeds with "x" suffix (e.g., "0.5x", "1.5x").
+
+#### Props
+
+| Prop     | Type                | Default                                    | Description                         |
+| -------- | ------------------- | ------------------------------------------ | ----------------------------------- |
+| speeds   | `readonly number[]` | `[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]` | Available playback speeds           |
+| variant  | `ButtonVariant`     | `"ghost"`                                  | Button variant                      |
+| size     | `ButtonSize`        | `"icon"`                                   | Button size                         |
+| ...props | `ButtonProps`       | -                                          | All standard Button component props |
+
+#### Example
+
+```tsx
+<AudioPlayerSpeed variant="ghost" size="icon" />
+```
+
+### AudioPlayerSpeedButtonGroup
+
+A button group component for quick playback speed selection.
+
+#### Props
+
+| Prop      | Type                | Default            | Description                    |
+| --------- | ------------------- | ------------------ | ------------------------------ |
+| speeds    | `readonly number[]` | `[0.5, 1, 1.5, 2]` | Available playback speeds      |
+| className | `string`            | -                  | Optional CSS classes           |
+| ...props  | `HTMLDivElement`    | -                  | All standard div element props |
+
+#### Example
+
+```tsx
+<AudioPlayerSpeedButtonGroup speeds={[0.5, 0.75, 1, 1.5, 2]} />
+```
+
 ### useAudioPlayer Hook
 
 Access the audio player context to control playback programmatically.
@@ -190,11 +229,13 @@ const {
   error, // MediaError if any
   isPlaying, // Playing state
   isBuffering, // Buffering state
+  playbackRate, // Current playback speed
   isItemActive, // Check if an item is active
   setActiveItem, // Set the active item
   play, // Play audio
   pause, // Pause audio
   seek, // Seek to time
+  setPlaybackRate, // Change playback speed
 } = useAudioPlayer<TData>()
 ```
 
@@ -238,11 +279,30 @@ function CustomTimeDisplay() {
 
 ## Advanced Examples
 
+### Player with Speed Control
+
+```tsx showLineNumbers
+function AudioPlayerWithSpeed() {
+  return (
+    <AudioPlayerProvider>
+      <div className="flex items-center gap-4">
+        <AudioPlayerButton />
+        <AudioPlayerTime />
+        <AudioPlayerProgress className="flex-1" />
+        <AudioPlayerDuration />
+        <AudioPlayerSpeed />
+      </div>
+    </AudioPlayerProvider>
+  )
+}
+```
+
 ### Custom Controls
 
 ```tsx showLineNumbers
 function CustomAudioPlayer() {
-  const { play, pause, isPlaying, seek, duration } = useAudioPlayer()
+  const { play, pause, isPlaying, seek, duration, setPlaybackRate } =
+    useAudioPlayer()
 
   return (
     <div className="space-y-4">
@@ -255,6 +315,8 @@ function CustomAudioPlayer() {
       <button onClick={() => duration && seek(duration * 0.5)}>
         Jump to 50%
       </button>
+
+      <button onClick={() => setPlaybackRate(1.5)}>Speed 1.5x</button>
     </div>
   )
 }
@@ -288,3 +350,5 @@ function AudioPlayerWithError() {
 - Space bar triggers play/pause when the progress slider is focused
 - The component includes TypeScript support with generic data types
 - Audio state is managed globally within the provider context
+- Playback speed displays "Normal" for 1x speed and numerical values (e.g., "0.5x", "1.5x") for other speeds
+- Playback speed is preserved when switching between tracks

apps/www/public/r/all.json

@@ -11,7 +11,7 @@
   "files": [
     {
       "path": "examples/audio-player-demo.tsx",
-      "content": "\"use client\"\n\nimport { PauseIcon, PlayIcon } from \"lucide-react\"\n\nimport { cn } from \"@/lib/utils\"\nimport {\n  AudioPlayerButton,\n  AudioPlayerDuration,\n  AudioPlayerProgress,\n  AudioPlayerProvider,\n  AudioPlayerTime,\n  exampleTracks,\n  useAudioPlayer,\n} from \"@/components/ui/audio-player\"\nimport { Button } from \"@/components/ui/button\"\nimport { Card } from \"@/components/ui/card\"\nimport { ScrollArea } from \"@/components/ui/scroll-area\"\n\ninterface Track {\n  id: string\n  name: string\n  url: string\n}\n\nexport default function AudioPlayer() {\n  return (\n    <AudioPlayerProvider<Track>>\n      <AudioPlayerDemo />\n    </AudioPlayerProvider>\n  )\n}\n\nconst AudioPlayerDemo = () => {\n  return (\n    <Card className=\"w-full overflow-hidden p-0\">\n      <div className=\"flex flex-col lg:h-[180px] lg:flex-row\">\n        <div className=\"bg-muted/50 flex flex-col overflow-hidden lg:h-full lg:w-64\">\n          <ScrollArea className=\"h-48 w-full lg:h-full\">\n            <div className=\"space-y-1 p-3\">\n              {exampleTracks.map((song, index) => (\n                <SongListItem\n                  key={song.id}\n                  song={song}\n                  trackNumber={index + 1}\n                />\n              ))}\n            </div>\n          </ScrollArea>\n        </div>\n        <Player />\n      </div>\n    </Card>\n  )\n}\n\nconst Player = () => {\n  const player = useAudioPlayer<Track>()\n\n  return (\n    <div className=\"flex flex-1 items-center p-4 sm:p-6\">\n      <div className=\"mx-auto w-full max-w-2xl\">\n        <div className=\"mb-4\">\n          <h3 className=\"text-base font-semibold sm:text-lg\">\n            {player.activeItem?.data?.name ?? \"No track selected\"}\n          </h3>\n        </div>\n        <div className=\"flex items-center gap-3 sm:gap-4\">\n          <AudioPlayerButton\n            variant=\"outline\"\n            size=\"default\"\n            className=\"h-12 w-12 shrink-0 sm:h-10 sm:w-10\"\n            disabled={!player.activeItem}\n          />\n          <div className=\"flex flex-1 items-center gap-2 sm:gap-3\">\n            <AudioPlayerTime className=\"text-xs tabular-nums\" />\n            <AudioPlayerProgress className=\"flex-1\" />\n            <AudioPlayerDuration className=\"text-xs tabular-nums\" />\n          </div>\n        </div>\n      </div>\n    </div>\n  )\n}\n\nconst SongListItem = ({\n  song,\n  trackNumber,\n}: {\n  song: Track\n  trackNumber: number\n}) => {\n  const player = useAudioPlayer<Track>()\n  const isActive = player.isItemActive(song.id)\n  const isCurrentlyPlaying = isActive && player.isPlaying\n\n  return (\n    <div className=\"group/song relative\">\n      <Button\n        variant={isActive ? \"secondary\" : \"ghost\"}\n        size=\"sm\"\n        className={cn(\n          \"h-10 w-full justify-start px-3 font-normal sm:h-9 sm:px-2\",\n          isActive && \"bg-secondary\"\n        )}\n        onClick={() => {\n          if (isCurrentlyPlaying) {\n            player.pause()\n          } else {\n            player.play({\n              id: song.id,\n              src: song.url,\n              data: song,\n            })\n          }\n        }}\n      >\n        <div className=\"flex w-full items-center gap-3\">\n          <div className=\"flex w-5 shrink-0 items-center justify-center\">\n            {isCurrentlyPlaying ? (\n              <PauseIcon className=\"h-4 w-4 sm:h-3.5 sm:w-3.5\" />\n            ) : (\n              <>\n                <span className=\"text-muted-foreground/60 text-sm tabular-nums group-hover/song:invisible\">\n                  {trackNumber}\n                </span>\n                <PlayIcon className=\"invisible absolute h-4 w-4 group-hover/song:visible sm:h-3.5 sm:w-3.5\" />\n              </>\n            )}\n          </div>\n          <span className=\"truncate text-left text-sm\">{song.name}</span>\n        </div>\n      </Button>\n    </div>\n  )\n}\n",
+      "content": "\"use client\"\n\nimport { PauseIcon, PlayIcon } from \"lucide-react\"\n\nimport { cn } from \"@/lib/utils\"\nimport {\n  AudioPlayerButton,\n  AudioPlayerDuration,\n  AudioPlayerProgress,\n  AudioPlayerProvider,\n  AudioPlayerSpeed,\n  AudioPlayerTime,\n  exampleTracks,\n  useAudioPlayer,\n} from \"@/components/ui/audio-player\"\nimport { Button } from \"@/components/ui/button\"\nimport { Card } from \"@/components/ui/card\"\nimport { ScrollArea } from \"@/components/ui/scroll-area\"\n\ninterface Track {\n  id: string\n  name: string\n  url: string\n}\n\nexport default function AudioPlayer() {\n  return (\n    <AudioPlayerProvider<Track>>\n      <AudioPlayerDemo />\n    </AudioPlayerProvider>\n  )\n}\n\nconst AudioPlayerDemo = () => {\n  return (\n    <Card className=\"w-full overflow-hidden p-0\">\n      <div className=\"flex flex-col lg:h-[180px] lg:flex-row\">\n        <div className=\"bg-muted/50 flex flex-col overflow-hidden lg:h-full lg:w-64\">\n          <ScrollArea className=\"h-48 w-full lg:h-full\">\n            <div className=\"space-y-1 p-3\">\n              {exampleTracks.map((song, index) => (\n                <SongListItem\n                  key={song.id}\n                  song={song}\n                  trackNumber={index + 1}\n                />\n              ))}\n            </div>\n          </ScrollArea>\n        </div>\n        <Player />\n      </div>\n    </Card>\n  )\n}\n\nconst Player = () => {\n  const player = useAudioPlayer<Track>()\n\n  return (\n    <div className=\"flex flex-1 items-center p-4 sm:p-6\">\n      <div className=\"mx-auto w-full max-w-2xl\">\n        <div className=\"mb-4\">\n          <h3 className=\"text-base font-semibold sm:text-lg\">\n            {player.activeItem?.data?.name ?? \"No track selected\"}\n          </h3>\n        </div>\n        <div className=\"flex items-center gap-3 sm:gap-4\">\n          <AudioPlayerButton\n            variant=\"outline\"\n            size=\"default\"\n            className=\"h-12 w-12 shrink-0 sm:h-10 sm:w-10\"\n            disabled={!player.activeItem}\n          />\n          <div className=\"flex flex-1 items-center gap-2 sm:gap-3\">\n            <AudioPlayerTime className=\"text-xs tabular-nums\" />\n            <AudioPlayerProgress className=\"flex-1\" />\n            <AudioPlayerDuration className=\"text-xs tabular-nums\" />\n            <AudioPlayerSpeed variant=\"ghost\" size=\"icon\" />\n          </div>\n        </div>\n      </div>\n    </div>\n  )\n}\n\nconst SongListItem = ({\n  song,\n  trackNumber,\n}: {\n  song: Track\n  trackNumber: number\n}) => {\n  const player = useAudioPlayer<Track>()\n  const isActive = player.isItemActive(song.id)\n  const isCurrentlyPlaying = isActive && player.isPlaying\n\n  return (\n    <div className=\"group/song relative\">\n      <Button\n        variant={isActive ? \"secondary\" : \"ghost\"}\n        size=\"sm\"\n        className={cn(\n          \"h-10 w-full justify-start px-3 font-normal sm:h-9 sm:px-2\",\n          isActive && \"bg-secondary\"\n        )}\n        onClick={() => {\n          if (isCurrentlyPlaying) {\n            player.pause()\n          } else {\n            player.play({\n              id: song.id,\n              src: song.url,\n              data: song,\n            })\n          }\n        }}\n      >\n        <div className=\"flex w-full items-center gap-3\">\n          <div className=\"flex w-5 shrink-0 items-center justify-center\">\n            {isCurrentlyPlaying ? (\n              <PauseIcon className=\"h-4 w-4 sm:h-3.5 sm:w-3.5\" />\n            ) : (\n              <>\n                <span className=\"text-muted-foreground/60 text-sm tabular-nums group-hover/song:invisible\">\n                  {trackNumber}\n                </span>\n                <PlayIcon className=\"invisible absolute h-4 w-4 group-hover/song:visible sm:h-3.5 sm:w-3.5\" />\n              </>\n            )}\n          </div>\n          <span className=\"truncate text-left text-sm\">{song.name}</span>\n        </div>\n      </Button>\n    </div>\n  )\n}\n",
       "type": "registry:example"
     }
   ]