Metadata-Version: 1.1
Name: beets-beatport4
Version: 0.3.0
Summary: Plugin for beets (http://beets.io) to replace stock beatport plugin which is not yet compatible with Beatport API v4.
Home-page: https://github.com/Samik081/beets-beatport4
Author: Szymon "Samik" Tarasinski
Author-email: st.samik@gmail.com
License: MIT
Download-URL: https://github.com/Samik081/beets-beatport4/releases/download/v0.3.0/beets-beatport4-0.3.0.tar.gz
Description: **beets Beatport API v4 compatible plugin**
        ==================================================
        
        .. image:: http://img.shields.io/pypi/v/beets-beatport4.svg
            :target: https://pypi.python.org/pypi/beets-beatport4
        
        Plugin for `beets <https://github.com/beetbox/beets>`_ to replace stock beatport plugin and use Beatport API v4 as an
        autotagger source.
        
        As Beatport had killed their API v3, the stock beatport plugin does not work anymore. It is also currently not possible to request the access to the API "normal" way (by using your client credentials or API token generated by Beatport), so I have found workaround that uses public API client id used for `Beatport docs frontend <https://api.beatport.com/v4/docs/>`_ and updated the code to use the new specification.
        
        For more info, see the discussion on this issue: https://github.com/beetbox/beets/issues/3862
        
        I have also opened a pull request in the official beets repository (https://github.com/beetbox/beets/pull/4477), so if it gets merged, I am probably going to take down this plugin.
        
        Installation
        ------------
        
        Install this plugin with
        
        ..
        
           $ pip install beets-beatport4
        
        and add ``beatport4`` to the ``plugins`` list in your beets config file.
        
        Beatport Authorization
        ----------------------
        There are two ways of acquiring user access token to the Beatport v4 API using
        this plugin.
        
        Method 1: username and password
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        This method is fully automatic and relies on holding your Beatport username
        and password inside your beets config file.
        It will authorize to the Beatport API using ``authorization_code`` grant type
        and ``client_id`` provided by beatport for the sake of their ``swagger-ui``
        frontend in which you can test their API: https://api.beatport.com/v4/docs/
        By default, ``client_id`` is scrapped automatically from the above URL.
        Alternatively, you can also pass it via plugin configuration.
        
        Steps:
        
        1. Add ``beatport4`` plugin to your ``beets/config.yaml`` plugins list
        2. Add below configuration and fill your credentials
        
        .. code-block:: yaml
        
            beatport4:
                art: yes
                art_overwrite: no
                username: <YOUR_BEATPORT_USERNAME>
                password: <YOUR_BEATPORT_PASSWORD>
        
        
        Method 2. copy token from the browser
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        You will probably want to use this method if you don't want to store your
        credentials unencrypted within the config file. Also, it will be helpful if
        for any reason something goes wrong during the username/password authorization
        process.
        
        This is also a fallback method if you provide wrong credentials in the config.
        
        Steps:
        
        1. Add ``beatport4`` plugin to your ``beets/config.yaml`` plugins list
        2. When the first import with plugin enabled happens, you will be prompted to paste the access token JSON
        3. Visit https://api.beatport.com/v4/docs/
        4. Open Network tab in your browser and start capturing the traffic
        5. Login with your Beatport account
        6. Search for the following request: ``https://api.beatport.com/v4/auth/o/token/``
        7. Copy the response (whole JSON structure)
        8. Paste it to the terminal (or `beatport_token.json` file next to your ``beets/config.yaml`` - you can check the path by running ``beet config --paths`` command)
        9. If the token expires, you will be prompted again and required to repeat above steps
        
        Fetching and embedding an art
        -----------------------------
        Additionally, this plugin has implemented separate art fetching and embedding.
        Unlike `fetchart plugin <https://beets.readthedocs.io/en/stable/plugins/fetchart.html>`_, it handles both singletons and albums,
        but it will not work if you choose candidate source other than Beatport.
        Also, it does not require enabling
        `fetchart <https://beets.readthedocs.io/en/stable/plugins/fetchart.html>`_ or
        `embedart <https://beets.readthedocs.io/en/stable/plugins/embedart.html>`_
        plugins, as it uses
        `beets.art module <https://github.com/beetbox/beets/blob/master/beets/art.py>`_
        shipped with the core library.
        
        Under the hood, it uses image URL for the track's release,
        exposed by the Beatport API.
        
        You can disable this feature via configuration (**it is enabled by default**):
        
        .. code-block:: yaml
        
            beatport4:
                art: yes
        
        By default, if a track already contains an art, it will not be overwritten.
        Again, you can force such behaviour via configuration:
        
        .. code-block:: yaml
        
            beatport4:
                art: yes
                art_overwrite: yes
        
        Plugin configuration
        --------------------
        .. code-block:: yaml
        
            beatport4:
                art: yes
                art_overwrite: no
                username: <YOUR_BEATPORT_USERNAME>
                password: <YOUR_BEATPORT_PASSWORD>
                client_id: <BEATPORT_API_CLIENT_ID> # optional, you can set it, but it should be scrapped automatically from the docs
        
        Apart from the above, plugin should work exactly the same way as the stock one, so please refer to the `official documentation <https://beets.readthedocs.io/en/v1.6.0/plugins/beatport.html>`_
Platform: ALL
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Players :: MP3
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
