@djangocfg/ui-tools 2.1.91

package/src/tools/AudioPlayer/components/ReactiveCover/effects/SpotlightEffect.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+/**
+ * SpotlightEffect - Rotating spotlight with conic gradients
+ */
+
+import { cn } from '../../../../_shared';
+import type { calculateSpotlight } from '../../../effects';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface SpotlightEffectProps {
+  data: ReturnType<typeof calculateSpotlight>;
+  colors: string[];
+  blur: string;
+  isPlaying: boolean;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function SpotlightEffect({ data, colors, blur, isPlaying }: SpotlightEffectProps) {
+  const inset = 'inset' in data ? data.inset : 12;
+  const pulseInset = 'pulseInset' in data ? data.pulseInset : 24;
+  const ringOpacity = 'ringOpacity' in data ? data.ringOpacity : 0.3;
+  const ringScale = 'ringScale' in data ? data.ringScale : 1;
+
+  return (
+    <>
+      {/* Rotating conic gradient - reactive size */}
+      <div
+        className={cn('absolute rounded-xl -z-10', blur)}
+        style={{
+          inset: `-${inset}px`,
+          background: `conic-gradient(
+            from ${data.rotation}deg,
+            hsl(${colors[0]} / ${data.colors[0]?.opacity || 0.5}),
+            hsl(${colors[1] || colors[0]} / ${data.colors[1]?.opacity || 0.7}),
+            hsl(${colors[2] || colors[0]} / ${data.colors[2]?.opacity || 0.5}),
+            hsl(${colors[0]} / ${data.colors[1]?.opacity || 0.7}),
+            hsl(${colors[0]} / ${data.colors[0]?.opacity || 0.5})
+          )`,
+          opacity: isPlaying ? 1 : 0,
+          transition: 'all 0.08s ease-out',
+        }}
+      />
+
+      {/* Inner border */}
+      <div
+        className="absolute -inset-1 rounded-lg bg-background -z-10"
+        style={{ opacity: isPlaying ? 1 : 0, transition: 'opacity 0.1s' }}
+      />
+
+      {/* Bass pulse glow - reactive size */}
+      <div
+        className={cn('absolute rounded-2xl -z-10', blur)}
+        style={{
+          inset: `-${pulseInset}px`,
+          background: `radial-gradient(circle, hsl(${colors[0]} / 0.7) 0%, hsl(${colors[0]} / 0.3) 50%, transparent 70%)`,
+          opacity: isPlaying ? data.pulseOpacity : 0,
+          transform: `scale(${data.pulseScale})`,
+          transition: 'all 0.08s ease-out',
+        }}
+      />
+
+      {/* Outer ring glow */}
+      <div
+        className="absolute rounded-3xl -z-10 blur-2xl"
+        style={{
+          inset: `-${pulseInset + 30}px`,
+          background: `radial-gradient(circle, hsl(${colors[1] || colors[0]} / 0.4) 0%, transparent 60%)`,
+          opacity: isPlaying ? ringOpacity : 0,
+          transform: `scale(${ringScale})`,
+          transition: 'all 0.08s ease-out',
+        }}
+      />
+    </>
+  );
+}

package/src/tools/AudioPlayer/components/ReactiveCover/effects/index.ts

@@ -0,0 +1,8 @@
+/**
+ * ReactiveCover effects - Audio-reactive visual effects
+ */
+
+export { GlowEffect, type GlowEffectData } from './GlowEffect';
+export { OrbsEffect } from './OrbsEffect';
+export { SpotlightEffect } from './SpotlightEffect';
+export { MeshEffect } from './MeshEffect';

package/src/tools/AudioPlayer/components/ReactiveCover/index.ts

@@ -0,0 +1,6 @@
+/**
+ * ReactiveCover - Audio-reactive cover art component
+ */
+
+export { AudioReactiveCover, type AudioReactiveCoverProps } from './AudioReactiveCover';
+export { GlowEffect, OrbsEffect, SpotlightEffect, MeshEffect, type GlowEffectData } from './effects';

package/src/tools/AudioPlayer/components/index.ts

@@ -0,0 +1,22 @@
+/**
+ * AudioPlayer components - Public API
+ *
+ * Uses HTML5 audio for playback + Web Audio API for visualization.
+ * No crackling, native streaming support.
+ */
+
+// Player components
+export { HybridAudioPlayer, type HybridAudioPlayerProps } from './HybridAudioPlayer';
+export { HybridSimplePlayer, type HybridSimplePlayerProps } from './HybridSimplePlayer';
+export { HybridWaveform, type HybridWaveformProps } from './HybridWaveform';
+
+// ReactiveCover
+export {
+  AudioReactiveCover,
+  type AudioReactiveCoverProps,
+  GlowEffect,
+  OrbsEffect,
+  SpotlightEffect,
+  MeshEffect,
+  type GlowEffectData,
+} from './ReactiveCover';

package/src/tools/AudioPlayer/context/HybridAudioProvider.tsx

@@ -0,0 +1,158 @@
+'use client';
+
+/**
+ * HybridAudioProvider - Context provider for hybrid audio player.
+ *
+ * Provides audio state, controls, and analysis data to child components.
+ * Uses native HTML5 audio for playback with Web Audio API for visualization only.
+ */
+
+import { createContext, useContext, useMemo, useEffect, useRef, type ReactNode } from 'react';
+import {
+  useHybridAudio,
+  type UseHybridAudioOptions,
+  type HybridAudioState,
+  type HybridAudioControls,
+  type HybridWebAudioAPI,
+} from '../hooks/useHybridAudio';
+import { useHybridAudioAnalysis } from '../hooks/useHybridAudioAnalysis';
+import { useVisualization } from '../hooks/useVisualization';
+import type { AudioLevels } from '../effects';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface HybridAudioContextValue {
+  // Audio state
+  state: HybridAudioState;
+
+  // Controls
+  controls: HybridAudioControls;
+
+  // Web Audio (for visualizations)
+  webAudio: HybridWebAudioAPI;
+
+  // Audio levels (for reactive effects)
+  audioLevels: AudioLevels;
+
+  // Audio element ref (for custom integrations)
+  audioRef: React.RefObject<HTMLAudioElement | null>;
+}
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+const HybridAudioContext = createContext<HybridAudioContextValue | null>(null);
+
+// =============================================================================
+// PROVIDER
+// =============================================================================
+
+export interface HybridAudioProviderProps extends UseHybridAudioOptions {
+  children: ReactNode;
+}
+
+export function HybridAudioProvider({ children, ...options }: HybridAudioProviderProps) {
+  // Load persisted settings (shared with visualization)
+  const { settings: savedSettings, setSetting } = useVisualization();
+
+  // Use saved settings as initial values
+  const effectiveOptions = {
+    ...options,
+    initialVolume: savedSettings.volume,
+    loop: savedSettings.isLooping,
+  };
+
+  const { audioRef, state, controls, webAudio } = useHybridAudio(effectiveOptions);
+
+  // Track if we've applied initial settings
+  const hasAppliedInitialSettings = useRef(false);
+
+  // Apply saved settings after audio is ready (for hydration timing)
+  useEffect(() => {
+    if (!state.isReady || hasAppliedInitialSettings.current) return;
+    hasAppliedInitialSettings.current = true;
+
+    // Apply saved volume and loop settings
+    controls.setVolume(savedSettings.volume);
+    controls.setLoop(savedSettings.isLooping);
+  }, [state.isReady, savedSettings, controls]);
+
+  // Persist settings when they change
+  useEffect(() => {
+    if (!state.isReady) return;
+
+    // Only save if values actually changed
+    if (state.volume !== savedSettings.volume) {
+      setSetting('volume', state.volume);
+    }
+    if (state.isLooping !== savedSettings.isLooping) {
+      setSetting('isLooping', state.isLooping);
+    }
+  }, [state.isReady, state.volume, state.isLooping, savedSettings, setSetting]);
+
+  // Audio analysis for reactive effects
+  const audioLevels = useHybridAudioAnalysis(webAudio.analyser, state.isPlaying);
+
+  const value = useMemo<HybridAudioContextValue>(
+    () => ({
+      state,
+      controls,
+      webAudio,
+      audioLevels,
+      audioRef,
+    }),
+    [state, controls, webAudio, audioLevels, audioRef]
+  );
+
+  return <HybridAudioContext.Provider value={value}>{children}</HybridAudioContext.Provider>;
+}
+
+// =============================================================================
+// HOOKS
+// =============================================================================
+
+/**
+ * Access full hybrid audio context
+ */
+export function useHybridAudioContext(): HybridAudioContextValue {
+  const context = useContext(HybridAudioContext);
+  if (!context) {
+    throw new Error('useHybridAudioContext must be used within HybridAudioProvider');
+  }
+  return context;
+}
+
+/**
+ * Access audio state only (read-only)
+ */
+export function useHybridAudioState(): HybridAudioState {
+  const { state } = useHybridAudioContext();
+  return state;
+}
+
+/**
+ * Access audio controls only (no state re-renders)
+ */
+export function useHybridAudioControls(): HybridAudioControls {
+  const { controls } = useHybridAudioContext();
+  return controls;
+}
+
+/**
+ * Access audio levels for reactive effects
+ */
+export function useHybridAudioLevels(): AudioLevels {
+  const { audioLevels } = useHybridAudioContext();
+  return audioLevels;
+}
+
+/**
+ * Access Web Audio API for custom visualizations
+ */
+export function useHybridWebAudio(): HybridWebAudioAPI {
+  const { webAudio } = useHybridAudioContext();
+  return webAudio;
+}

package/src/tools/AudioPlayer/context/index.ts

@@ -0,0 +1,16 @@
+/**
+ * AudioPlayer context - Public API
+ *
+ * HybridAudioProvider: HTML5 audio + Web Audio API for visualization
+ */
+
+export {
+  HybridAudioProvider,
+  useHybridAudioContext,
+  useHybridAudioState,
+  useHybridAudioControls,
+  useHybridAudioLevels,
+  useHybridWebAudio,
+  type HybridAudioContextValue,
+  type HybridAudioProviderProps,
+} from './HybridAudioProvider';

package/src/tools/AudioPlayer/effects/index.ts

@@ -0,0 +1,412 @@
+/**
+ * Audio Reactive Effects - Common utilities and types
+ *
+ * Provides reusable effect calculations and configurations
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type EffectVariant = 'glow' | 'orbs' | 'spotlight' | 'mesh';
+export type EffectIntensity = 'subtle' | 'medium' | 'strong';
+export type EffectColorScheme = 'primary' | 'vibrant' | 'cool' | 'warm';
+
+export interface AudioLevels {
+  bass: number;
+  mid: number;
+  high: number;
+  overall: number;
+}
+
+export interface EffectConfig {
+  opacity: number;
+  scale: number;
+  blur: string;
+}
+
+export interface EffectColors {
+  colors: string[];
+  hueShift: number;
+}
+
+export interface EffectLayer {
+  inset: number;
+  opacity: number;
+  scale: number;
+  background: string;
+  blur: string;
+  animation?: string;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+export const INTENSITY_CONFIG: Record<EffectIntensity, EffectConfig> = {
+  subtle: { opacity: 0.3, scale: 0.02, blur: 'blur-2xl' },
+  medium: { opacity: 0.5, scale: 0.04, blur: 'blur-xl' },
+  strong: { opacity: 0.7, scale: 0.06, blur: 'blur-lg' },
+};
+
+export const COLOR_SCHEMES: Record<EffectColorScheme, string[]> = {
+  primary: ['217 91% 60%'],
+  vibrant: ['217 91% 60%', '142 76% 36%', '262 83% 58%', '25 95% 53%'],
+  cool: ['217 91% 60%', '262 83% 58%', '199 89% 48%'],
+  warm: ['25 95% 53%', '0 84% 60%', '38 92% 50%'],
+};
+
+// Default multi-color palette when single color provided
+const DEFAULT_GLOW_COLORS = [
+  '217 91% 60%',  // Blue
+  '262 83% 58%',  // Purple
+  '330 81% 60%',  // Pink
+  '25 95% 53%',   // Orange
+];
+
+// =============================================================================
+// UTILITIES
+// =============================================================================
+
+/**
+ * Get effect configuration from intensity setting
+ */
+export function getEffectConfig(intensity: EffectIntensity): EffectConfig {
+  return INTENSITY_CONFIG[intensity];
+}
+
+/**
+ * Get color array from color scheme
+ */
+export function getColors(colorScheme: EffectColorScheme): string[] {
+  return COLOR_SCHEMES[colorScheme];
+}
+
+/**
+ * Prepare colors with hue shift based on audio levels
+ */
+export function prepareEffectColors(
+  colorScheme: EffectColorScheme,
+  levels: AudioLevels
+): EffectColors {
+  const baseColors = COLOR_SCHEMES[colorScheme];
+  const colors = baseColors.length > 1 ? baseColors : DEFAULT_GLOW_COLORS;
+  const hueShift = Math.floor(
+    (levels.bass * 30) + (levels.mid * 20) + (levels.high * 10)
+  );
+
+  return { colors, hueShift };
+}
+
+/**
+ * Calculate glow layer properties
+ */
+export function calculateGlowLayers(
+  levels: AudioLevels,
+  config: EffectConfig,
+  colors: string[]
+): EffectLayer[] {
+  const { bass, mid, high } = levels;
+
+  return [
+    // Layer 1: Bass glow - bottom
+    {
+      inset: 60 + bass * 90,
+      opacity: 1,
+      scale: 1 + bass * 0.5,
+      background: `radial-gradient(ellipse 80% 60% at 50% 100%, hsl(${colors[0]} / ${0.4 + bass * 0.4}) 0%, transparent 70%)`,
+      blur: 'blur-3xl',
+    },
+    // Layer 2: Mid glow - top
+    {
+      inset: 45 + mid * 75,
+      opacity: 1,
+      scale: 1 + mid * 0.4,
+      background: `radial-gradient(ellipse 70% 50% at 50% 0%, hsl(${colors[1] || colors[0]} / ${0.3 + mid * 0.5}) 0%, transparent 70%)`,
+      blur: 'blur-2xl',
+    },
+    // Layer 3: High glow - left
+    {
+      inset: 30 + high * 60,
+      opacity: 1,
+      scale: 1 + high * 0.3,
+      background: `radial-gradient(ellipse 50% 80% at 0% 50%, hsl(${colors[2] || colors[0]} / ${0.3 + high * 0.4}) 0%, transparent 60%)`,
+      blur: 'blur-2xl',
+    },
+    // Layer 4: High glow - right
+    {
+      inset: 30 + high * 60,
+      opacity: 1,
+      scale: 1 + high * 0.3,
+      background: `radial-gradient(ellipse 50% 80% at 100% 50%, hsl(${colors[3] || colors[0]} / ${0.3 + high * 0.4}) 0%, transparent 60%)`,
+      blur: 'blur-2xl',
+    },
+    // Layer 5: Center pulsing glow
+    {
+      inset: 24 + bass * 45,
+      opacity: 1,
+      scale: 1 + bass * 0.2,
+      background: `radial-gradient(circle at 50% 50%, hsl(${colors[0]} / ${0.2 + bass * 0.3}) 0%, hsl(${colors[1] || colors[0]} / ${0.1 + mid * 0.2}) 40%, transparent 70%)`,
+      blur: 'blur-xl',
+      animation: 'glow-breathe 2s ease-in-out infinite',
+    },
+  ];
+}
+
+/**
+ * Calculate orb positions and properties - highly reactive
+ */
+export function calculateOrbs(
+  levels: AudioLevels,
+  config: EffectConfig,
+  colors: string[],
+  baseSize: number = 50
+) {
+  const { bass, mid, high, overall } = levels;
+  const size = baseSize * 3;
+
+  // Dynamic position offsets
+  const bassMove = bass * 30;
+  const midMove = mid * 25;
+  const highMove = high * 20;
+
+  return [
+    // Bass orb - top left, big pulses
+    {
+      x: -40 + bassMove,
+      y: -40 - bassMove * 0.5,
+      size: size * (1 + bass * 1.2),
+      color: colors[0],
+      opacity: 0.5 + bass * 0.5,
+      scale: 1 + bass * 0.6,
+    },
+    // Mid orb - top right
+    {
+      x: 130 - midMove * 0.5,
+      y: -30 + midMove,
+      size: size * (0.9 + mid * 1.0),
+      color: colors[1] || colors[0],
+      opacity: 0.5 + mid * 0.5,
+      scale: 1 + mid * 0.5,
+    },
+    // High orb - bottom right
+    {
+      x: 140 + highMove * 0.3,
+      y: 120 - highMove,
+      size: size * (0.8 + high * 0.8),
+      color: colors[2] || colors[0],
+      opacity: 0.4 + high * 0.6,
+      scale: 1 + high * 0.45,
+    },
+    // Mid orb 2 - bottom left
+    {
+      x: -30 - midMove * 0.4,
+      y: 130 + midMove * 0.3,
+      size: size * (0.9 + mid * 0.9),
+      color: colors[3] || colors[0],
+      opacity: 0.45 + mid * 0.55,
+      scale: 1 + mid * 0.5,
+    },
+    // Center overall orb
+    {
+      x: 50,
+      y: 50,
+      size: size * (0.6 + overall * 1.5),
+      color: colors[0],
+      opacity: 0.3 + overall * 0.5,
+      scale: 1 + overall * 0.7,
+    },
+  ];
+}
+
+/**
+ * Calculate mesh gradient positions - dynamic and reactive
+ */
+export function calculateMeshGradients(
+  levels: AudioLevels,
+  config: EffectConfig,
+  colors: string[]
+) {
+  const { bass, mid, high, overall } = levels;
+
+  // More aggressive offsets for visible movement
+  const bassOffset = bass * 40;
+  const midOffset = mid * 30;
+  const highOffset = high * 25;
+
+  return [
+    // Large bass blob - top right, pulses hard
+    {
+      width: `${200 + bass * 150}%`,
+      height: `${200 + bass * 150}%`,
+      top: `${-80 + bassOffset}%`,
+      right: `${-80 - bassOffset}%`,
+      color: colors[0],
+      opacity: 0.4 + bass * 0.6,
+      scale: 1 + bass * 0.5,
+      rotation: bass * 45,
+      blur: 'blur-2xl',
+    },
+    // Mid blob - bottom left
+    {
+      width: `${180 + mid * 120}%`,
+      height: `${180 + mid * 120}%`,
+      bottom: `${-60 + midOffset}%`,
+      left: `${-60 - midOffset}%`,
+      color: colors[1] || colors[0],
+      opacity: 0.4 + mid * 0.6,
+      scale: 1 + mid * 0.4,
+      rotation: -mid * 40,
+      blur: 'blur-2xl',
+    },
+    // High blob - bottom right
+    {
+      width: `${140 + high * 100}%`,
+      height: `${140 + high * 100}%`,
+      top: `${70 - highOffset}%`,
+      right: `${-50 + highOffset}%`,
+      color: colors[2] || colors[0],
+      opacity: 0.35 + high * 0.65,
+      scale: 1 + high * 0.35,
+      rotation: high * 35,
+      blur: 'blur-xl',
+    },
+    // Extra bass reactive blob - top left
+    {
+      width: `${160 + bass * 140}%`,
+      height: `${160 + bass * 140}%`,
+      top: `${-60 - bassOffset * 0.8}%`,
+      left: `${-60 + bassOffset * 0.8}%`,
+      color: colors[3] || colors[1] || colors[0],
+      opacity: 0.35 + bass * 0.65,
+      scale: 1 + bass * 0.55,
+      rotation: -bass * 50,
+      blur: 'blur-2xl',
+    },
+    // Center glow - pulses with overall
+    {
+      width: `${80 + overall * 150}%`,
+      height: `${80 + overall * 150}%`,
+      top: '50%',
+      left: '50%',
+      color: colors[0],
+      opacity: 0.3 + overall * 0.5,
+      scale: 1 + overall * 0.4,
+      rotation: 0,
+      isCenter: true,
+      blur: 'blur-3xl',
+    },
+  ];
+}
+
+/**
+ * Calculate spotlight effect properties - highly reactive
+ */
+export function calculateSpotlight(
+  levels: AudioLevels,
+  config: EffectConfig,
+  colors: string[],
+  rotation: number
+) {
+  const { bass, mid, high, overall } = levels;
+
+  return {
+    // Rotation speed increases with mid frequencies
+    rotation: rotation + mid * 180,
+    // Border expands with bass
+    inset: 12 + bass * 30,
+    // Color intensities react to different frequencies
+    colors: colors.map((c, i) => ({
+      color: c,
+      opacity: i === 0
+        ? 0.3 + bass * 0.7
+        : i === 1
+        ? 0.3 + mid * 0.7
+        : 0.3 + high * 0.7,
+    })),
+    // Pulse glow - big and reactive
+    pulseInset: 24 + bass * 50,
+    pulseOpacity: 0.3 + bass * 0.7,
+    pulseScale: 1 + bass * 0.4,
+    // Extra glow ring
+    ringOpacity: 0.2 + overall * 0.6,
+    ringScale: 1 + overall * 0.3,
+  };
+}
+
+/**
+ * CSS for effect animations - can be injected once
+ */
+export const EFFECT_ANIMATIONS = `
+  @keyframes spotlight-spin {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+  }
+
+  @keyframes orb-float-1 {
+    0%, 100% { transform: translate(-50%, -50%) translateY(0); }
+    50% { transform: translate(-50%, -50%) translateY(-15px); }
+  }
+
+  @keyframes orb-float-2 {
+    0%, 100% { transform: translate(-50%, -50%) translateX(0); }
+    50% { transform: translate(-50%, -50%) translateX(15px); }
+  }
+
+  @keyframes orb-float-3 {
+    0%, 100% { transform: translate(-50%, -50%) translate(0, 0); }
+    33% { transform: translate(-50%, -50%) translate(10px, -10px); }
+    66% { transform: translate(-50%, -50%) translate(-10px, 10px); }
+  }
+
+  @keyframes orb-float-4 {
+    0%, 100% { transform: translate(-50%, -50%) translate(0, 0); }
+    50% { transform: translate(-50%, -50%) translate(-15px, -10px); }
+  }
+
+  @keyframes mesh-float-1 {
+    0%, 100% { transform: translate(0, 0) scale(1); }
+    25% { transform: translate(-5%, 10%) scale(1.05); }
+    50% { transform: translate(5%, 5%) scale(0.95); }
+    75% { transform: translate(-3%, -5%) scale(1.02); }
+  }
+
+  @keyframes mesh-float-2 {
+    0%, 100% { transform: translate(0, 0) scale(1); }
+    33% { transform: translate(8%, -8%) scale(1.08); }
+    66% { transform: translate(-6%, 6%) scale(0.92); }
+  }
+
+  @keyframes mesh-float-3 {
+    0%, 100% { transform: translate(0, 0) scale(1); }
+    50% { transform: translate(10%, 10%) scale(1.1); }
+  }
+
+  @keyframes mesh-float-4 {
+    0%, 100% { transform: translate(0, 0) scale(1) rotate(0deg); }
+    25% { transform: translate(10%, -5%) scale(1.1) rotate(5deg); }
+    50% { transform: translate(-5%, 10%) scale(0.95) rotate(-5deg); }
+    75% { transform: translate(-10%, -10%) scale(1.05) rotate(3deg); }
+  }
+
+  @keyframes mesh-pulse {
+    0%, 100% { transform: translate(-50%, -50%) scale(1); opacity: 0.3; }
+    50% { transform: translate(-50%, -50%) scale(1.2); opacity: 0.5; }
+  }
+
+  @keyframes glow-breathe {
+    0%, 100% { opacity: 0.6; transform: scale(1); }
+    50% { opacity: 1; transform: scale(1.05); }
+  }
+
+  @keyframes glow-rotate {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+  }
+
+  @keyframes sparkle-move {
+    0% { opacity: 0; transform: scale(0.8); }
+    50% { opacity: 1; }
+    100% { opacity: 0; transform: scale(1.2); }
+  }
+`;