From 31305d443d2d2ec6913036e3bfb8c8b4f81ef9ad Mon Sep 17 00:00:00 2001
From: cbaucom <chrisrb83@gmail.com>
Date: Wed, 10 Jun 2026 23:11:36 -0400
Subject: [PATCH 1/3] Add video-audio ducking envelope and per-slide audio
 overrides.

Planner now emits ramped soundtrack ducking around video spans; composition and slide settings apply the mix controls from issue #12.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 specs/issue-12-video-audio-ducking.md    |  46 +++++++
 src/composition/SlideshowComposition.tsx |  14 ++-
 src/composition/soundtrackVolume.ts      |  45 +++++++
 src/editor-shell/SlideSettingsDialog.tsx |  88 +++++++++++++
 src/sequence-planner/ducking.test.ts     | 124 +++++++++++++++++++
 src/sequence-planner/ducking.ts          | 151 +++++++++++++++++++++++
 src/sequence-planner/index.ts            |   2 +-
 src/sequence-planner/planner.test.ts     |   9 +-
 src/sequence-planner/planner.ts          |  14 ++-
 src/sequence-planner/types.ts            |  20 ++-
 src/timeline-core/index.ts               |   9 +-
 src/timeline-core/settings.ts            |   9 +-
 12 files changed, 520 insertions(+), 11 deletions(-)
 create mode 100644 specs/issue-12-video-audio-ducking.md
 create mode 100644 src/composition/soundtrackVolume.ts
 create mode 100644 src/sequence-planner/ducking.test.ts
 create mode 100644 src/sequence-planner/ducking.ts

diff --git a/specs/issue-12-video-audio-ducking.md b/specs/issue-12-video-audio-ducking.md
new file mode 100644
index 0000000..d42b3c0
--- /dev/null
+++ b/specs/issue-12-video-audio-ducking.md
@@ -0,0 +1,46 @@
+# Issue 12 — Video-audio ducking + per-slide audio overrides
+
+## Scope
+
+Planner computes a soundtrack ducking envelope; Composition applies volume curves. Per-slide audio overrides live in `SlideSettingsDialog`.
+
+## Types
+
+### SlideOverrides (timeline-core)
+
+| Field | Type | Effect |
+| --- | --- | --- |
+| `muteMusic` | `boolean?` | Soundtrack silent for slide span |
+| `muteVideoAudio` | `boolean?` | Video plays muted; no ducking |
+| `musicVolume` | `number?` | Custom soundtrack level (0–1) during slide |
+| `videoVolume` | `number?` | Custom video audio level (0–1); default 1 |
+
+### RenderPlan (sequence-planner)
+
+- `SoundtrackTrack.duckingEnvelope`: `{ keyframes, rampFrames, segments }`
+- `RenderPlanEntry.videoVolume`: resolved 0–1 for video slides
+
+Constants: `DUCK_LEVEL = 0.2`, `DUCK_RAMP_FRAMES = 6`.
+
+## Ducking rules
+
+1. Video slide, default: duck music to 20% for slide span with 6-frame attack/release ramps.
+2. `muteVideoAudio`: music stays at full level; `videoVolume = 0`.
+3. `muteMusic`: music at 0 for slide span; video audio unchanged unless `videoVolume` set.
+4. `musicVolume` override replaces duck level (or sets level on non-video slides).
+5. `videoVolume` override sets video playback volume.
+
+## Composition
+
+- `Html5Audio` uses envelope keyframes interpolated by composition frame.
+- `Video` uses `volume` / `muted` from entry `videoVolume`.
+
+## UI
+
+`SlideSettingsDialog`: audio section on all slides; video-only mute-video control.
+
+## Tests
+
+- Golden: photo–video–photo produces one duck segment aligned to video entry.
+- Override: muteVideoAudio → no segment; muteMusic → keyframes at 0.
+- Property: duck segments exactly cover unmuted, non–mute-music video spans.
diff --git a/src/composition/SlideshowComposition.tsx b/src/composition/SlideshowComposition.tsx
index 81b7b95..f3181f7 100644
--- a/src/composition/SlideshowComposition.tsx
+++ b/src/composition/SlideshowComposition.tsx
@@ -9,6 +9,7 @@ import type { RenderPlanEntry, RenderPlan } from '../sequence-planner/types'
 import type { TransitionType } from '../timeline-core/settings'
 import { isTitleSlide } from '../timeline-core/types'
 import type { MediaSlide, TitleSlide } from '../timeline-core/types'
