meeting-assistant/openspec/changes/recover-microphone-disconnect/specs/meeting-recording/spec.md

MODIFIED Requirements

Requirement: Recording mode captures microphone and computer output

Meeting Assistant SHALL capture microphone input and computer output and combine them into one audio stream for transcription.

Meeting Assistant SHALL capture audio as 16 kHz mono PCM chunks for the existing recording and transcription pipeline.

Meeting Assistant SHALL capture microphone and system loopback as separate input streams before producing the final mono chunks.

Meeting Assistant SHALL clean the microphone stream with a local acoustic echo cancellation stage that uses system loopback as the far-end reference.

Meeting Assistant SHALL produce final mono chunks by adding the cleaned microphone samples and system samples.

Meeting Assistant SHALL align microphone and system samples through per-source buffers before mixing and SHALL NOT emit normal live audio chunks that contain only one source while the other source is merely delayed.

When one source stays quiet beyond the alignment timeout, Meeting Assistant SHALL mix the available source with synthetic silence for the missing source instead of blocking transcription.

Meeting Assistant SHALL allow the final microphone/system mono mix to apply configurable microphone and system gain before combining samples.

Meeting Assistant SHALL use the active run or launch profile recording options when configuring capture format and final microphone/system gains.

Meeting Assistant SHALL clamp mixed samples after gain is applied.

Meeting Assistant SHALL write only the mixed stream to the temporary WAV used by transcription and finalization.

Meeting Assistant SHALL allow Recording:MicrophoneDeviceId to select a Windows microphone capture endpoint.

When Recording:MicrophoneDeviceId is blank or absent, Meeting Assistant SHALL use the Windows default capture endpoint.

When a microphone is selected from the tray icon menu, Meeting Assistant SHALL use that selected microphone for later recording starts until another microphone is selected or the process exits.

The tray icon right-click menu SHALL expose a Microphone submenu listing active microphone capture endpoints.

The Microphone submenu SHALL mark exactly one effective microphone as checked.

When no runtime microphone override is selected, the checked microphone SHALL be the configured microphone when it is available, otherwise the Windows default capture endpoint.

When the active microphone endpoint disappears, microphone capture fails, or microphone capture stops unexpectedly while a meeting recording is active, Meeting Assistant SHALL keep the meeting recording active and SHALL repeatedly re-resolve and restart microphone capture until capture succeeds or the recording is stopped.

Each microphone recovery attempt SHALL re-enumerate active microphone endpoints and apply the existing runtime-selected, configured, and Windows-default selection rules so an available endpoint can take over.

While microphone recovery is pending, Meeting Assistant SHALL keep system-loopback capture active and SHALL continue producing mixed audio with synthetic silence for the missing microphone stream.

Scenario: Both sources produce audio

• WHEN microphone and computer output audio chunks are available
• THEN Meeting Assistant mixes them into one PCM stream before transcription

Scenario: Mixed audio uses cleaned microphone and system audio

• GIVEN the echo canceller cleans a microphone chunk to sample 2000
• AND the matching system chunk has sample 10000
• WHEN microphone and system chunks are mixed with gains 1 and 1
• THEN the mixed sample is 12000

Scenario: Temporary recording stores only the mixed stream

• GIVEN Meeting Assistant has mixed microphone and system audio into one PCM chunk
• WHEN Meeting Assistant appends the chunk to the temporary recording
• THEN the main temporary WAV contains the mixed PCM
• AND no microphone or system sidecar WAV is written

Scenario: Launch profile recording options configure capture and gains

• GIVEN an active launch profile configures sample format and microphone/system mix gains
• WHEN Meeting Assistant captures and mixes audio for that run
• THEN the microphone and system capture sources receive that launch profile recording configuration
• AND the mixed output uses that launch profile's microphone/system gains

Scenario: Delayed sources are buffered before mixing

• GIVEN microphone audio arrives before matching system audio
• WHEN matching system audio arrives after a short delay
• THEN Meeting Assistant emits one mixed chunk for the aligned samples
• AND it does not emit separate microphone-only and system-only chunks for that delayed pair

Scenario: Quiet system audio does not block microphone transcription

• GIVEN microphone audio arrives
• AND system loopback audio does not arrive within the alignment timeout
• WHEN Meeting Assistant mixes the available audio
• THEN it emits the microphone audio mixed with silent system audio
• AND live transcription can continue while system loopback is quiet

Scenario: Continuous microphone audio does not suppress the alignment timeout

• GIVEN microphone audio keeps arriving
• AND system loopback audio stays unavailable past the alignment timeout
• WHEN Meeting Assistant checks the buffered microphone audio
• THEN it emits the buffered microphone audio mixed with silent system audio
• AND it does not wait indefinitely for a loopback chunk

Scenario: Device-level capture cannot be verified in tests

• WHEN automated tests run without live audio devices
• THEN Meeting Assistant verifies the audio mixer through deterministic source abstractions rather than depending on physical microphone or speaker devices

Scenario: Configured microphone is used for capture

• GIVEN Recording:MicrophoneDeviceId identifies an active microphone endpoint
• WHEN Meeting Assistant starts microphone capture
• THEN it captures from that endpoint

Scenario: Blank microphone setting uses Windows default

• GIVEN Recording:MicrophoneDeviceId is blank
• WHEN Meeting Assistant starts microphone capture
• THEN it captures from the Windows default capture endpoint

Scenario: Tray menu lists microphones with current selection checked

• GIVEN active microphone endpoints integrated microphone and other microphone
• AND integrated microphone is the effective microphone
• WHEN the taskbar menu is opened
• THEN it shows a Microphone submenu
• AND the integrated microphone item is checked
• AND the other microphone item is unchecked

Scenario: Tray microphone selection changes later capture

• GIVEN active microphone endpoints integrated microphone and other microphone
• WHEN the user selects other microphone from the taskbar microphone submenu
• THEN later recording starts capture from other microphone

Scenario: Disconnected microphone fails over during recording

• GIVEN a meeting is actively recording from one microphone and another microphone is available
• WHEN the active microphone is disconnected and its capture fails
• THEN the meeting recording remains active
• AND Meeting Assistant re-resolves the effective microphone and resumes capture from the available microphone

Scenario: Recording continues while no microphone is available

• GIVEN a meeting is actively recording
• WHEN the active microphone disconnects and no microphone is temporarily available
• THEN Meeting Assistant keeps the meeting recording and system-loopback capture active
• AND emits system audio mixed with synthetic microphone silence
• WHEN a microphone becomes available
• THEN Meeting Assistant resumes microphone capture for the same meeting run