@djangocfg/ui-nextjs 2.1.82 → 2.1.83

package/src/tools/AudioPlayer/components/HybridAudioPlayer.tsx

@@ -0,0 +1,251 @@
+'use client';
+
+/**
+ * HybridAudioPlayer - Audio playback controls with frequency visualization
+ *
+ * Uses HybridAudioContext for state management.
+ * Native HTML5 audio for playback, Web Audio API for visualization only.
+ *
+ * Features:
+ * - Real-time frequency visualization
+ * - Playback controls (play, pause, skip, restart)
+ * - Volume control with mute
+ * - Loop toggle
+ * - Keyboard shortcuts
+ * - Timer display
+ */
+
+import { memo } from 'react';
+import {
+  Play,
+  Pause,
+  RotateCcw,
+  SkipBack,
+  SkipForward,
+  Volume2,
+  VolumeX,
+  Loader2,
+  Repeat,
+} from 'lucide-react';
+import { Button, Slider, cn } from '@djangocfg/ui-nextjs';
+import { useHybridAudioContext } from '../context/HybridAudioProvider';
+import { HybridWaveform } from './HybridWaveform';
+import { AudioEqualizer } from './AudioEqualizer';
+import { AudioShortcutsPopover } from './AudioShortcutsPopover';
+import { useAudioHotkeys } from '../hooks';
+import { formatTime } from '../utils';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface HybridAudioPlayerProps {
+  /** Show playback controls */
+  showControls?: boolean;
+  /** Show frequency waveform */
+  showWaveform?: boolean;
+  /** Waveform visualization mode */
+  waveformMode?: 'frequency' | 'static';
+  /** Waveform height in pixels */
+  waveformHeight?: number;
+  /** Show equalizer bars */
+  showEqualizer?: boolean;
+  /** Show time display */
+  showTimer?: boolean;
+  /** Show volume control */
+  showVolume?: boolean;
+  /** Show loop button */
+  showLoop?: boolean;
+  /** Equalizer options */
+  equalizerOptions?: {
+    barCount?: number;
+    height?: number;
+    gap?: number;
+    showPeaks?: boolean;
+    barColor?: string;
+    peakColor?: string;
+  };
+  /** Additional CSS class */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export const HybridAudioPlayer = memo(function HybridAudioPlayer({
+  showControls = true,
+  showWaveform = true,
+  waveformMode = 'frequency',
+  waveformHeight = 64,
+  showEqualizer = false,
+  showTimer = true,
+  showVolume = true,
+  showLoop = true,
+  equalizerOptions = {},
+  className,
+  style,
+}: HybridAudioPlayerProps) {
+  const { state, controls } = useHybridAudioContext();
+
+  // Enable keyboard shortcuts
+  useAudioHotkeys({ enabled: state.isReady });
+
+  const isLoading = !state.isReady;
+
+  const handleVolumeChange = (value: number[]) => {
+    controls.setVolume(value[0] / 100);
+  };
+
+  return (
+    <div
+      className={cn('flex flex-col gap-3 p-4 rounded-lg bg-card border', className)}
+      style={style}
+    >
+      {/* Frequency Waveform */}
+      {showWaveform && (
+        <div className="relative">
+          <HybridWaveform
+            mode={waveformMode}
+            height={waveformHeight}
+            className={cn(isLoading && 'opacity-50')}
+          />
+          {isLoading && (
+            <div className="absolute inset-0 flex items-center justify-center">
+              <Loader2 className="h-6 w-6 animate-spin text-primary" />
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Equalizer animation */}
+      {showEqualizer && (
+        <AudioEqualizer
+          barCount={equalizerOptions.barCount}
+          height={equalizerOptions.height}
+          gap={equalizerOptions.gap}
+          showPeaks={equalizerOptions.showPeaks}
+          barColor={equalizerOptions.barColor}
+          peakColor={equalizerOptions.peakColor}
+          className="px-1"
+        />
+      )}
+
+      {/* Timer */}
+      {showTimer && (
+        <div className="flex justify-between text-xs text-muted-foreground tabular-nums px-1">
+          <span>{formatTime(state.currentTime)}</span>
+          <span>{formatTime(state.duration)}</span>
+        </div>
+      )}
+
+      {/* Controls */}
+      {showControls && (
+        <div className="flex items-center justify-center gap-1">
+          {/* Restart */}
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-9 w-9"
+            onClick={controls.restart}
+            disabled={!state.isReady}
+            title="Restart"
+          >
+            <RotateCcw className="h-4 w-4" />
+          </Button>
+
+          {/* Skip back 5s */}
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-9 w-9"
+            onClick={() => controls.skip(-5)}
+            disabled={!state.isReady}
+            title="Back 5 seconds"
+          >
+            <SkipBack className="h-4 w-4" />
+          </Button>
+
+          {/* Play/Pause */}
+          <Button
+            variant="default"
+            size="icon"
+            className="h-12 w-12 rounded-full"
+            onClick={controls.togglePlay}
+            disabled={!state.isReady && !isLoading}
+            title={state.isPlaying ? 'Pause' : 'Play'}
+          >
+            {isLoading ? (
+              <Loader2 className="h-5 w-5 animate-spin" />
+            ) : state.isPlaying ? (
+              <Pause className="h-5 w-5" />
+            ) : (
+              <Play className="h-5 w-5 ml-0.5" />
+            )}
+          </Button>
+
+          {/* Skip forward 5s */}
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-9 w-9"
+            onClick={() => controls.skip(5)}
+            disabled={!state.isReady}
+            title="Forward 5 seconds"
+          >
+            <SkipForward className="h-4 w-4" />
+          </Button>
+
+          {/* Volume */}
+          {showVolume && (
+            <>
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-9 w-9"
+                onClick={controls.toggleMute}
+                title={state.isMuted ? 'Unmute' : 'Mute'}
+              >
+                {state.isMuted || state.volume === 0 ? (
+                  <VolumeX className="h-4 w-4" />
+                ) : (
+                  <Volume2 className="h-4 w-4" />
+                )}
+              </Button>
+
+              <Slider
+                value={[state.isMuted ? 0 : state.volume * 100]}
+                max={100}
+                step={1}
+                onValueChange={handleVolumeChange}
+                className="w-20"
+                aria-label="Volume"
+              />
+            </>
+          )}
+
+          {/* Loop/Repeat */}
+          {showLoop && (
+            <Button
+              variant="ghost"
+              size="icon"
+              className={cn('h-9 w-9', state.isLooping && 'text-primary')}
+              onClick={controls.toggleLoop}
+              disabled={!state.isReady}
+              title={state.isLooping ? 'Disable loop' : 'Enable loop'}
+            >
+              <Repeat className="h-4 w-4" />
+            </Button>
+          )}
+
+          {/* Shortcuts help */}
+          <AudioShortcutsPopover compact />
+        </div>
+      )}
+    </div>
+  );
+});
+
+export default HybridAudioPlayer;

package/src/tools/AudioPlayer/components/HybridSimplePlayer.tsx

@@ -0,0 +1,291 @@
+'use client';
+
+/**
+ * HybridSimplePlayer - Easy-to-use hybrid audio player wrapper
+ *
+ * Combines HybridAudioProvider + HybridAudioPlayer + optional reactive cover
+ * in a single component with sensible defaults.
+ *
+ * Uses native HTML5 audio for playback (no crackling) with Web Audio API
+ * for visualization only.
+ *
+ * @example
+ * // Minimal usage
+ * <HybridSimplePlayer src="https://example.com/audio.mp3" />
+ *
+ * @example
+ * // With cover art and reactive effects
+ * <HybridSimplePlayer
+ *   src={audioUrl}
+ *   title="Track Title"
+ *   artist="Artist Name"
+ *   coverArt="/path/to/cover.jpg"
+ *   reactiveCover
+ *   variant="spotlight"
+ * />
+ */
+
+import { type ReactNode } from 'react';
+import { Music } from 'lucide-react';
+import { cn } from '@djangocfg/ui-core';
+
+import { HybridAudioProvider } from '../context/HybridAudioProvider';
+import { HybridAudioPlayer } from './HybridAudioPlayer';
+import { AudioReactiveCover } from './ReactiveCover';
+import { VisualizationProvider, useVisualization } from '../hooks';
+import type { EqualizerOptions } from '../types';
+import type { EffectIntensity, EffectColorScheme } from '../effects';
+import type { VisualizationVariant } from '../hooks';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface HybridSimplePlayerProps {
+  /** Audio source URL */
+  src: string;
+
+  /** Track title */
+  title?: string;
+
+  /** Artist name */
+  artist?: string;
+
+  /** Cover art URL or ReactNode */
+  coverArt?: string | ReactNode;
+
+  /** Cover art size */
+  coverSize?: 'sm' | 'md' | 'lg';
+
+  /** Show frequency waveform */
+  showWaveform?: boolean;
+
+  /** Waveform visualization mode */
+  waveformMode?: 'frequency' | 'static';
+
+  /** Waveform height in pixels */
+  waveformHeight?: number;
+
+  /** Show equalizer bars */
+  showEqualizer?: boolean;
+
+  /** Show timer */
+  showTimer?: boolean;
+
+  /** Show volume control */
+  showVolume?: boolean;
+
+  /** Show loop/repeat button */
+  showLoop?: boolean;
+
+  /** Enable audio-reactive cover effects */
+  reactiveCover?: boolean;
+
+  /** Reactive effect variant */
+  variant?: VisualizationVariant;
+
+  /** Reactive effect intensity */
+  intensity?: EffectIntensity;
+
+  /** Reactive effect color scheme */
+  colorScheme?: EffectColorScheme;
+
+  /** Auto-play on load */
+  autoPlay?: boolean;
+
+  /** Loop playback */
+  loop?: boolean;
+
+  /** Initial volume (0-1) */
+  initialVolume?: number;
+
+  /** Equalizer customization */
+  equalizerOptions?: EqualizerOptions;
+
+  /** Layout direction */
+  layout?: 'vertical' | 'horizontal';
+
+  /** Additional class name */
+  className?: string;
+
+  /** Callbacks */
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onError?: (error: Error) => void;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const COVER_SIZES = {
+  sm: 'w-24 h-24',
+  md: 'w-32 h-32',
+  lg: 'w-48 h-48',
+};
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function HybridSimplePlayer(props: HybridSimplePlayerProps) {
+  return (
+    <VisualizationProvider>
+      <HybridSimplePlayerContent {...props} />
+    </VisualizationProvider>
+  );
+}
+
+function HybridSimplePlayerContent({
+  src,
+  title,
+  artist,
+  coverArt,
+  coverSize = 'md',
+  showWaveform = true,
+  waveformMode = 'frequency',
+  waveformHeight = 64,
+  showEqualizer = false,
+  showTimer = true,
+  showVolume = true,
+  showLoop = true,
+  reactiveCover = true,
+  variant,
+  intensity,
+  colorScheme,
+  autoPlay = false,
+  loop = false,
+  initialVolume = 1,
+  equalizerOptions,
+  layout = 'vertical',
+  className,
+  onPlay,
+  onPause,
+  onEnded,
+  onError,
+}: HybridSimplePlayerProps) {
+  const { settings: vizSettings, nextVariant } = useVisualization();
+
+  // Determine effective variant (from props or localStorage settings)
+  const effectiveVariant =
+    variant ?? (vizSettings.variant !== 'none' ? vizSettings.variant : 'spotlight');
+  const effectiveIntensity = intensity ?? vizSettings.intensity;
+  const effectiveColorScheme = colorScheme ?? vizSettings.colorScheme;
+
+  // Show reactive cover if enabled and variant is not 'none'
+  const showReactiveCover = reactiveCover && effectiveVariant !== 'none';
+
+  // Render cover art content
+  const renderCoverContent = () => {
+    if (typeof coverArt === 'string') {
+      return (
+        <img src={coverArt} alt={title || 'Album cover'} className="w-full h-full object-cover" />
+      );
+    }
+
+    if (coverArt) {
+      return coverArt;
+    }
+
+    // Default placeholder
+    return (
+      <div className="w-full h-full bg-muted/30 flex items-center justify-center">
+        <Music className="w-1/3 h-1/3 text-muted-foreground/50" />
+      </div>
+    );
+  };
+
+  const isHorizontal = layout === 'horizontal';
+
+  return (
+    <HybridAudioProvider
+      src={src}
+      autoPlay={autoPlay}
+      loop={loop}
+      initialVolume={initialVolume}
+      onPlay={onPlay}
+      onPause={onPause}
+      onEnded={onEnded}
+      onError={onError}
+    >
+      <div
+        className={cn(
+          'flex gap-4',
+          isHorizontal ? 'flex-row items-center' : 'flex-col items-center',
+          className
+        )}
+      >
+        {/* Cover Art */}
+        {(coverArt || reactiveCover) && (
+          <div className="flex flex-col items-center gap-2 shrink-0">
+            {showReactiveCover ? (
+              <AudioReactiveCover
+                size={coverSize}
+                variant={effectiveVariant as 'glow' | 'orbs' | 'spotlight' | 'mesh'}
+                intensity={effectiveIntensity}
+                colorScheme={effectiveColorScheme}
+                onClick={nextVariant}
+              >
+                <div className={cn('rounded-lg overflow-hidden', COVER_SIZES[coverSize])}>
+                  {renderCoverContent()}
+                </div>
+              </AudioReactiveCover>
+            ) : (
+              <div
+                className={cn(
+                  'rounded-lg overflow-hidden shadow-lg cursor-pointer',
+                  COVER_SIZES[coverSize]
+                )}
+                onClick={nextVariant}
+                role="button"
+                tabIndex={0}
+                onKeyDown={(e) => e.key === 'Enter' && nextVariant()}
+              >
+                {renderCoverContent()}
+              </div>
+            )}
+
+            {/* Effect indicator */}
+            {reactiveCover && (
+              <span className="text-[10px] uppercase tracking-wider text-muted-foreground/50 select-none">
+                {vizSettings.variant === 'none' ? 'off' : vizSettings.variant}
+              </span>
+            )}
+          </div>
+        )}
+
+        {/* Track Info + Player */}
+        <div
+          className={cn('flex flex-col gap-3', isHorizontal ? 'flex-1 min-w-0' : 'w-full max-w-md')}
+        >
+          {/* Track Info */}
+          {(title || artist) && (
+            <div className={cn('text-center', isHorizontal && 'text-left')}>
+              {title && (
+                <h3 className="text-base font-medium text-foreground truncate">{title}</h3>
+              )}
+              {artist && <p className="text-sm text-muted-foreground truncate">{artist}</p>}
+            </div>
+          )}
+
+          {/* Audio Player */}
+          <HybridAudioPlayer
+            showControls
+            showWaveform={showWaveform}
+            waveformMode={waveformMode}
+            waveformHeight={waveformHeight}
+            showEqualizer={showEqualizer}
+            showTimer={showTimer}
+            showVolume={showVolume}
+            showLoop={showLoop}
+            equalizerOptions={equalizerOptions}
+            className="border-0 bg-transparent"
+          />
+        </div>
+      </div>
+    </HybridAudioProvider>
+  );
+}
+
+export default HybridSimplePlayer;