Gitzian has two sides. On the host side, a Windows or Linux computer runs the Gitzian GPU Streamer. This is the machine whose display output you want to send to a small screen. On the device side, a Raspberry Pi usually runs the Gitzian Pi client, talks to the decoder hardware, and drives the connected display.

The standard Kit/reference setup uses the Gitzian decoder with the Raspberry Pi HAT. The DIY path lets you build custom hardware around the decoder; the HAT PCB and Python client code are available as references. See the DIY page for that.

Requirements are easiest to read as two sides: the server, where the image is created, and the streaming client / decoder side, where the image is received and shown on the small display.

Quick overview

You need a server and a streaming client / decoder side.

• Server: Windows, Linux / KDE Plasma, or Raspberry Pi running the Gitzian GPU Streamer.
• Streaming client: Raspberry Pi running gitzian-pi, or your own controller based on the Python client code.
• Hardware: Gitzian decoder, supported display, and either the Raspberry Pi HAT or your own carrier board.
• Network: local network, same device, internet/VPN, or your own embedded setup.

Hardware requirements

Required: Gitzian decoder hardware and a supported display. You can get them as a Display Streaming Kit with display, or use a Decoder Kit for Supported Displays if you already have a compatible panel.

Kit/reference path: decoder + Raspberry Pi HAT + display bridge + Raspberry Pi client.

DIY path: decoder + custom HAT/carrier board + your own controller. The Raspberry Pi HAT PCB and the Python client code are useful references if you want to build around the decoder. More on that is collected on the DIY page.

Supported displays

The decoder supports multiple display configurations. Use firmware and hardware that match the display you connect. I am expanding the supported display list step by step, including matching open-source designs for driving them.

Software requirements

Server: Gitzian GPU Streamer. A better GPU usually gives lower latency and more headroom. A dedicated GPU is not required; many modern iGPUs work well. Raspberry Pi can also be used as a server. If you can choose, use Raspberry Pi 5 for that path.

Client: gitzian-pi on Raspberry Pi, or custom client code based on the Gitzian Python package.

Display setup: Windows can use the optional virtual display driver. Linux / KDE Plasma can use the EDID display setup when a dedicated display mode is needed.

Server platform support

Supported means tested and documented. Planned means intended, but not ready yet. Possible means it can be looked at if there is real demand, or it may already work but is untested.

Back to contents

For the first test, keep everything on the same local network. Install the Gitzian GPU Streamer on the Windows or Linux host, install the Gitzian Pi client on the Raspberry Pi, set the host IP in the client config, and start the client.

Raspberry Pi quick commands

sudo raspi-config
sudo apt update
sudo apt install -y python3-dev build-essential
pip install gitzian
gitzian-pi --init-config
nano ~/.config/gitzian/client/default.ini
gitzian-pi

In the config, set the server IP address. If the server runs on the same device as the client, use 127.0.0.1.

[network]
enabled = true
server_host = 10.77.0.4
server_port = 55556

Back to contents

On Windows, install the Gitzian GPU Streamer. It can stream a full display, a selected area of an existing display, or a virtual display created by a virtual display driver.

Before remote or headless setup

If you operate the Windows machine remotely, enable Remote Desktop first if your Windows edition supports it. OpenSSH Server is also useful as a fallback. Confirm that remote access works before installing display drivers, changing monitor layout, or rebooting.

The current streamer does not capture UAC prompts, the Windows login screen, the lock screen, or other secure system screens. For remote reboot setups, automatic login can avoid getting stuck before the streamer starts. If a UAC prompt appears, use RDP or another fallback path to confirm it.

Graphics

The Windows streamer needs working GPU acceleration for normal performance. A dedicated GPU is not required; many integrated GPUs work well, and Intel UHD 620 has been tested successfully. The graphics adapter should support OpenGL ES 3.1 or newer. If you do not know what that means, chances are very high that your GPU already supports it. Virtual GPUs can work when their driver provides proper acceleration. I also run Gitzian servers successfully in KVM machines, using two old Nvidia GPUs, each bound to one KVM on the same old 2017 gaming PC. That works very fine. KVM is an advanced topic, but if you are motivated, it is a rabbit hole worth going down.

Install

Download the latest Windows installer from the Gitzian downloads page, run it, start the Gitzian GPU Streamer, and allow private network access if Windows Firewall asks. Then select the display or screen area you want to stream.

After installation, this is roughly what you can expect on Windows: a small Gitzian GPU Streamer app with settings for the server port, capture viewport, input backend, startup behavior, and reload/save actions.

Back to contents

