Coverage for downtify/album_artist.py: 100%

33 statements  

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

1"""Which artist an album is filed and tagged under, and when an album is a 

2various-artists compilation. 

3 

4A leaf module (it imports nothing from Downtify), like ``file_naming``, so 

5the Spotify, Deezer and YouTube Music scrapers and the downloader can share 

6the one rule. 

7 

8The album artist is always the one the source declares for the album, never 

9something worked out from its tracks: a single-artist album with a guest on 

10one track ("Alice feat. Bob") still belongs to Alice, and a duo album has 

11the same two artists on every track without being a compilation. Only when 

12the source credits the album to "Various Artists" is it a compilation - 

13which media servers like Navidrome want marked on every track (``TCMP`` / 

14``COMPILATION`` / ``cpil``), or they break the album up by artist. 

15""" 

16 

17from __future__ import annotations 

18 

19import re 

20from typing import Any 

21 

22from loguru import logger 

23 

24VARIOUS_ARTISTS = 'Various Artists' 

25 

26# The "Various Artists" entity on each service. Deezer localizes its name 

27# ("Vários intérpretes" for a Brazilian client), so its ids are what count 

28# there; Spotify only exposes its id on the playlist GraphQL path. The two 

29# id spaces can't collide (Deezer's are numeric, Spotify's base62). 

30_VARIOUS_ARTISTS_IDS = frozenset({ 

31 '0LyfQWJT6nXafLPZqxe9Of', # Spotify 

32 '5080', # Deezer 

33 '108420982', # Deezer, a second "Various Artists" entity 

34}) 

35 

36# Names a source may use for it, case-insensitive. Only the first is what 

37# Spotify and YouTube Music have been seen to send; the rest are the 

38# translations services use, in case one turns up. 

39_VARIOUS_ARTISTS_NAMES = frozenset({ 

40 'various artists', 

41 'various', 

42 'vários artistas', 

43 'varios artistas', 

44 'vários intérpretes', 

45 'varios intérpretes', 

46 'varios interpretes', 

47 'artistes divers', 

48 'artistes variés', 

49 'verschiedene interpreten', 

50 'artisti vari', 

51 'artisti varie', 

52}) 

53 

54 

55def is_various_artists(name: Any, *, artist_id: Any = '') -> bool: 

56 """Whether *name* (or *artist_id*, a Spotify or Deezer artist id) is 

57 the "Various Artists" placeholder rather than a real artist.""" 

58 

59 if str(artist_id or '').strip() in _VARIOUS_ARTISTS_IDS: 

60 return True 

61 text = ' '.join(str(name or '').split()).casefold() 

62 if text not in _VARIOUS_ARTISTS_NAMES: 

63 return False 

64 if text != VARIOUS_ARTISTS.casefold(): 

65 logger.info('Treating album artist {!r} as Various Artists', name) 

66 return True 

67 

68 

69# What sits between the members' names in an act's own name: "Henrique & 

70# Juliano", "Simon + Garfunkel", "Sandy e Junior", "Zé Neto, Cristiano". 

71# Not "x": "Anitta x Pedro Sampaio" names a collaboration, not an act. 

72_ACT_NAME_JOINER = r'\s*(?:&|\+|,|/|\b(?:e|and|y)\b)\s*' 

73 

74 

75def is_act_of(names: list[str], act: Any) -> bool: 

76 """Whether *act* is the name of an act made of exactly *names* (two or 

77 more), joined the way an act's name joins its members, in any order: 

78 ``(['Mateus', 'Jorge'], 'Jorge & Mateus')`` -> True. Mirrored by 

79 ``isActOf`` in ``frontend/src/lib/library.js``.""" 

80 

81 if len(names) < 2: 

82 return False 

83 members = [ 

84 part 

85 for part in re.split(_ACT_NAME_JOINER, str(act or '').casefold()) 

86 if part.strip() 

87 ] 

88 return sorted(part.strip() for part in members) == sorted( 

89 str(name).strip().casefold() for name in names 

90 ) 

91 

92 

93def filing_artist(song: dict[str, Any]) -> str: 

94 """The artist a downloaded *song* is filed under ("Organize by artist") 

95 and whose profile it seeds: its album artist, so every track of an 

96 album lands together - except for a various-artists compilation, whose 

97 tracks go to their own first artist instead of a "Various Artists" 

98 folder (the tags still say "Various Artists", which is what keeps the 

99 album whole in a media server). ``''`` when there is no artist.""" 

100 

101 album_artist = str(song.get('album_artist') or '').strip() 

102 if ( 

103 album_artist 

104 and not song.get('compilation') 

105 and not is_various_artists(album_artist) 

106 ): 

107 return album_artist 

108 artists = song.get('artists') or [] 

109 return str(artists[0]).strip() if artists else '' 

110 

111 

112def album_artist_fields(name: Any, *, artist_id: Any = '') -> dict[str, Any]: 

113 """The song fields for an album credited to *name*: ``album_artist``, 

114 plus ``compilation: True`` (and the canonical "Various Artists") when 

115 it is a various-artists compilation. Empty when *name* is blank, so 

116 the caller falls back to the track's first artist.""" 

117 

118 if is_various_artists(name, artist_id=artist_id): 

119 return {'album_artist': VARIOUS_ARTISTS, 'compilation': True} 

120 text = str(name or '').strip() 

121 return {'album_artist': text} if text else {}