tjbot-ce 3.0.1

package/dist/servo/servo-lgpio.js

@@ -0,0 +1,178 @@
+/**
+ * Copyright 2025 IBM Corp. All Rights Reserved.
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { createRequire } from 'module';
+import { getLogger } from '../utils/logging.js';
+import { TJBotError } from '../utils/errors.js';
+import { MAX_PULSE_MS, MID_PULSE_MS, MIN_PULSE_MS } from './servo-constants.js';
+const logger = getLogger(import.meta.url);
+const require = createRequire(import.meta.url);
+// lgpio is published as CommonJS; createRequire avoids ESM namespace interop issues.
+const lgpio = require('lgpio');
+/**
+ * Servo controller using lgpio on Raspberry Pi GPIO character devices
+ */
+export class LGPIOServoController {
+    chipNumber;
+    pin;
+    freq;
+    chipHandle;
+    claimed = false;
+    currentPulseMs;
+    running;
+    autoStopTimer;
+    autoStopDelayMs;
+    /**
+     * Create a LGPIOServoController instance
+     * @param chipNumber GPIO chip number (usually 0)
+     * @param pin GPIO pin number (BCM)
+     * @param freq PWM frequency in Hz (default 50 for standard servos)
+     */
+    constructor(chipNumber, pin, freq = 50, autoStopDelayMs = 2000) {
+        this.chipNumber = chipNumber;
+        this.pin = pin;
+        this.freq = freq;
+        this.currentPulseMs = MID_PULSE_MS;
+        this.running = false;
+        this.autoStopDelayMs = autoStopDelayMs;
+        logger.debug(`LGPIOServoController initialized with config:
+            chip: ${chipNumber}
+            pin: ${pin}
+            frequency: ${freq} Hz`);
+    }
+    /**
+     * Set the servo to a specific position.
+     * @param position Servo position in microseconds (500-2500 for standard servos)
+     */
+    setPosition(position) {
+        const pulseMs = position / 1000;
+        logger.verbose(`setting servo position to ${position} μs (${pulseMs} ms)`);
+        this.setPulseWidth(pulseMs);
+    }
+    ensureStarted() {
+        if (this.running)
+            return;
+        logger.debug('starting LGPIOServoController');
+        const handle = lgpio.gpiochipOpen(this.chipNumber);
+        lgpio.gpioClaimOutput(handle, this.pin);
+        this.chipHandle = handle;
+        this.claimed = true;
+        this.running = true;
+    }
+    setServoPulse(pulseMs) {
+        if (this.chipHandle === undefined) {
+            throw new TJBotError('Servo GPIO is not initialized');
+        }
+        logger.debug(`setting servo pulse: ${pulseMs.toFixed(2)} ms`);
+        const periodMs = 1000 / this.freq;
+        const dutyCycle = Math.max(0, Math.min(100, (pulseMs / periodMs) * 100));
+        // 0 cycles means continuous output until changed.
+        lgpio.txPwm(this.chipHandle, this.pin, this.freq, dutyCycle, 0, 0);
+    }
+    /**
+     * Start the servo controller worker
+     */
+    start() {
+        try {
+            this.ensureStarted();
+            this.setServoPulse(this.currentPulseMs);
+        }
+        catch (err) {
+            logger.error('ServoController failed to start:', err);
+            throw err;
+        }
+    }
+    /**
+     * Stop the servo controller and clean up resources
+     */
+    async stop() {
+        logger.debug('stopping LGPIOServoController');
+        this.running = false;
+        if (this.autoStopTimer) {
+            clearTimeout(this.autoStopTimer);
+            this.autoStopTimer = undefined;
+        }
+        if (this.claimed && this.chipHandle !== undefined) {
+            try {
+                lgpio.txPwm(this.chipHandle, this.pin, this.freq, 0, 0, 0);
+                lgpio.gpioWrite(this.chipHandle, this.pin, false);
+                lgpio.gpioFree(this.chipHandle, this.pin);
+                lgpio.gpiochipClose(this.chipHandle);
+            }
+            catch (err) {
+                logger.warn('ServoController cleanup warning:', err);
+            }
+            finally {
+                this.claimed = false;
+                this.chipHandle = undefined;
+            }
+        }
+    }
+    /**
+     * Set pulse width in milliseconds
+     * Valid range is 0.5-2.5ms for standard servos
+     * @param pulseMs Pulse width in milliseconds
+     */
+    setPulseWidth(pulseMs) {
+        this.currentPulseMs = Math.max(MIN_PULSE_MS, Math.min(MAX_PULSE_MS, pulseMs));
+        this.ensureStarted();
+        this.setServoPulse(this.currentPulseMs);
+        // Reset auto-stop timer
+        if (this.autoStopTimer) {
+            clearTimeout(this.autoStopTimer);
+        }
+        this.autoStopTimer = setTimeout(() => {
+            logger.debug('ServoController auto-stopping after inactivity');
+            this.stop();
+        }, this.autoStopDelayMs);
+    }
+    /**
+     * Set servo angle (0-180 degrees)
+     * 0° = 0.5ms pulse, 90° = 1.5ms pulse, 180° = 2.5ms pulse
+     * @param angle Angle in degrees (0-180)
+     */
+    setAngle(angle) {
+        angle = Math.max(0, Math.min(180, angle));
+        const pulse = MIN_PULSE_MS + (angle / 180.0) * (MAX_PULSE_MS - MIN_PULSE_MS);
+        this.setPulseWidth(pulse);
+    }
+    /**
+     * Get the current pulse width
+     */
+    getPulseWidth() {
+        return this.currentPulseMs;
+    }
+    /**
+     * Get the current angle (approximately)
+     */
+    getAngle() {
+        return Math.round(((this.currentPulseMs - MIN_PULSE_MS) / (MAX_PULSE_MS - MIN_PULSE_MS)) * 180);
+    }
+    /**
+     * Check if the controller is running
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Cleanup and stop the controller
+     */
+    async cleanup() {
+        logger.debug('LGPIOServoController cleanup');
+        await this.stop();
+    }
+}
+//# sourceMappingURL=servo-lgpio.js.map

