features/favorites

FavoriteChangedEvent

Event data for when the favorite state of the active track changes. Emitted when the user taps the heart button in a media controller (notification, Android Auto, CarPlay).

Properties

Property	Type	Description
track	Track	The track whose favorite state changed.
favorited	boolean	The new favorite state.

---

setActiveTrackFavorited()

function setActiveTrackFavorited(favorited): void;

Sets the favorited state of the currently playing track. Updates the heart icon in media controllers (notification, Android Auto).

Use this for programmatic favorite changes (e.g., from a favorite button in your app). For heart button taps from media controllers, use onFavoriteChanged instead - the native side handles those automatically.

Parameters

Parameter	Type	Description
favorited	boolean	Whether the track is favorited

Returns

void

Example

setActiveTrackFavorited(true)

---

toggleActiveTrackFavorited()

function toggleActiveTrackFavorited(): void;

Toggles the favorited state of the currently playing track.

Returns

void

Example

// In a button handler
toggleActiveTrackFavorited()

---

onFavoriteChanged

const onFavoriteChanged: NativeUpdatedValue<FavoriteChangedEvent>;

Subscribes to favorite state change events. Called when the user taps the heart button in a media controller. The native side has already updated the track's favorite state and UI.

Param

Called with the track and its new favorite state

Returns

Cleanup function to unsubscribe

Example

const unsubscribe = onFavoriteChanged.addListener(({ track, favorited }) => {
  // Persist the change to your backend/storage
  if (favorited) {
    addToFavorites(track)
  } else {
    removeFromFavorites(track)
  }
})

---

setFavorites()

function setFavorites(favorites): void;

Sets the list of favorited track source identifiers.

This syncs your app's favorites with the native favorites cache, enabling the heart button in media controllers (notification, Android Auto, CarPlay) to show the correct state.

Note: This is only needed if the tracks provided to AudioBrowser do not include the favorited field. If your API already includes favorite state in track responses, the native favorites cache is populated automatically during browsing.

When the heart button is tapped in media controllers or when you call setActiveTrackFavorited(), the native favorites cache is automatically updated. You only need to call this on app launch to hydrate the cache.

Parameters

Parameter	Type	Description
favorites	string[]	Array of favorited track src values

Returns

void

Example

const favoriteSrcs = await loadFavoritesFromStorage()
setFavorites(favoriteSrcs)