muzical-ui 0.1.1

package/lib/musicbrainz/search-musicbrainz-recordings.ts

@@ -0,0 +1,33 @@
+import { fetchMusicBrainzJson } from "@/lib/musicbrainz/fetch-musicbrainz-json";
+import { musicBrainzRecordingToTrack } from "@/lib/musicbrainz/musicbrainz-recording-to-track";
+import type { MusicBrainzSearchHints } from "@/lib/musicbrainz/build-musicbrainz-lucene-queries";
+import type { MusicBrainzRecording } from "@/lib/musicbrainz/types";
+import type { Track } from "@/types/track";
+
+/**
+ * Search MusicBrainz recordings with a Lucene query.
+ */
+export async function searchMusicBrainzRecordingsQuery(
+  luceneQuery: string,
+  hints: MusicBrainzSearchHints,
+  signal?: AbortSignal,
+  limit = 25,
+): Promise<Track[]> {
+  const trimmed = luceneQuery.trim();
+  if (!trimmed) return [];
+
+  const url = new URL("https://musicbrainz.org/ws/2/recording");
+  url.searchParams.set("query", trimmed);
+  url.searchParams.set("fmt", "json");
+  url.searchParams.set("limit", String(limit));
+  url.searchParams.set("inc", "artist-credits+releases");
+
+  const body = await fetchMusicBrainzJson<{
+    recordings?: MusicBrainzRecording[];
+  }>(url, signal);
+  const recordings = Array.isArray(body.recordings) ? body.recordings : [];
+
+  return recordings.map((recording) =>
+    musicBrainzRecordingToTrack(recording, hints),
+  );
+}

package/lib/musicbrainz/search-musicbrainz-release-groups.ts

@@ -0,0 +1,24 @@
+import { fetchMusicBrainzJson } from "@/lib/musicbrainz/fetch-musicbrainz-json";
+import type { MusicBrainzReleaseGroup } from "@/lib/musicbrainz/types";
+
+/**
+ * Search MusicBrainz release groups (albums, EPs, etc.).
+ */
+export async function searchMusicBrainzReleaseGroups(
+  query: string,
+  signal?: AbortSignal,
+  limit = 8,
+): Promise<MusicBrainzReleaseGroup[]> {
+  const trimmed = query.trim();
+  if (!trimmed) return [];
+
+  const url = new URL("https://musicbrainz.org/ws/2/release-group");
+  url.searchParams.set("query", trimmed);
+  url.searchParams.set("fmt", "json");
+  url.searchParams.set("limit", String(limit));
+
+  const body = await fetchMusicBrainzJson<{
+    "release-groups"?: MusicBrainzReleaseGroup[];
+  }>(url, signal);
+  return Array.isArray(body["release-groups"]) ? body["release-groups"] : [];
+}

package/lib/musicbrainz/search-musicbrainz.ts