package/dist/servo/servo-lgpio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"servo-lgpio.js","sourceRoot":"","sources":["../../src/servo/servo-lgpio.ts"],"names":[],"mappings":"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"}

package/dist/speaker/audio-player.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { EventEmitter } from 'events';
+/**
+ * Native audio player that uses aplay for audio playback on Raspbian/ALSA systems
+ * Provides the same API surface as sound-player package
+ */
+export declare class AudioPlayer extends EventEmitter {
+    private process;
+    /**
+     * Play an audio file using aplay
+     * @param audioPath Path to the audio file to play
+     * @param device Optional audio device to use (e.g., 'hw:0,0')
+     */
+    play(audioPath: string, device?: string): void;
+}
+//# sourceMappingURL=audio-player.d.ts.map

package/dist/speaker/audio-player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-player.d.ts","sourceRoot":"","sources":["../../src/speaker/audio-player.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAMtC;;;GAGG;AACH,qBAAa,WAAY,SAAQ,YAAY;IACzC,OAAO,CAAC,OAAO,CAA6B;IAE5C;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;CA2CjD"}

package/dist/speaker/audio-player.js

@@ -0,0 +1,68 @@
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { EventEmitter } from 'events';
+import { spawn } from 'child_process';
+import { getLogger } from '../utils/logging.js';
+const logger = getLogger(import.meta.url);
+/**
+ * Native audio player that uses aplay for audio playback on Raspbian/ALSA systems
+ * Provides the same API surface as sound-player package
+ */
+export class AudioPlayer extends EventEmitter {
+    process = null;
+    /**
+     * Play an audio file using aplay
+     * @param audioPath Path to the audio file to play
+     * @param device Optional audio device to use (e.g., 'hw:0,0')
+     */
+    play(audioPath, device) {
+        const args = [audioPath];
+        // Add device parameter if specified
+        if (device && device !== '') {
+            args.unshift('-D', device);
+        }
+        // Log the command being executed
+        logger.verbose(`Playing audio with command: aplay ${args.join(' ')}`);
+        // Spawn aplay process
+        this.process = spawn('aplay', args, {
+            stdio: ['ignore', 'ignore', 'pipe'], // Only capture stderr for errors
+        });
+        let stderrOutput = '';
+        // Capture stderr for error reporting
+        if (this.process.stderr) {
+            this.process.stderr.on('data', (data) => {
+                stderrOutput += data.toString();
+            });
+        }
+        // Handle process completion
+        this.process.on('close', (code) => {
+            this.process = null;
+            if (code === 0) {
+                this.emit('complete');
+            }
+            else {
+                const error = new Error(`aplay exited with code ${code}: ${stderrOutput}`);
+                this.emit('error', error);
+            }
+        });
+        // Handle process errors (e.g., aplay not found)
+        this.process.on('error', (err) => {
+            this.process = null;
+            this.emit('error', err);
+        });
+    }
+}
+//# sourceMappingURL=audio-player.js.map

