Warning
Viewwall is deprecated in favor of viewpie, which supersedes it and is where development continues. Please use Viewpie for new installations.
Viewwall hit two limits of its Python and GStreamer foundation:
- No atomic presenter. Viewwall has two output backends, and each gives
up something.
kms-planesscans every viewport out on its own plane through its ownkmssink, but the independent page flips share one refresh, capping each viewport at roughly the refresh rate divided by the number of viewports.compositorrenders the wall in software, which gives up most of the benefit of hardware acceleration and costs a lot of CPU. The right design lies between the two: an atomic presenter that still scans each feed out on its own KMS plane, but commits all of them together once per refresh. That cannot be built in Python on top of GStreamer. - No hardware H.265 decoding on the Raspberry Pi. Current GStreamer does not support the Pi's HEVC decoder, so H.265 cameras fall back to software decoding.
Viewpie is written in Rust around one atomic commit for the whole wall, and decodes with FFmpeg's libav* libraries.
Show all your security cameras on one screen, on a Raspberry Pi.
Viewwall turns a Pi and a TV into a camera wall: a grid of live RTSP feeds, started at boot, that recovers on its own when a camera or the network drops out. It draws straight to the screen through DRM/KMS, so there is no desktop, no browser and no window manager.
Built and tested against UniFi Protect, and works with any camera or NVR that publishes RTSP.
+-------------+-------------+-------------+
| driveway | porch | street |
+-------------+-------------+-------------+
| yard | doorbell | garage |
+-------------+-------------+-------------+
| shed | patio | side gate |
+-------------+-------------+-------------+
- Any layout. Viewports are rectangles in fractions of the screen, so one configuration follows a change of resolution.
- Hardware decoding, no copying. Each feed is decoded once by the Pi's video hardware and scanned out on its own display plane. A Pi 3 sustains nine feeds at full camera framerate.
- Rotation. A viewport can cycle through several cameras, keeping them all connected so switching is instant.
- Unattended. Feeds reconnect on their own; systemd restarts the wall if it ever dies. It is meant to run for months on a shelf.
You need a Raspberry Pi 3 or newer running Raspberry Pi OS Lite, a screen, and cameras that publish RTSP.
Nothing needs configuring first: a current Raspberry Pi OS image works as it comes.
Download the .deb from releases:
sudo apt install ./viewwall_0.1.0-1_all.debsudoedit /etc/viewwall/viewwall.toml[feeds.driveway]
uri = "rtsp://192.168.1.1:7447/aBcDeFgHiJkLmNoP"
[feeds.porch]
uri = "rtsp://192.168.1.1:7447/QrStUvWxYzAbCdEf"
# Each viewport shows a camera, placed as fractions of the screen.
[[viewports]]
x = 0
y = 0
width = "1/2"
height = 1
feeds = ["driveway"]
[[viewports]]
x = "1/2"
y = 0
width = "1/2"
height = 1
feeds = ["porch"]On UniFi Protect, enable RTSP per camera in the Protect app. The URL it shows needs two edits before it will play here:
rtsps://192.168.1.1:7441/aBcDeFgHiJkLmNoP?enableSrtp <- what Protect shows
rtsp://192.168.1.1:7447/aBcDeFgHiJkLmNoP <- what to configure
Drop ?enableSrtp, which asks for encrypted media Viewwall cannot decrypt, and
switch rtsps:// on 7441 to rtsp:// on 7447. The stream id stays as it is,
and there are no credentials. To keep TLS instead, leave the rtsps:// URL on
7441 and see RTSP and RTSPS -- but still drop ?enableSrtp.
Other cameras that want a login take it inline as rtsp://user:password@host/path.
sudo -u viewwall viewwall -c /etc/viewwall/viewwall.toml validatesudo systemctl enable --now viewwallThe wall appears within a few seconds. To watch what it is doing:
journalctl -u viewwall -fAnything omitted uses its default, so a working configuration is mostly feeds and viewports. A fuller example is in examples/viewwall.toml. An option Viewwall does not recognise is an error rather than a silent no-op, so a typo says so instead of leaving a setting at its default.
[[viewports]] — one table per viewport: a region of the screen showing
one camera. Viewports have no names; logs and metrics identify one by its
position in the file, counting from 1, and name the feed it is showing
alongside.
| Option | Default | Meaning |
|---|---|---|
x, y |
required | Where the viewport's top-left corner sits, as a fraction of the screen: "1/3", or a whole 0 or 1. |
width, height |
required | How much of the screen it covers, in the same units. A 3x3 wall is nine viewports of 1/3. The camera is stretched to fill it, deliberately: it avoids black bars around a doorbell camera that is not 16:9. |
feeds |
required | Feed names. Listing more than one rotates the viewport through them; every one stays connected and decoding, so a switch is instant rather than waiting for the stream to start, and unhealthy cameras are skipped. |
rotate_seconds |
8 |
Seconds between switches; must be positive. Ignored on a single-feed viewport. |
display |
the only display | Which display the viewport is on, by name. Only needed with more than one [displays.<name>] table, since otherwise there is a single display to be on: the one configured, or the first one connected when none is. |
[feeds.<name>] — one table per camera.
| Option | Default | Meaning |
|---|---|---|
uri |
required | rtsp:// or rtsps://. A ${VAR} placeholder is expanded from the environment. H.264 or H.265 is detected from the RTSP announcement. |
latency_ms |
150 |
Jitterbuffer depth. Raise it on a lossy network, at the cost of latency. |
transport |
"tcp" |
The RTP transport: "tcp", "udp", "udp-mcast", or "auto" to negotiate one of the three with the server. TCP (default) was the only one to work reliably during testing using a Raspberry Pi 3 and UniFi NVR; udp and auto crashed within seconds and udp-mcast connected to nothing. |
verify_tls |
true |
rtsps:// only. false accepts a self-signed certificate; the transport stays encrypted, the server is simply not verified. |
[feed_defaults] — latency_ms, transport and verify_tls for any feed
that does not set its own.
[displays.<name>] — one table per output, needed only to drive more than
one screen. With none of these, the first connected output is used and the
rest are left alone; [display_defaults] still applies to it, so setting a
seam does not mean naming a screen.
| Option | Default | Meaning |
|---|---|---|
connector_id |
the first connected output | Which output this is. Required only when more than one display is configured. With a single one the first connected output is driven and any others are left alone, which is the same choice made when there is no [displays] table at all. kmsprint -l lists them as Connector 0 (35) HDMI-A-1 (connected), where 35 is the id, and the startup log line names the ones in use. With several displays, which screen showed what would otherwise depend on probe order. |
gap_px |
0 |
Seam between viewports, in pixels. Made by trimming that pixel off the edge of the video rather than drawing over it, so the picture is never scaled and every plane stays on the cheap 1:1 path. |
outer_margin_px |
0 |
Inset from this screen's edges. |
width, height |
active mode | Overrides the detected resolution. Both or neither. |
mode |
connector default | Mode to drive the connector at, as "1280x720" or "1280x720@60". Without a refresh rate the driver picks one, which on a panel offering 1920x1080 at 120, 60, 50, 30 and 24 is whichever it resolves first -- 120 on the measured panel. Naming the rate is the only way to choose, and the compositor backend wants 60 rather than 120: it blends every output frame on the CPU, so twice the refresh is twice the work for no visible gain once every camera is already showing every frame it sends. |
[display_defaults] — gap_px and outer_margin_px for any display that
does not set its own, including the discovered one.
Each display is its own canvas: a viewport's position is a fraction of the screen it is on, not of some union of screens. A viewport cannot span two displays, because a KMS plane belongs to exactly one output.
[displays.hall]
connector_id = 35
[displays.office]
connector_id = 36
gap_px = 1
[[viewports]]
x = 0
y = 0
width = 1
height = 1
feeds = ["driveway"]
display = "hall"
[[viewports]]
x = 0
y = 0
width = "1/2"
height = "1/2"
feeds = ["porch"]
display = "office"A feed may appear on both, and is still decoded once. The planes each display needs are worked out together, since on a Pi many planes can drive more than one output and a plane handed to one display is not available to the other.
[metrics]
| Option | Default | Meaning |
|---|---|---|
interval_seconds |
60 |
How often to log per-viewport framerate and queue depth. 0 disables. |
[drm] — the graphics card, which is one card however many displays.
| Option | Default | Meaning |
|---|---|---|
device |
detected | DRM card to open. Displays are connectors within one card, not separate devices. Detected from the card that owns the connectors, which is card0 on a Pi 3 but card1 on a Pi 5; set it to pin one. |
poll_interval_seconds |
2 |
How often to re-probe the card for a resolution change. One probe reports every connector. |
background |
"#000000" |
Color painted under the viewports as #RRGGBB, or "none" to leave the framebuffer console showing. "none" needs output_backend = "kms-planes": the compositor draws the whole screen, so no console is left behind it. |
output_backend |
"kms-planes" |
How viewports reach the screen. See below. |
kms-planes gives every viewport its own KMS overlay plane and its own
kmssink. The video path is zero-copy, but each sink issues a separate legacy
drmModeSetPlane, and those serialise into one commit per vblank per CRTC: on
a 60Hz output nine viewports share 60 commits a second and get about 6.7 each,
whatever their cameras send. Raising the output to 120Hz doubles the budget at
no CPU cost, which is why a high-refresh mode is worth choosing here.
compositor blends the whole wall into one frame and scans it out through a
single kmssink on a single plane, so one commit carries every viewport and
each tile is limited by its own feed rather than by its share of the commit
budget. It costs a CPU blend of the full output frame.
Measured on a Pi 5 at 1920x1080, nine feeds of 640x360 (15-30 fps sources):
kms-planes @120Hz |
compositor @60Hz |
|
|---|---|---|
| per viewport | 13.4 fps, uniform | 13.7-29.9 fps, each at its camera's rate |
| CPU | ~55% of one core | ~70-80% of one core |
| planes used | one per viewport | one per display |
The compositor figure is a range because run-to-run spread on a shared Pi is
several points; treat it as "most of a core", not a precise number. A
layout.gap_px above zero adds roughly fifteen points on top of it: the seam
is cut from each source by a videocrop, and compositor never offers a crop
meta, so that element copies every frame of every tile instead of passing it
through. gap_px = 0 leaves the tiles abutting and costs nothing.
That same missing crop meta is fatal rather than merely expensive on a Pi 3,
where the hardware decoder hands videocrop DMA_DRM caps: with nothing to fall
back on it refuses the crop outright and every seamed viewport dies at startup
with "Dowstream doesn't support crop for non-raw caps". The compositor backend
there needs gap_px = 0, and is otherwise unmeasured on that board.
The compositor's cost scales with output resolution and refresh, not with the number of viewports: at 120Hz it blends twice as many frames for no visible gain once every camera is already showing every frame it sends. Pair it with a 60Hz mode. Capping the blend rate below the refresh was measured and changes nothing at 60Hz, so there is no setting for it.
kms-planes remains the default: it is the zero-copy path, it needs less CPU,
and it is what the Pi 3 wall has run on. The compositor has not been measured
on a Pi 3.
Two settings behave differently under the two backends. drm.background = "none" is refused with compositor, because a full-screen composited frame
leaves no console to show through. And the compositor wants a lower refresh
rate than kms-planes: see mode below.
Every 60 seconds viewwall logs what each viewport is doing:
metrics viewport=2 feed=porch state=healthy queued_fps=29.6 decoded_fps=29.8 \
window_s=60.0 presented_fps=7.4 sink_dropped=1327 queue_ms=45
The three rates follow one frame along the path, and a drop between any two names where it is being lost:
| Field | Where it is counted |
|---|---|
decoded_fps |
Frames leaving the decoder. |
queued_fps |
Buffers leaving the viewport's output queue toward its plane. A gap below decoded_fps is the leaky queue shedding frames the wall could not keep up with. |
presented_fps |
Buffers the sink actually put on the KMS plane. This is what reaches the screen. |
sink_dropped |
Buffers the sink discarded for arriving late against the clock, which is the difference between the two rates above. |
Expect presented_fps to sit well below queued_fps on a full wall. Each
plane is updated by its own drmModeSetPlane and the VC4 retires one per
vblank, so the viewports share 60 updates a second between them: a nine-viewport
wall measures about 7.4fps each, summing to 60. See the plane budget section of
DESIGN.md.
queue_ms is how much video is waiting — a viewport sitting at 250ms is a
quarter of a second behind live.
A rotating viewport that switched feeds during the interval is marked rotated=1,
with window_s giving the shorter span the rates cover. Its rates and
decoded_fps are measured over different spans and should not be compared.
Under systemd these are attached as structured journal fields, so they can be summarized without parsing the text:
journalctl -u viewwall -o json --output-fields=VW_VIEWPORT,VW_QUEUED_FPS,VW_PRESENTED_FPS \
| jq -r 'select(.VW_VIEWPORT) | [.VW_VIEWPORT, .VW_QUEUED_FPS, .VW_PRESENTED_FPS] | @tsv'To change the interval, or turn it off:
[metrics]
interval_seconds = 60 # 0 disableslog_level sets how much the wall says, as a top-level key:
log_level = "DEBUG" # DEBUG, INFO, WARNING or ERROR; default INFO--log-level overrides it, so a level can be forced without editing the file.
DEBUG adds per-event detail -- crop and aspect decisions, GStreamer error
detail, and the numbers behind each feed-recovery verdict. Nothing at that
level runs per frame, so it costs little beyond journal volume.
Feeds use rtsp:// over TCP by default (feed_defaults.transport = "tcp").
rtsps:// works. A UniFi Protect NVR presents a self-signed certificate, so
certificate validation has to be relaxed:
[feeds.backyard]
uri = "rtsps://192.168.1.1:7441/aBcDeFgHiJkLmNoP"
verify_tls = falseverify_tls may be set per feed or in [feed_defaults], and applies only to
rtsps:// URIs. It is a boolean rather than a set of modes: a partial
validation mask looks like the right way to accept just a self-signed
certificate, but
GLib deprecated per-condition flags and this GStreamer treats any non-zero value
as full validation. Measured against a Protect NVR, flags 122/126/127 all fail
with "Could not open resource for reading and writing" and only 0 connects, so
a partial mode would silently do nothing. With verify_tls = false the
transport is still encrypted; the server is simply not verified. Viewwall logs
a warning whenever a feed runs this way.
Protect offers both per camera: 7447 for plain RTSP and 7441 for RTSPS. The
samples here use 7447, because on a LAN it is the better trade. RTSPS does not
improve image quality or framerate, costs a little extra CPU for TLS on a Pi
that has none to spare, and against a self-signed certificate it buys less than
it appears to: verify_tls = false stops passive sniffing but not an active
attacker, who can present their own certificate and be believed. That is close
to the plain-RTSP threat model with extra steps.
RTSPS earns its keep when the feeds cross a network you do not control, or when
the server has a certificate you can actually verify -- with verify_tls left
at true, the guarantee is real.
SRTP is not supported: drop ?enableSrtp from the URL Protect shows. It is
opt-in on both ports, so nothing else has to change -- SRTP encrypts the media
payload, which is separate from whether the control channel uses TLS, and
rtsps:// on 7441 works without it. Left on, the stream connects and then
fails because the payload cannot be decrypted; Viewwall detects this from the
negotiated SDP and stops that feed with a clear message rather than retrying
forever. See DESIGN.md for what supporting it would involve.
The wall writes directly to KMS overlay planes, so the container needs the
host's DRM and V4L2 devices. It cannot render anything in an ordinary sandboxed
container, and nothing else may hold DRM master — stop a native viewwall
service before starting the container.
# compose.yaml
services:
viewwall:
image: ghcr.io/<owner>/viewwall:0.1.0
restart: unless-stopped
devices:
# card0 on a Pi 3, card1 on a Pi 5, where card0 is the render-only v3d
# node with no connectors. Check with: ls /sys/class/drm
- /dev/dri/card0:/dev/dri/card0 # KMS output planes
# A Pi 5 has no H.264 decoder and needs no video device for one; it
# software-decodes with avdec_h264. /dev/video19 is its HEVC decoder.
- /dev/video10:/dev/video10 # hardware H.264 decoder (Pi 3/4)
# H.265 needs these too. v4l2slh265dec is a stateless decoder, and
# GStreamer only registers one when it can reach the media controller
# node that drives it: without them the element does not exist and an
# H.265 feed fails to start, while the same feed works outside Docker.
- /dev/media0:/dev/media0 # media controller (stateless codecs)
- /dev/media1:/dev/media1
- /dev/media2:/dev/media2
group_add:
# Numeric GIDs, not names: group names are resolved inside the container,
# whose /etc/group has no video or render entry. Check yours with
# getent group video render
- "44" # video
- "992" # render
volumes:
- /etc/viewwall:/etc/viewwall:ro
environment:
# A "${PORCH_RTSP}" placeholder in viewwall.toml is expanded from the
# environment, which keeps the credentials out of the config file and
# lets Compose supply them.
PORCH_RTSP: ${PORCH_RTSP}Stop any native service first, or the container cannot take DRM master:
sudo systemctl stop viewwall
docker compose up -dVerified on a Raspberry Pi 3 running Raspberry Pi OS Trixie: the container renders all nine planes from live cameras with the device nodes and two groups above.
Pass every /dev/videoN decoder node your Pi exposes if you are unsure which
one GStreamer will pick; on a Pi 3 the H.264 decoder is /dev/video10, and on
a Pi 5 the HEVC decoder is /dev/video19. Pass /dev/media* as well. A
stateless decoder -- v4l2slh265dec, which is the only way viewwall decodes
H.265 -- is registered by GStreamer only when it can reach the media
controller node behind it, so without those an H.265 feed fails to start with
"no supported decoder is available for H265" while the same feed plays on a
native install.
A native systemd install is lighter than Docker on a Pi 3, and is the recommended deployment.
Raspberry Pi 3, running Raspberry Pi OS. Developed and verified on a Pi 3
Model B+ with Raspberry Pi OS Trixie, which is what the kms-planes backend
and its measurements describe.
A Pi 5 also works and is where the compositor backend was measured, but it
is a different trade rather than a faster Pi: BCM2712 dropped the H.264
decoder block, so every feed is software-decoded with avdec_h264, and the
DRM card that owns the connectors is card1. Nine feeds leave a Pi 3 around
76% idle on kms-planes; the same wall on a Pi 5 under compositor costs
most of a core. A Pi 4 should work and is untested.
Older Pi models are not supported: they lack the KMS overlay planes the design depends on.
Other hardware, including x86, is out of scope for now. The design itself is not Pi-specific: the layout model, recovery logic, GStreamer graph and KMS output path would all port. Three things currently tie it to a Pi:
kms++-utils, used for KMS discovery, is packaged by Raspberry Pi OS rather than Debian, so the.debcannot satisfy its dependencies on plain x86 Debian. The published image is built forlinux/arm/v7andlinux/arm64.- Decoder selection prefers the Pi's V4L2 M2M decoders. H.264 falls back to
software
avdec_h264, so it would run on x86 but on the CPU; there is no VAAPI or NVDEC path. - A wall on the default
kms-planesbackend needs one overlay plane per viewport (compositorneeds one per display instead). Intel and AMD display engines typically expose far fewer than the nine a 3x3 wall wants.
Supporting x86 properly would mean replacing the kmsprint shell-out with
direct DRM queries and adding VAAPI to the decoder policy.
Nothing appears on screen. Check journalctl -u viewwall -n 50. "No
unused YUV-capable KMS overlay planes found" means the display driver is not
full KMS. Raspberry Pi OS enables it by default, so this points at a
dtoverlay line in /boot/firmware/config.txt selecting the legacy or
vc4-fkms-v3d driver; neither is supported.
One viewport is black. That camera is unreachable or still starting. Viewwall retries on its own, backing off up to 30 seconds; the log names the feed.
Every viewport is black. Viewwall logs no viewport is showing video at error
level and reports it to systemd, so systemctl status viewwall shows it too.
That is the NVR being unreachable, credentials having changed, or a
transport the streams cannot use.
"A lot of buffers are being dropped" at --log-level DEBUG. GStreamer
emits this from a late-buffer count alone, and a camera whose decoder holds
and then releases frames in bursts trips it continuously without losing any.
Check that viewport's fps in the metrics rather than trusting the warning; it is
logged at debug level for this reason.
A viewport is behind the others. Check queue_ms in the metrics lines.
Some cameras declare frame reordering in
their H.264 stream, which makes the decoder hold frames and puts that viewport a
quarter-second behind the rest. It is a camera-side setting; see
DESIGN.md.
Feeds fail to start. The log names the feed and the reason. A camera that is unreachable is retried; one that keeps failing usually points at the URL, credentials, or a codec viewwall cannot decode on that model.
It worked, then stopped after adding cameras. A wall needs one display plane per viewport, and hardware runs out of them. The log reports a resource error naming the viewport that failed.
The wall restarted itself after a camera came back. A feed that connects, reports healthy, and dies within seconds -- three times in a row, and again after viewwall rebuilds that feed's branch -- is wedged on state a retry cannot reach. The log says so and names the feed, and the wall exits so the service manager gives it a clean process. A camera that is simply off or unreachable never triggers this; it retries indefinitely instead. If it keeps happening, the restarts spread out from five seconds to a minute apart rather than stopping, so the wall keeps showing whichever cameras are healthy.
DESIGN.md covers the media path, the recovery model, how viewports are resolved to pixels, the measurements behind the current settings, and the approaches that were tried and rejected.
Unit tests cover configuration validation, fractional layout resolution, source-crop calculation, and KMS discovery parsing:
pytest -qLive RTSP, V4L2 decoder, DMA-BUF, and KMS behavior must be tested on the Pi.
./scripts/build-deb.sh # -> dist/viewwall_<version>-<rev>_all.deb
docker build -t viewwall:dev . # needs an armhf/arm64 builder for a PiTo cut a release, set the version in pyproject.toml, commit, then tag:
git tag v0.1.0 && git push origin v0.1.0That runs the release workflow, which tests, builds the package, pushes a
multi-arch image to GHCR ({{version}}, {{major}}.{{minor}} and latest),
and creates a GitHub release with the .deb attached. The version comes from
pyproject.toml rather than from the tag; the workflow compares the two and
fails if they disagree.
The .deb is Architecture: all — it is pure Python, a unit file and a
wrapper script, so one package serves every supported Pi. The Pi-specific part
is its dependencies, not its contents.
After the first release only, make the GHCR package public, or pulls fail
with a 403: a package pushed by GITHUB_TOKEN is private by default, and its
visibility can only be set once the package exists. Find it under the
repository's Packages, then Package settings → Change visibility. This is a
one-time step and is independent of whether the repository itself is public.
GPL-3.0-or-later. Copyright Sebastian Noack.