@@ -0,0 +1,65 @@
+import { buildMusicBrainzLuceneQueries } from "@/lib/musicbrainz/build-musicbrainz-lucene-queries";
+import { fetchReleaseTracks } from "@/lib/musicbrainz/fetch-release-tracks";
+import { mergeTracksById } from "@/lib/musicbrainz/merge-tracks-by-id";
+import { pickReleaseGroupReleaseId } from "@/lib/musicbrainz/pick-release-group-release-id";
+import { releaseGroupArtistName } from "@/lib/musicbrainz/release-group-artist-name";
+import { searchMusicBrainzRecordingsQuery } from "@/lib/musicbrainz/search-musicbrainz-recordings";
+import { searchMusicBrainzReleaseGroups } from "@/lib/musicbrainz/search-musicbrainz-release-groups";
+import type { Track } from "@/types/track";
+
+const MAX_RECORDING_RESULTS = 40;
+const MAX_RELEASE_GROUP_EXPAND = 4;
+
+/**
+ * Search MusicBrainz across recordings and release groups; returns deduped tracks.
+ */
+export async function searchMusicBrainz(
+  query: string,
+  signal?: AbortSignal,
+): Promise<Track[]> {
+  const trimmed = query.trim();
+  if (!trimmed) return [];
+
+  const { queries, hints } = buildMusicBrainzLuceneQueries(trimmed);
+  const merged: Track[] = [];
+
+  for (const luceneQuery of queries) {
+    if (signal?.aborted) return merged;
+    const batch = await searchMusicBrainzRecordingsQuery(
+      luceneQuery,
+      hints,
+      signal,
+      25,
+    );
+    mergeTracksById(merged, batch);
+    if (merged.length >= MAX_RECORDING_RESULTS) break;
+  }
+
+  const groups = await searchMusicBrainzReleaseGroups(trimmed, signal, 10);
+  const albumHint = hints.album?.trim().toLowerCase() ?? "";
+  const prioritized = [...groups].sort((a, b) => {
+    if (!albumHint) return 0;
+    const aTitle = a.title?.trim().toLowerCase() ?? "";
+    const bTitle = b.title?.trim().toLowerCase() ?? "";
+    const aScore =
+      aTitle === albumHint ? 2 : aTitle.includes(albumHint) ? 1 : 0;
+    const bScore =
+      bTitle === albumHint ? 2 : bTitle.includes(albumHint) ? 1 : 0;
+    return bScore - aScore;
+  });
+
+  let expanded = 0;
+  for (const group of prioritized) {
+    if (signal?.aborted) break;
+    if (expanded >= MAX_RELEASE_GROUP_EXPAND) break;
+    const releaseId = pickReleaseGroupReleaseId(group);
+    if (!releaseId) continue;
+    const artist = releaseGroupArtistName(group);
+    const album = group.title?.trim() || "Unknown album";
+    const tracks = await fetchReleaseTracks(releaseId, album, artist, signal);
+    mergeTracksById(merged, tracks);
+    expanded += 1;
+  }
+
+  return merged;
+}

package/lib/musicbrainz/types.ts

@@ -0,0 +1,43 @@
+export type MusicBrainzArtistCredit = {
+  name?: string;
+  artist?: { name?: string };
+};
+
+export type MusicBrainzReleaseRef = {
+  id?: string;
+  title?: string;
+  status?: string;
+  "release-group"?: { title?: string };
+};
+
+export type MusicBrainzRecording = {
+  id: string;
+  title: string;
+  length?: number;
+  "artist-credit"?: MusicBrainzArtistCredit[];
+  releases?: MusicBrainzReleaseRef[];
+};
+
+export type MusicBrainzReleaseGroup = {
+  id: string;
+  title: string;
+  "first-release-date"?: string;
+  "artist-credit"?: MusicBrainzArtistCredit[];
+  releases?: Array<{ id: string; title?: string; status?: string }>;
+};
+
+export type MusicBrainzReleaseTrack = {
+  id: string;
+  title: string;
+  length?: number;
+  recording?: MusicBrainzRecording;
+};
+
+export type MusicBrainzReleaseDetail = {
+  id: string;
+  title: string;
+  "artist-credit"?: MusicBrainzArtistCredit[];
+  media?: Array<{
+    tracks?: MusicBrainzReleaseTrack[];
+  }>;
+};

package/lib/musicbrainz.ts

@@ -0,0 +1,3 @@
+export { searchMusicBrainz } from "@/lib/musicbrainz/search-musicbrainz";
+export { searchMusicBrainz as searchMusicBrainzRecordings } from "@/lib/musicbrainz/search-musicbrainz";
+export type { MusicBrainzRecording } from "@/lib/musicbrainz/types";

package/lib/playback/build-queue-from-snapshot.ts