package/dist/speaker/audio-player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-player.js","sourceRoot":"","sources":["../../src/speaker/audio-player.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE1C;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,YAAY;IACjC,OAAO,GAAwB,IAAI,CAAC;IAE5C;;;;OAIG;IACH,IAAI,CAAC,SAAiB,EAAE,MAAe;QACnC,MAAM,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QAEzB,oCAAoC;QACpC,IAAI,MAAM,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/B,CAAC;QAED,iCAAiC;QACjC,MAAM,CAAC,OAAO,CAAC,qCAAqC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEtE,sBAAsB;QACtB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YAChC,KAAK,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,iCAAiC;SACzE,CAAC,CAAC;QAEH,IAAI,YAAY,GAAG,EAAE,CAAC;QAEtB,qCAAqC;QACrC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;gBACpC,YAAY,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,CAAC,CAAC,CAAC;QACP,CAAC;QAED,4BAA4B;QAC5B,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YAC9B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YAEpB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACJ,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,0BAA0B,IAAI,KAAK,YAAY,EAAE,CAAC,CAAC;gBAC3E,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAC9B,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,gDAAgD;QAChD,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YAC7B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACP,CAAC;CACJ"}

package/dist/speaker/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright 2025 IBM Corp. All Rights Reserved.
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export { SpeakerController } from './speaker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/speaker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/speaker/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/speaker/index.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright 2025 IBM Corp. All Rights Reserved.
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export { SpeakerController } from './speaker.js';
+//# sourceMappingURL=index.js.map

