react-native-audio-browser 0.0.1 → 0.1.0-next.1

package/lib/typescript/src/features/battery.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Battery optimization status and warning handling for Android 12+ foreground service restrictions.
+ *
+ * When an external controller (Bluetooth, car head unit) tries to resume playback while the app
+ * is killed and battery restrictions are in place, Android 12+ blocks the foreground service start.
+ * This module exposes APIs to detect this condition and guide users to fix their settings.
+ */
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+/**
+ * Battery optimization status.
+ *
+ * - `unrestricted`: App can run freely in background. User explicitly allowed it.
+ * - `optimized`: System may limit background work (Doze, App Standby). Default state.
+ * - `restricted`: User or system severely limited background. Services blocked.
+ */
+export type BatteryOptimizationStatus = 'unrestricted' | 'optimized' | 'restricted';
+/**
+ * Event fired when battery warning pending state changes.
+ */
+export type BatteryWarningPendingChangedEvent = {
+    pending: boolean;
+};
+/**
+ * Event fired when battery optimization status changes.
+ */
+export type BatteryOptimizationStatusChangedEvent = {
+    status: BatteryOptimizationStatus;
+};
+/**
+ * Check if a battery warning is pending (Android only).
+ * Returns true if a foreground service start was blocked and the user hasn't dismissed
+ * the warning or fixed their battery settings.
+ * Auto-clears when battery status becomes unrestricted.
+ * @returns true if warning is pending, always false on iOS
+ */
+export declare function getBatteryWarningPending(): boolean;
+/**
+ * Get the current battery optimization status (Android only).
+ * Also fires onBatteryOptimizationStatusChanged if status changed since last call.
+ * @returns Current status, always 'unrestricted' on iOS
+ */
+export declare function getBatteryOptimizationStatus(): BatteryOptimizationStatus;
+/**
+ * Dismiss the battery warning without fixing settings (Android only).
+ * Call this when the user chooses to ignore the warning.
+ * No-op on iOS.
+ */
+export declare function dismissBatteryWarning(): void;
+/**
+ * Open the system battery settings for this app (Android only).
+ * No-op on iOS.
+ */
+export declare function openBatterySettings(): void;
+/**
+ * Subscribes to battery warning pending state changes (Android only).
+ * Fires when: failure occurs (true), dismissBatteryWarning() called (false),
+ * or status becomes unrestricted (false).
+ * Never fires on iOS.
+ */
+export declare const onBatteryWarningPendingChanged: NativeUpdatedValue<BatteryWarningPendingChangedEvent>;
+/**
+ * Subscribes to battery optimization status changes (Android only).
+ * Fires when user returns from settings with a different status.
+ * Never fires on iOS.
+ */
+export declare const onBatteryOptimizationStatusChanged: NativeUpdatedValue<BatteryOptimizationStatusChangedEvent>;
+/**
+ * Hook that returns whether a battery warning is pending and updates when it changes (Android only).
+ * @returns true if warning is pending, always false on iOS
+ */
+export declare function useBatteryWarningPending(): boolean;
+/**
+ * Hook that returns the current battery optimization status and updates when it changes (Android only).
+ * @returns Current status, always 'unrestricted' on iOS
+ */
+export declare function useBatteryOptimizationStatus(): BatteryOptimizationStatus;
+/**
+ * Return type for useBatteryWarning hook.
+ */
+export interface BatteryWarning {
+    /** Whether a battery warning is pending */
+    pending: boolean;
+    /** Current battery optimization status */
+    status: BatteryOptimizationStatus;
+    /** Dismiss the warning without changing settings */
+    dismiss: () => void;
+    /** Open system battery settings for this app */
+    openSettings: () => void;
+}
+/**
+ * Meta hook that bundles all battery warning state and actions (Android only).
+ * Use this for a complete battery warning UI implementation.
+ *
+ * @example
+ * ```tsx
+ * function BatteryWarningBanner() {
+ *   const { pending, status, dismiss, openSettings } = useBatteryWarning()
+ *
+ *   if (!pending) return null
+ *
+ *   return (
+ *     <View>
+ *       <Text>Battery status: {status}</Text>
+ *       <Button onPress={openSettings} title="Fix" />
+ *       <Button onPress={dismiss} title="Dismiss" />
+ *     </View>
+ *   )
+ * }
+ * ```
+ */
+export declare function useBatteryWarning(): BatteryWarning;
+//# sourceMappingURL=battery.d.ts.map

