Skip to content

About

A cross-platform client for Apple's macOS Screen Sharing High Performance mode

Resources

Stars

4 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

175 Commits

Folders and files

Repository files navigation

iShareScreen

Cross-platform Python client for Apple's macOS Screen Sharing High Performance mode (HEVC RExt 4:4:4 over UDP/SRTP). Renders the host Mac's screen in a native wgpu window with hardware decode where available.

Setup

On the host Mac (the target you want to view)

  1. Any modern macOS that supports the Screen Sharing app's High Performance mode (Apple Silicon, recent macOS).
  2. System Settings → General → Sharing → Screen Sharing → toggle on.

On the viewing machine

macOS

  1. Install Python 3.10 or later (from python.org, brew install python, or uv python install 3.13).
  2. Install iShareScreen:
    pip install git+https://github.com/renegadelink/iShareScreen.git

Windows

  1. Install Python 3.10 or later from python.org (the installer includes pip; check "Add python.exe to PATH" during install).

  2. Open PowerShell or cmd and run:

    pip install git+https://github.com/renegadelink/iShareScreen.git
  3. Audio uses the included PyAV plain AAC-ELD decoder automatically, without an environment variable or another DLL. Audible playback was confirmed with a macOS 27.2 host. If PyAV cannot initialize, the client tries libfdk-aac, available through MSYS2:

    pacman -Sy --noconfirm mingw-w64-x86_64-fdk-aac

    This drops libfdk-aac-2.dll at C:\msys64\mingw64\bin\, which iss searches automatically. If you already have scoop, scoop install msys2 followed by the same pacman command also works — iss looks under %USERPROFILE%\scoop\apps\msys2\current\mingw64\bin too. Without a usable audio decoder, video continues and a warning is logged. To select FDK explicitly for a different host configuration, set $env:AAC_BACKEND = 'fdk' before launching from the same PowerShell window. See audio configuration and negotiation notes.

Linux (Debian / Ubuntu)

  1. Install Python and the system libraries that the GPU + window stack need (Vulkan loader, OpenGL, X11 / Wayland surfaces, PortAudio, AAC-ELD-SBR audio decoder):

    sudo apt install python3 python3-pip python3-venv \
        libvulkan1 libgl1 libegl1 \
        libxrandr2 libxinerama1 libxcursor1 libxi6 \
        libportaudio2 libfdk-aac2 \
        xclip

    libfdk-aac2 is optional: audio tries the included PyAV decoder first, then FDK if PyAV cannot initialize. The PyAV path was verified on Windows against macOS 27.2. Video works without an audio decoder.

    xclip enables bidirectional clipboard sync with the macOS host. On Wayland desktops use wl-clipboard instead. If neither is installed iss logs a one-line warning at startup and runs without clipboard sync — everything else still works.

  2. (Optional, for hardware HEVC decode on Intel GPUs) install vaapi:

    sudo apt install vainfo intel-media-va-driver-non-free

    For AMD, swap the driver: sudo apt install mesa-va-drivers.

  3. Install iShareScreen (in a venv recommended):

    python3 -m venv ~/.venvs/iss
    ~/.venvs/iss/bin/pip install git+https://github.com/renegadelink/iShareScreen.git
    ~/.venvs/iss/bin/iss     # or symlink to ~/.local/bin

For Fedora / Arch / openSUSE, translate the apt package names with your distro's package manager (most are named the same or very close).

Firewall

iss connects to the host Mac over TCP 5900 (control) plus two UDP flows: 5900 (audio + RTCP) and 5901 (video). It sends from both UDP ports during connect. If a firewall still blocks the stream, allow UDP 5900–5901 inbound.

Usage

iss

Opens the terminal UI: a connect form for host / username / password (masked) and resolution, then a live session view with per-tile fps and loss, throughput, UDP queue health, and a log tail. The actual screen streams in a separate window. Last-session values pre-fill the form on the next launch. Passwords are saved only when you enable Remember password in system credential store, and are kept in the OS credential store rather than the connection profile. Leave the password blank on later connections.

