Poweramp API

Poweramp provides several different API surfaces depending on the type of extension or integration you are building. The available SDKs and integration methods include:

• Skin SDK: For creating custom user interface skins.
• Intent-based APIs: For interacting with Poweramp via Android Intents (includes support for Tasker and similar automation apps).
• Visualization Presets: For creating custom visualizers.
• Track Providers: For providing music tracks to Poweramp.
• Lyrics Plugin: For providing lyrics data.
• Album Art Loaders: (Status: TBD) For custom album art loading logic.

For additional developer resources and community discussion, visit the Poweramp Developer Area.

Poweramp v3 (build 948+) allows third-party plugins to provide external lyrics (both plain text and LRC formats) for tracks currently playing in the player.

The API operates using a broadcast-based intent system. Poweramp sends intents to your plugin, and your plugin responds by sending intents back to Poweramp. While referred to as 'broadcasts', these intents are sent to a single specific receiver (either the plugin application or the Poweramp application).

Poweramp provides Intent-based APIs designed for simplicity and control. Developers can interact with Poweramp by sending Intents to perform actions or by listening to published Intents to retrieve the current state of the application.

Key capabilities include:

• Playback Control: Command Poweramp to play specific content.
• Command Execution: Send instructions to Poweramp to perform various tasks.
• State Retrieval: Access Poweramp's current state via published Intents.

These Intents can be triggered programmatically within an application or via automation apps.

You can provide metadata and album art using one of two approaches:

1. Provider-Provided Metadata

If you include MediaStore.MediaColumns.TITLE or MediaStore.MediaColumns.DURATION in your cursor, Poweramp assumes you are providing the metadata and will not attempt to scan the file itself.

• Album Art: If Document.COLUMN_FLAGS contains Document.FLAG_SUPPORTS_THUMBNAIL, Poweramp will request the art via openDocumentThumbnail.
• Lyrics: Can be provided via TrackProviderConsts.COLUMN_TRACK_LYRICS.

2. Track-File Metadata

If TITLE or DURATION are missing from your cursor, Poweramp will attempt to open the file via the file descriptor to extract tags and embedded album art itself.

Poweramp broadcasts status changes using the action com.maxmpz.audioplayer.STATUS_CHANGED. You can listen for this intent to react to playback changes.

When the intent is received, it includes several extras that can be accessed directly (e.g., in automation apps like Tasker).

Available Extras (Build 948+): Since build 948, track metadata is included directly in the STATUS_CHANGED extras. You can access:

• %title
• %album
• %artist
• (and other track info extras)

Playback State Extras:

• %state
• %paused

Action: com.maxmpz.audioplayer.STATUS_CHANGED

Example variables:
State=%state
Paused=%paused
Artist=%artist
Title=%title

Poweramp performs scanning in two distinct phases to build its library:

1. Hierarchy Scan:

   • Establishes the folder and track hierarchy.
   • Adds new tracks and removes deleted ones from the database.
   • Updates last modified timestamps.
   • Uses a limited set of projection columns.

2. Metadata Scan:

   • Retrieves detailed metadata for new or modified tracks (based on timestamps).
   • Uses a broader set of projection columns (though some, like lyrics, may still be excluded).

Note on Loading: Poweramp does not support "Loading" cursors. You should provide ready-to-use cursors. If data loading is slow, you can block in your provider methods, but be aware of Poweramp's scan and openDocument timeouts (the latter is configurable by the user as "Network Timeout").

The Poweramp Equalizer can load Poweramp skins. To support the Equalizer, use the additional styles, attributes, and layouts specifically defined for it, which typically use a peq prefix or suffix.

Note: When building your skin, you should still build against the Poweramp APK, as the Equalizer APK does not contain public definitions.

Poweramp saves user settings based on the IDs generated for your skin's styles and attributes. If you perform a clean build and these IDs change, user settings will be lost.

To prevent this, use a stable-ids.txt file. This file is automatically updated during the build process and should be kept in your project.

Important: Only attributes used in your skins.xml <skin> tag's style attribute need stable IDs. For example, if you use <skin style="@style/SampleSkin">, your stable-ids.txt must contain a line like: com.poweramp.v3.sampleskin:style/SampleSkin = 0x80070054

The Poweramp Track Provider API is not a proprietary standalone API; instead, it is built upon standard Android APIs:

1. Storage Access Framework (SAF)
2. DocumentsContract

Because it uses these standard interfaces, a provider plugin implemented for Poweramp can also be used by other Android applications (like Google Files or other file managers) that implement SAF/DocumentsContract client APIs. If you require your provider to be hidden from other apps, you must request this via a GitHub issue.

It is important to note that Poweramp v2 and v3 skins are not compatible with each other.

For skins targeting Build 912+, new attributes are available for FastTextView (used for titles, meta, etc.) to simplify pixel-perfect alignment across different fonts and zoom levels:

• layout_alignToContent: Forces alignment to the content, ignoring padding.
• eatFontPads: Removes implicit vertical font paddings.

To enable the new padding system in your skin, add allowNewPadding="true" to your <skin> element.

Warning: If you redefine ItemTrackTitle or other ItemTrack** text styles, ensure you override all margin/alignment attributes (scale, padding, gravity) or remove overrides entirely to avoid broken layouts when using derived styles.