expo-gliph-player 1.0.0

package/src/GliphPlayer.ts

@@ -0,0 +1,356 @@
+/**
+ * GliphPlayer.ts
+ *
+ * Main JS/TS API surface. Wraps the TurboModule (NativeGliphPlayer) and
+ * provides a clean, typed interface identical in spirit to react-native-track-player.
+ */
+
+import { NativeEventEmitter, Platform } from 'react-native';
+import NativeGliphPlayer from './specs/NativeGliphPlayer';
+import type {
+  Track,
+  PlayerOptions,
+  UpdateOptions,
+  Progress,
+  PlaybackState,
+} from './types';
+import { RepeatMode, State } from './types';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+let _emitter: NativeEventEmitter | null = null;
+
+function getEmitter(): NativeEventEmitter {
+  if (!NativeGliphPlayer) {
+    throw new Error('[RNGliphPlayer] Native module not found. Is it linked correctly?');
+  }
+  if (!_emitter) {
+    _emitter = new NativeEventEmitter(NativeGliphPlayer as any);
+  }
+  return _emitter;
+}
+
+/** Resolve a require()'d asset to a URI string the native side can consume */
+function resolveAssetSource(source: string | number): string {
+  if (typeof source === 'number') {
+
+    const { Image } = require('react-native');
+    return Image.resolveAssetSource(source).uri as string;
+  }
+  return source;
+}
+
+/** Serialize a Track to a plain object safe for the TurboModule bridge */
+function serializeTrack(track: Track): Record<string, unknown> {
+  return {
+    id: track.id ?? `track_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+    url: resolveAssetSource(track.url as string | number),
+    title: track.title,
+    artist: track.artist,
+    album: track.album ?? '',
+    artwork: track.artwork != null ? resolveAssetSource(track.artwork as string | number) : '',
+    duration: track.duration ?? -1,
+    genre: track.genre ?? '',
+    date: track.date ?? '',
+    description: track.description ?? '',
+    rating: track.rating ?? 0,
+    isLiveStream: track.isLiveStream ?? false,
+    headers: track.headers ?? {},
+    pitchAlgorithm: track.pitchAlgorithm ?? 0,
+    userAgent: track.userAgent ?? '',
+  };
+}
+
+function checkModule(): NonNullable<typeof NativeGliphPlayer> {
+  if (!NativeGliphPlayer) {
+    throw new Error(
+      '[RNGliphPlayer] Native module not found. ' +
+      'Ensure you have rebuilt the app after installing the library and ' +
+      'that you are not calling player methods before the JSI bridge is ready.'
+    );
+  }
+  return NativeGliphPlayer;
+}
+
+// ─── GliphPlayer API ─────────────────────────────────────────────────────────
+
+const GliphPlayer = {
+  // ── Setup ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Initialize the player. Must be called once before any other method.
+   * Safe to call multiple times — subsequent calls are no-ops.
+   */
+  async setupPlayer(options: PlayerOptions = {}): Promise<void> {
+    if (!NativeGliphPlayer) {
+      throw new Error('[RNGliphPlayer] Native module not ready. Ensure setup is called after app initialization.');
+    }
+    const opts: Record<string, unknown> = {
+      minBuffer: options.minBuffer ?? 15,
+      maxBuffer: options.maxBuffer ?? 50,
+      playBuffer: options.playBuffer ?? 2.5,
+      backBuffer: options.backBuffer ?? 0,
+      maxCacheSize: options.maxCacheSize ?? 0,
+      iosCategory: options.iosCategory ?? 'playback',
+      iosCategoryMode: options.iosCategoryMode ?? 'default',
+      iosCategoryOptions: options.iosCategoryOptions ?? [],
+      waitForBuffer: options.waitForBuffer ?? true,
+      autoHandleInterruptions: options.autoHandleInterruptions ?? false,
+      autoUpdateMetadata: options.autoUpdateMetadata ?? true,
+      progressUpdateEventInterval: options.progressUpdateEventInterval ?? 1.0,
+      android: options.android ?? {},
+    };
+    return NativeGliphPlayer.setupPlayer(opts);
+  },
+
+  /**
+   * Destroy the player and release all resources.
+   */
+  destroy(): void {
+    checkModule().destroy();
+    _emitter = null;
+  },
+
+  /**
+   * Returns true if the background service is running (Android).
+   */
+  async isServiceRunning(): Promise<boolean> {
+    if (Platform.OS !== 'android') {return true;}
+    return checkModule().isServiceRunning();
+  },
+
+  // ── Queue management ───────────────────────────────────────────────────────
+
+  /**
+   * Add one or more tracks to the queue.
+   * @param tracks  Single track or array of tracks.
+   * @param insertBeforeIndex  Insert position. Defaults to end of queue.
+   * @returns The index of the first inserted track.
+   */
+  async add(
+    tracks: Track | Track[],
+    insertBeforeIndex?: number
+  ): Promise<number | void> {
+    const arr = Array.isArray(tracks) ? tracks : [tracks];
+    const serialized = arr.map(serializeTrack);
+    // Pass -1 as sentinel for "append to end" — Codegen doesn't support optional number params
+    const result = await checkModule().add(serialized, insertBeforeIndex ?? -1);
+    return result;
+  },
+
+  /**
+   * Remove tracks by their IDs.
+   */
+  async remove(trackIds: string | string[]): Promise<void> {
+    const ids = Array.isArray(trackIds) ? trackIds : [trackIds];
+    return checkModule().remove(ids);
+  },
+
+  /**
+   * Remove all tracks after the current one.
+   */
+  async removeUpcomingTracks(): Promise<void> {
+    return checkModule().removeUpcomingTracks();
+  },
+
+  /**
+   * Skip to a specific queue index.
+   */
+  async skip(index: number, initialPosition?: number): Promise<void> {
+    return checkModule().skip(index, initialPosition ?? -1);
+  },
+
+  /**
+   * Skip to the next track.
+   */
+  async skipToNext(initialPosition?: number): Promise<void> {
+    return checkModule().skipToNext(initialPosition ?? -1);
+  },
+
+  /**
+   * Skip to the previous track.
+   */
+  async skipToPrevious(initialPosition?: number): Promise<void> {
+    return checkModule().skipToPrevious(initialPosition ?? -1);
+  },
+
+  /**
+   * Move a track from one index to another.
+   */
+  async move(fromIndex: number, toIndex: number): Promise<void> {
+    return checkModule().move(fromIndex, toIndex);
+  },
+
+  // ── Playback control ───────────────────────────────────────────────────────
+
+  async play(): Promise<void> {
+    return checkModule().play();
+  },
+
+  async pause(): Promise<void> {
+    return checkModule().pause();
+  },
+
+  async stop(): Promise<void> {
+    return checkModule().stop();
+  },
+
+  /**
+   * Stop playback and clear the queue.
+   */
+  async reset(): Promise<void> {
+    return checkModule().reset();
+  },
+
+  /**
+   * Seek to an absolute position in seconds.
+   */
+  async seekTo(position: number): Promise<void> {
+    return checkModule().seekTo(position);
+  },
+
+  /**
+   * Seek by a relative offset in seconds (positive = forward, negative = back).
+   */
+  async seekBy(offset: number): Promise<void> {
+    return checkModule().seekBy(offset);
+  },
+
+  /**
+   * Set volume (0.0 – 1.0).
+   */
+  async setVolume(volume: number): Promise<void> {
+    if (volume < 0 || volume > 1) {throw new Error('Volume must be between 0 and 1');}
+    return checkModule().setVolume(volume);
+  },
+
+  async getVolume(): Promise<number> {
+    return checkModule().getVolume();
+  },
+
+  /**
+   * Set playback rate (1.0 = normal speed).
+   */
+  async setRate(rate: number): Promise<void> {
+    return checkModule().setRate(rate);
+  },
+
+  async getRate(): Promise<number> {
+    return checkModule().getRate();
+  },
+
+  async setRepeatMode(mode: RepeatMode): Promise<void> {
+    return checkModule().setRepeatMode(mode);
+  },
+
+  async getRepeatMode(): Promise<RepeatMode> {
+    const mode = await checkModule().getRepeatMode();
+    return mode as RepeatMode;
+  },
+
+  // ── Queue getters ──────────────────────────────────────────────────────────
+
+  async getQueue(): Promise<Track[]> {
+    const queue = await checkModule().getQueue();
+    return queue as Track[];
+  },
+
+  async getActiveTrackIndex(): Promise<number | null> {
+    const idx = await checkModule().getActiveTrackIndex();
+    // Native returns -1 as sentinel when no track is active
+    return (idx as number) < 0 ? null : (idx as number);
+  },
+
+  async getActiveTrack(): Promise<Track | null> {
+    const track = await checkModule().getActiveTrack();
+    return track as Track | null;
+  },
+
+  async getTrack(index: number): Promise<Track | null> {
+    const track = await checkModule().getTrack(index);
+    return track as Track | null;
+  },
+
+  async getQueueSize(): Promise<number> {
+    return checkModule().getQueueSize();
+  },
+
+  // ── State / progress ───────────────────────────────────────────────────────
+
+  async getPlaybackState(): Promise<PlaybackState> {
+    const state = await checkModule().getPlaybackState();
+    return state as PlaybackState;
+  },
+
+  async getProgress(): Promise<Progress> {
+    const progress = await checkModule().getProgress();
+    return progress as Progress;
+  },
+
+  // ── Metadata ───────────────────────────────────────────────────────────────
+
+  async updateMetadataForTrack(
+    index: number,
+    metadata: Partial<Track>
+  ): Promise<void> {
+    return checkModule().updateMetadataForTrack(index, metadata as Record<string, unknown>);
+  },
+
+  async clearNowPlayingMetadata(): Promise<void> {
+    return checkModule().clearNowPlayingMetadata();
+  },
+
+  async updateNowPlayingMetadata(metadata: Partial<Track>): Promise<void> {
+    return checkModule().updateNowPlayingMetadata(metadata as Record<string, unknown>);
+  },
+
+  // ── Options / notification ─────────────────────────────────────────────────
+
+  /**
+   * Configure notification capabilities, jump intervals, etc.
+   */
+  async updateOptions(options: UpdateOptions): Promise<void> {
+    return checkModule().updateOptions(options as Record<string, unknown>);
+  },
+
+  // ── Event subscription ─────────────────────────────────────────────────────
+
+  /**
+   * Subscribe to a player event.
+   * Returns an unsubscribe function — call it to remove the listener.
+   *
+   * @example
+   * const unsub = GliphPlayer.addEventListener(Event.PlaybackState, ({ state }) => {
+   *   console.log('State:', state);
+   * });
+   * // later:
+   * unsub();
+   */
+  addEventListener<E extends string>(
+    event: E,
+    listener: (data: any) => void
+  ): () => void {
+    const subscription = getEmitter().addListener(event, listener);
+    return () => subscription.remove();
+  },
+};
+
+export default GliphPlayer;
+
+// ─── Convenience state helpers ────────────────────────────────────────────────
+
+export function isPlaying(state: State): boolean {
+  return state === State.Playing;
+}
+
+export function isPaused(state: State): boolean {
+  return state === State.Paused;
+}
+
+export function isBuffering(state: State): boolean {
+  return state === State.Buffering || state === State.Loading;
+}
+
+export function isStopped(state: State): boolean {
+  return state === State.Stopped || state === State.None;
+}

package/src/hooks.ts

@@ -0,0 +1,256 @@
+/**
+ * hooks.ts — React hooks for react-native-gliph-player
+ */
+
+import { useEffect, useRef, useState, useCallback } from 'react';
+import GliphPlayer from './GliphPlayer';
+import { Event, State } from './types';
+import type {
+  Track,
+  Progress,
+  PlaybackState,
+  RepeatMode,
+  EventPayloadByEvent,
+} from './types';
+
+// ─── useTrackPlayerEvents ─────────────────────────────────────────────────────
+
+/**
+ * Subscribe to one or more player events inside a component.
+ * Automatically unsubscribes on unmount.
+ *
+ * @example
+ * useTrackPlayerEvents([Event.PlaybackState], ({ state }) => {
+ *   console.log(state);
+ * });
+ */
+export function useTrackPlayerEvents<E extends Event>(
+  events: E[],
+  handler: (payload: EventPayloadByEvent[E] & { type: E }) => void
+): void {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const unsubs = events.map((event) =>
+      GliphPlayer.addEventListener(event, (data: any) => {
+        handlerRef.current({ ...data, type: event });
+      })
+    );
+    return () => unsubs.forEach((u) => u());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, events);
+}
+
+// ─── usePlaybackState ─────────────────────────────────────────────────────────
+
+/**
+ * Returns the current playback state, updating reactively.
+ */
+export function usePlaybackState(): PlaybackState {
+  const [state, setState] = useState<PlaybackState>({ state: State.None });
+
+  useEffect(() => {
+    let mounted = true;
+
+    // Fetch initial state
+    GliphPlayer.getPlaybackState()
+      .then((s) => { if (mounted) {setState(s);} })
+      .catch(() => {});
+
+    const unsub = GliphPlayer.addEventListener(
+      Event.PlaybackState,
+      (data: { state: State }) => {
+        if (mounted) {setState({ state: data.state });}
+      }
+    );
+
+    return () => {
+      mounted = false;
+      unsub();
+    };
+  }, []);
+
+  return state;
+}
+
+// ─── useProgress ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns live playback progress (position, duration, buffered).
+ * @param updateInterval  How often to poll in ms. Defaults to 1000ms.
+ *                        Set to 0 to rely solely on native progress events.
+ */
+export function useProgress(updateInterval = 1000): Progress {
+  const [progress, setProgress] = useState<Progress>({
+    position: 0,
+    duration: 0,
+    buffered: 0,
+  });
+
+  useEffect(() => {
+    let mounted = true;
+    let timer: ReturnType<typeof setInterval> | null = null;
+
+    const update = () => {
+      GliphPlayer.getProgress()
+        .then((p) => { if (mounted) {setProgress(p);} })
+        .catch(() => {});
+    };
+
+    update();
+
+    if (updateInterval > 0) {
+      timer = setInterval(update, updateInterval);
+    }
+
+    // Also listen to native progress events for immediate updates
+    const unsub = GliphPlayer.addEventListener(
+      Event.PlaybackProgressUpdated,
+      (data: { position: number; duration: number; buffered: number }) => {
+        if (mounted) {
+          setProgress({
+            position: data.position,
+            duration: data.duration,
+            buffered: data.buffered,
+          });
+        }
+      }
+    );
+
+    return () => {
+      mounted = false;
+      if (timer) {clearInterval(timer);}
+      unsub();
+    };
+  }, [updateInterval]);
+
+  return progress;
+}
+
+// ─── useActiveTrack ───────────────────────────────────────────────────────────
+
+/**
+ * Returns the currently active track, updating when the track changes.
+ */
+export function useActiveTrack(): Track | null | undefined {
+  const [track, setTrack] = useState<Track | null | undefined>(undefined);
+
+  useEffect(() => {
+    let mounted = true;
+
+    GliphPlayer.getActiveTrack()
+      .then((t) => { if (mounted) {setTrack(t);} })
+      .catch(() => {});
+
+    const unsub = GliphPlayer.addEventListener(
+      Event.PlaybackActiveTrackChanged,
+      (data: { track: Track | null }) => {
+        if (mounted) {setTrack(data.track);}
+      }
+    );
+
+    return () => {
+      mounted = false;
+      unsub();
+    };
+  }, []);
+
+  return track;
+}
+
+// ─── useQueue ─────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the current queue, updating when tracks are added/removed/changed.
+ */
+export function useQueue(): Track[] {
+  const [queue, setQueue] = useState<Track[]>([]);
+
+  const refresh = useCallback(() => {
+    GliphPlayer.getQueue()
+      .then(setQueue)
+      .catch(() => {});
+  }, []);
+
+  useEffect(() => {
+    refresh();
+
+    // Re-fetch on any track change event
+    const unsub1 = GliphPlayer.addEventListener(Event.PlaybackActiveTrackChanged, refresh);
+    const unsub2 = GliphPlayer.addEventListener(Event.PlaybackQueueEnded, refresh);
+
+    return () => {
+      unsub1();
+      unsub2();
+    };
+  }, [refresh]);
+
+  return queue;
+}
+
+// ─── useRepeatMode ────────────────────────────────────────────────────────────
+
+/**
+ * Returns the current repeat mode and a setter.
+ */
+export function useRepeatMode(): [RepeatMode | null, (mode: RepeatMode) => Promise<void>] {
+  const [mode, setMode] = useState<RepeatMode | null>(null);
+
+  useEffect(() => {
+    GliphPlayer.getRepeatMode()
+      .then(setMode)
+      .catch(() => {});
+
+    const unsub = GliphPlayer.addEventListener(
+      Event.PlaybackRepeatModeChanged,
+      (data) => {
+        setMode(data.mode);
+      }
+    );
+
+    return () => unsub();
+  }, []);
+
+  const set = useCallback(async (newMode: RepeatMode) => {
+    await GliphPlayer.setRepeatMode(newMode);
+    setMode(newMode);
+  }, []);
+
+  return [mode, set];
+}
+
+// ─── useVolume ────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the current volume (0–1) and a setter.
+ */
+export function useVolume(): [number, (v: number) => Promise<void>] {
+  const [volume, setVolume] = useState(1);
+
+  useEffect(() => {
+    GliphPlayer.getVolume()
+      .then(setVolume)
+      .catch(() => {});
+  }, []);
+
+  const set = useCallback(async (v: number) => {
+    await GliphPlayer.setVolume(v);
+    setVolume(v);
+  }, []);
+
+  return [volume, set];
+}
+
+// ─── useIsPlaying ─────────────────────────────────────────────────────────────
+
+/**
+ * Convenience hook — returns { playing, bufferingDuringPlay }.
+ */
+export function useIsPlaying(): { playing: boolean; bufferingDuringPlay: boolean } {
+  const { state } = usePlaybackState();
+  return {
+    playing: state === State.Playing || state === State.Buffering,
+    bufferingDuringPlay: state === State.Buffering,
+  };
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * react-native-gliph-player
+ * Public API entry point
+ */
+
+// Default export — the player API
+export { default } from './GliphPlayer';
+export { default as GliphPlayer } from './GliphPlayer';
+export { isPlaying, isPaused, isBuffering, isStopped } from './GliphPlayer';
+
+// Types
+export type {
+  Track,
+  PlayerOptions,
+  UpdateOptions,
+  Progress,
+  PlaybackState,
+  PlaybackError,
+  CustomAction,
+  EventPayloadByEvent,
+  PlaybackStateEvent,
+  PlaybackErrorEvent,
+  PlaybackActiveTrackChangedEvent,
+  PlaybackQueueEndedEvent,
+  PlaybackProgressUpdatedEvent,
+  PlaybackMetadataReceivedEvent,
+  RemoteSeekEvent,
+  RemoteJumpForwardEvent,
+  RemoteJumpBackwardEvent,
+  RemoteSetRatingEvent,
+  RemoteDuckEvent,
+  RemoteSkipEvent,
+} from './types';
+
+// Enums
+export {
+  State,
+  Event,
+  RepeatMode,
+  Capability,
+  RatingType,
+  PitchAlgorithm,
+  IOSCategory,
+  IOSCategoryMode,
+  IOSCategoryOptions,
+  AndroidAudioContentType,
+  AndroidAudioUsage,
+  AppKilledPlaybackBehavior,
+} from './types';
+
+// Hooks
+export {
+  useTrackPlayerEvents,
+  usePlaybackState,
+  useProgress,
+  useActiveTrack,
+  useQueue,
+  useRepeatMode,
+  useVolume,
+  useIsPlaying,
+} from './hooks';