Any flag accepted by iss --headless also pre-fills the form, so launchers can do:

iss --host mac.local -u me --advertise 1920x1080 --no-curtain

Useful keys in the live session: f force IDR refresh (fixes the rare gray patch the auto-recovery doesn't catch), r reconnect, d disconnect, Ctrl-B save a bug-report snapshot, q quit.

The native desktop viewer uses immediate presentation on macOS to keep display buffer waits off the input path. Set ISS_VSYNC=1 to restore display synchronization if needed. ISS_PRESENT_FPS controls the desktop redraw limit (default 120); input processing and decoding continue independently of that limit. For example, ISS_PRESENT_FPS=240 iss --frontend desktop favors more frequent updates at the cost of additional GPU work.

The test suite uses deterministic protocol and queue tests by default. On macOS, ISS_NATIVE_TESTS=1 pytest also checks that decoded pixel planes remain valid after their frame and decoder are released.

For CI / scripted use:

echo "$PASSWORD" | iss --headless --host mac.local -u me --password-stdin --auto-quit-secs 30

Saved passwords and Kerberos

To save a password after the first successful connection, then reuse it:

iss --host mac.local -u me --remember-password  # prompts once in a terminal
iss --host mac.local -u me                    # reads the saved password
iss --host mac.local -u me --forget-password  # deletes this endpoint/account's password

The store is macOS Keychain, Windows Credential Manager, or Linux Secret Service (for example GNOME Keyring, with an unlocked desktop D-Bus session). There is no plaintext-file fallback. Entries are scoped to host, TCP port and username; hostname and IP aliases remain separate entries. --password-stdin overrides a saved password, and --no-keyring bypasses the store entirely. First access or a locked store may require a system authorization prompt. Replacing an outdated saved password requires entering the new password and enabling Remember password again.

The Authentication selector also supports Kerberos, using Apple RFB security type 35. It reuses cached tickets first. On macOS, supplying a password also permits initial ticket acquisition through Apple's gss_aapl_initial_cred / LKDC API, following the libvncserver example and its authentication implementation.

# Existing Kerberos tickets; no password or credential-store access:
iss --host mac.example.com -u me --auth kerberos --no-keyring \
    --krb-realm EXAMPLE.COM --krb-service vnc/mac.example.com@EXAMPLE.COM

# macOS LKDC: first connection; discover the realm and acquire tickets.
# At a terminal --password-stdin prompts without echoing the password.
iss --host mac.local -u me --auth kerberos \
    --password-stdin --remember-password

# Later connections: reuse tickets, or reacquire using the saved password.
iss --host mac.local -u me --auth kerberos

--krb-principal overrides the client identity (otherwise user@realm). The default service is vnc@host, or vnc/REALM@REALM for an LKDC realm. The original hostname is retained for service identity even when transport uses a resolved IPv4 address. With a short username and no explicit realm/principal, the client discovers the remote Mac's LKDC realm via a password-free AS-REQ to TCP/UDP 88, before acquiring credentials. No SSH or prior desktop login is needed. In the connect form, enter the host, username and Mac account password on the first connection; realm and principal configuration is automatic. Fully qualified client/service principals or an explicit realm override discovery; use these for conventional domain KDCs. If cached credentials cannot produce a service ticket, macOS retries acquisition once with an available password before sending the RFB AP-REQ. Linux Kerberos requires libgssapi-krb5 and tickets acquired beforehand, such as with kinit; this Kerberos backend is unavailable on Windows. Kerberos failures do not fall back to password authentication. Starting a separate user's desktop still requires a password for Apple's SessionSelect message, even when Kerberos authenticates the connection.

Validation covers the native macOS credential-store round trip, native GSS library/name handling, live remote LKDC realm discovery, and simulated type-35 framing and error paths. A full Kerberos connection to a real Screen Sharing host remains to be verified.

License

AGPL-3.0-or-later. See LICENSE.

This is an independent reverse-engineering of a publicly-documented network protocol. No Apple source code, headers, or symbols are included.

About

A cross-platform client for Apple's macOS Screen Sharing High Performance mode

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages