Merge pull request #47 from DakaraProject/feature/detect-instrumental-files

Improve management of instrumental files

Author: Neraste

CHANGELOG.md

@@ -33,10 +33,16 @@
 ### Changed
 
 - The metadata parser can now be specified with the configuration key `metadata_parser`. Accepted values are `ffprobe` (default), `mediainfo`, or `null` (for testing only).
+- Songs with instrumental version are specified either with the `instrumental_file` field, if there is an audio file of the same name in the same directory as the video file, or with the `instrumental_track` field, if the video file has a second audio track. Both fields are sent to the server, instead of the `has_instrumental` field (see removed sub-section).
 
 ### Removed
 
 - Dropped Python 3.9.
+- Removed the `has_instrumental` field of songs, in favor of `instrumental_file` and `instrumental_track`.
+
+### Fixed
+
+- Matroshka files containing only an audio track and having the `.mka` extension are correctly detected as adio files.
 
 ## 1.9.0 - 2025-03-06
 

src/dakara_feeder/directory.py

@@ -1,10 +1,12 @@
 """List directoryes to extract song files."""
 
 import logging
+import mimetypes
 from itertools import groupby
 
 import filetype
 
+from dakara_feeder.media import is_audio, is_video
 from dakara_feeder.subtitle.parsing import is_subtitle
 
 logger = logging.getLogger(__name__)
@@ -54,23 +56,81 @@ def get_path_without_extension(path):
 
 
 def get_main_type(file):
-    """Get the first part of the MIME type of the given file.
+    """Get the type of a given file.
+
+    First try a manual detection on expected extensions, as this is required
+    for subtitles, and as some audio files can be mistaken for video files
+    (notably, `.mka` files). Then try an automatic detection based on the
+    extension of the file. If this fails, try an automatic detection based on
+    the magic numbers in the file.
 
     Args:
-        file (pathlib.Path): Absolute path to the file to extract the MIME type.
+        file (pathlib.Path): Absolute path to the file to extract the type.
 
     Returns
-        str: Main type if the MIME type can be extracted, `None` otherwise.
+        str: Type if it can be extracted, `None` otherwise.
     """
-    kind = filetype.guess(str(file))
+    # manual detection of video files
+    if is_video(file):
+        return "video"
+
+    # manual detection of audio files
+    if is_audio(file):
+        return "audio"
+
+    # manual detection of subtitle files
+    if is_subtitle(file):
+        return "subtitle"
 
-    if not kind:
+    # automatic detection using extension
+    mimetype = get_mimetype_by_extension(file)
+
+    # if it failed, automatic detection using magic number
+    if mimetype is None:
+        mimetype = get_mimetype_by_magic_number(file)
+
+    # abort if not found
+    if mimetype is None:
         return None
 
-    maintype, _ = kind.mime.split("/")
+    # extract main type from MIME type
+    maintype, _ = mimetype.split("/")
     return maintype
 
 
+def get_mimetype_by_magic_number(file):
+    """Return the MIME type of a file based on its magic number.
+
+    This strategy is more costly and should be used as a second option.
+
+    Args:
+        file (pathlib.Path): Absolute path to the file to extract the MIME type.
+
+    Returns
+        str: MIME type. `None` if teh MIME type cannot be identified.
+    """
+    instance = filetype.guess(str(file))
+
+    if instance:
+        return instance.mime
+
+    return None
+
+
+def get_mimetype_by_extension(file):
+    """Return the MIME type of a file based on its extension.
+
+    Args:
+        file (pathlib.Path): Absolute path to the file to extract the MIME type.
+
+    Returns
+        str: MIME type. `None` if the MIME type cannot be identified.
+    """
+    # TODO Use `guess_type_file` from Python 3.13
+    mimetype, _ = mimetypes.guess_type(file, strict=False)
+    return mimetype
+
+
 def group_by_type(files, path):
     """Group files by extension.
 
@@ -97,7 +157,7 @@ def group_by_type(files, path):
             audios.append(file)
             continue
 
-        if is_subtitle(file):
+        if maintype == "subtitle":
             subtitles.append(file)
             continue
 

src/dakara_feeder/media.py

@@ -0,0 +1,34 @@
+VIDEO_EXTENSIONS = (
+    ".mkv",
+    ".mp4",
+)
+"""Known video extensions."""
+
+AUDIO_EXTENSIONS = (
+    ".ogg",
+    ".mka",
+    ".m4a",
+)
+"""Known audio extensions."""
+
+
+def is_video(file):
+    """Detect known video extensions.
+
+    Args:
+        file (pathlib.Path): File.
+
+    Returns: True if the extension is known to be of a video file.
+    """
+    return file.suffix in VIDEO_EXTENSIONS
+
+
+def is_audio(file):
+    """Detect known video extensions.
+
+    Args:
+        file (pathlib.Path): File.
+
+    Returns: True if the extension is known to be of an audio file.
+    """
+    return file.suffix in AUDIO_EXTENSIONS

src/dakara_feeder/song.py

@@ -21,7 +21,8 @@ class BaseSong:
 
     - `get_title`;
     - `get_duration`;
-    - `get_has_instrumental`;
+    - `get_instrumental_file`;
+    - `get_instrumental_track`;
     - `get_version`;
     - `get_detail`;
     - `get_detail_video`;
@@ -151,20 +152,29 @@ def get_duration(self):
         """
         return self.metadata.get_duration().total_seconds()
 
-    def get_has_instrumental(self):
-        """Get the flag if the song has an instrumental track.
+    def get_instrumental_file(self):
+        """Get the path to the instrumental file, if any.
 
         Returns:
-            bool: `True` either if there is an extra audio file siding with the
-            video file, or if the video file has more than 2 audio tracks.
+            str: Name of the extra audio file siding with the video
+            file. `None` otherwise.
         """
         if self.audio_path:
-            return True
+            return self.audio_path.name
 
+        return None
+
+    def get_instrumental_track(self):
+        """Get index of the instrumental track, if any.
+
+        Returns:
+            int: Index of the second audio track (i.e. 1) if the video file has more
+            than 2 audio tracks. `None` otherwise.
+        """
         if self.metadata.get_audio_tracks_count() >= 2:
-            return True
+            return 1
 
-        return False
+        return None
 
     def get_artists(self):
         """Get the list of artists.
@@ -317,7 +327,8 @@ def get_representation(self):
             "filename": str(self.video_path.name),
             "directory": get_clean_directory(self.video_path.parent),
             "duration": self.get_duration(),
-            "has_instrumental": self.get_has_instrumental(),
+            "instrumental_file": self.get_instrumental_file(),
+            "instrumental_track": self.get_instrumental_track(),
             "version": self.get_version(),
             "detail": self.get_detail(),
             "detail_video": self.get_detail_video(),

tests/integration/test_feeder_songs.py

@@ -44,7 +44,8 @@ def test_feed(self, mocked_http_client_dakara_class):
                     "filename": "dummy.mkv",
                     "directory": "",
                     "duration": 2.023,
-                    "has_instrumental": True,
+                    "instrumental_file": None,
+                    "instrumental_track": 1,
                     "artists": [],
                     "works": [],
                     "tags": [],