New tags: Copyright, ISRC, Artists, AlbumArtists, URL

docs/index.rst

@@ -23,10 +23,11 @@ The metadata schema is generally based on MusicBrainz' schema with similar namin
 
 * basic fields like ``title``, ``album``, ``artist`` and ``albumartist``,
 * sorting variants like ``albumartist_sort`` and ``composer_sort``,
-* identifiers like ``asin`` or ``mb_releasegroupid``,
+* plural/list variants like ``artists`` and ``albumartists``,
+* identifiers like ``asin``, ``isrc`` or ``mb_releasegroupid``,
 * dates like the release ``year``, ``month`` and ``day`` with convenience wrapper ``date``,
 * detailed metadata like ``language`` or ``media``,
-* ``lyrics``,
+* ``lyrics``, ``copyright``, ``url``
 * calculated metadata like ``bpm`` (beats per minute) and ``r128_track_gain`` (ReplayGain),
 * embedded images (e.g. album art),
 * file metadata like ``bitrate`` and ``length``.

mediafile.py

@@ -839,31 +839,38 @@ def store(self, mutagen_file, value):
 class MP3DescStorageStyle(MP3StorageStyle):
     """Store data in a TXXX (or similar) ID3 frame. The frame is
     selected based its ``desc`` field.
+    ``attr`` allows to specify name of data accessor property in the frame.
+    Most of frames use `text`.
+    ``multispec`` specifies if frame data is ``mutagen.id3.MultiSpec``
+    which means that the data is being packed in the list.
     """
-    def __init__(self, desc=u'', key='TXXX', **kwargs):
+    def __init__(self, desc=u'', key='TXXX', attr='text', multispec=True,
+                 **kwargs):
         assert isinstance(desc, six.text_type)
         self.description = desc
+        self.attr = attr
+        self.multispec = multispec
         super(MP3DescStorageStyle, self).__init__(key=key, **kwargs)
 
     def store(self, mutagen_file, value):
         frames = mutagen_file.tags.getall(self.key)
-        if self.key != 'USLT':
+        if self.multispec:
             value = [value]
 
         # Try modifying in place.
         found = False
         for frame in frames:
             if frame.desc.lower() == self.description.lower():
-                frame.text = value
+                setattr(frame, self.attr, value)
                 frame.encoding = mutagen.id3.Encoding.UTF8
                 found = True
 
         # Try creating a new frame.
         if not found:
             frame = mutagen.id3.Frames[self.key](
                 desc=self.description,
-                text=value,
                 encoding=mutagen.id3.Encoding.UTF8,
+                **{self.attr: value}
             )
             if self.id3_lang:
                 frame.lang = self.id3_lang
@@ -872,10 +879,10 @@ def store(self, mutagen_file, value):
     def fetch(self, mutagen_file):
         for frame in mutagen_file.tags.getall(self.key):
             if frame.desc.lower() == self.description.lower():
-                if self.key == 'USLT':
-                    return frame.text
+                if not self.multispec:
+                    return getattr(frame, self.attr)
                 try:
-                    return frame.text[0]
+                    return getattr(frame, self.attr)[0]
                 except IndexError:
                     return None
 
@@ -889,6 +896,34 @@ def delete(self, mutagen_file):
             del mutagen_file[frame.HashKey]
 
 
