Does: an Android emulator's or a leased physical phone's screen as core's screen frames, through the vendored scrcpy server and our own client. Flows: Android driver, input, stream.
The target:
- The driver hands the capture one
ScreenTargetper device. Every adb command and connection of a session goes through it:argsstart at the adb subcommand, and the target aims them at its device and picks its adb server. - The capture names no adb server port and runs no version check of its own. The physical handler (
../physical-handler.ts) is the one place that knows both (architecture rule 10; safety rule: the check before every physical command). Each of a phone'srun,spawnandconnectpasses the check first; a closed check sends nothing and throwsScreenUnavailableErrorwith its message. - A screen stream touches only its own
scid: its jar path and socket name; never another stream's.
What a stream does to the device:
- A screen stream changes no device setting and drops no frame. One exception: a phone's stream sets stay awake (
stay_awake=true, scrcpy'sstay_on_while_plugged_in) while it runs, and scrcpy's clean-up process puts the old value back when the server ends. An emulator's server never gets the option. - A phone's screen state is read before anything is pushed (
mWakefulnessindumpsys power).AsleeporDozing: oneKEYCODE_WAKEUP, then the same read again; still off isScreenUnavailableError, and nothing is pushed. - Only a read that names one of those two words is a fact about the screen. Another word, no line, a non-zero exit or a timed-out read goes on, with no wake.
- The wake is the only key this stream sends. Emulators skip the read and the wake.
Start and stop:
- No
adb forward: the session speaks adb's host protocol through the target, so a daemon that dies leaves no listening port on the host. FAILon the second request (nothing listening yet), a refused connect, or a socket that closes before the server's zero byte is retried.FAILon the first refuses.- The start budget (
START_DEADLINE_MSinscrcpy-link.ts) counts from the moment the server's process started, so a phone's check before the spawn does not spend it. Each step keeps its own limit; there is no overall budget. - A phone's worst case is the sum of those limits. The console's wait for a stream's headers (
STREAM_HEAD_TIMEOUT_MSinui/src/state/screen.ts) must stay above it. - The screen read, the wake and the push cannot be interrupted: a stop during one waits for it and runs nothing after it. A stopped open cleans up (shell killed, jar removed) before it throws.
closeis idempotent. It removes the jar through the target, so a check still closed then sends nothing andclosestill resolves. The body's end, error or cancel calls it.
The body:
- It is pull-based (
highWaterMark: 0): the socket is read only when the body's reader pulls, so nothing is dropped. - The control socket is the server's second connection, made before the video is read. A refused control connection refuses the open; its end before
close, or a failed write to it, ends the stream like the video's end. - A still screen sends no key frame, so
RESET_VIDEO_AFTER_MS(ADR 0079 §5) without one makes the session write reset video; the answer is relayed as for a rotation. - After
ALIVE_AFTER_MSof quiet the body sends an emptyaliveframe, only after the first key frame, so an encoder that never paints meets the stream's silence bound. - A rotation starts a new scrcpy session: a new meta frame, then a new description before the next picture. The browser decoder re-reads both mid-stream.
- A body whose socket ends errors with the server's last output and closes the feed.
- A fresh emulator answers its first resets slowly, so a joiner then waits longer than the ADR's bound for a key frame.
- The
avcCrecord omits the High-profile extension (chroma format, bit depths); browsers accept it. - A phone that is not charging is woken but not held awake: stay awake does nothing without power. When its
screen turns off mid-stream it shows its last picture, still marked live by
aliveframes, until the screen is on again or the lease ends. Nothing ends the stream for it. - A phone woken to its lock screen streams the lock screen. simlock does not unlock it.
- A viewer that joins a phone that went dark mid-stream sees no picture. A joiner opens nothing, so nothing wakes it.
- The stay-awake setting stays on if the phone loses power or reboots before the clean-up process writes the old value back.
- A holder's own stay-awake change is overwritten: a holder that changes
stay_on_while_plugged_inover passthroughadbwhile a stream is open has it replaced when the stream ends, since scrcpy writes back the value it found. - A pushed jar can survive on a phone when the version check closes after the push and stays closed through the
close and the server never started: the
rm -fgoes through that check and is not sent. A server that started deletes its own jar (cleanup=true). The jar's digest is not checked at push either.