:py:mod:`calliope.select` ========================= .. py:module:: calliope.select .. autoapi-nested-parse:: Select tracks for a playlist based on a set of constraints. This module was inspired by the 2008 paper `Music playlist generation by adapted simulated annealing `_ (S. Pauws, W. Verhaegh, M. Vossen). See :mod:`calliope.select.constraints` for details of the constraints. Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: calliope.select.Constraint calliope.select.ItemConstraint calliope.select.GlobalConstraint calliope.select.SetConstraint calliope.select.RangeConstraint calliope.select.EachGlobalConstraint calliope.select.FractionGlobalConstraint calliope.select.SumGlobalConstraint calliope.select.ItemDurationConstraint calliope.select.PlaylistDurationConstraint calliope.select.PlaylistDiskSpaceConstraint Functions ~~~~~~~~~ .. autoapisummary:: calliope.select.linear_score calliope.select.constraint_from_string calliope.select.select Attributes ~~~~~~~~~~ .. autoapisummary:: calliope.select.CONSTRAINTS_BY_NAME .. py:function:: linear_score(value, vmin, vmax) Objective function for `value` and target range [`vmin`, `vmax`] Returns 1.0 if vmin <= value <= vmax, decreasing linearly to 0.0 as value tends towards 0.0 and vmax*2. .. py:class:: Constraint Abstract base class. .. py:method:: __repr__() Return repr(self). .. py:class:: ItemConstraint(prop) Bases: :py:obj:`Constraint` Abstract base class. .. py:method:: __repr__() Return repr(self). .. py:method:: score_item(item) :abstractmethod: Score how well `item` satisfies this constraint. The score must be between 0.0 (doesn't satisfy constraint) and 1.0 (satisfies it perfectly). .. py:method:: partition(collection) :abstractmethod: Divide 'collection' into one 'good' and one or more 'bad' groups. This is used to define the neighbourhood we search for a solution. .. py:class:: GlobalConstraint Bases: :py:obj:`Constraint` Abstract base class for global (whole playlist) constraints. .. py:method:: score_playlist(playlist) :abstractmethod: Score how well `playlist` satisfies this constraint. The score must be between 0.0 (doesn't satisfy constraint) and 1.0 (satisfies it perfectly). .. py:class:: SetConstraint(prop, values) Bases: :py:obj:`ItemConstraint` Abstract base class. Simple set constraint, for properties with nominal (string) values. An item satisfies the constraint if its value matches one member of `values`. .. py:method:: __repr__() Return repr(self). .. py:method:: score_item(item) Score how well `item` satisfies this constraint. The score must be between 0.0 (doesn't satisfy constraint) and 1.0 (satisfies it perfectly). .. py:method:: partition(collection) Divide 'collection' into one 'good' and one or more 'bad' groups. This is used to define the neighbourhood we search for a solution. .. py:class:: RangeConstraint(prop, vmin, vmax) Bases: :py:obj:`ItemConstraint` Abstract base class. Simple range constraint, for properties with numeric values. An item scores 1.0 if `vmin` <= `prop` <= `vmax`. The score decreases linearly towards 0.0 as `prop` approaches 0 or 2*`vmax`. t's common to specify a single value by specifying `vmin` = `vmax`. .. py:method:: __repr__() Return repr(self). .. py:method:: score_item(item) Score how well `item` satisfies this constraint. The score must be between 0.0 (doesn't satisfy constraint) and 1.0 (satisfies it perfectly). .. py:method:: partition(collection) Divide 'collection' into one 'good' and one or more 'bad' groups. This is used to define the neighbourhood we search for a solution. .. py:class:: EachGlobalConstraint(item_constraint) Bases: :py:obj:`GlobalConstraint` Apply an item constraint to every item in the playlist. .. py:method:: __repr__() Return repr(self). .. py:method:: score_playlist(playlist) Score how well `playlist` satisfies this constraint. The score must be between 0.0 (doesn't satisfy constraint) and 1.0 (satisfies it perfectly). .. py:method:: partition(collection) .. py:class:: FractionGlobalConstraint(item_constraint, fmin, fmax) Bases: :py:obj:`GlobalConstraint` Apply an item set constraint to some items in the playlist. .. py:method:: __repr__() Return repr(self). .. py:method:: score_playlist(playlist) Score how well `playlist` satisfies this constraint. The score must be between 0.0 (doesn't satisfy constraint) and 1.0 (satisfies it perfectly). .. py:method:: partition(collection) .. py:class:: SumGlobalConstraint(prop, vmin, vmax) Bases: :py:obj:`GlobalConstraint`, :py:obj:`RangeConstraint` The sum of 'prop' for all songs should be between 'vmin' and 'vmax'. Simple range constraint, for properties with numeric values. An item scores 1.0 if `vmin` <= `prop` <= `vmax`. The score decreases linearly towards 0.0 as `prop` approaches 0 or 2*`vmax`. t's common to specify a single value by specifying `vmin` = `vmax`. .. py:method:: __repr__() Return repr(self). .. py:method:: score_playlist(playlist) Score how well `playlist` satisfies this constraint. The score must be between 0.0 (doesn't satisfy constraint) and 1.0 (satisfies it perfectly). .. py:method:: partition(collection) Divide 'collection' into one 'good' and one or more 'bad' groups. This is used to define the neighbourhood we search for a solution. .. py:class:: ItemDurationConstraint(vmin, vmax) Bases: :py:obj:`EachGlobalConstraint` Each song should have duration in range [min, max]. .. py:attribute:: PROP :value: 'duration' .. py:class:: PlaylistDurationConstraint(vmin, vmax) Bases: :py:obj:`SumGlobalConstraint` Playlist should be a specified number of seconds in duration. Simple range constraint, for properties with numeric values. An item scores 1.0 if `vmin` <= `prop` <= `vmax`. The score decreases linearly towards 0.0 as `prop` approaches 0 or 2*`vmax`. t's common to specify a single value by specifying `vmin` = `vmax`. .. py:attribute:: PROP :value: 'duration' .. py:class:: PlaylistDiskSpaceConstraint(vmin, vmax) Bases: :py:obj:`SumGlobalConstraint` Playlist items should total a specified number of bytes in size. Simple range constraint, for properties with numeric values. An item scores 1.0 if `vmin` <= `prop` <= `vmax`. The score decreases linearly towards 0.0 as `prop` approaches 0 or 2*`vmax`. t's common to specify a single value by specifying `vmin` = `vmax`. .. py:attribute:: PROP :value: 'album.size_mb' .. py:data:: CONSTRAINTS_BY_NAME .. py:exception:: SelectError Bases: :py:obj:`Exception` Exception returned from :mod:`calliope.select` module. Initialize self. See help(type(self)) for accurate signature. .. py:exception:: ConstraintStringParseError Bases: :py:obj:`SelectError` Error returned by :func:`constraint_from_string`. Initialize self. See help(type(self)) for accurate signature. .. py:function:: constraint_from_string(text) .. py:function:: select(playlist, constraints, viewer = None) Select music from input playlist according to a set of constraints. A simple constraint solving algorithm is used to produce a playlist. This involves some random choices, which may produce different results each time the function is called unless the same random seed is used. See also: :command:`cpe select`. :param playlist: input songs (order isn't important) :param constraints: one or more Constraint instances :returns: A playlist that satisfies the constraints.