/**
 * Copyright (c) Double Symmetry GmbH
 * Commercial use requires a license. See https://rntp.dev/pricing
 */
import { type EmitterSubscription } from 'react-native';
import { type PlayerConfig, type RemoteControlConfig, type BrowseCategory, type MediaItem, type MediaUrl, type Progress, type RepeatMode, type PreloadOptions } from './interfaces';
import { Event, type EventPayloadByEvent, type BackgroundEvent } from './events';
import { type PlaybackState } from './events';
export type BackgroundEventHandler = (event: BackgroundEvent) => Promise<void>;
/**
 * Initializes the native player and applies initial options.
 * Must be called once before using any other API.
 * Defaults are defined in TS; native receives a full config.
 *
 * @remarks
 * - **Android**: Should be called while the app is in the foreground
 * - Calling twice will throw
 */
export declare function setupPlayer(options?: PlayerConfig): void;
/**
 * Android only. Headless JS handler while the app UI is backgrounded. Normalizes Headless
 * payloads to {@link BackgroundEvent} before invoking the handler.
 *
 * @remarks
 * - iOS: no-op — use {@link addEventListener} (including audio background with UIBackgroundModes `audio`).
 * - Register from `index.js` before `AppRegistry.registerComponent`. Handler receives {@link BackgroundEvent}; keep work under ~5s.
 * - UI foreground on Android: use {@link addEventListener} instead.
 * - Does **not** run for Android Auto or CarPlay — in-car controls use native {@link setCommands} handling only.
 * - Only receives remote events when {@link setCommands} uses `handling: 'js'` or `'hybrid'` for that command; default `native` performs actions without invoking this handler.
 */
export declare function registerBackgroundEventHandler(factory: () => BackgroundEventHandler): void;
/**
 * Subscribe to player events (payload only; the event name is the first argument).
 *
 * @remarks
 * - iOS: foreground and audio background (UIBackgroundModes `audio`).
 * - Android: UI foreground; {@link registerBackgroundEventHandler} when backgrounded.
 * - Remote control events are emitted only when {@link setCommands} uses `handling: 'js'` or `'hybrid'` for that command.
 * - Android Auto and CarPlay do not invoke JS listeners; use native {@link setCommands} for in-car behavior.
 */
export declare function addEventListener<T extends Event>(event: T, listener: EventPayloadByEvent[T] extends never ? () => void : (event: EventPayloadByEvent[T]) => void): EmitterSubscription;
/** Start playback. */
export declare function play(): void;
/** Pause playback. */
export declare function pause(): void;
/** Stop playback and reset position. Queue is preserved. */
export declare function stop(): void;
/** Seek to a position in seconds. */
export declare function seekTo(position: number): void;
/** Seek by a relative offset in seconds (negative = rewind). */
export declare function seekBy(offset: number): void;
/** Skip to the next item in the queue. */
export declare function skipToNext(): void;
/**
 * Skip to the previous item in the queue.
 * If playback is past ~3 seconds, restarts the current item instead.
 */
export declare function skipToPrevious(): void;
/** Skip to a specific index in the queue. */
export declare function skipToIndex(index: number): void;
/**
 * Re-prepares the current media item after a playback error.
 * No-op if the player is not in an error state.
 * Does not auto-play — call {@link play} after if needed.
 */
export declare function retry(): void;
/** Set the playback speed (1.0 = normal). */
export declare function setPlaybackSpeed(speed: number): void;
/** Set the player volume (0.0 to 1.0). */
export declare function setVolume(volume: number): void;
/**
 * Clears the queue, adds the media item, and resets position.
 * To begin playback, call {@link play} after this.
 */
export declare function setMediaItem(mediaItem: MediaItem): void;
/**
 * Clears the queue, adds the media items, and resets position.
 * @param startIndex The index of the item to start from (default: 0).
 */
export declare function setMediaItems(mediaItems: MediaItem[], startIndex?: number): void;
/** Append a media item to the end of the queue. */
export declare function addMediaItem(mediaItem: MediaItem): void;
/** Append media items to the end of the queue. */
export declare function addMediaItems(mediaItems: MediaItem[]): void;
/** Insert a media item at the given index. */
export declare function insertMediaItem(index: number, mediaItem: MediaItem): void;
/** Insert media items starting at the given index. */
export declare function insertMediaItems(index: number, mediaItems: MediaItem[]): void;
/** Remove the media item at the given index. */
export declare function removeMediaItem(index: number): void;
/**
 * Remove media items in the range [fromIndex, toIndex).
 * @param fromIndex Start of range (inclusive)
 * @param toIndex End of range (exclusive)
 */
export declare function removeMediaItems(fromIndex: number, toIndex: number): void;
/** Clear all media items from the queue. */
export declare function clear(): void;
/** Clears the on-disk audio cache. For debugging; next playback will re-download. */
export declare function clearCache(): void;
/**
 * Preload a media item into the cache for instant playback later.
 * Works independently of the queue — any future play of the same URL
 * will be a cache hit.
 */
export declare function preload(item: MediaItem, options?: PreloadOptions): void;
/**
 * Cancel an in-progress preload for the given media item.
 * Partial data remains in cache.
 */
