Introducing a new way to review your PRs.

Read the announcement

genymobile / scrcpy

Display and control your Android device

View on GitHub

13 documents · Updated Nov 16, 2026

docs / client-recording-file-push-and-assets

Client recording, file push, and packaged assets

Overview

This area covers the native client surfaces that create local recording files, react to user file drops by pushing or installing files on the Android device, and package user-facing desktop assets.

Recording is owned by app/…/recorder.c and declared in app/…/recorder.h. app/…/scrcpy.c creates the recorder only when options->record_filename is set, passing the chosen record_format, enabled video/audio flags, and record_orientation, then starts a background scrcpy-recorder thread before attaching video_packet_sink and/or audio_packet_sink to the corresponding demuxer packet sources. The recorder opens the output itself on that thread with FFmpeg/libavformat, maps scrcpy record formats to muxers (mp4, matroska, opus, flac, wav), writes Recorded by scrcpy <version> metadata, and closes the AVIO/context after trailer writing.

app/…/recorder.c receives encoded packets through sc_packet_sink callbacks rather than encoding media itself. Each sink open creates an AVStream, copies codec parameters, records the stream index, and decides whether the first packet must be consumed as codec extradata: video expects a config packet except for VP8/VP9, and audio expects one except for raw PCM. The recorder thread waits until enabled streams are initialized and required config packets are queued, converts those config packets to stream extradata, then writes the container header. Normal packets are queued under a mutex/condition variable, cloned with av_packet_ref, and consumed by the thread. PTS values are in microseconds in the scrcpy packet path, then rescaled to the container stream time base on write; the first usable video/audio packet establishes a zero PTS origin, non-monotonic PTS values are bumped, and video packet duration is filled from the following frame, with an arbitrary duration for the final frame. If audio initialization is disabled dynamically, sc_recorder_audio_packet_sink_disable() clears the audio flag and lets recording proceed with video only. End-of-stream on either sink, an explicit stop, or a write failure sets stopped; app/…/scrcpy.c later stops, joins, and destroys the recorder, and sc_recorder_on_ended() reports failures as SC_EVENT_RECORDER_ERROR.

File push is owned by app/…/file_pusher.c and declared in app/…/file_pusher.h. app/…/scrcpy.c initializes it only when both windowing and control are enabled, because the user-facing entry point is drag-and-drop on the scrcpy window and the pusher needs a controller for follow-up device commands. app/…/input_manager.c handles SDL_EVENT_DROP_FILE: it ignores drops for camera mode, missing control, or disconnection; duplicates the dropped path; selects SC_FILE_PUSHER_ACTION_INSTALL_APK for .apk suffixes and SC_FILE_PUSHER_ACTION_PUSH_FILE otherwise; then transfers ownership of the allocated path to sc_file_pusher_request().

The pusher is lazily threaded. sc_file_pusher_request() starts the scrcpy-file thread on the first request, logs the requested operation, queues {action, file} in a VecDeque, and wakes the worker when the queue was empty. The worker drains requests serially. APK requests call sc_adb_install() for the connected serial. Other files call sc_adb_push() to push_target, defaulting to /sdcard/Download/ when --push-target is unset; on successful push, request_scan_file() sends an SC_CONTROL_MSG_TYPE_SCAN_FILE control message with the target path so Android media providers notice the new file. Shutdown in app/…/scrcpy.c stops the pusher before controller teardown, interrupts any in-flight ADB operation through sc_intr_interrupt(), joins the thread if it was lazily started, destroys synchronization primitives, frees the duplicated serial, and frees any unprocessed queued file paths.

Packaged static assets under app/data/** are user-facing integration files rather than runtime logic. app/data/bash-completion/scrcpy and app/data/zsh-completion/_scrcpy expose command-line options and value completions, including recording options (--record, --record-format, --record-orientation) and file-push target selection (--push-target). app/data/scrcpy.desktop launches scrcpy through an interactive shell without a terminal so user shell PATH/ADB setup is honored, while app/data/scrcpy-console.desktop launches scrcpy --pause-on-exit=if-error in a terminal for visible failures. app/data/scrcpy-noconsole.vbs wraps scrcpy.exe on Windows without a visible console while preserving arguments, and app/data/open_a_terminal_here.bat opens a command prompt in-place for Windows bundles. app/…/scrcpy.svg, app/…/scrcpy.png, and app/data/icon.ico are application icons for desktop/package/resource use; app/…/disconnected.png is the displayed disconnected-state artwork. Windows executable metadata is in app/scrcpy-windows.rc, which embeds data/icon.ico, the manifest, and version/product strings; app/scrcpy-windows.manifest marks the executable DPI-aware with PerMonitorV2 awareness.

Coupling

  • If enum sc_record_format or option parsing changes supported recording formats, update sc_recorder_get_format_name() in app/…/recorder.c and the completion files app/data/bash-completion/scrcpy and app/data/zsh-completion/_scrcpy; otherwise users can request formats that do not map to a muxer or completions can advertise stale values.
  • If packet timestamp units change upstream of the recorder, update SCRCPY_TIME_BASE and the PTS-origin/duration logic in app/…/recorder.c; the recorder assumes incoming AVPacket timestamps are microseconds before av_packet_rescale_ts() writes them to the container.
  • If supported codecs change their config-packet behavior, revisit video_expects_config_packet and audio_expects_config_packet in app/…/recorder.c; the header writer blocks until required config packets arrive and rejects a first “config” packet that has a real PTS.
  • If drag-and-drop behavior changes in app/…/input_manager.c, keep ownership semantics in app/…/file_pusher.h intact: sc_file_pusher_request() takes a heap-allocated char * and frees it after processing, while callers must free it only when queuing fails.
  • If file push should work without the displayed window or without control, change both initialization in app/…/scrcpy.c and post-push scanning in app/…/file_pusher.c; the current implementation needs control to send SC_CONTROL_MSG_TYPE_SCAN_FILE after successful adb push.
  • If command-line options are renamed or added, update both shell completion assets in app/data/bash-completion/scrcpy and app/data/zsh-completion/_scrcpy; they duplicate option names and enum-like value lists instead of generating them from app/…/options.h.
  • If release versioning changes, keep app/scrcpy-windows.rc in sync with the built product version because that file embeds Windows Explorer metadata independently of the C version metadata used by the running app.

Risks

  • app/…/recorder.c has many historical timestamp and stream-start fixes (Record at least video packets on stop, Fix PTS when not monotonically increasing, Fix recorder waiting when stream disabled, Fix VPx recording). If packet ordering, disabled-stream handling, or VPx/raw codec setup changes, recording can hang before writing headers or produce invalid/non-playable files.
  • app/…/recorder.c queues cloned AVPacket * values from producer threads and frees them on several error/stop paths; prior fixes include packet leak and queue cleanup commits. If a new push error path skips av_packet_free() or queue clearing, long recordings can leak packets or double-free during teardown.
  • app/…/file_pusher.c stops immediately when stopped is set and intentionally does not drain queued requests. If shutdown ordering changes around sc_file_pusher_stop()/sc_file_pusher_join() in app/…/scrcpy.c, user-dropped files may be silently abandoned or an in-flight ADB operation may not be interrupted.