package/lib/typescript/src/features/battery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"battery.d.ts","sourceRoot":"","sources":["../../../../src/features/battery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAKhE;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,WAAW,GACX,YAAY,CAAA;AAEhB;;GAEG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,qCAAqC,GAAG;IAClD,MAAM,EAAE,yBAAyB,CAAA;CAClC,CAAA;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,yBAAyB,CAExE;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAID;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,uDAGxC,CAAA;AAEH;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,2DAG5C,CAAA;AAIH;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAMlD;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,yBAAyB,CAMxE;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAA;IAChB,0CAA0C;IAC1C,MAAM,EAAE,yBAAyB,CAAA;IACjC,oDAAoD;IACpD,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,gDAAgD;IAChD,YAAY,EAAE,MAAM,IAAI,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAUlD"}

package/lib/typescript/src/features/browser.d.ts

@@ -0,0 +1,68 @@
+import type { BrowserConfiguration, ResolvedTrack, Track } from '../types';
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+/**
+ * Configures the browser with routes, tabs, and other settings.
+ * Also registers the browser with the player to enable:
+ * - Media URL transformation for authenticated playback
+ * - Android Auto / CarPlay browsing integration
+ * - Playback of browsable tracks via navigate()
+ *
+ * @param configuration - Browser configuration including routes, tabs, media config, etc.
+ *
+ * @example
+ * ```ts
+ * configureBrowser({
+ *   routes: {
+ *     '/albums/:id': { path: '/api/albums/:id' }
+ *   },
+ *   tabs: [
+ *     { title: 'Home', url: '/' },
+ *     { title: 'Search', url: '/search' }
+ *   ]
+ * })
+ * ```
+ */
+export declare function configureBrowser(configuration: BrowserConfiguration): void;
+export declare function navigate(pathOrTrack: string | Track): void;
+export declare function getPath(): string | undefined;
+export declare const onPathChanged: NativeUpdatedValue<string | undefined>;
+export declare function usePath(): string | undefined;
+export declare function getContent(): ResolvedTrack | undefined;
+export declare const onContentChanged: NativeUpdatedValue<ResolvedTrack | undefined>;
+export declare function useContent(): ResolvedTrack | undefined;
+export declare function getTabs(): Track[] | undefined;
+export declare const onTabsChanged: NativeUpdatedValue<Track[] | undefined>;
+export declare function useTabs(): Track[] | undefined;
+/**
+ * Notifies external media controllers (Android Auto, CarPlay) that content
+ * at the specified path has changed and should be refreshed.
+ *
+ * @param path - The path where content has changed (e.g., '/favorites')
+ *
+ * @example
+ * ```ts
+ * // After adding a track to favorites
+ * notifyContentChanged('/favorites')
+ * ```
+ */
+export declare const notifyContentChanged: (path: string) => void;
+/**
+ * Returns whether search functionality is configured via `configureBrowser({ search: ... })`.
+ */
+export declare function hasSearch(): boolean;
+/**
+ * Searches for tracks using the configured search source.
+ *
+ * @param query - The search query string
+ * @returns Promise resolving to an array of matching tracks
+ *
+ * @see {@link configureBrowser}
+ *
+ * @example
+ * ```ts
+ * const results = await search('jazz')
+ * console.log(`Found ${results.length} tracks`)
+ * ```
+ */
+export declare function search(query: string): Promise<Track[]>;
+//# sourceMappingURL=browser.d.ts.map

