Belseck · Nov 4, 2026 · Nov 5, 2026 · Nov 5, 2026 · Nov 5, 2026
diff --git a/addons/README.md b/addons/README.md
@@ -17,6 +17,7 @@ the core bigger or change how it behaves. You install an add-on only if you want
 | [Weather](weather/) | The weather for one city: now, US air quality and the next three days, from Open-Meteo (no key) | [@Sumyabazar1](https://github.com/Sumyabazar1) | Hisense SmartTV 4K FFM (lushan), Google TV 12 | `INTERNET` | <img src="weather/screenshot.jpg" width="240" alt="Weather on a TV"> |
 | [Photo Prints](photo-prints/) | Your own photos as a screensaver: dated prints dealt in on a time-of-day sky, and a card that starts the slideshow | [@shivamsingh262](https://github.com/shivamsingh262) | Sony BRAVIA KD-65X82L (Google TV 12) | None | <img src="photo-prints/screenshot.jpg" width="240" alt="Photo Prints on a TV"> |
 | [Photo screensaver](photo-screensaver/) | Your own pictures and MP4 clips as the TV's screensaver and as a card, slowly zooming and crossfading (20 s each by default); optional time, photo dates, prints on a sky and weather | [JorickGU](https://github.com/JorickGU) | TCL 43P69K (Google TV 12) | `INTERNET` and coarse location, only with the weather option on | <img src="photo-screensaver/screenshot.jpg" width="240" alt="Photo screensaver on a TV"> |
+| [Topic Photos](topic-photos/) | Freely licensed photos of the topics you choose, from Wikimedia Commons (no key), at the screen's own resolution: full screen with their credit and details, and as a screensaver | CleanYourTV contributors | Chromecast with Google TV 4K (Google TV 14) | `INTERNET` | <img src="topic-photos/screenshot.jpg" width="240" alt="Topic Photos on a TV"> |
 | [Prayer Times](prayer-times/) | Today's prayer times for one city from Aladhan (no key), the next prayer with a countdown, Gregorian and Hijri dates | [@majnioui](https://github.com/majnioui) | Xiaomi TV (MiTV-MOOR2), Google TV 11 | `INTERNET`, start at boot, exact alarm, overlay (only with reminders on) | <img src="prayer-times/screenshot.jpg" width="240" alt="Prayer Times on a TV"> |
 | [TV Hub](tv-hub/) | One live-TV guide for M3U/XMLTV playlists, Dispatcharr and HDHomeRun tuners, with a Media3 player and shortcuts to installed live-TV apps | [@maxhayim](https://github.com/maxhayim) | MOKA R8G (Android TV 14) | `INTERNET` | <img src="tv-hub/screenshot.jpg" width="240" alt="TV Hub on a TV"> |
 | [Headphones](headphones/) | Bluetooth headphones made easy: where the sound goes, paired pairs with battery, a pairing shortcut, and a quiet guard that pauses and mutes the speakers when headphones drop | [@maxhayim](https://github.com/maxhayim) | MOKA R8G (Android 14) | Bluetooth (paired devices only) | <img src="headphones/screenshot.jpg" width="240" alt="Headphones on a TV"> |

diff --git a/addons/topic-photos/.gitignore b/addons/topic-photos/.gitignore
@@ -0,0 +1,4 @@
+.gradle/
+build/
+app/build/
+local.properties
diff --git a/addons/topic-photos/README.md b/addons/topic-photos/README.md
@@ -0,0 +1,74 @@
+# Topic Photos
+
+Freely licensed photos of the topics you choose, full screen on the TV and as its screensaver. Pick or type a few topics
+("mountains, ocean, city at night"), and the app finds matching photos on [Wikimedia Commons](https://commons.wikimedia.org),
+keeps them on the TV and changes them on their own. For the [Clean Your TV](../../README.md) launcher it declares a
+[module card](../../docs/modules.md), so once you answer **Show card** its tile reads "Topic Photos"; on any other
+Android TV home it is an ordinary app.
+
+![Topic Photos on a TV](screenshot.jpg)
+
+- **The photos** come from Wikimedia Commons, which needs no account or key. Each topic is one search, with the
+  screen's resolution in it: Commons returns only files at least the size of the screen, and scales each one to the
+  screen's width before it is downloaded, so a photo is never stretched and never larger than it needs to be. Only
+  landscape JPEGs are kept, at most three by one author for each topic, about 30 in all.
+- **They stay on the TV.** The set is fetched again when the topics change, when day-and-night photos switch, or
+  after three days. In between, and while the TV is offline, the saved photos are shown.
+- **The credit** stays in a corner on every photo: the author, Wikimedia Commons, the licence, and the place it was
+  taken when the photo has coordinates (the licences most of these photos carry, CC BY and CC BY-SA, ask for it).
+
+## The remote
+
+| Key | In the app | In the screensaver |
+|---|---|---|
+| Left / Right | Back through the photos already shown, in order; forward again, then a new photo at random | The same |
+| Up | The photo's details: its description, place, author and licence, the date it was taken, and its size on the TV beside the original's | The same |
+| Down | Hides the details | The same |
+| OK | Settings | Wakes the TV |
+| Back | Hides the details, then closes the app | Hides the details, then wakes the TV |
+
+What a photo's uploader left out reads **Not given**.
+
+## Settings
+
+Press OK in the app (or the settings button of the screensaver in the TV's settings). Choices are kept on this TV.
+
+| Setting | Default | What it does |
+|---|---|---|
+| Topics | A varied mix: mountain landscape, ocean waves, misty forest, city skyline at night, starry night sky, waterfall, desert dunes, northern lights | Up to eight, on a screen of their own: tick them from suggestions grouped as holidays, seasons, and nature and more, or type your own, which the suggestions complete. English topics find the most photos. |
+| Change photo every | 30 s | 10 s to 30 min. |
+| Day and night photos | Off | From 7:00 to 19:00 by the TV's clock, daylight photos of your topics; the rest of the day, night photos. No location is asked for. |
+| Use as the screensaver | | Opens the TV's screensaver settings, where you pick Topic Photos. |
+
+## Permissions
+
+| Permission | Why |
+|---|---|
+| `INTERNET` | Wikimedia Commons for the search and the photos; OpenStreetMap's reverse lookup for the place names. |
+
+That is all. What is sent: your topics, as search terms, to Wikimedia Commons; a photo's own coordinates, once per
+photo, to OpenStreetMap. Both requests name the app in their User-Agent, as those services ask. No account, no
+telemetry, no ads, no background service: photos are fetched only while the app or the screensaver is on screen.
+The photos and your choices stay in the app's own storage (backups are off).
+
+## Build and install
+
+JDK 17 and Android SDK platform 34 with build-tools 34.0.0, as for the launcher:
+
+```bash
+cd addons/topic-photos && ./gradlew assembleRelease
+TV_HOST=<tv ip> ../../tools/venv/bin/python -I ../../tools/tv.py --push app/build/outputs/apk/release/app-release.apk /data/local/tmp/addon.apk
+TV_HOST=<tv ip> ../../tools/venv/bin/python -I ../../tools/tv.py 'pm install -r /data/local/tmp/addon.apk; rm -f /data/local/tmp/addon.apk'
+```
+
+Press Home: the launcher asks once whether to show the card. Change the answer later by holding OK on
+Settings, then Module cards.
+
+The release build is signed with the debug key so it installs over ADB like the launcher. Sign your own builds
+with your own key if you hand them out; the launcher pins its Show answer to the signing key.
+
+## Tested on
+
+Chromecast with Google TV 4K (`sabrina`), Google TV 14: the photos fetched for the default topics at the screen's
+1920 x 1080, Left/Right, the details on Up and the settings on OK, the place names from OpenStreetMap, the launcher's
+prompt to show the card, and Topic Photos in the TV's list of screensavers.
diff --git a/addons/topic-photos/app/build.gradle b/addons/topic-photos/app/build.gradle
@@ -0,0 +1,36 @@
+plugins {
+    id 'com.android.application'
+}
+
+android {
+    namespace 'io.github.cleanyourtv.topicphotos'
+    compileSdk 34
+
+    defaultConfig {
+        applicationId 'io.github.cleanyourtv.topicphotos'
+        minSdk 26
+        targetSdk 34
+        versionCode 1
+        versionName '1.0'
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled true
+            shrinkResources true
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
+            // Sideloaded over ADB like the launcher: signed with the debug key. Sign your own releases with your key.
+            signingConfig signingConfigs.debug
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+}
+
+dependencies {
+    // Test only (never in the APK): plain JVM tests for the photo choice and the search, src/test.
+    testImplementation 'junit:junit:4.13.2'
+}
diff --git a/addons/topic-photos/app/src/main/AndroidManifest.xml b/addons/topic-photos/app/src/main/AndroidManifest.xml
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-feature android:name="android.software.leanback" android:required="false" />
+    <uses-feature android:name="android.hardware.touchscreen" android:required="false" />
+
+    <!-- The only permission: Wikimedia Commons for the photos, OpenStreetMap for their place names. -->
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application
+        android:allowBackup="false"
+        android:banner="@drawable/banner"
+        android:icon="@drawable/icon"
+        android:label="@string/app_name"
+        android:supportsRtl="false"
+        android:theme="@android:style/Theme.Material.NoActionBar.Fullscreen">
+
+        <activity
+            android:name=".ViewerActivity"
+            android:exported="true"
+            android:screenOrientation="landscape">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
+            </intent-filter>
+            <!-- Clean Your TV module card (docs/specs/card.md): the tile shows as "Topic Photos" once the owner says Show. -->
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="com.gathin.tvhome.category.DOCK_CARD" />
+            </intent-filter>
+            <meta-data android:name="com.gathin.tvhome.card" android:resource="@xml/module_card" />
+        </activity>
+
+        <activity
+            android:name=".TopicsActivity"
+            android:exported="false" />
+        <activity
+            android:name=".SettingsActivity"
+            android:exported="true"
+            android:label="@string/settings_title" />
+
+        <!-- The screensaver: pick "Topic Photos" in the TV's screensaver settings. -->
+        <service
+            android:name=".PhotoDream"
+            android:exported="true"
+            android:label="@string/app_name"
+            android:permission="android.permission.BIND_DREAM_SERVICE">
+            <intent-filter>
+                <action android:name="android.service.dreams.DreamService" />
+                <category android:name="android.intent.category.DEFAULT" />
+            </intent-filter>
+            <meta-data android:name="android.service.dream" android:resource="@xml/dream" />
+        </service>
+    </application>
+</manifest>