Gitzian can stream from a viewport on a real display, or from a dedicated virtual/display setup. Multi-display setups are possible on Windows and on Linux / KDE Plasma. In that case, select the output or viewport you want to stream.

If your GPU/display setup supports the target resolution directly, the viewport dimensions can match the client display. If not, use a virtual display setup. A virtual display is also the cleaner path when you want a dedicated output that is not part of your normal desktop.

Virtual Display (Windows): on Windows, the optional virtual display driver is recommended for the best experience. Install the MikeTheTech / Virtual Display Driver, follow their install guide, create one virtual display, and set it to the resolution of your target display.

Virtual Display (Linux / EDID): on Linux / KDE Plasma, Gitzian uses the Linux display path directly. Viewport and multi-display setups are supported there too. EDID setup is used when you need a dedicated display mode; for custom EDID files, use the EDID guide.

Back to contents

The currently supported public path is KDE Plasma 6.3.6 on Wayland, including Plasma Mobile setups.

Install

Add the Gitzian APT repository first.

sudo apt update
sudo apt install -y curl

curl -fsSL https://apt.gitzian.com/gitzian-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/gitzian-archive-keyring.gpg >/dev/null

ARCH="$(dpkg --print-architecture)"

sudo tee /etc/apt/sources.list.d/gitzian.sources >/dev/null <<EOF
Types: deb
URIs: https://apt.gitzian.com
Suites: trixie
Components: main
Architectures: ${ARCH}
Signed-By: /usr/share/keyrings/gitzian-archive-keyring.gpg
EOF

sudo apt update
sudo apt install -y libgitzian-api gitzian-kwin-plugin gitzian

sudo tee -a /etc/apt/sources.list.d/gitzian.sources >/dev/null <<'EOF'

Types: deb-src
URIs: https://apt.gitzian.com
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/gitzian-archive-keyring.gpg
EOF

sudo apt update
apt source gitzian-api

The Gitzian KWin plugin (KDE Plasma) should start automatically after a reboot. Right after the first installation, load it once manually if you do not want to reboot yet:

qdbus6 org.kde.KWin /Plugins org.kde.KWin.Plugins.LoadPlugin gitzian_kwin_plugin

Verify that the plugin is visible:

qdbus6 org.kde.KWin /KWin supportInformation

Wayland and cursor setup

Run the streamer on the Wayland path. For KDE Plasma setups, also enable the software cursor.

mkdir -p ~/.config/plasma-workspace/env

cat > ~/.config/plasma-workspace/env/kwin_env.sh <<'EOF'
#!/bin/sh
export KWIN_FORCE_SW_CURSOR=1
export EGL_PLATFORM=wayland
EOF

chmod +x ~/.config/plasma-workspace/env/kwin_env.sh
reboot

Virtual Display (Linux / EDID)

KDE Plasma / Wayland setups use an EDID-based display setup when you need a dedicated target display mode. For the full EDID generator guide, including refresh-rate selection, use the EDID guide.

Streamer profile

Set the profile before running the streamer. Use dgpu for a dedicated GPU. Use raspi when the Raspberry Pi itself is the server.

gitzian-gpu config set calibration.profile dgpu
# or, on Raspberry Pi server setups:
gitzian-gpu config set calibration.profile raspi

If you are unsure, run calibration:

gitzian-gpu calibrate

Start the server:

EGL_PLATFORM=wayland gitzian-gpu run

gitzian-gpu displays list
gitzian-gpu displays prefer first
gitzian-gpu displays prefer name:HDMI-A-1
gitzian-gpu config print
gitzian-gpu server status
gitzian-gpu server reload
gitzian-gpu doctor

[controller]
port=55556
stream_width=720
stream_height=720

[kwin]
preferred_outputs=first
fallback_output=first
viewport_x=0
viewport_y=0

[calibration]
# profile options: dgpu, igpu, raspi, expert
profile=raspi
# expert mode params
p1=0
p2=0
p3=0

[meta]
generation=1

kwriteconfig6 --file kwinrc --group Plugins --key gitzian_kwin_pluginEnabled false
qdbus6 org.kde.KWin /KWin reconfigure

Back to contents

The Raspberry Pi runs the Gitzian Pi client. It receives the stream, drives the connected display through the decoder, handles backlight and touch hardware where supported, and forwards local input events.

Recommended models are Raspberry Pi Zero 2 W, Raspberry Pi 2, Raspberry Pi 3, Raspberry Pi 4, and Raspberry Pi 5. Raspberry Pi Zero v1.1 works too, but its Wi-Fi is weaker. It is useful for simple setups, but not the best choice for gaming or fluid video.