package/lib/typescript/src/features/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../src/features/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAGpB,aAAa,EAKb,KAAK,EAEN,MAAM,UAAU,CAAA;AAMjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AA4LhE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,oBAAoB,GAAG,IAAI,CAE1E;AAED,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK,QAMnD;AAED,wBAAgB,OAAO,uBAEtB;AAED,eAAO,MAAM,aAAa,wCAEzB,CAAA;AAED,wBAAgB,OAAO,IAAI,MAAM,GAAG,SAAS,CAE5C;AAED,wBAAgB,UAAU,IAAI,aAAa,GAAG,SAAS,CAEtD;AAED,eAAO,MAAM,gBAAgB,+CAEmB,CAAA;AAEhD,wBAAgB,UAAU,IAAI,aAAa,GAAG,SAAS,CAEtD;AACD,wBAAgB,OAAO,IAAI,KAAK,EAAE,GAAG,SAAS,CAE7C;AAED,eAAO,MAAM,aAAa,yCAEzB,CAAA;AAED,wBAAgB,OAAO,IAAI,KAAK,EAAE,GAAG,SAAS,CAE7C;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,IAEnD,CAAA;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAInC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAE5D"}

package/lib/typescript/src/features/equalizer.d.ts

@@ -0,0 +1,35 @@
+import type { EqualizerSettings } from '../specs/audio-browser.nitro';
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+export type { EqualizerSettings };
+/**
+ * Gets the current equalizer settings (Android only).
+ * @returns Equalizer settings, or undefined if not available
+ */
+export declare function getEqualizerSettings(): EqualizerSettings | undefined;
+/**
+ * Enables or disables the equalizer (Android only).
+ * @param enabled - Whether to enable the equalizer
+ */
+export declare function setEqualizerEnabled(enabled: boolean): void;
+/**
+ * Sets the equalizer to a preset (Android only).
+ * @param preset - The name of the preset to apply
+ */
+export declare function setEqualizerPreset(preset: string): void;
+/**
+ * Sets custom equalizer band levels (Android only).
+ * @param levels - Array of level values for each band (in millibels)
+ */
+export declare function setEqualizerLevels(levels: number[]): void;
+/**
+ * Subscribes to equalizer settings changes (Android only).
+ * @param callback - Called when equalizer settings change
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onEqualizerChanged: NativeUpdatedValue<EqualizerSettings>;
+/**
+ * Hook that returns the current equalizer settings and updates when they change (Android only).
+ * @returns Current equalizer settings, or undefined if not available
+ */
+export declare function useEqualizerSettings(): EqualizerSettings | undefined;
+//# sourceMappingURL=equalizer.d.ts.map

package/lib/typescript/src/features/equalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equalizer.d.ts","sourceRoot":"","sources":["../../../../src/features/equalizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAErE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAGhE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAIjC;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,SAAS,CAEpE;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE1D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAEzD;AAID;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,uCAG5B,CAAA;AAIH;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,SAAS,CAEpE"}

package/lib/typescript/src/features/errors.d.ts