@@ -0,0 +1,49 @@
+import type { PersistedPlaybackSnapshot } from "@/types/persisted-playback-snapshot";
+import type { QueuedTrack } from "@/types/queue";
+import type { Track } from "@/types/track";
+
+export type RestoredQueue = {
+  queue: QueuedTrack[];
+  activeQueueId: string | null;
+  positionSec: number;
+};
+
+/**
+ * Rebuilds a playback queue from a snapshot and the current library catalog.
+ */
+export default function buildQueueFromSnapshot(
+  libraryCatalog: readonly Track[],
+  snapshot: PersistedPlaybackSnapshot,
+): RestoredQueue {
+  const libraryById = new Map<string, Track>();
+  for (const t of libraryCatalog) libraryById.set(t.id, t);
+
+  const resolvedTracks: Track[] = [];
+  if (snapshot.tracks && snapshot.tracks.length > 0) {
+    for (const row of snapshot.tracks) {
+      resolvedTracks.push(libraryById.get(row.id) ?? row);
+    }
+  } else {
+    for (const trackId of snapshot.trackIds) {
+      const track = libraryById.get(trackId);
+      if (track) resolvedTracks.push(track);
+    }
+  }
+
+  const queue: QueuedTrack[] = resolvedTracks.map((track) => ({
+    queueId: crypto.randomUUID(),
+    track,
+  }));
+  let activeQueueId: string | null = null;
+  if (snapshot.activeTrackId) {
+    const row = queue.find((q) => q.track.id === snapshot.activeTrackId);
+    activeQueueId = row?.queueId ?? queue[0]?.queueId ?? null;
+  } else {
+    activeQueueId = queue[0]?.queueId ?? null;
+  }
+  return {
+    queue,
+    activeQueueId,
+    positionSec: snapshot.positionSec,
+  };
+}

package/lib/playback/parse-persisted-track.ts

@@ -0,0 +1,45 @@
+import type { LibraryTrackRef } from '@/types/track'
+import type { Track } from '@/types/track'
+
+function parseLibraryRef(value: unknown): LibraryTrackRef | undefined {
+  if (!value || typeof value !== 'object') return undefined
+  const o = value as Record<string, unknown>
+  if (typeof o.rootId !== 'string' || typeof o.relativePath !== 'string') return undefined
+  return { rootId: o.rootId, relativePath: o.relativePath }
+}
+
+/**
+ * Validates a track object loaded from a persisted playback snapshot.
+ */
+export default function parsePersistedTrack(value: unknown): Track | null {
+  if (!value || typeof value !== 'object') return null
+  const o = value as Record<string, unknown>
+  if (typeof o.id !== 'string' || !o.id.trim()) return null
+  if (typeof o.title !== 'string') return null
+  if (typeof o.artist !== 'string') return null
+  if (typeof o.album !== 'string') return null
+  const durationSec =
+    typeof o.durationSec === 'number' && Number.isFinite(o.durationSec) && o.durationSec >= 0
+      ? o.durationSec
+      : 0
+  const source =
+    o.source === 'library' || o.source === 'musicbrainz' || o.source === 'youtube'
+      ? o.source
+      : undefined
+  const audioUrl = typeof o.audioUrl === 'string' ? o.audioUrl : o.audioUrl === null ? null : undefined
+  const youtubeQuery = typeof o.youtubeQuery === 'string' ? o.youtubeQuery : undefined
+  const youtubeVideoId = typeof o.youtubeVideoId === 'string' ? o.youtubeVideoId : undefined
+  const library = parseLibraryRef(o.library)
+  return {
+    id: o.id.trim(),
+    title: o.title,
+    artist: o.artist,
+    album: o.album,
+    durationSec,
+    audioUrl,
+    youtubeQuery,
+    youtubeVideoId,
+    source,
+    library,
+  }
+}

package/lib/playback/read-stored-playback-snapshot.ts

