@djangocfg/ui-nextjs 2.1.65 → 2.1.67

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); }
+  }
+`;

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

@@ -0,0 +1,29 @@
+/**
+ * AudioPlayer hooks - re-exports all hooks
+ */
+
+// Internal hooks (used by provider)
+export { useSharedWebAudio } from './useSharedWebAudio';
+export { useAudioAnalysis } from './useAudioAnalysis';
+
+// Public hooks
+export { useAudioHotkeys, AUDIO_SHORTCUTS } from './useAudioHotkeys';
+export type { AudioHotkeyOptions, ShortcutItem, ShortcutGroup } from './useAudioHotkeys';
+
+export {
+  useVisualization,
+  useAudioVisualization, // backward compat alias
+  VisualizationProvider,
+  VARIANT_INFO,
+  INTENSITY_INFO,
+  COLOR_SCHEME_INFO,
+} from './useVisualization';
+export type {
+  VisualizationSettings,
+  VisualizationVariant,
+  VisualizationIntensity,
+  VisualizationColorScheme,
+  UseVisualizationReturn,
+  UseAudioVisualizationReturn,
+  VisualizationProviderProps,
+} from './useVisualization';

package/src/tools/AudioPlayer/hooks/useAudioAnalysis.ts

@@ -0,0 +1,110 @@
+'use client';
+
+/**
+ * useAudioAnalysis - Real-time audio frequency analysis for reactive effects.
+ *
+ * Analyzes audio frequencies for bass, mid, high, and overall levels.
+ * Uses shared Web Audio context to prevent duplicate source nodes.
+ */
+
+import { useState, useRef, useEffect, useCallback } from 'react';
+import type { SharedWebAudioContext } from '../types';
+import type { AudioLevels } from '../effects';
+
+export function useAudioAnalysis(
+  sharedAudio: SharedWebAudioContext,
+  isPlaying: boolean
+): AudioLevels {
+  const [levels, setLevels] = useState<AudioLevels>({ bass: 0, mid: 0, high: 0, overall: 0 });
+  const analyserRef = useRef<AnalyserNode | null>(null);
+  const animationRef = useRef<number | null>(null);
+  const dataArrayRef = useRef<Uint8Array | null>(null);
+
+  const cleanup = useCallback(() => {
+    if (animationRef.current) {
+      cancelAnimationFrame(animationRef.current);
+      animationRef.current = null;
+    }
+  }, []);
+
+  // Create analyser when shared audio is ready
+  useEffect(() => {
+    if (!sharedAudio.sourceNode || analyserRef.current) return;
+
+    const analyser = sharedAudio.createAnalyser({ fftSize: 256, smoothing: 0.85 });
+    if (analyser) {
+      analyserRef.current = analyser;
+      dataArrayRef.current = new Uint8Array(analyser.frequencyBinCount);
+    }
+
+    return () => {
+      if (analyserRef.current) {
+        sharedAudio.disconnectAnalyser(analyserRef.current);
+        analyserRef.current = null;
+        dataArrayRef.current = null;
+      }
+    };
+  }, [sharedAudio.sourceNode, sharedAudio.createAnalyser, sharedAudio.disconnectAnalyser]);
+
+  // Animation loop
+  useEffect(() => {
+    if (!isPlaying || !analyserRef.current || !dataArrayRef.current) {
+      cleanup();
+      // Smooth fade out
+      setLevels(prev => ({
+        bass: prev.bass * 0.95 < 0.01 ? 0 : prev.bass * 0.95,
+        mid: prev.mid * 0.95,
+        high: prev.high * 0.95,
+        overall: prev.overall * 0.95,
+      }));
+      return;
+    }
+
+    const analyser = analyserRef.current;
+    const dataArray = dataArrayRef.current;
+
+    const animate = () => {
+      analyser.getByteFrequencyData(dataArray as Uint8Array<ArrayBuffer>);
+      const binCount = dataArray.length;
+
+      // Bass (0-15%)
+      const bassEnd = Math.floor(binCount * 0.15);
+      let bassSum = 0;
+      for (let i = 0; i < bassEnd; i++) bassSum += dataArray[i];
+      const bass = bassSum / bassEnd / 255;
+
+      // Mids (15-50%)
+      const midStart = bassEnd;
+      const midEnd = Math.floor(binCount * 0.5);
+      let midSum = 0;
+      for (let i = midStart; i < midEnd; i++) midSum += dataArray[i];
+      const mid = midSum / (midEnd - midStart) / 255;
+
+      // Highs (50-100%)
+      const highStart = midEnd;
+      let highSum = 0;
+      for (let i = highStart; i < binCount; i++) highSum += dataArray[i];
+      const high = highSum / (binCount - highStart) / 255;
+
+      // Overall
+      let totalSum = 0;
+      for (let i = 0; i < binCount; i++) totalSum += dataArray[i];
+      const overall = totalSum / binCount / 255;
+
+      // Smooth with lerp
+      setLevels(prev => ({
+        bass: prev.bass * 0.7 + bass * 0.3,
+        mid: prev.mid * 0.7 + mid * 0.3,
+        high: prev.high * 0.7 + high * 0.3,
+        overall: prev.overall * 0.7 + overall * 0.3,
+      }));
+
+      animationRef.current = requestAnimationFrame(animate);
+    };
+
+    animationRef.current = requestAnimationFrame(animate);
+    return cleanup;
+  }, [isPlaying, cleanup]);
+
+  return levels;
+}

package/src/tools/AudioPlayer/hooks/useAudioHotkeys.ts

@@ -0,0 +1,149 @@
+'use client';
+
+/**
+ * useAudioHotkeys - Keyboard shortcuts for audio playback control.
+ *
+ * Uses useHotkey from @djangocfg/ui-nextjs.
+ */
+
+import { useHotkey, useDeviceDetect } from '@djangocfg/ui-nextjs';
+import { useAudioControls, useAudioState } from '../context';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface AudioHotkeyOptions {
+  /** Enable hotkeys (default: true) */
+  enabled?: boolean;
+  /** Skip duration in seconds (default: 10) */
+  skipDuration?: number;
+  /** Volume step (default: 0.1) */
+  volumeStep?: number;
+}
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function useAudioHotkeys(options: AudioHotkeyOptions = {}) {
+  const { enabled = true, skipDuration = 10, volumeStep = 0.1 } = options;
+
+  const { togglePlay, skip, setVolume, toggleMute, toggleLoop, isReady } = useAudioControls();
+  const { volume, duration } = useAudioState();
+  const device = useDeviceDetect();
+
+  // Play/Pause - Space
+  useHotkey(
+    'space',
+    (e) => {
+      e.preventDefault();
+      togglePlay();
+    },
+    { enabled: enabled && isReady, description: 'Play/Pause' }
+  );
+
+  // Skip backward - ArrowLeft or J
+  useHotkey(
+    ['ArrowLeft', 'j'],
+    () => skip(-skipDuration),
+    { enabled: enabled && isReady, description: `Skip ${skipDuration}s backward` }
+  );
+
+  // Skip forward - ArrowRight or L
+  useHotkey(
+    ['ArrowRight', 'l'],
+    () => skip(skipDuration),
+    { enabled: enabled && isReady, description: `Skip ${skipDuration}s forward` }
+  );
+
+  // Volume up - ArrowUp
+  useHotkey(
+    'ArrowUp',
+    (e) => {
+      e.preventDefault();
+      setVolume(Math.min(1, volume + volumeStep));
+    },
+    { enabled: enabled && isReady, description: 'Volume up' }
+  );
+
+  // Volume down - ArrowDown
+  useHotkey(
+    'ArrowDown',
+    (e) => {
+      e.preventDefault();
+      setVolume(Math.max(0, volume - volumeStep));
+    },
+    { enabled: enabled && isReady, description: 'Volume down' }
+  );
+
+  // Mute/Unmute - M
+  useHotkey(
+    'm',
+    () => toggleMute(),
+    { enabled: enabled && isReady, description: 'Mute/Unmute' }
+  );
+
+  // Loop/Repeat - L key (conflicts with skip forward, using Shift+L)
+  useHotkey(
+    'shift+l',
+    () => toggleLoop(),
+    { enabled: enabled && isReady, description: 'Toggle loop' }
+  );
+
+  // Number keys 0-9 to seek to percentage
+  useHotkey(
+    ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'],
+    (e) => {
+      if (!duration) return;
+      const percent = parseInt(e.key, 10) / 10;
+      skip(duration * percent - duration * (volume || 0));
+    },
+    { enabled: enabled && isReady, description: 'Seek to percentage' }
+  );
+
+  return {
+    isMac: device.isMacOs,
+    isEnabled: enabled && isReady,
+  };
+}
+
+// =============================================================================
+// SHORTCUTS CONFIG (for display)
+// =============================================================================
+
+export interface ShortcutItem {
+  keys: string[];
+  label: string;
+}
+
+export interface ShortcutGroup {
+  title: string;
+  shortcuts: ShortcutItem[];
+}
+
+export const AUDIO_SHORTCUTS: ShortcutGroup[] = [
+  {
+    title: 'Playback',
+    shortcuts: [
+      { keys: ['Space'], label: 'Play/Pause' },
+      { keys: ['←'], label: 'Skip 10s back' },
+      { keys: ['→'], label: 'Skip 10s forward' },
+      { keys: ['⇧', 'L'], label: 'Toggle loop' },
+    ],
+  },
+  {
+    title: 'Volume',
+    shortcuts: [
+      { keys: ['↑'], label: 'Volume up' },
+      { keys: ['↓'], label: 'Volume down' },
+      { keys: ['M'], label: 'Mute/Unmute' },
+    ],
+  },
+  {
+    title: 'Seek',
+    shortcuts: [
+      { keys: ['0-9'], label: 'Jump to 0-90%' },
+    ],
+  },
+];