Skip to content

Commit 7f847ae

Browse files
fix(server): report ffmpeg errors when opening Android emulators (pingdotgg#18784)
Co-authored-by: Julius Marminge <[email protected]>
1 parent 27b7085 commit 7f847ae

8 files changed

Lines changed: 223 additions & 23 deletions

File tree

‎apps/server/src/device/DeviceMultiHost.test.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,16 @@ import * as DeviceService from "./DeviceService.ts";
1212
it.effect("keeps hosts independent when serials collide and another host fails", () =>
1313
Effect.gen(function* () {
1414
const host = (id: string, failed = false): DeviceHost.DeviceHost["Service"] => {
15-
const ready = {
15+
const ready: DeviceHost.DeviceHostAgentReady = {
1616
nodePath: process.execPath,
1717
hub: { origin: `http://${id}` },
1818
agentDevice: { baseUrl: `http://${id}`, token: "test", entryPath: "/agent-device" },
19-
run: () => Effect.succeed({ stdout: "", stderr: "", code: 0 }),
19+
run: (command) =>
20+
Effect.succeed({
21+
stdout: command === "emulator" ? "" : " V....D libx264",
22+
stderr: "",
23+
code: 0,
24+
}),
2025
helpers: { serveSimAxSettings: null, serveSimCli: null },
2126
};
2227
return {

‎apps/server/src/device/DeviceService.test.ts‎

Lines changed: 113 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import {
55
DeviceOperationError,
66
LOCAL_DEVICE_HOST_ID,
77
ThreadId,
8+
type DeviceSummary,
89
type DeviceServiceState,
910
type ServerSettings as Settings,
1011
type SshDeviceHostConfig,
@@ -90,13 +91,18 @@ const fixture = Effect.fn("fixture")(function* (
9091
const agentStarts: string[] = [];
9192
const agentStops: string[] = [];
9293
const requests: string[] = [];
94+
const devices: Array<Omit<DeviceSummary, "hostId">> = [];
95+
const encoderResult = yield* Ref.make({ code: 0, stdout: " V....D libx264", stderr: "" });
9396
let booted = false;
9497
let shutDown = false;
9598
const ready: DeviceHost.DeviceHostReady = {
9699
nodePath: process.execPath,
97100
hub: { origin: "http://device.test" },
98101
helpers: { serveSimAxSettings: null, serveSimCli: null },
99-
run: () => Effect.succeed({ code: 0, stdout: "Pixel_API_35\n", stderr: "" }),
102+
run: (command) =>
103+
command === "emulator"
104+
? Effect.succeed({ code: 0, stdout: "Pixel_API_35\n", stderr: "" })
105+
: Ref.get(encoderResult),
100106
};
101107
const host: DeviceHost.DeviceHost["Service"] = {
102108
...(inspectError
@@ -115,7 +121,10 @@ const fixture = Effect.fn("fixture")(function* (
115121
id: LOCAL_DEVICE_HOST_ID,
116122
kind: "local",
117123
label: "Test server",
118-
platforms: [{ platform: "android", available: true }],
124+
platforms: [
125+
{ platform: "android", available: true },
126+
{ platform: "ios", available: true },
127+
],
119128
hubInstalled: true,
120129
agentDeviceInstalled: false,
121130
}),
@@ -207,29 +216,35 @@ const fixture = Effect.fn("fixture")(function* (
207216
),
208217
);
209218
}
219+
if (request.url.endsWith("/grid/api/start")) {
220+
return HttpClientResponse.fromWeb(request, Response.json({ ok: true }));
221+
}
210222
return HttpClientResponse.fromWeb(
211223
request,
212224
Response.json({
213-
simulators: [],
214-
emulators: booted
215-
? [
216-
{
217-
id: "emulator-5554",
218-
name: "Pixel_API_35",
219-
platform: "android",
220-
version: "Android 15",
221-
booted: true,
222-
physical: false,
223-
},
224-
]
225-
: [],
225+
simulators: devices.filter((device) => device.platform === "ios"),
226+
emulators: [
227+
...devices.filter((device) => device.platform === "android"),
228+
...(booted
229+
? [
230+
{
231+
id: "emulator-5554",
232+
name: "Pixel_API_35",
233+
platform: "android",
234+
version: "Android 15",
235+
booted: true,
236+
physical: false,
237+
},
238+
]
239+
: []),
240+
],
226241
}),
227242
);
228243
}),
229244
),
230245
),
231246
);
232-
return { service, starts, agentStarts, agentStops, requests, settings };
247+
return { service, starts, agentStarts, agentStops, requests, settings, devices, encoderResult };
233248
});
234249

235250
describe("device setup consent", () => {
@@ -349,6 +364,88 @@ describe("device setup consent", () => {
349364
}).pipe(Effect.scoped),
350365
);
351366

367+
it.effect("blocks only emulator video until ffmpeg is usable, then allows retry", () =>
368+
Effect.gen(function* () {
369+
const { service, requests, devices, encoderResult } = yield* fixture();
370+
devices.push(
371+
{
372+
id: DeviceId.make("physical-android"),
373+
name: "Pixel",
374+
platform: "android",
375+
version: "Android 15",
376+
booted: true,
377+
physical: true,
378+
},
379+
{
380+
id: DeviceId.make("ios-simulator"),
381+
name: "iPhone",
382+
platform: "ios",
383+
version: "iOS 18",
384+
booted: true,
385+
physical: false,
386+
},
387+
);
388+
yield* Ref.set(encoderResult, { code: 127, stdout: "", stderr: "spawn ffmpeg ENOENT" });
389+
const state = yield* service.configure({ enabled: true });
390+
expect(state.devices.map((device) => device.id)).toEqual([
391+
"ios-simulator",
392+
"physical-android",
393+
"Pixel_API_35",
394+
]);
395+
const threadId = ThreadId.make("emulator-video-readiness");
396+
const physical = yield* service.open({
397+
threadId,
398+
deviceId: "physical-android",
399+
platform: "android",
400+
});
401+
const ios = yield* service.open({ threadId, deviceId: "ios-simulator", platform: "ios" });
402+
expect(physical.deviceId).toBe("physical-android");
403+
expect(ios.deviceId).toBe("ios-simulator");
404+
405+
const openEmulator = service.open({
406+
threadId,
407+
deviceId: "Pixel_API_35",
408+
platform: "android",
409+
});
410+
const missing = yield* openEmulator.pipe(Effect.flip);
411+
expect(missing.message).toMatch(/ffmpeg/i);
412+
expect(missing.message).toMatch(/emulator/i);
413+
expect(requests.filter((url) => url.endsWith("/boot"))).toEqual([]);
414+
expect((yield* service.state).sessions).toEqual([physical, ios]);
415+
expect((yield* service.state).bootingDevices ?? []).toEqual([]);
416+
417+
yield* Ref.set(encoderResult, { code: 1, stdout: "", stderr: "cannot execute ffmpeg" });
418+
expect((yield* openEmulator.pipe(Effect.flip)).message).toMatch(/ffmpeg/i);
419+
yield* Ref.set(encoderResult, {
420+
code: 0,
421+
stdout: " V....D libx264rgb libx264 H.264 / AVC RGB (codec h264)",
422+
stderr: "",
423+
});
424+
expect((yield* openEmulator.pipe(Effect.flip)).message).toMatch(/libx264/i);
425+
expect(requests.filter((url) => url.endsWith("/boot"))).toEqual([]);
426+
expect((yield* service.state).sessions).toEqual([physical, ios]);
427+
428+
devices.push({
429+
id: DeviceId.make("emulator-5556"),
430+
name: "Already_booted",
431+
platform: "android",
432+
version: "Android 15",
433+
booted: true,
434+
physical: false,
435+
});
436+
expect(
437+
(yield* service
438+
.open({ threadId, deviceId: "emulator-5556", platform: "android" })
439+
.pipe(Effect.flip)).message,
440+
).toMatch(/libx264/i);
441+
442+
yield* Ref.set(encoderResult, { code: 0, stdout: " V....D libx264", stderr: "" });
443+
const emulator = yield* openEmulator;
444+
expect(emulator.deviceId).toBe("emulator-5554");
445+
expect(requests.filter((url) => url.endsWith("/boot"))).toHaveLength(1);
446+
}).pipe(Effect.scoped),
447+
);
448+
352449
it.effect("installs agent support only after the separate agent permission", () =>
353450
Effect.gen(function* () {
354451
const { service, agentStarts, agentStops, settings } = yield* fixture();

‎apps/server/src/device/DeviceService.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -671,6 +671,33 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
671671
if (!device) {
672672
return yield* new DeviceNotFoundError({ hostId: host.id, deviceId: input.deviceId });
673673
}
674+
if (device.platform === "android" && !device.physical) {
675+
// Resolve the override on the device host the way its hub does.
676+
const encoders = yield* ready.run(ready.nodePath, [
677+
"-e",
678+
`const { spawnSync } = require("node:child_process");
679+
const result = spawnSync(process.env.SERVE_EMU_FFMPEG?.trim() || "ffmpeg", ["-hide_banner", "-encoders"], {
680+
stdio: "inherit", timeout: 10000, killSignal: "SIGKILL",
681+
});
682+
process.exitCode = result.error ? 1 : (result.status ?? 1);`,
683+
]);
684+
if (encoders.code !== 0) {
685+
return yield* new DevicePlatformUnavailableError({
686+
hostId: host.id,
687+
platform: "android",
688+
reason:
689+
"Android emulator video needs working ffmpeg with the libx264 encoder. Install it on the device host's PATH or set SERVE_EMU_FFMPEG there, then retry opening the emulator. After changing PATH or SERVE_EMU_FFMPEG, turn device support off and on for SSH hosts, or restart the local environment server.",
690+
});
691+
}
692+
if (!/^\s*V\S*[ \t]+libx264(?:[ \t]|$)/m.test(`${encoders.stdout}\n${encoders.stderr}`)) {
693+
return yield* new DevicePlatformUnavailableError({
694+
hostId: host.id,
695+
platform: "android",
696+
reason:
697+
"Android emulator video needs the libx264 encoder. Install an ffmpeg build that includes libx264 on the device host, then retry opening the emulator. After changing PATH or SERVE_EMU_FFMPEG, turn device support off and on for SSH hosts, or restart the local environment server.",
698+
});
699+
}
700+
}
674701
if (!device.booted && input.boot !== false) {
675702
const booting = { ...device, threadId: input.threadId };
676703
yield* publish((current) => ({

‎apps/server/src/device/LocalDeviceHost.test.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -502,6 +502,56 @@ http.createServer((req,res)=>res.end('ok')).listen(Number(args[args.indexOf('--p
502502
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
503503
);
504504

505+
it.effect("keeps local Android and iOS available without ffmpeg", () =>
506+
Effect.gen(function* () {
507+
const fs = yield* FileSystem.FileSystem;
508+
const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-device-ffmpeg-" });
509+
yield* fs.makeDirectory(`${baseDir}/bin`);
510+
yield* fs.writeFileString(`${baseDir}/bin/xcrun`, "#!/bin/sh\nexit 0\n");
511+
yield* fs.chmod(`${baseDir}/bin/xcrun`, 0o755);
512+
for (const [directory, tool] of [
513+
["platform-tools", "adb"],
514+
["emulator", "emulator"],
515+
["cmdline-tools/latest/bin", "avdmanager"],
516+
]) {
517+
yield* fs.makeDirectory(`${baseDir}/sdk/${directory}`, { recursive: true });
518+
yield* fs.writeFileString(`${baseDir}/sdk/${directory}/${tool}`, "");
519+
}
520+
const onTestHost = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
521+
effect.pipe(
522+
Effect.provideService(HostProcess.Environment, {
523+
HOME: baseDir,
524+
PATH: `${baseDir}/bin`,
525+
ANDROID_HOME: `${baseDir}/sdk`,
526+
}),
527+
Effect.provideService(HostProcess.Platform, "darwin"),
528+
);
529+
const host = yield* LocalDeviceHost.make().pipe(
530+
Effect.provide(Layer.mergeAll(ServerConfig.layerTest(baseDir, baseDir), NetService.layer)),
531+
onTestHost,
532+
Effect.provideService(
533+
HttpClient.HttpClient,
534+
HttpClient.make(() => Effect.die(new Error("Readiness must not make network requests"))),
535+
),
536+
Effect.provideService(ProcessRunner.ProcessRunner, {
537+
run: () => Effect.die("Platform availability must not probe emulator video"),
538+
}),
539+
);
540+
expect((yield* onTestHost(host.summary)).platforms).toEqual([
541+
{ platform: "ios", available: true },
542+
{ platform: "android", available: true },
543+
]);
544+
expect(yield* onTestHost(host.platformAvailability("android"))).toEqual({
545+
platform: "android",
546+
available: true,
547+
});
548+
expect(yield* onTestHost(host.platformAvailability("ios"))).toEqual({
549+
platform: "ios",
550+
available: true,
551+
});
552+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
553+
);
554+
505555
it.effect(
506556
"constructs and inspects an unconfigured host without installing or starting helpers",
507557
() =>

‎apps/server/src/device/LocalDeviceHost.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,7 @@ export const make = Effect.fn("LocalDeviceHost.make")(function* () {
237237
const runner = yield* ProcessRunner.ProcessRunner;
238238
const httpClient = yield* HttpClient.HttpClient;
239239
const environment = yield* HostProcess.Environment;
240+
const workingDirectory = yield* HostProcess.WorkingDirectory;
240241
const hostPlatform = yield* HostProcess.Platform;
241242
const sdk = yield* androidSdk;
242243
const hostEnvironment = deviceHostEnvironment(environment, sdk.root, hostPlatform, path);
@@ -401,6 +402,7 @@ export const make = Effect.fn("LocalDeviceHost.make")(function* () {
401402
...hubPlatformArguments(hostPlatform),
402403
],
403404
{
405+
cwd: workingDirectory,
404406
detached: false,
405407
shell: false,
406408
stdout: "pipe",
@@ -766,6 +768,7 @@ export const make = Effect.fn("LocalDeviceHost.make")(function* () {
766768
)
767769
: command,
768770
args,
771+
cwd: workingDirectory,
769772
env: hostEnvironment,
770773
timeout: Duration.millis(options?.timeoutMs ?? 20_000),
771774
timeoutBehavior: "timedOutResult",
@@ -775,7 +778,7 @@ export const make = Effect.fn("LocalDeviceHost.make")(function* () {
775778
Effect.map((result) => ({
776779
stdout: result.stdout,
777780
stderr: result.stderr,
778-
code: Number(result.code),
781+
code: result.timedOut ? 124 : Number(result.code ?? 127),
779782
})),
780783
Effect.catch((cause) => Effect.succeed({ stdout: "", stderr: String(cause), code: 127 })),
781784
);

‎apps/server/src/device/SshDeviceHost.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,10 @@ export const make = Effect.fn("SshDeviceHost.make")(function* (
172172
provide(
173173
runSshCommand(targetFor(config), {
174174
preHostArgs: identityArgs(config),
175-
remoteCommandArgs: commandArgs(`exec ${[command, ...args].map(quoteRemoteArg).join(" ")}`),
175+
// Match the hub cwd so relative executables and PATH entries resolve identically.
176+
remoteCommandArgs: commandArgs(
177+
`cd "$HOME/.t3/device/hosts/${owner}" && exec ${[command, ...args].map(quoteRemoteArg).join(" ")}`,
178+
),
176179
...(options?.stdin === undefined ? {} : { stdin: options.stdin }),
177180
...(options?.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
178181
}),

‎apps/server/src/device/sshDeviceScript.test.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,12 @@ else { const child=spawn(process.execPath,[path.join(path.dirname(process.argv[1
111111
.replace(AGENT_DEVICE_VERSION, upgraded ? nextAgentVersion : AGENT_DEVICE_VERSION),
112112
);
113113
const result = await exec(process.execPath, [file], {
114-
env: { ...process.env, HOME: home, PATH: `${bin}:${process.env.PATH}` },
114+
env: {
115+
...process.env,
116+
HOME: home,
117+
PATH: `${bin}:${process.env.PATH}`,
118+
SERVE_EMU_FFMPEG: NodePath.join(home, "missing-ffmpeg"),
119+
},
115120
});
116121
return result.stdout ? JSON.parse(result.stdout) : null;
117122
};

‎docs/user/devices.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,15 @@ macOS with Xcode. Android needs the SDK Platform-Tools, Android Emulator,
3131
and Command-line Tools (latest), plus a virtual device created in Android
3232
Studio's Device Manager. T3 Code detects standard SDK locations; set
3333
`ANDROID_HOME` for a custom location. The panel explains missing dependencies.
34-
After installing them, restart the environment server and refresh devices.
34+
After installing SDK tools, restart the environment server and refresh devices.
35+
36+
Android emulator video also needs `ffmpeg` with the libx264 encoder on the device
37+
host's PATH, or an executable selected by `SERVE_EMU_FFMPEG` on that host. If
38+
opening an emulator reports an ffmpeg problem, install or fix the executable
39+
and retry opening it. After changing PATH or `SERVE_EMU_FFMPEG`, restart the
40+
environment server for local devices, or turn device support off and on for SSH
41+
devices, so the running tools inherit the new environment. Physical Android
42+
devices and iOS do not need ffmpeg.
3543

3644
The screen is interactive: click and drag to touch, type while the screen is
3745
focused, and use the toolbar for Home, Back, and Recents on Android, rotate on
@@ -100,7 +108,9 @@ the environment’s own machine are skipped, since its devices are already local
100108
The first device listing installs pinned device tools on the host.
101109
Node 22 or newer and npm must be available to non-interactive SSH commands.
102110
T3 checks common Homebrew and Android SDK locations; custom installations need
103-
the appropriate PATH and ANDROID_HOME on the host.
111+
the appropriate PATH and ANDROID_HOME on the host. Android emulator video needs
112+
`ffmpeg` with libx264 on that host; physical Android devices use scrcpy and do
113+
not need ffmpeg.
104114

105115
The picker identifies devices by host when several hosts are configured.
106116
Connections recover after interruptions. Removing a host closes its device

0 commit comments

Comments
 (0)