@@ -0,0 +1,45 @@
+import parsePersistedTrack from "@/lib/playback/parse-persisted-track";
+import type { PersistedPlaybackSnapshot } from "@/types/persisted-playback-snapshot";
+import type { Track } from "@/types/track";
+
+const STORAGE_KEY = "muzical.playbackSnapshot";
+
+/**
+ * Loads the last saved queue / playhead snapshot from localStorage.
+ */
+export default function readStoredPlaybackSnapshot(): PersistedPlaybackSnapshot | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return null;
+    const o = parsed as Record<string, unknown>;
+    if (!Array.isArray(o.trackIds)) return null;
+    const trackIds = o.trackIds.filter(
+      (x): x is string => typeof x === "string" && x.length > 0,
+    );
+    let tracks: Track[] | undefined;
+    if (Array.isArray(o.tracks)) {
+      const list: Track[] = [];
+      for (const item of o.tracks) {
+        const row = parsePersistedTrack(item);
+        if (row) list.push(row);
+      }
+      if (list.length > 0) tracks = list;
+    }
+    const activeTrackId =
+      typeof o.activeTrackId === "string" ? o.activeTrackId : null;
+    const positionSec =
+      typeof o.positionSec === "number" &&
+      Number.isFinite(o.positionSec) &&
+      o.positionSec >= 0
+        ? o.positionSec
+        : 0;
+    return { trackIds, tracks, activeTrackId, positionSec };
+  } catch {
+    return null;
+  }
+}
+
+export { STORAGE_KEY as PLAYBACK_SNAPSHOT_STORAGE_KEY };

package/lib/playback/write-stored-playback-snapshot.ts

@@ -0,0 +1,19 @@
+import { PLAYBACK_SNAPSHOT_STORAGE_KEY } from "@/lib/playback/read-stored-playback-snapshot";
+import type { PersistedPlaybackSnapshot } from "@/types/persisted-playback-snapshot";
+
+/**
+ * Persists queue / playhead snapshot to localStorage.
+ */
+export default function writeStoredPlaybackSnapshot(
+  snapshot: PersistedPlaybackSnapshot,
+): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(
+      PLAYBACK_SNAPSHOT_STORAGE_KEY,
+      JSON.stringify(snapshot),
+    );
+  } catch {
+    /* ignore */
+  }
+}

package/lib/theme-constants.ts

@@ -0,0 +1,4 @@
+/** localStorage key for persisted color scheme */
+export const THEME_STORAGE_KEY = "muzical-theme" as const;
+
+export type ColorScheme = "light" | "dark";

package/lib/theme-init-script.ts

@@ -0,0 +1,9 @@
+import { THEME_STORAGE_KEY } from "@/lib/theme-constants";
+
+/**
+ * Runs before paint so the first frame matches stored theme (default light).
+ */
+export function getThemeInitScript(): string {
+  const k = JSON.stringify(THEME_STORAGE_KEY);
+  return `(function(){try{var s=localStorage.getItem(${k});document.documentElement.classList.toggle('dark',s==='dark');}catch(e){}})();`;
+}

package/lib/youtube/clear-youtube-data-api-blocked.ts

@@ -0,0 +1,8 @@
+import { setYoutubeDataApiBlockedInternal } from '@/lib/youtube/read-youtube-data-api-blocked'
+
+/**
+ * Re-enables YouTube Data API v3 lookups (e.g. after saving a new API key).
+ */
+export default function clearYoutubeDataApiBlocked(): void {
+  setYoutubeDataApiBlockedInternal(false)
+}

package/lib/youtube/collect-youtube-prefetch-targets.ts

@@ -0,0 +1,20 @@
+import type { Track } from '@/types/track'
+import type { YoutubePrefetchTarget } from '@/lib/youtube/prefetch-youtube-video-ids'
+
+/**
+ * Builds deduped prefetch targets from tracks missing a YouTube video id.
+ */
+export default function collectYoutubePrefetchTargets(
+  tracks: readonly Track[],
+): YoutubePrefetchTarget[] {
+  const seen = new Set<string>()
+  const out: YoutubePrefetchTarget[] = []
+  for (const track of tracks) {
+    const query = track.youtubeQuery?.trim()
+    if (!query || track.youtubeVideoId?.trim()) continue
+    if (seen.has(track.id)) continue
+    seen.add(track.id)
+    out.push({ trackId: track.id, query })
+  }
+  return out
+}

