Merge branch 'main' of https://github.com/appium/appium-ios-remotexpc into accessibility-audit-service

Author: navin772

CHANGELOG.md

@@ -1,3 +1,21 @@
+## [5.14.3](https://github.com/appium/appium-ios-remotexpc/compare/v5.14.2...v5.14.3) (2026-08-11)
+
+### Bug Fixes
+
+* **display:** close the video writer when the audio writer's close throws ([#291](https://github.com/appium/appium-ios-remotexpc/issues/291)) ([ee8f381](https://github.com/appium/appium-ios-remotexpc/commit/ee8f381d867dfe703e407462ad7da0184b59a67d))
+
+## [5.14.2](https://github.com/appium/appium-ios-remotexpc/compare/v5.14.1...v5.14.2) (2026-08-11)
+
+### Bug Fixes
+
+* **display:** stop captures when the recording's output file cannot be created ([#290](https://github.com/appium/appium-ios-remotexpc/issues/290)) ([18ad748](https://github.com/appium/appium-ios-remotexpc/commit/18ad7480bf5a82888a7ea9a574e937ce11b5eaba))
+
+## [5.14.1](https://github.com/appium/appium-ios-remotexpc/compare/v5.14.0...v5.14.1) (2026-08-11)
+
+### Bug Fixes
+
+* **display:** surface screen-recording write errors instead of crashing ([#289](https://github.com/appium/appium-ios-remotexpc/issues/289)) ([2ef7852](https://github.com/appium/appium-ios-remotexpc/commit/2ef7852814d01bcc08202e82434ebea74424d8de))
+
 ## [5.14.0](https://github.com/appium/appium-ios-remotexpc/compare/v5.13.6...v5.14.0) (2026-08-09)
 
 ### Features

package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "5.14.0",
+  "version": "5.14.3",
   "description": "",
   "keywords": [],
   "bugs": {

src/services/ios/display/audio/audio-stream-capture.ts

@@ -242,7 +242,25 @@ export async function recordAudioToFile(
   const timer = setTimeout(() => controller.abort(), durationMs);
   timer.unref?.();
 
-  const writer = await M4aFileWriter.create(outputPath);
+  let writer: M4aFileWriter;
+  try {
+    writer = await M4aFileWriter.create(outputPath);
+  } catch (error) {
+    // The capture is already streaming and never escapes this function, so a
+    // caller cannot stop it. Left running, the device keeps sending into a
+    // receiver whose queue nobody drains.
+    clearTimeout(timer);
+    // Swallowed so it cannot mask the error being thrown, but logged: a failed
+    // stop means the device is still streaming, which is the leak itself.
+    await capture.stop().catch((stopError: unknown) => {
+      log.debug(
+        `Failed to stop the audio stream after the output file could not be created: ${
+          stopError instanceof Error ? stopError.message : String(stopError)
+        }`,
+      );
+    });
+    throw error;
+  }
   let written;
   try {
     for await (const unit of capture.accessUnits(controller.signal)) {

src/services/ios/display/recording/av-capture.ts

@@ -1,14 +1,11 @@
-import {once} from 'node:events';
-import {createWriteStream} from 'node:fs';
-
 import {getLogger} from '../../../../lib/logger.js';
 import {XPCUUID} from '../../../../lib/remote-xpc/xpc-uuid.js';
 import {type AacEldFormat, aacEldDurationMs} from '../audio/aac-eld.js';
 import {AudioStreamCapture, type AudioStreamStats} from '../audio/audio-stream-capture.js';
 import {M4aFileWriter} from '../audio/m4a-writer.js';
 import {type DisplayService, type StartVideoStreamOptions} from '../index.js';
 import {toAnnexB} from '../video/hevc.js';
-import {ScreenStreamCapture, type ScreenStreamStats} from '../video/screen-stream-capture.js';
+import {AnnexBFileWriter, ScreenStreamCapture, type ScreenStreamStats} from '../video/screen-stream-capture.js';
 import {type MuxCommand, ffmpegMuxCommandBuilder} from './mux-command.js';
 
 const log = getLogger('AvCapture');
@@ -127,8 +124,30 @@ export async function recordScreenAndAudioToFiles(
     throw error;
   }
 
-  const videoOut = createWriteStream(videoPath);
-  const audioOut = await M4aFileWriter.create(audioPath);
+  const videoOut = new AnnexBFileWriter(videoPath);
+  let audioOut: M4aFileWriter;
+  try {
+    audioOut = await M4aFileWriter.create(audioPath);
+  } catch (error) {
+    // Both captures are already streaming by now, and neither they nor the
+    // video writer escape this function, so a caller cannot release them. Left
+    // running, the device keeps encoding into a receiver whose queue nobody
+    // drains, and its RTCP keepalive keeps the session alive indefinitely.
+    // Each failure is swallowed so it cannot mask the error being thrown. The
+    // stop is still logged: if it fails the device is left streaming, which is
+    // the leak itself. One stop tears down both streams, so the second call and
+    // the file close are quiet.
+    await videoCapture.stop().catch((stopError: unknown) => {
+      log.debug(
+        `Failed to stop cleanly after the audio file could not be created: ${
+          stopError instanceof Error ? stopError.message : String(stopError)
+        }`,
+      );
+    });
+    await audioCapture.stop().catch((): void => undefined);
+    await videoOut.close().catch((): void => undefined);
+    throw error;
+  }
   let framesWritten = 0;
   let videoBytes = 0;
   let sawKeyFrame = false;
@@ -147,9 +166,7 @@ export async function recordScreenAndAudioToFiles(
         sawKeyFrame = true;
       }
       const chunk = toAnnexB(unit.nals);
-      if (!videoOut.write(chunk)) {
-        await once(videoOut, 'drain');
-      }
+      await videoOut.write(chunk);
       framesWritten += 1;
       videoBytes += chunk.length;
     }
@@ -179,16 +196,16 @@ export async function recordScreenAndAudioToFiles(
       log.debug(`Failed to stop cleanly: ${error instanceof Error ? error.message : String(error)}`);
     });
     await audioCapture.stop().catch((): void => undefined);
-    audioWritten = await audioOut.close();
-    await new Promise<void>((resolve, reject) => {
-      videoOut.end((error?: Error | null): void => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-    });
+    // The video writer closes even when the audio writer throws. M4aFileWriter
+    // finalizes by reopening the finished file to patch mdat's length, so it can
+    // fail on a full disk long after every frame is safely on disk. Sequencing
+    // the two closes would leak the video file descriptor for the life of the
+    // process, and the error its stream is holding would never be read.
+    try {
+      audioWritten = await audioOut.close();
+    } finally {
+      await videoOut.close();
+    }
   }
 
   const audioDurationMs = aacEldDurationMs(audioWritten.sampleCount);

src/services/ios/display/video/screen-stream-capture.ts

@@ -191,6 +191,69 @@ export class ScreenStreamCapture {
   }
 }
 
+/**
+ * The Annex-B output file, with the write stream's `'error'` event held instead
+ * of left to reach the process.
+ *
+ * A recording runs unattended for minutes and the stream never escapes the
+ * function that owns it, so a caller cannot attach a listener of its own.
+ * Without one here, a mistyped path or a write that fails after the fact (a full
+ * disk, an unplugged volume) arrives as an uncaught `'error'` event and takes
+ * the process down — `end(callback)` does not help, since the callback receives
+ * the error *and* the event is still emitted. Holding the first error and
+ * re-throwing it from the next `write` or `close` turns that into a rejection
+ * the caller can see, the guarantee {@link M4aFileWriter} already gives the
+ * audio track.
+ *
+ * Opening is deliberately not awaited, unlike `M4aFileWriter.create`: the
+ * capture is already streaming by the time the file is created, so a rejection
+ * before the caller holds the writer would strand it. An open failure surfaces
+ * from the first {@link write} instead.
+ */
+export class AnnexBFileWriter {
+  private readonly stream: ReturnType<typeof createWriteStream>;
+  /** First stream error seen, re-thrown from the next `write` or `close`. */
+  private streamError: Error | undefined;
+
+  /** @param path Destination file path; truncated if it exists. */
+  constructor(path: string) {
+    this.stream = createWriteStream(path);
+    this.stream.on('error', (error: Error) => {
+      this.streamError ??= error;
+    });
+  }
+
+  /**
+   * Appends one chunk, resolving once the stream has room for more so an
+   * `await` per chunk applies backpressure.
+   */
+  async write(chunk: Buffer): Promise<void> {
+    if (this.streamError) {
+      throw this.streamError;
+    }
+    if (!this.stream.write(chunk)) {
+      await once(this.stream, 'drain');
+    }
+    if (this.streamError) {
+      throw this.streamError;
+    }
+  }
+
+  /** Flushes and closes the file, re-throwing any error the stream saw. */
+  async close(): Promise<void> {
+    // The held error is reported in preference to ending an already-failed
+    // stream, which answers with a generic `ERR_STREAM_DESTROYED` and buries the
+    // cause. That is the common path for a bad output path: the open fails
+    // before the first keyframe arrives, so no `write` ever ran to surface it.
+    if (this.streamError) {
+      throw this.streamError;
+    }
+    await new Promise<void>((resolve, reject) => {
+      this.stream.end((error?: Error | null): void => (error ? reject(error) : resolve()));
+    });
+  }
+}
+
 /** Options for {@link recordScreenToFile}. */
 export interface RecordScreenOptions extends ScreenStreamCaptureOptions {
   /** How long to record, in milliseconds. Defaults to 5000. */
@@ -239,7 +302,7 @@ export async function recordScreenToFile(
   const {durationMs = 5000, maxFrames = Number.POSITIVE_INFINITY, ...captureOptions} = options;
 
   const capture = await ScreenStreamCapture.start(service, captureOptions);
-  const output = createWriteStream(outputPath);
+  const output = new AnnexBFileWriter(outputPath);
   let framesWritten = 0;
   let bytesWritten = 0;
   let sawKeyFrame = false;
@@ -262,9 +325,7 @@ export async function recordScreenToFile(
       }
 
       const chunk = toAnnexB(unit.nals);
-      if (!output.write(chunk)) {
-        await once(output, 'drain');
-      }
+      await output.write(chunk);
       framesWritten += 1;
       bytesWritten += chunk.length;
 
@@ -277,15 +338,7 @@ export async function recordScreenToFile(
     await capture.stop().catch((error: unknown) => {
       log.debug(`Failed to stop the media stream cleanly: ${error instanceof Error ? error.message : String(error)}`);
     });
-    await new Promise<void>((resolve, reject) => {
-      output.end((error?: Error | null): void => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-    });
+    await output.close();
   }
 
   return {

test/unit/display/audio/audio-stream-capture.spec.ts

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import {mkdtemp, rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {after, before, describe, it} from 'node:test';
+
+import {recordAudioToFile} from '../../../../src/services/ios/display/audio/audio-stream-capture.js';
+import type {DisplayService, MediaStreamAnswer} from '../../../../src/services/ios/display/index.js';
+
+/** A stub service that negotiates without a device and counts teardowns. */
+function makeStubService(): {service: DisplayService; stopCalls: () => number} {
+  let stopCalls = 0;
+  const service = {
+    getTunnelLocalAddress: async (): Promise<string> => '::1',
+    getDeviceAddress: async (): Promise<string> => '::1',
+    startAudioStream: async (): Promise<MediaStreamAnswer> =>
+      // An empty streamConfig means no RTCP identity, so no keepalive timer is
+      // started — the negotiation is all this test needs.
+      ({clientSessionId: undefined, streamConfig: {}, connection: {}, raw: {}}) as unknown as MediaStreamAnswer,
+    stopAllMediaStreams: async (): Promise<number[]> => {
+      stopCalls += 1;
+      return [];
+    },
+  } as unknown as DisplayService;
+  return {service, stopCalls: () => stopCalls};
+}
+
+describe('recordAudioToFile', function () {
+  let directory: string;
+
+  before(async function () {
+    directory = await mkdtemp(join(tmpdir(), 'record-audio-'));
+  });
+
+  after(async function () {
+    await rm(directory, {force: true, recursive: true});
+  });
+
+  it('stops the capture when the output file cannot be created', async function () {
+    // The capture is started before the writer, so a writer that fails to open
+    // used to strand a live device stream: nothing stopped it, its UDP receiver
+    // stayed bound, and its queue grew with every packet nobody read. The
+    // capture never escapes the function, so no caller could clean it up.
+    const {service, stopCalls} = makeStubService();
+    const unwritablePath = join(directory, 'no', 'such', 'dir', 'audio.m4a');
+
+    await assert.rejects(() => recordAudioToFile(service, unwritablePath), /ENOENT/);
+
+    assert.strictEqual(stopCalls(), 1, 'the capture must be stopped before the error propagates');
+  });
+});