adb-harness 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,17 @@
1
+ """Find a phone's wireless-debugging adb port, keep it connected, and record its
2
+ screen so a moment in a run can be looked at afterwards.
3
+
4
+ Three commands, installed together:
5
+
6
+ capture one screenrecord for a run, an event beside each moment, and
7
+ the exact frame for an event
8
+ adb-connect the mDNS lookup for the wireless-debugging port, and the
9
+ `adb connect` that follows it
10
+ adb-watch a loop that runs adb-connect whenever the device list goes
11
+ empty
12
+
13
+ Nothing here is a library: the modules are the commands' implementations and the
14
+ shell script the watcher runs.
15
+ """
16
+
17
+ __version__ = "0.2.0"
adb_harness/capture.py ADDED
@@ -0,0 +1,551 @@
1
+ #!/usr/bin/env python3
2
+ """A screen recording of a run, and the moments in it.
3
+
4
+ The suite records the device's screen once, from the first check to the last, and
5
+ writes an event next to every moment worth finding later: a check starting, a
6
+ key typed, a frame asked for. Nothing is extracted while the tests run. This
7
+ script is the recording, the events, and the "extract that frame now" part.
8
+
9
+ capture start --dir out/capture
10
+ capture event session:typed
11
+ capture stop
12
+ capture frames --event session:typed --out out/frames
13
+ capture frames --at 12.5,40 --out out/frames
14
+ capture show
15
+
16
+ Why the mapping is exact, and not "the video starts when I pressed start"
17
+ ------------------------------------------------------------------------
18
+ `screenrecord` writes the presentation time of every frame, in the device's
19
+ elapsed-realtime clock, into a metadata track beside the video (
20
+ `writeWinscopeMetadata` in frameworks/av's screenrecord.cpp): a magic string, the
21
+ frame count, and one 64-bit timestamp per frame. That is the same clock
22
+ `/proc/uptime` reports, so a moment logged on the device and a frame in the video
23
+ are comparable numbers rather than two clocks to be eyeballed against each other.
24
+
25
+ This script reads that track out of the MP4 itself (ffprobe does not expose data
26
+ tracks) and pairs it with the container's own pts, so an event becomes a frame
27
+ index: the last frame presented at or before the event. An event therefore maps
28
+ to the picture that was on screen at that moment, which is what a screenshot
29
+ means. No frame rate is assumed; `screenrecord` records frames only when the
30
+ screen changes, and gaps in time are gaps in the list.
31
+
32
+ The one number that is not from the video is the offset between the device's
33
+ clock and this machine's: the suite logs `event` on this side, the frames are
34
+ timed on that side. It is sampled twice, half a round trip each way, and the
35
+ spread between the samples is reported as the accuracy of the mapping. A round
36
+ trip is tens of milliseconds; a frame is 33 ms at 30 fps, and the sidecar says
37
+ which of the two dominated. An event that already carries a device time
38
+ (`--data device_ns=...`, as the pixel watch's do) skips the offset altogether:
39
+ its frame is on the recording's own clock, and `timed: device` says so.
40
+
41
+ Where the device predates the metadata track (Android 12 and older screenrecord),
42
+ `stop` falls back to the offset from the recording's own start and says so; the
43
+ mapping is then only as good as that assumption, and `accuracy` names it.
44
+ """
45
+
46
+ import argparse
47
+ import json
48
+ import os
49
+ import re
50
+ import shutil
51
+ import struct
52
+ import subprocess
53
+ import sys
54
+ import time
55
+
56
+ MAGIC_V1 = b"#VV1NSC0PET1ME!#"
57
+ MAGIC_V2 = b"#VV1NSC0PET1ME2#"
58
+ CONTAINERS = {b"moov", b"trak", b"mdia", b"minf", b"stbl", b"dinf"}
59
+ STATE = "capture.json"
60
+ EVENTS = "events.jsonl"
61
+ RECORDING = "recording.mp4"
62
+ REMOTE = "/data/local/tmp/suite-capture.mp4"
63
+
64
+
65
+ def adb(args, serial="", capture=True):
66
+ command = [os.environ.get("ADB", "adb")]
67
+ if serial:
68
+ command += ["-s", serial]
69
+ command += args
70
+ if capture:
71
+ return subprocess.run(command, capture_output=True, text=True)
72
+ return subprocess.run(command)
73
+
74
+
75
+ def device_shell(command, serial=""):
76
+ return adb(["shell", command], serial)
77
+
78
+
79
+ def host_clock():
80
+ """This machine's monotonic seconds: a clock ntpd cannot step.
81
+
82
+ Termux cannot read /proc/uptime (SELinux), and time.monotonic is the same
83
+ kind of clock anyway. It is not the device's boot clock: the difference is
84
+ the machine's own suspend time, a constant for the run, and it lands in the
85
+ measured offset rather than in the mapping.
86
+ """
87
+ return time.monotonic()
88
+
89
+
90
+ def device_uptime(serial=""):
91
+ """The device's elapsed-realtime seconds, the clock the video's frames use."""
92
+ result = device_shell("cat /proc/uptime", serial)
93
+ if result.returncode != 0:
94
+ return None
95
+ return float(result.stdout.split()[0])
96
+
97
+
98
+ def sample_clock(serial=""):
99
+ """(device - host) in seconds, with the half round trip as its error bar."""
100
+ before = host_clock()
101
+ device = device_uptime(serial)
102
+ after = host_clock()
103
+ if device is None:
104
+ return None
105
+ # The device's reading was taken somewhere inside the call, so the middle of
106
+ # the call is the best guess at when, and half the call is how wrong that is.
107
+ return {"offset": device - (before + after) / 2.0, "error": (after - before) / 2.0}
108
+
109
+
110
+ # --- the MP4's metadata track ------------------------------------------------
111
+
112
+
113
+ def boxes(data, start, end):
114
+ pos = start
115
+ while pos + 8 <= end:
116
+ size, kind = struct.unpack(">I4s", data[pos:pos + 8])
117
+ header = 8
118
+ if size == 1:
119
+ size = struct.unpack(">Q", data[pos + 8:pos + 16])[0]
120
+ header = 16
121
+ if size < header or pos + size > end:
122
+ return
123
+ yield kind, pos, header, size
124
+ if kind in CONTAINERS:
125
+ yield from boxes(data, pos + header, pos + size)
126
+ pos += size
127
+
128
+
129
+ def full_box(body, fields):
130
+ """Read a version-0 full box's fields: a 4-byte version/flags, then values."""
131
+ values = struct.unpack(">" + fields, body[4:4 + struct.calcsize(">" + fields)])
132
+ return values
133
+
134
+
135
+ def track_tables(data, start, end):
136
+ """What a track's sample tables say: handler, sizes, offsets, chunk layout."""
137
+ handler = None
138
+ sizes, offsets, chunks = [], [], []
139
+ for kind, pos, header, size in boxes(data, start, end):
140
+ body = data[pos + header:pos + size]
141
+ if kind == b"hdlr":
142
+ handler = body[8:12]
143
+ elif kind == b"stsz":
144
+ default, count = full_box(body, "II")
145
+ sizes = [default] * count if default else list(
146
+ struct.unpack(">%dI" % count, body[12:12 + 4 * count]))
147
+ elif kind == b"stco":
148
+ count = full_box(body, "I")[0]
149
+ offsets = list(struct.unpack(">%dI" % count, body[8:8 + 4 * count]))
150
+ elif kind == b"co64":
151
+ count = full_box(body, "I")[0]
152
+ offsets = list(struct.unpack(">%dQ" % count, body[8:8 + 8 * count]))
153
+ elif kind == b"stsc":
154
+ count = full_box(body, "I")[0]
155
+ for i in range(count):
156
+ chunks.append(struct.unpack(">III", body[8 + 12 * i:20 + 12 * i])[:2])
157
+ return handler, sizes, offsets, chunks
158
+
159
+
160
+ def track_samples(data, offsets, chunks, sizes):
161
+ index, out = 0, []
162
+ for piece, (first_chunk, per_chunk) in enumerate(chunks):
163
+ last = (chunks[piece + 1][0] - 1) if piece + 1 < len(chunks) else len(offsets)
164
+ for chunk in range(first_chunk, last + 1):
165
+ offset = offsets[chunk - 1]
166
+ for _ in range(per_chunk):
167
+ if index >= len(sizes):
168
+ return out
169
+ out.append(data[offset:offset + sizes[index]])
170
+ offset += sizes[index]
171
+ index += 1
172
+ return out
173
+
174
+
175
+ def parse_metadata(path):
176
+ """Frame times from the Winscope metadata track: {clock, frames, epoch_offset}."""
177
+ data = open(path, "rb").read()
178
+ best = None
179
+ for kind, pos, header, size in boxes(data, 0, len(data)):
180
+ if kind != b"trak":
181
+ continue
182
+ handler, sizes, offsets, chunks = track_tables(data, pos + header, pos + size)
183
+ if handler != b"meta":
184
+ continue
185
+ for payload in track_samples(data, offsets, chunks, sizes):
186
+ # Version 2 first: the elapsed clock, which /proc/uptime also reports.
187
+ if payload.startswith(MAGIC_V2):
188
+ epoch_offset = struct.unpack("<q", payload[20:28])[0]
189
+ count = struct.unpack("<I", payload[28:32])[0]
190
+ stamps = struct.unpack("<%dQ" % count, payload[32:32 + 8 * count])
191
+ found = {"clock": "elapsed", "unit": 1e9, "frames": list(stamps),
192
+ "epoch_offset_ns": epoch_offset}
193
+ elif payload.startswith(MAGIC_V1):
194
+ count = struct.unpack("<I", payload[16:20])[0]
195
+ stamps = struct.unpack("<%dQ" % count, payload[20:20 + 8 * count])
196
+ found = {"clock": "monotonic", "unit": 1e6, "frames": list(stamps)}
197
+ else:
198
+ continue
199
+ if found["frames"] and (best is None or found["clock"] == "elapsed"):
200
+ best = found
201
+ if best is None:
202
+ return None
203
+ frames = best["frames"]
204
+ if any(b < a for a, b in zip(frames, frames[1:])):
205
+ sys.exit("capture: the metadata track's frame times are not in order")
206
+ return best
207
+
208
+
209
+ def container_pts(path):
210
+ """The container's own pts per frame, in presentation order."""
211
+ result = subprocess.run(
212
+ ["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
213
+ "frame=pts_time", "-of", "csv=p=0", path], capture_output=True, text=True)
214
+ if result.returncode != 0:
215
+ return []
216
+ stamps = []
217
+ for line in result.stdout.split():
218
+ try:
219
+ stamps.append(float(line))
220
+ except ValueError:
221
+ pass
222
+ return stamps
223
+
224
+
225
+ # --- commands ----------------------------------------------------------------
226
+
227
+
228
+ def load_state(directory):
229
+ path = os.path.join(directory, STATE)
230
+ if not os.path.isfile(path):
231
+ sys.exit("capture: no recording in %s (run start first)" % directory)
232
+ with open(path) as handle:
233
+ return json.load(handle)
234
+
235
+
236
+ def save_state(directory, state):
237
+ os.makedirs(directory, exist_ok=True)
238
+ with open(os.path.join(directory, STATE), "w") as handle:
239
+ json.dump(state, handle, indent=2)
240
+
241
+
242
+ def cmd_start(args):
243
+ os.makedirs(args.dir, exist_ok=True)
244
+ serial = args.serial or os.environ.get("ANDROID_SERIAL", "")
245
+ if adb(["get-state"], serial).returncode != 0:
246
+ sys.exit("capture: no device (set ANDROID_SERIAL or --serial)")
247
+ device_shell("rm -f %s" % REMOTE, serial)
248
+ # A leftover recorder from a dead run would hold the display's capture slot
249
+ # and would also be found by stop, so it is stopped before this one starts.
250
+ device_shell("pkill -INT screenrecord", serial)
251
+ clock = sample_clock(serial)
252
+ if clock is None:
253
+ sys.exit("capture: could not read the device clock")
254
+ option = ""
255
+ if args.size:
256
+ option += " --size %s" % args.size
257
+ if args.bit_rate:
258
+ option += " --bit-rate %s" % args.bit_rate
259
+ # setsid + & so the recorder outlives this adb call: start and stop are
260
+ # separate commands, and the suite does not hold a client open for a run.
261
+ device_shell("setsid screenrecord --time-limit 0%s %s </dev/null >/dev/null 2>&1 &"
262
+ % (option, REMOTE), serial)
263
+ running = False
264
+ for _ in range(40):
265
+ if device_shell("pidof screenrecord", serial).returncode == 0:
266
+ running = True
267
+ break
268
+ time.sleep(0.05)
269
+ if not running:
270
+ sys.exit("capture: screenrecord did not start")
271
+ state = {"remote": REMOTE, "serial": serial, "started": time.time(),
272
+ "host_clock": host_clock(), "clock": [clock],
273
+ "size": args.size or "native", "bit_rate": args.bit_rate or "default"}
274
+ save_state(args.dir, state)
275
+ with open(os.path.join(args.dir, EVENTS), "w") as handle:
276
+ handle.write(json.dumps({"name": "record:start", "host": host_clock()}) + "\n")
277
+ print("capture: recording to the device, events in %s" % os.path.join(args.dir, EVENTS))
278
+
279
+
280
+ def cmd_event(args):
281
+ directory = args.dir
282
+ if not os.path.isdir(directory):
283
+ return 0
284
+ if not os.path.isfile(os.path.join(directory, STATE)):
285
+ return 0
286
+ record = {"name": args.name, "host": host_clock()}
287
+ for pair in args.data or []:
288
+ key, _, value = pair.partition("=")
289
+ record.setdefault("data", {})[key.strip()] = value.strip()
290
+ with open(os.path.join(directory, EVENTS), "a") as handle:
291
+ handle.write(json.dumps(record) + "\n")
292
+ return 0
293
+
294
+
295
+ def cmd_stop(args):
296
+ state = load_state(args.dir)
297
+ serial = state.get("serial", "")
298
+ stop_sampled = sample_clock(serial)
299
+ device_shell("pkill -INT screenrecord", serial)
300
+ for _ in range(100):
301
+ if device_shell("pidof screenrecord", serial).returncode != 0:
302
+ break
303
+ time.sleep(0.05)
304
+ else:
305
+ sys.exit("capture: screenrecord would not stop")
306
+ recording = os.path.join(args.dir, RECORDING)
307
+ pull = adb(["pull", state["remote"], os.path.abspath(recording)], serial)
308
+ if pull.returncode != 0:
309
+ sys.exit("capture: could not pull the recording: %s" % pull.stderr.strip())
310
+ device_shell("rm -f %s" % state["remote"], serial)
311
+ # The file screenrecord closes is used as it is. It already keeps `moov`
312
+ # before `mdat`, so seeking it is a seek, and its metadata track carries the
313
+ # per-frame times: remuxing it through ffmpeg would drop that track and make
314
+ # the recording stop explaining itself.
315
+ meta = parse_metadata(recording)
316
+ pts = container_pts(recording)
317
+ sidecar = {"recording": os.path.basename(recording),
318
+ "size": os.path.getsize(recording),
319
+ "duration": pts[-1] - pts[0] if len(pts) > 1 else 0.0,
320
+ "events": [], "frames": []}
321
+ if state.get("clock") and stop_sampled:
322
+ state["clock"].append(stop_sampled)
323
+ if meta is None:
324
+ sidecar["sync"] = {"clock": "none", "accuracy_ms": None,
325
+ "why": "this screenrecord wrote no metadata track"}
326
+ else:
327
+ sidecar["frames"] = meta["frames"]
328
+ sidecar["sync"] = {"clock": meta["clock"], "unit_ns": int(meta["unit"]),
329
+ "frame_count": len(meta["frames"]),
330
+ "epoch_offset_ns": meta.get("epoch_offset_ns")}
331
+ clocks = state.get("clock") or []
332
+ if clocks:
333
+ offsets = [sample["offset"] for sample in clocks]
334
+ errors = [sample["error"] for sample in clocks]
335
+ sidecar["sync"]["offset"] = sum(offsets) / len(offsets)
336
+ sidecar["sync"]["offset_samples"] = len(offsets)
337
+ # The spread of the samples is the honest error of the offset; half a
338
+ # round trip is the floor. A frame at 30 fps is 33 ms, so this says
339
+ # whether the mapping is frame accurate or only approximate.
340
+ sidecar["sync"]["offset_spread_ms"] = 1000.0 * (
341
+ max(offsets) - min(offsets)) / 2.0
342
+ sidecar["sync"]["round_trip_ms"] = 1000.0 * sum(errors) / len(errors)
343
+ if pts and len(pts) != len(meta["frames"]):
344
+ # A count that differs means an index would point at the wrong
345
+ # picture; the timestamps are still good for --at.
346
+ print("capture: %d frames in the container, %d in the metadata: "
347
+ "events keep their frame index, and --at still works"
348
+ % (len(pts), len(meta["frames"])))
349
+ sidecar["events"] = map_events(args.dir, sidecar)
350
+ with open(os.path.join(args.dir, "recording.json"), "w") as handle:
351
+ json.dump(sidecar, handle, indent=2)
352
+ print_summary(args.dir, sidecar)
353
+ return 0
354
+
355
+
356
+ def map_events(directory, sidecar):
357
+ frames = sidecar.get("frames") or []
358
+ sync = sidecar.get("sync") or {}
359
+ pts = container_pts(os.path.join(directory, RECORDING))
360
+ out = []
361
+ path = os.path.join(directory, EVENTS)
362
+ if not os.path.isfile(path):
363
+ return out
364
+ for line in open(path, errors="replace"):
365
+ line = line.strip()
366
+ if not line:
367
+ continue
368
+ try:
369
+ event = json.loads(line)
370
+ except ValueError:
371
+ continue
372
+ mapped = {"name": event.get("name"), "host": event.get("host")}
373
+ data = event.get("data") or {}
374
+ if data:
375
+ mapped["data"] = data
376
+ device_ns = None
377
+ from_host = False
378
+ if data.get("device_ns"):
379
+ # A moment the device timed itself is already on the clock the frames
380
+ # are timed by, so it needs no offset and is not made worse by one.
381
+ # The pixel watch is this case: it passes on a frame of the screen it
382
+ # took, which the recording has its own timestamp for.
383
+ try:
384
+ device_ns = float(data["device_ns"])
385
+ except (TypeError, ValueError):
386
+ device_ns = None
387
+ if device_ns is None and frames and "offset" in sync:
388
+ device_ns = (event["host"] + sync["offset"]) * 1e9
389
+ from_host = True
390
+ if frames and device_ns is not None:
391
+ mapped["timed"] = "host" if from_host else "device"
392
+ at = 0
393
+ for index, stamp in enumerate(frames):
394
+ if stamp <= device_ns:
395
+ at = index
396
+ else:
397
+ break
398
+ mapped["frame"] = at
399
+ # How long before the event that frame had appeared. A still screen
400
+ # produces no new frames, so this is often seconds and is not an
401
+ # error: that frame was what was on screen. Negative means the event
402
+ # came before anything had been drawn, which only the start event of
403
+ # a run does.
404
+ mapped["since_frame_ms"] = round((device_ns - frames[at]) / 1e6, 1)
405
+ if device_ns < frames[0]:
406
+ mapped["before_video"] = True
407
+ if at < len(pts):
408
+ mapped["video_s"] = round(pts[at], 3)
409
+ else:
410
+ mapped["video_s"] = round(pts[-1] + (device_ns - frames[-1]) / 1e9, 3)
411
+ out.append(mapped)
412
+ return out
413
+
414
+
415
+ def print_summary(directory, sidecar):
416
+ sync = sidecar.get("sync") or {}
417
+ frames = sidecar.get("frames") or []
418
+ events = sidecar.get("events") or []
419
+ print("capture: %s %.1f s %.1f MB %d frame(s)"
420
+ % (sidecar["recording"], sidecar["duration"],
421
+ sidecar["size"] / 1e6, len(frames)))
422
+ if sync.get("clock") == "none":
423
+ print("capture: no per-frame timestamps: events are not mapped")
424
+ return
425
+ period = 0.0
426
+ if len(frames) > 1:
427
+ gaps = sorted((b - a) / sync["unit_ns"] for a, b in zip(frames, frames[1:]))
428
+ period = gaps[len(gaps) // 2]
429
+ print("capture: clock %s%s, events mapped %d/%d, typical frame %.0f ms, "
430
+ "clock offset error %.0f ms (%.1f ms round trip)"
431
+ % (sync["clock"], " (per-frame)" if frames else "",
432
+ sum(1 for e in events if "frame" in e), len(events), period * 1000,
433
+ sync.get("offset_spread_ms") or 0.0, sync.get("round_trip_ms") or 0.0))
434
+
435
+
436
+ def cmd_show(args):
437
+ directory = args.dir
438
+ sidecar_path = os.path.join(directory, "recording.json")
439
+ if not os.path.isfile(sidecar_path):
440
+ sys.exit("capture: no recording.json in %s (run stop first)" % directory)
441
+ with open(sidecar_path) as handle:
442
+ sidecar = json.load(handle)
443
+ print_summary(directory, sidecar)
444
+ for event in sidecar.get("events") or []:
445
+ if "frame" not in event:
446
+ print(" %-40s (not mapped)" % event["name"])
447
+ continue
448
+ print(" %-40s frame %4d at %7.3fs %6.0f ms after that frame"
449
+ % (event["name"], event["frame"], event["video_s"],
450
+ event["since_frame_ms"]))
451
+ return 0
452
+
453
+
454
+ def frame_command(recording, video_s, out):
455
+ # Seek just before the frame's own pts: ffmpeg seeks to a keyframe and decodes
456
+ # forward, and `-frames:v 1` then hands over the first frame at or after the
457
+ # seek, which is the frame that was on screen.
458
+ return ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y",
459
+ "-ss", "%.6f" % max(0.0, video_s - 0.001), "-i", recording,
460
+ "-map", "0:v:0", "-frames:v", "1", out]
461
+
462
+
463
+ def cmd_frames(args):
464
+ directory = args.dir
465
+ sidecar_path = args.sidecar or os.path.join(directory, "recording.json")
466
+ if not os.path.isfile(sidecar_path):
467
+ sys.exit("capture: no recording.json; run stop first")
468
+ with open(sidecar_path) as handle:
469
+ sidecar = json.load(handle)
470
+ recording = args.recording or os.path.join(directory, sidecar["recording"])
471
+ if not os.path.isfile(recording):
472
+ sys.exit("capture: no recording at %s" % recording)
473
+ events = sidecar.get("events") or []
474
+ wanted = [name.strip() for name in (args.event or "").split(",") if name.strip()]
475
+ missing = [name for name in wanted
476
+ if not any(e["name"] == name and "video_s" in e for e in events)]
477
+ if missing:
478
+ sys.exit("capture: no mapped event named: " + ", ".join(missing))
479
+ picks = []
480
+ if args.all:
481
+ picks = [e for e in events if "video_s" in e]
482
+ for name in wanted:
483
+ # A repeated name (a check that marks its own start and end with the same
484
+ # name) gives every moment, not one of them.
485
+ picks.extend([e for e in events if e["name"] == name and "video_s" in e])
486
+ for value in (args.at or "").split(","):
487
+ value = value.strip()
488
+ if value:
489
+ picks.append({"name": "at-%s" % value, "video_s": float(value)})
490
+ if not picks:
491
+ sys.exit("capture: say what to extract: --event NAME, --at SECONDS, or --all")
492
+ os.makedirs(args.out, exist_ok=True)
493
+ for pick in picks:
494
+ slug = re.sub(r"[^A-Za-z0-9_.-]+", "-", pick["name"]).strip("-")
495
+ out = os.path.join(args.out, "%07.3fs-%s.png" % (pick["video_s"], slug))
496
+ result = subprocess.run(frame_command(recording, pick["video_s"], out),
497
+ capture_output=True, text=True)
498
+ if result.returncode != 0:
499
+ sys.exit("capture: ffmpeg failed at %.3fs: %s"
500
+ % (pick["video_s"], result.stderr.strip()))
501
+ print("%s %.3fs %s" % (out, pick["video_s"], pick.get("name", "")))
502
+ return 0
503
+
504
+
505
+ def main(argv=None):
506
+ parser = argparse.ArgumentParser(
507
+ description="Record a run once, keep the moments as events, extract "
508
+ "frames when asked.")
509
+ parser.add_argument("--dir", default="out/capture",
510
+ help="where the recording and its events live")
511
+ sub = parser.add_subparsers(dest="command", required=True)
512
+
513
+ def with_dir(parser, **kwargs):
514
+ """Every subcommand takes --dir: the shell writes it after the verb."""
515
+ parser.add_argument("--dir", dest="sub_dir", default="")
516
+ return parser
517
+
518
+ start = with_dir(sub.add_parser("start", help="start recording the device's screen"))
519
+ start.add_argument("--serial", default="")
520
+ start.add_argument("--size", default="", help="WxH; native by default")
521
+ start.add_argument("--bit-rate", dest="bit_rate", default="6M")
522
+ start.set_defaults(run=cmd_start)
523
+
524
+ event = with_dir(sub.add_parser("event", help="mark a moment; no adb call"))
525
+ event.add_argument("name")
526
+ event.add_argument("--data", action="append", metavar="KEY=VALUE")
527
+ event.set_defaults(run=cmd_event)
528
+
529
+ stop = with_dir(sub.add_parser("stop", help="stop, pull, and map the events to frames"))
530
+ stop.set_defaults(run=cmd_stop)
531
+
532
+ show = with_dir(sub.add_parser("show", help="the mapped events of a recording"))
533
+ show.set_defaults(run=cmd_show)
534
+
535
+ frames = with_dir(sub.add_parser("frames", help="extract frames, now"))
536
+ frames.add_argument("--event", default="", help="event name(s), comma separated")
537
+ frames.add_argument("--at", default="", help="seconds into the video, comma separated")
538
+ frames.add_argument("--all", action="store_true", help="every mapped event")
539
+ frames.add_argument("--out", default="out/frames")
540
+ frames.add_argument("--recording", default="")
541
+ frames.add_argument("--sidecar", default="")
542
+ frames.set_defaults(run=cmd_frames)
543
+
544
+ args = parser.parse_args(sys.argv[1:] if argv is None else argv)
545
+ # `--dir` is accepted on either side of the verb; the shell writes it after.
546
+ args.dir = args.sub_dir or args.dir
547
+ return args.run(args)
548
+
549
+
550
+ if __name__ == "__main__":
551
+ sys.exit(main(sys.argv[1:]))