@@ -0,0 +1,136 @@
+import type { FormattedNavigationError } from '../types/browser';
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+export type { FormattedNavigationError } from '../types/browser';
+export type PlaybackError = {
+    code: string;
+    message: string;
+};
+/**
+ * Emitted when a playback error occurs.
+ */
+export interface PlaybackErrorEvent {
+    error?: PlaybackError;
+}
+/**
+ * Type of navigation error that occurred.
+ *
+ * - `'content-not-found'` - No route configured for the requested path, or route resolution
+ *   returned no content. This is a configuration issue, not an HTTP 404 from the server.
+ * - `'network-error'` - Network request failed (connection error, timeout, no internet).
+ * - `'http-error'` - Server returned a non-2xx HTTP status code, or returned 2xx but response
+ *   parsing failed. Check `statusCode` and `statusCodeSuccess` for details.
+ * - `'callback-error'` - The browse callback returned an error (e.g., `{ error: 'message' }`).
+ *   Use this for business logic errors like authentication failures or subscription requirements.
+ * - `'unknown-error'` - An unexpected error occurred (e.g., invalid configuration).
+ */
+export type NavigationErrorType = 'content-not-found' | 'network-error' | 'http-error' | 'callback-error' | 'unknown-error';
+export type NavigationError = {
+    code: NavigationErrorType;
+    message: string;
+    /** HTTP status code when code is 'http-error' */
+    statusCode?: number;
+    /** True if HTTP status code was 2xx (success), useful when error is due to response parsing */
+    statusCodeSuccess?: boolean;
+};
+/**
+ * Emitted when a navigation error occurs.
+ */
+export interface NavigationErrorEvent {
+    error?: NavigationError;
+}
+/**
+ * Gets the current playback error, if any.
+ * @returns The current error or undefined if there is no error
+ */
+export declare function getPlaybackError(): PlaybackError | undefined;
+/**
+ * Subscribes to playback error events.
+ * @param callback - Called when a playback error occurs
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onPlaybackError: NativeUpdatedValue<PlaybackErrorEvent>;
+/**
+ * Hook that returns the current playback error and updates when it changes.
+ * @returns The current playback error or undefined
+ */
+export declare function usePlaybackError(): PlaybackError | undefined;
+/**
+ * Gets the current navigation error, if any.
+ * @returns The current navigation error or undefined if there is no error
+ */
+export declare function getNavigationError(): NavigationError | undefined;
+/**
+ * Subscribes to navigation error events.
+ * @param callback - Called when a navigation error occurs
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onNavigationError: NativeUpdatedValue<NavigationErrorEvent>;
+/**
+ * Hook that returns the current navigation error and updates when it changes.
+ * @returns The current navigation error or undefined
+ */
+export declare function useNavigationError(): NavigationError | undefined;
+/**
+ * Gets the current navigation error formatted for display.
+ * Native formats the error using the configured `formatNavigationError` callback,
+ * or falls back to default formatting.
+ *
+ * @returns Formatted error with title and message, or undefined if no error
+ */
+export declare function getFormattedNavigationError(): FormattedNavigationError | undefined;
+/**
+ * Subscribes to formatted navigation error changes.
+ * @param callback - Called when the formatted navigation error changes
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onFormattedNavigationError: NativeUpdatedValue<FormattedNavigationError | undefined>;
+/**
+ * Hook that returns the current navigation error formatted for display.
+ *
+ * Native formats the error using the `formatNavigationError` callback configured
+ * in {@link BrowserConfiguration}, or falls back to default English messages.
+ *
+ * The same formatted error is used by CarPlay and Android Auto error dialogs,
+ * ensuring consistent error presentation across your app and external controllers.
+ *
+ * @returns Formatted error with title and message, or undefined if no error
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const error = useFormattedNavigationError()
+ *
+ * if (error) {
+ *   return <ErrorView title={error.title} message={error.message} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Configure custom formatting - override only specific errors or routes
+ * configureBrowser({
+ *   formatNavigationError: ({ error, defaultFormatted, path }) => {
+ *     // Custom message for specific routes
+ *     if (error.code === 'network-error' && path.startsWith('/json-api')) {
+ *       return {
+ *         title: 'API Server Not Running',
+ *         message: 'Start the API server first'
+ *       }
+ *     }
+ *     if (error.code === 'http-error') {
+ *       return {
+ *         title: t('error.serverError'),
+ *         message: t('error.httpMessage', { status: error.statusCode })
+ *       }
+ *     }
+ *     // Use default for other error types
+ *     return defaultFormatted
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link BrowserConfiguration.formatNavigationError} - Configure custom error formatting
+ * @see {@link useNavigationError} - Access the raw error with code and status details
+ */
+export declare function useFormattedNavigationError(): FormattedNavigationError | undefined;
+//# sourceMappingURL=errors.d.ts.map

package/lib/typescript/src/features/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/features/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAEhE,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,eAAe,GACf,YAAY,GACZ,gBAAgB,GAChB,eAAe,CAAA;AAEnB,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,mBAAmB,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,eAAe,CAAA;CACxB;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAID;;;;GAIG;AACH,eAAO,MAAM,eAAe,wCAGzB,CAAA;AAIH;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAGhE;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,0CAG3B,CAAA;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAID;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IACvC,wBAAwB,GACxB,SAAS,CAEZ;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,0DAEmB,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,2BAA2B,IACvC,wBAAwB,GACxB,SAAS,CAKZ"}

package/lib/typescript/src/features/favorites.d.ts

