Coverage for downtify/navidrome.py: 73%
813 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""Navidrome integration via the Subsonic API (playlist sync)."""
3from __future__ import annotations
5import hashlib
6import re
7import secrets
8import threading
9import time
10import unicodedata
11from dataclasses import dataclass
12from pathlib import Path
13from typing import Any, Optional
14from urllib.parse import urlencode
16import httpx
17from loguru import logger
19from .library_delete import (
20 TagMismatchDeleteContext,
21 delete_if_spotify_tag_mismatch,
22)
23from .library_metadata import read_audio_metadata
24from .library_paths import locate_library_file
25from .navidrome_index import NavidromeIndex
26from .playlist_identity import made_by_downtify, playlist_key
27from .track_index import normalize_spotify_track_id
28from .track_tag_match import (
29 snapshot_spotify_metadata,
30 spotify_aligns_with_file_tags,
31 spotify_file_tag_mismatch_label,
32)
34# Subsonic createPlaylist via GET appends every songId to the query string; large
35# playlists hit HTTP 414. POST form bodies avoid that; we still batch adds.
36_PLAYLIST_SONG_ID_BATCH = 80
38#: Subsonic error code for a wrong username or password.
39SUBSONIC_AUTH_FAILED = 40
42class SubsonicError(ValueError):
43 """A ``status: failed`` Subsonic reply, with the server's error code.
45 A ``ValueError`` like before, so existing callers catch it unchanged;
46 the code is what tells "wrong password" (40) from any other refusal.
47 """
49 def __init__(self, message: str, code: int = 0) -> None:
50 super().__init__(message)
51 self.code = code
54def _song_id_batches(
55 song_ids: list[str], batch_size: int = _PLAYLIST_SONG_ID_BATCH
56) -> list[list[str]]:
57 batches: list[list[str]] = []
58 for index in range(0, len(song_ids), batch_size):
59 batches.append(song_ids[index : index + batch_size])
60 return batches
63def _parse_subsonic_http_response(resp: httpx.Response) -> dict[str, Any]:
64 resp.raise_for_status()
65 data = resp.json()
66 body = data.get('subsonic-response') if isinstance(data, dict) else None
67 if not isinstance(body, dict):
68 raise ValueError('Invalid Subsonic response')
69 if body.get('status') == 'failed':
70 err = body.get('error') or {}
71 message = err.get('message') if isinstance(err, dict) else str(err)
72 raise ValueError(str(message or 'Subsonic request failed'))
73 return body
76def _playlist_id_from_body(
77 body: dict[str, Any], fallback: Optional[str] = None
78) -> str:
79 playlist = body.get('playlist')
80 if isinstance(playlist, dict):
81 pid = str(playlist.get('id') or '').strip()
82 if pid:
83 return pid
84 if fallback:
85 return fallback
86 raise ValueError('createPlaylist returned no playlist id')
89@dataclass
90class PlaylistSyncResult:
91 playlist_id: str
92 playlist_name: str
93 matched: int
94 total: int
95 scanned: bool
96 scan_complete: bool = False
99def _search_title(title: str) -> str:
100 """Title used for Navidrome search (strip feat. suffixes, keep remix names)."""
102 text = str(title or '').strip()
103 lowered = text.casefold()
104 for marker in (' - feat.', ' (feat.', ' - ft.', ' (ft.', ' - featuring '):
105 idx = lowered.find(marker)
106 if idx > 0:
107 return text[:idx].strip()
108 return text
111def _normalize_path_text(path: str) -> str:
112 return unicodedata.normalize('NFC', str(path or '').replace('\\', '/'))
115def _path_match_keys(filename: str) -> list[str]:
116 """Path fragments for matching Navidrome ``path`` (any library root prefix)."""
118 text = _normalize_path_text(filename).casefold().strip()
119 if not text:
120 return []
121 keys: list[str] = [text]
122 parts = [part for part in text.split('/') if part]
123 if len(parts) >= 2:
124 tail = '/'.join(parts[-2:])
125 if tail not in keys:
126 keys.append(tail)
127 base = text.rsplit('/', 1)[-1]
128 if base and base not in keys:
129 keys.append(base)
130 if text.startswith('slskd/'):
131 without_slskd = text[len('slskd/') :]
132 if without_slskd not in keys:
133 keys.append(without_slskd)
134 return keys
137def _navidrome_path_basename(path: str) -> str:
138 return str(path or '').replace('\\', '/').casefold().rsplit('/', 1)[-1]
141def _normalize_filename_key(name: str) -> str:
142 text = str(name or '').casefold().replace('&', ' and ')
143 text = re.sub(r'[^\w\s.-]', '', text)
144 return re.sub(r'\s+', ' ', text).strip()
147def _loosen_search_query(text: str) -> str:
148 """Strip punctuation so Navidrome full-text search finds filename-like rows."""
150 lowered = _normalize_path_text(text).casefold().replace('&', ' and ')
151 cleaned = re.sub(r'[^\w\s-]', ' ', lowered)
152 return re.sub(r'\s+', ' ', cleaned).strip()
155def _queries_from_filename_stem(stem: str) -> list[str]:
156 text = str(stem or '').strip()
157 if not text:
158 return []
159 out: list[str] = []
160 if ' - ' in text:
161 artists_part, title_part = text.rsplit(' - ', 1)
162 artists_part = artists_part.strip()
163 title_part = title_part.strip()
164 if title_part:
165 out.append(title_part)
166 if artists_part:
167 out.append(artists_part)
168 lead = artists_part.split(',')[0].strip()
169 if lead and title_part:
170 out.append(f'{title_part} {lead}')
171 out.append(f'{lead} {title_part}')
172 loosened = _loosen_search_query(text)
173 if loosened and loosened not in out:
174 out.append(loosened)
175 return out
178def _basename_aligned(stored: str, indexed: str) -> bool:
179 if stored == indexed:
180 return True
181 left = _normalize_filename_key(stored)
182 right = _normalize_filename_key(indexed)
183 if not left or not right:
184 return False
185 if left == right:
186 return True
187 if (
188 len(left) >= 12
189 and len(right) >= 12
190 and (left in right or right in left)
191 ):
192 return True
193 return False
196def _path_matches(path_keys: list[str], navidrome_path: str) -> bool:
197 """True when Downtify's stored path lines up with Navidrome's indexed path."""
199 c_path = _normalize_path_text(navidrome_path).casefold()
200 if not path_keys or not c_path:
201 return False
202 c_base = _navidrome_path_basename(c_path)
203 for key in path_keys:
204 if not key:
205 continue
206 if c_path == key or c_path.endswith(f'/{key}'):
207 return True
208 if key in c_path:
209 return True
210 key_base = key.rsplit('/', 1)[-1]
211 if key_base and _basename_aligned(key_base, c_base):
212 return True
213 return False
216def _library_tags(song: dict[str, Any]) -> tuple[str, list[str]]:
217 title = str(song.get('name') or '').strip()
218 artists = [str(a) for a in (song.get('artists') or []) if str(a).strip()]
219 return title, artists
222def _normalize_tag(text: str) -> str:
223 return unicodedata.normalize('NFC', str(text or '').strip()).casefold()
226def _title_matches_with_navidrome_suffix(
227 title: str, candidate_title: str
228) -> bool:
229 """Match titles when Navidrome appends a media source label."""
231 expected = _normalize_tag(title)
232 candidate = _normalize_tag(candidate_title)
233 if expected == candidate:
234 return True
235 if not expected or not candidate.startswith(f'{expected} ('):
236 return False
237 suffix = candidate[len(expected) + 2 :].strip()
238 if not suffix.endswith(')'):
239 return False
240 suffix = suffix[:-1].strip()
241 return suffix == 'pmedia' or bool(re.fullmatch(r'\[\d+\]\s*pl', suffix))
244def _duration_close(
245 target_duration: int, candidate_duration: int, *, slack: int = 12
246) -> bool:
247 if not target_duration or not candidate_duration:
248 return True
249 return abs(target_duration - candidate_duration) <= slack
252def _exact_tag_match(
253 song: dict[str, Any],
254 candidate: dict[str, Any],
255 target_duration: int,
256) -> bool:
257 """Match Navidrome row to on-disk ID3/Vorbis tags (exact title + artist)."""
259 title, artists = _library_tags(song)
260 if not title:
261 return False
262 c_title = str(candidate.get('title') or '').strip()
263 c_artist = str(candidate.get('artist') or '').strip()
264 if _normalize_tag(title) != _normalize_tag(c_title):
265 return False
266 if not artists:
267 return True
268 c_artist_n = _normalize_tag(c_artist)
269 joined = _normalize_tag(', '.join(artists))
270 if joined == c_artist_n:
271 return True
272 if any(_normalize_tag(artist) in c_artist_n for artist in artists):
273 return True
274 return False
277_PRIMARY_SEARCH_COUNT = 40
278_FALLBACK_SEARCH_COUNT = 80
279_MAX_FALLBACK_QUERIES = 4
282def _search_query_phases(
283 song: dict[str, Any], path_keys: list[str]
284) -> tuple[list[str], list[str]]:
285 """Primary tag/metadata queries, then a short filename fallback list."""
287 title, artists = _library_tags(song)
288 search_title = _search_title(title)
289 artist = artists[0] if artists else ''
290 tagged = bool(song.get('library_from_tags'))
291 primary: list[str] = []
292 fallback: list[str] = []
294 def add_primary(query: str) -> None:
295 text = str(query or '').strip()
296 if text and text not in primary:
297 primary.append(text)
299 def add_fallback(query: str) -> None:
300 text = str(query or '').strip()
301 if text and text not in fallback and text not in primary:
302 fallback.append(text)
304 if tagged and title:
305 if artist:
306 add_primary(f'{artist} {title}')
307 add_primary(f'{title} {artist}')
308 else:
309 add_primary(title)
310 if len(artists) > 1:
311 add_primary(f'{title} {", ".join(artists)}')
312 else:
313 add_primary(f'{search_title} {artist}'.strip())
314 if len(artists) > 1:
315 add_primary(f'{search_title} {", ".join(artists[:3])}'.strip())
317 if path_keys:
318 basename = path_keys[0].rsplit('/', 1)[-1]
319 stem = basename.rsplit('.', 1)[0] if basename else ''
320 loosened = _loosen_search_query(stem) if stem else ''
321 if loosened:
322 add_fallback(loosened)
323 if stem:
324 add_fallback(stem)
325 if basename:
326 add_fallback(basename)
327 add_fallback(path_keys[0])
328 return primary, fallback[:_MAX_FALLBACK_QUERIES]
331def _pick_song_id_from_candidates(
332 songs: list[dict[str, Any]],
333 song: dict[str, Any],
334 path_keys: list[str],
335 target_duration: int,
336) -> Optional[str]:
337 title, artists = _library_tags(song)
338 search_title = _search_title(title)
339 artist = artists[0] if artists else ''
340 require_artist = bool(path_keys)
341 use_exact_tags = bool(song.get('library_from_tags') and title)
343 for candidate in songs:
344 if not isinstance(candidate, dict):
345 continue
346 cid = str(candidate.get('id') or '').strip()
347 if not cid:
348 continue
349 c_path = str(candidate.get('path') or '')
350 if path_keys and _path_matches(path_keys, c_path):
351 return cid
353 if use_exact_tags:
354 for candidate in songs:
355 if not isinstance(candidate, dict):
356 continue
357 cid = str(candidate.get('id') or '').strip()
358 if cid and _exact_tag_match(song, candidate, target_duration):
359 return cid
361 for candidate in songs:
362 if not isinstance(candidate, dict):
363 continue
364 cid = str(candidate.get('id') or '').strip()
365 if not cid:
366 continue
367 c_artist = str(candidate.get('artist') or '')
368 c_title = str(candidate.get('title') or '')
369 c_duration = int(candidate.get('duration') or 0)
371 artist_match = artist and artist.casefold() in c_artist.casefold()
372 title_match = _title_matches_with_navidrome_suffix(
373 search_title, c_title
374 ) or _title_matches_with_navidrome_suffix(title, c_title)
375 duration_match = _duration_close(target_duration, c_duration, slack=10)
377 if artist_match and title_match and duration_match:
378 return cid
379 if not require_artist and title_match and duration_match:
380 return cid
381 return None
384def _effective_navidrome_settings(settings: dict[str, Any]) -> dict[str, Any]:
385 raw = settings.get('navidrome')
386 if not isinstance(raw, dict):
387 raw = {}
388 url = str(raw.get('url') or '').strip().rstrip('/')
389 username = str(raw.get('username') or '').strip()
390 password = str(raw.get('password') or '')
391 admin_username = str(raw.get('admin_username') or '').strip()
392 admin_password = str(raw.get('admin_password') or '')
393 try:
394 scan_wait_seconds = int(raw.get('scan_wait_seconds') or 120)
395 except (TypeError, ValueError):
396 scan_wait_seconds = 120
397 scan_wait_seconds = min(600, max(10, scan_wait_seconds))
398 try:
399 scan_poll_seconds = int(raw.get('scan_poll_seconds') or 5)
400 except (TypeError, ValueError):
401 scan_poll_seconds = 5
402 scan_poll_seconds = min(120, max(2, scan_poll_seconds))
403 try:
404 scan_retry_seconds = int(raw.get('scan_retry_seconds') or 15)
405 except (TypeError, ValueError):
406 scan_retry_seconds = 15
407 scan_retry_seconds = min(120, max(0, scan_retry_seconds))
408 return {
409 'enabled': bool(raw.get('enabled', False)),
410 'url': url,
411 'username': username,
412 'password': password,
413 'admin_username': admin_username,
414 'admin_password': admin_password,
415 'public_playlist': bool(raw.get('public_playlist', False)),
416 # Navidrome imports the M3U Downtify writes (with its cover) as a
417 # playlist of its own; with this on, Downtify doesn't create a
418 # second one through the API (see sync_playlist_to_navidrome).
419 'm3u_import': bool(raw.get('m3u_import', False)),
420 'scan_after_download': bool(raw.get('scan_after_download', True)),
421 'scan_full': bool(raw.get('scan_full', False)),
422 # Hold the scans Downtify starts while a Navidrome client is
423 # playing (see _trigger_library_scan / IdleScan).
424 'scan_when_idle': bool(raw.get('scan_when_idle', False)),
425 'scan_wait_seconds': scan_wait_seconds,
426 'scan_poll_seconds': scan_poll_seconds,
427 'scan_retry_seconds': scan_retry_seconds,
428 'client_name': str(raw.get('client_name') or 'Downtify').strip()
429 or 'Downtify',
430 'api_version': str(raw.get('api_version') or '1.16.1').strip()
431 or '1.16.1',
432 }
435class NavidromeClient:
436 """Minimal Subsonic client for Navidrome playlist and library operations."""
438 def __init__(self, cfg: dict[str, Any]):
439 self.base_url = str(cfg.get('url') or '').rstrip('/')
440 self.username = str(cfg.get('username') or '')
441 self.password = str(cfg.get('password') or '')
442 self.admin_username = str(cfg.get('admin_username') or '')
443 self.admin_password = str(cfg.get('admin_password') or '')
444 self.client_name = str(cfg.get('client_name') or 'Downtify')
445 self.api_version = str(cfg.get('api_version') or '1.16.1')
446 self.scan_poll_seconds = int(cfg.get('scan_poll_seconds') or 5)
447 self.timeout = 30
448 self._token = ''
449 self._salt = ''
451 def configured(self) -> bool:
452 return bool(self.base_url and self.username and self.password)
454 def _refresh_auth(self) -> None:
455 salt = secrets.token_urlsafe(8)[:12]
456 token = hashlib.md5(f'{self.password}{salt}'.encode()).hexdigest()
457 self._salt = salt
458 self._token = token
460 def _auth_query(
461 self,
462 *,
463 username: Optional[str] = None,
464 password: Optional[str] = None,
465 ) -> dict[str, str]:
466 user = username if username is not None else self.username
467 pwd = password if password is not None else self.password
468 salt = secrets.token_urlsafe(8)[:12]
469 token = hashlib.md5(f'{pwd}{salt}'.encode()).hexdigest()
470 return {
471 'u': user,
472 't': token,
473 's': salt,
474 'v': self.api_version,
475 'c': self.client_name,
476 'f': 'json',
477 }
479 def _request(
480 self,
481 endpoint: str,
482 extra: Optional[dict[str, Any]] = None,
483 *,
484 username: Optional[str] = None,
485 password: Optional[str] = None,
486 ) -> dict[str, Any]:
487 params = self._auth_query(username=username, password=password)
488 if extra:
489 for key, value in extra.items():
490 if value is None:
491 continue
492 params[key] = str(value)
493 url = f'{self.base_url}/rest/{endpoint}?{urlencode(params)}'
494 resp = httpx.get(url, timeout=self.timeout, follow_redirects=True)
495 resp.raise_for_status()
496 data = resp.json()
497 body = (
498 data.get('subsonic-response') if isinstance(data, dict) else None
499 )
500 if not isinstance(body, dict):
501 raise ValueError('Invalid Subsonic response')
502 if body.get('status') == 'failed':
503 err = body.get('error') or {}
504 message = err.get('message') if isinstance(err, dict) else str(err)
505 code = err.get('code') if isinstance(err, dict) else 0
506 raise SubsonicError(
507 str(message or 'Subsonic request failed'),
508 code if isinstance(code, int) else 0,
509 )
510 return body
512 def ping(self) -> bool:
513 try:
514 self._request('ping')
515 return True
516 except Exception as exc:
517 logger.info(
518 'navidrome: ping failed url={!r} err={}', self.base_url, exc
519 )
520 return False
522 def _scan_credentials(self) -> tuple[str, str]:
523 if self.admin_username and self.admin_password:
524 return self.admin_username, self.admin_password
525 return self.username, self.password
527 def start_scan(self, *, full: bool = False) -> None:
528 """Trigger Navidrome ``startScan`` (incremental by default, like Explo/deemix hooks)."""
530 extra: dict[str, Any] = {}
531 if full:
532 extra['fullScan'] = 'true'
533 user, pwd = self._scan_credentials()
534 self._request('startScan', extra or None, username=user, password=pwd)
536 def now_playing(self) -> list[dict[str, Any]]:
537 """What Navidrome's clients report playing right now
538 (``getNowPlaying``), for every user."""
540 user, pwd = self._scan_credentials()
541 body = self._request('getNowPlaying', username=user, password=pwd)
542 block = body.get('nowPlaying') if isinstance(body, dict) else None
543 entries = block.get('entry') if isinstance(block, dict) else None
544 if isinstance(entries, dict):
545 entries = [entries]
546 return [e for e in entries or [] if isinstance(e, dict)]
548 def wait_scan_complete(self, max_wait_seconds: int) -> bool:
549 deadline = time.monotonic() + max(10, max_wait_seconds)
550 user, pwd = self._scan_credentials()
551 while time.monotonic() < deadline:
552 try:
553 body = self._request(
554 'getScanStatus', username=user, password=pwd
555 )
556 except Exception as exc:
557 logger.info('navidrome: scan status failed err={}', exc)
558 return False
559 status = body.get('scanStatus') if isinstance(body, dict) else None
560 if isinstance(status, dict) and not status.get('scanning'):
561 return True
562 time.sleep(self.scan_poll_seconds)
563 logger.warning(
564 'navidrome: library scan still running after {}s; '
565 'playlist match may be incomplete',
566 max_wait_seconds,
567 )
568 return False
570 def _search3_songs(
571 self, query: str, *, song_count: int = _PRIMARY_SEARCH_COUNT
572 ) -> list[dict]:
573 body = self._request(
574 'search3',
575 {'query': query, 'songCount': song_count},
576 )
577 results = body.get('searchResult3') if isinstance(body, dict) else None
578 songs: list[Any] = []
579 if isinstance(results, dict):
580 songs = results.get('song') or []
581 if isinstance(songs, dict):
582 songs = [songs]
583 if not isinstance(songs, list):
584 return []
585 return [s for s in songs if isinstance(s, dict)]
587 def search_song_id(self, song: dict[str, Any]) -> Optional[str]:
588 path_keys = _path_match_keys(str(song.get('filename') or ''))
589 primary, fallback = _search_query_phases(song, path_keys)
590 if not primary and not fallback:
591 return None
593 target_duration = int(song.get('duration') or 0)
594 if target_duration > 1000:
595 target_duration //= 1000
597 for query in primary:
598 batch = self._search3_songs(
599 query, song_count=_PRIMARY_SEARCH_COUNT
600 )
601 picked = _pick_song_id_from_candidates(
602 batch, song, path_keys, target_duration
603 )
604 if picked:
605 return picked
607 for query in fallback:
608 batch = self._search3_songs(
609 query, song_count=_FALLBACK_SEARCH_COUNT
610 )
611 picked = _pick_song_id_from_candidates(
612 batch, song, path_keys, target_duration
613 )
614 if picked:
615 return picked
616 return None
618 def find_playlist_ids_by_name(self, name: str) -> list[str]:
619 """Return all playlist IDs with an exact *name* match (newest API order)."""
621 body = self._request('getPlaylists')
622 playlists = body.get('playlists') if isinstance(body, dict) else None
623 items = []
624 if isinstance(playlists, dict):
625 items = playlists.get('playlist') or []
626 if isinstance(items, dict):
627 items = [items]
628 ids: list[str] = []
629 for pl in items:
630 if not isinstance(pl, dict):
631 continue
632 if str(pl.get('name') or '') != name:
633 continue
634 pid = str(pl.get('id') or '').strip()
635 if pid:
636 ids.append(pid)
637 return ids
639 def get_playlist_songs(self, playlist_id: str) -> list[dict[str, Any]]:
640 """Return the rows currently stored in a Navidrome playlist."""
642 body = self._request('getPlaylist', {'id': playlist_id})
643 playlist = body.get('playlist') if isinstance(body, dict) else None
644 songs = playlist.get('entry') if isinstance(playlist, dict) else None
645 if isinstance(songs, dict):
646 songs = [songs]
647 if not isinstance(songs, list):
648 return []
649 return [song for song in songs if isinstance(song, dict)]
651 def delete_playlist(
652 self, playlist_id: str, *, admin: bool = False
653 ) -> None:
654 """Delete a playlist - with the admin login when *admin*, which
655 is what a playlist Navidrome imported (owned by its admin)
656 needs."""
658 if admin:
659 user, pwd = self._scan_credentials()
660 self._request(
661 'deletePlaylist',
662 {'id': playlist_id},
663 username=user,
664 password=pwd,
665 )
666 return
667 self._request('deletePlaylist', {'id': playlist_id})
669 def list_playlists(self, *, admin: bool = False) -> list[dict[str, Any]]:
670 """``getPlaylists`` rows the user (or the admin login) can see."""
672 user, pwd = (
673 self._scan_credentials()
674 if admin
675 else (self.username, self.password)
676 )
677 body = self._request('getPlaylists', username=user, password=pwd)
678 playlists = body.get('playlists') if isinstance(body, dict) else None
679 items = (
680 playlists.get('playlist') if isinstance(playlists, dict) else []
681 )
682 if isinstance(items, dict):
683 items = [items]
684 return [p for p in items or [] if isinstance(p, dict)]
686 def native_playlists(self) -> Optional[list[dict[str, Any]]]:
687 """Every playlist through Navidrome's own API, with the M3U each
688 was imported from (``path``) and whether it follows that file
689 (``sync``) - which the Subsonic API doesn't say. Signs in with
690 the admin login when one is set. ``None`` when that fails (not
691 Navidrome, or no admin rights)."""
693 user, pwd = self._scan_credentials()
694 try:
695 login = httpx.post(
696 f'{self.base_url}/auth/login',
697 json={'username': user, 'password': pwd},
698 timeout=self.timeout,
699 follow_redirects=True,
700 )
701 login.raise_for_status()
702 token = str((login.json() or {}).get('token') or '')
703 if not token:
704 return None
705 headers = {'x-nd-authorization': f'Bearer {token}'}
706 found: list[dict[str, Any]] = []
707 start = 0
708 while True:
709 resp = httpx.get(
710 f'{self.base_url}/api/playlist',
711 params={'_start': start, '_end': start + 500},
712 headers=headers,
713 timeout=self.timeout,
714 follow_redirects=True,
715 )
716 resp.raise_for_status()
717 batch = resp.json()
718 if not isinstance(batch, list):
719 return None
720 found.extend(p for p in batch if isinstance(p, dict))
721 if len(batch) < 500 or start > 50_000:
722 break
723 start += 500
724 except (httpx.HTTPError, ValueError) as exc:
725 logger.info('navidrome: native playlist list failed err={}', exc)
726 return None
727 return [
728 {
729 'id': str(p.get('id') or ''),
730 'name': str(p.get('name') or ''),
731 'songCount': int(p.get('songCount') or 0),
732 'owner': str(p.get('ownerName') or ''),
733 'comment': str(p.get('comment') or ''),
734 'path': str(p.get('path') or ''),
735 'sync': bool(p.get('sync')),
736 'public': bool(p.get('public')),
737 }
738 for p in found
739 ]
741 def all_songs(self, *, limit: int = 200_000) -> list[dict[str, Any]]:
742 """Every song Navidrome lists (``search3`` with an empty query,
743 500 at a time), as ``{id, artist, title, duration, path}``."""
745 songs: list[dict[str, Any]] = []
746 offset = 0
747 while offset < limit:
748 body = self._request(
749 'search3',
750 {
751 'query': '',
752 'songCount': 500,
753 'songOffset': offset,
754 'artistCount': 0,
755 'albumCount': 0,
756 },
757 )
758 result = (
759 body.get('searchResult3') if isinstance(body, dict) else None
760 )
761 batch = result.get('song') if isinstance(result, dict) else None
762 if isinstance(batch, dict):
763 batch = [batch]
764 if not batch:
765 break
766 for song in batch:
767 if isinstance(song, dict):
768 songs.append({
769 'id': str(song.get('id') or ''),
770 'artist': str(song.get('artist') or ''),
771 'title': str(song.get('title') or ''),
772 'duration': song.get('duration') or 0,
773 'path': str(song.get('path') or ''),
774 })
775 if len(batch) < 500:
776 break
777 offset += 500
778 return songs
780 @staticmethod
781 def _as_list(value: Any) -> list[dict[str, Any]]:
782 """Subsonic sends a single entry as an object, not a list."""
784 if isinstance(value, dict):
785 value = [value]
786 if not isinstance(value, list):
787 return []
788 return [item for item in value if isinstance(item, dict)]
790 def artists(self) -> list[dict[str, str]]:
791 """Every artist (``getArtists``) as ``{id, name}``."""
793 body = self._request('getArtists')
794 root = body.get('artists') if isinstance(body, dict) else None
795 found: list[dict[str, str]] = []
796 for index in self._as_list(
797 root.get('index') if isinstance(root, dict) else None
798 ):
799 for artist in self._as_list(index.get('artist')):
800 found.append({
801 'id': str(artist.get('id') or ''),
802 'name': str(artist.get('name') or ''),
803 })
804 return found
806 def artist_albums(self, artist_id: str) -> list[dict[str, Any]]:
807 """An artist's albums (``getArtist``) as
808 ``{id, name, song_count}``."""
810 body = self._request('getArtist', {'id': artist_id})
811 artist = body.get('artist') if isinstance(body, dict) else None
812 return [
813 {
814 'id': str(album.get('id') or ''),
815 'name': str(album.get('name') or ''),
816 'song_count': int(album.get('songCount') or 0),
817 }
818 for album in self._as_list(
819 artist.get('album') if isinstance(artist, dict) else None
820 )
821 ]
823 def album(self, album_id: str) -> dict[str, Any]:
824 """An album (``getAlbum``) as ``{id, name, artist, songs}``, each
825 song ``{id, title, starred, rating}``."""
827 body = self._request('getAlbum', {'id': album_id})
828 album = body.get('album') if isinstance(body, dict) else None
829 if not isinstance(album, dict):
830 album = {}
831 songs: list[dict[str, Any]] = []
832 for song in self._as_list(album.get('song')):
833 try:
834 rating = int(song.get('userRating') or 0)
835 except (TypeError, ValueError):
836 rating = 0
837 songs.append({
838 'id': str(song.get('id') or ''),
839 'title': str(song.get('title') or ''),
840 'starred': bool(song.get('starred')),
841 'rating': rating,
842 })
843 return {
844 'id': str(album.get('id') or album_id),
845 'name': str(album.get('name') or ''),
846 'artist': str(album.get('artist') or ''),
847 'songs': songs,
848 }
850 def set_rating(self, song_id: str, rating: int) -> None:
851 """Give a song 0-5 stars (``setRating``)."""
853 self._request(
854 'setRating', {'id': song_id, 'rating': max(0, min(5, rating))}
855 )
857 def _rest_post(
858 self,
859 endpoint: str,
860 query: dict[str, str],
861 form_pairs: list[tuple[str, str]],
862 ) -> dict[str, Any]:
863 url = f'{self.base_url}/rest/{endpoint}'
864 # httpx takes repeated form keys as a list per key, not as
865 # (key, value) pairs; insertion order within each key is kept.
866 form: dict[str, list[str]] = {}
867 for key, value in form_pairs:
868 form.setdefault(key, []).append(value)
869 resp = httpx.post(
870 url,
871 params=query,
872 data=form,
873 timeout=self.timeout,
874 follow_redirects=True,
875 )
876 return _parse_subsonic_http_response(resp)
878 def _add_songs_to_playlist(
879 self, playlist_id: str, song_ids: list[str]
880 ) -> None:
881 if not song_ids:
882 return
883 query = self._auth_query()
884 query['playlistId'] = playlist_id
885 form = [('songIdToAdd', sid) for sid in song_ids]
886 self._rest_post('updatePlaylist', query, form)
888 def _create_or_replace_playlist(
889 self,
890 name: str,
891 song_ids: list[str],
892 *,
893 playlist_id: Optional[str] = None,
894 ) -> str:
895 """Create a playlist or replace tracks on an existing one (Subsonic semantics)."""
897 if not song_ids:
898 raise ValueError('No songs matched in Navidrome library')
899 batches = _song_id_batches(song_ids)
900 query = self._auth_query()
901 query['name'] = name
902 if playlist_id:
903 query['playlistId'] = playlist_id
904 form = [('songId', sid) for sid in batches[0]]
905 logger.info(
906 'navidrome: createPlaylist POST batch 1/{} songs={} (uri-safe)',
907 len(batches),
908 len(form),
909 )
910 body = self._rest_post('createPlaylist', query, form)
911 pid = _playlist_id_from_body(body, playlist_id)
912 for index, batch in enumerate(batches[1:], start=2):
913 logger.info(
914 'navidrome: updatePlaylist POST batch {}/{} songs={}',
915 index,
916 len(batches),
917 len(batch),
918 )
919 self._add_songs_to_playlist(pid, batch)
920 return pid
922 def create_playlist(self, name: str, song_ids: list[str]) -> str:
923 return self._create_or_replace_playlist(name, song_ids)
925 def replace_playlist(
926 self, playlist_id: str, name: str, song_ids: list[str]
927 ) -> str:
928 """Replace all tracks on an existing playlist (same ID, no delete)."""
930 return self._create_or_replace_playlist(
931 name, song_ids, playlist_id=playlist_id
932 )
934 def update_playlist_meta(
935 self,
936 playlist_id: str,
937 *,
938 comment: str,
939 public: bool,
940 ) -> None:
941 self._request(
942 'updatePlaylist',
943 {
944 'playlistId': playlist_id,
945 'comment': comment,
946 'public': str(public).lower(),
947 },
948 )
951def _song_label(song: dict[str, Any]) -> str:
952 tags_row = dict(song)
953 title, artists = _library_tags(song)
954 if title:
955 tags_row['name'] = title
956 if artists:
957 tags_row['artists'] = artists
958 tags_row['library_from_tags'] = bool(title)
959 return spotify_file_tag_mismatch_label(tags_row)
962def _songs_for_playlist_sync(
963 playlist_name: str,
964 songs: list[dict[str, Any]],
965 *,
966 delete_mismatches: Optional[TagMismatchDeleteContext] = None,
967) -> list[dict[str, Any]]:
968 """Drop rows whose on-disk path clearly does not match track metadata."""
970 kept: list[dict[str, Any]] = []
971 for song in songs:
972 if spotify_aligns_with_file_tags(song):
973 kept.append(song)
974 continue
975 fn = str(song.get('filename') or '').strip()
976 label = spotify_file_tag_mismatch_label(song)
977 if delete_mismatches is not None and delete_if_spotify_tag_mismatch(
978 song,
979 delete_mismatches,
980 playlist_name=playlist_name,
981 ):
982 continue
983 logger.info(
984 'navidrome: skip sync for {}; Spotify does not match file tags',
985 f'{label} ({fn})' if fn else label,
986 )
987 return kept
990def _scan_wait_budget(cfg: dict[str, Any], track_count: int) -> int:
991 """Seconds to wait for Navidrome scan; scales slightly with playlist size."""
993 base = int(cfg['scan_wait_seconds'])
994 return min(900, max(base, 30 + track_count * 2))
997def enrich_song_from_library_file(
998 song: dict[str, Any],
999 download_dir: Path,
1000 slskd_dir: Optional[Path],
1001) -> dict[str, Any]:
1002 """Attach on-disk path metadata (mutagen tags) for Navidrome matching."""
1004 row = snapshot_spotify_metadata(song)
1005 filename = str(row.get('filename') or '').strip()
1006 if not filename:
1007 return row
1008 path = locate_library_file(filename, download_dir, slskd_dir)
1009 if path is None:
1010 return row
1011 meta = read_audio_metadata(path)
1012 if meta.get('title'):
1013 row['name'] = meta['title']
1014 row['library_from_tags'] = True
1015 if meta.get('artists'):
1016 row['artists'] = meta['artists']
1017 row['library_from_tags'] = True
1018 return row
1021def resolve_navidrome_song_id(
1022 client: NavidromeClient,
1023 song: dict[str, Any],
1024 index: Optional[NavidromeIndex] = None,
1025 *,
1026 download_dir: Optional[Path] = None,
1027 slskd_dir: Optional[Path] = None,
1028) -> tuple[Optional[str], bool]:
1029 """Return ``(navidrome song id, from_cache)``."""
1031 filename = str(song.get('filename') or '').strip()
1032 full_path: Optional[Path] = None
1033 if filename and download_dir is not None:
1034 full_path = locate_library_file(filename, download_dir, slskd_dir)
1036 if index is not None:
1037 cached = index.lookup_song(song, full_path=full_path)
1038 if cached:
1039 return cached, True
1040 sid = client.search_song_id(song)
1041 if sid and index is not None and filename:
1042 index.store(
1043 filename,
1044 sid,
1045 spotify_track_id=normalize_spotify_track_id(song),
1046 full_path=full_path,
1047 )
1048 return sid, False
1051def cache_navidrome_song_id(
1052 settings: dict[str, Any],
1053 song: dict[str, Any],
1054 filename: str,
1055 index: Optional[NavidromeIndex],
1056 *,
1057 download_dir: Optional[Path] = None,
1058 slskd_dir: Optional[Path] = None,
1059) -> None:
1060 """Resolve and store Navidrome id after a successful download."""
1062 if index is None or not _effective_navidrome_settings(settings).get(
1063 'enabled'
1064 ):
1065 return
1066 row = dict(song)
1067 row['filename'] = filename
1068 if download_dir is not None:
1069 row = enrich_song_from_library_file(row, download_dir, slskd_dir)
1070 client = NavidromeClient(_effective_navidrome_settings(settings))
1071 if not client.configured() or not client.ping():
1072 return
1073 resolve_navidrome_song_id(
1074 client, row, index, download_dir=download_dir, slskd_dir=slskd_dir
1075 )
1078def _match_songs_in_library(
1079 client: NavidromeClient,
1080 songs: list[dict[str, Any]],
1081 index: Optional[NavidromeIndex] = None,
1082 *,
1083 download_dir: Optional[Path] = None,
1084 slskd_dir: Optional[Path] = None,
1085) -> tuple[list[str], list[dict[str, Any]]]:
1086 song_ids: list[str] = []
1087 unmatched: list[dict[str, Any]] = []
1088 cached = 0
1089 for song in songs:
1090 sid, from_cache = resolve_navidrome_song_id(
1091 client,
1092 song,
1093 index,
1094 download_dir=download_dir,
1095 slskd_dir=slskd_dir,
1096 )
1097 if sid:
1098 song_ids.append(sid)
1099 if from_cache:
1100 cached += 1
1101 else:
1102 unmatched.append(song)
1103 if index is not None and songs:
1104 logger.info(
1105 'navidrome: resolved {}/{} track(s) ({} from cache)',
1106 len(song_ids),
1107 len(songs),
1108 cached,
1109 )
1110 return song_ids, unmatched
1113def someone_listening(client: NavidromeClient) -> bool:
1114 """Whether any Navidrome client is playing. A failed check counts as
1115 nobody, so scans are never held by an error."""
1117 try:
1118 return bool(client.now_playing())
1119 except Exception as exc:
1120 logger.info('navidrome: now-playing check failed err={}', exc)
1121 return False
1124class IdleScan:
1125 """One Navidrome scan held until nobody is listening.
1127 With ``scan_when_idle`` on, a scan Downtify would start while a
1128 Navidrome client is playing is handed here instead: requests are
1129 merged into one (full if any asked for full), and a background
1130 thread checks every :attr:`poll_seconds` and starts it once nothing
1131 is playing. Nothing else waits for it - the playlist sync that asked
1132 goes on without a fresh scan.
1133 """
1135 poll_seconds = 60
1137 def __init__(self) -> None:
1138 self._lock = threading.Lock()
1139 self._pending: Optional[tuple[NavidromeClient, bool]] = None
1140 self._thread: Optional[threading.Thread] = None
1142 @property
1143 def pending(self) -> bool:
1144 return self._pending is not None
1146 def request(self, client: NavidromeClient, *, full: bool) -> None:
1147 with self._lock:
1148 if self._pending is not None:
1149 full = full or self._pending[1]
1150 self._pending = (client, full)
1151 if self._thread is None or not self._thread.is_alive():
1152 self._thread = threading.Thread(
1153 target=self._run, name='navidrome-idle-scan', daemon=True
1154 )
1155 self._thread.start()
1157 def run_once(self) -> bool:
1158 """Start the held scan if nobody is listening; returns whether
1159 one is still held."""
1161 with self._lock:
1162 held = self._pending
1163 if held is None:
1164 return False
1165 client, full = held
1166 if someone_listening(client):
1167 return True
1168 with self._lock:
1169 if self._pending is held:
1170 self._pending = None
1171 try:
1172 client.start_scan(full=full)
1173 logger.info('navidrome: nobody listening; held scan started')
1174 except Exception as exc:
1175 logger.info('navidrome: held scan failed err={}', exc)
1176 return self.pending
1178 def _run(self) -> None:
1179 while True:
1180 time.sleep(self.poll_seconds)
1181 if not self.run_once():
1182 return
1185idle_scan = IdleScan()
1188def _trigger_library_scan(
1189 client: NavidromeClient,
1190 cfg: dict[str, Any],
1191 track_count: int,
1192) -> bool:
1193 """Start Navidrome scan and block until idle or timeout. Returns scan
1194 finished. With ``scan_when_idle`` on and a client playing, the scan
1195 is held (:class:`IdleScan`) and ``False`` returned at once."""
1197 if cfg.get('scan_when_idle') and someone_listening(client):
1198 logger.info(
1199 'navidrome: someone is listening; library scan held until '
1200 'playback stops'
1201 )
1202 idle_scan.request(client, full=bool(cfg.get('scan_full')))
1203 return False
1204 wait_seconds = _scan_wait_budget(cfg, track_count)
1205 mode = 'full' if cfg.get('scan_full') else 'incremental'
1206 logger.info(
1207 'navidrome: starting {} library scan before playlist sync '
1208 '(up to {}s, {} tracks)',
1209 mode,
1210 wait_seconds,
1211 track_count,
1212 )
1213 client.start_scan(full=bool(cfg.get('scan_full')))
1214 if client.wait_scan_complete(wait_seconds):
1215 logger.info('navidrome: library scan finished')
1216 return True
1217 return False
1220def _library_dirs_from_settings(
1221 settings: dict[str, Any],
1222 download_dir: Optional[Path] = None,
1223) -> tuple[Path, Optional[Path]]:
1224 slskd_raw = settings.get('slskd')
1225 slskd_dir: Optional[Path] = None
1226 if isinstance(slskd_raw, dict):
1227 source = str(slskd_raw.get('source_dir') or '').strip()
1228 if source:
1229 slskd_dir = Path(source)
1230 dl = download_dir
1231 if dl is None and isinstance(slskd_raw, dict):
1232 raw_dl = str(slskd_raw.get('download_dir') or '').strip()
1233 if raw_dl:
1234 dl = Path(raw_dl)
1235 if dl is None:
1236 dl = Path('/downloads')
1237 return Path(dl), slskd_dir
1240def remove_own_playlist_copies(client: NavidromeClient, name: str) -> int:
1241 """Delete the playlists Downtify created for *name* through the API.
1243 Only the Downtify login's own playlists carrying Downtify's comment
1244 are touched - never one Navidrome imported or a user made. Names are
1245 compared the way the M3U file is named, so ``Chill: Vibes`` also
1246 finds the copy for ``Chill Vibes.m3u``.
1247 """
1249 want = playlist_key(name)
1250 removed = 0
1251 try:
1252 playlists = client.list_playlists()
1253 except Exception as exc:
1254 logger.info('navidrome: could not list playlists err={}', exc)
1255 return 0
1256 for playlist in playlists:
1257 if (
1258 playlist_key(str(playlist.get('name') or '')) != want
1259 or not made_by_downtify(playlist)
1260 or str(playlist.get('owner') or '') != client.username
1261 ):
1262 continue
1263 try:
1264 client.delete_playlist(str(playlist.get('id') or ''))
1265 removed += 1
1266 except Exception as exc:
1267 logger.info(
1268 'navidrome: could not remove playlist id={} err={}',
1269 playlist.get('id'),
1270 exc,
1271 )
1272 return removed
1275def remove_navidrome_playlist_by_name(
1276 playlist_name: str,
1277 settings: dict[str, Any],
1278) -> int:
1279 """Delete Navidrome playlist(s) matching *playlist_name*. Returns count removed."""
1281 cfg = _effective_navidrome_settings(settings)
1282 if not cfg.get('enabled'):
1283 return 0
1284 client = NavidromeClient(cfg)
1285 if not client.configured() or not client.ping():
1286 return 0
1287 removed = 0
1288 for playlist_id in client.find_playlist_ids_by_name(playlist_name):
1289 try:
1290 client.delete_playlist(playlist_id)
1291 removed += 1
1292 logger.info(
1293 'navidrome: removed playlist id={} name={!r}',
1294 playlist_id,
1295 playlist_name,
1296 )
1297 except Exception as exc:
1298 logger.info(
1299 'navidrome: could not remove playlist id={} name={!r} err={}',
1300 playlist_id,
1301 playlist_name,
1302 exc,
1303 )
1304 return removed
1307def sync_playlist_to_navidrome( # noqa: PLR0914
1308 playlist_name: str,
1309 songs: list[dict[str, Any]],
1310 settings: dict[str, Any],
1311 *,
1312 navidrome_index: Optional[NavidromeIndex] = None,
1313 download_dir: Optional[Path] = None,
1314 comment: str = 'Synced from Spotify via Downtify',
1315 trigger_scan: Optional[bool] = None,
1316 delete_tag_mismatches: Optional[TagMismatchDeleteContext] = None,
1317) -> Optional[PlaylistSyncResult]:
1318 """Match *songs* in Navidrome and create/replace a server playlist.
1320 *trigger_scan*: when ``None``, use ``scan_after_download`` from settings
1321 (typical after new downloads). Pass ``False`` after deletes or path fixes
1322 when files were removed, not added.
1323 """
1324 cfg = _effective_navidrome_settings(settings)
1325 if not cfg.get('enabled'):
1326 return None
1327 client = NavidromeClient(cfg)
1328 if not client.configured():
1329 logger.info('navidrome: missing url/username/password')
1330 return None
1331 if not client.ping():
1332 logger.info('navidrome: server unreachable url={!r}', cfg.get('url'))
1333 return None
1334 if not songs:
1335 return None
1337 incoming = len(songs)
1338 songs = _songs_for_playlist_sync(
1339 playlist_name,
1340 songs,
1341 delete_mismatches=delete_tag_mismatches,
1342 )
1343 if len(songs) < incoming:
1344 action = (
1345 'deleted or excluded'
1346 if delete_tag_mismatches is not None
1347 else 'excluded'
1348 )
1349 logger.info(
1350 'navidrome: {} {} of {} track(s) from sync for playlist={!r} '
1351 '(Spotify/file tag mismatch)',
1352 action,
1353 incoming - len(songs),
1354 incoming,
1355 playlist_name,
1356 )
1357 if not songs:
1358 return None
1360 scanned = False
1361 scan_complete = False
1362 do_scan = (
1363 bool(cfg.get('scan_after_download'))
1364 if trigger_scan is None
1365 else bool(trigger_scan)
1366 )
1367 if do_scan:
1368 try:
1369 scanned = True
1370 scan_complete = _trigger_library_scan(client, cfg, len(songs))
1371 except Exception as exc:
1372 logger.info('navidrome: library scan failed err={}', exc)
1374 if cfg.get('m3u_import') and settings.get('generate_m3u', True):
1375 # Navidrome builds this playlist itself from the M3U (and its
1376 # cover) on the scan above; a playlist of Downtify's own would
1377 # only show up next to it as a duplicate.
1378 removed = remove_own_playlist_copies(client, playlist_name)
1379 logger.info(
1380 'navidrome: {!r} is imported from its M3U by Navidrome; no API '
1381 'playlist created ({} earlier copy removed)',
1382 playlist_name,
1383 removed,
1384 )
1385 return PlaylistSyncResult(
1386 '', playlist_name, 0, len(songs), scanned, scan_complete
1387 )
1389 dl_dir, slskd_dir = _library_dirs_from_settings(settings, download_dir)
1390 song_ids, pending = _match_songs_in_library(
1391 client,
1392 songs,
1393 navidrome_index,
1394 download_dir=dl_dir,
1395 slskd_dir=slskd_dir,
1396 )
1397 retry_seconds = int(cfg.get('scan_retry_seconds') or 0)
1398 if pending and scanned and retry_seconds > 0:
1399 logger.info(
1400 'navidrome: {} track(s) not indexed yet; retrying match in {}s',
1401 len(pending),
1402 retry_seconds,
1403 )
1404 time.sleep(retry_seconds)
1405 extra_ids, pending = _match_songs_in_library(
1406 client,
1407 pending,
1408 navidrome_index,
1409 download_dir=dl_dir,
1410 slskd_dir=slskd_dir,
1411 )
1412 song_ids.extend(extra_ids)
1414 total = len(songs)
1415 matched = len(song_ids)
1416 if pending:
1417 labels = [_song_label(s) for s in pending]
1418 logger.info(
1419 'navidrome: {} track(s) not in library index for playlist={!r}: {}',
1420 len(pending),
1421 playlist_name,
1422 '; '.join(labels[:12]) + ('; ...' if len(labels) > 12 else ''),
1423 )
1424 if matched == 0:
1425 logger.info(
1426 'navidrome: no tracks matched library for playlist={!r} total={}',
1427 playlist_name,
1428 total,
1429 )
1430 return PlaylistSyncResult(
1431 '', playlist_name, 0, total, scanned, scan_complete
1432 )
1434 existing_ids = client.find_playlist_ids_by_name(playlist_name)
1435 try:
1436 if existing_ids:
1437 playlist_id = existing_ids[0]
1438 for duplicate_id in existing_ids[1:]:
1439 try:
1440 client.delete_playlist(duplicate_id)
1441 logger.info(
1442 'navidrome: removed duplicate playlist id={} name={!r}',
1443 duplicate_id,
1444 playlist_name,
1445 )
1446 except Exception as exc:
1447 logger.info(
1448 'navidrome: could not remove duplicate playlist id={} err={}',
1449 duplicate_id,
1450 exc,
1451 )
1452 playlist_id = client.replace_playlist(
1453 playlist_id, playlist_name, song_ids
1454 )
1455 logger.info(
1456 'navidrome: updated existing playlist id={} name={!r}',
1457 playlist_id,
1458 playlist_name,
1459 )
1460 else:
1461 playlist_id = client.create_playlist(playlist_name, song_ids)
1462 logger.info(
1463 'navidrome: created playlist id={} name={!r}',
1464 playlist_id,
1465 playlist_name,
1466 )
1467 client.update_playlist_meta(
1468 playlist_id,
1469 comment=comment,
1470 public=bool(cfg.get('public_playlist')),
1471 )
1472 except Exception as exc:
1473 logger.info(
1474 'navidrome: playlist create failed name={!r} matched={}/{} err={}',
1475 playlist_name,
1476 matched,
1477 total,
1478 exc,
1479 )
1480 return PlaylistSyncResult(
1481 '', playlist_name, matched, total, scanned, scan_complete
1482 )
1484 logger.info(
1485 'navidrome: playlist synced name={!r} id={} matched={}/{} scan_complete={}',
1486 playlist_name,
1487 playlist_id,
1488 matched,
1489 total,
1490 scan_complete,
1491 )
1492 return PlaylistSyncResult(
1493 playlist_id, playlist_name, matched, total, scanned, scan_complete
1494 )