Coverage for downtify/m3u.py: 95%

239 statements  

« prev     ^ index     » next       coverage.py v7.17.4, created at 2026-11-21 22:18 +0000

1"""Build and write Jellyfin-compatible ``.m3u`` playlist files. 

2 

3The Spotify embed flow gives us the playlist name and an ordered list of 

4tracks; the downloader gives us the final on-disk filename of every 

5track that succeeds. Combining the two produces an ``EXTM3U`` file that 

6Jellyfin (and any other media server that consumes M3U) can pick up so 

7the playlist appears as a single unit instead of a pile of loose tracks. 

8""" 

9 

10from __future__ import annotations 

11 

12import os 

13import re 

14from pathlib import Path 

15from typing import Iterable, Optional, Sequence 

16 

17from loguru import logger 

18 

19from .library_paths import ( 

20 EXTERNAL_LIBRARY_PREFIX, 

21 SLSKD_LIBRARY_PREFIX, 

22 ResolvedLibraryRoots, 

23 locate_library_file, 

24) 

25from .library_paths_cache import forget_cached_playlists 

26 

27# Only characters that are genuinely illegal in FAT/NTFS/ext filenames are 

28# dropped. Everything else — including accented and non-Latin letters such 

29# as "ö" (Sólrún) or "é" (Renata Béranger) — is preserved so folder names 

30# match the original artist/album/playlist titles. 

31_PLAYLIST_NAME_INVALID = re.compile(r'[\\/:*?"<>|\x00-\x1f]') 

32#: Marks an M3U the user built in the Library, so it can be edited 

33#: without touching downloaded Spotify/YouTube playlists. 

34MANUAL_M3U_MARKER = '#EXTDOWNTIFY:manual' 

35 

36 

37def read_m3u_text(m3u_path: Path) -> Optional[str]: 

38 """Read a playlist without modifying it, or warn and return ``None``. 

39 

40 Prefer strict UTF-8 (with an optional BOM). Legacy ``.m3u`` files 

41 fall back to strict Windows-1252, matching the external-playlist 

42 importer; ``.m3u8`` files must be UTF-8. Windows-1252 also covers 

43 printable Latin-1 text, but undefined bytes are rejected rather 

44 than dropped or replaced. NULs indicate unsupported text (such as 

45 UTF-16) or binary data and must not reach path resolution. 

46 """ 

47 

48 try: 

49 data = m3u_path.read_bytes() 

50 try: 

51 text = data.decode('utf-8-sig') 

52 except UnicodeDecodeError: 

53 if m3u_path.suffix.lower() != '.m3u': 

54 raise 

55 text = data.decode('cp1252') 

56 except (OSError, UnicodeDecodeError) as exc: 

57 logger.warning( 

58 'Skipping unreadable playlist {}: {}. Check file permissions ' 

59 'or save a copy as UTF-8.', 

60 m3u_path, 

61 exc, 

62 ) 

63 return None 

64 if '\x00' in text: 

65 logger.warning( 

66 'Skipping unreadable playlist {}: NUL characters in text. ' 

67 'Save a copy as UTF-8.', 

68 m3u_path, 

69 ) 

70 return None 

71 return text 

72 

73 

74def is_manual_m3u(m3u_path: Path) -> bool: 

75 """True when *m3u_path* was written as a Library-created playlist.""" 

76 

77 text = read_m3u_text(m3u_path) 

78 if text is None: 

79 return False 

80 head = text[:2048] 

81 return any( 

82 line.strip() == MANUAL_M3U_MARKER for line in head.splitlines()[:12] 

83 ) 

84 

85 

86def iter_m3u_files(download_dir: Path) -> list[Path]: 

87 """Every ``.m3u`` / ``.m3u8`` under *download_dir*, sorted by path.""" 

88 

89 base = Path(download_dir) 

90 found: list[Path] = [] 

91 try: 

92 if not base.is_dir(): 

93 return [] 