+import { useSoundtrackVolume } from './soundtrackVolume'
 
 type MediaRenderPlanEntry = Omit<RenderPlanEntry, 'slide'> & { slide: MediaSlide }
 type TitleRenderPlanEntry = Omit<RenderPlanEntry, 'slide'> & { slide: TitleSlide }
@@ -62,7 +63,7 @@ export function SlideshowComposition({ plan }: SlideshowProps) {
   return (
     <AbsoluteFill>
       {plan.soundtrack ? (
-        <Html5Audio src={plan.soundtrack.blobUrl} volume={plan.soundtrack.volume} />
+        <SoundtrackAudio track={plan.soundtrack} />
       ) : null}
       <TransitionSeries>
       {plan.entries.map((entry) => (
@@ -87,6 +88,11 @@ export function SlideshowComposition({ plan }: SlideshowProps) {
   )
 }
 
+function SoundtrackAudio({ track }: { track: NonNullable<RenderPlan['soundtrack']> }) {
+  const volume = useSoundtrackVolume(track.duckingEnvelope)
+  return <Html5Audio src={track.blobUrl} volume={volume} />
+}
+
 function TitleSlideView({ entry }: { entry: TitleRenderPlanEntry }) {
   const { slide } = entry
   const bg = slide.style === 'light' ? '#fff' : '#111'
@@ -130,7 +136,7 @@ function TitleSlideView({ entry }: { entry: TitleRenderPlanEntry }) {
 }
 
 function MediaSlideView({ entry }: { entry: MediaRenderPlanEntry }) {
-  const { slide, fitMode, kenBurns, durationInFrames } = entry
+  const { fitMode, kenBurns, durationInFrames, slide, videoVolume } = entry
   const frame = useCurrentFrame()
 
   // Compute Ken Burns transform (images only; null for videos).
@@ -152,8 +158,10 @@ function MediaSlideView({ entry }: { entry: MediaRenderPlanEntry }) {
     return (
       <AbsoluteFill style={{ background: '#000' }}>
         <Video
+          muted={videoVolume === 0}
           src={slide.blobUrl}
-          style={{ width: '100%', height: '100%', objectFit: 'contain' }}
+          style={{ height: '100%', objectFit: 'contain', width: '100%' }}
+          volume={videoVolume}
         />
       </AbsoluteFill>
     )
diff --git a/src/composition/soundtrackVolume.ts b/src/composition/soundtrackVolume.ts
new file mode 100644
index 0000000..46773f7
--- /dev/null
+++ b/src/composition/soundtrackVolume.ts
@@ -0,0 +1,45 @@
+import { interpolate, useCurrentFrame } from 'remotion'
+import type { DuckingEnvelope, VolumeKeyframe } from '../sequence-planner/types'
+
+export function volumeAtFrame(envelope: DuckingEnvelope, frame: number): number {
+  const { keyframes, rampFrames } = envelope
+  if (keyframes.length === 0) return 1
+
+  let active = keyframes[0]
+  let next = keyframes[0]
+
+  for (let index = 0; index < keyframes.length; index++) {
+    if (keyframes[index].frame <= frame) {
+      active = keyframes[index]
+      next = keyframes[Math.min(index + 1, keyframes.length - 1)]
+      continue
+    }
+    next = keyframes[index]
+    break
+  }
+
+  if (active.frame === next.frame || frame <= active.frame) {
+    return active.volume
+  }
+
+  const rampEndFrame = Math.min(active.frame + rampFrames, next.frame)
+  if (frame >= next.frame) {
+    return next.volume
+  }
+  if (frame <= rampEndFrame && active.volume !== next.volume) {
+    return interpolate(frame, [active.frame, rampEndFrame], [active.volume, next.volume], {
+      extrapolateLeft: 'clamp',
+      extrapolateRight: 'clamp',
+    })
+  }
+
+  return active.volume
+}
+
+export function useSoundtrackVolume(envelope: VolumeKeyframe[] | DuckingEnvelope, rampFrames = 6) {
+  const frame = useCurrentFrame()
+  const duckingEnvelope = Array.isArray(envelope)
+    ? { keyframes: envelope, rampFrames, segments: [] }
+    : envelope
+  return volumeAtFrame(duckingEnvelope, frame)
+}
diff --git a/src/editor-shell/SlideSettingsDialog.tsx b/src/editor-shell/SlideSettingsDialog.tsx
index dbe8f5d..bde708c 100644
--- a/src/editor-shell/SlideSettingsDialog.tsx
+++ b/src/editor-shell/SlideSettingsDialog.tsx
@@ -115,6 +115,94 @@ export function SlideSettingsDialog({ globalSettings, onClose, onOverride, slide
           </div>
         ) : null}
 
+        <div className="override-row">
+          <span className="override-label">Mute music</span>
+          <input
+            checked={ov.muteMusic ?? false}
+            onChange={e => {
+              if (e.target.checked) {
+                setField('muteMusic', true)
+                return
+              }
+              clearField('muteMusic')
+            }}
+            type="checkbox"
+          />
+          {ov.muteMusic !== undefined
+            ? <button className="override-reset" onClick={() => clearField('muteMusic')} title="Reset to global">↩</button>
+            : <span className="override-default">off</span>
+          }
+        </div>
+
+        <div className="override-row">
+          <span className="override-label">Music level</span>
+          <input
+            className="settings-input"
+            disabled={ov.muteMusic === true}
+            max={100}
+            min={0}
+            onChange={e => {
+              const value = Number(e.target.value) / 100
+              if (Number.isNaN(value)) return
+              setField('musicVolume', value)
+            }}
+            step={5}
+            type="range"
+            value={Math.round((ov.musicVolume ?? 1) * 100)}
+          />
+          <span className="settings-unit">{Math.round((ov.musicVolume ?? 1) * 100)}%</span>
+          {ov.musicVolume !== undefined
+            ? <button className="override-reset" onClick={() => clearField('musicVolume')} title="Reset to global">↩</button>
+            : <span className="override-default">auto</span>
+          }
+        </div>
+
+        {slide.type === 'video' ? (
+          <>
+            <div className="override-row">
+              <span className="override-label">Mute video audio</span>
+              <input
+                checked={ov.muteVideoAudio ?? false}
+                onChange={e => {
+                  if (e.target.checked) {
+                    setField('muteVideoAudio', true)
+                    return
+                  }
+                  clearField('muteVideoAudio')
+                }}
+                type="checkbox"
+              />
+              {ov.muteVideoAudio !== undefined
+                ? <button className="override-reset" onClick={() => clearField('muteVideoAudio')} title="Reset to global">↩</button>
+                : <span className="override-default">off</span>
+              }
+            </div>
+
+            <div className="override-row">
+              <span className="override-label">Video level</span>
+              <input
+                className="settings-input"
+                disabled={ov.muteVideoAudio === true}
+                max={100}
+                min={0}
+                onChange={e => {
+                  const value = Number(e.target.value) / 100
+                  if (Number.isNaN(value)) return
+                  setField('videoVolume', value)
+                }}
+                step={5}
+                type="range"
+                value={Math.round((ov.videoVolume ?? 1) * 100)}
+              />
+              <span className="settings-unit">{Math.round((ov.videoVolume ?? 1) * 100)}%</span>
+              {ov.videoVolume !== undefined
+                ? <button className="override-reset" onClick={() => clearField('videoVolume')} title="Reset to global">↩</button>
+                : <span className="override-default">100%</span>
+              }
+            </div>
+          </>
+        ) : null}
+
         <div className="slide-dialog-footer">
           {hasOverrides ? (
             <button className="override-reset-all" onClick={resetAll}>
diff --git a/src/sequence-planner/ducking.test.ts b/src/sequence-planner/ducking.test.ts
new file mode 100644
index 0000000..7179c67
--- /dev/null
+++ b/src/sequence-planner/ducking.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest'
+import { isTitleSlide } from '../timeline-core/types'
+import { DEFAULT_GLOBAL_SETTINGS } from '../timeline-core/settings'
+import type { MediaSlide } from '../timeline-core/types'
+import { DUCK_LEVEL, DUCK_RAMP_FRAMES, plan } from './planner'
+
+function makeSlide(
+  id: string,
+  type: 'image' | 'video',
+  durationInFrames: number,
+  overrides?: MediaSlide['overrides'],
+): MediaSlide {
+  return {
+    blobUrl: '',
+    durationInFrames,
+    excluded: false,
+    filename: `${id}.${type === 'image' ? 'jpg' : 'mp4'}`,
+    id,
+    overrides,
+    type,
+  }
+}
+
+const SETTINGS = { ...DEFAULT_GLOBAL_SETTINGS, transitionType: 'cut' as const }
+const SOUNDTRACK = { blobUrl: 'blob:audio', durationInFrames: 900 }
+
+describe('plan — soundtrack ducking envelope', () => {
+  it('ducks music during a video slide between photos', () => {
+    const photo = makeSlide('a', 'image', 90)
+    const video = makeSlide('v', 'video', 120)
+    const photo2 = makeSlide('b', 'image', 90)
+
+    const result = plan([photo, video, photo2], SETTINGS, undefined, SOUNDTRACK)
+    const envelope = result.soundtrack?.duckingEnvelope
+
+    expect(envelope).toBeDefined()
+    expect(envelope!.rampFrames).toBe(DUCK_RAMP_FRAMES)
+    expect(envelope!.segments).toEqual([
+      {
+        duckEndFrame: 90 + 120 - DUCK_RAMP_FRAMES - 1,
+        duckLevel: DUCK_LEVEL,
+        duckStartFrame: 90 + DUCK_RAMP_FRAMES,
+      },
+    ])
+
+    const holdKeyframes = envelope!.keyframes.filter((keyframe) => keyframe.volume === DUCK_LEVEL)
+    expect(holdKeyframes.length).toBeGreaterThan(0)
+    expect(envelope!.keyframes[0]).toEqual({ frame: 0, volume: 1 })
+  })
+
+  it('does not duck when video audio is muted', () => {
+    const video = makeSlide('v', 'video', 120, { muteVideoAudio: true })
+
+    const result = plan([video], SETTINGS, undefined, SOUNDTRACK)
+
+    expect(result.soundtrack?.duckingEnvelope.segments).toEqual([])
+    expect(result.entries[0].videoVolume).toBe(0)
+  })
+
+  it('mutes soundtrack when muteMusic is set', () => {
+    const video = makeSlide('v', 'video', 120, { muteMusic: true })
+
+    const result = plan([video], SETTINGS, undefined, SOUNDTRACK)
+    const { keyframes } = result.soundtrack!.duckingEnvelope
+
+    expect(result.soundtrack?.duckingEnvelope.segments).toEqual([])
+    expect(keyframes).toContainEqual({ frame: 0, volume: 0 })
+    expect(keyframes).toContainEqual({ frame: 120, volume: 1 })
+  })
+
+  it('uses custom musicVolume instead of default duck level', () => {
+    const video = makeSlide('v', 'video', 120, { musicVolume: 0.5 })
+
+    const result = plan([video], SETTINGS, undefined, SOUNDTRACK)
+
+    expect(result.soundtrack?.duckingEnvelope.segments).toEqual([])
+    expect(result.soundtrack?.duckingEnvelope.keyframes).toContainEqual({ frame: 0, volume: 0.5 })
+    expect(result.soundtrack?.duckingEnvelope.keyframes).toContainEqual({ frame: 120, volume: 1 })
+  })
+})
+
+describe('plan — ducking envelope property', () => {
+  it('duck segments exactly cover unmuted video-audio spans', () => {
+    const cases: MediaSlide[][] = [
+      [makeSlide('a', 'image', 60), makeSlide('v', 'video', 90), makeSlide('b', 'image', 45)],
+      [
+        makeSlide('v1', 'video', 30),
+        makeSlide('v2', 'video', 40, { muteVideoAudio: true }),
+        makeSlide('v3', 'video', 50, { muteMusic: true }),
+        makeSlide('v4', 'video', 70),
+      ],
+      [makeSlide('v', 'video', 8)],
+    ]
+
+    for (const slides of cases) {
+      const result = plan(slides, SETTINGS, undefined, SOUNDTRACK)
+      const envelope = result.soundtrack!.duckingEnvelope
+      const expectedSpans = result.entries.flatMap((entry) => {
+        const { durationInFrames, slide, startFrame } = entry
+        if (isTitleSlide(slide) || slide.type !== 'video') return []
+        if (slide.overrides?.muteVideoAudio || slide.overrides?.muteMusic) return []
+        if (slide.overrides?.musicVolume !== undefined) return []
+        return [{
+          endFrame: startFrame + durationInFrames - 1,
+          startFrame,
+        }]
+      })
+
+      const actualSpans = envelope.segments.map((segment) => ({
+        endFrame: segment.duckEndFrame,
+        startFrame: segment.duckStartFrame,
+      }))
+
+      expect(actualSpans).toEqual(expectedSpans.map((span) => {
+        const duckStartFrame = span.startFrame + DUCK_RAMP_FRAMES
+        const duckEndFrame = span.endFrame - DUCK_RAMP_FRAMES
+        if (duckEndFrame < duckStartFrame) {
+          return { endFrame: span.endFrame, startFrame: span.startFrame }
+        }
+        return { endFrame: duckEndFrame, startFrame: duckStartFrame }
+      }))
+    }
+  })
+})
diff --git a/src/sequence-planner/ducking.ts b/src/sequence-planner/ducking.ts
new file mode 100644
index 0000000..e21361b
--- /dev/null
+++ b/src/sequence-planner/ducking.ts
@@ -0,0 +1,151 @@
+import { isTitleSlide } from '../timeline-core/types'
+import type { Slide } from '../timeline-core/types'
+import type { DuckingEnvelope, RenderPlanEntry, VolumeKeyframe } from './types'
+
+export const DUCK_LEVEL = 0.2
+export const DUCK_RAMP_FRAMES = 6
+export const FULL_VOLUME = 1
+
+type SlideSpan = {
+  duckEndFrame?: number
+  duckLevel: number
+  duckStartFrame?: number
+  endFrame: number
+  kind: 'duck' | 'hold' | 'mute'
+  startFrame: number
+}
+
+export function buildDuckingEnvelope(entries: RenderPlanEntry[]): DuckingEnvelope {
+  const spans = entries.flatMap(collectSlideSpan)
+  const keyframes = spansToKeyframes(spans)
+  const segments = spans
+    .filter((span): span is SlideSpan & { kind: 'duck' } => span.kind === 'duck')
+    .map((span) => ({
+      duckEndFrame: span.duckEndFrame ?? span.endFrame,
+      duckLevel: span.duckLevel,
+      duckStartFrame: span.duckStartFrame ?? span.startFrame,
+    }))
+
+  return {
+    keyframes,
+    rampFrames: DUCK_RAMP_FRAMES,
+    segments,
+  }
+}
+
+function collectSlideSpan(entry: RenderPlanEntry): SlideSpan[] {
+  const { durationInFrames, slide, startFrame } = entry
+  const endFrame = startFrame + durationInFrames - 1
+  const overrides = slide.overrides
+
+  if (overrides?.muteMusic) {
+    return [{ duckLevel: 0, endFrame, kind: 'mute', startFrame }]
+  }
+
+  if (overrides?.musicVolume !== undefined) {
+    return [{
+      duckLevel: overrides.musicVolume,
+      endFrame,
+      kind: 'hold',
+      startFrame,
+    }]
+  }
+
+  if (!isTitleSlide(slide) && slide.type === 'video' && !overrides?.muteVideoAudio) {
+    const duckStartFrame = startFrame + DUCK_RAMP_FRAMES
+    const duckEndFrame = endFrame - DUCK_RAMP_FRAMES
+    if (duckEndFrame < duckStartFrame) {
+      return [{
+        duckLevel: DUCK_LEVEL,
+        endFrame,
+        kind: 'duck',
+        startFrame,
+      }]
+    }
+    return [{
+      duckEndFrame,
+      duckLevel: DUCK_LEVEL,
+      duckStartFrame,
+      endFrame,
+      kind: 'duck',
+      startFrame,
+    }]
+  }
+
+  return []
+}
+
+function spansToKeyframes(spans: SlideSpan[]): VolumeKeyframe[] {
+  const keyframes: VolumeKeyframe[] = [{ frame: 0, volume: FULL_VOLUME }]
+
+  for (const span of spans) {
+    if (span.kind === 'mute' || span.kind === 'hold') {
+      pushKeyframe(keyframes, span.startFrame, span.duckLevel)
+      pushKeyframe(keyframes, span.endFrame + 1, FULL_VOLUME)
+      continue
+    }
+
+    const holdStart = span.duckStartFrame ?? span.startFrame
+    const holdEnd = span.duckEndFrame ?? span.endFrame
+
+    if (holdEnd < holdStart) {
+      pushKeyframe(keyframes, span.startFrame, span.duckLevel)
+      pushKeyframe(keyframes, span.endFrame + 1, FULL_VOLUME)
+      continue
+    }
+
+    pushKeyframe(keyframes, span.startFrame, FULL_VOLUME)
+    pushKeyframe(keyframes, holdStart, span.duckLevel)
+    pushKeyframe(keyframes, holdEnd, span.duckLevel)
+    pushKeyframe(keyframes, span.endFrame + 1, FULL_VOLUME)
+  }
+
+  return normalizeKeyframes(keyframes)
+}
+
+function pushKeyframe(keyframes: VolumeKeyframe[], frame: number, volume: number) {
+  const last = keyframes[keyframes.length - 1]
+  if (last && last.frame === frame) {
+    last.volume = volume
+    return
+  }
+  keyframes.push({ frame, volume })
+}
+
+function normalizeKeyframes(keyframes: VolumeKeyframe[]): VolumeKeyframe[] {
+  const sorted = [...keyframes].sort((left, right) => left.frame - right.frame)
+  const deduped: VolumeKeyframe[] = []
+
+  for (const keyframe of sorted) {
+    const last = deduped[deduped.length - 1]
+    if (last && last.frame === keyframe.frame) {
+      last.volume = keyframe.volume
+      continue
+    }
+    deduped.push({ ...keyframe })
+  }
+
+  if (deduped.length === 0 || deduped[0].frame !== 0) {
+    deduped.unshift({ frame: 0, volume: FULL_VOLUME })
+  }
+
+  return deduped
+}
+
+export function resolveVideoVolume(slide: Slide): number {
+  if (isTitleSlide(slide) || slide.type !== 'video') return FULL_VOLUME
+  if (slide.overrides?.muteVideoAudio) return 0
+  return slide.overrides?.videoVolume ?? FULL_VOLUME
+}
+
+export function getUnmutedVideoAudioSpans(entries: RenderPlanEntry[]): Array<{
+  endFrame: number
+  startFrame: number
+}> {
+  return entries.flatMap((entry) => {
+    const { durationInFrames, slide, startFrame } = entry
+    if (isTitleSlide(slide) || slide.type !== 'video') return []
+    if (slide.overrides?.muteVideoAudio || slide.overrides?.muteMusic) return []
+    return [{ endFrame: startFrame + durationInFrames - 1, startFrame }]
+  })
+}
diff --git a/src/sequence-planner/index.ts b/src/sequence-planner/index.ts
index e2fe2ef..f649f8d 100644
--- a/src/sequence-planner/index.ts
+++ b/src/sequence-planner/index.ts
@@ -1,3 +1,3 @@
 export { plan, TRANSITION_FRAMES } from './planner'
 export type { SoundtrackInput } from './planner'
-export type { MediaMetadata, RenderPlan, RenderPlanEntry, SoundtrackTrack, TransitionSpec } from './types'
+export type { MediaMetadata, RenderPlan, RenderPlanEntry, SoundtrackTrack, TransitionSpec, DuckingEnvelope, DuckingSegment, VolumeKeyframe } from './types'
diff --git a/src/sequence-planner/planner.test.ts b/src/sequence-planner/planner.test.ts
index 578b6c7..1580ed0 100644
--- a/src/sequence-planner/planner.test.ts
+++ b/src/sequence-planner/planner.test.ts
@@ -381,7 +381,14 @@ describe('plan — soundtrack', () => {
 
   it('includes soundtrack on RenderPlan when provided', () => {
     const result = plan([IMG_90], CROSSFADE, undefined, SOUNDTRACK)
-    expect(result.soundtrack).toEqual({ ...SOUNDTRACK, volume: 1 })
+    expect(result.soundtrack).toEqual({
+      ...SOUNDTRACK,
+      duckingEnvelope: {
+        keyframes: [{ frame: 0, volume: 1 }],
+        rampFrames: 6,
+        segments: [],
+      },
+    })
     expect(result.totalFrames).toBe(90)
   })
 
diff --git a/src/sequence-planner/planner.ts b/src/sequence-planner/planner.ts
index 14af21b..04575da 100644
--- a/src/sequence-planner/planner.ts
+++ b/src/sequence-planner/planner.ts
@@ -2,6 +2,7 @@ import { resolve } from '../timeline-core/settings'
 import type { FitMode, GlobalSettings, TransitionType } from '../timeline-core/settings'
 import { isTitleSlide } from '../timeline-core/types'
 import type { Slide } from '../timeline-core/types'
+import { buildDuckingEnvelope, resolveVideoVolume } from './ducking'
 import type {
   KenBurnsVector,
   MediaMetadata,
@@ -13,7 +14,7 @@ import type {
 
 export type SoundtrackInput = Pick<SoundtrackTrack, 'blobUrl' | 'durationInFrames'>
 
-const DEFAULT_SOUNDTRACK_VOLUME = 1
+export { DUCK_LEVEL, DUCK_RAMP_FRAMES, FULL_VOLUME } from './ducking'
 
 const FPS = 30
 
@@ -42,7 +43,10 @@ export function plan(
     return {
       entries: [],
       soundtrack: soundtrack
-        ? { ...soundtrack, volume: DEFAULT_SOUNDTRACK_VOLUME }
+        ? {
+            ...soundtrack,
+            duckingEnvelope: buildDuckingEnvelope([]),
+          }
         : undefined,
       totalFrames: 0,
     }
@@ -116,6 +120,7 @@ export function plan(
       transitionIn,
       fitMode: getFitMode(slide),
       kenBurns,
+      videoVolume: resolveVideoVolume(slide),
     })
 
     // Advance by this slide's duration minus the NEXT slide's inbound transition overlap.
@@ -129,7 +134,10 @@ export function plan(
   return {
     entries,
     soundtrack: soundtrack
-      ? { ...soundtrack, volume: DEFAULT_SOUNDTRACK_VOLUME }
+      ? {
+          ...soundtrack,
+          duckingEnvelope: buildDuckingEnvelope(entries),
+        }
       : undefined,
     totalFrames: cursor,
   }
diff --git a/src/sequence-planner/types.ts b/src/sequence-planner/types.ts
index d720aa7..7cb8d22 100644
--- a/src/sequence-planner/types.ts
+++ b/src/sequence-planner/types.ts
@@ -15,6 +15,23 @@ export type KenBurnsVector = {
   toY: number
 }
 
+export type VolumeKeyframe = {
+  frame: number
+  volume: number
+}
+
+export type DuckingSegment = {
+  duckEndFrame: number
+  duckLevel: number
+  duckStartFrame: number
+}
+
+export type DuckingEnvelope = {
+  keyframes: VolumeKeyframe[]
+  rampFrames: number
+  segments: DuckingSegment[]
+}
+
 export type RenderPlanEntry = {
   slide: Slide
   startFrame: number
@@ -22,12 +39,13 @@ export type RenderPlanEntry = {
   transitionIn?: TransitionSpec
   fitMode: FitMode
   kenBurns: KenBurnsVector | null
+  videoVolume: number
 }
 
 export type SoundtrackTrack = {
   blobUrl: string
+  duckingEnvelope: DuckingEnvelope
   durationInFrames: number
-  volume: number
 }
 
 export type RenderPlan = {
diff --git a/src/timeline-core/index.ts b/src/timeline-core/index.ts
index 2f1978e..a5dacdc 100644
--- a/src/timeline-core/index.ts
+++ b/src/timeline-core/index.ts
@@ -1,6 +1,13 @@
 export { getMediaType, isSupportedAudio, isSupportedMedia, sortByFilename } from './media'
 export { moveSlide, toggleExcluded, filterIncluded, createTitleSlide } from './timeline'
 export { resolve, applyImageDuration, DEFAULT_GLOBAL_SETTINGS } from './settings'
-export type { GlobalSettings, SlideOverrides, ResolvedSlideSettings, TransitionType, FitMode } from './settings'
+export type {
+  GlobalSettings,
+  ResolvedSlideSettings,
+  SlideAudioOverrides,
+  SlideOverrides,
+  TransitionType,
+  FitMode,
+} from './settings'
 export type { MediaSlide, TitleSlide, Slide, MediaType } from './types'
 export { isTitleSlide } from './types'
diff --git a/src/timeline-core/settings.ts b/src/timeline-core/settings.ts
index 1b6cd10..94cb1d0 100644
--- a/src/timeline-core/settings.ts
+++ b/src/timeline-core/settings.ts
@@ -11,7 +11,14 @@ export type GlobalSettings = {
   fitMode: FitMode
 }
 
-export type SlideOverrides = Partial<GlobalSettings>
+export type SlideAudioOverrides = {
+  muteMusic?: boolean
+  muteVideoAudio?: boolean
+  musicVolume?: number
+  videoVolume?: number
+}
+
+export type SlideOverrides = Partial<GlobalSettings> & SlideAudioOverrides
 
 export type ResolvedSlideSettings = GlobalSettings
 

From a633555c66f2c1d8cdd99602c89844568b760e7c Mon Sep 17 00:00:00 2001
From: cbaucom <chrisrb83@gmail.com>
Date: Wed, 10 Jun 2026 23:14:06 -0400
Subject: [PATCH 2/3] Use shared span helper in ducking property test.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/sequence-planner/ducking.test.ts | 15 ++++-----------
 src/sequence-planner/planner.ts      |  2 +-
 2 files changed, 5 insertions(+), 12 deletions(-)

diff --git a/src/sequence-planner/ducking.test.ts b/src/sequence-planner/ducking.test.ts
index 7179c67..5d1261d 100644
--- a/src/sequence-planner/ducking.test.ts
+++ b/src/sequence-planner/ducking.test.ts
@@ -1,8 +1,7 @@
 import { describe, expect, it } from 'vitest'
-import { isTitleSlide } from '../timeline-core/types'
 import { DEFAULT_GLOBAL_SETTINGS } from '../timeline-core/settings'
 import type { MediaSlide } from '../timeline-core/types'
-import { DUCK_LEVEL, DUCK_RAMP_FRAMES, plan } from './planner'
+import { DUCK_LEVEL, DUCK_RAMP_FRAMES, getUnmutedVideoAudioSpans, plan } from './planner'
 
 function makeSlide(
   id: string,
@@ -95,15 +94,9 @@ describe('plan — ducking envelope property', () => {
     for (const slides of cases) {
       const result = plan(slides, SETTINGS, undefined, SOUNDTRACK)
       const envelope = result.soundtrack!.duckingEnvelope
-      const expectedSpans = result.entries.flatMap((entry) => {
-        const { durationInFrames, slide, startFrame } = entry
-        if (isTitleSlide(slide) || slide.type !== 'video') return []
-        if (slide.overrides?.muteVideoAudio || slide.overrides?.muteMusic) return []
-        if (slide.overrides?.musicVolume !== undefined) return []
-        return [{
-          endFrame: startFrame + durationInFrames - 1,
-          startFrame,
-        }]
+      const expectedSpans = getUnmutedVideoAudioSpans(result.entries).filter((span) => {
+        const entry = result.entries.find((candidate) => candidate.startFrame === span.startFrame)
+        return entry?.slide.overrides?.musicVolume === undefined
       })
 
       const actualSpans = envelope.segments.map((segment) => ({
diff --git a/src/sequence-planner/planner.ts b/src/sequence-planner/planner.ts
index 04575da..2f3ee30 100644
--- a/src/sequence-planner/planner.ts
+++ b/src/sequence-planner/planner.ts
@@ -14,7 +14,7 @@ import type {
 
 export type SoundtrackInput = Pick<SoundtrackTrack, 'blobUrl' | 'durationInFrames'>
 
-export { DUCK_LEVEL, DUCK_RAMP_FRAMES, FULL_VOLUME } from './ducking'
+export { DUCK_LEVEL, DUCK_RAMP_FRAMES, FULL_VOLUME, getUnmutedVideoAudioSpans } from './ducking'
 
 const FPS = 30
 

From 25f9caa0c6fc7c4f69e7cecf4f9302dd211b5028 Mon Sep 17 00:00:00 2001
From: cbaucom <chrisrb83@gmail.com>
Date: Wed, 10 Jun 2026 23:22:10 -0400
Subject: [PATCH 3/3] Label audio override controls for accessibility and smoke
 testing.

---
 src/editor-shell/SlideSettingsDialog.tsx | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/editor-shell/SlideSettingsDialog.tsx b/src/editor-shell/SlideSettingsDialog.tsx
index bde708c..3fd7877 100644
--- a/src/editor-shell/SlideSettingsDialog.tsx
+++ b/src/editor-shell/SlideSettingsDialog.tsx
@@ -116,9 +116,10 @@ export function SlideSettingsDialog({ globalSettings, onClose, onOverride, slide
         ) : null}
 
         <div className="override-row">
-          <span className="override-label">Mute music</span>
+          <label className="override-label" htmlFor={`${slide.id}-mute-music`}>Mute music</label>
           <input
             checked={ov.muteMusic ?? false}
+            id={`${slide.id}-mute-music`}
             onChange={e => {
               if (e.target.checked) {
                 setField('muteMusic', true)
@@ -135,10 +136,11 @@ export function SlideSettingsDialog({ globalSettings, onClose, onOverride, slide
         </div>
 
         <div className="override-row">
-          <span className="override-label">Music level</span>
+          <label className="override-label" htmlFor={`${slide.id}-music-volume`}>Music level</label>
           <input
             className="settings-input"
             disabled={ov.muteMusic === true}
+            id={`${slide.id}-music-volume`}
             max={100}
             min={0}
             onChange={e => {
@@ -160,9 +162,10 @@ export function SlideSettingsDialog({ globalSettings, onClose, onOverride, slide
         {slide.type === 'video' ? (
           <>
             <div className="override-row">
-              <span className="override-label">Mute video audio</span>
+              <label className="override-label" htmlFor={`${slide.id}-mute-video-audio`}>Mute video audio</label>
               <input
                 checked={ov.muteVideoAudio ?? false}
+                id={`${slide.id}-mute-video-audio`}
                 onChange={e => {
                   if (e.target.checked) {
                     setField('muteVideoAudio', true)
@@ -179,10 +182,11 @@ export function SlideSettingsDialog({ globalSettings, onClose, onOverride, slide
             </div>
 
             <div className="override-row">
-              <span className="override-label">Video level</span>
+              <label className="override-label" htmlFor={`${slide.id}-video-volume`}>Video level</label>
               <input
                 className="settings-input"
                 disabled={ov.muteVideoAudio === true}
+                id={`${slide.id}-video-volume`}
                 max={100}
                 min={0}
                 onChange={e => {