Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions components/FullPlayerModal.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -1671,10 +1671,18 @@ export const FullPlayerModal: React.FC<FullPlayerModalProps> = ({
setIsGeneratingAiMix(true);
try {
playHaptic(Haptic.ToggleOn);
// Dynamic import: aiMixPlaylist pulls storage + replay history, and the
// Dynamic import: aiMixGenerator pulls storage + replay history, and the
// player modal should not pay that cost until the user asks for a mix.
const { generateAiMixPlaylist } = await import("../modules/aiMixPlaylist");
const mix = await generateAiMixPlaylist(language === "fa" ? "fa" : "en");
// Discovery-first: LLM writes search queries, the app's own search
// resolves them, scoring stays deterministic. Any stage failing falls
// back to the on-device mix inside the generator — mix is null only
// when there is genuinely no history to work from.
const { generateAiMixWithDiscovery } = await import(
"../modules/aiMixGenerator"
);
const mix = await generateAiMixWithDiscovery(
language === "fa" ? "fa" : "en",
);
// null = not enough history to curate from. The icon stops spinning and
// the user is still looking at the player, so the alert carries the
// outcome — the same pattern the credits sheet already uses here.
Expand Down
283 changes: 283 additions & 0 deletions modules/aiMixGenerator.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,283 @@
/********************************************************************
* aiMixGenerator.ts — LLM-guided discovery mix (issue #49, discovery mode)
*
* The on-device mix (aiMixPlaylist.ts) only reshuffles what the user
* already has. This generator asks a keyless LLM for SEARCH QUERIES
* only — it never picks tracks. The queries run through the app's own
* search API, results are scored by the same buildSmartQueue weights,
* and a failure at any stage falls back to the on-device mix.
*
* Endpoint: Pollinations text API, OpenAI-compatible, anonymous.
* The free lane accepts no credentials — an API token in the request
* would be rejected, so none is ever attached.
*
* Privacy: the prompt carries artist/track NAMES only. No ids, no
* accounts, no play counts beyond rank order. Same tradeoff class as
* streaming the songs themselves.
******************************************************************/
import type { Track } from "../contexts/PlayerContext";
import { StorageService, type Playlist } from "../utils/storage";
import { loadReplaySummary } from "../utils/listeningStats";
import { searchAPI } from "./searchAPI";
import { buildSmartQueue, loadPlayCounts } from "./aiPlaylistService";
import {
generateAiMixPlaylist,
persistAiMix,
pickSeed,
} from "./aiMixPlaylist";

/**
* The keyless lane is rate-limited and returns HTTP 402 once an IP has used
* its anonymous quota. Try the canonical model id after the alias before
* giving up: an alias can be retired (404) while the id it points at lives on.
* Anonymous only — no credentials are ever attached.
*/
const ENDPOINTS = [
{ url: "https://text.pollinations.ai/openai", model: "openai" },
{ url: "https://text.pollinations.ai/openai", model: "openai-fast" },
];
const REQUEST_TIMEOUT_MS = 15000;
const MAX_QUERIES = 6;
const QUERIES_PER_REQUEST = 8;
const MIN_DISCOVERY_TRACKS = 8;
const SEARCH_LIMIT = 10;

/**
* The prompt carries names only — top artists and top tracks, ranked.
* Fenced to a JSON array so parsing is mechanical, not hopeful.
*/
export function buildHistoryPrompt(language: "en" | "fa"): string {
const ask =
language === "fa"
? "لطفا فقط یک آرایه JSON از رشته‌ها برگردان، بدون هیچ متن دیگری."
: "Reply with ONLY a JSON array of strings, no other text.";
return [
"You suggest music search queries.",
`Give me exactly ${QUERIES_PER_REQUEST} YouTube Music search queries for finding songs I have NOT heard yet but will like.`,
`Make them general discovery queries (genres, eras, moods, scenes) - do NOT include these exact artist or track names in the queries.`,
`Rules: 3-6 words each, in ${language === "fa" ? "Persian/Farsi" : "English"}.`,
ask,
].join("\n");
}

export function buildHistoryContext(
artists: string[],
tracks: string[],
language: "en" | "fa",
): string {
const head =
language === "fa"
? "من به این آهنگ‌ها گوش می‌دهم:"
: "These are what I listen to most:";
return [
head,
`Top artists: ${artists.slice(0, 10).join(", ")}`,
`Top tracks: ${tracks.slice(0, 15).join("; ")}`,
Comment on lines +74 to +75

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Listening history sent to third party

When the user taps the AI Mix button with listening history available, loadHistoryNames puts ranked artist and track names into the prompt, and fetchFrom posts it to Pollinations. The player tells the user only that an AI Mix is being generated, so they are not informed that personal listening preferences leave the device and are sent to an external service.

Disclose the third-party transfer and obtain informed opt-in before sending history names, or keep the history-based generation on-device.

Also at modules/aiMixGenerator.ts:128.

Prompt for AI agents
In `modules/aiMixGenerator.ts` at lines 74-75:

**Listening history sent to third party**

When the user taps the AI Mix button with listening history available, `loadHistoryNames` puts ranked artist and track names into the prompt, and `fetchFrom` posts it to Pollinations. The player tells the user only that an AI Mix is being generated, so they are not informed that personal listening preferences leave the device and are sent to an external service.

Disclose the third-party transfer and obtain informed opt-in before sending history names, or keep the history-based generation on-device.

Also at `modules/aiMixGenerator.ts:128`.

buildHistoryPrompt(language),
].join("\n");
}

/**
* Strict parser: finds the first JSON array of strings in model output,
* tolerates markdown fences and chatter around it. Anything else (an
* object, nested arrays, garbage) returns []. The caller treats [] as
* "LLM failed" and falls back — never as "empty playlist".
*/
export function parseQueryList(raw: unknown): string[] {
if (typeof raw !== "string") return [];
// Strip code fences first: they are the common wrapping, and their
// brackets would otherwise win the scan.
const unfenced = raw.replace(/```[a-z]*\n?/gi, "").replace(/```/g, "");
const match = unfenced.match(/\[[\s\S]*\]/);
if (!match) return [];
let parsed: unknown;
try {
parsed = JSON.parse(match[0]);
} catch {
return [];
}
if (!Array.isArray(parsed)) return [];
const out: string[] = [];
for (const item of parsed) {
if (typeof item !== "string") continue;
const clean = item.trim().slice(0, 80);
// A query must be words: reject JSON fragments that slipped through.
if (clean.length < 3 || !/[a-z\u0600-\u06FF]/i.test(clean)) continue;
out.push(clean);
if (out.length >= MAX_QUERIES) break;
}
return out;
}

/** One attempt against one endpoint. Returns [] on any failure. */
async function fetchFrom(
endpoint: { url: string; model: string },
prompt: string,
fetchImpl: typeof fetch,
): Promise<string[]> {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
try {
const res = await fetchImpl(endpoint.url, {
method: "POST",
headers: { "Content-Type": "application/json" },
// Anonymous is the free lane: no auth token of any kind.
body: JSON.stringify({
model: endpoint.model,
stream: false,
messages: [{ role: "user", content: prompt }],
}),
signal: controller.signal,
});
if (!res.ok) {
console.log(`[aiMix] ${endpoint.model} HTTP ${res.status}`);
return [];
}
const data = (await res.json()) as {
choices?: Array<{ message?: { content?: string } }>;
};
return parseQueryList(data?.choices?.[0]?.message?.content);
} catch (error) {
console.log(
`[aiMix] ${endpoint.model} failed:`,
error instanceof Error ? error.message : error,
);
return [];
} finally {
clearTimeout(timer);
}
}

/**
* Walk the keyless endpoint chain until one returns usable queries.
* The last resort is not here — it is the on-device mix, in the caller.
*/
export async function fetchSearchQueries(
prompt: string,
fetchImpl: typeof fetch = fetch,
): Promise<string[]> {
for (const endpoint of ENDPOINTS) {
const queries = await fetchFrom(endpoint, prompt, fetchImpl);
if (queries.length) return queries;
}
return [];
}

/** Load ranked artist/track names from local listening stats. */
async function loadHistoryNames(): Promise<{
artists: string[];
tracks: string[];
}> {
try {
const summary = await loadReplaySummary("alltime");
const artists = (summary.topArtists || [])
.map((a) => a.name)
.filter(Boolean);
const tracks = (summary.topTracks || [])
.map((t) => (t.artist ? `${t.title} — ${t.artist}` : t.title))
.filter(Boolean);
return { artists, tracks };
} catch {
return { artists: [], tracks: [] };
}
}

/** Run discovery queries through the app's own search. Dedupes by id. */
export async function resolveQueries(
queries: string[],
search: (query: string) => Promise<Track[]> = defaultSearch,
): Promise<Track[]> {
const seen = new Set<string>();
const found: Track[] = [];
for (const query of queries.slice(0, MAX_QUERIES)) {
let results: Track[] = [];
try {
results = await search(query);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · A hanging search stalls generation

When a search request remains pending instead of resolving or rejecting, resolveQueries awaits each search without a deadline, so it never reaches the remaining queries or on-device fallback and the generating indicator stays active indefinitely.

Give search requests a deadline so a stalled request can be skipped and generation can continue.

Prompt for AI agents
In `modules/aiMixGenerator.ts` at line 195:

**A hanging search stalls generation**

When a search request remains pending instead of resolving or rejecting, `resolveQueries` awaits each search without a deadline, so it never reaches the remaining queries or on-device fallback and the generating indicator stays active indefinitely.

Give search requests a deadline so a stalled request can be skipped and generation can continue.

} catch {
// one dead query source must not sink the batch
continue;
}
for (const t of results) {
if (!t?.id || !t.title || seen.has(String(t.id))) continue;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 High · Known tracks enter discovery mix

When a search query returns a track the user has liked or previously played, resolveQueries passes the track to buildSmartQueue, which excludes only the seed and can include the already-known track in the discovery mix.

Exclude liked and previously played track IDs from discovery candidates before scoring them.

Also at modules/aiMixGenerator.ts:258, modules/aiMixGenerator.ts:268-273.

Prompt for AI agents
In `modules/aiMixGenerator.ts` at line 201:

**Known tracks enter discovery mix**

When a search query returns a track the user has liked or previously played, `resolveQueries` passes the track to `buildSmartQueue`, which excludes only the seed and can include the already-known track in the discovery mix.

Exclude liked and previously played track IDs from discovery candidates before scoring them.

Also at `modules/aiMixGenerator.ts:258`, `modules/aiMixGenerator.ts:268-273`.

seen.add(String(t.id));
found.push(t);
}
}
return found;
}

/** Default resolver: YouTube Music via the existing search surface. */
async function defaultSearch(query: string): Promise<Track[]> {
const result = await searchAPI.searchWithYouTubeMusic(query, "all", 1, SEARCH_LIMIT);
const items = result?.items || [];
return items.map((item: any) => ({
id: String(item.id),
title: item.title || "",
artist: item.author || item.artist || "",
thumbnail: item.img || item.thumbnailUrl || item.thumbnail,
url: item.href,
source: "youtubemusic",
})) as Track[];
Comment on lines +210 to +220

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Discovery searches only one catalog

When a discovery track is available from another supported search catalog but not YouTube Music, defaultSearch calls only searchWithYouTubeMusic, so tracks from the other mixed-search providers never enter the candidate pool.

Use the app's mixed search providers to resolve discovery queries.

Prompt for AI agents
In `modules/aiMixGenerator.ts` at lines 210-220:

**Discovery searches only one catalog**

When a discovery track is available from another supported search catalog but not YouTube Music, `defaultSearch` calls only `searchWithYouTubeMusic`, so tracks from the other mixed-search providers never enter the candidate pool.

Use the app's mixed search providers to resolve discovery queries.

}

/**
* Discovery-first generator. Stages:
* 1. history names -> prompt -> LLM queries (fail => on-device)
* 2. queries -> search -> candidate pool (< MIN => on-device)
* 3. score with buildSmartQueue against seed (empty => on-device)
* 4. persist under the stable @ai_mix id
*/
export async function generateAiMixWithDiscovery(
language: "en" | "fa",
deps?: {
fetchImpl?: typeof fetch;
search?: (query: string) => Promise<Track[]>;
},
): Promise<Playlist | null> {
const [{ artists, tracks: trackNames }, liked, recent, playCounts] =
await Promise.all([
loadHistoryNames(),
StorageService.loadLikedSongs(),
StorageService.loadPreviouslyPlayedSongs(),
Comment on lines +240 to +241

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · History read failures look like no history

When reading liked songs or previously played songs fails while the user has history, StorageService returns empty arrays, so pickSeed returns null and generation reports an empty-history outcome instead of a read failure.

Propagate history read errors or distinguish them from valid empty lists before deciding there is no seed.

Also at modules/aiMixGenerator.ts:248.

Prompt for AI agents
In `modules/aiMixGenerator.ts` at lines 240-241:

**History read failures look like no history**

When reading liked songs or previously played songs fails while the user has history, `StorageService` returns empty arrays, so `pickSeed` returns `null` and generation reports an empty-history outcome instead of a read failure.

Propagate history read errors or distinguish them from valid empty lists before deciding there is no seed.

Also at `modules/aiMixGenerator.ts:248`.

loadPlayCounts(),
]);

const seed = await pickSeed(liked, recent);
if (!seed) {
// Same contract as the on-device path: honest null, no fake playlist.
return null;
}

const prompt = buildHistoryContext(artists, trackNames, language);
const queries = await fetchSearchQueries(prompt, deps?.fetchImpl);
if (!queries.length) {
console.log("[aiMix] no queries from LLM, falling back to on-device mix");
return generateAiMixPlaylist(language);
}

const candidates = await resolveQueries(queries, deps?.search);
if (candidates.length < MIN_DISCOVERY_TRACKS) {
console.log(
`[aiMix] only ${candidates.length} discovery tracks, falling back to on-device mix`,
);
return generateAiMixPlaylist(language);
}

// Seed scoring gives the discovery pool taste; new tracks have no play
// history, so playCounts only discriminates tracks the user already has.
const discovered = buildSmartQueue({
seed,
library: candidates,
size: 30,
playCounts,
});
Comment on lines +268 to +273

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Unrelated tracks enter discovery mix

When discovery queries return enough candidates with no meaningful artist or title overlap with the seed, buildSmartQueue gives every candidate a positive liked-track baseline, so unrelated search results remain eligible and can be included instead of triggering fallback.

Require meaningful similarity to the seed before accepting discovery candidates, and fall back when too few qualify.

Prompt for AI agents
In `modules/aiMixGenerator.ts` at lines 268-273:

**Unrelated tracks enter discovery mix**

When discovery queries return enough candidates with no meaningful artist or title overlap with the seed, `buildSmartQueue` gives every candidate a positive liked-track baseline, so unrelated search results remain eligible and can be included instead of triggering fallback.

Require meaningful similarity to the seed before accepting discovery candidates, and fall back when too few qualify.

if (discovered.length < MIN_DISCOVERY_TRACKS) {
console.log("[aiMix] scoring kept too little, falling back to on-device mix");
return generateAiMixPlaylist(language);
}

console.log(
`[aiMix] discovery: ${queries.length} queries -> ${candidates.length} candidates -> ${discovered.length} tracks`,
);
return persistAiMix(discovered, language);
}
61 changes: 36 additions & 25 deletions modules/aiMixPlaylist.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,39 @@ export const AI_MIX_ID = "@ai_mix";

const MIX_SIZE = 30;

/**
* Persist an already-built track list as the pinned AI Mix.
* Shared by the on-device generator and the discovery generator so
* both write through one write path and one stable id.
*/
export async function persistAiMix(
tracks: Track[],
language: "en" | "fa",
): Promise<Playlist> {
const now = new Date().toISOString();
// Read once, write once. addPlaylist re-reads the list internally, so
// going through it here would race another writer's change; and reading
// twice (once for `existing`, once for `rest`) lets the two disagree.
const stored = await StorageService.loadPlaylists();

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Critical · Existing playlists can be erased

When StorageService.loadPlaylists() encounters a read or parse error, persistAiMix treats the returned empty array as a successful read and saves only the AI Mix, overwriting the user's other playlists.

Distinguish a failed playlist read from a valid empty list and do not save a replacement after a failed read.

Prompt for AI agents
In `modules/aiMixPlaylist.ts` at line 23:

**Existing playlists can be erased**

When `StorageService.loadPlaylists()` encounters a read or parse error, `persistAiMix` treats the returned empty array as a successful read and saves only the AI Mix, overwriting the user's other playlists.

Distinguish a failed playlist read from a valid empty list and do not save a replacement after a failed read.

const existing = stored.find((p) => p.id === AI_MIX_ID);
const playlist: Playlist = {
id: AI_MIX_ID,
name: aiMixName(language),
description: language === "fa" ? "از تاریخچه پخش شما" : "Built from your listening history",
tracks,
createdAt: existing?.createdAt ?? now,
updatedAt: now,
// The top track's art doubles as the cover: a real image beats a
// placeholder glyph, and it changes as the mix does.
thumbnail: tracks[0]?.thumbnail,
};
// Replace in place, keep every other playlist, and put the mix first so
// it stays where the user expects it.
const rest = stored.filter((p) => p.id !== AI_MIX_ID);
await StorageService.savePlaylists([playlist, ...rest]);
Comment on lines +23 to +39

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 High · Concurrent playlist changes disappear

When another playlist writer or AI Mix generation saves between persistAiMix loading and saving the list, persistAiMix saves its earlier snapshot over the concurrent change, so the user's playlist edit or newer mix disappears.

Serialize playlist read-modify-write operations or use an atomic update that preserves concurrent changes.

Prompt for AI agents
In `modules/aiMixPlaylist.ts` at lines 23-39:

**Concurrent playlist changes disappear**

When another playlist writer or AI Mix generation saves between `persistAiMix` loading and saving the list, `persistAiMix` saves its earlier snapshot over the concurrent change, so the user's playlist edit or newer mix disappears.

Serialize playlist read-modify-write operations or use an atomic update that preserves concurrent changes.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Saved mix may not refresh the library

When the metadata-cache update fails after the playlist write succeeds, savePlaylists rejects after storing the mix but before updating the metadata cache and emitting the library event, so the library may not refresh and the player shows no result alert.

Keep the metadata cache and library event consistent when a playlist write succeeds, even if the cache update initially fails.

Also at components/FullPlayerModal.tsx:1693-1695.

Prompt for AI agents
In `modules/aiMixPlaylist.ts` at line 39:

**Saved mix may not refresh the library**

When the metadata-cache update fails after the playlist write succeeds, `savePlaylists` rejects after storing the mix but before updating the metadata cache and emitting the library event, so the library may not refresh and the player shows no result alert.

Keep the metadata cache and library event consistent when a playlist write succeeds, even if the cache update initially fails.

Also at `components/FullPlayerModal.tsx:1693-1695`.

return playlist;
}

/** Playlist name in both languages; the id is what the code keys on. */
export function aiMixName(language: "en" | "fa"): string {
return language === "fa" ? "میکس هوش مصنوعی" : "AI Mix";
Expand All @@ -16,7 +49,7 @@ export function aiMixName(language: "en" | "fa"): string {
* The seed: what the user actually listens to, not just what they liked.
* Falls back to the most recent track when nothing has been played yet.
*/
async function pickSeed(liked: Track[], recent: Track[]): Promise<Track | null> {
export async function pickSeed(liked: Track[], recent: Track[]): Promise<Track | null> {
if (recent.length) {
return recent[0];
}
Expand Down Expand Up @@ -79,27 +112,5 @@ export async function generateAiMixPlaylist(
return null;
}

const now = new Date().toISOString();
// Read once, write once. addPlaylist re-reads the list internally, so
// going through it here would race another writer's change; and reading
// twice (once for `existing`, once for `rest`) lets the two disagree.
const stored = await StorageService.loadPlaylists();
const existing = stored.find((p) => p.id === AI_MIX_ID);
const playlist: Playlist = {
id: AI_MIX_ID,
name: aiMixName(language),
description: language === "fa" ? "از تاریخچه پخش شما" : "Built from your listening history",
tracks,
createdAt: existing?.createdAt ?? now,
updatedAt: now,
// The top track's art doubles as the cover: a real image beats a
// placeholder glyph, and it changes as the mix does.
thumbnail: tracks[0]?.thumbnail,
};

// Replace in place, keep every other playlist, and put the mix first so
// it stays where the user expects it.
const rest = stored.filter((p) => p.id !== AI_MIX_ID);
await StorageService.savePlaylists([playlist, ...rest]);
return playlist;
}
return persistAiMix(tracks, language);
}
Loading
Loading