v0.93.0: Import from URL takes Apple Music songs, albums and playlists, found on YouTube like Spotify's, with a playlist of the same name offered

This commit is contained in:
2026-11-17 19:09:15 -08:00
parent 8afcd4433b
commit 2069e1b1d0
7 changed files with 448 additions and 19 deletions
+8
View File
@@ -845,6 +845,14 @@ persistence) → GUI (Qt widgets that read the manager and connect to its signal
track number into the mp3 **before** emitting `downloaded`, so the
import files it under the right artist and Identify ranks by that artist.
If the embed page changes shape, `parse_embed` raises `SpotifyError`.
**An Apple Music link** (Round 130, `apple_music_link.py`) is the same
path with another reader: `AppleMusicProbe` returns `SpotifyTrack`s
(kind `"apple"`, same `"spotify"` entry key, same worker). Albums and
songs (`/song/<id>`, `/album/…?i=<id>`) come from the keyless iTunes
Lookup API (track/disc numbers, `limit=200`); a playlist has no keyless
API, so its `music.apple.com` page's `serialized-server-data` JSON is read
— measured to hold every song (143 of 143), with album and length each.
Private `/library/` playlists can't be read and aren't matched.
**Several songs are identified as one batch** (Round 77,
`identify_batch.py` + `gui/identify_batch_dialog.py`): an import of more
than one song never pops a dialog mid-download. `IdentifyCollector` looks
+1 -1
View File
@@ -1,3 +1,3 @@
"""LinTunes — iTunes-style music library manager and player for Linux."""
__version__ = "0.92.0"
__version__ = "0.93.0"
+193
View File
@@ -0,0 +1,193 @@
"""Apple Music links for File ▸ Import from URL… (Round 130).
Spotify's twin (``spotify_link``): Apple won't hand over audio either, but
it will say what a link is, without a key or a login, and each song is then
found on YouTube by artist, title and length exactly as a Spotify song is.
The songs come back as ``spotify_link.SpotifyTrack``s, so the probe, the
checklist, the YouTube search and the tagging are all Spotify's own.
Where the list comes from depends on the link (measured November 2026):
- **An album or a song** — the public iTunes Lookup API
(``itunes.apple.com/lookup``), which is documented and stable: track and
disc numbers, the album's name, each song's length.
- **A playlist** — has no keyless API, but its ``music.apple.com`` page
carries every song as JSON in a ``serialized-server-data`` script: title,
artist, album and length per song, and the playlist's name. All of them,
not a first page: a 143-song playlist's page held all 143.
Shaped like ``spotify_link``: pure helpers first (tested against canned
JSON), then the network calls.
"""
import json
import re
from urllib.parse import parse_qs, urlsplit
import requests
from lintunes.spotify_link import USER_AGENT, SpotifyTrack
TIMEOUT = 20
LOOKUP_URL = "https://itunes.apple.com/lookup"
PLAYLIST_URL = "https://music.apple.com/{storefront}/playlist/{id}"
_HOSTS = ("music.apple.com", "geo.music.apple.com", "embed.music.apple.com",
"itunes.apple.com")
_SERVER_DATA = re.compile(
r'<script[^>]*id="serialized-server-data"[^>]*>\s*(.*?)\s*</script>',
re.DOTALL)
class AppleMusicError(Exception):
pass
def apple_source(text: str) -> tuple[str, str, str] | None:
"""(kind, id, storefront) for an Apple Music song, album or playlist
link, else None. kind is "song", "album" or "playlist"; an album link
with ``?i=<song id>`` (what Share Song copies) is that one song."""
text = (text or "").strip()
try:
parts = urlsplit(text)
except ValueError:
return None
if parts.scheme not in ("http", "https") or \
(parts.hostname or "").lower() not in _HOSTS:
return None
segments = [s for s in parts.path.split("/") if s]
storefront = "us"
if segments and re.fullmatch(r"[a-z]{2}", segments[0]):
storefront = segments.pop(0)
if len(segments) < 2:
return None
kind, source_id = segments[0], segments[-1]
song = (parse_qs(parts.query).get("i") or [""])[0]
if kind == "album":
if song.isdigit():
return "song", song, storefront
m = re.fullmatch(r"(?:id)?(\d+)", source_id)
return ("album", m.group(1), storefront) if m else None
if kind == "song":
m = re.fullmatch(r"(?:id)?(\d+)", source_id)
return ("song", m.group(1), storefront) if m else None
if kind == "playlist" and source_id.startswith("pl."):
return "playlist", source_id, storefront
return None
def _seconds(ms) -> int | None:
try:
return round(float(ms) / 1000) or None
except (TypeError, ValueError):
return None
def parse_lookup(data: dict, kind: str) -> tuple[str, list[SpotifyTrack]]:
"""An iTunes Lookup answer → (the album's or song's name, its songs).
An album's songs are numbered as on the album; a lone song too, since
the lookup knows where it sits."""
results = (data or {}).get("results") or []
songs = [r for r in results
if r.get("wrapperType") == "track" and r.get("trackName")]
if not songs:
raise AppleMusicError("Apple Music has no songs at that link (it may "
"be private, deleted, or not in that country)")
songs.sort(key=lambda r: (r.get("discNumber") or 0,
r.get("trackNumber") or 0))
collection = next((r for r in results
if r.get("wrapperType") == "collection"), None)
discs = max((r.get("discCount") or 0) for r in songs)
tracks = [SpotifyTrack(
id=str(r.get("trackId") or n), title=r["trackName"],
artist=r.get("artistName") or "",
album=r.get("collectionName") or "",
duration=_seconds(r.get("trackTimeMillis")),
track_number=r.get("trackNumber") or 0,
track_count=r.get("trackCount") or 0,
disc_number=(r.get("discNumber") or 0) if discs > 1 else 0,
disc_count=discs if discs > 1 else 0)
for n, r in enumerate(songs, 1)]
if kind == "song":
return tracks[0].title, tracks[:1]
name = (collection or {}).get("collectionName") or tracks[0].album
return name or "Apple Music", tracks
def _link_title(item: dict, key: str) -> str:
links = item.get(key) or []
return (links[0].get("title") or "") if links else ""
def parse_playlist_page(html: str) -> tuple[str, list[SpotifyTrack]]:
"""A ``music.apple.com`` playlist page → (its name, its songs in order).
Raises AppleMusicError when the page isn't shaped the way it was in
November 2026."""
m = _SERVER_DATA.search(html or "")
if not m:
raise AppleMusicError("Apple Music's page didn't have the song list "
"in it (Apple may have changed its page "
"format)")
try:
data = json.loads(m.group(1))
sections = data["data"][0]["data"]["sections"]
except (ValueError, KeyError, IndexError, TypeError) as e:
raise AppleMusicError(f"Apple Music's song list couldn't be read: "
f"{e}")
name = ""
tracks: list[SpotifyTrack] = []
for section in sections:
kind = section.get("itemKind")
items = section.get("items") or []
if kind == "containerDetailHeaderLockup" and items and not name:
name = items[0].get("title") or ""
elif kind == "trackLockup":
for n, item in enumerate(items, 1):
title = item.get("title")
if not title:
continue
ident = ((item.get("contentDescriptor") or {})
.get("identifiers") or {}).get("storeAdamID")
tracks.append(SpotifyTrack(
id=str(ident or n), title=title,
artist=(item.get("artistName")
or _link_title(item, "subtitleLinks")),
album=_link_title(item, "tertiaryLinks"),
duration=_seconds(item.get("duration"))))
if not tracks:
raise AppleMusicError("Apple Music's page had no songs in it")
return name or "Apple Music", tracks
# ---- network ----
def _get(url: str, **params) -> requests.Response:
try:
return requests.get(url, params=params or None, timeout=TIMEOUT,
headers={"User-Agent": USER_AGENT})
except requests.RequestException as e:
raise AppleMusicError(f"couldn't reach Apple Music: {e}")
def fetch(kind: str, source_id: str,
storefront: str = "us") -> tuple[str, list[SpotifyTrack]]:
if kind == "playlist":
resp = _get(PLAYLIST_URL.format(storefront=storefront, id=source_id))
if resp.status_code == 404:
raise AppleMusicError("Apple Music has no playlist with that "
"link (it may be private or deleted)")
if not resp.ok:
raise AppleMusicError(f"Apple Music answered {resp.status_code}")
return parse_playlist_page(resp.text)
params = {"id": source_id, "country": storefront}
if kind == "album":
params["entity"] = "song"
params["limit"] = 200 # the default 50 cuts a box set short
resp = _get(LOOKUP_URL, **params)
if not resp.ok:
raise AppleMusicError(f"Apple Music answered {resp.status_code}")
try:
data = resp.json()
except ValueError as e:
raise AppleMusicError(f"Apple Music's answer couldn't be read: {e}")
return parse_lookup(data, kind)
+17 -12
View File
@@ -22,10 +22,11 @@ moment and downloads the song's own page with the list stripped off.
A Spotify link (Round 76) is listed the same way, from Spotify's own page
(``url_import.SpotifyProbe``): a track goes straight through, an album or
playlist is a checklist with everything ticked. The caller reads the chosen
songs from ``spotify_tracks()`` and finds each one on YouTube.
songs from ``spotify_tracks()`` and finds each one on YouTube. An Apple
Music link (Round 130, ``url_import.AppleMusicProbe``) works the same way.
A list that has a name (a YouTube or SoundCloud playlist, a Spotify album
or playlist) offers to make a new playlist of the same name holding every
A list that has a name (a YouTube or SoundCloud playlist, a Spotify or
Apple Music album or playlist) offers to make a new playlist of the same name holding every
song imported (``new_playlist_name()``). Off unless ticked; the name can be
edited first.
"""
@@ -39,11 +40,15 @@ from PyQt6.QtWidgets import (
)
from lintunes.url_import import (
PlaylistProbe, SpotifyProbe, link_kind, looks_like_url,
AppleMusicProbe, PlaylistProbe, SpotifyProbe, link_kind, looks_like_url,
)
ENTRY_ROLE = Qt.ItemDataRole.UserRole
# Links whose songs are found on YouTube: kind → (name, probe).
_CATALOGS = {"spotify": ("Spotify", SpotifyProbe),
"apple": ("Apple Music", AppleMusicProbe)}
def format_duration(seconds) -> str:
if not seconds:
@@ -85,7 +90,7 @@ class UrlImportDialog(QDialog):
layout = QVBoxLayout(self)
layout.addWidget(QLabel("Paste a link to a song, or to a playlist of "
"songs (YouTube, Spotify, …):"))
"songs (YouTube, Spotify, Apple Music, …):"))
self._url = QLineEdit()
self._url.setPlaceholderText("https://…")
clipboard = QApplication.clipboard().text().strip()
@@ -195,7 +200,7 @@ class UrlImportDialog(QDialog):
def spotify_tracks(self) -> list:
"""The chosen songs of a Spotify link, as ``SpotifyTrack``s (empty
for any other link): the ticked ones, or the link's one song."""
if self._kind != "spotify":
if self._kind not in _CATALOGS:
return []
entries = self.chosen_entries() or (
[self._single] if self._single else [])
@@ -247,14 +252,14 @@ class UrlImportDialog(QDialog):
self._list_name = ""
self._url.setEnabled(False)
self._just.setVisible(bool(self._linked))
spotify = self._kind == "spotify"
self._status.setText("Reading the songs off Spotify…" if spotify
else "Checking what's at the link…")
catalog = _CATALOGS.get(self._kind)
self._status.setText(f"Reading the songs off {catalog[0]}…"
if catalog else "Checking what's at the link…")
self._status.show()
self._busy.show()
# No parent: a cancelled probe's thread can outlive this dialog,
# and must not be emitting from a deleted QObject when it does.
probe = (SpotifyProbe if spotify else PlaylistProbe)(
probe = (catalog[1] if catalog else PlaylistProbe)(
url, cookies_browser=self._cookies)
probe.entry.connect(self._on_entry)
probe.named.connect(self._on_named)
@@ -330,8 +335,8 @@ class UrlImportDialog(QDialog):
def _count_text(self, listing: bool) -> str:
n = len(self._entries)
if self._kind == "spotify":
return (f"This Spotify link has {n} songs"
if self._kind in _CATALOGS:
return (f"This {_CATALOGS[self._kind][0]} link has {n} songs"
+ ("…" if listing else ".")
+ "\nEach one is found on YouTube by its artist, title "
"and length.")
+5
View File
@@ -68,6 +68,8 @@ class SpotifyTrack:
duration: int | None = None # seconds
track_number: int = 0
track_count: int = 0
disc_number: int = 0 # only for a multi-disc album
disc_count: int = 0
def label(self) -> str:
return f"{self.artist} — {self.title}" if self.artist else self.title
@@ -202,6 +204,9 @@ def tag_fields(track: SpotifyTrack) -> dict:
if track.track_number:
fields["track_number"] = track.track_number
fields["track_count"] = track.track_count
if track.disc_number:
fields["disc_number"] = track.disc_number
fields["disc_count"] = track.disc_count
return fields
+28 -6
View File
@@ -38,6 +38,9 @@ the same checklist, and ``SpotifyImportWorker`` takes them one at a time:
a five-result YouTube search, the result closest to Spotify's length, the
`song` download, then Spotify's tags written into the file *before* it's
handed over, so the import files it under the right artist and album.
An Apple Music link (Round 130, ``apple_music_link``) is the same thing
with another reader: ``AppleMusicProbe`` lists its songs as
``SpotifyTrack``s and ``SpotifyImportWorker`` finds them on YouTube.
"""
import os
import shutil
@@ -53,7 +56,7 @@ from urllib.parse import parse_qs, urlsplit
from PyQt6.QtCore import QObject, pyqtSignal
from lintunes import spotify_link, tagging
from lintunes import apple_music_link, spotify_link, tagging
from lintunes.models.playlist import PlaylistType
log = logging.getLogger(__name__)
@@ -119,7 +122,8 @@ def link_kind(url: str) -> str:
"""What a link names, from the URL alone: "song", "song_in_list" (a song
opened from a playlist or a YouTube Mix — yt-dlp would take the whole
list), "list", "spotify" (a Spotify track, album or playlist, which is
found on YouTube song by song), or "unknown" (another site; only a probe
found on YouTube song by song), "apple" (the same for Apple Music), or
"unknown" (another site; only a probe
can tell).
Only "song" skips the probe, so a plain song link imports as fast as
@@ -128,6 +132,8 @@ def link_kind(url: str) -> str:
"""
if spotify_link.spotify_source(url) is not None:
return "spotify"
if apple_music_link.apple_source(url) is not None:
return "apple"
try:
parts = urlsplit((url or "").strip())
except ValueError:
@@ -641,15 +647,20 @@ class SpotifyProbe(QObject):
self._busy = True
threading.Thread(target=self._run, daemon=True).start()
def _lookup(self):
"""→ (is it a list, its name, its songs)."""
kind, source_id = spotify_link.spotify_source(self._url)
name, tracks = spotify_link.fetch(kind, source_id)
return kind != "track", name, tracks
def _run(self):
try:
kind, source_id = spotify_link.spotify_source(self._url)
name, tracks = spotify_link.fetch(kind, source_id)
is_list, name, tracks = self._lookup()
except Exception as e:
self._busy = False
self.failed.emit(str(e))
return
if kind != "track":
if is_list:
self.named.emit(name)
count = 0
for track in tracks:
@@ -663,6 +674,17 @@ class SpotifyProbe(QObject):
self.finished.emit(count)
class AppleMusicProbe(SpotifyProbe):
"""``SpotifyProbe`` for an Apple Music link: the songs come from the
iTunes Lookup API (album, song) or the playlist's own page, as
``SpotifyTrack``s under the same ``"spotify"`` key."""
def _lookup(self):
kind, source_id, storefront = apple_music_link.apple_source(self._url)
name, tracks = apple_music_link.fetch(kind, source_id, storefront)
return kind != "song", name, tracks
class SpotifyImportWorker(UrlImportWorker):
"""``UrlImportWorker``'s signals, for songs a Spotify link named: each
is searched for on YouTube, the best-length result downloaded (the next
@@ -773,7 +795,7 @@ class SpotifyImportWorker(UrlImportWorker):
self._fail_nothing(*last, "download")
else:
self.failed.emit(errors[-1] if errors else
"nothing on the Spotify link was found "
"none of the link's songs were found "
"on YouTube")
return
self.finished.emit({"downloaded": downloaded, "errors": errors,
+196
View File
@@ -0,0 +1,196 @@
"""Round 130: Apple Music links in File ▸ Import from URL.
Spotify's path with another reader: an Apple Music song, album or playlist
is listed (iTunes Lookup API for albums and songs, the playlist page's
``serialized-server-data`` JSON for playlists), each song is found on
YouTube by artist, title and length, and a named list offers a playlist of
the same name. No network here: the answers are canned.
"""
import json
import time
import pytest
from lintunes import apple_music_link, spotify_link, url_import
from lintunes.apple_music_link import (
AppleMusicError, apple_source, parse_lookup, parse_playlist_page,
)
from lintunes.gui.url_import_dialog import UrlImportDialog
PLAYLIST_URL = "https://music.apple.com/us/playlist/2026-10/pl.u-zPyLmjRtEZ54PZ"
def _lockup(adam_id, title, artist, album, ms):
return {"title": title, "artistName": artist, "duration": ms,
"trackNumber": None,
"subtitleLinks": [{"title": artist}],
"tertiaryLinks": [{"title": album}],
"contentDescriptor": {"kind": "song",
"identifiers": {"storeAdamID": adam_id}}}
def _page(name, lockups) -> str:
data = {"data": [{"intent": {}, "data": {"sections": [
{"itemKind": "containerDetailHeaderLockup",
"items": [{"title": name, "trackCount": len(lockups)}]},
{"itemKind": "trackLockup", "items": lockups},
{"itemKind": "bubbleLockup", "items": [{"title": "Some Artist"}]},
]}}]}
return ('<html><script type="application/json" '
'id="serialized-server-data">' + json.dumps(data)
+ "</script></html>")
PLAYLIST = _page("2026-10", [
_lockup("617854252", "Tomorrow's Girls", "Donald Fagen", "Kamakiriad",
377680),
_lockup("1452872926", "Zou bisou bisou", "Gillian Hills",
"Twistin' the Rock", 136000),
])
ALBUM = {"resultCount": 4, "results": [
{"wrapperType": "collection", "collectionName": "Double"},
# Out of order on purpose, and two discs.
{"wrapperType": "track", "trackId": 3, "trackName": "Three",
"artistName": "A", "collectionName": "Double", "trackTimeMillis": 3000,
"trackNumber": 1, "trackCount": 1, "discNumber": 2, "discCount": 2},
{"wrapperType": "track", "trackId": 2, "trackName": "Two",
"artistName": "A", "collectionName": "Double", "trackTimeMillis": 2000,
"trackNumber": 2, "trackCount": 2, "discNumber": 1, "discCount": 2},
{"wrapperType": "track", "trackId": 1, "trackName": "One",
"artistName": "A", "collectionName": "Double", "trackTimeMillis": 1000,
"trackNumber": 1, "trackCount": 2, "discNumber": 1, "discCount": 2},
]}
SONG = {"resultCount": 1, "results": [
{"wrapperType": "track", "trackId": 617854252,
"trackName": "Tomorrow's Girls", "artistName": "Donald Fagen",
"collectionName": "Kamakiriad", "trackTimeMillis": 377680,
"trackNumber": 5, "trackCount": 8, "discNumber": 1, "discCount": 1}]}
# --------------------------------------------------------------------------
# A. links
@pytest.mark.parametrize("text, source", [
(PLAYLIST_URL, ("playlist", "pl.u-zPyLmjRtEZ54PZ", "us")),
("https://music.apple.com/gb/playlist/pl.f4d106fed2bd41149aaacabb233eb5eb",
("playlist", "pl.f4d106fed2bd41149aaacabb233eb5eb", "gb")),
("https://music.apple.com/us/album/kamakiriad/617853627",
("album", "617853627", "us")),
("https://music.apple.com/us/album/tomorrows-girls/617853627"
"?i=617854252", ("song", "617854252", "us")),
("https://music.apple.com/us/song/tomorrows-girls/617854252",
("song", "617854252", "us")),
("https://geo.music.apple.com/album/x/id617853627",
("album", "617853627", "us")),
("https://music.apple.com/us/artist/donald-fagen/155517", None),
("https://music.apple.com/library/playlist/p.abc", None),
("https://example.com/us/album/x/1", None),
("not a link", None),
])
def test_apple_source(text, source):
assert apple_source(text) == source
def test_link_kind():
assert url_import.link_kind(PLAYLIST_URL) == "apple"
assert url_import.looks_like_url(PLAYLIST_URL)
# --------------------------------------------------------------------------
# B. reading the songs
def test_a_playlist_page_names_its_songs_with_albums_and_lengths():
name, tracks = parse_playlist_page(PLAYLIST)
assert name == "2026-10"
assert [(t.id, t.artist, t.title, t.album, t.duration, t.track_number)
for t in tracks] == [
("617854252", "Donald Fagen", "Tomorrow's Girls", "Kamakiriad", 378,
0),
("1452872926", "Gillian Hills", "Zou bisou bisou",
"Twistin' the Rock", 136, 0)]
@pytest.mark.parametrize("html", [
"<html>nothing</html>",
'<script type="application/json" id="serialized-server-data">{</script>',
_page("Empty", []),
])
def test_a_changed_page_says_so(html):
with pytest.raises(AppleMusicError):
parse_playlist_page(html)
def test_an_album_is_in_disc_and_track_order_and_numbered():
name, tracks = parse_lookup(ALBUM, "album")
assert name == "Double"
assert [(t.title, t.disc_number, t.track_number) for t in tracks] == [
("One", 1, 1), ("Two", 1, 2), ("Three", 2, 1)]
assert spotify_link.tag_fields(tracks[2]) == {
"name": "Three", "artist": "A", "album": "Double",
"track_number": 1, "track_count": 1,
"disc_number": 2, "disc_count": 2}
def test_a_song_is_one_song_and_one_disc_gets_no_disc_tag():
name, tracks = parse_lookup(SONG, "song")
assert name == "Tomorrow's Girls" and len(tracks) == 1
assert "disc_number" not in spotify_link.tag_fields(tracks[0])
assert tracks[0].track_number == 5
def test_nothing_found_says_so():
with pytest.raises(AppleMusicError):
parse_lookup({"resultCount": 0, "results": []}, "album")
# --------------------------------------------------------------------------
# C. the dialog
def _pump(qapp, until, timeout=10.0):
deadline = time.monotonic() + timeout
while not until() and time.monotonic() < deadline:
qapp.processEvents()
time.sleep(0.01)
assert until(), "timed out waiting"
@pytest.fixture
def canned(monkeypatch):
def fetch(kind, _id, _storefront="us"):
if kind == "playlist":
return parse_playlist_page(PLAYLIST)
return parse_lookup(SONG if kind == "song" else ALBUM, kind)
monkeypatch.setattr(apple_music_link, "fetch", fetch)
def _dialog(qapp, url):
qapp.clipboard().setText(url)
dialog = UrlImportDialog(None)
assert dialog.url() == url
return dialog
def test_a_playlist_is_a_checklist_offering_a_playlist_of_its_name(
qapp, canned):
dialog = _dialog(qapp, PLAYLIST_URL)
dialog._on_import()
_pump(qapp, lambda: dialog._probe is None)
assert dialog._picking and dialog._list.count() == 2
assert "Apple Music link has 2 songs" in dialog._status.text()
assert not dialog._make.isHidden()
assert dialog._make_name.text() == "2026-10"
dialog._make.setChecked(True)
dialog._on_import()
assert dialog.new_playlist_name() == "2026-10"
assert [t.title for t in dialog.spotify_tracks()] == [
"Tomorrow's Girls", "Zou bisou bisou"]
def test_an_apple_song_goes_straight_through(qapp, canned):
dialog = _dialog(qapp, "https://music.apple.com/us/song/x/617854252")
dialog._on_import()
_pump(qapp, lambda: dialog.result() == dialog.DialogCode.Accepted)
assert [t.artist for t in dialog.spotify_tracks()] == ["Donald Fagen"]
assert dialog.new_playlist_name() == ""