koreader-picture-feed

A KOReader plugin that renders images fetched from a list of URLs at a set interval, in a corner of your e-reader's screen. Built for keeping an eye on security cameras while you read — works with Frigate, Blue Iris, UniFi, or any camera/NVR that exposes a plain JPEG snapshot URL.

Features

• Any number of image URLs ("feeds"). Tap the image once to rotate through your cameras; tap and hold to close the feed.
• Refresh interval in seconds (default 5; 2/3/5/10/30 available).
• Placement in any corner, size from 25–66 % of screen width.
• Partial e-ink refreshes scoped to just the image — your book page never repaints or flashes.
• The overlay never blocks input: page turns, menus and gestures all behave normally.
• Auto-off timer (default 15 min) so a forgotten feed doesn't drain the battery; pauses on suspend and resumes on wake.
• Toggle from the menu, a gesture, or a QuickMenu entry.

Install

The repo root is the plugin folder, so you can clone it straight into KOReader's plugin directory:

cd koreader/plugins
git clone https://github.com/zackify/picturefeed.koplugin.git

Or download a zip of the repo and unpack it into koreader/plugins/ — just make sure the folder name ends in .koplugin (e.g. picturefeed.koplugin/).

Then restart KOReader and find it under the tools menu (🔧) → Picture Feed.

Setup

The plugin needs at least one feed URL. Pick whichever is easier:

Option A — on device

🔧 → Picture Feed → Feeds → Add feed URL…, then enable Picture Feed → Enabled.

Option B — settings file

Create/edit koreader/settings/picture-feed.lua (with KOReader closed) and drop in your URLs:

return {
    ["interval"] = 5,        -- seconds between frames
    ["active"] = 1,          -- index of the feed shown first
    ["corner"] = "tl",       -- tl / tr / bl / br
    ["width_pct"] = 40,      -- % of screen width
    ["urls"] = {
        [1] = "http://192.168.1.100:5000/api/doorbell/latest.jpg",
        [2] = "http://192.168.1.100:5000/api/driveway/latest.jpg",
    },
}

Getting a snapshot URL

• Frigate: http://<frigate-host>:5000/api/<camera-name>/latest.jpg (camera names are in Frigate's web UI; port 5000 needs no auth on the LAN).
• Anything else: look for a "JPEG snapshot" / "still image" URL in your camera or NVR docs. If opening the URL in a browser shows a JPEG, it works.

Notes:

• Plain http:// only — the fetch path doesn't do TLS. Keep feeds on your LAN or tailnet (see below).
• Each fetch has a 5 s timeout; if a feed is unreachable the last good frame stays on screen and the error goes to the log.

Controls

Action	Result
Toggle on/off	🔧 → Picture Feed → Enabled, or bind the "Picture Feed: toggle" action (General category) to a gesture or QuickMenu entry
Tap the image	Rotate to the next feed
Hold the image	Hide the feed

Watching your cameras away from home

Your Kindle needs network access to the feed URLs, which are usually only on your LAN. To reach them from anywhere, run Tailscale on the Kindle and use your tailnet IPs in the feed URLs — see zackify/kindle-pw6-tailscale for a step-by-step setup (tested on the Paperwhite 6, adaptable to other jailbroken Kindles).

Settings reference

Stored in koreader/settings/picture-feed.lua:

key	default	meaning
urls	two example URLs	array of JPEG snapshot URLs
active	1	index of the current feed
interval	5	seconds between frames
corner	tl	tl / tr / bl / br
width_pct	40	% of screen width (menu: 25–66)
auto_off_min	15	minutes until auto-off, 0 = never

Troubleshooting

• Log file: koreader/picture-feed.log (also mirrored into crash.log). Every fetch, rotation and error is timestamped there.
• host or service not provided, or not known → DNS/hostname isn't resolving on the Kindle; use IP addresses in the URLs.
• HTTP 401/403 → the snapshot URL needs credentials; embed them (http://user:pass@host/...) if your camera supports it.
• Some graininess in the image is normal — it's a photo dithered to e-ink grays with a partial refresh. Slower intervals (5–10 s) look and feel best.