package/lib/youtube/is-youtube-quota-error-message.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns true when a YouTube Data API error message indicates quota exhaustion.
+ */
+export default function isYoutubeQuotaErrorMessage(message: string): boolean {
+  const m = message.toLowerCase()
+  return m.includes('quota') || m.includes('quotaexceeded')
+}

package/lib/youtube/mark-youtube-data-api-blocked.ts

@@ -0,0 +1,8 @@
+import { setYoutubeDataApiBlockedInternal } from '@/lib/youtube/read-youtube-data-api-blocked'
+
+/**
+ * Disables further YouTube Data API v3 search requests for this session.
+ */
+export default function markYoutubeDataApiBlocked(): void {
+  setYoutubeDataApiBlockedInternal(true)
+}

package/lib/youtube/prefetch-youtube-video-ids.ts

@@ -0,0 +1,55 @@
+import readYoutubeDataApiBlocked from '@/lib/youtube/read-youtube-data-api-blocked'
+import searchYoutubeVideoId from '@/lib/youtube/search-youtube-video-id'
+
+export type YoutubePrefetchTarget = {
+  trackId: string
+  query: string
+}
+
+type PrefetchYoutubeVideoIdsOptions = {
+  signal?: AbortSignal
+  maxConcurrent?: number
+}
+
+/**
+ * Resolves YouTube video ids for many tracks concurrently (Data API v3).
+ */
+export default async function prefetchYoutubeVideoIds(
+  targets: readonly YoutubePrefetchTarget[],
+  apiKey: string,
+  onResolved: (trackId: string, videoId: string) => void,
+  options: PrefetchYoutubeVideoIdsOptions = {},
+): Promise<void> {
+  const key = apiKey.trim()
+  if (!key || targets.length === 0 || readYoutubeDataApiBlocked()) return
+
+  const maxConcurrent =
+    typeof options.maxConcurrent === 'number' && options.maxConcurrent > 0
+      ? Math.floor(options.maxConcurrent)
+      : 3
+  const signal = options.signal
+  let index = 0
+
+  const worker = async (): Promise<void> => {
+    while (index < targets.length) {
+      if (signal?.aborted) return
+      const i = index
+      index += 1
+      const target = targets[i]
+      if (readYoutubeDataApiBlocked()) return
+      let videoId: string | null = null
+      try {
+        videoId = await searchYoutubeVideoId(target.query, key, signal)
+      } catch {
+        continue
+      }
+      if (signal?.aborted || readYoutubeDataApiBlocked() || !videoId) continue
+      onResolved(target.trackId, videoId)
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(maxConcurrent, targets.length) }, () =>
+    worker(),
+  )
+  await Promise.all(workers)
+}

package/lib/youtube/read-stored-youtube-api-key.ts

@@ -0,0 +1,16 @@
+const STORAGE_KEY = 'muzical.youtubeApiKey'
+
+/**
+ * Loads the YouTube Data API key from localStorage.
+ */
+export default function readStoredYoutubeApiKey(): string {
+  if (typeof window === 'undefined') return ''
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY)
+    return typeof raw === 'string' ? raw.trim() : ''
+  } catch {
+    return ''
+  }
+}
+
+export { STORAGE_KEY as YOUTUBE_API_KEY_STORAGE_KEY }

package/lib/youtube/read-youtube-data-api-blocked.ts

@@ -0,0 +1,12 @@
+let blocked = false
+
+/**
+ * Whether Data API v3 lookups are disabled (e.g. after quota exhaustion).
+ */
+export default function readYoutubeDataApiBlocked(): boolean {
+  return blocked
+}
+
+export function setYoutubeDataApiBlockedInternal(next: boolean): void {
+  blocked = next
+}

