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>

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

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>
 

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,29 +284,40 @@ export function PlaybackControls({
           )}
         </div>
 
-        {/* Volume Control */}
+        {/* Volume Control & Master Meter */}
-        <div className="flex items-center gap-3 min-w-[200px]">
+        <div className="flex items-center gap-4">
-          <Button
+          {/* Master Meter */}
-            variant="ghost"
+          <MasterMeter
-            size="icon"
+            peakLevel={masterPeakLevel}
-            onClick={handleMuteToggle}
+            rmsLevel={masterRmsLevel}
-            title={isMuted ? 'Unmute' : 'Mute'}
+            isClipping={masterIsClipping}
-          >
+            onResetClip={onResetClip}
-            {isMuted || volume === 0 ? (
-              <VolumeX className="h-5 w-5" />
-            ) : (
-              <Volume2 className="h-5 w-5" />
-            )}
-          </Button>
-
-          <Slider
-            value={volume}
-            onChange={handleVolumeChange}
-            min={0}
-            max={1}
-            step={0.01}
-            className="flex-1"
           />
+
+          {/* Volume Control */}
+          <div className="flex items-center gap-3 min-w-[200px]">
+            <Button
+              variant="ghost"
+              size="icon"
+              onClick={handleMuteToggle}
+              title={isMuted ? 'Unmute' : 'Mute'}
+            >
+              {isMuted || volume === 0 ? (
+                <VolumeX className="h-5 w-5" />
+              ) : (
+                <Volume2 className="h-5 w-5" />
+              )}
+            </Button>
+
+            <Slider
+              value={volume}
+              onChange={handleVolumeChange}
+              min={0}
+              max={1}
+              step={0.01}
+              className="flex-1"
+            />
+          </div>
         </div>
       </div>
     </div>

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,