94 except OSError: 

95 return [] 

96 for dirpath, _dirnames, filenames in os.walk(base, followlinks=False): 

97 current = Path(dirpath) 

98 for name in filenames: 

99 if name.lower().endswith(('.m3u', '.m3u8')): 

100 found.append(current / name) 

101 found.sort() 

102 return found 

103 

104 

105def find_m3u_for_name( 

106 download_dir: Path, playlist_name: str 

107) -> Optional[Path]: 

108 """The M3U whose stem matches *playlist_name* (case-insensitive).""" 

109 

110 want = str(playlist_name or '').strip().casefold() 

111 if not want: 

112 return None 

113 for path in iter_m3u_files(download_dir): 

114 if path.stem.casefold() == want: 

115 return path 

116 return None 

117 

118 

119def sanitize_playlist_name(name: str) -> str: 

120 """Strip filesystem-unsafe characters from a playlist name. 

121 

122 Removes only characters that are illegal in filenames on common 

123 filesystems while keeping Unicode letters, digits and punctuation 

124 intact. Collapses runs of whitespace and trims leading/trailing dots 

125 and spaces. Returns ``'playlist'`` if nothing is left after 

126 sanitising so we never produce an empty filename. 

127 """ 

128 

129 if not name: 

130 return 'playlist' 

131 cleaned = _PLAYLIST_NAME_INVALID.sub('', name) 

132 cleaned = re.sub(r'\s+', ' ', cleaned).strip().strip('.').strip() 

133 return cleaned or 'playlist' 

134 

135 

136def build_m3u_content( 

137 entries: Iterable[dict], 

138 *, 

139 download_dir: Path, 

140 m3u_dir: Optional[Path] = None, 

141 slskd_dir: Optional[Path] = None, 

142 extra_dirs: Optional[Sequence[Path]] = None, 

143) -> tuple[str, int]: 

144 """Render the body of a ``.m3u`` file. 

145 

146 Each entry is a dict with at least ``filename`` and optionally 

147 ``title``, ``artist`` and ``duration``. Entries whose file does not 

148 exist on disk are skipped (and logged). 

149 

150 Track paths are written **relative to the M3U file's directory** so 

151 the same file works whether it's read from inside the Downtify 

152 container (``/downloads/...``) or from another consumer that mounts 

153 the same library at a different root (Jellyfin under 

154 ``/nas/music/...``, etc). ``m3u_dir`` defaults to 

155 ``download_dir/Playlists`` to match :func:`write_m3u`. 

156 

157 Returns ``(content, kept_count)`` so the caller can both write the 

158 file and report how many tracks ended up in it. 

159 """ 

160 

161 if m3u_dir is None: 

162 m3u_dir = download_dir / 'Playlists' 

163 lines: list[str] = ['#EXTM3U'] 

164 kept = 0 

165 for entry in entries: 

166 filename = (entry or {}).get('filename') 

167 if not filename: 

168 continue 

169 # Also finds ``slskd/...`` files left in place under the slskd 

170 # folder, outside download_dir. 

171 path = locate_library_file( 

172 filename, download_dir, slskd_dir, extra_dirs 

173 ) 

174 if path is None: 

175 logger.warning('Skipping missing track in M3U: {}', filename) 

176 continue 

177 title = (entry.get('title') or '').strip() 

178 artist = (entry.get('artist') or '').strip() 

179 duration = entry.get('duration') 

180 try: 

181 duration_int = int(duration) if duration is not None else -1 

182 except (TypeError, ValueError): 

183 duration_int = -1 

184 if title or artist: 

185 label = ' - '.join(p for p in (artist, title) if p) 

186 lines.append(f'#EXTINF:{duration_int},{label}') 

187 lines.append(os.path.relpath(path, start=m3u_dir)) 

188 kept += 1 

189 # Standard M3U uses LF line endings. 

190 return '\n'.join(lines) + '\n', kept 

191 

192 