First enable I2C and SPI in sudo raspi-config. Then install dependencies and the Python package:

sudo apt update
sudo apt install -y python3-dev build-essential
pip install gitzian

Create the default config and set the server IP address:

gitzian-pi --init-config
nano ~/.config/gitzian/client/default.ini

[network]
enabled = true
server_host = 10.77.0.4
server_port = 55556

Replace 10.77.0.4 with your server IP address. If the server runs on the same device as the client, use 127.0.0.1. Then start the client:

gitzian-pi

Raspberry Pi 5

Raspberry Pi 5 is supported and tested. Install the Gitzian RP1 GPCLK0 DKMS package before running the client.

sudo apt update
sudo apt install -y curl

curl -fsSL https://apt.gitzian.com/gitzian-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/gitzian-archive-keyring.gpg >/dev/null

ARCH="$(dpkg --print-architecture)"

sudo tee /etc/apt/sources.list.d/gitzian.sources >/dev/null <<EOF
Types: deb
URIs: https://apt.gitzian.com
Suites: trixie
Components: main
Architectures: ${ARCH}
Signed-By: /usr/share/keyrings/gitzian-archive-keyring.gpg
EOF

sudo apt update
sudo apt install -y gitzian-rp1-gpclk0-dkms

PyPI package page: pypi.org/project/gitzian

Back to contents

A Raspberry Pi can also be used as the server with KDE Plasma. This is useful when you want a compact local setup or a fallback when the network/server connection is not available.

If you want to use a Raspberry Pi as the server, I currently recommend Raspberry Pi 5. As a rough example, Raspberry Pi 5 can currently reach up to about 25 FPS at 720x720. Raspberry Pi 4 is closer to 12 FPS at 720x720. That is already useful for common GUI usage with low latency, but not the best path for gaming or fluid video.

Raspberry Pi 4 and older models can still have use cases, but expect lower frame rates and less headroom when the Pi is used as the server. Performance work is ongoing; there is still room for improvement.

For a Raspberry Pi server, follow the same Linux / KDE Plasma setup as above. Then set the calibration profile to raspi.

gitzian-gpu config set calibration.profile raspi
EGL_PLATFORM=wayland gitzian-gpu run

If the Raspberry Pi should start Gitzian automatically after boot, enable autologin in KDE Plasma.

Back to contents

Assembly is mostly board-to-board alignment. Start with the display bridge: connect the display cable to the display bridge before attaching the bridge to the Gitzian decoder. This keeps the small connector area accessible and avoids forcing the cable after the boards are already stacked.

Use the white guide lines to align the decoder with the display bridge. Line up the board-to-board connectors, then press straight down with firm, even pressure until the connectors are fully seated. Do not twist or rock the boards while pressing.

Place the Raspberry Pi HAT on the upper GPIO pins exactly as shown. Check the pin alignment before pressing it down so the HAT sits straight on the header.

Back to contents

Firmware flashing is not part of the standard first install path. When you buy a Display Streaming Kit, Decoder Kit, or decoder module, I usually flash the proper stock firmware for the ordered hardware and display configuration.

Use firmware flashing to update the decoder, change to another supported display, or install a different supported configuration. Use the official Raspberry Pi HAT compatible flashing hardware without extended wires or adapter chains.

Install OpenOCD

sudo apt update
sudo apt install -y openocd wget

Prepare files

Create a working directory and download the OpenOCD configuration for your Raspberry Pi. The configuration files are browsable at downloads.gitzian.com/d/firmware/openocd/. Raspberry Pi 1 / 2 / 3 / 4 use pi1234-jtag.cfg. Raspberry Pi 5 uses pi5-jtag.cfg.

mkdir -p ~/gitzian-firmware-flash
cd ~/gitzian-firmware-flash
OPENOCD_CFG=pi1234-jtag.cfg
wget "https://downloads.gitzian.com/d/firmware/openocd/$OPENOCD_CFG"

Open the Gitzian downloads page, go to the Firmware section, and choose the matching .svf firmware file for the decoder hardware and display configuration. Copy the file link from the downloads page and download it into the same directory as the OpenOCD .cfg file.

FIRMWARE_URL="paste-svf-download-link-from-downloads-page-here"
wget "$FIRMWARE_URL"
FIRMWARE="$(basename "$FIRMWARE_URL")"

Flash the decoder

Run OpenOCD with the selected configuration. A successful flash is when the command returns without errors.

openocd -f "$OPENOCD_CFG" -c "init; svf $FIRMWARE; exit"

