<init>

Base class for a Muzei Live Wallpaper artwork provider. Art providers are a way for other apps to feed wallpapers (called artworks) to Muzei Live Wallpaper.

Subclassing MuzeiArtProvider

Subclasses must implement at least the onLoadRequested callback method, which is called whenever Muzei has displayed all available artwork from your provider. It is strongly recommended to load new artwork at this point and add it via addArtwork so that users can continue to move to the next artwork.

All artwork added via addArtwork is available to Muzei. Muzei controls how often the artwork changes and the order that it proceeds through the artwork. As a convenience, you can use setArtwork to remove all artwork and set just a single new Artwork. You can use ContentResolver.delete with contentUri to delete specific artwork based on criteria of your choosing.

Many operations are also available in ProviderContract.Artwork, allowing you to add, update, delete, and query for artwork from anywhere in your app.

Registering your provider

Each provider must be added to your application's AndroidManifest.xml file via a <provider> element.

The Muzei app discover available providers using Android's Intent mechanism. Ensure that your provider definition includes an <intent-filter> with an action of ACTION_MUZEI_ART_PROVIDER. It is strongly recommended to protect access to your provider's data by adding the ACCESS_PERMISSION, which will ensure that only your app and Muzei can access your data.

Lastly, there are a few <meta-data> elements that you should add to your provider definition:

• settingsActivity (optional): if present, should be the qualified component name for a configuration activity in the provider's package that Muzei can offer to the user for customizing the extension. This activity must be exported.
• setupActivity (optional): if present, should be the qualified component name for an initial setup activity that must be ran before the provider can be activated. It will be started with android.app.Activity.startActivityForResult and must return android.app.Activity.RESULT_OK for the provider to be activated. This activity must be exported.

Example

Below is an example provider declaration in the manifest:

<provider android:name=".ExampleArtProvider"
  android:authorities="com.example.artprovider"
  android:label="@string/source_title"
  android:description="@string/source_description"
  android:permission="com.google.android.apps.muzei.api.ACCESS_PROVIDER">
  <intent-filter>
    <action android:name="com.google.android.apps.muzei.api.MuzeiArtProvider" />
  </intent-filter>
  <!-- A settings activity is optional -->
  <meta-data android:name="settingsActivity"
    android:value=".ExampleSettingsActivity" />
</provider>

If a settingsActivity meta-data element is present, an activity with the given component name should be defined and exported in the application's manifest as well. Muzei will set the EXTRA_FROM_MUZEI extra to true in the launch intent for this activity. An example is shown below:

<activity android:name=".ExampleSettingsActivity"
  android:label="@string/title_settings"
  android:exported="true" />

Finally, below is a simple example MuzeiArtProvider subclass that publishes a single, static artwork:

class ExampleArtProvider : MuzeiArtProvider() {
  override fun onLoadRequested(initial: Boolean) {
    if (initial) {
      setArtwork(Artwork(
          title = "Example image",
          byline = "Unknown person, c. 1980",
          persistentUri = Uri.parse("http://example.com/image.jpg"),
          webUri = Uri.parse("http://example.com/imagedetails.html")))
    }
  }
}

As onLoadRequested can be called at any time (including when offline), it is strongly recommended to use the callback of onLoadRequested to kick off a load operation using WorkManager, JobScheduler, or a comparable API. These other components can then use a ProviderClient and ProviderClient.addArtwork to add Artwork to the MuzeiArtProvider.

Additional notes

Providers can also expose additional user-facing commands (such as 'Share artwork') by returning one or more RemoteActionCompat instances from getCommandActions.

Providers can provide a dynamic description of the current configuration (e.g. 'Popular photos tagged "landscape"'), by overriding getDescription. By default, the android:description element of the provider element in the manifest will be used.

All artwork should support opening an Activity to view more details about the artwork. You can provider your own functionality by overriding getArtworkInfo.

If custom behavior is needed to retrieve the artwork's binary data (for example, authentication with a remote server), this behavior can be added to openFile. If you already have binary data available locally for your artwork, you can also write it directly via ContentResolver.openOutputStream.

It is strongly recommended to add a MuzeiArtDocumentsProvider to your manifest to make artwork from your MuzeiArtProvider available via the default file picker and Files app.

MuzeiArtProvider respects Log.isLoggable for debug logging, allowing you to use adb shell setprop log.tag.MuzeiArtProvider VERBOSE to enable logging of the communications between Muzei and your MuzeiArtProvider.