193def read_m3u_tracks( 

194 m3u_path: Path, 

195 download_dir: Path, 

196 slskd_dir: Optional[Path] = None, 

197 extra_dirs: Optional[Sequence[Path]] = None, 

198 *, 

199 keep_missing: bool = False, 

200) -> list[str]: 

201 """Return the tracks listed in *m3u_path*, as paths relative to 

202 *download_dir* (the same shape ``/list`` returns), in file order. 

203 

204 Inverts the relative-path scheme :func:`build_m3u_content` writes: 

205 each non-comment line is relative to the M3U's own directory, not to 

206 *download_dir* (absolute lines are accepted too). Tracks under 

207 *slskd_dir* — slskd downloads left in place — come back with the 

208 virtual ``slskd/`` prefix. Lines that don't resolve to an existing 

209 file under either root are skipped — self-healing when a track was 

210 deleted or a line is otherwise stale, and a hard guard against a 

211 malicious or malformed M3U escaping the library via ``../``. 

212 """ 

213 

214 resolve = _line_resolver(m3u_path, download_dir, slskd_dir, extra_dirs) 

215 text = read_m3u_text(m3u_path) 

216 if text is None: 

217 return [] 

218 lines = text.splitlines() 

219 

220 tracks: list[str] = [] 

221 for raw in lines: 

222 line = raw.strip() 

223 if not line or line.startswith('#'): 

224 continue 

225 found = resolve(line) 

226 if found is None: 

227 continue 

228 stored, resolved = found 

229 if resolved.is_file() or keep_missing: 

230 tracks.append(stored) 

231 return tracks 

232 

233 

234def _line_resolver( 

235 m3u_path: Path, 

236 download_dir: Path, 

237 slskd_dir: Optional[Path], 

238 extra_dirs: Optional[Sequence[Path]], 

239): 

240 """``line -> (stored path, resolved path)`` for an M3U's track lines, 

241 ``None`` for a line outside the library (see :func:`read_m3u_tracks`).""" 

242 

243 download_dir = Path(download_dir).resolve() 

244 slskd_root = Path(slskd_dir).resolve() if slskd_dir else None 

245 m3u_dir = m3u_path.resolve().parent 

246 extras = ResolvedLibraryRoots.from_dirs( 

247 download_dir, slskd_dir, extra_dirs 

248 ).extras 

249 

250 def resolve(line: str) -> Optional[tuple[str, Path]]: 

251 try: 

252 resolved = (m3u_dir / line).resolve() 

253 except OSError: 

254 return None 

255 stored = _stored_library_path( 

256 resolved, download_dir, slskd_root, extras 

257 ) 

258 return (stored, resolved) if stored else None 

259 

260 return resolve 

261 

262 

263def extinf_label(extinf: str) -> str: 

264 """``Artist - Title`` from an ``#EXTINF:<seconds>,<label>`` line.""" 

265 

266 text = str(extinf or '').strip() 

267 if not text.startswith('#EXTINF'): 

268 return '' 

269 _duration, _sep, label = text.partition(',') 

270 return label.strip() 

271 

272 

273def read_m3u_entries( 

274 m3u_path: Path, 

275 download_dir: Path, 

276 slskd_dir: Optional[Path] = None, 

277 extra_dirs: Optional[Sequence[Path]] = None, 

278) -> list[tuple[str, str]]: 

279 """``(stored path, #EXTINF line or '')`` for every track of 

280 *m3u_path* that is in the library, present or not, in file order.""" 

281 

282 resolve = _line_resolver(m3u_path, download_dir, slskd_dir, extra_dirs) 

283 text = read_m3u_text(m3u_path) 

284 if text is None: 

285 return [] 

286 lines = text.splitlines() 

287 entries: list[tuple[str, str]] = [] 

288 extinf = '' 

289 for raw in lines: 

290 line = raw.strip() 

291 if line.startswith('#EXTINF'): 

292 extinf = line 

