From fe1b4fc8aeba65a6db37d73340f6b30a96272110 Mon Sep 17 00:00:00 2001
From: Xiaohan-Tian <157918347+Xiaohan-Tian@users.noreply.github.com>
Date: Mon, 18 May 2026 18:28:31 -0700
Subject: [PATCH] feat: added an option to allow user choose whether to trim
 leading silence when bouncing audio

---
 public/config.json                            |   1 +
 .../settings/sections/BehaviorSettings.tsx    |  25 ++++
 src/constants/coreConstants.ts                |   2 +-
 .../audio-interface/KGOfflineRenderer.test.ts | 108 +++++++++++++++++-
 src/core/audio-interface/KGOfflineRenderer.ts |   3 +-
 src/core/config-upgrader/KGConfigUpgrader.ts  |   5 +
 .../config-upgrader/upgradeConfigToV4.test.ts |  64 +++++++++++
 src/core/config-upgrader/upgradeConfigToV4.ts |  30 +++++
 src/core/config/ConfigManager.ts              |   2 +
 9 files changed, 236 insertions(+), 4 deletions(-)
 create mode 100644 src/core/config-upgrader/upgradeConfigToV4.test.ts
 create mode 100644 src/core/config-upgrader/upgradeConfigToV4.ts

diff --git a/public/config.json b/public/config.json
index 88226c1..5a9763c 100644
--- a/public/config.json
+++ b/public/config.json
@@ -76,6 +76,7 @@
         "default_open": true
     },
     "audio": {
+        "bounce_starts_from_beat_1": true,
         "enable_audio_capture_for_screen_sharing": false,
         "input_device_id": "default",
         "lookahead_time": 0.05,
diff --git a/src/components/settings/sections/BehaviorSettings.tsx b/src/components/settings/sections/BehaviorSettings.tsx
index 88f6d05..4688346 100644
--- a/src/components/settings/sections/BehaviorSettings.tsx
+++ b/src/components/settings/sections/BehaviorSettings.tsx
@@ -14,6 +14,7 @@ const BehaviorSettings: React.FC = () => {
   const [midiAutomationInterpolationIntervalMs, setMidiAutomationInterpolationIntervalMs] = useState<number>(10);
   const [playbackDelay, setPlaybackDelay] = useState<string>('200');
   const [recordingOffset, setRecordingOffset] = useState<string>('0');
+  const [bounceStartsFromBeat1, setBounceStartsFromBeat1] = useState<boolean>(true);
   const [enableAudioCapture, setEnableAudioCapture] = useState<boolean>(false);
   const [lookaheadValidationErrors, setLookaheadValidationErrors] = useState<string[]>([]);
   const [playbackDelayValidationErrors, setPlaybackDelayValidationErrors] = useState<string[]>([]);
@@ -42,6 +43,7 @@ const BehaviorSettings: React.FC = () => {
       setPlaybackDelay(((playbackDelaySeconds * 1000).toFixed(0)));
       const recordingOffsetSeconds = (configManager.get('audio.recording_offset') as number) ?? 0;
       setRecordingOffset(((recordingOffsetSeconds * 1000).toFixed(0)));
+      setBounceStartsFromBeat1((configManager.get('audio.bounce_starts_from_beat_1') as boolean) ?? true);
       setEnableAudioCapture((configManager.get('audio.enable_audio_capture_for_screen_sharing') as boolean) ?? false);
     };
 
@@ -158,6 +160,12 @@ const BehaviorSettings: React.FC = () => {
     await configManager.set('audio.enable_audio_capture_for_screen_sharing', boolValue);
   };
 
+  const handleBounceStartsFromBeat1Change = async (value: string) => {
+    const boolValue = value === 'yes';
+    setBounceStartsFromBeat1(boolValue);
+    await configManager.set('audio.bounce_starts_from_beat_1', boolValue);
+  };
+
   return (
     <div className="settings-section">
       <div className="settings-section-header">
@@ -325,6 +333,23 @@ const BehaviorSettings: React.FC = () => {
             </div>
           </div>
 
+          <div className="settings-item">
+            <label className="settings-label">
+              Bounce Starts From Beat 1
+            </label>
+            <select
+              className="settings-select"
+              value={bounceStartsFromBeat1 ? 'yes' : 'no'}
+              onChange={(e) => handleBounceStartsFromBeat1Change(e.target.value)}
+            >
+              <option value="no">No</option>
+              <option value="yes">Yes</option>
+            </select>
+            <div className="settings-help" style={{ fontSize: '12px', color: '#888', marginTop: '4px' }}>
+              Yes includes leading silence from the start of the song up to the first rendered region when bouncing WAV/MP3. No trims that leading silence and starts bounce at the first rendered note or audio region.
+            </div>
+          </div>
+
           <div className="settings-item">
             <label className="settings-label">
               Capture Audio for Screen Sharing
diff --git a/src/constants/coreConstants.ts b/src/constants/coreConstants.ts
index 33f0f40..a1d36b4 100644
--- a/src/constants/coreConstants.ts
+++ b/src/constants/coreConstants.ts
@@ -104,7 +104,7 @@ export const OPFS_CONSTANTS = {
 
 export const CONFIG_UPGRADER_CONSTANTS = {
   VERSION_KEY: '__config_version',
-  CURRENT_VERSION: 3,
+  CURRENT_VERSION: 4,
 };
 
 export const URL_CONSTANTS = {
diff --git a/src/core/audio-interface/KGOfflineRenderer.test.ts b/src/core/audio-interface/KGOfflineRenderer.test.ts
index c184320..358c880 100644
--- a/src/core/audio-interface/KGOfflineRenderer.test.ts
+++ b/src/core/audio-interface/KGOfflineRenderer.test.ts
@@ -1,7 +1,37 @@
-import { describe, it, expect } from 'vitest';
-import { applyOfflinePitchBendAutomation, encodeWav, getOfflineTrackGain, getOfflineTrackVolumeDb } from './KGOfflineRenderer';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createMockMidiNote, createMockMidiRegion, createMockMidiTrack, createMockProject } from '../../test/utils/mock-data';
 import { bakeMidiAutomationPointsInWindow } from '../../util/midiAutomationUtil';
 
+const { offlineMock, configGetMock } = vi.hoisted(() => ({
+  offlineMock: vi.fn(),
+  configGetMock: vi.fn(),
+}));
+
+vi.mock('tone', () => ({
+  Offline: offlineMock,
+}));
+
+vi.mock('./KGAudioInterface', () => ({
+  KGAudioInterface: {
+    instance: vi.fn(() => ({
+      getTrackVolume: vi.fn().mockReturnValue(0),
+      getTrackMuted: vi.fn().mockReturnValue(false),
+      getTrackSolo: vi.fn().mockReturnValue(false),
+      getAudioBuffer: vi.fn().mockReturnValue(null),
+    })),
+  },
+}));
+
+vi.mock('../config/ConfigManager', () => ({
+  ConfigManager: {
+    instance: vi.fn(() => ({
+      get: configGetMock,
+    })),
+  },
+}));
+
+import { KGOfflineRenderer, applyOfflinePitchBendAutomation, encodeWav, getOfflineTrackGain, getOfflineTrackVolumeDb } from './KGOfflineRenderer';
+
 /**
  * Create a minimal AudioBuffer-like object for testing.
  * In the jsdom test environment, AudioBuffer is not available,
@@ -228,3 +258,77 @@ describe('offline pitch bend automation', () => {
     expect(calls[0][1]).toBe(0.26);
   });
 });
+
+describe('renderToBuffer bounce range', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    configGetMock.mockImplementation((key: string) => {
+      if (key === 'audio.bounce_starts_from_beat_1') return true;
+      if (key === 'audio.midi_automation_interpolation_interval_ms') return 10;
+      return null;
+    });
+    offlineMock.mockResolvedValue({
+      duration: 0,
+      numberOfChannels: 2,
+      get: vi.fn(),
+    });
+    ;(KGOfflineRenderer as unknown as { _instance: KGOfflineRenderer | null })._instance = null;
+  });
+
+  it('starts non-looping bounce at beat 0 when configured to include leading silence', async () => {
+    const region = createMockMidiRegion({
+      startFromBeat: 8,
+      notes: [createMockMidiNote({ startBeat: 0, endBeat: 4 })],
+    });
+    const track = createMockMidiTrack({ id: 1, regions: [region] });
+    const project = createMockProject({ bpm: 120, tracks: [track] });
+
+    await KGOfflineRenderer.instance().renderToBuffer(project, { tailSeconds: 0 });
+
+    expect(offlineMock).toHaveBeenCalledWith(expect.any(Function), 6, 2, 44100);
+  });
+
+  it('starts non-looping bounce at first content when the setting is disabled', async () => {
+    configGetMock.mockImplementation((key: string) => {
+      if (key === 'audio.bounce_starts_from_beat_1') return false;
+      if (key === 'audio.midi_automation_interpolation_interval_ms') return 10;
+      return null;
+    });
+
+    const region = createMockMidiRegion({
+      startFromBeat: 8,
+      notes: [createMockMidiNote({ startBeat: 0, endBeat: 4 })],
+    });
+    const track = createMockMidiTrack({ id: 1, regions: [region] });
+    const project = createMockProject({ bpm: 120, tracks: [track] });
+
+    await KGOfflineRenderer.instance().renderToBuffer(project, { tailSeconds: 0 });
+
+    expect(offlineMock).toHaveBeenCalledWith(expect.any(Function), 2, 2, 44100);
+  });
+
+  it('keeps looping bounce bounds regardless of the beat-1 setting', async () => {
+    configGetMock.mockImplementation((key: string) => {
+      if (key === 'audio.bounce_starts_from_beat_1') return false;
+      if (key === 'audio.midi_automation_interpolation_interval_ms') return 10;
+      return null;
+    });
+
+    const project = createMockProject({ bpm: 120, tracks: [] });
+    project.setIsLooping(true);
+    project.setLoopingRange([2, 5]);
+
+    await KGOfflineRenderer.instance().renderToBuffer(project, { tailSeconds: 0 });
+
+    expect(offlineMock).toHaveBeenCalledWith(expect.any(Function), 8, 2, 44100);
+  });
+
+  it('falls back to the full project length when there is no renderable content', async () => {
+    const project = createMockProject({ bpm: 120, tracks: [] });
+    project.setMaxBars(16);
+
+    await KGOfflineRenderer.instance().renderToBuffer(project, { tailSeconds: 0 });
+
+    expect(offlineMock).toHaveBeenCalledWith(expect.any(Function), 32, 2, 44100);
+  });
+});
diff --git a/src/core/audio-interface/KGOfflineRenderer.ts b/src/core/audio-interface/KGOfflineRenderer.ts
index 5f57326..2cdc143 100644
--- a/src/core/audio-interface/KGOfflineRenderer.ts
+++ b/src/core/audio-interface/KGOfflineRenderer.ts
@@ -99,6 +99,7 @@ export class KGOfflineRenderer {
 
     let renderStartBeat = 0;
     let renderEndBeat: number;
+    const bounceStartsFromBeat1 = (ConfigManager.instance().get('audio.bounce_starts_from_beat_1') as boolean) ?? true;
 
     const isLooping = project.getIsLooping();
     // Looping range is determined up-front; non-looping range is computed
@@ -272,7 +273,7 @@ export class KGOfflineRenderer {
       }
 
       if (contentEnd > 0) {
-        renderStartBeat = contentStart;
+        renderStartBeat = bounceStartsFromBeat1 ? 0 : contentStart;
         renderEndBeat = contentEnd;
       }
       // else: no content found, keep the full project range as fallback
diff --git a/src/core/config-upgrader/KGConfigUpgrader.ts b/src/core/config-upgrader/KGConfigUpgrader.ts
index 21e08d7..96acc28 100644
--- a/src/core/config-upgrader/KGConfigUpgrader.ts
+++ b/src/core/config-upgrader/KGConfigUpgrader.ts
@@ -3,6 +3,7 @@ import { CONFIG_UPGRADER_CONSTANTS } from '../../constants/coreConstants';
 import { upgradeConfigToV1 } from './upgradeConfigToV1';
 import { upgradeConfigToV2 } from './upgradeConfigToV2';
 import { upgradeConfigToV3 } from './upgradeConfigToV3';
+import { upgradeConfigToV4 } from './upgradeConfigToV4';
 
 /**
  * KGConfigUpgrader — Orchestrates app-level migrations (e.g., storage backend changes).
@@ -43,6 +44,10 @@ export class KGConfigUpgrader {
           await upgradeConfigToV3();
           break;
         }
+        case 4: {
+          await upgradeConfigToV4();
+          break;
+        }
         default: {
           throw new Error(`No config upgrader found for version ${nextVersion}`);
         }
diff --git a/src/core/config-upgrader/upgradeConfigToV4.test.ts b/src/core/config-upgrader/upgradeConfigToV4.test.ts
new file mode 100644
index 0000000..bfbce5c
--- /dev/null
+++ b/src/core/config-upgrader/upgradeConfigToV4.test.ts
@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const getRawMock = vi.fn();
+const saveRawMock = vi.fn();
+
+vi.mock('../io/KGConfigStorage', () => ({
+  KGConfigStorage: {
+    getInstance: vi.fn(() => ({
+      getRaw: getRawMock,
+      saveRaw: saveRawMock,
+    })),
+  },
+}));
+
+import { upgradeConfigToV4 } from './upgradeConfigToV4';
+
+describe('upgradeConfigToV4', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('creates the audio config and defaults bounce_starts_from_beat_1 to true when audio is missing', async () => {
+    const config: Record<string, unknown> = {
+      general: {},
+    };
+    getRawMock.mockResolvedValue(config);
+
+    await upgradeConfigToV4();
+
+    expect(config.audio).toEqual({ bounce_starts_from_beat_1: true });
+    expect(saveRawMock).toHaveBeenCalledWith('userConfig', config);
+  });
+
+  it('defaults bounce_starts_from_beat_1 to true when the key is missing', async () => {
+    const config: Record<string, unknown> = {
+      audio: {
+        playback_delay: 0.2,
+      },
+    };
+    getRawMock.mockResolvedValue(config);
+
+    await upgradeConfigToV4();
+
+    expect(config.audio).toEqual({
+      playback_delay: 0.2,
+      bounce_starts_from_beat_1: true,
+    });
+    expect(saveRawMock).toHaveBeenCalledWith('userConfig', config);
+  });
+
+  it('preserves an explicit false value', async () => {
+    const config: Record<string, unknown> = {
+      audio: {
+        bounce_starts_from_beat_1: false,
+      },
+    };
+    getRawMock.mockResolvedValue(config);
+
+    await upgradeConfigToV4();
+
+    expect(saveRawMock).not.toHaveBeenCalled();
+    expect((config.audio as Record<string, unknown>).bounce_starts_from_beat_1).toBe(false);
+  });
+});
diff --git a/src/core/config-upgrader/upgradeConfigToV4.ts b/src/core/config-upgrader/upgradeConfigToV4.ts
new file mode 100644
index 0000000..c592dea
--- /dev/null
+++ b/src/core/config-upgrader/upgradeConfigToV4.ts
@@ -0,0 +1,30 @@
+import { KGConfigStorage } from '../io/KGConfigStorage';
+
+const CONFIG_KEY = 'userConfig';
+
+export async function upgradeConfigToV4(): Promise<void> {
+  const storage = KGConfigStorage.getInstance();
+  const rawConfig = await storage.getRaw(CONFIG_KEY);
+  if (!rawConfig || typeof rawConfig !== 'object') {
+    return;
+  }
+
+  const config = rawConfig as Record<string, unknown>;
+  const audio = config.audio;
+
+  if (!audio || typeof audio !== 'object') {
+    config.audio = {
+      bounce_starts_from_beat_1: true,
+    };
+    await storage.saveRaw(CONFIG_KEY, config);
+    return;
+  }
+
+  const audioRecord = audio as Record<string, unknown>;
+  if ('bounce_starts_from_beat_1' in audioRecord) {
+    return;
+  }
+
+  audioRecord.bounce_starts_from_beat_1 = true;
+  await storage.saveRaw(CONFIG_KEY, config);
+}
diff --git a/src/core/config/ConfigManager.ts b/src/core/config/ConfigManager.ts
index 0b6a102..1886049 100644
--- a/src/core/config/ConfigManager.ts
+++ b/src/core/config/ConfigManager.ts
@@ -80,6 +80,7 @@ interface AppConfig {
     default_open: boolean;
   };
   audio: {
+    bounce_starts_from_beat_1: boolean;
     enable_audio_capture_for_screen_sharing: boolean;
     input_device_id: string;
     lookahead_time: number;
@@ -260,6 +261,7 @@ export class ConfigManager {
           default_open: true
         },
         audio: {
+          bounce_starts_from_beat_1: true,
           enable_audio_capture_for_screen_sharing: false,
           input_device_id: 'default',
           lookahead_time: 0.05,