fix: handle unhandled 'error' event on FfmpegCommand in audio.ts (#1173)

Co-authored-by: Brian Yin <brian.yin@livekit.io>

Author: enriqueespaillat-gyde

.changeset/witty-suns-trade.md

@@ -0,0 +1,5 @@
+---
+"@livekit/agents": patch
+---
+
+fix: handle unhandled 'error' event on FfmpegCommand in audio.ts

agents/src/audio.ts

@@ -7,7 +7,7 @@ import ffmpeg from 'fluent-ffmpeg';
 import type { ReadableStream } from 'node:stream/web';
 import { log } from './log.js';
 import { createStreamChannel } from './stream/stream_channel.js';
-import type { AudioBuffer } from './utils.js';
+import { type AudioBuffer, isFfmpegTeardownError } from './utils.js';
 
 ffmpeg.setFfmpegPath(ffmpegInstaller.path);
 
@@ -143,6 +143,17 @@ export function audioFramesFromFile(
     }
   };
 
+  command.on('error', (err: Error) => {
+    if (isFfmpegTeardownError(err)) {
+      // Expected during teardown — not an error
+      logger.debug('FFmpeg command ended during shutdown');
+    } else {
+      logger.error(err, 'FFmpeg command error');
+    }
+    commandRunning = false;
+    onClose();
+  });
+
   const outputStream = command.pipe();
   options.abortSignal?.addEventListener('abort', onClose, { once: true });
 

agents/src/utils.ts

@@ -753,6 +753,21 @@ export function isStreamClosedError(error: unknown): boolean {
   );
 }
 
+/** FFmpeg error messages expected during normal teardown/shutdown. */
+const FFMPEG_TEARDOWN_ERRORS = ['Output stream closed', 'received signal 2', 'SIGKILL', 'SIGINT'];
+
+/**
+ * Check if an error is an expected FFmpeg teardown error that can be safely ignored during cleanup.
+ *
+ * @param error - The error to check.
+ * @returns True if the error is an expected FFmpeg shutdown error.
+ */
+export function isFfmpegTeardownError(error: unknown): boolean {
+  return (
+    error instanceof Error && FFMPEG_TEARDOWN_ERRORS.some((msg) => error.message?.includes(msg))
+  );
+}
+
 /**
  * In JS an error can be any arbitrary value.
  * This function converts an unknown error to an Error and stores the original value in the error object.

agents/src/voice/recorder_io/recorder_io.ts

@@ -13,7 +13,7 @@ import { TransformStream } from 'node:stream/web';
 import { log } from '../../log.js';
 import { isStreamReaderReleaseError } from '../../stream/deferred_stream.js';
 import { type StreamChannel, createStreamChannel } from '../../stream/stream_channel.js';
-import { Future, Task, cancelAndWait, delay } from '../../utils.js';
+import { Future, Task, cancelAndWait, delay, isFfmpegTeardownError } from '../../utils.js';
 import type { AgentSession } from '../agent_session.js';
 import { AudioInput, AudioOutput, type PlaybackFinishedEvent } from '../io.js';
 
@@ -203,12 +203,7 @@ export class RecorderIO {
         })
         .on('error', (err) => {
           // Ignore errors from intentional stream closure or SIGINT during shutdown
-          if (
-            err.message?.includes('Output stream closed') ||
-            err.message?.includes('received signal 2') ||
-            err.message?.includes('SIGKILL') ||
-            err.message?.includes('SIGINT')
-          ) {
+          if (isFfmpegTeardownError(err)) {
             resolve();
           } else {
             this.logger.error({ err }, 'FFmpeg encoding error');