293 continue 

294 if not line or line.startswith('#'): 

295 continue 

296 found = resolve(line) 

297 if found is not None: 

298 entries.append((found[0], extinf)) 

299 extinf = '' 

300 return entries 

301 

302 

303def remove_m3u_tracks( 

304 m3u_path: Path, 

305 stored_paths: Iterable[str], 

306 download_dir: Path, 

307 slskd_dir: Optional[Path] = None, 

308 extra_dirs: Optional[Sequence[Path]] = None, 

309) -> int: 

310 """Take the tracks at *stored_paths* (library paths, as 

311 :func:`read_m3u_tracks` returns them) out of *m3u_path*, with their 

312 ``#EXTINF`` lines. Every other line - markers, comments, the other 

313 tracks - is kept as written. How many lines went.""" 

314 

315 drop = { 

316 str(item or '').strip().replace('\\', '/') 

317 for item in stored_paths 

318 if str(item or '').strip() 

319 } 

320 if not drop: 

321 return 0 

322 resolve = _line_resolver(m3u_path, download_dir, slskd_dir, extra_dirs) 

323 text = read_m3u_text(m3u_path) 

324 if text is None: 

325 return 0 

326 lines = text.splitlines() 

327 kept: list[str] = [] 

328 pending: list[str] = [] 

329 removed = 0 

330 for raw in lines: 

331 line = raw.strip() 

332 if not line or line.startswith('#'): 

333 pending.append(raw) 

334 continue 

335 found = resolve(line) 

336 if found is not None and found[0] in drop: 

337 kept.extend( 

338 p for p in pending if not p.strip().startswith('#EXTINF') 

339 ) 

340 removed += 1 

341 else: 

342 kept.extend(pending) 

343 kept.append(raw) 

344 pending = [] 

345 kept.extend(pending) 

346 if removed: 

347 m3u_path.write_text( 

348 '\n'.join(kept) + '\n', encoding='utf-8', newline='\n' 

349 ) 

350 forget_cached_playlists() 

351 return removed 

352 

353 

354def insert_m3u_track( 

355 m3u_path: Path, 

356 stored_path: str, 

357 position: int, 

358 extinf: str, 

359 download_dir: Path, 

360 slskd_dir: Optional[Path] = None, 

361 extra_dirs: Optional[Sequence[Path]] = None, 

362) -> bool: 

363 """Put the library file *stored_path* back into *m3u_path* as its 

364 *position*-th track (at the end when the list is shorter), with its 

365 ``#EXTINF`` line. ``False`` when the file isn't in the library.""" 

366 

367 full = locate_library_file( 

368 stored_path, download_dir, slskd_dir, extra_dirs 

369 ) 

370 if full is None: 

371 return False 

372 text = read_m3u_text(m3u_path) 

373 if text is None: 

374 return False 

375 lines = text.splitlines() 

376 block = [extinf] if str(extinf or '').startswith('#EXTINF') else [] 

377 block.append(os.path.relpath(full, start=m3u_path.parent)) 

378 at = len(lines) 

379 seen = 0 

380 start: Optional[int] = None 

381 for index, raw in enumerate(lines): 

382 line = raw.strip() 

383 if line.startswith('#EXTINF'): 

384 start = index if start is None else start 

385 continue 

386 if not line or line.startswith('#'): 

387 continue 

388 if seen == position: 

389 at = index if start is None else start 

390 break 

391 seen += 1 

392 start = None 

393 lines[at:at] = block 

394 m3u_path.write_text( 

395 '\n'.join(lines) + '\n', encoding='utf-8', newline='\n' 

396 ) 

397 forget_cached_playlists() 

398 return True 

399 

400 

401def _stored_library_path( 

402 resolved: Path, 

403 download_dir: Path, 

404 slskd_root: Optional[Path], 

405 extras: Sequence[tuple[Path, str]], 

406) -> str: 

407 if resolved.is_relative_to(download_dir): 

