muzei-api / com.google.android.apps.muzei.api.provider / MuzeiArtProvider

MuzeiArtProvider

abstract class MuzeiArtProvider : ContentProvider, ProviderClient

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:

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.

Constructors

<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.

MuzeiArtProvider()

Properties

contentUri

Retrieve the content URI for the MuzeiArtProvider, allowing you to build custom queries, inserts, updates, and deletes using a ContentResolver.

val contentUri: Uri

lastAddedArtwork

Retrieve the last added artwork from the MuzeiArtProvider.

val lastAddedArtwork: Artwork?

Functions

addArtwork

Add a new piece of artwork to the MuzeiArtProvider.

fun addArtwork(artwork: Artwork): Uri?

Add multiple artwork as a batch operation to the MuzeiArtProvider.

fun addArtwork(artwork: Iterable<Artwork>): List<Uri>

getArtworkInfo

Callback when the user wishes to see more information about the given artwork. The default implementation constructs a PendingIntent to the web uri of the artwork.

open fun getArtworkInfo(artwork: Artwork): PendingIntent?

getCommandActions

Retrieve the list of commands available for the given artwork. Each action should have an icon 24x24dp. Muzei respects the RemoteActionCompat.setShouldShowIcon to determine when to show the action as an icon (assuming there is enough space). Actions with a blank title will be ignored by Muzei.

open fun getCommandActions(artwork: Artwork): List<RemoteActionCompat>

getCommands

Retrieve the list of commands available for the given artwork.

open fun getCommands(artwork: Artwork): List<UserCommand>

getDescription

The longer description for the current state of this MuzeiArtProvider. For example, 'Popular photos tagged "landscape"'). The default implementation returns the android:description element of the provider element in the manifest.

open fun getDescription(): String

isArtworkValid

Called every time an image is loaded (even if there is a cached image available). This gives you an opportunity to circumvent the typical loading process and remove previously cached artwork on demand. The default implementation always returns true.

open fun isArtworkValid(artwork: Artwork): Boolean

onCommand

Callback method indicating that the user has selected a command returned by getCommands.

open fun onCommand(artwork: Artwork, id: Int): Unit

onInvalidArtwork

Called when Muzei failed to load the given artwork, usually due to an incompatibility in supported image format. The default behavior is to delete the artwork.

open fun onInvalidArtwork(artwork: Artwork): Unit

onLoadRequested

Callback method when the user has viewed all of the available artwork. This should be used as a cue to load more artwork so that the user has a constant stream of new artwork.

abstract fun onLoadRequested(initial: Boolean): Unit

openArtworkInfo

Callback when the user wishes to see more information about the given artwork. The default implementation opens the web uri of the artwork.

open fun openArtworkInfo(artwork: Artwork): Boolean

openFile

Provide an InputStream to the binary data associated with artwork that has not yet been cached. The default implementation retrieves the image from the persistent URI and supports URI schemes in the following formats:

open fun openFile(artwork: Artwork): InputStream

setArtwork

Set the MuzeiArtProvider to only show the given artwork, deleting any other artwork previously added. Only in the cases where the artwork is successfully inserted will the other artwork be removed.

fun setArtwork(artwork: Artwork): Uri?
fun setArtwork(artwork: Iterable<Artwork>): List<Uri>

Companion Object Properties

ACCESS_PERMISSION

Permission that can be used with your MuzeiArtProvider to ensure that only your app and Muzei can read and write its data.

const val ACCESS_PERMISSION: String

ACTION_MUZEI_ART_PROVIDER

The Intent action representing a Muzei art provider. This provider should declare an <intent-filter> for this action in order to register with Muzei.

const val ACTION_MUZEI_ART_PROVIDER: String

EXTRA_FROM_MUZEI

Boolean extra that will be set to true when Muzei starts provider settings and setup activities.

const val EXTRA_FROM_MUZEI: String

Extension Functions

createChooseProviderIntent

Deep link into Muzei's Sources screen, automatically scrolling to the com.google.android.apps.muzei.api.provider.MuzeiArtProvider associated with this ProviderClient. If Muzei is not yet activated, users will be asked to activate Muzei before continuing onto the Sources screen.

fun ProviderClient.createChooseProviderIntent(): Intent

isSelected

Checks the MuzeiContract.Sources table provided by Muzei to determine whether the com.google.android.apps.muzei.api.provider.MuzeiArtProvider associated with this ProviderClient has been selected by the user.

fun ProviderClient.isSelected(context: Context): Boolean