@williamzujkowski/live-coding-music-mcp 1.0.0

package/dist/server/tools/transform.js

@@ -0,0 +1,399 @@
+/**
+ * transform domain — mutate the current pattern.
+ *
+ * Owns (14 tools): transpose, reverse, stretch, quantize, humanize,
+ * add_swing, apply_scale, generate_variation, add_effect, remove_effect,
+ * set_tempo, shift_mood, set_energy, refine.
+ *
+ * Per the #110 audit this eventually collapses into:
+ * - `transform` (op enum) — 8 tools
+ * - `effect` (add/remove enum) — 2 tools
+ * - `shape` (mood/energy/refine enum) — 3 tools
+ * - `set_tempo` stays — high-traffic verb
+ *
+ * For now we keep the individual verbs and just move them out of server.ts.
+ */
+import { InputValidator } from '../../utils/InputValidator.js';
+const ENERGY_LEVELS = {
+    0: { tempoAdjust: -20, roomAmount: 0.5, densityAdjust: '.slow(4)', description: 'minimal/ambient' },
+    1: { tempoAdjust: -15, roomAmount: 0.4, densityAdjust: '.slow(3)', description: 'very sparse' },
+    2: { tempoAdjust: -10, roomAmount: 0.3, densityAdjust: '.slow(2)', description: 'sparse' },
+    3: { tempoAdjust: -5, roomAmount: 0.2, densityAdjust: '.slow(1.5)', description: 'light' },
+    4: { tempoAdjust: 0, roomAmount: 0.15, densityAdjust: '', description: 'relaxed' },
+    5: { tempoAdjust: 0, roomAmount: 0.1, densityAdjust: '', description: 'normal' },
+    6: { tempoAdjust: 5, roomAmount: 0.08, densityAdjust: '', description: 'moderate' },
+    7: { tempoAdjust: 10, roomAmount: 0.05, densityAdjust: '.fast(1.25)', description: 'driving' },
+    8: { tempoAdjust: 15, roomAmount: 0.03, densityAdjust: '.fast(1.5)', description: 'intense' },
+    9: { tempoAdjust: 18, roomAmount: 0.02, densityAdjust: '.fast(1.75)', description: 'very intense' },
+    10: { tempoAdjust: 20, roomAmount: 0.01, densityAdjust: '.fast(2)', description: 'maximum' },
+};
+const MOOD_PROFILES = {
+    dark: { preferMinor: true, tempoMod: -0.1, cutoffMod: -200, roomMod: 0.2, gainMod: -0.1, noteShift: -12 },
+    euphoric: { preferMinor: false, tempoMod: 0.1, cutoffMod: 400, roomMod: 0.1, gainMod: 0.1, noteShift: 12 },
+    melancholic: { preferMinor: true, tempoMod: -0.15, cutoffMod: -100, roomMod: 0.3, gainMod: -0.05, noteShift: 0 },
+    aggressive: { preferMinor: false, tempoMod: 0.15, cutoffMod: 600, roomMod: -0.1, gainMod: 0.15, noteShift: 0 },
+    dreamy: { preferMinor: false, tempoMod: -0.2, cutoffMod: -300, roomMod: 0.4, delayMod: 0.3, gainMod: -0.1, noteShift: 0 },
+    peaceful: { preferMinor: false, tempoMod: -0.25, cutoffMod: -200, roomMod: 0.25, gainMod: -0.15, noteShift: 0 },
+    energetic: { preferMinor: false, tempoMod: 0.2, cutoffMod: 300, roomMod: 0, gainMod: 0.1, noteShift: 0 },
+};
+function transposePattern(pattern, semitones) {
+    return pattern.replace(/([a-g][#b]?)(\d)/gi, (_match, note, octave) => {
+        const noteMap = {
+            'c': 0, 'c#': 1, 'd': 2, 'd#': 3, 'e': 4, 'f': 5,
+            'f#': 6, 'g': 7, 'g#': 8, 'a': 9, 'a#': 10, 'b': 11,
+        };
+        const currentNote = note.toLowerCase();
+        const noteValue = noteMap[currentNote] || 0;
+        const newNoteValue = (noteValue + semitones + 12) % 12;
+        const noteNames = ['c', 'c#', 'd', 'd#', 'e', 'f', 'f#', 'g', 'g#', 'a', 'a#', 'b'];
+        const newOctave = parseInt(octave) + Math.floor((noteValue + semitones) / 12);
+        return noteNames[newNoteValue] + newOctave;
+    });
+}
+export const tools = [
+    {
+        name: 'transpose',
+        description: 'Transpose notes by semitones',
+        inputSchema: {
+            type: 'object',
+            properties: { semitones: { type: 'number', description: 'Semitones to transpose' } },
+            required: ['semitones'],
+        },
+    },
+    {
+        name: 'reverse',
+        description: 'Reverse pattern',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'stretch',
+        description: 'Time stretch pattern',
+        inputSchema: {
+            type: 'object',
+            properties: { factor: { type: 'number', description: 'Stretch factor' } },
+            required: ['factor'],
+        },
+    },
+    {
+        name: 'quantize',
+        description: 'Quantize to grid',
+        inputSchema: {
+            type: 'object',
+            properties: { grid: { type: 'string', description: 'Grid size (e.g., "1/16")' } },
+            required: ['grid'],
+        },
+    },
+    {
+        name: 'humanize',
+        description: 'Add human timing variation',
+        inputSchema: {
+            type: 'object',
+            properties: { amount: { type: 'number', description: 'Humanization amount (0-1)' } },
+        },
+    },
+    {
+        name: 'generate_variation',
+        description: 'Create pattern variations',
+        inputSchema: {
+            type: 'object',
+            properties: { type: { type: 'string', description: 'Variation type (subtle/moderate/extreme/glitch/evolving)' } },
+        },
+    },
+    {
+        name: 'add_effect',
+        description: 'Add effect to pattern',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                effect: { type: 'string', description: 'Effect name' },
+                params: { type: 'string', description: 'Effect parameters' },
+            },
+            required: ['effect'],
+        },
+    },
+    {
+        name: 'remove_effect',
+        description: 'Remove effect',
+        inputSchema: {
+            type: 'object',
+            properties: { effect: { type: 'string', description: 'Effect to remove' } },
+            required: ['effect'],
+        },
+    },
+    {
+        name: 'set_tempo',
+        description: 'Set BPM',
+        inputSchema: {
+            type: 'object',
+            properties: { bpm: { type: 'number', description: 'Tempo in BPM' } },
+            required: ['bpm'],
+        },
+    },
+    {
+        name: 'add_swing',
+        description: 'Add swing to pattern',
+        inputSchema: {
+            type: 'object',
+            properties: { amount: { type: 'number', description: 'Swing amount (0-1)' } },
+            required: ['amount'],
+        },
+    },
+    {
+        name: 'apply_scale',
+        description: 'Apply scale to notes',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scale: { type: 'string', description: 'Scale name' },
+                root: { type: 'string', description: 'Root note' },
+            },
+            required: ['scale', 'root'],
+        },
+    },
+    {
+        name: 'shift_mood',
+        description: 'Transform current pattern to match a different emotional mood by adjusting tempo, effects, and note choices. Moods: dark, euphoric, melancholic, aggressive, dreamy, peaceful, energetic.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target_mood: {
+                    type: 'string',
+                    enum: ['dark', 'euphoric', 'melancholic', 'aggressive', 'dreamy', 'peaceful', 'energetic'],
+                    description: 'Target mood',
+                },
+                intensity: { type: 'number', minimum: 0, maximum: 1, description: 'How strongly to apply the mood transformation (0-1, default: 0.5)' },
+                auto_play: { type: 'boolean', description: 'Start playback after transformation (default: true)' },
+            },
+            required: ['target_mood'],
+        },
+    },
+    {
+        name: 'set_energy',
+        description: 'Adjust the overall energy level of the current pattern on a 0-10 scale. 0: minimal/ambient, 1-2: sparse, 3-4: light/relaxed, 5-6: normal/moderate, 7-8: driving/intense, 9-10: maximum. Auto-plays after applying energy level.',
+        inputSchema: {
+            type: 'object',
+            properties: { level: { type: 'number', description: 'Energy level from 0 (minimal) to 10 (maximum)' } },
+            required: ['level'],
+        },
+    },
+    {
+        name: 'refine',
+        description: 'Incrementally refine the current pattern with simple directional commands. Supports: faster/slower (tempo), louder/quieter (gain), brighter/darker (filter cutoff), "more reverb"/drier (reverb). Auto-plays after applying refinement.',
+        inputSchema: {
+            type: 'object',
+            properties: { direction: { type: 'string', description: 'Refinement direction: faster, slower, louder, quieter, brighter, darker, "more reverb", or drier' } },
+            required: ['direction'],
+        },
+    },
+];
+export const toolNames = new Set(tools.map(t => t.name));
+export async function execute(name, args, ctx) {
+    switch (name) {
+        case 'transpose': {
+            if (typeof args.semitones !== 'number' || !Number.isInteger(args.semitones)) {
+                throw new Error('Semitones must be an integer');
+            }
+            const p = await ctx.getCurrentPatternSafe();
+            await ctx.writePatternSafe(transposePattern(p, args.semitones));
+            return `Transposed ${args.semitones} semitones`;
+        }
+        case 'reverse': {
+            const p = await ctx.getCurrentPatternSafe();
+            await ctx.writePatternSafe(p + '.rev');
+            return 'Pattern reversed';
+        }
+        case 'stretch': {
+            InputValidator.validateGain(args.factor);
+            const p = await ctx.getCurrentPatternSafe();
+            await ctx.writePatternSafe(p + `.slow(${args.factor})`);
+            return `Stretched by factor of ${args.factor}`;
+        }
+        case 'quantize': {
+            InputValidator.validateStringLength(args.grid, 'grid', 50, false);
+            const p = await ctx.getCurrentPatternSafe();
+            await ctx.writePatternSafe(p + `.struct("${args.grid}")`);
+            return `Quantized to ${args.grid} grid`;
+        }
+        case 'humanize': {
+            if (args.amount !== undefined)
+                InputValidator.validateNormalizedValue(args.amount, 'amount');
+            const p = await ctx.getCurrentPatternSafe();
+            const amt = args.amount || 0.01;
+            await ctx.writePatternSafe(p + `.nudge(rand.range(-${amt}, ${amt}))`);
+            return 'Added human timing';
+        }
+        case 'generate_variation': {
+            const p = await ctx.getCurrentPatternSafe();
+            const varied = ctx.generator.generateVariation(p, args.type || 'subtle');
+            await ctx.writePatternSafe(varied);
+            return `Added ${args.type || 'subtle'} variation`;
+        }
+        case 'add_effect': {
+            InputValidator.validateStringLength(args.effect, 'effect', 100, false);
+            if (args.params)
+                InputValidator.validateStringLength(args.params, 'params', 1000, true);
+            const p = await ctx.getCurrentPatternSafe();
+            const withEffect = args.params
+                ? p + `.${args.effect}(${args.params})`
+                : p + `.${args.effect}()`;
+            await ctx.writePatternSafe(withEffect);
+            return `Added ${args.effect} effect`;
+        }
+        case 'remove_effect': {
+            InputValidator.validateStringLength(args.effect, 'effect', 100, false);
+            const p = await ctx.getCurrentPatternSafe();
+            const regex = new RegExp(`\\.${args.effect}\\([^)]*\\)`, 'g');
+            const stripped = p.replace(regex, '');
+            if (stripped === p)
+                return `No ${args.effect} effect found to remove`;
+            await ctx.writePatternSafe(stripped);
+            return `Removed ${args.effect} effect`;
+        }
+        case 'set_tempo': {
+            InputValidator.validateBPM(args.bpm);
+            const p = await ctx.getCurrentPatternSafe();
+            await ctx.writePatternSafe(`setcpm(${args.bpm})\n${p}`);
+            return `Set tempo to ${args.bpm} BPM`;
+        }
+        case 'add_swing': {
+            InputValidator.validateNormalizedValue(args.amount, 'amount');
+            const p = await ctx.getCurrentPatternSafe();
+            await ctx.writePatternSafe(p + `.swing(${args.amount})`);
+            return `Added swing: ${args.amount}`;
+        }
+        case 'apply_scale': {
+            InputValidator.validateStringLength(args.scale, 'scale', 50, false);
+            InputValidator.validateRootNote(args.root);
+            const p = await ctx.getCurrentPatternSafe();
+            await ctx.writePatternSafe(p + `.scale("${args.root}:${args.scale}")`);
+            return `Applied ${args.root} ${args.scale} scale`;
+        }
+        case 'shift_mood':
+            return await shiftMood(args, ctx);
+        case 'set_energy':
+            return await setEnergyLevel(args.level, ctx);
+        case 'refine':
+            return await refinePattern(args.direction, ctx);
+        default:
+            throw new Error(`transform module does not handle tool: ${name}`);
+    }
+}
+async function shiftMood(args, ctx) {
+    const mood = args.target_mood?.toLowerCase()?.trim();
+    const profile = MOOD_PROFILES[mood];
+    if (!profile) {
+        return {
+            success: false,
+            error: `Unknown mood: ${args.target_mood}. Valid moods: ${Object.keys(MOOD_PROFILES).join(', ')}.`,
+        };
+    }
+    const pattern = await ctx.getCurrentPatternSafe();
+    if (!pattern || pattern.trim().length === 0) {
+        return { success: false, error: 'No pattern to transform. Write a pattern first.' };
+    }
+    const intensity = args.intensity ?? 0.5;
+    if (intensity < 0 || intensity > 1) {
+        return { success: false, error: 'Intensity must be between 0 and 1.' };
+    }
+    const applied = [];
+    let result = pattern;
+    if (profile.tempoMod !== 0) {
+        const adjust = 1 + (profile.tempoMod * intensity);
+        if (adjust > 1) {
+            result += `.fast(${adjust.toFixed(2)})`;
+            applied.push(`tempo +${Math.round(profile.tempoMod * 100 * intensity)}%`);
+        }
+        else {
+            result += `.slow(${(1 / adjust).toFixed(2)})`;
+            applied.push(`tempo ${Math.round(profile.tempoMod * 100 * intensity)}%`);
+        }
+    }
+    if (profile.cutoffMod !== 0) {
+        const base = 1000;
+        const cutoff = Math.max(200, base + (profile.cutoffMod * intensity));
+        result += `.lpf(${Math.round(cutoff)})`;
+        applied.push(`cutoff ${profile.cutoffMod > 0 ? '+' : ''}${Math.round(profile.cutoffMod * intensity)}Hz`);
+    }
+    if (profile.roomMod !== 0) {
+        const room = Math.max(0, Math.min(1, profile.roomMod * intensity));
+        result += `.room(${room.toFixed(2)})`;
+        applied.push(`reverb ${room.toFixed(2)}`);
+    }
+    if (profile.delayMod && profile.delayMod > 0) {
+        const d = profile.delayMod * intensity;
+        result += `.delay(${d.toFixed(2)})`;
+        applied.push(`delay ${d.toFixed(2)}`);
+    }
+    if (profile.gainMod !== 0) {
+        const g = 1 + (profile.gainMod * intensity);
+        result += `.gain(${g.toFixed(2)})`;
+        applied.push(`gain ${profile.gainMod > 0 ? '+' : ''}${Math.round(profile.gainMod * 100 * intensity)}%`);
+    }
+    await ctx.writePatternSafe(result);
+    if (args.auto_play !== false && ctx.isInitialized()) {
+        await ctx.controller.play();
+    }
+    return { success: true, target_mood: mood, intensity, applied_effects: applied };
+}
+async function setEnergyLevel(level, ctx) {
+    if (level < 0 || level > 10 || !Number.isInteger(level)) {
+        return { success: false, error: 'Energy level must be an integer from 0 to 10.' };
+    }
+    const pattern = await ctx.getCurrentPatternSafe();
+    if (!pattern || pattern.trim().length === 0) {
+        return { success: false, error: 'No pattern to adjust. Write a pattern first.' };
+    }
+    const config = ENERGY_LEVELS[level];
+    let result = pattern;
+    if (config.densityAdjust)
+        result += config.densityAdjust;
+    result += `.room(${config.roomAmount})`;
+    await ctx.writePatternSafe(result);
+    if (ctx.isInitialized())
+        await ctx.controller.play();
+    return { success: true, level, description: config.description };
+}
+async function refinePattern(direction, ctx) {
+    const pattern = await ctx.getCurrentPatternSafe();
+    if (!pattern || pattern.trim().length === 0) {
+        return { success: false, error: 'No pattern to refine. Write a pattern first.' };
+    }
+    const dir = direction.toLowerCase().trim();
+    let modification = '';
+    switch (dir) {
+        case 'faster':
+            modification = '.fast(1.1)';
+            break;
+        case 'slower':
+            modification = '.slow(1.1)';
+            break;
+        case 'louder':
+            modification = '.gain(1.1)';
+            break;
+        case 'quieter':
+            modification = '.gain(0.9)';
+            break;
+        case 'brighter':
+            modification = '.lpf(2000)';
+            break;
+        case 'darker':
+            modification = '.lpf(800)';
+            break;
+        case 'more reverb':
+            modification = '.room(0.5)';
+            break;
+        case 'drier':
+            modification = '.room(0.1)';
+            break;
+        default:
+            return {
+                success: false,
+                error: `Unknown refinement direction: ${direction}. Supported: faster, slower, louder, quieter, brighter, darker, "more reverb", drier.`,
+            };
+    }
+    await ctx.writePatternSafe(pattern + modification);
+    if (ctx.isInitialized())
+        await ctx.controller.play();
+    return { success: true, direction: dir, applied: modification };
+}
+export const transformModule = { tools, toolNames, execute };

