calliope.select
¶
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 calliope.select.constraints
for details of the constraints.
Package Contents¶
Classes¶
Abstract base class. |
|
Abstract base class. |
|
Abstract base class for global (whole playlist) constraints. |
|
Abstract base class. |
|
Abstract base class. |
|
Apply an item constraint to every item in the playlist. |
|
Apply an item set constraint to some items in the playlist. |
|
The sum of 'prop' for all songs should be between 'vmin' and 'vmax'. |
|
Each song should have duration in range [min, max]. |
|
Playlist should be a specified number of seconds in duration. |
|
Playlist items should total a specified number of bytes in size. |
Functions¶
|
Objective function for value and target range [vmin, vmax] |
|
|
|
Select music from input playlist according to a set of constraints. |
Attributes¶
- calliope.select.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.
- class calliope.select.ItemConstraint(prop)¶
Bases:
Constraint
Abstract base class.
- Parameters:
prop (str) –
- __repr__()¶
Return repr(self).
- abstract 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).
- Parameters:
item (calliope.playlist.Item) –
- Return type:
float
- abstract 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.
- Return type:
[[calliope.playlist.Item]]
- class calliope.select.GlobalConstraint¶
Bases:
Constraint
Abstract base class for global (whole playlist) constraints.
- abstract 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).
- class calliope.select.SetConstraint(prop, values)¶
Bases:
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.
- Parameters:
prop (str) –
values ([str]) –
- __repr__()¶
Return repr(self).
- 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).
- Parameters:
item (calliope.playlist.Item) –
- Return type:
float
- 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.
- class calliope.select.RangeConstraint(prop, vmin, vmax)¶
Bases:
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.
- Parameters:
prop (str) –
vmin (float) –
vmax (float) –
- __repr__()¶
Return repr(self).
- 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).
- 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.
- class calliope.select.EachGlobalConstraint(item_constraint)¶
Bases:
GlobalConstraint
Apply an item constraint to every item in the playlist.
- Parameters:
item_constraint (ItemConstraint) –
- __repr__()¶
Return repr(self).
- 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).
- partition(collection)¶
- class calliope.select.FractionGlobalConstraint(item_constraint, fmin, fmax)¶
Bases:
GlobalConstraint
Apply an item set constraint to some items in the playlist.
- Parameters:
item_constraint (SetConstraint) –
fmin (float) –
fmax (float) –
- __repr__()¶
Return repr(self).
- 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).
- partition(collection)¶
- class calliope.select.SumGlobalConstraint(prop, vmin, vmax)¶
Bases:
GlobalConstraint
,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.
- __repr__()¶
Return repr(self).
- 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).
- 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.
- class calliope.select.ItemDurationConstraint(vmin, vmax)¶
Bases:
EachGlobalConstraint
Each song should have duration in range [min, max].
- PROP = 'duration'¶
- class calliope.select.PlaylistDurationConstraint(vmin, vmax)¶
Bases:
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.
- PROP = 'duration'¶
- class calliope.select.PlaylistDiskSpaceConstraint(vmin, vmax)¶
Bases:
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.
- PROP = 'album.size_mb'¶
- calliope.select.CONSTRAINTS_BY_NAME¶
- exception calliope.select.SelectError¶
Bases:
Exception
Exception returned from
calliope.select
module.Initialize self. See help(type(self)) for accurate signature.
- exception calliope.select.ConstraintStringParseError¶
Bases:
SelectError
Error returned by
constraint_from_string()
.Initialize self. See help(type(self)) for accurate signature.
- calliope.select.constraint_from_string(text)¶
- Parameters:
text (str) –
- Return type:
- calliope.select.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: cpe select.
- Parameters:
playlist (calliope.playlist.Playlist) – input songs (order isn’t important)
constraints ([select.constraints]) – one or more Constraint instances
viewer (simpleai.search.viewers.BaseViewer) –
- Returns:
A playlist that satisfies the constraints.
- Return type: