Plugin API v1.0.0
Wallpaper Plugin Contract Specification
Hearth supports dynamic third-party wallpaper engines via standard Android ContentProvider and BroadcastReceiver primitives.
1. ContentProvider Endpoint
Providers publish wallpapers by registering an exported ContentProvider in their AndroidManifest.xml matching the Hearth authority convention:
<!-- Provider AndroidManifest.xml --><provider android:name=".WallpaperProvider" android:authorities="com.example.wallpapers.hearth.wallpaper" android:exported="true" />Hearth resolves and queries the standard URI:content://<provider_authority>/wallpapers
2. Cursor Database Schema
The ContentProvider's query() method must return an Android Cursor containing the following columns:
| Column Name | Type | Required | Description |
|---|---|---|---|
_id | INTEGER | Yes | Unique positive integer item identifier. |
media_uri | TEXT | Yes | Content URI pointing to the image (content://... or android.resource://...). |
media_type | TEXT | Yes | "IMAGE", "SOLID_COLOR", or "VIDEO". |
scale_mode | TEXT | No | "FILL" (default), "FIT", or "CENTER". |
title | TEXT | No | Title of the wallpaper artwork (max 100 characters). |
author | TEXT | No | Artist credit (max 100 characters). |
3. Broadcast Signals & Dynamic Context
Hearth provides two-way broadcast signals so wallpapers can adapt based on user focus or ambient states:
// Action broadcast by Hearth when user focuses an appAction: "in.neetinsolanki.hearth.plugin.action.EVENT_ITEM_SELECTED" Extras: - "in.neetinsolanki.hearth.plugin.extra.PACKAGE_NAME": "com.netflix.ninja" - "in.neetinsolanki.hearth.plugin.extra.APP_LABEL": "Netflix"// Action broadcast by Hearth when entering screensaver / ambient modeAction: "in.neetinsolanki.hearth.plugin.action.EVENT_AMBIENT_MODE" Extras: - "in.neetinsolanki.hearth.plugin.extra.IS_IDLE": true4. Reference Implementation
A complete, buildable reference wallpaper provider is included directly in the Hearth monorepo under the :sample-wallpaper-provider Gradle module.