feat: support Android emulator camera video files

Author: thymikee

src/client-types.ts

@@ -555,6 +555,8 @@ type RepeatedPressOptions = {
 
 export type DeviceBootOptions = DeviceCommandBaseOptions & {
   headless?: boolean;
+  cameraFront?: string;
+  cameraBack?: string;
 };
 
 export type DeviceShutdownOptions = DeviceCommandBaseOptions;
@@ -850,6 +852,8 @@ type CommandExecutionOptions = Partial<ScreenshotRequestFlags> & {
   pauseMs?: number;
   pattern?: SwipePattern;
   headless?: boolean;
+  cameraFront?: string;
+  cameraBack?: string;
   restart?: boolean;
   replayUpdate?: boolean;
   replayBackend?: string;

src/commands/cli-grammar/apps.ts

@@ -28,6 +28,8 @@ export const appCliReaders = {
   boot: (_positionals, flags) => ({
     ...commonInputFromFlags(flags),
     headless: flags.headless,
+    cameraFront: flags.cameraFront,
+    cameraBack: flags.cameraBack,
   }),
   shutdown: (_positionals, flags) => commonInputFromFlags(flags),
   prepare: (positionals, flags) => ({

src/commands/client-command-metadata.ts

@@ -37,6 +37,8 @@ export const clientCommandMetadata = [
   defineClientCommandMetadata('devices', {}),
   defineClientCommandMetadata('boot', {
     headless: booleanField('Boot without showing simulator UI when supported.'),
+    cameraFront: stringField('Android emulator front camera mode or video file path used at boot.'),
+    cameraBack: stringField('Android emulator back camera mode or video file path used at boot.'),
   }),
   defineClientCommandMetadata('shutdown', {}),
   defineClientCommandMetadata('prepare', {

src/daemon/handlers/__tests__/session.test.ts

@@ -937,6 +937,61 @@ test('boot launches Android emulator with GUI when no running device matches', a
   }
 });
 
+test('boot launches Android emulator with camera video files', async () => {
+  const sessionStore = makeSessionStore();
+  mockResolveTargetDevice.mockRejectedValue(new AppError('DEVICE_NOT_FOUND', 'No device found'));
+  const launchCalls: Array<{
+    avdName: string;
+    serial?: string;
+    headless?: boolean;
+    cameraFront?: string;
+    cameraBack?: string;
+  }> = [];
+  mockEnsureAndroidEmulatorBooted.mockImplementation(
+    async ({ avdName, serial, headless, cameraFront, cameraBack }) => {
+      launchCalls.push({ avdName, serial, headless, cameraFront, cameraBack });
+      return {
+        platform: 'android',
+        id: 'emulator-5554',
+        name: 'Pixel_9_Pro_XL',
+        kind: 'emulator',
+        target: 'mobile',
+        booted: true,
+      };
+    },
+  );
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'boot',
+      positionals: [],
+      flags: {
+        platform: 'android',
+        device: 'Pixel_9_Pro_XL',
+        cameraFront: '/tmp/front.mp4',
+        cameraBack: '/tmp/back.mp4',
+      },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response).toBeTruthy();
+  expect(response?.ok).toBe(true);
+  expect(launchCalls).toEqual([
+    {
+      avdName: 'Pixel_9_Pro_XL',
+      serial: undefined,
+      headless: false,
+      cameraFront: '/tmp/front.mp4',
+      cameraBack: '/tmp/back.mp4',
+    },
+  ]);
+});
+
 test('boot --headless requires avd selector when device cannot be resolved', async () => {
   const sessionStore = makeSessionStore();
   mockResolveTargetDevice.mockRejectedValue(new AppError('DEVICE_NOT_FOUND', 'No device found'));

src/daemon/handlers/session-state.ts

@@ -18,6 +18,8 @@ async function ensureAndroidEmulatorBoot(params: {
   avdName: string;
   serial?: string;
   headless?: boolean;
+  cameraFront?: string;
+  cameraBack?: string;
 }): Promise<DeviceInfo> {
   const { ensureAndroidEmulatorBooted } = await import('../../platforms/android/devices.ts');
   return await ensureAndroidEmulatorBooted(params);
@@ -148,12 +150,19 @@ export async function handleSessionStateCommands(params: {
       normalizePlatformSelector(flags.platform) ?? session?.device.platform;
     const targetsAndroid = normalizedPlatform === 'android';
     const wantsAndroidHeadless = flags.headless === true;
+    const wantsAndroidCamera = Boolean(flags.cameraFront || flags.cameraBack);
     if (wantsAndroidHeadless && !targetsAndroid) {
       return errorResponse(
         'INVALID_ARGS',
         'boot --headless is supported only for Android emulators.',
       );
     }
+    if (wantsAndroidCamera && !targetsAndroid) {
+      return errorResponse(
+        'INVALID_ARGS',
+        'boot --camera-front/--camera-back is supported only for Android emulators.',
+      );
+    }
 
     const fallbackAvdName = resolveAndroidEmulatorAvdName({
       flags,
@@ -173,13 +182,13 @@ export async function handleSessionStateCommands(params: {
       const appErr = asAppError(error);
       if (
         targetsAndroid &&
-        wantsAndroidHeadless &&
+        (wantsAndroidHeadless || wantsAndroidCamera) &&
         !fallbackAvdName &&
         appErr.code === 'DEVICE_NOT_FOUND'
       ) {
         return errorResponse(
           'INVALID_ARGS',
-          'boot --headless requires --device <avd-name> (or an Android emulator session target).',
+          androidBootOptionsRequireDeviceMessage(wantsAndroidCamera),
         );
       }
       if (
@@ -193,6 +202,8 @@ export async function handleSessionStateCommands(params: {
         avdName: fallbackAvdName,
         serial: flags.serial,
         headless: wantsAndroidHeadless,
+        cameraFront: typeof flags.cameraFront === 'string' ? flags.cameraFront : undefined,
+        cameraBack: typeof flags.cameraBack === 'string' ? flags.cameraBack : undefined,
       });
       launchedAndroidEmulator = true;
     }
@@ -204,11 +215,13 @@ export async function handleSessionStateCommands(params: {
       );
     }
 
-    if (targetsAndroid && wantsAndroidHeadless) {
+    if (targetsAndroid && (wantsAndroidHeadless || wantsAndroidCamera)) {
       if (device.platform !== 'android' || device.kind !== 'emulator') {
         return errorResponse(
           'INVALID_ARGS',
-          'boot --headless is supported only for Android emulators.',
+          wantsAndroidCamera
+            ? 'boot --camera-front/--camera-back is supported only for Android emulators.'
+            : 'boot --headless is supported only for Android emulators.',
         );
       }
       if (!launchedAndroidEmulator) {
@@ -220,13 +233,15 @@ export async function handleSessionStateCommands(params: {
         if (!avdName) {
           return errorResponse(
             'INVALID_ARGS',
-            'boot --headless requires --device <avd-name> (or an Android emulator session target).',
+            androidBootOptionsRequireDeviceMessage(wantsAndroidCamera),
           );
         }
         device = await ensureAndroidEmulatorBoot({
           avdName,
           serial: flags.serial,
-          headless: true,
+          headless: wantsAndroidHeadless,
+          cameraFront: typeof flags.cameraFront === 'string' ? flags.cameraFront : undefined,
+          cameraBack: typeof flags.cameraBack === 'string' ? flags.cameraBack : undefined,
         });
       }
       await ensureDeviceReady(device);
@@ -332,6 +347,12 @@ export async function handleSessionStateCommands(params: {
   return null;
 }
 
+function androidBootOptionsRequireDeviceMessage(wantsAndroidCamera: boolean): string {
+  return wantsAndroidCamera
+    ? 'boot --camera-front/--camera-back requires --device <avd-name> (or an Android emulator session target).'
+    : 'boot --headless requires --device <avd-name> (or an Android emulator session target).';
+}
+
 function shutdownFailureMessage(
   shutdown: Awaited<ReturnType<typeof shutdownDeviceTarget>>,
 ): string {

src/platforms/android/__tests__/devices.test.ts

@@ -355,6 +355,47 @@ test('ensureAndroidEmulatorBooted launches emulator with GUI by default', async
   });
 }, 10_000);
 
+test('ensureAndroidEmulatorBooted launches emulator with camera video files', async () => {
+  await withMockedAndroidTools(async ({ emulatorLogPath }) => {
+    const frontVideo = path.join(os.tmpdir(), 'front-camera.mp4');
+    const backVideo = path.join(os.tmpdir(), 'back-camera.mp4');
+    await fs.writeFile(frontVideo, 'front', 'utf8');
+    await fs.writeFile(backVideo, 'back', 'utf8');
+
+    const device = await ensureAndroidEmulatorBooted({
+      avdName: 'Pixel_9_Pro_XL',
+      timeoutMs: 5_000,
+      cameraFront: frontVideo,
+      cameraBack: backVideo,
+    });
+    assert.equal(device.id, 'emulator-5554');
+    const log = await fs.readFile(emulatorLogPath, 'utf8');
+    assert.match(
+      log,
+      new RegExp(`-camera-front videofile:${escapeRegExp(path.resolve(frontVideo))}`),
+    );
+    assert.match(
+      log,
+      new RegExp(`-camera-back videofile:${escapeRegExp(path.resolve(backVideo))}`),
+    );
+  });
+}, 10_000);
+
+test('ensureAndroidEmulatorBooted rejects camera inputs for a running emulator', async () => {
+  await withMockedAndroidTools(async ({ emulatorBootedPath }) => {
+    await fs.writeFile(emulatorBootedPath, 'ready', 'utf8');
+    await assert.rejects(
+      async () =>
+        await ensureAndroidEmulatorBooted({
+          avdName: 'Pixel_9_Pro_XL',
+          timeoutMs: 5_000,
+          cameraBack: '/tmp/back-camera.mp4',
+        }),
+      /camera inputs can only be applied when starting an emulator/,
+    );
+  });
+}, 10_000);
+
 test('ensureAndroidEmulatorBooted falls back to ANDROID_SDK_ROOT when PATH is incomplete', async () => {
   await withMockedAndroidSdkRoot(async ({ emulatorLogPath, sdkRoot }) => {
     const device = await ensureAndroidEmulatorBooted({
@@ -370,3 +411,7 @@ test('ensureAndroidEmulatorBooted falls back to ANDROID_SDK_ROOT when PATH is in
     assert.equal(process.env.ANDROID_HOME, sdkRoot);
   });
 }, 10_000);
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

src/platforms/android/devices.ts

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 import { runCmd, runCmdDetached, whichCmd } from '../../utils/exec.ts';
 import type { ExecResult } from '../../utils/exec.ts';
 import { sleep } from '../../utils/timeouts.ts';
@@ -403,6 +405,8 @@ export async function ensureAndroidEmulatorBooted(params: {
   serial?: string;
   timeoutMs?: number;
   headless?: boolean;
+  cameraFront?: string;
+  cameraBack?: string;
 }): Promise<DeviceInfo> {
   await ensureAndroidSdkPathConfigured();
   const requestedAvdName = params.avdName.trim();
@@ -434,11 +438,26 @@ export async function ensureAndroidEmulatorBooted(params: {
     resolvedAvdName,
     params.serial,
   );
+  if (existing && (params.cameraFront || params.cameraBack)) {
+    throw new AppError(
+      'INVALID_STATE',
+      'Android emulator camera inputs can only be applied when starting an emulator.',
+      {
+        avdName: resolvedAvdName,
+        serial: existing.id,
+        hint: 'Shut down the emulator first, then run boot again with --camera-front or --camera-back.',
+      },
+    );
+  }
   if (!existing) {
     const launchArgs = ['-avd', resolvedAvdName];
     if (params.headless) {
       launchArgs.push('-no-window', '-no-audio');
     }
+    const cameraFront = resolveAndroidEmulatorCameraMode(params.cameraFront, 'front');
+    if (cameraFront) launchArgs.push('-camera-front', cameraFront);
+    const cameraBack = resolveAndroidEmulatorCameraMode(params.cameraBack, 'back');
+    if (cameraBack) launchArgs.push('-camera-back', cameraBack);
     runCmdDetached('emulator', launchArgs);
   }
 
@@ -468,6 +487,38 @@ export async function ensureAndroidEmulatorBooted(params: {
   };
 }
 
+function resolveAndroidEmulatorCameraMode(
+  value: string | undefined,
+  camera: 'front' | 'back',
+): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.startsWith('videofile:')) {
+    const videoPath = trimmed.slice('videofile:'.length);
+    const resolvedPath = path.resolve(videoPath);
+    if (videoPath && existsSync(resolvedPath)) return `videofile:${resolvedPath}`;
+  }
+  if (isAndroidEmulatorCameraMode(trimmed, camera)) return trimmed;
+  const resolvedPath = path.resolve(trimmed);
+  if (existsSync(resolvedPath)) return `videofile:${resolvedPath}`;
+  throw new AppError(
+    'INVALID_ARGS',
+    `Android emulator ${camera} camera input is not valid: ${trimmed}`,
+    {
+      hint:
+        camera === 'back'
+          ? 'Use a video file path, videofile:<path>, emulated, virtualscene, webcam<N>, or none.'
+          : 'Use a video file path, videofile:<path>, emulated, webcam<N>, or none.',
+    },
+  );
+}
+
+function isAndroidEmulatorCameraMode(value: string, camera: 'front' | 'back'): boolean {
+  if (value === 'emulated' || value === 'none') return true;
+  if (/^webcam\d+$/.test(value)) return true;
+  return camera === 'back' && value === 'virtualscene';
+}
+
 export async function waitForAndroidBoot(serial: string, timeoutMs = 60000): Promise<void> {
   const timeoutBudget = timeoutMs;
   const deadline = Deadline.fromTimeoutMs(timeoutBudget);

src/utils/__tests__/args.test.ts

@@ -34,13 +34,26 @@ test('parseArgs recognizes command-specific flag combinations', async () => {
     },
     {
       label: 'boot --headless on android',
-      argv: ['boot', '--platform', 'android', '--device', 'Pixel_9_Pro_XL', '--headless'],
+      argv: [
+        'boot',
+        '--platform',
+        'android',
+        '--device',
+        'Pixel_9_Pro_XL',
+        '--headless',
+        '--camera-front',
+        '/tmp/front.mp4',
+        '--camera-back',
+        '/tmp/back.mp4',
+      ],
       strictFlags: true,
       assertParsed: (parsed) => {
         assert.equal(parsed.command, 'boot');
         assert.equal(parsed.flags.platform, 'android');
         assert.equal(parsed.flags.device, 'Pixel_9_Pro_XL');
         assert.equal(parsed.flags.headless, true);
+        assert.equal(parsed.flags.cameraFront, '/tmp/front.mp4');
+        assert.equal(parsed.flags.cameraBack, '/tmp/back.mp4');
       },
     },
     {

src/utils/cli-command-overrides.ts

@@ -63,7 +63,7 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = {
 const CLI_COMMAND_OVERRIDES = {
   boot: {
     summary: 'Boot target device/simulator',
-    allowedFlags: ['headless'],
+    allowedFlags: ['headless', 'cameraFront', 'cameraBack'],
   },
   shutdown: {
     summary: 'Shutdown target simulator/emulator',