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.

Attributes

CONSTRAINTS_BY_NAME

Exceptions

SelectError

Exception returned from calliope.select module.

ConstraintStringParseError

Error returned by constraint_from_string().

Classes

Constraint

Abstract base class.

ItemConstraint

Abstract base class.

GlobalConstraint

Abstract base class for global (whole playlist) constraints.

SetConstraint

Abstract base class.

RangeConstraint

Abstract base class.

EachGlobalConstraint

Apply an item constraint to every item in the playlist.

FractionGlobalConstraint

Apply an item set constraint to some items in the playlist.

SumGlobalConstraint

The sum of 'prop' for all songs should be between 'vmin' and 'vmax'.

ItemDurationConstraint

Each song should have duration in range [min, max].

PlaylistDurationConstraint

Playlist should be a specified number of seconds in duration.

PlaylistDiskSpaceConstraint

Playlist items should total a specified number of bytes in size.

Functions

linear_score(value, vmin, vmax)

Objective function for value and target range [vmin, vmax]

constraint_from_string(text)

select(playlist, constraints[, viewer])

Select music from input playlist according to a set of constraints.

Package Contents

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.Constraint

Abstract base class.

__repr__()
class calliope.select.ItemConstraint(prop)

Bases: Constraint

Abstract base class.

Parameters:

prop (str)

prop
__repr__()
abstractmethod 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

abstractmethod 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.

abstractmethod 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])

values
__repr__()
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)

vmin
vmax
__repr__()
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)

item_constraint
__repr__()
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
fmin
fmax
__repr__()
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__()
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:

constraints.Constraint

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:

calliope.playlist.Playlist