package/dist/speaker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/speaker/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/speaker/speaker.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright 2025 IBM Corp. All Rights Reserved.
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Speaker controller for TJBot
+ * Handles audio playback and text-to-speech synthesis
+ */
+export declare class SpeakerController {
+    private device;
+    private onPauseCallback?;
+    private onResumeCallback?;
+    constructor();
+    /**
+     * Auto-detect the first available audio playback device
+     * Prefers USB audio devices over HDMI devices
+     * @returns The device string (e.g., 'plughw:0,0') or empty string if none found
+     */
+    private detectSpeakerDevice;
+    /**
+     * Initialize the speaker with configuration
+     * @param device Optional specific audio device to use (auto-detected if not specified)
+     */
+    initialize(device?: string): void;
+    /**
+     * Set callbacks for pause/resume (typically to pause/resume microphone)
+     * @param onPause Callback when audio playback starts
+     * @param onResume Callback when audio playback ends
+     */
+    setAudioLifecycleCallbacks(onPause?: () => void, onResume?: () => void): void;
+    /**
+     * Play audio from a file
+     * @param audioPath Path to the audio file to play
+     */
+    playAudio(audioPath: string): Promise<void>;
+    /**
+     * Clean up resources
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=speaker.d.ts.map

package/dist/speaker/speaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speaker.d.ts","sourceRoot":"","sources":["../../src/speaker/speaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH;;;GAGG;AACH,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,eAAe,CAAC,CAAa;IACrC,OAAO,CAAC,gBAAgB,CAAC,CAAa;;IAMtC;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IA6B3B;;;OAGG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAYjC;;;;OAIG;IACH,0BAA0B,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI;IAK7E;;;OAGG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCjD;;OAEG;IACH,OAAO,IAAI,IAAI;CAGlB"}

package/dist/speaker/speaker.js

@@ -0,0 +1,125 @@
+/**
+ * Copyright 2025 IBM Corp. All Rights Reserved.
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { AudioPlayer } from './audio-player.js';
+import { once } from 'events';
+import { execSync } from 'child_process';
+import { getLogger } from '../utils/logging.js';
+const logger = getLogger(import.meta.url);
+/**
+ * Speaker controller for TJBot
+ * Handles audio playback and text-to-speech synthesis
+ */
+export class SpeakerController {
+    device;
+    onPauseCallback;
+    onResumeCallback;
+    constructor() {
+        this.device = '';
+    }
+    /**
+     * Auto-detect the first available audio playback device
+     * Prefers USB audio devices over HDMI devices
+     * @returns The device string (e.g., 'plughw:0,0') or empty string if none found
+     */
+    detectSpeakerDevice() {
+        try {
+            // Run aplay -l to list playback devices
+            const output = execSync('aplay -l', { encoding: 'utf8' });
+            const lines = output.split('\n');
+            // Prefer USB audio devices over HDMI (which may not work without connected display)
+            const usbLine = lines.find((line) => line.includes('USB') && line.match(/card (\d+):.*device (\d+):/));
+            const targetLine = usbLine || lines.find((line) => line.match(/card (\d+):.*device (\d+):/));
+            if (targetLine) {
+                const match = targetLine.match(/card (\d+):.*device (\d+):/);
+                if (match) {
+                    const card = match[1];
+                    const device = match[2];
+                    const deviceString = `plughw:${card},${device}`;
+                    logger.verbose(`🔈 auto-detected speaker device: ${deviceString}`);
+                    return deviceString;
+                }
+            }
+            logger.warn('No audio playback devices found');
+            return '';
+        }
+        catch (error) {
+            logger.error('Error detecting speaker device:', error);
+            return '';
+        }
+    }
+    /**
+     * Initialize the speaker with configuration
+     * @param device Optional specific audio device to use (auto-detected if not specified)
+     */
+    initialize(device) {
+        // Auto-detect device if not specified
+        let selectedDevice = device || '';
+        if (!selectedDevice || selectedDevice === '') {
+            selectedDevice = this.detectSpeakerDevice();
+        }
+        this.device = selectedDevice;
+        logger.verbose(`Initialized speaker on device ${this.device}`);
+    }
+    /**
+     * Set callbacks for pause/resume (typically to pause/resume microphone)
+     * @param onPause Callback when audio playback starts
+     * @param onResume Callback when audio playback ends
+     */
+    setAudioLifecycleCallbacks(onPause, onResume) {
+        this.onPauseCallback = onPause;
+        this.onResumeCallback = onResume;
+    }
+    /**
+     * Play audio from a file
+     * @param audioPath Path to the audio file to play
+     */
+    async playAudio(audioPath) {
+        // pause listening while we play a sound
+        if (this.onPauseCallback) {
+            this.onPauseCallback();
+        }
+        const player = new AudioPlayer();
+        if (this.device !== undefined && this.device !== '') {
+            logger.verbose(`Playing audio file ${audioPath} through user-defined audio device (${this.device})`);
+        }
+        else {
+            logger.verbose(`Playing audio file ${audioPath} through default audio device`);
+        }
+        // Set up event handlers
+        player.on('complete', () => {
+            logger.debug('Audio playback finished');
+            // resume listening
+            if (this.onResumeCallback) {
+                this.onResumeCallback();
+            }
+        });
+        player.on('error', (err) => {
+            logger.error('Error occurred while playing audio', err);
+        });
+        // play the audio
+        player.play(audioPath, this.device);
+        // wait for the audio to finish playing, either by completing playback or by throwing an error
+        await Promise.race([once(player, 'complete'), once(player, 'error')]);
+    }
+    /**
+     * Clean up resources
+     */
+    cleanup() {
+        logger.debug('SpeakerController cleanup (no-op)');
+    }
+}
+//# sourceMappingURL=speaker.js.map

package/dist/speaker/speaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speaker.js","sourceRoot":"","sources":["../../src/speaker/speaker.ts"],"names":[],"mappings":"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"}

package/dist/stt/backends/azure-stt.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { STTEngine, STTRequestOptions } from '../stt-engine.js';
+/**
+ * Azure Cognitive Services Speech-to-Text Engine
+ *
+ * Cloud-based speech recognition using Microsoft Azure Speech Services.
+ * Requires Azure subscription key and region to be configured.
+ * @public
+ */
+export declare class AzureSTTEngine extends STTEngine {
+    private microphoneRate;
+    private microphoneChannels;
+    private subscriptionKey?;
+    private region?;
+    initialize(microphoneRate: number, microphoneChannels: number): Promise<void>;
+    transcribe(micStream: NodeJS.ReadableStream, options: STTRequestOptions): Promise<string>;
+}
+//# sourceMappingURL=azure-stt.d.ts.map

package/dist/stt/backends/azure-stt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"azure-stt.d.ts","sourceRoot":"","sources":["../../../src/stt/backends/azure-stt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAKhE;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,SAAS;IACzC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,MAAM,CAAC,CAAS;IAElB,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B7E,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;CAwNlG"}