recommend_for_mood

Recommend new songs that match how the listener actually feels right now.

Unlike recommend_from_song, the mood decides where candidates come from: seeds are drawn from the listener's OWN library nearest the target mood, then expanded through radio/related/artist signals and songs from YouTube's mood playlists. Results are still guaranteed absent from their library.

Describing the mood -- in priority order: vector The precise path, and the one to prefer. A dict with valence (-1..1, despairing->euphoric), energy (0..1, still->frantic), tension (0..1, resolved->anxious; this is what separates angry from excited) and depth (0..1, background ->lyric-forward). YOU should read the user's words and set these -- you understand "wistful but still wants to get things done" far better than any keyword list. feeling Their words verbatim, as a fallback when you'd rather not commit to numbers. Matched against a mood-word lexicon. context One of: Chill, Sleep, Focus, Commute, Feel good, Romance, Energize, Workout, Party, Gaming, Sad. If none are given, the mood is inferred from recent listening history.

arc shapes the sequence rather than returning a flat mood-matched set: mirror stay where they are and validate it (default) lift start where they are, rise gradually -- never jump straight to upbeat when someone is low, it reads as being told to cheer up settle descend to calm; an evening wind-down deepen go further in; sometimes you want to sit in it properly hold stay in a band with energy as a curve (workout: warmup/peak/cooldown)

genres optionally restricts the seeds to the listener's own genre playlists, e.g. ["Punjabi", "Hip-Hop & Rap"].

language / exclude_languages filter the RESULTS, e.g. language=["english"]. Strict by default: a candidate with no language label is dropped, because someone asking for English only wants a guarantee. The response says how many were dropped and why; pass allow_unlabelled_language=True to keep them.

bpm biases ranking toward a tempo (half- and double-time count as close). bpm_min/bpm_max bound it instead. Songs with no known BPM are KEPT and simply not scored on tempo -- Deezer has no tempo for much of the non-English catalogue, so dropping them would delete whole languages.

limit is a ceiling, not a guarantee. If fewer than limit songs genuinely fit the mood (rated, with a real fit -- not just an unrated placeholder score), the shortfall is NOT padded with weak filler to hit the number. Filler is capped at 25% of limit: asking for 100 with 7 genuine matches returns 32 (7 + 25), not 100. See match_quality in the result for the genuine/filler breakdown, and notes for the human-readable version.

If they also point at a specific playlist ("look at this playlist and recommend me songs for how I feel"), use recommend_from_playlist_for_mood instead -- it seeds from that playlist's own fitting tracks rather than from the whole library.

This is READ-ONLY. If they asked for a PLAYLIST rather than a list, this tool is step one of three: get the songs here, create the playlist from the returned videoIds with a playlist-management tool, then call refresh_library() so those tracks are excluded from later recommendations.

The result carries target (the mood aimed at), target_origin (where it came from), seeds (which of their songs it grew from), notes (caveats worth repeating to the user), match_quality (genuine vs. filler counts) and songs, each with its slot, mood fit and which signals surfaced it.