package/lib/youtube/search-youtube-video-id.ts

@@ -0,0 +1,60 @@
+import isYoutubeQuotaErrorMessage from '@/lib/youtube/is-youtube-quota-error-message'
+import markYoutubeDataApiBlocked from '@/lib/youtube/mark-youtube-data-api-blocked'
+import readYoutubeDataApiBlocked from '@/lib/youtube/read-youtube-data-api-blocked'
+
+type YoutubeSearchResponse = {
+  items?: Array<{
+    id?: { videoId?: string }
+  }>
+  error?: { message?: string; errors?: Array<{ reason?: string }> }
+}
+
+const videoIdCache = new Map<string, string>()
+
+/**
+ * Resolves a YouTube video id for a search query via YouTube Data API v3.
+ */
+export default async function searchYoutubeVideoId(
+  query: string,
+  apiKey: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  const q = query.trim()
+  const key = apiKey.trim()
+  if (!q || !key) return null
+  if (readYoutubeDataApiBlocked()) return null
+
+  const cacheKey = q.toLowerCase()
+  const cached = videoIdCache.get(cacheKey)
+  if (cached) return cached
+
+  const url = new URL('https://www.googleapis.com/youtube/v3/search')
+  url.searchParams.set('part', 'snippet')
+  url.searchParams.set('type', 'video')
+  url.searchParams.set('maxResults', '5')
+  url.searchParams.set('videoEmbeddable', 'true')
+  url.searchParams.set('q', q)
+  url.searchParams.set('key', key)
+
+  const response = await fetch(url, { signal })
+  const body = (await response.json()) as YoutubeSearchResponse
+  if (!response.ok) {
+    const message = body.error?.message?.trim() ?? ''
+    const quotaReason = body.error?.errors?.some((e) => e.reason === 'quotaExceeded') ?? false
+    if (quotaReason || isYoutubeQuotaErrorMessage(message)) {
+      markYoutubeDataApiBlocked()
+      return null
+    }
+    return null
+  }
+
+  for (const item of body.items ?? []) {
+    const id = item.id?.videoId?.trim()
+    if (id) {
+      videoIdCache.set(cacheKey, id)
+      return id
+    }
+  }
+
+  return null
+}

package/lib/youtube/should-use-youtube-search-playback.ts

@@ -0,0 +1,19 @@
+import readYoutubeDataApiBlocked from '@/lib/youtube/read-youtube-data-api-blocked'
+
+/**
+ * True when playback should use the iframe search playlist instead of a resolved video id.
+ */
+export default function shouldUseYoutubeSearchPlayback(
+  youtubeQuery: string | undefined,
+  youtubeVideoId: string | undefined,
+  hasApiKey: boolean,
+  forceSearchFallback: boolean,
+): boolean {
+  const query = youtubeQuery?.trim()
+  if (!query) return false
+  if (youtubeVideoId?.trim()) return false
+  if (forceSearchFallback) return true
+  if (readYoutubeDataApiBlocked()) return true
+  if (!hasApiKey) return true
+  return false
+}

package/lib/youtube/write-stored-youtube-api-key.ts

@@ -0,0 +1,18 @@
+import { YOUTUBE_API_KEY_STORAGE_KEY } from '@/lib/youtube/read-stored-youtube-api-key'
+
+/**
+ * Persists the YouTube Data API key to localStorage.
+ */
+export default function writeStoredYoutubeApiKey(apiKey: string): void {
+  if (typeof window === 'undefined') return
+  try {
+    const trimmed = apiKey.trim()
+    if (trimmed) {
+      window.localStorage.setItem(YOUTUBE_API_KEY_STORAGE_KEY, trimmed)
+    } else {
+      window.localStorage.removeItem(YOUTUBE_API_KEY_STORAGE_KEY)
+    }
+  } catch {
+    /* ignore */
+  }
+}

package/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;