@@ -0,0 +1,84 @@
+import type { Track } from '../types';
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+/**
+ * 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.
+ *
+ * @param favorited - Whether the track is favorited
+ *
+ * @example
+ * ```ts
+ * setActiveTrackFavorited(true)
+ * ```
+ */
+export declare function setActiveTrackFavorited(favorited: boolean): void;
+/**
+ * Toggles the favorited state of the currently playing track.
+ *
+ * @example
+ * ```ts
+ * // In a button handler
+ * toggleActiveTrackFavorited()
+ * ```
+ */
+export declare function toggleActiveTrackFavorited(): 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.
+ *
+ * @param favorites - Array of favorited track `src` values
+ *
+ * @example
+ * ```ts
+ * const favoriteSrcs = await loadFavoritesFromStorage()
+ * setFavorites(favoriteSrcs)
+ * ```
+ */
+export declare function setFavorites(favorites: string[]): void;
+/**
+ * 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).
+ */
+export interface FavoriteChangedEvent {
+    /** The track whose favorite state changed. */
+    track: Track;
+    /** The new favorite state. */
+    favorited: boolean;
+}
+/**
+ * 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 callback - Called with the track and its new favorite state
+ * @returns Cleanup function to unsubscribe
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = onFavoriteChanged.addListener(({ track, favorited }) => {
+ *   // Persist the change to your backend/storage
+ *   if (favorited) {
+ *     addToFavorites(track)
+ *   } else {
+ *     removeFromFavorites(track)
+ *   }
+ * })
+ * ```
+ */
+export declare const onFavoriteChanged: NativeUpdatedValue<FavoriteChangedEvent>;
+//# sourceMappingURL=favorites.d.ts.map

package/lib/typescript/src/features/favorites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"favorites.d.ts","sourceRoot":"","sources":["../../../../src/features/favorites.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAErC,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAEhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAEtD;AAID;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,KAAK,EAAE,KAAK,CAAA;IACZ,8BAA8B;IAC9B,SAAS,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,0CAG3B,CAAA"}

package/lib/typescript/src/features/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Feature-based exports - each feature includes:
+ * - Event types
+ * - Getters (get*)
+ * - Setters (set*)
+ * - Event callbacks (on*)
+ * - React hooks (use*)
+ */
+export * from './output';
+export * from './playback';
+export * from './player';
+export * from './queue';
+export * from './battery';
+export * from './browser';
+export * from './equalizer';
+export * from './errors';
+export * from './favorites';
+export * from './metadata';
+export * from './network';
+export * from './nowPlaying';
+export * from './remoteControls';
+export * from './sleepTimer';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/features/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/features/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA"}

package/lib/typescript/src/features/metadata.d.ts

