:py:mod:`examples.special_mix.special_mix`
==========================================

.. py:module:: examples.special_mix.special_mix

.. autoapi-nested-parse::

   Special mix
   ===========

   An example of generating personalised playlists based on a user's listening
   history.

   The idea of Special Mix is: create a 60 minute playlist, taking a specific
   year of listen-history as the starting point.

   Usage
   -----

   The example can be run from the ``calliope_examples`` package when installed:

   .. code:: bash

       python3 -m calliope_examples.special_mix ...

   You'll need to choose and configure a listen history provider.  Listen history
   can be fetched using any of the
   :func:`calliope.available_listen_history_providers` classes.
   An example of using :mod:`calliope.listenbrainz.listens` to fetch Listenbrainz history:

   .. code:: bash

       ... --history-provider=listenbrainz_history --history-provider-args="username=mylistenbrainzusername"

   You also need to choose and configure a content resolver.  Playable tracks can
   be resolved using any of the :func:`calliope.available_content_resolvers` classes.

   An example using :mod:`calliope.tracker` to resolve tracks to locally available music:

   .. code:: bash

       ... --resolver=tracker

   An example using :mod:`calliope.spotify` to resolve tracks to Spotify:

   .. code:: bash

       # Make sure `calliope.conf` exists and defines spotify API key, etc.
       ... --resolver=spotify --resolver-args=user=myspotifyusername

   .. rubric:: Notes

   Listen history needs to be synced, and the initial sync can take a long time
   if there is a lot of history.

   All candidate tracks are resolved before generating the playlist, as the
   ``select`` module needs to know the track durations in advance. This can make
   execution take a long time. Caching means that it should be faster once it has
   run a few times.

   If none of the tracks from listen history can be resolved, the output will
   be an empty playlist.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   examples.special_mix.special_mix.Config
   examples.special_mix.special_mix.PlaylistGenerator
   examples.special_mix.special_mix.DiscoveredInTimePeriod



Functions
~~~~~~~~~

.. autoapisummary::

   examples.special_mix.special_mix.one_year_after
   examples.special_mix.special_mix.main



Attributes
~~~~~~~~~~

.. autoapisummary::

   examples.special_mix.special_mix.DURATION


.. py:data:: DURATION

   

.. py:exception:: ConfigError


   Bases: :py:obj:`Exception`

   Common base class for all non-exit exceptions.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:class:: Config(sync=True, history_provider=None, history_provider_args=None, resolver=None, resolver_args=None)


   Bases: :py:obj:`calliope.config.Configuration`

   Config is stored in 'special_mix' section of calliope.conf

   .. py:method:: content_resolver()


   .. py:method:: history_provider()


   .. py:method:: sync()



.. py:class:: PlaylistGenerator(config)


   .. py:method:: setup_content_resolver()


   .. py:method:: setup_listen_history()



.. py:function:: one_year_after(d)


.. py:class:: DiscoveredInTimePeriod(config, span='year', period=None, minimum_tracks=100)


   Bases: :py:obj:`PlaylistGenerator`

   Tracks where first play was in specified time period.

   .. py:method:: setup()


   .. py:method:: run()



.. py:function:: main(output, debug, random_seed, history_provider, history_provider_args, resolver, resolver_args, sync)