408 return resolved.relative_to(download_dir).as_posix() 

409 if slskd_root is not None and resolved.is_relative_to(slskd_root): 

410 rel = resolved.relative_to(slskd_root).as_posix() 

411 return f'{SLSKD_LIBRARY_PREFIX}{rel}' 

412 return _extra_stored_path(resolved, extras) 

413 

414 

415def _extra_stored_path( 

416 resolved: Path, extras: Sequence[tuple[Path, str]] 

417) -> str: 

418 for extra_root, folder_id in extras: 

419 try: 

420 rel = resolved.relative_to(extra_root).as_posix() 

421 except ValueError: 

422 continue 

423 return f'{EXTERNAL_LIBRARY_PREFIX}{folder_id}/{rel}' 

424 return '' 

425 

426 

427def m3u_path_for( 

428 download_dir: Path, 

429 playlist_name: str, 

430 *, 

431 playlist_subdir: Optional[str] = None, 

432) -> Path: 

433 """Where :func:`write_m3u` would put this playlist's M3U. 

434 

435 Resolving the path without writing anything lets the playlist's 

436 cover art be saved beside it before the first track is downloaded — 

437 see ``downtify.monitor.download_playlist_cover``. 

438 """ 

439 

440 if playlist_subdir: 

441 target_dir = Path(download_dir) / playlist_subdir 

442 else: 

443 target_dir = Path(download_dir) / 'Playlists' 

444 return target_dir / f'{sanitize_playlist_name(playlist_name)}.m3u' 

445 

446 

447def write_m3u( 

448 download_dir: Path, 

449 playlist_name: str, 

450 entries: Iterable[dict], 

451 *, 

452 playlist_subdir: Optional[str] = None, 

453 slskd_dir: Optional[Path] = None, 

454 extra_dirs: Optional[Sequence[Path]] = None, 

455 manual: bool = False, 

456 allow_empty: bool = False, 

457) -> tuple[Optional[Path], int]: 

458 """Write an M3U for ``playlist_name``. 

459 

460 When ``playlist_subdir`` is given the M3U is placed inside that 

461 per-playlist folder (``download_dir/<playlist_subdir>/<safe>.m3u``) 

462 so the directory is fully self-contained — handy for browsing on a 

463 NAS or playing folders directly on Sonos. Otherwise the legacy 

464 ``download_dir/Playlists/<safe>.m3u`` location is used. 

465 

466 Returns ``(path, kept)``. ``path`` is ``None`` and ``kept`` is ``0`` 

467 when no track survived the existence check; nothing is written in 

468 that case. 

469 """ 

470 

471 target = m3u_path_for( 

472 download_dir, playlist_name, playlist_subdir=playlist_subdir 

473 ) 

474 target_dir = target.parent 

475 target_dir.mkdir(parents=True, exist_ok=True) 

476 

477 content, kept = build_m3u_content( 

478 list(entries), 

479 download_dir=Path(download_dir), 

480 m3u_dir=target_dir, 

481 slskd_dir=slskd_dir, 

482 extra_dirs=extra_dirs, 

483 ) 

484 if manual: 

485 lines = content.splitlines() 

486 if lines[:1] == ['#EXTM3U'] and MANUAL_M3U_MARKER not in lines[:4]: 

487 lines.insert(1, MANUAL_M3U_MARKER) 

488 content = '\n'.join(lines) + '\n' 

489 if kept == 0 and not allow_empty: 

490 logger.warning( 

491 'Refusing to write empty M3U for playlist {!r}', playlist_name 

492 ) 

493 return None, 0 

494 

495 # UTF-8, no BOM, LF line endings — encoding='utf-8' on text mode 

496 # gives us no BOM, and we built the content with '\n' already. 

497 target.write_text(content, encoding='utf-8', newline='\n') 

498 forget_cached_playlists() 

499 logger.info('Wrote M3U: {} with {} tracks', target, kept) 

500 return target, kept