For Raspberry Pi 5, set OPENOCD_CFG=pi5-jtag.cfg before downloading the config. If flashing does not complete, fully power cycle the hardware first, then run the command again.

Power cycle after flashing

A power cycle is required after a successful flash. sudo poweroff alone is not enough. After the Raspberry Pi has shut down, remove power from the hardware by pulling the plug, or carefully detach and re-attach the hardware.

Verify the flashed firmware

After the full power cycle, run the Pi client and check that the detected decoder firmware matches the version you flashed.

gitzian-pi

Back to contents

Local network use is the default setup. For secure use over the internet, use a private tunnel such as WireGuard.

Advanced: WireGuard

If your home network is behind NAT, rent a small vServer close to your location, usually in your home country or on the same continent, and use it as a WireGuard relay. Connect the server side and the remote device through the tunnel, then use the tunnel IP as the server IP in the Gitzian client config. This gives you your own small VPN setup for a few bucks a month.

Home server behind NAT
        ↓
WireGuard tunnel
        ↓
vServer relay
        ↓
Remote client

Super advanced: NAT punching

NAT punching may be possible for some setups, but this is a super advanced topic. WireGuard is the first term to get familiar with before going down that rabbit hole.

Back to contents

Very slow streaming on Windows

If streaming is very slow even under good network conditions, Microsoft Defender may be scanning or throttling the streaming application. Add the Gitzian installation folder to Microsoft Defender exclusions and test again.

UAC prompt, login screen, or lock screen is not visible

These screens are not captured by the current streamer. Use Remote Desktop or another fallback path to confirm UAC prompts or log in. If you are connected through OpenSSH and need to switch an RDP session back to the console, use tscon.

Client cannot connect

Check the server IP address in ~/.config/gitzian/client/default.ini, confirm that server_port matches the streamer configuration, and verify that both devices are on the same network or the same VPN. On Windows, also check the private-network firewall permission for the Gitzian GPU Streamer.

Linux plugin does not appear to run after install

The plugin is enabled for future starts. After the first install, load it once or reboot. Then check support information.

qdbus6 org.kde.KWin /Plugins org.kde.KWin.Plugins.LoadPlugin gitzian_kwin_plugin
qdbus6 org.kde.KWin /KWin supportInformation

Back to contents

Do I need the virtual display driver on Windows?

No. You can stream a selected area from an existing display. The virtual display driver is optional, but recommended for the best Windows experience.

Can Linux be the server?

Yes. The supported Linux path is currently KDE Plasma 6.3.6 on Wayland, using the Gitzian plugin and gitzian-gpu.

Can a Raspberry Pi be the server?

Yes. A Raspberry Pi can run the server with KDE Plasma. Raspberry Pi 5 is recommended; it currently reaches roughly up to 25 FPS at 720x720.

Which Raspberry Pi should I use as client?

Recommended models are Raspberry Pi Zero 2 W, Raspberry Pi 2, Raspberry Pi 3, Raspberry Pi 4, and Raspberry Pi 5. Raspberry Pi Zero v1.1 works, but its Wi-Fi is weaker.

Can I use custom hardware?

Yes. The standard Kit/reference setup uses the Gitzian decoder with the Raspberry Pi HAT, but the HAT PCB and Python client code are also meant as references for custom hardware. See the DIY page.

Why can I not see UAC prompts?

UAC prompts and other secure Windows screens are not captured yet. Use Remote Desktop as a fallback.

Can I use Gitzian over the internet?

Yes, but local network use is the default. For internet use there are many ways, but if you are new to this, start with WireGuard and a Linux or Windows vServer / cloud server. This is basically your own small VPN.

Do I need to flash firmware?

No, not for the standard first install path. When you buy a Display Streaming Kit, Decoder Kit, or decoder module, I usually flash the proper stock firmware for you. Firmware flashing gives you flexibility later: updating the decoder, changing to another supported display, using special configurations, improving FPS, or recovering the decoder.

Back to contents

These items are planned or possible future work, not current setup requirements.

• CPU streamer: software-rendered streaming for headless servers with strong CPUs. This already exists internally, but is not published yet.
• Audio streaming: planned.
• Scaling / downscaling: useful when a program does not support the target small-screen resolution directly.
• Dynamic viewport: a larger captured area can move dynamically, for example by following the cursor, reacting to touch input, or listening to a special key combination.
• More platforms: GNOME, X11, Windows 10, and Flatpak packaging are planned.
• Possible later targets: Windows 7, Windows 8, and other Linux setups if there is real demand.