package/dist/server/tools/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared types for the per-domain tool modules under src/server/tools/.
+ *
+ * Part of the file-split work tracked in #104. Each domain file exports a
+ * `tools` array of MCP tool definitions and an `execute(name, args, ctx)`
+ * dispatcher. The server keeps the MCP protocol layer thin and delegates
+ * to these modules.
+ */
+export {};

package/dist/services/AudioCaptureService.js

@@ -0,0 +1,279 @@
+import { Logger } from '../utils/Logger.js';
+/**
+ * AudioCaptureService captures audio from Strudel's output using MediaRecorder API.
+ *
+ * Uses the same GainNode interception pattern as AudioAnalyzer to connect
+ * a MediaStreamDestination for recording without interfering with playback.
+ *
+ * @example
+ * const capture = new AudioCaptureService();
+ * await capture.injectRecorder(page);
+ * const result = await capture.captureForDuration(page, 5000);
+ * // result.blob contains WebM/Opus audio data
+ */
+export class AudioCaptureService {
+    logger = new Logger();
+    _isCapturing = false;
+    _startTime = 0;
+    // Default configuration
+    DEFAULT_FORMAT = 'webm';
+    DEFAULT_SAMPLE_RATE = 48000;
+    DEFAULT_DURATION_MS = 5000;
+    MIME_TYPE = 'audio/webm;codecs=opus';
+    /**
+     * Injects audio capture code into the Strudel page.
+     * Must be called before any capture operations.
+     *
+     * @param page - Playwright page instance to inject into
+     * @throws {Error} When injection fails
+     */
+    async injectRecorder(page) {
+        /* istanbul ignore next -- browser-injected IIFE, covered by integration tests */
+        await page.evaluate(() => {
+            window.strudelAudioCapture = {
+                mediaStreamDest: null,
+                recorder: null,
+                isConnected: false,
+                isCapturing: false,
+                startTime: 0,
+                chunks: [],
+                error: null,
+                /**
+                 * Connects to Strudel's audio output via GainNode interception
+                 */
+                connect() {
+                    const originalGainConnect = GainNode.prototype.connect;
+                    let intercepted = false;
+                    GainNode.prototype.connect = function (...args) {
+                        if (!intercepted && args[0] && args[0].context) {
+                            intercepted = true;
+                            const ctx = args[0].context;
+                            const capture = window.strudelAudioCapture;
+                            // Create MediaStreamDestination for recording
+                            capture.mediaStreamDest = ctx.createMediaStreamDestination();
+                            // Connect GainNode to both original destination and our capture node
+                            const result = originalGainConnect.apply(this, args);
+                            originalGainConnect.call(this, capture.mediaStreamDest);
+                            capture.isConnected = true;
+                            return result;
+                        }
+                        return originalGainConnect.apply(this, args);
+                    };
+                },
+                /**
+                 * Starts audio capture
+                 * @returns Success status and any error message
+                 */
+                startCapture() {
+                    const capture = window.strudelAudioCapture;
+                    if (!capture.isConnected || !capture.mediaStreamDest) {
+                        return {
+                            success: false,
+                            error: 'Audio capture not connected. Play a pattern first to initialize audio.'
+                        };
+                    }
+                    if (capture.isCapturing) {
+                        return { success: false, error: 'Capture already in progress.' };
+                    }
+                    try {
+                        // Reset state
+                        capture.chunks = [];
+                        capture.error = null;
+                        // Create MediaRecorder with WebM/Opus codec (Gemini compatible)
+                        const options = {
+                            mimeType: 'audio/webm;codecs=opus'
+                        };
+                        capture.recorder = new MediaRecorder(capture.mediaStreamDest.stream, options);
+                        capture.recorder.ondataavailable = (event) => {
+                            if (event.data.size > 0) {
+                                capture.chunks.push(event.data);
+                            }
+                        };
+                        capture.recorder.onerror = (event) => {
+                            capture.error = 'MediaRecorder error occurred';
+                            capture.isCapturing = false;
+                        };
+                        capture.recorder.onstop = () => {
+                            capture.isCapturing = false;
+                        };
+                        capture.startTime = Date.now();
+                        capture.isCapturing = true;
+                        capture.recorder.start(100); // Collect data every 100ms
+                        return { success: true };
+                    }
+                    catch (err) {
+                        return { success: false, error: err.message || 'Failed to start capture' };
+                    }
+                },
+                /**
+                 * Stops audio capture and returns recorded data
+                 * @returns Recorded audio data or error
+                 */
+                async stopCapture() {
+                    const capture = window.strudelAudioCapture;
+                    if (!capture.recorder || !capture.isCapturing) {
+                        return { success: false, error: 'No capture in progress.' };
+                    }
+                    return new Promise((resolve) => {
+                        const recorder = capture.recorder;
+                        const startTime = capture.startTime;
+                        recorder.onstop = () => {
+                            capture.isCapturing = false;
+                            const duration = Date.now() - startTime;
+                            if (capture.chunks.length === 0) {
+                                resolve({ success: false, error: 'No audio data captured.' });
+                                return;
+                            }
+                            const blob = new Blob(capture.chunks, { type: 'audio/webm;codecs=opus' });
+                            capture.chunks = [];
+                            resolve({
+                                success: true,
+                                blob,
+                                duration,
+                                format: 'audio/webm;codecs=opus'
+                            });
+                        };
+                        recorder.stop();
+                    });
+                },
+                /**
+                 * Returns current capture state
+                 */
+                getState() {
+                    const capture = window.strudelAudioCapture;
+                    return {
+                        isCapturing: capture.isCapturing,
+                        startTime: capture.startTime,
+                        chunks: capture.chunks
+                    };
+                }
+            };
+            // Initialize connection interception
+            window.strudelAudioCapture.connect();
+        });
+        this.logger.debug('Audio capture injected');
+    }
+    /**
+     * Starts audio capture on the page.
+     *
+     * @param page - Playwright page instance
+     * @param config - Optional capture configuration
+     * @throws {Error} When capture fails to start
+     */
+    async startCapture(page, config) {
+        const result = await page.evaluate(/* istanbul ignore next */ () => {
+            const capture = window.strudelAudioCapture;
+            if (!capture) {
+                return { success: false, error: 'Audio capture not initialized. Call injectRecorder first.' };
+            }
+            return capture.startCapture();
+        });
+        if (!result.success) {
+            throw new Error(result.error || 'Failed to start capture');
+        }
+        this._isCapturing = true;
+        this._startTime = Date.now();
+        this.logger.debug('Audio capture started');
+    }
+    /**
+     * Stops audio capture and returns the recorded audio.
+     *
+     * @param page - Playwright page instance
+     * @returns Captured audio result with blob, duration, and format
+     * @throws {Error} When capture fails or no data was recorded
+     */
+    async stopCapture(page) {
+        const result = await page.evaluate(/* istanbul ignore next */ async () => {
+            const capture = window.strudelAudioCapture;
+            if (!capture) {
+                return { success: false, error: 'Audio capture not initialized.' };
+            }
+            return await capture.stopCapture();
+        });
+        this._isCapturing = false;
+        if (!result.success) {
+            throw new Error(result.error || 'Failed to stop capture');
+        }
+        this.logger.debug(`Audio capture stopped: ${result.duration}ms`);
+        return {
+            blob: result.blob,
+            duration: result.duration,
+            format: result.format,
+            timestamp: Date.now()
+        };
+    }
+    /**
+     * Captures audio for a specified duration.
+     * Convenience method that handles start, wait, and stop.
+     *
+     * @param page - Playwright page instance
+     * @param durationMs - Duration to record in milliseconds (default: 5000)
+     * @returns Captured audio result
+     * @throws {Error} When capture fails
+     *
+     * @example
+     * const result = await capture.captureForDuration(page, 5000);
+     * console.log(`Captured ${result.duration}ms of audio`);
+     */
+    async captureForDuration(page, durationMs) {
+        const duration = durationMs ?? this.DEFAULT_DURATION_MS;
+        await this.startCapture(page);
+        // Wait for the specified duration
+        await new Promise(resolve => setTimeout(resolve, duration));
+        return await this.stopCapture(page);
+    }
+    /**
+     * Returns whether audio capture is currently in progress.
+     *
+     * @returns True if capturing, false otherwise
+     */
+    isCapturing() {
+        return this._isCapturing;
+    }
+    /**
+     * Returns the elapsed capture time in milliseconds.
+     * Returns 0 if not currently capturing.
+     *
+     * @returns Elapsed time in milliseconds
+     */
+    getElapsedTime() {
+        if (!this._isCapturing) {
+            return 0;
+        }
+        return Date.now() - this._startTime;
+    }
+    /**
+     * Checks if audio capture is connected to Strudel's audio output.
+     *
+     * @param page - Playwright page instance
+     * @returns Connection status
+     */
+    async isConnected(page) {
+        return await page.evaluate(/* istanbul ignore next */ () => {
+            const capture = window.strudelAudioCapture;
+            return capture?.isConnected ?? false;
+        });
+    }
+    /**
+     * Clears any recorded chunks without stopping capture.
+     * Useful for discarding unwanted audio.
+     *
+     * @param page - Playwright page instance
+     */
+    async clearChunks(page) {
+        await page.evaluate(/* istanbul ignore next */ () => {
+            const capture = window.strudelAudioCapture;
+            if (capture) {
+                capture.chunks = [];
+            }
+        });
+    }
+    /**
+     * Gets the MIME type used for recording.
+     *
+     * @returns MIME type string
+     */
+    getMimeType() {
+        return this.MIME_TYPE;
+    }
+}