Metadata-Version: 2.1
Name: music-metadata-filter
Version: 2.0.0
Summary: A module for cleaning up artist, album, and song names.
Home-page: https://github.com/djmattyg007/music-metadata-filter
Author: Matthew Gamble
Author-email: git@matthewgamble.net
License: UNKNOWN
Description: # music-metadata-filter [![Test][workflowbadge]][workflow] [![PYPI][pypibadge]][PyPI]
        
        A module for cleaning up artist, album and song names.
        
        ## Installation
        
        The music-metadata-filter library can be found on [PyPI], and is installable with pip:
        
        ```sh
        pip install music-metadata-filter
        ```
        
        ## Usage
        
        ### Basic example
        
        ```python
        from music_metadata_filter.functions import remove_remastered
        
        print(remove_remastered("Track Title 1 - Remastered 2015"))
        # outputs "Track Title 1"
        print(remove_remastered("Track Title 2 (2011 Remaster)"))
        # outputs "Track Title 2"
        ```
        
        ### Single filter functions
        
        You can call filter functions for basic, one-line filter functionality.
        These filter functions are intended to be used on a single field, such as
        an artist, album or track.
        
        However, it is possible (not officially supported) to use some of these on
        combined fields ("Artist - Song", "Artist - Album"), as in the third example below.
        
        ```python
        import music_metadata_filter.functions as functions
        
        print(functions.remove_remastered("Jane Doe (Remastered)"))
        # outputs "Jane Doe"
        print(functions.remove_version("Get Lucky (Album Version)"))
        # outputs "Get Lucky"
        print(functions.youtube("Car Bomb - Scattered Sprites (Official Music Video)"))
        # outputs "Car Bomb - Scattered Sprites"
        ```
        
        See [functions.py](music_metadata_filter/functions.py) for more details.
        
        ### Combine filter functions
        
        You can also use multiple filter functions on a string at once by creating a
        `MetadataFilter` object which combines multiple functions from above,
        or by using one of the predefined [filter objects](#predefined-filters).
        
        First, create a filter set. This is a set of filter functions for different
        fields.
        
        ```python
        import music_metadata_filter.functions as functions
        from music_metadata_filter.filter import FilterSet
        
        filter_set: FilterSet = {
            "track": (
                functions.remove_remastered,
                functions.fix_track_suffix,
                functions.remove_live,
                functions.remove_version,
            ),
            "album": (
                functions.remove_remastered,
                functions.fix_track_suffix,
                functions.remove_live,
            ),
        }
        ```
        
        Then, construct a `MetadataFilter` using this filter set.
        
        ```python
        from music_metadata_filter.filter import MetadataFilter
        
        metadata_filter = MetadataFilter(filter_set)
        
        print(metadata_filter.filter_field("album", "Nevermind (Remastered)"))
        # outputs "Nevermind"
        print(metadata_filter.filter_field("track", "In Bloom - Nevermind Version"))
        # outputs "In Bloom (Nevermind Version)"
        print(metadata_filter.filter_field("track", "Won't Get Fooled Again - Album Version"))
        # outputs "Won't Get Fooled Again"
        ```
        
        ### Predefined filters
        
        There are also predefined filters available for easy access. For example,
        the above filter set is actually the predefined Spotify filter:
        
        ```python
        from music_metadata_filter.filters import make_spotify_filter
        
        metadata_filter = make_spotify_filter()
        ```
        
        See [filters.py](music_metadata_filter/filters.py) for more details.
        
        ### Extending filters
        
        Finally, you can take existing `MetadataFilter` objects and extend them with another filter.
        This is done by providing the `.extend()` method with another `MetadataFilter` object.
        
        ```python
        from music_metadata_filter.filters import make_spotify_filter, make_amazon_filter
        
        metadata_filter = make_spotify_filter()
        metadata_filter.extend(make_amazon_filter())
        
        print(metadata_filter.filter_field("track", "Seasons in the Abyss (Album Version)"))
        # outputs "Seasons in the Abyss"
        ```
        
        As an alternative, you can use the `.append()` method to apply a filter set to
        an existing `MetadataFilter` object.
        
        ```python
        metadata_filter = make_spotify_filter()
        metadata_filter.append({"album": lambda x: f"{x} Album"})
        ```
        
        Since these methods return a `MetadataFilter` instance, you can chain method calls.
        
        ```python
        metadata_filter = make_spotify_filter().append({
            "artist": lambda x: f"{x} The Artist",
        })
        ```
        
        ### Opinionated filters
        
        As discussed below, this library aims to be a direct port from another language. However, as is to
        be expected, I don't agree 100% with every choice made by the upstream maintainers. In order to
        make updates easier and ensure compatibility with upstream, my opinions are therefore separated out
        into a dedicated set of modules labelled with "opinionated".
        
        Right now, there isn't much that differs. The primary differences are that "Live" should not be
        stripped from Spotify metadata, and that "Live" suffixes should be normalised by the "fix suffix"
        ruleset (like "Instrumental" and "Remix").
        
        ```python
        from music_metadata_filter.opinionated_filters import make_spotify_filter
        
        metadata_filter = make_spotify_filter()
        
        print(metadata_filter.filter_field("track", "Track Title - Live / Remastered"))
        # outputs "Track Title (Live)"
        ```
        
        ## Development
        
        This project uses [invoke] as a task runner.
        
        ```sh
        # Initialise a virtualenv
        > python3 -m venv venv --prompt music-metadata-filter
        > source bin/activate
        
        # Install dev dependencies
        > pip install -r requirements-dev.txt
        
        # Run tests
        > inv test
        
        # Run black formatter
        > inv reformat
        
        # Run flake8 linter and black linter
        > inv lint
        
        # Run mypy type checker
        > inv type-check
        
        # Regenerate regular expressions and test fixtures from upstream
        > ./regen.sh
        ```
        
        ## License
        
        Licensed under the [MIT License](LICENSE.md).
        
        ## Acknowledgements
        
        This library is a (mostly) direct port of the original JS library
        [metadata-filter](https://github.com/web-scrobbler/metadata-filter).
        Some of the code in this library, including regular expressions and test fixtures,
        are taken directly from the upstream repository.
        
        I can't thank the web-scrobbler team enough for creating such a fantastic
        piece of software, and for collaborating with me in the creation of this
        port to Python.
        
        <!-- Badges -->
        
        [pypibadge]: https://img.shields.io/pypi/v/music-metadata-filter
        [workflowbadge]: https://img.shields.io/github/workflow/status/djmattyg007/music-metadata-filter/Test?label=test
        
        <!-- Related pages -->
        
        [PyPI]: https://pypi.org/project/music-metadata-filter
        [workflow]: https://github.com/djmattyg007/music-metadata-filter/actions?query=workflow%3ATest
        [invoke]: https://github.com/pyinvoke/invoke
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=3.7
Description-Content-Type: text/markdown
