feat: complete Phase 10.3 - master metering with peak/RMS display

Added comprehensive master output level monitoring: - Created MasterMeter component with dual vertical bars (peak + RMS) - Implemented real-time level monitoring in useMultiTrackPlayer hook - Added master analyser node connected to audio output - Displays color-coded levels (green/yellow/red) based on dB thresholds - Shows numerical dB readouts for both peak and RMS - Includes clickable clip indicator with reset functionality - Integrated into PlaybackControls next to master volume 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 23:56:53 +01:00
parent c54d5089c5
commit c33a77270b
4 changed files with 250 additions and 26 deletions
--- a/components/controls/MasterMeter.tsx
+++ b/components/controls/MasterMeter.tsx
@@ -0,0 +1,120 @@
+'use client';
+
+import * as React from 'react';
+
+export interface MasterMeterProps {
+  /** Peak level (0-1) */
+  peakLevel: number;
+  /** RMS level (0-1) */
+  rmsLevel: number;
+  /** Whether clipping has occurred */
+  isClipping: boolean;
+  /** Callback to reset clip indicator */
+  onResetClip?: () => void;
+}
+
+export function MasterMeter({
+  peakLevel,
+  rmsLevel,
+  isClipping,
+  onResetClip,
+}: MasterMeterProps) {
+  // Convert linear 0-1 to dB scale for display
+  const linearToDb = (linear: number): number => {
+    if (linear === 0) return -60;
+    const db = 20 * Math.log10(linear);
+    return Math.max(-60, Math.min(0, db));
+  };
+
+  const peakDb = linearToDb(peakLevel);
+  const rmsDb = linearToDb(rmsLevel);
+
+  // Calculate bar heights (0-100%)
+  const peakHeight = ((peakDb + 60) / 60) * 100;
+  const rmsHeight = ((rmsDb + 60) / 60) * 100;
+
+  return (
+    <div className="flex items-center gap-2 px-3 py-2 bg-muted/30 rounded-md border border-border/50">
+      {/* Clip Indicator */}
+      <button
+        onClick={onResetClip}
+        className={`w-6 h-6 rounded-sm border transition-colors ${
+          isClipping
+            ? 'bg-red-500 border-red-600 shadow-lg shadow-red-500/50'
+            : 'bg-muted border-border/50'
+        }`}
+        title={isClipping ? 'Click to reset clip indicator' : 'No clipping'}
+      >
+        <span className="text-[10px] font-bold text-white">C</span>
+      </button>
+
+      {/* Meters */}
+      <div className="flex gap-1">
+        {/* Peak Meter (Left) */}
+        <div className="w-6 h-24 bg-background/50 rounded-sm relative overflow-hidden border border-border/50">
+          <div className="absolute bottom-0 left-0 right-0 transition-all duration-75 ease-out"
+               style={{ height: `${Math.max(0, Math.min(100, peakHeight))}%` }}>
+            <div className={`w-full h-full ${
+              peakDb > -3 ? 'bg-red-500' :
+              peakDb > -6 ? 'bg-yellow-500' :
+              'bg-green-500'
+            }`} />
+          </div>
+          {/* dB markers */}
+          <div className="absolute inset-0 pointer-events-none">
+            <div className="absolute top-0 left-0 right-0 h-px bg-red-500/30" title="0 dB" />
+            <div className="absolute top-[5%] left-0 right-0 h-px bg-yellow-500/20" title="-3 dB" />
+            <div className="absolute top-[10%] left-0 right-0 h-px bg-border/20" title="-6 dB" />
+            <div className="absolute top-[25%] left-0 right-0 h-px bg-border/20" title="-12 dB" />
+            <div className="absolute top-[50%] left-0 right-0 h-px bg-border/20" title="-18 dB" />
+          </div>
+        </div>
+
+        {/* RMS Meter (Right) */}
+        <div className="w-6 h-24 bg-background/50 rounded-sm relative overflow-hidden border border-border/50">
+          <div className="absolute bottom-0 left-0 right-0 transition-all duration-150 ease-out"
+               style={{ height: `${Math.max(0, Math.min(100, rmsHeight))}%` }}>
+            <div className={`w-full h-full ${
+              rmsDb > -3 ? 'bg-red-400' :
+              rmsDb > -6 ? 'bg-yellow-400' :
+              'bg-green-400'
+            }`} />
+          </div>
+          {/* dB markers */}
+          <div className="absolute inset-0 pointer-events-none">
+            <div className="absolute top-0 left-0 right-0 h-px bg-red-500/30" />
+            <div className="absolute top-[5%] left-0 right-0 h-px bg-yellow-500/20" />
+            <div className="absolute top-[10%] left-0 right-0 h-px bg-border/20" />
+            <div className="absolute top-[25%] left-0 right-0 h-px bg-border/20" />
+            <div className="absolute top-[50%] left-0 right-0 h-px bg-border/20" />
+          </div>
+        </div>
+      </div>
+
+      {/* Labels and Values */}
+      <div className="flex flex-col text-[10px] font-mono">
+        <div className="flex items-center gap-1">
+          <span className="text-muted-foreground w-6">PK:</span>
+          <span className={`w-12 text-right ${
+            peakDb > -3 ? 'text-red-500' :
+            peakDb > -6 ? 'text-yellow-500' :
+            'text-green-500'
+          }`}>
+            {peakDb > -60 ? `${peakDb.toFixed(1)}` : '-∞'}
+          </span>
+        </div>
+        <div className="flex items-center gap-1">
+          <span className="text-muted-foreground w-6">RM:</span>
+          <span className={`w-12 text-right ${
+            rmsDb > -3 ? 'text-red-400' :
+            rmsDb > -6 ? 'text-yellow-400' :
+            'text-green-400'
+          }`}>
+            {rmsDb > -60 ? `${rmsDb.toFixed(1)}` : '-∞'}
+          </span>
+        </div>
+        <div className="text-muted-foreground text-center mt-0.5">dB</div>
+      </div>
+    </div>
+  );
+}
--- a/components/editor/AudioEditor.tsx
+++ b/components/editor/AudioEditor.tsx
@@ -219,6 +219,10 @@ export function AudioEditor() {
    currentTime,
    duration,
    trackLevels,
+    masterPeakLevel,
+    masterRmsLevel,
+    masterIsClipping,
+    resetClipIndicator,
    play,
    pause,
    stop,
@@ -1056,6 +1060,10 @@ export function AudioEditor() {
          onPunchOutTimeChange={setPunchOutTime}
          overdubEnabled={overdubEnabled}
          onOverdubEnabledChange={setOverdubEnabled}
+          masterPeakLevel={masterPeakLevel}
+          masterRmsLevel={masterRmsLevel}
+          masterIsClipping={masterIsClipping}
+          onResetClip={resetClipIndicator}
        />
      </div>

--- a/components/editor/PlaybackControls.tsx
+++ b/components/editor/PlaybackControls.tsx
@@ -4,6 +4,7 @@ import * as React from 'react';
 import { Play, Pause, Square, SkipBack, Volume2, VolumeX, Circle, AlignVerticalJustifyStart, AlignVerticalJustifyEnd, Layers } from 'lucide-react';
 import { Button } from '@/components/ui/Button';
 import { Slider } from '@/components/ui/Slider';
+import { MasterMeter } from '@/components/controls/MasterMeter';
 import { cn } from '@/lib/utils/cn';

 export interface PlaybackControlsProps {
@@ -32,6 +33,10 @@ export interface PlaybackControlsProps {
  onPunchOutTimeChange?: (time: number) => void;
  overdubEnabled?: boolean;
  onOverdubEnabledChange?: (enabled: boolean) => void;
+  masterPeakLevel?: number;
+  masterRmsLevel?: number;
+  masterIsClipping?: boolean;
+  onResetClip?: () => void;
 }

 export function PlaybackControls({
@@ -60,6 +65,10 @@ export function PlaybackControls({
  onPunchOutTimeChange,
  overdubEnabled = false,
  onOverdubEnabledChange,
+  masterPeakLevel = 0,
+  masterRmsLevel = 0,
+  masterIsClipping = false,
+  onResetClip,
 }: PlaybackControlsProps) {
  const [isMuted, setIsMuted] = React.useState(false);
  const [previousVolume, setPreviousVolume] = React.useState(volume);
@@ -275,6 +284,16 @@ export function PlaybackControls({
          )}
        </div>

+        {/* Volume Control & Master Meter */}
+        <div className="flex items-center gap-4">
+          {/* Master Meter */}
+          <MasterMeter
+            peakLevel={masterPeakLevel}
+            rmsLevel={masterRmsLevel}
+            isClipping={masterIsClipping}
+            onResetClip={onResetClip}
+          />
+
          {/* Volume Control */}
          <div className="flex items-center gap-3 min-w-[200px]">
            <Button
@@ -301,5 +320,6 @@ export function PlaybackControls({
          </div>
        </div>
      </div>
+    </div>
  );
 }
--- a/lib/hooks/useMultiTrackPlayer.ts
+++ b/lib/hooks/useMultiTrackPlayer.ts
@@ -29,6 +29,9 @@ export function useMultiTrackPlayer(
  const [currentTime, setCurrentTime] = useState(0);
  const [duration, setDuration] = useState(0);
  const [trackLevels, setTrackLevels] = useState<Record<string, number>>({});
+  const [masterPeakLevel, setMasterPeakLevel] = useState(0);
+  const [masterRmsLevel, setMasterRmsLevel] = useState(0);
+  const [masterIsClipping, setMasterIsClipping] = useState(false);

  const audioContextRef = useRef<AudioContext | null>(null);
  const sourceNodesRef = useRef<AudioBufferSourceNode[]>([]);
@@ -37,6 +40,8 @@ export function useMultiTrackPlayer(
  const analyserNodesRef = useRef<AnalyserNode[]>([]);
  const effectNodesRef = useRef<EffectNodeInfo[][]>([]); // Effect nodes per track
  const masterGainNodeRef = useRef<GainNode | null>(null);
+  const masterAnalyserRef = useRef<AnalyserNode | null>(null);
+  const masterLevelMonitorFrameRef = useRef<number | null>(null);
  const startTimeRef = useRef<number>(0);
  const pausedAtRef = useRef<number>(0);
  const animationFrameRef = useRef<number | null>(null);
@@ -116,6 +121,46 @@ export function useMultiTrackPlayer(
    levelMonitorFrameRef.current = requestAnimationFrame(monitorPlaybackLevels);
  }, []);

+  // Monitor master output levels (peak and RMS)
+  const monitorMasterLevels = useCallback(() => {
+    if (!masterAnalyserRef.current) {
+      return;
+    }
+
+    const analyser = masterAnalyserRef.current;
+    const bufferLength = analyser.fftSize;
+    const dataArray = new Float32Array(bufferLength);
+
+    analyser.getFloatTimeDomainData(dataArray);
+
+    // Calculate peak level (max absolute value)
+    let peak = 0;
+    for (let i = 0; i < bufferLength; i++) {
+      const abs = Math.abs(dataArray[i]);
+      if (abs > peak) {
+        peak = abs;
+      }
+    }
+
+    // Calculate RMS level (root mean square)
+    let sumSquares = 0;
+    for (let i = 0; i < bufferLength; i++) {
+      sumSquares += dataArray[i] * dataArray[i];
+    }
+    const rms = Math.sqrt(sumSquares / bufferLength);
+
+    // Detect clipping (signal >= 1.0)
+    const isClipping = peak >= 1.0;
+
+    setMasterPeakLevel(peak);
+    setMasterRmsLevel(rms);
+    if (isClipping) {
+      setMasterIsClipping(true);
+    }
+
+    masterLevelMonitorFrameRef.current = requestAnimationFrame(monitorMasterLevels);
+  }, []);
+
  // Apply automation values during playback
  const applyAutomation = useCallback(() => {
    if (!audioContextRef.current) return;
@@ -303,11 +348,20 @@ export function useMultiTrackPlayer(
    analyserNodesRef.current = [];
    effectNodesRef.current = [];

-    // Create master gain node
+    // Create master gain node with analyser for metering
    const masterGain = audioContext.createGain();
    masterGain.gain.setValueAtTime(masterVolume, audioContext.currentTime);
-    masterGain.connect(audioContext.destination);
+
+    const masterAnalyser = audioContext.createAnalyser();
+    masterAnalyser.fftSize = 256;
+    masterAnalyser.smoothingTimeConstant = 0.8;
+
+    // Connect: masterGain -> analyser -> destination
+    masterGain.connect(masterAnalyser);
+    masterAnalyser.connect(audioContext.destination);
+
    masterGainNodeRef.current = masterGain;
+    masterAnalyserRef.current = masterAnalyser;

    // Create audio graph for each track
    for (const track of tracks) {
@@ -376,10 +430,11 @@ export function useMultiTrackPlayer(
    // Start level monitoring
    isMonitoringLevelsRef.current = true;
    monitorPlaybackLevels();
+    monitorMasterLevels();

    // Start automation
    applyAutomation();
-  }, [tracks, duration, masterVolume, updatePlaybackPosition, monitorPlaybackLevels, applyAutomation]);
+  }, [tracks, duration, masterVolume, updatePlaybackPosition, monitorPlaybackLevels, monitorMasterLevels, applyAutomation]);

  const pause = useCallback(() => {
    if (!audioContextRef.current || !isPlaying) return;
@@ -414,6 +469,11 @@ export function useMultiTrackPlayer(
      levelMonitorFrameRef.current = null;
    }

+    if (masterLevelMonitorFrameRef.current) {
+      cancelAnimationFrame(masterLevelMonitorFrameRef.current);
+      masterLevelMonitorFrameRef.current = null;
+    }
+
    if (automationFrameRef.current) {
      cancelAnimationFrame(automationFrameRef.current);
      automationFrameRef.current = null;
@@ -650,6 +710,10 @@ export function useMultiTrackPlayer(
              cancelAnimationFrame(levelMonitorFrameRef.current);
              levelMonitorFrameRef.current = null;
            }
+            if (masterLevelMonitorFrameRef.current) {
+              cancelAnimationFrame(masterLevelMonitorFrameRef.current);
+              masterLevelMonitorFrameRef.current = null;
+            }
            if (automationFrameRef.current) {
              cancelAnimationFrame(automationFrameRef.current);
              automationFrameRef.current = null;
@@ -662,12 +726,13 @@ export function useMultiTrackPlayer(
        };
        updatePosition();
        monitorPlaybackLevels();
+        monitorMasterLevels();
        applyAutomation();
      }, 10);
    }

    previousEffectStructureRef.current = currentStructure;
-  }, [tracks, isPlaying, duration, masterVolume, monitorPlaybackLevels, applyAutomation]);
+  }, [tracks, isPlaying, duration, masterVolume, monitorPlaybackLevels, monitorMasterLevels, applyAutomation]);

  // Stop playback when all tracks are deleted
  useEffect(() => {
@@ -730,6 +795,9 @@ export function useMultiTrackPlayer(
      if (levelMonitorFrameRef.current) {
        cancelAnimationFrame(levelMonitorFrameRef.current);
      }
+      if (masterLevelMonitorFrameRef.current) {
+        cancelAnimationFrame(masterLevelMonitorFrameRef.current);
+      }
      if (automationFrameRef.current) {
        cancelAnimationFrame(automationFrameRef.current);
      }
@@ -750,11 +818,19 @@ export function useMultiTrackPlayer(
    };
  }, []);

+  const resetClipIndicator = useCallback(() => {
+    setMasterIsClipping(false);
+  }, []);
+
  return {
    isPlaying,
    currentTime,
    duration,
    trackLevels,
+    masterPeakLevel,
+    masterRmsLevel,
+    masterIsClipping,
+    resetClipIndicator,
    play,
    pause,
    stop,