@@ -0,0 +1,103 @@
+import type { Rating } from './rating';
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+export type RatingType = 'heart' | 'thumbs-up-down' | 'three-stars' | 'four-stars' | 'five-stars' | 'percentage' | 'none';
+export interface TrackMetadataBase {
+    /** The track title */
+    title?: string;
+    /** The track album */
+    album?: string;
+    /** The track artist */
+    artist?: string;
+    /** The track duration in seconds */
+    duration?: number;
+    /** The track artwork */
+    artwork?: string;
+    /** track description */
+    description?: string;
+    /** track mediaId */
+    mediaId?: string;
+    /** The track genre */
+    genre?: string;
+    /** The track rating */
+    rating?: Rating;
+}
+export interface NowPlayingMetadata extends TrackMetadataBase {
+    elapsedTime?: number;
+}
+/**
+ * Metadata update for the now playing notification.
+ * Pass to `updateNowPlaying()` to override what's shown in the notification/lock screen.
+ * Pass `null` to clear overrides and revert to track metadata.
+ */
+export type NowPlayingUpdate = {
+    /** Title shown in notification */
+    title?: string;
+    /** Artist shown in notification */
+    artist?: string;
+};
+/**
+ * Timed metadata received during playback.
+ * Contains metadata from ICY streams (radio) or ID3 frames.
+ */
+export interface TimedMetadata {
+    title?: string;
+    artist?: string;
+    album?: string;
+    date?: string;
+    genre?: string;
+}
+/**
+ * Static track metadata from the media file.
+ * Contains standardized metadata fields.
+ */
+export interface TrackMetadata {
+    title?: string;
+    artist?: string;
+    albumTitle?: string;
+    subtitle?: string;
+    description?: string;
+    artworkUri?: string;
+    trackNumber?: string;
+    composer?: string;
+    conductor?: string;
+    genre?: string;
+    compilation?: string;
+    station?: string;
+    mediaType?: string;
+    creationDate?: string;
+    creationYear?: string;
+    url?: string;
+}
+/**
+ * Chapter metadata with time range.
+ * Used for podcast chapters, audiobook chapters, etc.
+ */
+export interface ChapterMetadata {
+    /** Chapter start time in seconds */
+    startTime: number;
+    /** Chapter end time in seconds */
+    endTime: number;
+    /** Chapter title */
+    title?: string;
+    /** URL associated with the chapter */
+    url?: string;
+}
+/**
+ * Subscribes to chapter metadata events.
+ * @param callback - Called when chapter metadata is received
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onChapterMetadata: NativeUpdatedValue<ChapterMetadata[]>;
+/**
+ * Subscribes to track metadata events.
+ * @param callback - Called when static track metadata is received
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onTrackMetadata: NativeUpdatedValue<TrackMetadata>;
+/**
+ * Subscribes to timed metadata events (ICY/ID3 from live streams).
+ * @param callback - Called when stream metadata is received (title, artist from ICY/ID3 tags)
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onTimedMetadata: NativeUpdatedValue<TimedMetadata>;
+//# sourceMappingURL=metadata.d.ts.map

package/lib/typescript/src/features/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../../../src/features/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE,MAAM,MAAM,UAAU,GAClB,OAAO,GACP,gBAAgB,GAChB,aAAa,GACb,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,MAAM,CAAA;AAEV,MAAM,WAAW,iBAAiB;IAChC,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAID;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uCAEmB,CAAA;AAEjD;;;;GAIG;AACH,eAAO,MAAM,eAAe,mCAE3B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,mCAE3B,CAAA"}

package/lib/typescript/src/features/network.d.ts

@@ -0,0 +1,18 @@
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+/**
+ * Gets the current network connectivity state.
+ * @returns true if the device is online, false otherwise
+ */
+export declare function getOnline(): boolean;
+/**
+ * Subscribes to network connectivity changes.
+ * @param callback - Called when network state changes
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onOnlineChanged: NativeUpdatedValue<boolean>;
+/**
+ * Hook that returns the current network connectivity state and updates when it changes.
+ * @returns true if the device is online, false otherwise
+ */
+export declare function useOnline(): boolean;
+//# sourceMappingURL=network.d.ts.map

package/lib/typescript/src/features/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../../src/features/network.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAKhE;;;GAGG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAID;;;;GAIG;AACH,eAAO,MAAM,eAAe,6BAE3B,CAAA;AAID;;;GAGG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC"}

package/lib/typescript/src/features/nowPlaying.d.ts

@@ -0,0 +1,36 @@
+import type { NowPlayingMetadata, NowPlayingUpdate } from './metadata';
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+/**
+ * Updates the now playing notification metadata.
+ * Pass null/undefined to clear overrides and revert to track metadata.
+ *
+ * @example
+ * ```ts
+ * // Override notification with stream metadata
+ * updateNowPlaying({
+ *   title: streamMetadata.title,
+ *   artist: streamMetadata.artist,
+ * })
+ *
+ * // Clear overrides, revert to track metadata
+ * updateNowPlaying(null)
+ * ```
+ */
+export declare function updateNowPlaying(update: NowPlayingUpdate | null): void;
+/**
+ * Gets the current now playing metadata (override if set, else track metadata).
+ */
+export declare function getNowPlaying(): NowPlayingMetadata | undefined;
+/**
+ * Subscribes to now playing metadata change events.
+ * Fires when updateNowPlaying is called or when the track changes.
+ * @param callback - Called when now playing metadata changes
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onNowPlayingChanged: NativeUpdatedValue<NowPlayingMetadata>;
+/**
+ * Hook that returns the current now playing metadata and updates when it changes.
+ * @returns The current now playing metadata or undefined
+ */
+export declare function useNowPlaying(): NowPlayingMetadata | undefined;
+//# sourceMappingURL=nowPlaying.d.ts.map

package/lib/typescript/src/features/nowPlaying.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nowPlaying.d.ts","sourceRoot":"","sources":["../../../../src/features/nowPlaying.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAKhE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAEtE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,kBAAkB,GAAG,SAAS,CAE9D;AAID;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,wCAG7B,CAAA;AAIH;;;GAGG;AACH,wBAAgB,aAAa,IAAI,kBAAkB,GAAG,SAAS,CAE9D"}