+class MP3ListDescStorageStyle(MP3DescStorageStyle, ListStorageStyle):
+    def __init__(self, desc=u'', key='TXXX', split_v23=False, **kwargs):
+        self.split_v23 = split_v23
+        super(MP3ListDescStorageStyle, self).__init__(
+            desc=desc, key=key, **kwargs
+        )
+
+    def fetch(self, mutagen_file):
+        for frame in mutagen_file.tags.getall(self.key):
+            if frame.desc.lower() == self.description.lower():
+                if mutagen_file.tags.version == (2, 3, 0) and self.split_v23:
+                    return sum([el.split('/') for el in frame.text], start=[])
+                else:
+                    return frame.text
+        return []
+
+    def store(self, mutagen_file, values):
+        self.delete(mutagen_file)
+        frame = mutagen.id3.Frames[self.key](
+            desc=self.description,
+            text=values,
+            encoding=mutagen.id3.Encoding.UTF8,
+        )
+        if self.id3_lang:
+            frame.lang = self.id3_lang
+        mutagen_file.tags.add(frame)
+
+
 class MP3SlashPackStorageStyle(MP3StorageStyle):
     """Store value as part of pair that is serialized as a slash-
     separated string.
@@ -1643,6 +1678,12 @@ def update(self, dict):
         StorageStyle('ARTIST'),
         ASFStorageStyle('Author'),
     )
+    artists = ListMediaField(
+        MP3ListDescStorageStyle(desc=u'ARTISTS'),
+        MP4ListStorageStyle('----:com.apple.iTunes:ARTISTS'),
+        ListStorageStyle('ARTISTS'),
+        ASFStorageStyle('WM/ARTISTS'),
+    )
     album = MediaField(
         MP3StorageStyle('TALB'),
         MP4StorageStyle('\xa9alb'),
@@ -1722,8 +1763,15 @@ def update(self, dict):
         ASFStorageStyle('TotalDiscs'),
         out_type=int,
     )
+
+    url = MediaField(
+        MP3DescStorageStyle(key='WXXX', attr='url', multispec=False),
+        MP4StorageStyle('\xa9url'),
+        StorageStyle('URL'),
+        ASFStorageStyle('WM/URL'),
+    )
     lyrics = MediaField(
-        MP3DescStorageStyle(key='USLT'),
+        MP3DescStorageStyle(key='USLT', multispec=False),
         MP4StorageStyle('\xa9lyr'),
         StorageStyle('LYRICS'),
         ASFStorageStyle('WM/Lyrics'),
@@ -1736,6 +1784,12 @@ def update(self, dict):
         ASFStorageStyle('WM/Comments'),
         ASFStorageStyle('Description')
     )
+    copyright = MediaField(
+        MP3StorageStyle('TCOP'),
+        MP4StorageStyle('cprt'),
+        StorageStyle('COPYRIGHT'),
+        ASFStorageStyle('Copyright'),
+    )
     bpm = MediaField(
         MP3StorageStyle('TBPM'),
         MP4StorageStyle('tmpo', as_type=int),
@@ -1757,6 +1811,12 @@ def update(self, dict):
         StorageStyle('ALBUMARTIST'),
         ASFStorageStyle('WM/AlbumArtist'),
     )
+    albumartists = ListMediaField(
+        MP3ListDescStorageStyle(desc=u'ALBUMARTISTS'),
+        MP4ListStorageStyle('----:com.apple.iTunes:ALBUMARTISTS'),
+        ListStorageStyle('ALBUMARTISTS'),
+        ASFStorageStyle('WM/AlbumArtists'),
+    )
     albumtype = MediaField(
         MP3DescStorageStyle(u'MusicBrainz Album Type'),
         MP4StorageStyle('----:com.apple.iTunes:MusicBrainz Album Type'),
@@ -1801,8 +1861,18 @@ def update(self, dict):
         MP3DescStorageStyle(u'BARCODE'),
         MP4StorageStyle('----:com.apple.iTunes:BARCODE'),
         StorageStyle('BARCODE'),
+        StorageStyle('UPC', read_only=True),
+        StorageStyle('EAN/UPN', read_only=True),
+        StorageStyle('EAN', read_only=True),
+        StorageStyle('UPN', read_only=True),
         ASFStorageStyle('WM/Barcode'),
     )
+    isrc = MediaField(
+        MP3StorageStyle(u'TSRC'),
+        MP4StorageStyle('----:com.apple.iTunes:ISRC'),
+        StorageStyle('ISRC'),
+        ASFStorageStyle('WM/ISRC'),
+    )
     disctitle = MediaField(
         MP3StorageStyle('TSST'),
         MP4StorageStyle('----:com.apple.iTunes:DISCSUBTITLE'),

test/test_mediafile.py

@@ -365,6 +365,7 @@ class ReadWriteTestBase(ArtTestMixin, GenreListTestMixin,
         'disctotal',
         'lyrics',
         'comments',
+        'copyright',
         'bpm',
         'comp',
         'mb_trackid',
@@ -390,6 +391,7 @@ class ReadWriteTestBase(ArtTestMixin, GenreListTestMixin,
         'asin',
         'catalognum',
         'barcode',
+        'isrc',
         'disctitle',
         'script',
         'language',
@@ -449,7 +451,11 @@ def test_read_full(self):
     def test_read_empty(self):
         mediafile = self._mediafile_fixture('empty')
         for field in self.tag_fields:
-            self.assertIsNone(getattr(mediafile, field))
+            value = getattr(mediafile, field)
+            if isinstance(value, list):
+                assert not value
+            else:
+                self.assertIsNone(value)
 
     def test_write_empty(self):
         mediafile = self._mediafile_fixture('empty')
@@ -620,7 +626,11 @@ def test_delete_tag(self):
         mediafile = MediaFile(mediafile.path)
 
         for key in keys:
-            self.assertIsNone(getattr(mediafile, key))
+            value = getattr(mediafile, key)
+            if isinstance(value, list):
+                assert not value
+            else:
+                self.assertIsNone(value)
 
     def test_delete_packed_total(self):
         mediafile = self._mediafile_fixture('full')
@@ -705,9 +715,14 @@ def _generate_tags(self, base=None):
         for key in ['disc', 'disctotal', 'track', 'tracktotal', 'bpm']:
             tags[key] = 1
 
+        for key in ['artists', 'albumartists']:
+            tags[key] = ['multival', 'test']
+
         tags['art'] = self.jpg_data
         tags['comp'] = True
 
+        tags['url'] = "https://example.com/"
+
         date = datetime.date(2001, 4, 3)
         tags['date'] = date
         tags['year'] = date.year
@@ -976,7 +991,8 @@ def test_properties_from_readable_fields(self):
 
     def test_known_fields(self):
         fields = list(ReadWriteTestBase.tag_fields)
-        fields.extend(('encoder', 'images', 'genres', 'albumtype'))
+        fields.extend(('encoder', 'images', 'genres', 'albumtype', 'artists',
+                       'albumartists', 'url'))
         assertCountEqual(self, MediaFile.fields(), fields)
 
     def test_fields_in_readable_fields(self):