Coverage for downtify/m3u.py: 95%
239 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"""Build and write Jellyfin-compatible ``.m3u`` playlist files.
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"""
10from __future__ import annotations
12import os
13import re
14from pathlib import Path
15from typing import Iterable, Optional, Sequence
17from loguru import logger
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
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'
37def read_m3u_text(m3u_path: Path) -> Optional[str]:
38 """Read a playlist without modifying it, or warn and return ``None``.
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 """
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
74def is_manual_m3u(m3u_path: Path) -> bool:
75 """True when *m3u_path* was written as a Library-created playlist."""
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 )
86def iter_m3u_files(download_dir: Path) -> list[Path]:
87 """Every ``.m3u`` / ``.m3u8`` under *download_dir*, sorted by path."""
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
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)."""
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
119def sanitize_playlist_name(name: str) -> str:
120 """Strip filesystem-unsafe characters from a playlist name.
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 """
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'
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.
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).
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`.
157 Returns ``(content, kept_count)`` so the caller can both write the
158 file and report how many tracks ended up in it.
159 """
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
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.
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 """
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()
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
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`)."""
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
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
260 return resolve
263def extinf_label(extinf: str) -> str:
264 """``Artist - Title`` from an ``#EXTINF:<seconds>,<label>`` line."""
266 text = str(extinf or '').strip()
267 if not text.startswith('#EXTINF'):
268 return ''
269 _duration, _sep, label = text.partition(',')
270 return label.strip()
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."""
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
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."""
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
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."""
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
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)
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 ''
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.
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 """
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'
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``.
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.
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 """
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)
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
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