export declare function cancelPreload(item: MediaItem): void;
/**
 * Replace the media item at the given index.
 * May continue playback seamlessly if the URL hasn't changed.
 */
export declare function replaceMediaItem(index: number, mediaItem: MediaItem): void;
/** Move a media item from one position to another. */
export declare function moveMediaItem(fromIndex: number, toIndex: number): void;
/**
 * Update display metadata for a media item without interrupting playback.
 * Only provided fields are updated; omitted fields keep their current values.
 * Useful for livestreams/radio where metadata changes while the stream URL stays the same.
 */
export declare function updateMetadata(index: number, metadata: {
    title?: string;
    artist?: string;
    albumTitle?: string;
    artworkUrl?: MediaUrl;
}): void;
/** Gets the current playback state. */
export declare function getPlaybackState(): PlaybackState;
/** Whether the player is currently producing audio output. */
export declare function isPlaying(): boolean;
/** Gets position, duration, buffered position, and cached position in seconds. */
export declare function getProgress(): Progress;
/** Gets the current playback speed. */
export declare function getPlaybackSpeed(): number;
/** Gets the current player volume (0.0 to 1.0). */
export declare function getVolume(): number;
/** Gets the currently active media item, or null if none. */
export declare function getActiveMediaItem(): MediaItem | null;
/** Gets the index of the currently active media item, or null if none. */
export declare function getActiveMediaItemIndex(): number | null;
/** Gets all media items in the queue. */
export declare function getQueue(): MediaItem[];
/** Gets the current repeat mode. */
export declare function getRepeatMode(): RepeatMode;
/** Whether shuffle is enabled. */
export declare function isShuffleEnabled(): boolean;
/**
 * Update remote control configuration at runtime.
 * Use this to change which commands appear in the notification/lock screen
 * (e.g., disable skip buttons on a single-item queue).
 *
 * @remarks
 * Configures the **native** media session (lock screen, notification, Android Auto).
 * With `handling: 'native'` (default), actions run without JavaScript; on Android
 * config is persisted for the playback service. `handling: 'js'` / `'hybrid'` emit
 * remote events to `addEventListener` / `registerBackgroundEventHandler` on the phone
 * only — Android Auto and CarPlay do not run the JS runtime; use native handling
 * or native extensions for in-car custom behavior.
 */
export declare function setCommands(commands: RemoteControlConfig): void;
/** Set the repeat mode. */
export declare function setRepeatMode(mode: RepeatMode): void;
/** Enable or disable shuffle. */
export declare function setShuffleEnabled(enabled: boolean): void;
/** Update the HTTP headers used for progress sync POST requests. */
export declare function updateProgressSyncHeaders(headers: Record<string, string>): void;
/**
 * Set the media browse tree for Android Auto and CarPlay.
 * Each category becomes a top-level browsable folder (Android Auto) or tab (CarPlay);
 * its items can be playable tracks or browsable containers with children.
 *
 * When a user selects a playable item, the native player loads its siblings
 * as the queue and starts playback without JS intervention.
 *
 * @remarks
 * - On CarPlay, a maximum of 4 tabs are shown. If more than 4 categories are provided,
 *   the first 3 become tabs and the rest are grouped under a "More" tab.
 * - Maximum nesting depth: 4 levels (matching CarPlay's navigation stack limit).
 * - Call again to update the tree (e.g. after loading new content)
 */
export declare function setBrowseTree(categories: BrowseCategory[]): void;
/**
 * Sets a countdown sleep timer. Playback pauses after `seconds` of wall clock time.
 * The timer keeps counting even if playback is paused.
 *
 * @param seconds Duration in seconds before playback pauses.
 * @param options.fadeOutSeconds Gradually reduce volume over the last N seconds.
 *   Clamped to `seconds` if it exceeds it. Defaults to 0 (no fade).
 *
 * @remarks Cancels any existing sleep timer (last one wins).
 */
export declare function sleepAfterTime(seconds: number, options?: {
    fadeOutSeconds?: number;
}): void;
/**
 * Pauses playback after the media item at `index` finishes playing.
 *
 * @param index Queue index of the target media item. Defaults to the active item.
 *
 * @remarks
 * - Cancels any existing sleep timer (last one wins).
 * - Index is absolute — queue mutations after setting may shift which item it points to.
 * - No fade-out support (no known time horizon).
 */
export declare function sleepAfterMediaItemAtIndex(index?: number): void;
/**
 * Returns the current sleep timer state, or `null` if none is active.
 */
export declare function getSleepTimer(): {
    type: 'time';
    remainingSeconds: number;
    fadeOutSeconds: number;
} | {
    type: 'mediaItem';
    index: number;
} | null;
/**
 * Cancels the active sleep timer. If a volume fade is in progress,
 * restores the original volume immediately.
 */
export declare function cancelSleepTimer(): void;
/**
 * Tears down the player and releases all resources.
 * After calling this, you must call `setupPlayer()` again to use the player.
 */
export declare function destroy(): void;
//# sourceMappingURL=audio.d.ts.map